Config

Config is used to customize the behavior of the Processor and all JSON operations.

Config Struct

type Config struct {
    // ===== Cache Settings =====
    MaxCacheSize int           `json:"max_cache_size"` // Maximum cache entries
    CacheTTL     time.Duration `json:"cache_ttl"`      // Cache expiration time
    EnableCache  bool          `json:"enable_cache"`   // Whether to enable cache
    CacheResults bool          `json:"cache_results"`  // Whether to cache operation results
    CacheSharedResults bool    `json:"cache_shared_results"` // Share cached results (skip defensive deep copy; caller must not mutate returned containers)

    // ===== Size Limits =====
    MaxJSONSize  int64 `json:"max_json_size"`  // Maximum JSON size (bytes)
    MaxPathDepth int   `json:"max_path_depth"` // Maximum path depth
    MaxBatchSize int   `json:"max_batch_size"` // Maximum batch operation count

    // ===== Security Limits =====
    MaxNestingDepthSecurity   int   `json:"max_nesting_depth"`           // Maximum nesting depth
    MaxSecurityValidationSize int64 `json:"max_security_validation_size"` // Maximum security validation size
    MaxObjectKeys             int   `json:"max_object_keys"`             // Maximum object key count
    MaxArrayElements          int   `json:"max_array_elements"`          // Maximum array element count
    FullSecurityScan          bool  `json:"full_security_scan"`          // Enable full security scan

    // ===== Concurrency =====
    MaxConcurrency    int `json:"max_concurrency"`    // Maximum concurrency
    ParallelThreshold int `json:"parallel_threshold"` // Parallel processing threshold

    // ===== Processing Options =====
    EnableValidation bool `json:"enable_validation"` // Enable validation
    StrictMode       bool `json:"strict_mode"`       // Strict mode
    CreatePaths      bool `json:"create_paths"`      // Auto-create paths
    CleanupNulls     bool `json:"cleanup_nulls"`     // Cleanup null values
    CompactArrays    bool `json:"compact_arrays"`    // Compact arrays
    ContinueOnError  bool `json:"continue_on_error"` // Continue on batch operation error

    // ===== Input/Output Options =====
    AllowComments    bool `json:"allow_comments"`     // Allow comments
    PreserveNumbers  bool `json:"preserve_numbers"`   // Preserve number precision
    ValidateInput    bool `json:"validate_input"`     // Validate input
    ValidateFilePath bool `json:"validate_file_path"` // Validate file paths
    SkipValidation   bool `json:"skip_validation"`    // Skip validation (trusted input)

    // ===== Encoding Options =====
    Pretty          bool            `json:"pretty"`           // Pretty-print output
    Indent          string          `json:"indent"`           // Indentation string
    Prefix          string          `json:"prefix"`           // Prefix
    EscapeHTML      bool            `json:"escape_html"`      // HTML escaping
    SortKeys        bool            `json:"sort_keys"`        // Sort keys
    ValidateUTF8    bool            `json:"validate_utf8"`    // UTF-8 validation
    MaxDepth        int             `json:"max_depth"`        // Maximum encoding depth
    DisallowUnknown bool            `json:"disallow_unknown"` // Disallow unknown fields
    FloatPrecision  int             `json:"float_precision"`  // Float precision (-1 for auto)
    FloatTruncate   bool            `json:"float_truncate"`   // Truncate floats
    DisableEscaping bool            `json:"disable_escaping"` // Disable escaping
    EscapeUnicode   bool            `json:"escape_unicode"`   // Unicode escaping
    EscapeSlash     bool            `json:"escape_slash"`     // Slash escaping
    EscapeNewlines  bool            `json:"escape_newlines"`  // Newline escaping
    EscapeTabs      bool            `json:"escape_tabs"`      // Tab escaping
    IncludeNulls    bool            `json:"include_nulls"`    // Include null values
    CustomEscapes   map[rune]string `json:"custom_escapes,omitempty"` // Custom escape mapping

    // ===== Observability =====
    EnableMetrics     bool `json:"enable_metrics"`      // Enable metrics collection
    EnableHealthCheck bool `json:"enable_health_check"` // Enable health check

    // ===== Large File Processing =====
    ChunkSize       int64 `json:"chunk_size"`       // Chunk size
    MaxMemory       int64 `json:"max_memory"`       // Maximum memory usage
    BufferSize      int   `json:"buffer_size"`      // Buffer size
    SamplingEnabled bool  `json:"sampling_enabled"` // Enable sampling
    SampleSize      int   `json:"sample_size"`      // Sample count

    // ===== JSONL Configuration =====
    JSONLBufferSize    int   `json:"jsonl_buffer_size"`     // JSONL buffer size
    JSONLMaxLineSize   int   `json:"jsonl_max_line_size"`   // JSONL maximum line size
    JSONLSkipEmpty     bool  `json:"jsonl_skip_empty"`      // Skip empty lines
    JSONLSkipComments  bool  `json:"jsonl_skip_comments"`   // Skip comment lines
    JSONLContinueOnErr bool  `json:"jsonl_continue_on_err"` // Continue on error
    JSONLWorkers       int   `json:"jsonl_workers"`         // JSONL parallel worker count
    JSONLChunkSize     int   `json:"jsonl_chunk_size"`      // JSONL chunk size
    JSONLMaxMemory     int64 `json:"jsonl_max_memory"`      // JSONL maximum memory

    // ===== Merge Options =====
    MergeMode MergeMode `json:"merge_mode"` // Merge strategy

    // ===== Extension Points (no JSON tag, not serialized) =====
    CustomEncoder               CustomEncoder                // Custom encoder
    CustomTypeEncoders          map[reflect.Type]TypeEncoder // Custom type encoders
    CustomValidators            []Validator                  // Custom validators
    AdditionalDangerousPatterns []DangerousPattern           // Additional dangerous patterns
    DisableDefaultPatterns      bool                         // Disable default warning-level patterns
    Hooks                       []Hook                       // Operation hooks
    CustomPathParser            PathParser                   // Custom path parser
}

CacheSharedResults contract

When CacheSharedResults is true, a cache-hit Get/GetFromParsed returns the cached value directly, skipping the defensive deep copy (faster, fewer allocations). The caller must not mutate the returned map[string]any/[]any, since doing so corrupts the shared cache and affects subsequent reads. Primitives (bool, float64, string, json.Number, nil) are immutable and always safe. The default false preserves the safe copy-on-read behavior; enable it only when callers treat results as read-only (for example, read-heavy workloads that Get the same large subtrees repeatedly).

Configuration Presets

DefaultConfig

Signature: func DefaultConfig() Config

Returns the default configuration, suitable for most scenarios.

cfg := json.DefaultConfig()
processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Default Values

Field	Value	Description
MaxJSONSize	100MB	JSON size limit
MaxNestingDepthSecurity	200	Nesting depth
MaxPathDepth	50	Path depth
MaxSecurityValidationSize	10MB	Security validation size limit
MaxObjectKeys	100000	Maximum object keys
MaxArrayElements	100000	Maximum array elements
MaxConcurrency	50	Concurrency limit
MaxBatchSize	2000	Batch operation count
CacheTTL	5 minutes	Cache expiration
MaxCacheSize	128	Maximum cache entries
EnableCache	true	Enable cache
CacheResults	true	Cache operation results
CacheSharedResults	false	Share cached results (read-only high-throughput)
EnableValidation	true	Enable validation
StrictMode	false	Non-strict mode
FullSecurityScan	false	Sampled security scan (not full)
ValidateInput	true	Validate input
ValidateFilePath	true	Validate file paths
CreatePaths	true	Auto-create paths
Pretty	false	No pretty-print output
EscapeHTML	true	HTML escaping
ValidateUTF8	true	UTF-8 validation
IncludeNulls	true	Include null
EscapeNewlines	true	Newline escaping
EscapeTabs	true	Tab escaping
FloatPrecision	-1	Auto precision
MaxDepth	100	Encoding depth
Indent	" "	Default indentation
ChunkSize	1MB	Chunk size
MaxMemory	100MB	Maximum memory
BufferSize	64KB	Buffer size
SamplingEnabled	true	Enable sampling
SampleSize	1000	Sample count
JSONLBufferSize	64KB	JSONL buffer size
JSONLMaxLineSize	1MB	JSONL maximum line size
JSONLSkipEmpty	true	Skip empty lines
JSONLSkipComments	false	Do not skip comments
JSONLContinueOnErr	false	Stop on error
JSONLWorkers	4	Parallel worker count
JSONLChunkSize	1000	JSONL chunk size
JSONLMaxMemory	100MB	JSONL maximum memory
MergeMode	MergeUnion	Union merge

SecurityConfig

Signature: func SecurityConfig() Config

Returns a security configuration, suitable for processing untrusted input.

// Recommended for:
// - Public APIs and web services
// - User-submitted data
// - External webhooks
// - Authentication endpoints
// - Financial data processing
cfg := json.SecurityConfig()
processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Security Configuration Features

Field	Value	Description
MaxNestingDepthSecurity	30	Conservative nesting depth
MaxSecurityValidationSize	10MB	Security validation size
MaxObjectKeys	5000	Conservative key limit
MaxArrayElements	5000	Conservative element limit
MaxJSONSize	10MB	Conservative size limit
MaxPathDepth	30	Conservative path depth
FullSecurityScan	true	Full security scan
StrictMode	true	Strict mode
EnableValidation	true	Enable validation
EnableCache	true	Enable cache
MaxCacheSize	256	Cache size
CacheTTL	3 minutes	Shorter TTL

PrettyConfig

Signature: func PrettyConfig() Config

Returns a pretty-print output configuration.

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

Configuration Methods

Clone

Signature: func (c *Config) Clone() *Config

Deep copies the configuration.

cfg := json.DefaultConfig()
cfgCopy := cfg.Clone()
cfgCopy.EnableValidation = true // Does not affect original config

Validate

Signature: func (c *Config) Validate() error

Validates the configuration and automatically corrects invalid values. This method modifies the Config in place, correcting invalid fields to within their valid ranges: values that are too small (≤0) are raised to the minimum, and values that exceed the upper bound are capped at the maximum.

cfg := json.DefaultConfig()
cfg.MaxJSONSize = -1 // Invalid value
if err := cfg.Validate(); err != nil {
    panic(err)
}
// MaxJSONSize will be corrected in place to minimum value

ValidateWithWarnings

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

Validates the configuration and returns a list of correction warnings.

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

ConfigWarning Type

ConfigWarning represents auto-correction information during configuration validation.

type ConfigWarning struct {
    Field    string // Corrected field name
    OldValue any    // Original value (may be nil for invalid values)
    NewValue any    // Corrected value
    Reason   string // Correction reason
}

SecurityLimits Type

SecurityLimits summarizes the security-related limit fields in Config.

type SecurityLimits struct {
    MaxNestingDepth           int   `json:"max_nesting_depth"`
    MaxSecurityValidationSize int64 `json:"max_security_validation_size"`
    MaxObjectKeys             int   `json:"max_object_keys"`
    MaxArrayElements          int   `json:"max_array_elements"`
    MaxJSONSize               int64 `json:"max_json_size"`
    MaxPathDepth              int   `json:"max_path_depth"`
}

AddHook

Signature: func (c *Config) AddHook(hook Hook)

Adds an operation hook.

cfg := json.DefaultConfig()
cfg.AddHook(json.LoggingHook(slog.Default()))

AddValidator

Signature: func (c *Config) AddValidator(validator Validator)

Adds a custom validator.

cfg := json.DefaultConfig()
cfg.AddValidator(&MyValidator{})

AddDangerousPattern

Signature: func (c *Config) AddDangerousPattern(pattern DangerousPattern)

Adds an additional security pattern.

cfg := json.DefaultConfig()
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "eval(",
    Name:    "eval-call",
    Level:   json.PatternLevelCritical,
})

Usage Examples

Basic Usage

cfg := json.DefaultConfig()
processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Security Configuration

// Process untrusted input
cfg := json.SecurityConfig()
processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Pretty Output

// Pretty-print JSON
result, err := json.EncodeWithConfig(data, json.PrettyConfig())

Custom Configuration

cfg := json.DefaultConfig()

// Security settings
cfg.MaxJSONSize = 10 * 1024 * 1024 // 10MB
cfg.MaxNestingDepthSecurity = 50
cfg.EnableValidation = true

// Hooks
cfg.Hooks = []json.Hook{json.LoggingHook(slog.Default())}

// Validators
cfg.CustomValidators = []json.Validator{&MyValidator{}}

processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Clone and Modify

// Create variants based on default config
base := json.DefaultConfig()

// Variant 1: Development config
devCfg := base.Clone()
devCfg.EnableMetrics = true

// Variant 2: Production config
prodCfg := base.Clone()
prodCfg.EnableValidation = true

Configuration Constants

const (
    // Size limits
    DefaultMaxJSONSize       = 100 * 1024 * 1024  // 100MB
    DefaultMaxNestingDepth   = 200
    DefaultMaxPathDepth      = 50
    DefaultMaxDepth          = 100                 // Default nesting depth for encoding/decoding (Config.MaxDepth)
    DefaultMaxConcurrency    = 50
    DefaultMaxBatchSize      = 2000
    DefaultMaxSecuritySize   = 10 * 1024 * 1024   // 10MB
    DefaultMaxObjectKeys     = 100000
    DefaultMaxArrayElements  = 100000
    DefaultParallelThreshold = 10

    // Cache
    DefaultCacheTTL = 5 * time.Minute
)

Internal Constants

Path validation length limits (maxPathLength) and other constants have been converted to internal implementations and are no longer exported as public APIs. Related default values are reflected in the Config struct field defaults.

Merge Modes

MergeMode controls the merge strategy for MergeJSON and MergeMany functions.

MergeUnion (Default)

Merges all keys/elements, using the override value for conflicts.

cfg := json.DefaultConfig()
cfg.MergeMode = json.MergeUnion
result, err := json.MergeJSON(
    `{"a": 1, "b": 2}`,
    `{"b": 3, "c": 4}`,
    cfg,
)
// Result: {"a": 1, "b": 3, "c": 4}

MergeIntersection

Only keeps keys that exist in both objects.

cfg := json.DefaultConfig()
cfg.MergeMode = json.MergeIntersection
result, err := json.MergeJSON(
    `{"a": 1, "b": 2}`,
    `{"b": 3, "c": 4}`,
    cfg,
)
// Result: {"b": 3}

MergeDifference

Only keeps keys that exist in the base object but not in the override object.

cfg := json.DefaultConfig()
cfg.MergeMode = json.MergeDifference
result, err := json.MergeJSON(
    `{"a": 1, "b": 2}`,
    `{"b": 3, "c": 4}`,
    cfg,
)
// Result: {"a": 1}

Security Recommendations

Configuration	Recommended Value	Description
MaxJSONSize	10-100MB	Adjust based on server memory
MaxNestingDepthSecurity	30-50	Prevent deep nesting attacks
MaxPathDepth	30-50	Limit path complexity
EnableValidation	true	Always enable
FullSecurityScan	true (untrusted input)	Full security scan

Processor - Processor methods
Constants & Errors - Configuration constants
Security Overview - Security best practices
Interface Definitions - Extension interfaces

Config ​

Config Struct ​

Configuration Presets ​

DefaultConfig ​

SecurityConfig ​

PrettyConfig ​

Configuration Methods ​

Clone ​

Validate ​

ValidateWithWarnings ​

ConfigWarning Type ​

SecurityLimits Type ​

AddHook ​

AddValidator ​

AddDangerousPattern ​

Usage Examples ​

Basic Usage ​

Security Configuration ​

Pretty Output ​

Custom Configuration ​

Clone and Modify ​

Configuration Constants ​

Merge Modes ​

MergeUnion (Default) ​

MergeIntersection ​

MergeDifference ​

Security Recommendations ​

Related ​