Package-Level Iteration Functions

Iteration functions that can be called directly without creating a Processor instance. They correspond one-to-one with the Processor iteration methods (dual-layer design).

Foreach

Signature: func Foreach(jsonStr string, fn func(key any, item *IterableValue), cfg ...Config)

Iterates over a JSON array or object.

json.Foreach(data, func(key any, item *json.IterableValue) {
    fmt.Printf("Key: %v, Value: %v\n", key, item.GetData())
})

When iterating an array: key is the index (int) When iterating an object: key is the key name (string)

ForeachWithPath

Signature: func ForeachWithPath(jsonStr, path string, fn func(key any, item *IterableValue), cfg ...Config) error

Iterates by path, returns an error.

err := json.ForeachWithPath(data, "items", func(key any, item *json.IterableValue) {
    fmt.Printf("[%v] %v\n", key, item.GetData())
})

Suitable for:

Iterating nested arrays
Iterating objects at a specified path

ForeachNested

Signature: func ForeachNested(jsonStr string, fn func(key any, item *IterableValue), cfg ...Config)

Recursively iterates through all nested levels.

json.ForeachNested(data, func(key any, item *json.IterableValue) {
    fmt.Printf("Key: %v, Value: %v\n", key, item.GetData())
})

Sample data:

json

{
  "user": {
    "name": "test",
    "profile": {
      "age": 25,
      "tags": ["a", "b"]
    }
  }
}

Output:

text

Key: user, Value: map[string]any{...}
Key: name, Value: test
Key: profile, Value: map[string]any{...}
Key: age, Value: 25
Key: tags, Value: []any{...}
...

ForeachReturn

Signature: func ForeachReturn(jsonStr string, fn func(key any, item *IterableValue), cfg ...Config) (string, error)

Iterates over JSON data, accessing each element via the callback, and returns the re-serialized JSON string. The callback can modify map/slice via GetData(), and modifications are reflected in the returned value.

result, err := json.ForeachReturn(data, func(key any, item *json.IterableValue) {
    // Access/modify element via item.GetData()
})

Suitable for scenarios that require chained operations after iteration.

ForeachWithError

Signature: func ForeachWithError(jsonStr, path string, fn func(key any, item *IterableValue) error, cfg ...Config) error

Iterates by path; the callback can return an error.

err := json.ForeachWithError(data, "items", func(key any, item *json.IterableValue) error {
    if item.GetInt("id") == 0 {
        return fmt.Errorf("invalid item at index %v", key)
    }
    return nil // continue iteration
})

ForeachNestedWithError

Signature: func ForeachNestedWithError(jsonStr string, fn func(key any, item *IterableValue) error, cfg ...Config) error

Recursively iterates through all nested levels; the callback can return an error.

err := json.ForeachNestedWithError(data, func(key any, item *json.IterableValue) error {
    fmt.Printf("Key: %v, Value: %v\n", key, item.GetData())
    return nil
})

ForeachWithPathAndIterator

Signature: func ForeachWithPathAndIterator(jsonStr, path string, fn func(key any, item *IterableValue, currentPath string) IteratorControl, cfg ...Config) error

Iterates by path and provides current path information. Uses IteratorControl to control the iteration flow.

err := json.ForeachWithPathAndIterator(data, "items", func(key any, item *json.IterableValue, currentPath string) json.IteratorControl {
    fmt.Printf("Path: %s, Key: %v\n", currentPath, key)
    if item.GetInt("id") == targetID {
        return json.IteratorBreak // stop iteration
    }
    return json.IteratorNormal // continue iteration
})

ForeachWithPathAndControl

Signature: func ForeachWithPathAndControl(jsonStr, path string, fn func(key any, value any) IteratorControl, cfg ...Config) error

Iterates over raw values by path, using IteratorControl to control the flow.

err := json.ForeachWithPathAndControl(data, "items", func(key any, value any) json.IteratorControl {
    fmt.Printf("Key: %v, Value: %v\n", key, value)
    return json.IteratorNormal
})

IterableValue

The IterableValue in the iteration callback provides convenient value access capabilities. See Iterator Types for the complete method definitions.

Method	Description
`GetData() any`	Get the current value
`Get(path string) any`	Get a value by path
`GetString(key string) string`	Get a string value
`GetInt(key string) int`	Get an integer value
`GetFloat64(key string) float64`	Get a float64 value
`GetBool(key string) bool`	Get a boolean value
`GetArray(key string) []any`	Get an array value
`GetObject(key string) map[string]any`	Get an object value
`Exists(key string) bool`	Check whether a field exists
`IsNull(key string) bool` / `IsNullData() bool`	Check whether the value is null
`IsEmpty(key string) bool` / `IsEmptyData() bool`	Check whether the value is empty
`Break() error`	Return an error signal to break iteration
`Release()`	Release resources back to the object pool

Method Comparison

Method	Path arg	Recursive	Return value	Error callback
`Foreach`	No	No	none	No
`ForeachWithPath`	Yes	No	error	No
`ForeachNested`	No	Yes	none	No
`ForeachReturn`	No	No	(string, error)	No
`ForeachWithError`	Yes	No	error	Yes
`ForeachNestedWithError`	No	Yes	error	Yes
`ForeachWithPathAndIterator`	Yes	No	error	IteratorControl
`ForeachWithPathAndControl`	Yes	No	error	IteratorControl

File Iteration Functions

The package provides functions that iterate directly from a file, suitable for processing large JSON files. They correspond to the Processor file iteration methods.

ForeachFile

Signature: func ForeachFile(filePath string, fn func(key any, item *IterableValue) error, cfg ...Config) error

Loads JSON from a file and iterates.

Parameters

Name	Type	Description
`filePath`	`string`	JSON file path
`fn`	`func(key any, item *IterableValue) error`	Iteration callback

err := json.ForeachFile("data.json", func(key any, item *json.IterableValue) error {
    fmt.Printf("[%v] %v\n", key, item.GetData())
    return nil // continue iteration
})

ForeachFileWithPath

Signature: func ForeachFileWithPath(filePath, path string, fn func(key any, item *IterableValue) error, cfg ...Config) error

Loads JSON from a file and iterates by path.

// Iterate only the users array
err := json.ForeachFileWithPath("data.json", ".users", func(key any, item *json.IterableValue) error {
    name := item.GetString("name")
    fmt.Printf("User: %s\n", name)
    return nil
})

ForeachFileChunked

Signature: func ForeachFileChunked(filePath string, chunkSize int, fn func(chunk []*IterableValue) error, cfg ...Config) error

Iterates a JSON array in a file in chunks, suitable for batch processing of large datasets.

Parameters

Name	Type	Description
`filePath`	`string`	JSON file path
`chunkSize`	`int`	Number of items per batch (defaults to 100 when ≤0)
`fn`	`func(chunk []*IterableValue) error`	Batch callback

// Process 100 records per batch
err := json.ForeachFileChunked("large_data.json", 100, func(chunk []*json.IterableValue) error {
    // Batch insert into database
    records := make([]Record, len(chunk))
    for i, item := range chunk {
        records[i] = Record{
            ID:   item.GetInt("id"),
            Name: item.GetString("name"),
        }
    }
    return db.BatchInsert(records)
})

Use Cases

Batch database inserts
Batched API calls
Memory-constrained large-file processing

ForeachFileNested

Signature: func ForeachFileNested(filePath string, fn func(key any, item *IterableValue) error, cfg ...Config) error

Loads JSON from a file and recursively iterates through all nested structures.

err := json.ForeachFileNested("config.json", func(key any, item *json.IterableValue) error {
    // Traverse every key-value pair at every level
    fmt.Printf("Path: %v, Type: %T\n", key, item.GetData())
    return nil
})

Sample data:

json

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "pool": {
      "min": 5,
      "max": 20
    }
  }
}

Output:

text

Path: database, Type: map[string]any
Path: host, Type: string
Path: port, Type: float64
Path: pool, Type: map[string]any
Path: min, Type: float64
Path: max, Type: float64

File Iteration Method Comparison

Method	Path arg	Recursive	Chunked	Suitable for
`ForeachFile`	No	No	No	Simple file traversal
`ForeachFileWithPath`	Yes	No	No	Targeted traversal
`ForeachFileChunked`	No	No	Yes	Batch processing, memory-constrained
`ForeachFileNested`	No	Yes	No	Deep traversal of all nodes

Iteration Control

IteratorControl Constants

ForeachWithPathAndControl and ForeachWithPathAndIterator control the iteration flow by returning IteratorControl (constant definitions in Iterator Types):

Constant	Description
`IteratorNormal`	Continue iteration normally
`IteratorContinue`	Skip the current item and continue iteration
`IteratorBreak`	Stop iteration

Breaking Iteration

Returning item.Break() from an error callback breaks iteration:

err := json.ForeachFile("data.json", func(key any, item *json.IterableValue) error {
    if item.GetInt("id") == targetID {
        // Found target, stop iteration
        return item.Break()
    }
    return nil // continue iteration
})

Error Handling

Returning any other error breaks iteration and returns that error:

err := json.ForeachFile("data.json", func(key any, item *json.IterableValue) error {
    if item.GetString("status") == "error" {
        return fmt.Errorf("found error record: %v", key)
    }
    return nil
})
if err != nil {
    log.Printf("iteration broken: %v", err)
}

Processor Iteration Methods - The corresponding Processor methods
Iterator Types - Iterator/IterableValue/Stream/Batch/Parallel type definitions
Query & Get - Get family of methods
Batch Operations - ProcessBatch batch processing
File I/O - LoadFromFile/SaveToFile
Large File Processing Guide - Streaming processing practices

Package-Level Iteration Functions ​

Foreach ​

ForeachWithPath ​

ForeachNested ​

ForeachReturn ​

ForeachWithError ​

ForeachNestedWithError ​

ForeachWithPathAndIterator ​

ForeachWithPathAndControl ​

IterableValue ​

Method Comparison ​

File Iteration Functions ​

ForeachFile ​

ForeachFileWithPath ​

ForeachFileChunked ​

ForeachFileNested ​

File Iteration Method Comparison ​

Iteration Control ​

IteratorControl Constants ​

Breaking Iteration ​

Error Handling ​

Related ​