Skip to content

rnb3ds/json

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

75 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

cybergodev/json

Go Version GoDoc MIT License Thread Safe Security Zero Deps

A high-performance, feature-rich Go JSON processing library with 100% encoding/json compatibility. Powerful path syntax, type safety, streaming processing, production-grade performance.

中文文档


Why cybergodev/json

Feature encoding/json cybergodev/json
Path-based access ❌ Manual unmarshal json.Get(data, "users[0].name")
Index value items[-1] gets last element
Flatten nested arrays users{flat:tags}
Type-safe defaults GetStringOr(data, "path", "default")
Streaming large files ✅ Built-in streaming processors
Schema validation ✅ JSON Schema validation
Memory pooling sync.Pool for hot paths
Caching ✅ Smart path cache with TTL
100% Compatibility ✅ Drop-in replacement

Features

  • 100% Compatible - Drop-in replacement for encoding/json, zero learning curve
  • Powerful Paths - Intuitive syntax: users[0].name, items[-1], data{flat:tags}
  • High Performance - Smart caching, memory pooling, optimized hot paths
  • Type Safe - Generics support with GetTyped[T] and GetTypedOr[T]
  • Feature Rich - Batch operations, streaming, file I/O, schema validation, deep merge
  • Production Ready - Thread-safe, comprehensive error handling, security hardened

Installation

go get github.com/cybergodev/json

Requirements: Go 1.24 or later


Quick Start

package main

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

func main() {
    data := `{
        "user": {
            "name": "Alice",
            "age": 28,
            "tags": ["premium", "verified"]
        }
    }`

    // Simple field access
    name, _ := json.GetString(data, "user.name")
    fmt.Println(name) // "Alice"

    // Type-safe retrieval
    age, _ := json.GetInt(data, "user.age")
    fmt.Println(age) // 28

    // Negative indexing (last element)
    lastTag, _ := json.Get(data, "user.tags[-1]")
    fmt.Println(lastTag) // "verified"

    // Modify data
    updated, _ := json.Set(data, "user.age", 29)
    newAge, _ := json.GetInt(updated, "user.age")
    fmt.Println(newAge) // 29

    // 100% encoding/json compatible
    bytes, _ := json.Marshal(map[string]any{"status": "ok"})
    fmt.Println(string(bytes)) // {"status":"ok"}
}

Path Syntax Reference

Syntax Description Example
.property Access property user.name → "Alice"
[n] Array index items[0] → first element
[-n] Negative index (from end) items[-1] → last element
[start:end] Array slice items[1:3] → elements 1-2
[start:end:step] Slice with step items[::2] → every other element
[+] Append to array items[+] → append position
{field} Extract field from all elements users{name} → ["Alice", "Bob"]
{flat:field} Flatten nested arrays users{flat:tags} → merge all tags

Core API

Data Retrieval

// Basic getters - return (value, error)
json.Get(data, "user.name")            // (any, error)
json.GetString(data, "user.name")      // (string, error)
json.GetInt(data, "user.age")          // (int, error)
json.GetFloat(data, "user.score")      // (float64, error)
json.GetBool(data, "user.active")      // (bool, error)
json.GetArray(data, "user.tags")       // ([]any, error)
json.GetObject(data, "user.profile")   // (map[string]any, error)

// Type-safe generic retrieval
json.GetTyped[string](data, "user.name")
json.GetTyped[[]int](data, "numbers")
json.GetTyped[User](data, "user")      // custom struct

// With defaults (no error when path doesn't exist)
json.GetStringOr(data, "user.name", "Anonymous")
json.GetIntOr(data, "user.age", 0)
json.GetBoolOr(data, "user.active", false)
json.GetFloatOr(data, "user.score", 0.0)
json.GetTypedOr[[]any](data, "user.tags", []any{})

// Batch retrieval
results, err := json.GetMultiple(data, []string{"user.name", "user.age"})

Data Modification

// Basic set - returns modified JSON on success, original data on failure
result, err := json.Set(data, "user.name", "Bob")

// Auto-create paths with config
cfg := json.DefaultConfig()
cfg.CreatePaths = true
result, err := json.Set(data, "user.profile.level", "gold", cfg)

// Append to array
result, _ := json.Set(data, "user.tags[+]", "new-tag")

// Batch set
result, _ := json.SetMultiple(data, map[string]any{
    "user.name": "Bob",
    "user.age":  30,
})

// Delete
result, err := json.Delete(data, "user.temp")

Encoding & Formatting

// Standard encoding (100% compatible)
bytes, _ := json.Marshal(data)
json.Unmarshal(bytes, &target)
bytes, _ := json.MarshalIndent(data, "", "  ")

// Quick formatting
pretty, _    := json.Prettify(jsonStr)      // pretty print
compact, _   := json.CompactString(jsonStr) // minify
json.Print(data)        // compact to stdout
json.PrintPretty(data)  // pretty to stdout

// Encoding with config
cfg := json.DefaultConfig()
cfg.Pretty = true
cfg.SortKeys = true
result, _ := json.Encode(data, cfg)

// Preset configs
result, _ := json.Encode(data, json.PrettyConfig())

File Operations

// Load and save
jsonStr, _ := json.LoadFromFile("data.json")
json.SaveToFile("output.json", data, json.PrettyConfig())

// Struct/Map serialization
json.MarshalToFile("user.json", user)
json.UnmarshalFromFile("user.json", &user)

Type Conversion Utilities

// Safe type conversion
intVal, ok   := json.ConvertToInt(value)
floatVal, ok := json.ConvertToFloat64(value)
boolVal, ok  := json.ConvertToBool(value)
strVal       := json.ConvertToString(value)

// JSON utilities
equal, _    := json.CompareJSON(json1, json2)
merged, _   := json.MergeJSON(json1, json2)                       // union (default)
merged, _   := json.MergeJSON(json1, json2, json.MergeIntersection) // intersection
deepCopy, _ := json.DeepCopy(data)

Configuration

Custom Configuration

cfg := json.Config{
    EnableCache:      true,
    MaxCacheSize:     256,
    CacheTTL:         5 * time.Minute,
    MaxJSONSize:      100 * 1024 * 1024, // 100MB
    MaxConcurrency:   50,
    EnableValidation: true,
    CreatePaths:      true,  // auto-create paths on Set
    CleanupNulls:     true,  // cleanup nulls after Delete
}

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

// Use processor methods
result, _ := processor.Get(jsonStr, "user.name")
stats := processor.GetStats()
health := processor.GetHealthStatus()
processor.ClearCache()

Preset Configurations

cfg := json.DefaultConfig()   // balanced defaults
cfg := json.SecurityConfig()  // for untrusted input
cfg := json.PrettyConfig()    // for pretty output

Advanced Features

Data Iteration

// Basic iteration
json.Foreach(data, func(key any, item *json.IterableValue) {
    name := item.GetString("name")
    fmt.Printf("Key: %v, Name: %s\n", key, name)
})

// With path and control flow
json.ForeachWithPathAndControl(data, "users", func(key any, value any) json.IteratorControl {
    if shouldStop {
        return json.IteratorBreak  // early termination
    }
    return json.IteratorContinue
})

Batch Operations

data := `{"user": {"name": "Alice", "age": 28, "temp": "value"}}`

operations := []json.BatchOperation{
    {Type: "get", JSONStr: data, Path: "user.name"},
    {Type: "set", JSONStr: data, Path: "user.age", Value: 25},
    {Type: "delete", JSONStr: data, Path: "user.temp"},
}
results, err := json.ProcessBatch(operations)

Streaming (Large Files)

import "strings"

// Stream array elements
reader := strings.NewReader(largeJSONArray)
processor := json.NewStreamingProcessor(reader, 64*1024)
err := processor.StreamArray(func(index int, item any) bool {
    // process each element
    return true // continue
})

// JSONL/NDJSON processing
jsonlProcessor := json.NewNDJSONProcessor(64 * 1024)
err := jsonlProcessor.ProcessReader(reader, func(lineNum int, obj map[string]any) error {
    // process each line
    return nil
})

Schema Validation

schema := &json.Schema{
    Type:     "object",
    Required: []string{"name", "email"},
    Properties: map[string]*json.Schema{
        "name":  {Type: "string", MinLength: 1, MaxLength: 100},
        "email": {Type: "string", Format: "email"},
        "age":   {Type: "integer", Minimum: 0, Maximum: 150},
    },
}

errors, err := json.ValidateSchema(jsonStr, schema)

Common Use Cases

API Response Processing

apiResponse := `{
    "status": "success",
    "data": {
        "users": [{"id": 1, "name": "Alice", "permissions": ["read", "write"]}],
        "pagination": {"total": 25, "page": 1}
    }
}`

// Quick extraction
status, _ := json.GetString(apiResponse, "status")
total, _ := json.GetInt(apiResponse, "data.pagination.total")

// Extract all user names
names, _ := json.Get(apiResponse, "data.users{name}")
// Result: ["Alice"]

// Flatten all permissions
permissions, _ := json.Get(apiResponse, "data.users{flat:permissions}")
// Result: ["read", "write"]

Configuration Management

config := `{
    "database": {"host": "localhost", "port": 5432},
    "cache": {"enabled": true}
}`

// Type-safe with defaults
dbHost := json.GetStringOr(config, "database.host", "localhost")
dbPort := json.GetIntOr(config, "database.port", 5432)
cacheEnabled := json.GetBoolOr(config, "cache.enabled", false)

// Dynamic update
updated, _ := json.SetMultiple(config, map[string]any{
    "database.host": "prod-db.example.com",
    "cache.ttl":     3600,
})

Performance Monitoring

// Package-level monitoring
stats := json.GetStats()
fmt.Printf("Operations: %d\n", stats.OperationCount)
fmt.Printf("Cache Hit Rate: %.2f%%\n", stats.HitRatio*100)

health := json.GetHealthStatus()
fmt.Printf("Health Status: %v\n", health.Healthy)

// Cache management
json.ClearCache()

// Cache warmup
paths := []string{"user.name", "user.age", "user.profile"}
result, _ := json.WarmupCache(jsonStr, paths)

Migrating from encoding/json

Simply change the import:

// Before
import "encoding/json"

// After
import "github.com/cybergodev/json"

All standard functions are fully compatible:

  • json.Marshal() / json.Unmarshal()
  • json.MarshalIndent()
  • json.Valid()
  • json.Compact() / json.Indent() / json.HTMLEscape()

Security Configuration

// For handling untrusted JSON input
secureConfig := json.SecurityConfig()
// Features:
// - Full security scanning enabled
// - Conservative size limits (max 10MB)
// - Strict mode validation
// - Prototype pollution protection
// - Path traversal protection

processor, _ := json.New(secureConfig)
defer processor.Close()

Example Code

File Description
1_basic_usage.go Core operations
2_advanced_features.go Complex paths, nested extraction
3_production_ready.go Thread-safe patterns
4_error_handling.go Error handling patterns
5_encoding_options.go Encoding configuration
6_validation.go Schema validation
7_type_conversion.go Type conversion
8_helper_functions.go Helper utilities
9_iterator_functions.go Iteration patterns
10_file_operations.go File I/O
11_with_defaults.go Default value handling
12_advanced_delete.go Delete operations
13_streaming_ndjson.go Streaming & JSONL
14_batch_operations.go Batch processing
# Run examples
go run -tags=example examples/1_basic_usage.go

Documentation


License

MIT License - See LICENSE file for details.


If this project helps you, please give it a star! ⭐

About

This JSON library is a high-performance, thread-safe Go library for JSON processing, offering rich JSON manipulation capabilities including parsing, querying, modifying, validating, and formatting. Designed for elegant and rapid development, it features advanced caching mechanisms, performance optimizations, and modern Go development practices.

Resources

License

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Go 100.0%