Technical Specification

Overview

Type System

Base Types

Format Types

Composite Types

Determinism Guarantees

• Reproducible: Same input + params = identical output (byte-for-byte)
• SHA-256 verified: Outputs can be checksummed across runs
• Cross-runtime: Identical behavior in Node.js, Deno, Bun
• Seeded randomness: ndjson.sample uses deterministic PRNG

# Verify determinism
echo '{"a":1}' | json-toolbox exec json.format | sha256sum
# Run 1000x - same hash every time

Privacy Model

• Zero network calls: All processing is local
• No telemetry: Analytics are opt-in only
• No persistence: Nothing stored beyond session
• Compliance mode: Zero-network build available

Architecture

Core Components

core/
  index.js      # Entry point
  registry.js   # Operator registry (shared browser/CLI)
  pipeline.js   # Pipeline execution engine
  types.js      # Type definitions
  errors.js     # Error types
  manifest.js   # Manifest parsing/validation

Operator Structure

{
  name: 'namespace.operation',
  description: 'What it does',
  category: 'format|transform|aggregate|streaming|query',
  input: { type: 'string', format: 'json' },
  output: { type: 'any' },
  params: {
    paramName: {
      type: 'string|number|boolean|array|object',
      default: value,
      description: 'What it controls'
    }
  },
  tags: ['keyword', 'tags'],
  examples: [{ input: '...', params: {...}, output: '...' }],
  execute: (input, params) => result
}

CLI Exit Codes

Browser/CLI Parity

All 65 operators behave identically in browser and CLI:

• Same operator registry (core/registry.js)
• Same execution engine (core/pipeline.js)
• Same type validation
• 60 parity tests verify identical output

Streaming Mode

CLI supports memory-efficient streaming for large NDJSON files:

json-toolbox exec transform.filter \
  --key status --operator eq --value active \
  --stream \
  --chunk 1000 \
  --progress < huge.ndjson