Helper Functions

The json package provides a rich set of helper functions for JSON comparison, cache management, and utility processing.

JSON Comparison Functions

CompareJSON

Signature: func CompareJSON(json1, json2 string, cfg ...Config) (bool, error)

Compares two JSON strings for equality. Handles numeric precision differences and key order differences.

Without cfg, the behavior is identical to the historical implementation (no security validation; both sides are marshalled with encoding/json). When cfg is passed, security validation (size/depth/dangerous-mode limits) is applied to both inputs, and a symmetric comparison is performed using the configured encoding.

// Different key order but same content
equal, _ := json.CompareJSON(`{"a":1,"b":2}`, `{"b":2,"a":1}`)
fmt.Println(equal) // true

// Different numeric precision but same value
equal, _ = json.CompareJSON(`{"num":1}`, `{"num":1.0}`)
fmt.Println(equal) // true

// Different content
equal, _ = json.CompareJSON(`{"a":1}`, `{"a":2}`)
fmt.Println(equal) // false

// With configuration (applies security validation and encoding control)
equal, err = json.CompareJSON(a, b, json.SecurityConfig())

Processor Equivalent

Processor.CompareJSON always performs security validation (per cfg or the processor's own configuration), unlike the package-level function's no-cfg path. See Processor Data Modification.

JSON Merge Functions

MergeJSON

Signature: func MergeJSON(json1, json2 string, cfg ...Config) (string, error)

Merges two JSON objects, supports configuring merge mode via Config. See Modify Functions for details.

MergeMany

Signature: func MergeMany(jsons []string, cfg ...Config) (string, error)

Merges multiple JSON objects. See Modify Functions for details.

Cache and Statistics

ClearCache (Package Function)

Signature: func ClearCache()

Clears the internal cache of the global processor.

json.ClearCache()

GetStats (Package Function)

Signature: func GetStats() Stats

Gets the statistics of the global processor.

stats := json.GetStats()
fmt.Printf("Cache hit ratio: %.2f%%\n", stats.HitRatio * 100)
fmt.Printf("Cache size: %d\n", stats.CacheSize)

GetHealthStatus (Package Function)

Signature: func GetHealthStatus() HealthStatus

Gets the health status of the global processor.

status := json.GetHealthStatus()
if status.Healthy {
    fmt.Println("Processor is healthy")
}

Processor.ClearCache

Signature: func (p *Processor) ClearCache()

Clears the processor's internal cache.

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

p.ClearCache()

Processor.GetStats

Signature: func (p *Processor) GetStats() Stats

Gets the processor's statistics.

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

stats := p.GetStats()
fmt.Printf("Cache hit ratio: %.2f%%\n", stats.HitRatio * 100)
fmt.Printf("Cache size: %d\n", stats.CacheSize)

Processor.GetHealthStatus

Signature: func (p *Processor) GetHealthStatus() HealthStatus

Gets the processor's health status.

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

status := p.GetHealthStatus()
if status.Healthy {
    fmt.Println("Processor is healthy")
}

WarmupCache

Signature: func WarmupCache(jsonStr string, paths []string, cfg ...Config) (*WarmupResult, error)

Warms up the cache to improve subsequent operation performance.

data := `{"user": {"name": "Alice", "email": "[email protected]"}, "items": [{"id": 1}]}`
paths := []string{"user.name", "user.email", "items[*].id"}
result, err := json.WarmupCache(data, paths)
if err != nil {
    panic(err)
}
fmt.Printf("Successfully warmed up %d paths\n", result.Successful)

Global Processor Management

The global processor is used by all package-level functions (such as Get, GetString, etc.).

SetGlobalProcessor

Signature: func SetGlobalProcessor(processor *Processor)

Sets a custom global processor.

cfg := json.SecurityConfig()
p, err := json.New(cfg)
if err != nil {
    panic(err)
}

json.SetGlobalProcessor(p)

// All subsequent package-level functions use this processor
val := json.GetString(data, "user.name")

ShutdownGlobalProcessor

Signature: func ShutdownGlobalProcessor()

Shuts down the global processor and releases resources.

package main

import (
    "github.com/cybergodev/json"
)

func main() {
    cfg := json.DefaultConfig()
    p, err := json.New(cfg)
    if err != nil {
        panic(err)
    }
    json.SetGlobalProcessor(p)

    defer json.ShutdownGlobalProcessor()

    // Application logic...
}

Output Functions

API Change Notice

Print, PrintPretty, PrintE, PrintPrettyE have been removed from the library and are no longer available. Please use EncodeWithConfig, EncodePretty, or Prettify with fmt.Println instead (Encode is deprecated). See Print Functions for details.

Buffer Compatible Functions

Note

The following functions are fully compatible with the encoding/json standard library while supporting additional configuration via the cfg parameter.

Compact

Signature: func Compact(dst *bytes.Buffer, src []byte, cfg ...Config) error

Writes compressed JSON to a Buffer. 100% compatible with encoding/json.Compact.

var buf bytes.Buffer
err := json.Compact(&buf, []byte(`{"name": "test"}`))

Indent

Signature: func Indent(dst *bytes.Buffer, src []byte, prefix, indent string, cfg ...Config) error

Writes formatted JSON to a Buffer. 100% compatible with encoding/json.Indent.

var buf bytes.Buffer
err := json.Indent(&buf, []byte(`{"name":"test"}`), "", "  ")

HTMLEscape

Signature: func HTMLEscape(dst *bytes.Buffer, src []byte, cfg ...Config)

Writes HTML-escaped JSON to a Buffer. 100% compatible with encoding/json.HTMLEscape.

var buf bytes.Buffer
json.HTMLEscape(&buf, []byte(`{"html":"<script>alert(1)</script>"}`))

Security Pattern Functions

Config.AddDangerousPattern

cfg := json.DefaultConfig()
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "malicious_keyword",
    Name:    "Custom malicious keyword",
    Level:   json.PatternLevelCritical,
})
p, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer p.Close()

You can also set the AdditionalDangerousPatterns field after creating a Config:

cfg := json.DefaultConfig()
cfg.AdditionalDangerousPatterns = []json.DangerousPattern{
    {Pattern: "malicious_keyword", Name: "Custom malicious keyword", Level: json.PatternLevelCritical},
}
p, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer p.Close()

DangerousPattern Struct

Field	Type	Description
`Pattern`	`string`	Substring to detect
`Name`	`string`	Human-readable risk description
`Level`	`PatternLevel`	Severity level

PatternLevel Levels

Level	Description
`PatternLevelCritical`	Always blocks the operation
`PatternLevelWarning`	Blocks in strict mode, logs warning in permissive mode
`PatternLevelInfo`	Only logs, never blocks

Error Handling Functions

SafeError

Signature: func SafeError(err error) string

Returns a client-safe error message without internal details. Suitable for use in API responses.

val, err := json.Get(data, "user.name")
if err != nil {
    // Returns a safe error message (without sensitive info like paths, internal state)
    fmt.Println(json.SafeError(err))
}

RedactedPath

Signature: func RedactedPath(path string) string

Returns a redacted path for safe logging. Hides sensitive parts of the path.

path := "users[0].ssn"
fmt.Println(json.RedactedPath(path)) // Safe path representation

AccessResult Type Conversion Methods

AccessResult is the return type of Processor.SafeGet() and the package-level SafeGet(), providing type-safe conversion methods.

AccessResult.AsString

Signature: func (r AccessResult) AsString() (string, error)

Safely converts to string type. Only succeeds when the value itself is a string.

result := json.SafeGet(data, "user.name")
name, err := result.AsString()
if err != nil {
    return
}
fmt.Println(name)

AccessResult.AsStringConverted

Signature: func (r AccessResult) AsStringConverted() (string, error)

Converts any value to a string (using fmt.Sprintf formatting).

result := json.SafeGet(data, "user.age")
ageStr, err := result.AsStringConverted()
// "30" (string format)

AccessResult.AsInt

Signature: func (r AccessResult) AsInt() (int, error)

Safely converts to integer. Does not support bool to int conversion.

result := json.SafeGet(data, "user.age")
age, err := result.AsInt()

AccessResult.AsFloat64

Signature: func (r AccessResult) AsFloat64() (float64, error)

Safely converts to float64. Does not support bool to float64 conversion.

result := json.SafeGet(data, "item.price")
price, err := result.AsFloat64()

AccessResult.AsBool

Signature: func (r AccessResult) AsBool() (bool, error)

Safely converts to boolean. Only supports bool and string types.

result := json.SafeGet(data, "feature.enabled")
enabled, err := result.AsBool()

Query & Get Functions - Get, GetString and other query operations
Modify Functions - Set, Delete and other modification operations
Type Definitions - AccessResult and other types
Configuration Options - Config configuration details

Helper Functions ​

JSON Comparison Functions ​

CompareJSON ​

JSON Merge Functions ​

MergeJSON ​

MergeMany ​

Cache and Statistics ​

ClearCache (Package Function) ​

GetStats (Package Function) ​

GetHealthStatus (Package Function) ​

Processor.ClearCache ​

Processor.GetStats ​

Processor.GetHealthStatus ​

WarmupCache ​

Global Processor Management ​

SetGlobalProcessor ​

ShutdownGlobalProcessor ​

Output Functions ​

Buffer Compatible Functions ​

Compact ​

Indent ​

HTMLEscape ​

Security Pattern Functions ​

Config.AddDangerousPattern ​

Error Handling Functions ​

SafeError ​

RedactedPath ​

AccessResult Type Conversion Methods ​

AccessResult.AsString ​

AccessResult.AsStringConverted ​

AccessResult.AsInt ​

AccessResult.AsFloat64 ​

AccessResult.AsBool ​

Related ​