json package - github.com/cybergodev/json

json package - github.com/cybergodev/json - Go Packages

Package json provides a high-performance, thread-safe JSON processing library with 100% encoding/json compatibility and advanced path operations.

The package uses an internal package for implementation details:

internal: Private implementation including path parsing, navigation, extraction, caching, array utilities, security helpers, and encoding utilities

Most users can simply import the root package:

import "github.com/cybergodev/json"

Basic Usage ¶

Simple operations (100% compatible with encoding/json):

data, err := json.Marshal(value)
err = json.Unmarshal(data, &target)

Advanced path operations:

value, err := json.Get(`{"user":{"name":"John"}}`, "user.name")
result, err := json.Set(`{"user":{}}`, "user.age", 30)

Type-safe operations:

name, err := json.GetString(jsonStr, "user.name")
age, err := json.GetAsInt(jsonStr, "user.age")

Advanced processor for complex operations:

processor, err := json.New() // Use default config
if err != nil {
    // handle error
}
defer processor.Close()
value, err := processor.Get(jsonStr, "complex.path[0].field")

Configuration ¶

Use DefaultConfig and optional parameters for custom configuration:

cfg := json.DefaultConfig()
cfg.EnableCache = true
processor, err := json.New(cfg)
if err != nil {
    // handle error
}
defer processor.Close()

defer processor.Close()

Key Features ¶

100% encoding/json compatibility - drop-in replacement
High-performance path operations with smart caching
Thread-safe concurrent operations
Type-safe generic operations with Go 1.22+ features
Memory-efficient resource pooling
Production-ready error handling and validation

Package Structure ¶

The package is organized with all public API in the root package:

Core types: Processor, Config, ProcessorOptions, EncodeConfig
Error types: JsonsError, various error constructors
Encoding types: Number

Implementation details are in the internal/ package:

Path parsing and navigation utilities
Extraction and segment handling
Cache and array utilities
Security and encoding helpers

Core Types Organization ¶

Core types are organized in the following files:

types.go: All type definitions (Config, ProcessorOptions, Stats, etc.)
processor.go: Processor struct and all methods
ops.go: Internal operation implementations
path.go: Path parsing and navigation
encoding.go: JSON encoding/decoding
api.go: Package-level API functions
file.go: File operations
iterator.go: Iteration utilities
recursive.go: Recursive processing

Package json provides extension interfaces for customizing JSON processing behavior. These interfaces enable users to inject custom validation, encoding, and middleware logic.

Package json provides a high-performance, thread-safe JSON processing library with 100% encoding/json compatibility and advanced path operations.

Key Features:

100% encoding/json compatibility - drop-in replacement
High-performance path operations with smart caching
Thread-safe concurrent operations
Type-safe generic operations with Go 1.18+ generics
Memory-efficient resource pooling
Production-ready error handling and validation

Basic Usage:

// Simple operations (100% compatible with encoding/json)
data, err := json.Marshal(value)
err = json.Unmarshal(data, &target)

// Advanced path operations
value, err := json.Get(`{"user":{"name":"John"}}`, "user.name")
result, err := json.Set(`{"user":{}}`, "user.age", 30)

// Type-safe operations
name, err := json.GetString(jsonStr, "user.name")
age, err := json.GetAsInt(jsonStr, "user.age")

// Advanced processor for complex operations
processor := json.New() // Use default config
defer processor.Close()
value, err := processor.Get(jsonStr, "complex.path[0].field")

Configuration constants with optimized defaults for production workloads.

Merge mode constants - re-exported from internal package for public API

InvalidArrayIndex is a sentinel value indicating an invalid or out-of-bounds array index. Returned by array parsing functions when the index cannot be determined (e.g., invalid format, overflow, or empty string).

index := processor.ParseArrayIndex(str)
if index == InvalidArrayIndex {
    // Handle invalid index
}

View Source

var (
	ErrInvalidJSON     = errors.New("invalid JSON format")
	ErrPathNotFound    = errors.New("path not found")
	ErrTypeMismatch    = errors.New("type mismatch")
	ErrOperationFailed = errors.New("operation failed")
	ErrInvalidPath     = errors.New("invalid path format")
	ErrProcessorClosed = errors.New("processor is closed")
	ErrInternalError   = errors.New("internal error")

	
	ErrSizeLimit        = errors.New("size limit exceeded")
	ErrDepthLimit       = errors.New("depth limit exceeded")
	ErrConcurrencyLimit = errors.New("concurrency limit exceeded")

	
	ErrSecurityViolation = errors.New("security violation detected")
	ErrUnsupportedPath   = errors.New("unsupported path operation")

	
	ErrCacheFull         = errors.New("cache is full")
	ErrCacheDisabled     = errors.New("cache is disabled")
	ErrOperationTimeout  = errors.New("operation timeout")
	ErrResourceExhausted = errors.New("system resources exhausted")
)

Primary errors for common cases.

As safely converts the result to type T. Returns error if the type doesn't match.

func ClampIndex(index, length int) int

ClampIndex clamps an index to valid bounds for an array

ClearCache clears the processor's internal cache.

func ClearDangerousPatterns()

ClearDangerousPatterns removes all custom patterns from the global registry. Use with caution - this does not affect built-in patterns.

func ClearKeyInternCache()

ClearKeyInternCache clears the global key interning cache.

Compact appends to dst the JSON-encoded src with insignificant space characters elided. This function is 100% compatible with encoding/json.Compact.

CompactBuffer is an alias for Compact for buffer operations

CompactString removes whitespace from JSON string. This is the recommended function for compacting JSON strings.

CompareJSON compares two JSON strings for equality by parsing and normalizing them. This function handles numeric precision differences and key ordering.

Example:

equal, err := json.CompareJSON(`{"a":1}`, `{"a":1.0}`)
// equal == true

ConvertToBool converts any value to bool. String conversion supports both standard formats and user-friendly formats: Standard: "1", "t", "T", "TRUE", "true", "True", "0", "f", "F", "FALSE", "false", "False" Extended: "yes", "on" -> true, "no", "off", "" -> false Delegates to internal core function to reduce code duplication

ConvertToFloat64 converts any value to float64. Delegates to internal core functions to reduce code duplication. MAINTENANCE: Keep type switch cases in sync with ConvertToInt, ConvertToInt64, ConvertToUint64.

ConvertToInt converts any value to int with comprehensive type support. Delegates to internal core function to reduce code duplication. MAINTENANCE: Keep type switch cases in sync with ConvertToInt64, ConvertToUint64, ConvertToFloat64.

ConvertToInt64 converts any value to int64. Delegates to internal core function to reduce code duplication. MAINTENANCE: Keep type switch cases in sync with ConvertToInt, ConvertToUint64, ConvertToFloat64.

ConvertToString converts any value to string (for backward compatibility)

ConvertToUint64 converts any value to uint64. Delegates to internal core function to reduce code duplication. MAINTENANCE: Keep type switch cases in sync with ConvertToInt, ConvertToInt64, ConvertToFloat64.

func CreateEmptyContainer(containerType string) any

CreateEmptyContainer creates an empty container of the specified type

DeepCopy creates a deep copy of JSON-compatible data Uses direct recursive copying for better performance (avoids marshal/unmarshal overhead) SECURITY: Added depth limit to prevent stack overflow

Delete deletes a value from JSON at the specified path

Encode converts any Go value to JSON string. For configuration options, use EncodeWithConfig.

EncodeBatch encodes multiple key-value pairs as a JSON object. This is the unified API that replaces EncodeBatchWithOpts.

Example:

result, err := json.EncodeBatch(map[string]any{"name": "Alice", "age": 30})

EncodeFields encodes specific fields from a struct or map. This is the unified API that replaces EncodeFieldsWithOpts.

Example:

result, err := json.EncodeFields(user, []string{"name", "email"})

EncodeStream encodes multiple values as a JSON array. This is the unified API that replaces EncodeStreamWithOpts.

Example:

result, err := json.EncodeStream([]any{1, 2, 3}, json.PrettyConfig())

EncodeWithConfig converts any Go value to JSON string using the unified Config. This is the recommended way to encode JSON with configuration.

Example:

// Default configuration
result, err := json.EncodeWithConfig(data)

// Pretty output
result, err := json.EncodeWithConfig(data, json.PrettyConfig())

// Security-focused output
result, err := json.EncodeWithConfig(data, json.SecurityConfig())

// Custom configuration
cfg := json.DefaultConfig()
cfg.Pretty = true
cfg.SortKeys = true
result, err := json.EncodeWithConfig(data, cfg)

EscapeJSONPointer escapes special characters for JSON Pointer

func Foreach(jsonStr string, fn func(key any, item *IterableValue))

Foreach iterates over JSON arrays or objects with simplified signature (for test compatibility)

func ForeachNested(jsonStr string, fn func(key any, item *IterableValue))

ForeachNested iterates over nested JSON structures

ForeachReturn is a variant that returns error (for compatibility with test expectations)

ForeachWithPath iterates over JSON arrays or objects with simplified signature (for test compatibility)

func ForeachWithPathAndControl ¶ added in v1.0.8

ForeachWithPathAndControl iterates over JSON arrays or objects and applies a function This is the 3-parameter version used by most code

FormatNumber formats a number value as a string

Get retrieves a value from JSON at the specified path. Returns the value as any and requires type assertion.

GetArray retrieves an array value from JSON at the specified path.

GetBool retrieves a bool value from JSON at the specified path.

GetBoolOr retrieves a bool value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

func GetContainerSize(data any) int

GetContainerSize returns the size of a container

GetErrorSuggestion provides suggestions for common errors

GetFloat retrieves a float64 value from JSON at the specified path.

GetFloatOr retrieves a float64 value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

GetInt retrieves an int value from JSON at the specified path.

func GetIntOr(jsonStr, path string, defaultValue int, cfg ...Config) int

GetIntOr retrieves an int value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

func GetKeyInternCacheSize() int

GetKeyInternCacheSize returns the number of interned keys in the cache.

GetMultiple retrieves multiple values from JSON at the specified paths

GetObject retrieves an object value from JSON at the specified path.

func GetResultBuffer() *[]byte

GetResultBuffer gets a buffer for result marshaling

GetString retrieves a string value from JSON at the specified path.

GetStringOr retrieves a string value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

GetTyped retrieves a typed value from JSON at the specified path. This is the generic typed getter - use this for custom types.

Example:

type User struct { Name string }
user, err := json.GetAs[User](data, "user")

func GetTypedOr[T any](jsonStr, path string, defaultValue T, cfg ...Config) T

GetTypedOr retrieves a typed value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails. This is the recommended generic function for getting values with defaults.

Example:

name := json.GetOr[string](data, "user.name", "unknown")
age := json.GetOr[int](data, "user.age", 0)

HTMLEscape appends to dst the JSON-encoded src with <, >, &, U+2028, and U+2029 characters escaped. This function is 100% compatible with encoding/json.HTMLEscape.

HTMLEscapeBuffer is an alias for HTMLEscape for buffer operations

Indent appends to dst an indented form of the JSON-encoded src. This function is 100% compatible with encoding/json.Indent.

IndentBuffer appends to dst an indented form of the JSON-encoded src.

InternKey interns a string key for memory efficiency. Returns an interned version of the key that can be reused across operations.

Example:

key := json.InternKey("user_id") // Returns interned string

IsContainer checks if the data is a container type (map or slice)

IsDeletedMarker checks if a value is the deleted marker sentinel. This is the recommended way to check for deleted markers instead of direct comparison.

IsEmptyOrZero checks if a value is empty or its zero value. Supports all standard numeric types, bool, string, slices, maps, and json.Number. For slices and maps, returns true if nil or empty (len == 0).

Example:

if json.IsEmptyOrZero(value) {
    // Handle empty or zero value
}

IsInteger checks if a string represents an integer value

IsNumeric checks if a string represents a numeric value

IsRetryable determines if an error is retryable

IsSecurityRelated determines if an error is security-related

IsUserError determines if an error is caused by user input

IsValidJSON quickly checks if a string is valid JSON

IsValidPath checks if a path expression is valid

LoadFromFile loads JSON data from a file with optional configuration Uses the default processor with support for Config such as security validation

Marshal returns the JSON encoding of v. This function is 100% compatible with encoding/json.Marshal. For configuration options, use EncodeWithConfig or Processor.Marshal with cfg parameter.

MarshalIndent is like Marshal but applies indentation to format the output. This function is 100% compatible with encoding/json.MarshalIndent. For configuration options, use EncodeWithConfig or Processor.MarshalIndent with cfg parameter.

MarshalToFile marshals data to JSON and writes to a file. This is the unified API that replaces MarshalToFileWithOpts.

Example:

err := json.MarshalToFile("data.json", myStruct, json.PrettyConfig())

MergeJSON merges two JSON objects using deep merge strategy. For nested objects, it recursively merges keys according to the specified mode. For primitive values and arrays, the value from json2 takes precedence.

Supported modes (optional, defaults to MergeUnion):

MergeUnion: combines all keys from both objects (default)
MergeIntersection: only keys present in both objects
MergeDifference: keys in json1 but not in json2

Example:

// Union merge (default)
result, err := json.MergeJSON(a, b)

// Intersection merge
result, err := json.MergeJSON(a, b, json.MergeIntersection)

// Difference merge
result, err := json.MergeJSON(a, b, json.MergeDifference)

MergeJSONMany merges multiple JSON objects with specified merge mode. Returns error if less than 2 JSON strings are provided.

Example:

result, err := json.MergeJSONMany(json.MergeUnion, config1, config2, config3)

func NewProcessorUtils() *processorUtils

NewProcessorUtils creates a new processor utils instance

Parse parses a JSON string and returns the root value. This is the recommended entry point for parsing JSON strings.

Layer Architecture:

Package-level (this function): Convenience wrapper that uses cached processors
Processor-level: Use Processor.ParseAny() for the same behavior, or Processor.Parse() for unmarshaling into a target

Example:

// Simple parsing (uses default processor)
data, err := json.Parse(jsonStr)

// With configuration (uses config-cached processor)
cfg := json.SecurityConfig()
data, err := json.Parse(jsonStr, cfg)

Performance Tips:

For repeated operations on the same JSON, use Processor.PreParse() to parse once
For batch operations, use Processor.ProcessBatch()

Note: Get(jsonStr, "$") is equivalent but slightly less efficient due to path parsing overhead.

ParseBool parses a string to boolean with error handling

ParseFloat parses a string to float64 with error handling

ParseInt parses a string to integer with error handling

ParseJSONL parses JSONL data from a byte slice

ParseJSONLInto parses JSONL data into typed values

Prettify formats JSON string with pretty indentation. This is the recommended function for formatting JSON strings.

Example:

pretty, err := json.Prettify(`{"name":"Alice","age":30}`)
// Output:
// {
//   "name": "Alice",
//   "age": 30
// }

Print prints any Go value as JSON to stdout in compact format. Note: Writes errors to stderr. Use PrintE for error handling.

PrintE prints any Go value as JSON to stdout in compact format. Returns an error instead of writing to stderr, allowing callers to handle errors.

func PrintPretty(data any)

PrintPretty prints any Go value as formatted JSON to stdout. Note: Writes errors to stderr. Use PrintPrettyE for error handling.

PrintPrettyE prints any Go value as formatted JSON to stdout. Returns an error instead of writing to stderr, allowing callers to handle errors.

func PutResultBuffer(buf *[]byte)

PutResultBuffer returns a buffer to the pool

func RegisterDangerousPattern(pattern DangerousPattern)

RegisterDangerousPattern adds a pattern to the global registry. Patterns registered here are checked in addition to default patterns.

Example:

json.RegisterDangerousPattern(json.DangerousPattern{
    Pattern: "malicious_keyword",
    Name:    "Custom dangerous pattern",
    Level:   json.PatternLevelCritical,
})

SafeConvertToInt64 safely converts any value to int64 with error handling

SafeConvertToUint64 safely converts any value to uint64 with error handling

SanitizeKey sanitizes a key for safe use in maps

SaveToFile saves JSON data to a file with optional configuration. This is the unified API that replaces SaveToFileWithOpts.

Example:

// Simple save
err := json.SaveToFile("data.json", data)

// With pretty printing
cfg := json.PrettyConfig()
err := json.SaveToFile("data.json", data, cfg)

SaveToWriter writes JSON data to an io.Writer. This is the unified API that replaces SaveToWriterWithOpts.

Example:

var buf bytes.Buffer
err := json.SaveToWriter(&buf, data, json.PrettyConfig())

Set sets a value in JSON at the specified path Returns:

On success: modified JSON string and nil error
On failure: original unmodified JSON string and error information

func SetGlobalProcessor(processor *Processor)

SetGlobalProcessor sets a custom global processor (thread-safe)

SetMultiple sets multiple values using a map of path-value pairs

func ShutdownGlobalProcessor()

ShutdownGlobalProcessor shuts down the global processor

StreamArrayCount counts elements without storing them Memory-efficient for just getting array length

StreamArrayFilter filters array elements during streaming Only elements that pass the predicate are kept

StreamArrayFirst returns the first element that matches a predicate Stops processing as soon as a match is found

StreamArrayForEach processes each element without collecting results Useful for side effects like writing to a database or file

StreamArrayMap transforms array elements during streaming Each element is transformed using the provided function

StreamArrayReduce reduces array elements to a single value during streaming The reducer function receives the accumulated value and current element

StreamArraySkip skips the first n elements and returns the rest Useful for pagination

StreamArrayTake returns the first n elements from a streaming array Useful for pagination or sampling

StreamLinesInto processes JSONL data into a slice of typed values Uses generics for type-safe processing

StreamLinesIntoWithConfig processes JSONL data into a slice of typed values with config

ToJSONL converts a slice of values to JSONL format

ToJSONLString converts a slice of values to JSONL format string

UnescapeJSONPointer unescapes JSON Pointer special characters

Unmarshal parses the JSON-encoded data and stores the result in v. This function is 100% compatible with encoding/json.Unmarshal. For configuration options, use Processor.Unmarshal with cfg parameter.

UnmarshalFromFile reads JSON from a file and unmarshals it into v. This is a convenience function that combines file reading and unmarshalling. Uses the default processor for security validation and decoding.

Parameters:

path: file path to read JSON from
v: pointer to the target variable where JSON will be unmarshaled
cfg: optional Config for security validation and processing

Returns error if file reading fails or JSON cannot be unmarshaled.

func UnregisterDangerousPattern(pattern string)

UnregisterDangerousPattern removes a pattern from the global registry.

Valid reports whether data is valid JSON. This function is 100% compatible with encoding/json.Valid.

ValidString reports whether the JSON string is valid. This is a convenience wrapper for Valid that accepts a string directly.

ValidWithOptions reports whether the JSON string is valid with optional configuration. Returns both the validation result and any error that occurred during validation.

ValidatePath validates a path expression and returns detailed error information

func WarmupPathCache(commonPaths []string)

WarmupPathCache pre-populates the path cache with common paths. Delegates to internal.GlobalPathIntern for storage.

func WarmupPathCacheWithProcessor(processor *Processor, commonPaths []string)

WarmupPathCacheWithProcessor pre-populates the path cache using a specific processor. Delegates to internal.GlobalPathIntern for storage.

WrapError wraps an error with additional context

WrapPathError wraps an error with path context

AccessResult represents the result of a dynamic access operation. It extends Result[any] with type conversion methods for safe type handling.

Example:

result := processor.SafeGet(data, "user.age")
age, err := result.AsInt()
name, err := result.AsString()

func NewAccessResult(value any, exists bool) AccessResult

NewAccessResult creates a new AccessResult.

AsBool safely converts the result to bool. Unlike ConvertToBool, this method is stricter and only accepts bool and string types. Use ConvertToBool directly if you need more permissive conversion (e.g., int to bool).

AsFloat64 safely converts the result to float64 with precision checks. Unlike ConvertToFloat64, this method is stricter and does NOT convert bool to float64. Use ConvertToFloat64 directly if you need more permissive conversion.

AsInt safely converts the result to int with overflow and precision checks. Unlike ConvertToInt, this method is stricter and does NOT convert bool to int. Use ConvertToInt directly if you need more permissive conversion.

AsString safely converts the result to string. Returns ErrTypeMismatch if the value is not a string type. Use AsStringConverted() for explicit type conversion with formatting.

AsStringConverted converts the result to string using fmt.Sprintf formatting. Use this when you explicitly want string representation of any type. For strict type checking, use AsString() instead.

Ok returns true if the value exists.

func (r AccessResult) Unwrap() any

Unwrap returns the value or nil if it doesn't exist.

func (r AccessResult) UnwrapOr(defaultValue any) any

UnwrapOr returns the value or the provided default if it doesn't exist.

type BatchIterator struct {
	
}

BatchIterator processes arrays in batches for efficient bulk operations

func NewBatchIterator(data []any, batchSize int) *BatchIterator

NewBatchIterator creates a new batch iterator

func (it *BatchIterator) CurrentIndex() int

CurrentIndex returns the current position in the array

HasNext returns true if there are more batches to process

func (it *BatchIterator) NextBatch() []any

NextBatch returns the next batch of elements Returns nil when no more batches are available

func (*BatchIterator) Remaining ¶ added in v1.2.0

func (it *BatchIterator) Remaining() int

Remaining returns the number of remaining elements

func (it *BatchIterator) Reset()

Reset resets the iterator to the beginning

func (it *BatchIterator) TotalBatches() int

TotalBatches returns the total number of batches

type BatchOperation struct {
	Type    string `json:"type"`
	JSONStr string `json:"json_str"`
	Path    string `json:"path"`
	Value   any    `json:"value"`
	ID      string `json:"id"`
}

BatchOperation represents a single operation in a batch

type BatchResult struct {
	ID     string `json:"id"`
	Result any    `json:"result"`
	Error  error  `json:"error"`
}

BatchResult represents the result of a batch operation

func ProcessBatch(operations []BatchOperation, cfg ...Config) ([]BatchResult, error)

ProcessBatch processes multiple JSON operations in a single batch. This is more efficient than processing each operation individually.

type BulkProcessor struct {
	
}

BulkProcessor handles multiple operations efficiently

func NewBulkProcessor(processor *Processor, batchSize int) *BulkProcessor

NewBulkProcessor creates a bulk processor

BulkGet performs multiple Get operations efficiently

type CachedPathParser interface {
	PathParser
	
	ParsePathCached(path string) ([]PathSegment, error)
	
	ClearPathCache()
}

CachedPathParser provides path parsing with caching.

type CheckResult struct {
	Healthy bool   `json:"healthy"`
	Message string `json:"message"`
}

CheckResult represents the result of a single health check

type ChunkedReader struct {
	
}

ChunkedReader reads JSON in chunks for memory efficiency

NewChunkedReader creates a new chunked reader

ReadArray reads array elements one at a time

ReadObject reads object key-value pairs one at a time

type ChunkedWriter struct {
	
}

ChunkedWriter writes JSON in chunks for memory efficiency

NewChunkedWriter creates a new chunked writer

func (cw *ChunkedWriter) Count() int

Count returns the number of items written

Flush writes the buffer to the underlying writer

WriteItem writes a single item to the chunk

WriteKeyValue writes a key-value pair to the chunk

type Config struct {
	
	MaxCacheSize int           `json:"max_cache_size"`
	CacheTTL     time.Duration `json:"cache_ttl"`
	EnableCache  bool          `json:"enable_cache"`
	CacheResults bool          `json:"cache_results"` 

	
	MaxJSONSize  int64 `json:"max_json_size"`
	MaxPathDepth int   `json:"max_path_depth"`
	MaxBatchSize int   `json:"max_batch_size"`

	
	MaxNestingDepthSecurity   int   `json:"max_nesting_depth"`
	MaxSecurityValidationSize int64 `json:"max_security_validation_size"`
	MaxObjectKeys             int   `json:"max_object_keys"`
	MaxArrayElements          int   `json:"max_array_elements"`
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	
	FullSecurityScan bool `json:"full_security_scan"`

	
	MaxConcurrency    int `json:"max_concurrency"`
	ParallelThreshold int `json:"parallel_threshold"`

	
	EnableValidation bool `json:"enable_validation"`
	StrictMode       bool `json:"strict_mode"`
	CreatePaths      bool `json:"create_paths"`
	CleanupNulls     bool `json:"cleanup_nulls"`
	CompactArrays    bool `json:"compact_arrays"`
	ContinueOnError  bool `json:"continue_on_error"` 

	
	PreserveNumbers  bool `json:"preserve_numbers"`
	ValidateInput    bool `json:"validate_input"`
	ValidateFilePath bool `json:"validate_file_path"`
	SkipValidation   bool `json:"skip_validation"` 

	
	Pretty          bool            `json:"pretty"`
	Indent          string          `json:"indent"`
	Prefix          string          `json:"prefix"`
	EscapeHTML      bool            `json:"escape_html"`
	SortKeys        bool            `json:"sort_keys"`
	ValidateUTF8    bool            `json:"validate_utf8"`
	MaxDepth        int             `json:"max_depth"`
	DisallowUnknown bool            `json:"disallow_unknown"`
	FloatPrecision  int             `json:"float_precision"`
	FloatTruncate   bool            `json:"float_truncate"`
	DisableEscaping bool            `json:"disable_escaping"`
	EscapeUnicode   bool            `json:"escape_unicode"`
	EscapeSlash     bool            `json:"escape_slash"`
	EscapeNewlines  bool            `json:"escape_newlines"`
	EscapeTabs      bool            `json:"escape_tabs"`
	IncludeNulls    bool            `json:"include_nulls"`
	CustomEscapes   map[rune]string `json:"custom_escapes,omitempty"`

	
	EnableMetrics     bool `json:"enable_metrics"`
	EnableHealthCheck bool `json:"enable_health_check"`

	
	Context context.Context `json:"-"` 

	
	
	CustomEncoder CustomEncoder

	
	
	CustomTypeEncoders map[reflect.Type]TypeEncoder

	
	
	CustomValidators []Validator

	
	
	
	AdditionalDangerousPatterns []DangerousPattern

	
	
	DisableDefaultPatterns bool

	
	Hooks []Hook

	
	
	CustomPathParser PathParser
}

Config holds all configuration for the JSON processor. Start with DefaultConfig() and modify as needed.

Example:

cfg := json.DefaultConfig()
cfg.CreatePaths = true
cfg.Pretty = true
result, err := json.Set(data, "path", value, cfg)

func DefaultConfig() Config

DefaultConfig returns the default configuration. Creates a new instance each time to allow modifications without affecting other callers.

func PrettyConfig() Config

PrettyConfig returns a Config for pretty-printed JSON output. This is the unified version that returns Config instead of EncodeConfig.

Example:

result, err := json.Encode(data, json.PrettyConfig())

func SecurityConfig() Config

SecurityConfig returns a configuration with enhanced security settings for processing untrusted input from external sources.

This is the recommended configuration for:

Public APIs and web services
User-submitted data
External webhooks
Authentication endpoints
Financial data processing

Key characteristics:

Full security scan enabled for all input
Strict mode enabled for predictable parsing
Conservative limits for untrusted payloads
Caching enabled for repeated operations

This function unifies HighSecurityConfig and WebAPIConfig into a single entry point.

func (c *Config) AddDangerousPattern(pattern DangerousPattern)

AddDangerousPattern adds a security pattern to the configuration.

func (c *Config) AddHook(hook Hook)

AddHook adds an operation hook to the configuration. Hooks are executed in order for Before and in reverse order for After.

func (c *Config) AddValidator(validator Validator)

AddValidator adds a custom validator to the configuration. Validators are executed in order; all must pass for operations to proceed.

func (c *Config) Clone() *Config

Clone creates a copy of the configuration. Performs a deep copy of reference types (maps, slices). Returns a pointer to avoid unnecessary copying of the large Config struct.

NOTE: Interface fields (CustomEncoder, CustomPathParser, Context) are shallow-copied as they typically contain stateless or singleton implementations. CustomTypeEncoders, CustomValidators, AdditionalDangerousPatterns, and Hooks are deep-copied as they may be modified independently.

func (c *Config) GetFloatPrecision() int

func (c *Config) GetMaxCacheSize() int

func (c *Config) GetMaxConcurrency() int

func (c *Config) GetMaxDepth() int

func (c *Config) GetMaxJSONSize() int64

Convenience accessor methods for testing and interface-based usage. Rationale: These methods enable mock-based testing and potential future interface abstraction. In application code, direct field access is preferred:

cfg.MaxJSONSize instead of cfg.GetMaxJSONSize()
cfg.StrictMode instead of cfg.IsStrictMode()

func (c *Config) GetMaxNestingDepth() int

func (c *Config) GetMaxPathDepth() int

GetSecurityLimits returns a summary of current security limits

func (c *Config) IsCacheEnabled() bool

Required by CacheConfig interface (internal/cache.go) - do not remove.

func (c *Config) IsCommentsAllowed() bool

func (c *Config) IsDisallowUnknownEnabled() bool

func (c *Config) IsHTMLEscapeEnabled() bool

Required by EncoderConfig interface (interfaces.go) for custom encoders. These methods provide read-only access to encoding configuration.

func (c *Config) IsHealthCheckEnabled() bool

func (c *Config) IsMetricsEnabled() bool

func (c *Config) IsPrettyEnabled() bool

func (c *Config) IsSortKeysEnabled() bool

func (c *Config) IsStrictMode() bool

func (c *Config) IsTruncateFloatEnabled() bool

func (c *Config) ShouldCleanupNulls() bool

func (c *Config) ShouldCompactArrays() bool

func (c *Config) ShouldCreatePaths() bool

func (c *Config) ShouldEscapeNewlines() bool

func (c *Config) ShouldEscapeSlash() bool

func (c *Config) ShouldEscapeTabs() bool

func (c *Config) ShouldEscapeUnicode() bool

func (c *Config) ShouldIncludeNulls() bool

func (c *Config) ShouldPreserveNumbers() bool

func (c *Config) ShouldValidateFilePath() bool

func (c *Config) ShouldValidateInput() bool

func (c *Config) ShouldValidateUTF8() bool

Validate validates the configuration and applies corrections. This is the single source of truth for config validation. DRY FIX: Delegates to ValidateWithWarnings to avoid code duplication

func (c *Config) ValidateWithWarnings() []ConfigWarning

ValidateWithWarnings validates the configuration and returns warnings for any modifications made. This is useful for debugging configuration issues or informing users about automatic adjustments.

Example:

cfg := json.DefaultConfig()
cfg.MaxJSONSize = -1 // Invalid value
warnings := cfg.ValidateWithWarnings()
for _, w := range warnings {
    fmt.Printf("%s: %s\n", w.Field, w.Reason)
}

ConfigWarning represents a configuration modification made during validation.

CustomEncoder provides custom JSON encoding capability. Implement this interface to replace the default encoder entirely.

Example:

type UpperCaseEncoder struct{}
func (e *UpperCaseEncoder) Encode(value any) (string, error) {
    // Custom encoding logic
}

cfg := json.DefaultConfig()
cfg.CustomEncoder = &UpperCaseEncoder{}

type DangerousPattern struct {
	
	Pattern string

	
	Name string

	
	Level PatternLevel
}

DangerousPattern represents a security risk pattern to detect.

func GetCriticalPatterns() []DangerousPattern

GetCriticalPatterns returns patterns that are always fully scanned.

func GetDefaultPatterns() []DangerousPattern

GetDefaultPatterns returns the built-in dangerous patterns as DangerousPattern values. All default patterns are considered Critical level.

func ListDangerousPatterns() []DangerousPattern

ListDangerousPatterns returns all registered custom patterns.

Decoder reads and decodes JSON values from an input stream. This type is fully compatible with encoding/json.Decoder.

NewDecoder returns a new decoder that reads from r. This function is fully compatible with encoding/json.NewDecoder.

Decode reads the next JSON-encoded value from its input and stores it in v.

func (dec *Decoder) DisallowUnknownFields()

func (dec *Decoder) InputOffset() int64

func (dec *Decoder) More() bool

Token returns the next JSON token in the input stream. At the end of the input stream, Token returns nil, io.EOF.

func (dec *Decoder) UseNumber()

Delim is a JSON delimiter.

Encoder writes JSON values to an output stream. This type is fully compatible with encoding/json.Encoder.

NewEncoder returns a new encoder that writes to w. This function is fully compatible with encoding/json.NewEncoder.

NewEncoderWithOpts returns a new encoder that writes to w with Config configuration. This is the unified API for creating encoders with consistent Config pattern.

Example:

cfg := json.DefaultConfig()
cfg.Pretty = true
encoder := json.NewEncoderWithOpts(writer, &cfg)
err := encoder.Encode(data)

Encode writes the JSON encoding of v to the stream, followed by a newline character.

See the documentation for Marshal for details about the conversion of Go values to JSON.

func (enc *Encoder) SetEscapeHTML(on bool)

SetEscapeHTML specifies whether problematic HTML characters should be escaped inside JSON quoted strings. The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e to avoid certain safety problems that can arise when embedding JSON in HTML.

In non-HTML settings where the escaping interferes with the readability of the output, SetEscapeHTML(false) disables this behavior.

func (enc *Encoder) SetIndent(prefix, indent string)

SetIndent instructs the encoder to format each subsequent encoded value as if indented by the package-level function Indent(dst, src, prefix, indent). Calling SetIndent("", "") disables indentation.

type EncoderConfig interface {
	
	IsHTMLEscapeEnabled() bool

	
	IsPrettyEnabled() bool
	GetIndent() string
	GetPrefix() string

	
	IsSortKeysEnabled() bool

	
	GetFloatPrecision() int
	IsTruncateFloatEnabled() bool

	
	GetMaxDepth() int

	
	ShouldIncludeNulls() bool

	
	ShouldValidateUTF8() bool

	
	IsDisallowUnknownEnabled() bool

	
	ShouldEscapeUnicode() bool

	
	ShouldEscapeSlash() bool

	
	ShouldEscapeNewlines() bool

	
	ShouldEscapeTabs() bool
}

EncoderConfig provides configuration access for custom encoders. Implemented by Config struct.

type HealthStatus struct {
	Timestamp time.Time              `json:"timestamp"`
	Healthy   bool                   `json:"healthy"`
	Checks    map[string]CheckResult `json:"checks"`
}

HealthStatus represents the health status of the processor

func GetHealthStatus() HealthStatus

GetHealthStatus returns the health status of the default processor.

Hook intercepts operations before/after execution. Implement this interface to add cross-cutting concerns like logging, metrics, tracing, or request transformation.

Example:

type LoggingHook struct{ logger *slog.Logger }

func (h *LoggingHook) Before(ctx json.HookContext) error {
    h.logger.Info("operation starting", "op", ctx.Operation, "path", ctx.Path)
    return nil
}

func (h *LoggingHook) After(ctx json.HookContext, result any, err error) (any, error) {
    h.logger.Info("operation completed", "op", ctx.Operation, "error", err)
    return result, err
}

ErrorHook creates a hook that intercepts errors. The handler can transform errors or log them.

Example:

p.AddHook(json.ErrorHook(func(ctx json.HookContext, err error) error {
    sentry.CaptureException(err)
    return err // return original or transformed error
}))

func LoggingHook(logger interface{ Info(msg string, args ...any) }) Hook

LoggingHook creates a hook that logs all operations. The logger must implement Info(msg string, args ...any).

Example:

p.AddHook(json.LoggingHook(slog.Default()))

TimingHook creates a hook that records operation duration. The recorder must implement Record(op string, duration time.Duration).

Example:

p.AddHook(json.TimingHook(myMetricsRecorder))

func ValidationHook(validator func(jsonStr, path string) error) Hook

ValidationHook creates a hook that validates input before operations. Return error from the validator to abort the operation.

Example:

p.AddHook(json.ValidationHook(func(jsonStr, path string) error {
    if len(jsonStr) > 1_000_000 {
        return errors.New("JSON too large")
    }
    return nil
}))

HookChain manages multiple hooks for sequential execution.

ExecuteAfter runs all After hooks in reverse order.

func (hc HookChain) ExecuteBefore(ctx HookContext) error

ExecuteBefore runs all Before hooks in order, stopping at first error.

HookContext provides context for operation hooks.

HookFunc is an adapter to use ordinary functions as Hooks. Useful for simple hooks that don't need both Before and After.

Example:

// Only need After
p.AddHook(&json.HookFunc{
    AfterFn: func(ctx json.HookContext, result any, err error) (any, error) {
        log.Printf("%s completed in %v", ctx.Operation, time.Since(ctx.StartTime))
        return result, err
    },
})

After calls the AfterFn if set, otherwise returns the original result.

Before calls the BeforeFn if set, otherwise returns nil.

type InvalidUnmarshalError struct {
	Type reflect.Type
}

InvalidUnmarshalError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

type IterableValue struct {
	
}

IterableValue wraps a value to provide convenient access methods Note: Simplified to avoid resource leaks from holding processor/iterator references

func NewIterableValue(data any) *IterableValue

NewIterableValue creates an IterableValue from data

Exists checks if a key or path exists in the object Supports path navigation with dot notation and array indices

func (iv *IterableValue) ForeachNested(path string, fn func(key any, item *IterableValue))

ForeachNested iterates over nested JSON structures with a path

Get returns a value by path (supports dot notation and array indices)

GetArray returns an array value by key or path Supports path navigation with dot notation and array indices

GetBool returns a bool value by key or path Supports path navigation with dot notation and array indices

GetBoolWithDefault returns a bool value by key or path with a default fallback Supports path navigation with dot notation and array indices

func (iv *IterableValue) GetData() any

GetData returns the underlying data

GetFloat64 returns a float64 value by key or path Supports path navigation with dot notation and array indices

GetFloat64WithDefault returns a float64 value by key or path with a default fallback Supports path navigation with dot notation and array indices

GetInt returns an int value by key or path Supports path navigation with dot notation and array indices (e.g., "user.age" or "users[0].id")

GetIntWithDefault returns an int value by key or path with a default fallback Supports path navigation with dot notation and array indices

GetObject returns an object value by key or path Supports path navigation with dot notation and array indices

GetString returns a string value by key or path Supports path navigation with dot notation and array indices (e.g., "user.address.city" or "users[0].name")

GetStringWithDefault returns a string value by key or path with a default fallback Supports path navigation with dot notation and array indices

GetWithDefault returns a value by key or path with a default fallback Supports path navigation with dot notation and array indices

IsEmpty checks if a specific key's or path's value is empty Supports path navigation with dot notation and array indices

func (iv *IterableValue) IsEmptyData() bool

IsEmptyData checks if the whole value is empty (for backward compatibility)

IsNull checks if a specific key's or path's value is null Supports path navigation with dot notation and array indices

func (iv *IterableValue) IsNullData() bool

IsNullData checks if the whole value is null (for backward compatibility)

func (iv *IterableValue) Release()

Release returns the IterableValue to the pool

Iterator represents an iterator over JSON data

func NewIterator(data any, opts ...Config) *Iterator

NewIterator creates a new Iterator over the provided data. Simplified API: creates an iterator for traversing arrays and objects. Note: The opts parameter is reserved for future use and currently ignored.

func (it *Iterator) HasNext() bool

HasNext checks if there are more elements

Next returns the next element

IteratorControl represents control flags for iteration operations. Used by Foreach* functions to control iteration flow.

const (
	
	IteratorNormal IteratorControl = iota
	
	IteratorContinue
	
	IteratorBreak
)

type JSONLConfig struct {
	BufferSize    int        
	MaxLineSize   int        
	SkipEmpty     bool       
	ContinueOnErr bool       
	Processor     *Processor 
}

JSONLConfig holds configuration for JSONL processing

func DefaultJSONLConfig() JSONLConfig

DefaultJSONLConfig returns the default JSONL configuration

type JSONLProcessor struct {
	
}

JSONLProcessor processes JSON Lines format data PERFORMANCE: Uses buffered reading and object pooling for efficiency

NewJSONLProcessor creates a new JSONL processor with default configuration.

func NewJSONLProcessorWithConfig(reader io.Reader, config JSONLConfig) *JSONLProcessor

NewJSONLProcessorWithConfig creates a new JSONL processor with the specified configuration.

Example:

cfg := json.DefaultJSONLConfig()
cfg.SkipEmpty = false
cfg.Processor = customProcessor
proc := json.NewJSONLProcessorWithConfig(reader, cfg)

Err returns any error encountered during processing

func (j *JSONLProcessor) GetStats() JSONLStats

GetStats returns current processing statistics

func (j *JSONLProcessor) Release()

Release releases resources held by the JSONLProcessor.

IMPORTANT:

Call this after all processing is complete
For StreamLinesParallel, ensure workers have finished before calling Release
After Release, the processor must not be used

Resource Management:

Sets stopped flag to halt any pending operations
Clears internal processor reference to allow garbage collection

func (j *JSONLProcessor) Stop()

Stop stops the JSONL processor

StreamLines processes JSONL data line by line The callback function receives the line number and parsed data Return false from the callback to stop iteration

StreamLinesParallel processes JSONL data in parallel using worker pool PERFORMANCE: Parallel processing for CPU-bound operations on JSONL data

type JSONLStats struct {
	LinesProcessed int64
	BytesRead      int64
	BytesWritten   int64
	CurrentLine    int
}

Stats returns processing statistics

type JSONLWriter struct {
	
}

JSONLWriter writes JSON Lines format to an io.Writer

NewJSONLWriter creates a new JSONL writer

Err returns any error encountered during writing

func (w *JSONLWriter) Stats() JSONLStats

Stats returns writing statistics

Write writes a single JSON value as a line

WriteAll writes multiple JSON values as lines

WriteRaw writes a raw JSON line (already encoded)

type JsonsError struct {
	Op      string `json:"op"`      
	Path    string `json:"path"`    
	Message string `json:"message"` 
	Err     error  `json:"err"`     
}

JsonsError represents a JSON processing error with essential context

Is implements error matching for Go 1.13+ error handling Compares Op, Path, and Err fields for complete equality. Note: Message is intentionally excluded as it's derived from other fields.

Unwrap returns the underlying error for error chain support

type LargeFileConfig struct {
	ChunkSize       int64 
	MaxMemory       int64 
	BufferSize      int   
	SamplingEnabled bool  
	SampleSize      int   
}

LargeFileConfig holds configuration for large file processing

func DefaultLargeFileConfig() LargeFileConfig

DefaultLargeFileConfig returns the default configuration

type LargeFileProcessor struct {
	
}

LargeFileProcessor handles processing of large JSON files

func NewLargeFileProcessor(config LargeFileConfig) *LargeFileProcessor

NewLargeFileProcessor creates a new large file processor

ProcessFile processes a large JSON file efficiently

ProcessFileChunked processes a large JSON file in chunks

type LazyParser struct {
	
}

LazyParser provides lazy JSON parsing that supports both JSON objects and arrays

func NewLazyParser(data []byte) *LazyParser

NewLazyParser creates a new lazy parser

Error returns any parsing error, triggering parse if needed

Get retrieves a value at the given path

GetObject returns the parsed data as a map (only for JSON objects). Returns ErrTypeMismatch if the parsed JSON is not an object.

GetValue returns all parsed data as interface{} (supports any JSON type)

func (lp *LazyParser) IsArray() bool

IsArray returns true if the parsed JSON is an array

func (lp *LazyParser) IsObject() bool

IsObject returns true if the parsed JSON is an object

func (lp *LazyParser) IsParsed() bool

IsParsed returns whether the JSON has been parsed

Parse forces parsing and returns the parsed data

func (lp *LazyParser) Parsed() any

Parsed returns the parsed data without forcing parsing. Returns nil if not yet parsed.

Raw returns the raw JSON bytes

type Marshaler interface {
	MarshalJSON() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid JSON.

MarshalerError represents an error from calling a MarshalJSON or MarshalText method.

MergeMode defines the merge strategy for combining JSON objects and arrays. This is a type alias to internal.MergeMode to ensure consistency across the codebase.

type NDJSONProcessor struct {
	
}

NDJSONProcessor processes newline-delimited JSON files

func NewNDJSONProcessor(bufferSize int) *NDJSONProcessor

NewNDJSONProcessor creates a new NDJSON processor

ProcessFile processes an NDJSON file line by line

ProcessReader processes NDJSON from a reader

Number represents a JSON number literal.

Float64 returns the number as a float64.

Int64 returns the number as an int64.

String returns the literal text of the number.

type ParallelIterator struct {
	
}

ParallelIterator processes arrays in parallel using worker goroutines

func NewParallelIterator(data []any, workers int) *ParallelIterator

NewParallelIterator creates a new parallel iterator

func (it *ParallelIterator) Close()

Close releases resources associated with the ParallelIterator. RESOURCE FIX: Added for API consistency and to document proper cleanup patterns. The semaphore channel is automatically garbage collected when the iterator is no longer referenced.

Filter filters elements in parallel using a predicate function Returns a new slice with elements that pass the predicate

ForEach processes each element in parallel using the provided function The function receives the index and value of each element Returns the first error encountered, or nil if all operations succeed

ForEachBatch processes elements in batches in parallel Each batch is processed by a single goroutine

ForEachBatchWithContext processes elements in batches with context support for cancellation Each batch is processed by a single goroutine RESOURCE FIX: Added context support for graceful goroutine termination

ForEachWithContext processes each element in parallel with context support for cancellation The function receives the index and value of each element Returns the first error encountered, or ctx.Err() if context is cancelled RESOURCE FIX: Added context support for graceful goroutine termination

Map applies a transformation function to each element in parallel Returns a new slice with the transformed values

type ParsedJSON struct {
	
}

ParsedJSON represents a pre-parsed JSON document that can be reused for multiple operations. This is a performance optimization for scenarios where the same JSON is queried multiple times. OPTIMIZED: Pre-parsing avoids repeated JSON parsing overhead for repeated queries.

func (p *ParsedJSON) Data() any

Data returns the underlying parsed data

type PathParser interface {
	
	ParsePath(path string) ([]PathSegment, error)
}

PathParser parses path strings into segments. Implement to provide custom path syntax support.

type PathSecurityChecker struct {
	
}

PathSecurityChecker handles path security validation. RESPONSIBILITY: Validates JSON path syntax and security.

func NewPathSecurityChecker(maxPathLength int) *PathSecurityChecker

NewPathSecurityChecker creates a new path security checker.

Validate checks the path for security issues.

PathSegment represents a parsed path segment. This is an alias to internal.PathSegment. Methods like HasStart(), HasEnd(), etc. are available through the internal type.

func NewAppendSegment() PathSegment

NewAppendSegment creates an append segment.

func NewArrayIndexSegment(index int) PathSegment

NewArrayIndexSegment creates an array index access segment.

func NewArraySliceSegment(start, end, step int, hasStart, hasEnd, hasStep bool) PathSegment

NewArraySliceSegment creates an array slice segment.

NewExtractSegment creates an extraction segment.

func NewPropertySegment(key string) PathSegment

NewPropertySegment creates a property access segment.

func NewRecursiveSegment() PathSegment

NewRecursiveSegment creates a recursive descent segment.

func NewWildcardSegment() PathSegment

NewWildcardSegment creates a wildcard segment.

PathSegmentFlags are bit flags for path segment options. This is an alias to internal.PathSegmentFlags.

Path flag constants - aliases to internal package

PathSegmentType identifies the type of a path segment. This is an alias to internal.PathSegmentType.

Path segment type constants - aliases to internal package

type PathValidator interface {
	ValidatePath(path string) error
}

PathValidator validates path syntax before navigation. Implement to add custom path validation rules.

type PatternChecker struct {
	
}

PatternChecker handles dangerous pattern detection in JSON content. RESPONSIBILITY: Detects and reports dangerous patterns like XSS, prototype pollution, etc.

func NewPatternChecker(fullSecurityScan bool) *PatternChecker

NewPatternChecker creates a new pattern checker.

Check performs pattern validation on the JSON string. Returns error if dangerous patterns are detected.

PatternLevel represents the severity level of a dangerous pattern.

const (
	
	
	PatternLevelCritical PatternLevel = iota

	
	
	PatternLevelWarning

	
	
	PatternLevelInfo
)

String returns the string representation of PatternLevel.

type PatternRegistry interface {
	
	Add(pattern DangerousPattern)

	
	Remove(pattern string)

	
	List() []DangerousPattern

	
	ListByLevel(level PatternLevel) []DangerousPattern

	
	Clear()
}

PatternRegistry manages dangerous patterns with thread-safe operations.

type Processor struct {
	
}

Processor is the main JSON processing engine with thread safety and performance optimization

New creates a new JSON processor with the given configuration. If no configuration is provided, uses default configuration. Returns an error if the configuration is invalid.

Example:

// Using default configuration
processor, err := json.New()

// With custom configuration
cfg := json.DefaultConfig()
cfg.CreatePaths = true
processor, err := json.New(cfg)

// Using preset configuration
processor, err := json.New(json.SecurityConfig())

func (p *Processor) AddHook(hook Hook)

AddHook adds an operation hook to the processor. Hooks are called before and after each operation. Multiple hooks can be added and are executed in order (Before) and reverse order (After).

Example:

type LoggingHook struct{}
func (h *LoggingHook) Before(ctx json.HookContext) error {
    log.Printf("before %s", ctx.Operation)
    return nil
}
func (h *LoggingHook) After(ctx json.HookContext, result any, err error) (any, error) {
    log.Printf("after %s", ctx.Operation)
    return result, err
}

p := json.MustNew()
p.AddHook(&LoggingHook{})

BatchDeleteOptimized performs multiple Delete operations efficiently

BatchSetOptimized performs multiple Set operations efficiently

func (p *Processor) ClearCache()

ClearCache clears all cached data

Close closes the processor and cleans up resources This method is idempotent and thread-safe

Compact removes whitespace from JSON string

CompactBuffer appends to dst the JSON-encoded src with insignificant space characters elided. Compatible with encoding/json.Compact with optional Config support.

CompactBytes appends to dst the JSON-encoded src with insignificant space characters elided. This is an alias for CompactBuffer without optional Config, providing encoding/json.Compact compatibility. Use this method when you need the exact encoding/json.Compact signature.

Example:

var buf bytes.Buffer
err := processor.CompactBytes(&buf, []byte(`{"name": "Alice"}`))

CompactString removes whitespace from JSON string. This is an alias for Compact for consistency with the package-level CompactString function.

CompilePath compiles a JSON path string into a CompiledPath for fast repeated operations The returned CompiledPath can be reused for multiple Get/Set/Delete operations

Delete removes a value from JSON at the specified path

DeleteClean removes a value from JSON and cleans up null placeholders. This is the unified API for delete-with-cleanup operations.

Example:

result, err := processor.DeleteClean(data, "users[0].profile")

Encode converts any Go value to JSON string This is a convenience method that matches the package-level Encode signature

EncodeBatch encodes multiple key-value pairs as a JSON object. This method accepts variadic Config for unified API pattern.

Example:

result, err := processor.EncodeBatch(pairs, json.PrettyConfig())

EncodeFields encodes struct fields selectively based on field names. This method accepts variadic Config for unified API pattern.

Example:

result, err := processor.EncodeFields(value, []string{"name", "email"}, json.PrettyConfig())

EncodePretty converts any Go value to pretty-formatted JSON string This is a convenience method that matches the package-level EncodePretty signature

EncodeStream encodes multiple values as a JSON array stream. This method accepts variadic Config for unified API pattern.

Example:

result, err := processor.EncodeStream(values, json.PrettyConfig())

EncodeWithConfig converts any Go value to JSON string with full configuration control. PERFORMANCE: Uses FastEncoder for simple types to avoid reflection overhead.

Example:

// Default configuration
result, err := processor.EncodeWithConfig(data)

// With custom configuration
cfg := json.DefaultConfig()
cfg.Pretty = true
result, err := processor.EncodeWithConfig(data, cfg)

// With preset configuration
result, err := processor.EncodeWithConfig(data, json.PrettyConfig())

FastDelete is an optimized Delete operation for simple paths

FastGetMultiple performs multiple Get operations with single parse

FastSet is an optimized Set operation for simple paths Uses pooled resources and optimized marshaling

func (p *Processor) Foreach(jsonStr string, fn func(key any, item *IterableValue))

Foreach iterates over JSON arrays or objects using this processor

func (p *Processor) ForeachNested(jsonStr string, fn func(key any, item *IterableValue))

ForeachNested recursively iterates over all nested JSON structures This method traverses through all nested objects and arrays

ForeachReturn iterates over JSON arrays or objects and returns the JSON string This is useful for iteration with transformation purposes

ForeachWithPath iterates over JSON arrays or objects at a specific path using this processor This allows using custom processor configurations (security limits, nesting depth, etc.)

func (*Processor) ForeachWithPathAndControl ¶ added in v1.0.9

ForeachWithPathAndControl iterates with control over iteration flow

func (*Processor) ForeachWithPathAndIterator ¶ added in v1.0.9

ForeachWithPathAndIterator iterates over JSON at a path with path information

FormatCompact removes whitespace from JSON string (alias for Compact)

Get retrieves a value from JSON using a path expression with performance

GetArray retrieves an array value from JSON at the specified path

GetBool retrieves a bool value from JSON at the specified path

GetBoolOr retrieves a bool value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

GetCompiled retrieves a value from JSON using a pre-compiled path PERFORMANCE: Skips path parsing for faster repeated operations

GetCompiledExists checks if a path exists in pre-parsed JSON data using a compiled path

GetCompiledFromParsed retrieves a value from pre-parsed JSON data using a compiled path PERFORMANCE: No JSON parsing overhead - uses already parsed data

func (p *Processor) GetConfig() Config

GetConfig returns a copy of the processor configuration

GetFloat retrieves a float64 value from JSON at the specified path

GetFloatOr retrieves a float64 value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

GetFromParsed retrieves a value from a pre-parsed JSON document at the specified path. This is significantly faster than Get() for repeated queries on the same JSON.

OPTIMIZED: Skips JSON parsing, goes directly to path navigation.

GetFromParsedData retrieves a value from already-parsed data Uses the processor's path navigation without re-parsing

func (p *Processor) GetHealthStatus() HealthStatus

GetHealthStatus returns the current health status

GetInt retrieves an int value from JSON at the specified path

func (p *Processor) GetIntOr(jsonStr, path string, defaultValue int, opts ...Config) int

GetIntOr retrieves an int value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

GetMultiple retrieves multiple values from JSON using multiple path expressions

GetObject retrieves an object value from JSON at the specified path

func (p *Processor) GetStats() Stats

GetStats returns processor performance statistics

GetString retrieves a string value from JSON at the specified path

GetStringOr retrieves a string value from JSON at the specified path with a default fallback. Returns defaultValue if: path not found, value is null, or type conversion fails.

HTMLEscapeBuffer appends to dst the JSON-encoded src with HTML-safe escaping. Replaces &, <, and > with \u0026, \u003c, and \u003e for safe HTML embedding. Compatible with encoding/json.HTMLEscape with optional Config support.

IndentBuffer appends to dst an indented form of the JSON-encoded src. Compatible with encoding/json.Indent with optional Config support.

IndentBytes appends to dst an indented form of the JSON-encoded src. This is an alias for IndentBuffer without optional Config, providing encoding/json.Indent compatibility. Use this method when you need the exact encoding/json.Indent signature.

Example:

var buf bytes.Buffer
err := processor.IndentBytes(&buf, []byte(`{"name":"Alice"}`), "", "  ")

func (p *Processor) IsClosed() bool

IsClosed returns true if the processor has been closed

LoadFromFile loads JSON data from a file and returns the raw JSON string.

LoadFromFileAsData loads JSON data from a file and returns the parsed data structure.

LoadFromReader loads JSON data from an io.Reader and returns the raw JSON string.

LoadFromReaderAsData loads JSON data from an io.Reader and returns the parsed data structure.

Marshal converts any Go value to JSON bytes (similar to json.Marshal) PERFORMANCE: Uses FastEncoder for simple types to avoid reflection overhead

MarshalIndent converts any Go value to indented JSON bytes (similar to json.MarshalIndent)

MarshalToFile converts data to JSON and saves it to the specified file using Config. This is the unified API that accepts variadic Config.

Example:

err := processor.MarshalToFile("data.json", data, json.PrettyConfig())

Parse parses a JSON string into the provided target with improved error handling

ParseAny parses a JSON string and returns the result as any. This method provides the same behavior as the package-level Parse function. Use Parse when you need to unmarshal into a specific target type.

Example:

data, err := processor.ParseAny(`{"name": "Alice"}`)

PreParse parses a JSON string and returns a ParsedJSON object that can be reused for multiple Get operations. This is a performance optimization for scenarios where the same JSON is queried multiple times.

OPTIMIZED: Pre-parsing avoids repeated JSON parsing overhead for repeated queries.

Example:

parsed, err := processor.PreParse(jsonStr)
if err != nil { return err }
value1, _ := processor.GetFromParsed(parsed, "path1")
value2, _ := processor.GetFromParsed(parsed, "path2")

Prettify formats JSON string with indentation. This is the recommended method for formatting JSON strings.

func (p *Processor) ProcessBatch(operations []BatchOperation, opts ...Config) ([]BatchResult, error)

ProcessBatch processes multiple operations in a single batch

func (p *Processor) SafeGet(jsonStr, path string) AccessResult

SafeGet performs a type-safe get operation with comprehensive error handling

SaveToFile saves data to a JSON file using Config. This is the unified API that accepts variadic Config.

Example:

err := processor.SaveToFile("data.json", data, json.PrettyConfig())

SaveToWriter saves data to an io.Writer using Config. This is the unified API that accepts variadic Config.

Example:

var buf bytes.Buffer
err := processor.SaveToWriter(&buf, data, json.PrettyConfig())

Set sets a value in JSON at the specified path Returns:

On success: modified JSON string and nil error
On failure: original unmodified JSON string and error information

SetCreate sets a value at the specified path, creating intermediate paths as needed. This is the unified API for set-with-path-creation operations.

Example:

result, err := processor.SetCreate(data, "users[0].profile.name", "Alice")

SetFromParsed modifies a pre-parsed JSON document at the specified path. Returns a new ParsedJSON with the modified data (original is not modified).

OPTIMIZED: Skips JSON parsing, works directly on parsed data.

SetLogger sets a custom structured logger for the processor

SetMultiple sets multiple values in JSON using a map of path-value pairs Returns:

On success: modified JSON string and nil error
On failure: original unmodified JSON string and error information

SetMultipleCreate sets multiple values, creating intermediate paths as needed. This is the unified API for batch set-with-path-creation operations.

Example:

result, err := processor.SetMultipleCreate(data, map[string]any{"user.name": "Alice", "user.age": 30})

ToJsonString converts any Go value to JSON string with HTML escaping (safe for web)

ToJsonStringPretty converts any Go value to pretty JSON string with HTML escaping

func (*Processor) ToJsonStringStandard ¶

ToJsonStringStandard converts any Go value to compact JSON string without HTML escaping

Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v. This method is fully compatible with encoding/json.Unmarshal. PERFORMANCE: Fast path for simple cases to avoid string conversion overhead.

UnmarshalFromFile reads JSON data from the specified file and unmarshals it into the provided value.

Valid validates JSON format without parsing the entire structure

ValidBytes validates JSON format from byte slice (matches encoding/json.Valid signature) This method provides compatibility with the standard library's json.Valid function

func (p *Processor) ValidateSchema(jsonStr string, schema *Schema, opts ...Config) ([]ValidationError, error)

ValidateSchema validates JSON data against a schema

WarmupCache pre-loads commonly used paths into cache to improve first-access performance

type Result[T any] struct {
	Value  T     
	Exists bool  
	Error  error 
}

Result represents a type-safe operation result with comprehensive error handling. This is the unified type for all type-safe operations.

Example:

result := json.GetResult[string](data, "user.name")
if result.Ok() {
    name := result.Unwrap()
}
// Or with default
name := json.GetResult[string](data, "user.name").UnwrapOr("unknown")

NewResult creates a new Result with the given value.

Ok returns true if the result is valid (no error and exists).

func (r Result[T]) Unwrap() T

Unwrap returns the value or zero value if there's an error or value doesn't exist. For panic behavior, use Must() instead.

func (r Result[T]) UnwrapOr(defaultValue T) T

UnwrapOr returns the value or the provided default if there's an error or value doesn't exist.

type SamplingReader struct {
	
}

SamplingReader samples data from large JSON arrays

NewSamplingReader creates a new sampling reader

Sample reads a sample of items from a JSON array using reservoir sampling. The reservoir sampling algorithm ensures uniform random sampling distribution: each item in the array has an equal probability of being included in the sample.

TotalRead returns the total number of items read

type Schema struct {
	Type                 string             `json:"type,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	Required             []string           `json:"required,omitempty"`
	MinLength            int                `json:"minLength,omitempty"`
	MaxLength            int                `json:"maxLength,omitempty"`
	Minimum              float64            `json:"minimum,omitempty"`
	Maximum              float64            `json:"maximum,omitempty"`
	Pattern              string             `json:"pattern,omitempty"`
	Format               string             `json:"format,omitempty"`
	AdditionalProperties bool               `json:"additionalProperties,omitempty"`
	MinItems             int                `json:"minItems,omitempty"`
	MaxItems             int                `json:"maxItems,omitempty"`
	UniqueItems          bool               `json:"uniqueItems,omitempty"`
	Enum                 []any              `json:"enum,omitempty"`
	Const                any                `json:"const,omitempty"`
	MultipleOf           float64            `json:"multipleOf,omitempty"`
	ExclusiveMinimum     bool               `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum     bool               `json:"exclusiveMaximum,omitempty"`
	Title                string             `json:"title,omitempty"`
	Description          string             `json:"description,omitempty"`
	Default              any                `json:"default,omitempty"`
	Examples             []any              `json:"examples,omitempty"`
	
}

Schema represents a JSON schema for validation

func DefaultSchema() *Schema

DefaultSchema returns a default schema configuration. All zero values are omitted for brevity; only non-zero defaults are set.

func NewSchemaWithConfig(cfg SchemaConfig) *Schema

NewSchemaWithConfig creates a new Schema with the provided configuration. This is the recommended way to create configured Schema instances.

func (s *Schema) HasMaxItems() bool

HasMaxItems returns true if MaxItems constraint is explicitly set

func (s *Schema) HasMaxLength() bool

HasMaxLength returns true if MaxLength constraint is explicitly set

func (s *Schema) HasMaximum() bool

HasMaximum returns true if Maximum constraint is explicitly set

func (s *Schema) HasMinItems() bool

HasMinItems returns true if MinItems constraint is explicitly set

func (s *Schema) HasMinLength() bool

HasMinLength returns true if MinLength constraint is explicitly set

func (s *Schema) HasMinimum() bool

HasMinimum returns true if Minimum constraint is explicitly set

SchemaConfig provides configuration options for creating a Schema. This follows the Config pattern as required by the design guidelines.

type SecurityValidator interface {
	Validator
	
	
	ValidateContent(content string) error
}

SecurityValidator checks for dangerous patterns in content. Extends Validator with content-specific security checks.

type Stats struct {
	CacheSize        int64         `json:"cache_size"`
	CacheMemory      int64         `json:"cache_memory"`
	MaxCacheSize     int           `json:"max_cache_size"`
	HitCount         int64         `json:"hit_count"`
	MissCount        int64         `json:"miss_count"`
	HitRatio         float64       `json:"hit_ratio"`
	CacheTTL         time.Duration `json:"cache_ttl"`
	CacheEnabled     bool          `json:"cache_enabled"`
	IsClosed         bool          `json:"is_closed"`
	MemoryEfficiency float64       `json:"memory_efficiency"`
	OperationCount   int64         `json:"operation_count"`
	ErrorCount       int64         `json:"error_count"`
}

Stats provides processor performance statistics

GetStats returns statistics about the default processor.

type StreamIterator struct {
	
}

StreamIterator provides memory-efficient iteration over large JSON arrays It processes elements one at a time without loading the entire array into memory

NewStreamIterator creates a stream iterator from a reader with default settings

func NewStreamIteratorWithConfig(reader io.Reader, config StreamIteratorConfig) *StreamIterator

NewStreamIteratorWithConfig creates a stream iterator with custom configuration PERFORMANCE: Configurable buffer size improves throughput for large JSON streams

Err returns any error encountered during iteration

func (si *StreamIterator) Index() int

Index returns the current index

Next advances to the next element Returns true if there is a next element, false otherwise

func (si *StreamIterator) Value() any

Value returns the current element

type StreamIteratorConfig struct {
	BufferSize int  
	ReadAhead  bool 
}

StreamIteratorConfig holds configuration options for StreamIterator

type StreamObjectIterator struct {
	
}

StreamObjectIterator provides memory-efficient iteration over JSON objects

NewStreamObjectIterator creates a stream object iterator from a reader

Err returns any error encountered

Key returns the current key

Next advances to the next key-value pair

Value returns the current value

type StreamingProcessor struct {
	
}

StreamingProcessor handles large JSON files efficiently

NewStreamingProcessor creates a streaming processor for large JSON

Close releases any resources held by the streaming processor. Note: This does NOT close the underlying reader - the caller owns it. Provided for API consistency and future extensibility. PERFORMANCE v2: Returns processor to pool for reuse

func (sp *StreamingProcessor) GetStats() StreamingStats

GetStats returns streaming statistics

StreamArray streams array elements one at a time This is memory-efficient for large arrays

StreamArrayChunked streams array elements in chunks for memory-efficient processing The chunkSize parameter controls how many elements are processed at once

StreamObject streams object key-value pairs

StreamObjectChunked streams object key-value pairs in chunks for memory-efficient processing The chunkSize parameter controls how many pairs are processed at once

type StreamingStats struct {
	BytesProcessed int64
	ItemsProcessed int64
	Depth          int
}

StreamingStats tracks streaming processing statistics

type StructureValidator struct {
	
}

StructureValidator handles JSON structure and nesting validation. RESPONSIBILITY: Validates JSON syntax, structure, and depth limits.

func NewStructureValidator(maxNestingDepth int64) *StructureValidator

NewStructureValidator creates a new structure validator.

ValidateNesting checks the nesting depth of the JSON.

ValidateStructure checks the JSON structure for validity.

type SyntaxError struct {
	Offset int64 
	
}

SyntaxError is a description of a JSON syntax error. Unmarshal will return a SyntaxError if the JSON can't be parsed.

type TextMarshaler interface {
	MarshalText() (text []byte, err error)
}

TextMarshaler is the interface implemented by an object that can marshal itself into a textual form.

MarshalText encodes the receiver into UTF-8-encoded text and returns the result.

type TextUnmarshaler interface {
	UnmarshalText(text []byte) error
}

TextUnmarshaler is the interface implemented by an object that can unmarshal a textual representation of itself.

UnmarshalText must be able to decode the form generated by MarshalText. UnmarshalText must copy the text if it wishes to retain the text after returning.

Token holds a value of one of these types:

Delim, for the four JSON delimiters [ ] { }
bool, for JSON booleans
float64, for JSON numbers
Number, for JSON numbers
string, for JSON string literals
nil, for JSON null

TypeEncoder handles encoding for specific reflect.Types. Register via Config.CustomTypeEncoders map.

Example:

type TimeEncoder struct{}
func (e *TimeEncoder) Encode(v reflect.Value) (string, error) {
    t := v.Interface().(time.Time)
    return `"` + t.Format(time.RFC3339) + `"`, nil
}

cfg := json.DefaultConfig()
cfg.CustomTypeEncoders = map[reflect.Type]json.TypeEncoder{
    reflect.TypeOf(time.Time{}): &TimeEncoder{},
}

UnmarshalTypeError describes a JSON value that was not appropriate for a value of a specific Go type.

type Unmarshaler interface {
	UnmarshalJSON([]byte) error
}

Unmarshaler is the interface implemented by types that can unmarshal a JSON description of themselves. The input can be assumed to be a valid encoding of a JSON value. UnmarshalJSON must copy the JSON data if it wishes to retain the data after returning.

By convention, to approximate the behavior of Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte("null")) as a no-op.

UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.

UnsupportedValueError is returned by Marshal when attempting to encode an unsupported value.

type ValidationChain []Validator

ValidationChain runs multiple validators in sequence. Stops at the first error encountered.

Validate executes all validators in order, stopping at first error.

type ValidationError struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}

ValidationError represents a schema validation error

ValidateSchema validates JSON data against a schema

type Validator interface {
	
	
	Validate(jsonStr string) error
}

Validator validates JSON input before processing. Implement this interface to add custom validation logic.

Example:

type SizeValidator struct { MaxSize int64 }
func (v *SizeValidator) Validate(jsonStr string) error {
    if int64(len(jsonStr)) > v.MaxSize {
        return fmt.Errorf("JSON exceeds max size: %d", v.MaxSize)
    }
    return nil
}

type WarmupResult struct {
	TotalPaths  int      `json:"total_paths"`
	Successful  int      `json:"successful"`
	Failed      int      `json:"failed"`
	SuccessRate float64  `json:"success_rate"`
	FailedPaths []string `json:"failed_paths,omitempty"`
}

WarmupResult represents the result of a cache warmup operation

WarmupCache pre-warms the cache for frequently accessed paths. This can improve performance for subsequent operations on the same JSON.