API Reference

This section provides the complete API reference for the github.com/cybergodev/json library.

Two API styles

The library offers two API surfaces: package-level functions (e.g. json.GetString(data, "path"), no instance required) and Processor methods (e.g. p.GetString(data, "path"), with configuration reuse, pre-parse caching, and the hook system). Not sure which to use? See the decision tree in the Processor Guide.

Module Index

Function APIs

Module	Description
Package Functions	Package-level function reference (query/modify/delete/encode/parse/batch/JSONL/file/iteration)
Processor	Processor methods (mirrors the package functions, plus lifecycle and pre-parsing)

Types and Interfaces

Module	Description
Config	Configuration options in detail (DefaultConfig / SecurityConfig / PrettyConfig)
Type Definitions	Core types (Config / Schema / Stats / AccessResult, plus Encoder / Decoder, CompiledPath / PathSegment)
Interface Definitions	Extension interfaces (CustomEncoder / Validator / Hook / PathParser)
Iterators and IterableValue	Iterator / BatchIterator / ParallelIterator / StreamIterator types
Generic Operations	Generic APIs (GetTyped[T] / StreamLinesInto[T] / Result[T])
Constants and Errors	Constants and error types (including Default* constants and a Config field mapping table)

Utilities and Helpers

Module	Description
Helper Functions	CompareJSON / MergeJSON, cache management, the global processor, SafeError / RedactedPath, AccessResult methods
Formatted Output	Pretty vs compact output, incl. Print-family migration notes

Cross-Module Topics

Module	Description
Streaming	Large-file guide (full-load vs streaming iteration)
JSONL / NDJSON Streaming	Streaming reads and writes with the StreamJSONL family and JSONLWriter
Security Validation	Security-mode API (SecurityConfig / DangerousPattern / RegisterDangerousPattern)
Schema Validation	Schema validation (ValidateSchema / DefaultSchema / NewSchema)
Hook System	Operation interception hooks (LoggingHook / TimingHook / ValidationHook / ErrorHook)
Custom Encoders	Custom encoders (CustomEncoder / TypeEncoder)

Quick Lookup

By Feature

Path Queries

Function	Description
Get, GetWithContext, GetString, GetInt, GetFloat, GetBool, GetArray, GetObject	Type-safe gets
GetTyped[T]	Generic get
SafeGet	Safe get returning an AccessResult
GetMultiple	Batch get

Modification Operations

Function	Description
Set, SetMultiple	Set values
SetCreate, SetMultipleCreate	Set values with automatic path creation
Delete, DeleteClean	Delete values
ProcessBatch	Batch operations

Encoding and Decoding

Function	Description
Marshal, Unmarshal	Standard encode/decode (encoding/json compatible, optional cfg)
MarshalIndent	Indented encoding (encoding/json.MarshalIndent compatible, optional cfg)
Encode, EncodePretty	Encode to string (with config / pretty output)
EncodeWithConfig (deprecated)	Functionally equivalent to Encode, retained within v1 — use Encode or Marshal in new code
NewEncoder, NewDecoder	Streaming encode/decode
Parse, ParseAny	Parse into a target variable / parse as any
EncodeBatch, EncodeFields, EncodeStream	Encode key-value pairs into an object / encode selected fields / encode multiple values into an array

Formatting

Function	Description
Prettify	Pretty-print JSON
Compact	Compact JSON (buffer form, encoding/json.Compact compatible)
CompactString	Compact JSON (string in/out form, mirrors Processor.Compact)
Indent	Indent and write to a buffer (encoding/json.Indent compatible)
HTMLEscape	Escape HTML characters into a buffer (encoding/json.HTMLEscape compatible)

File Operations

Function	Description
LoadFromFile, SaveToFile	Read and write files
LoadFromReader	Read from a Reader
MarshalToFile, UnmarshalFromFile	File encode/decode
SaveToWriter	Write to any Writer

Iteration and Traversal

Function	Description
Foreach, ForeachWithError, ForeachNested, ForeachNestedWithError	Iterate arrays/objects (incl. deep traversal)
ForeachWithPath, ForeachWithPathAndIterator, ForeachWithPathAndControl	Iterate at a given path (carrying the current path / with break control)
ForeachReturn	Iterate and return the modified JSON
ForeachFile, ForeachFileWithPath, ForeachFileChunked, ForeachFileNested	Item-by-item file iteration (fully loaded, then item-by-item/batched callbacks)
NewIterator, NewBatchIterator, NewParallelIterator, NewStreamIterator	Standalone iterator constructors (see Iterators)

Cache and Globals

Function	Description
WarmupCache, ClearCache	Cache warm-up / clearing
GetStats, GetHealthStatus	Runtime statistics / health check
GetConfig, SetLogger	Read processor config / inject a logger (both global and Processor methods)
SetGlobalProcessor, ShutdownGlobalProcessor	Replace and shut down the global processor
RegisterDangerousPattern, UnregisterDangerousPattern, ListDangerousPatterns	Global dangerous-pattern registry register / remove / list (see Helper Functions)
CompilePath (Processor), PreParse (Processor)	Path pre-compilation / JSON pre-parsing

Streaming

Type/Method	Description
StreamLinesInto[T]	Stream JSONL from a Reader and convert to []T
ParseJSONL	Parse JSONL bytes into []any
ToJSONL, ToJSONLString	Convert []any to JSONL format
JSONLWriter	JSONL writer (Write/WriteAll/WriteRaw)
NDJSONProcessor (deprecated)	NDJSON/JSONL processor (created by NewNDJSONProcessor; use the StreamJSONL family in new code)
ForeachFile	Item-by-item file iteration (whole file loaded)

Validation

Function	Description
Valid	JSON validation (encoding/json.Valid compatible)
ValidWithConfig	JSON validation with config
ValidateSchema	Schema validation (used with the Schema type)
CompareJSON	Compare JSON for equivalence
MergeJSON, MergeMany	JSON merging (union/intersection/difference modes, see Helper Functions)

Naming Conventions

The library follows these naming conventions:

Pattern	Description	Example
Get{Type}	Get as the given type (defaultValue supported)	GetString, GetInt
GetTyped[T]	Generic get, returns T	GetTyped[User]
New{Type}	Create an instance	New (returns *Processor), NewEncoder
Default{Type}	Default configuration	DefaultConfig
{Type}Config	Configuration preset	SecurityConfig, PrettyConfig
Foreach*	Iteration variants (WithError / WithPath / Nested / File)	ForeachNestedWithError
Stream*	Streaming variants (Into / Parallel / File / Chunked)	StreamJSONLParallel
{Verb}Hook	Hook factories	LoggingHook, ValidationHook

See Also

• Quick Start -- installation and basic usage
• Processor Guide -- when to use a processor
• Path Expression Syntax -- path query syntax
• Examples -- real-world code examples
• Large File Handling -- streaming guide