jpact

README

jpact

jpact is a small, fast JSON compaction library with selectable drivers. It is built for streaming workloads and provides both a clean top-level API and exposed driver packages when you want explicit control.

Why jpact

• Streaming compaction: process JSON without loading it all into memory.
• Strict JSON validation: rejects invalid JSON (e.g., trailing commas).
• Selectable drivers: internal compactor or a jsonv2-tokenizer-based driver.
• Low allocation: pooled, reusable buffers for steady-state workloads.

Installation

go get pkt.systems/jpact

Usage

Default (internal) driver

package main

import (
	"bytes"
	"strings"

	"pkt.systems/jpact"
)

func main() {
	input := `{"a": 1, "b": [true, false, null]}`
	var out bytes.Buffer

	c := jpact.New() // default internal driver
	if err := c.CompactWriter(&out, strings.NewReader(input), 0); err != nil {
		panic(err)
	}

	// out.String() == {"a":1,"b":[true,false,null]}
}

Select the jsonv2 driver

c := jpact.New(jpact.WithDriver(jpact.DriverJSONv2))

Package helpers

var out bytes.Buffer
_ = jpact.CompactWriter(&out, strings.NewReader(`{"a": 1}`), 0)

Note: package helpers always use the internal driver and do not modify any package-level state.

Driver packages (explicit)

import "pkt.systems/jpact/compactor"
import "pkt.systems/jpact/jsonv2compactor"

_ = compactor.CompactWriter(w, r, 0)
_ = jsonv2compactor.CompactWriter(w, r, 0)

API surface

• jpact.New(opts ...Option) Compactor
• jpact.WithDriver(Driver)
• jpact.CompactWriter(w, r, maxBytes)
• jpact.CompactToBuffer(r, maxBytes)

maxBytes <= 0 disables the limit. When enabled, the compactor returns an error once the input exceeds the limit.

Performance

Benchmarks (Go 1.25.5, linux/amd64, 13th Gen Intel(R) Core(TM) i7-1355U) run with:

go test ./compactor -run '^$' -bench . -benchmem

Results (ns/op):

Small:
  encoding_json      302.2
  compactor          391.4
  jsonv2compactor    370.5

Medium:
  encoding_json      59,340
  compactor          46,300
  jsonv2compactor    36,695

Large:
  encoding_json      3,487,766
  compactor          709,888
  jsonv2compactor    874,995

Allocations in these benchmarks are 0 allocs/op for all jpact drivers after pooling and benchmark harness adjustments. Real-world allocation counts will vary depending on your output writer and workload.

Fuzzing

Fuzzers are wired for both drivers and can be run independently:

go test ./compactor -run Fuzz -fuzz=Fuzz -fuzztime=30s
go test ./jsonv2compactor -run Fuzz -fuzz=Fuzz -fuzztime=30s

These were last run on 2025-12-23 and completed successfully.

Behavior notes

• Strict JSON validation (no trailing commas).
• Invalid UTF-8 within strings is allowed to match encoding/json behavior.
• Compactors are stateless and safe for concurrent use.

License

See LICENSE.

Documentation

Overview

Package jpact provides JSON compaction with selectable drivers.

It exposes a small Compactor interface for streaming JSON compaction and convenience helpers that default to the internal driver.

Usage:

c := jpact.New()
if err := c.CompactWriter(w, r, 0); err != nil {
	// handle error
}

// Choose the jsonv2 driver.
c = jpact.New(jpact.WithDriver(jpact.DriverJSONv2))

The maxBytes parameter limits the number of bytes read from the input stream; values <= 0 disable the limit.

The package-level helpers (CompactWriter/CompactToBuffer) are always routed to the internal driver and do not mutate any package-level state.

Example

input := `{"a": 1, "b": [true, false, null]}`
var out bytes.Buffer

compactor := New()
_ = compactor.CompactWriter(&out, strings.NewReader(input), 0)

Example (PackageHelpers)

input := `{"a": 1}`
var out bytes.Buffer

_ = CompactWriter(&out, strings.NewReader(input), 0)

Example (WithDriver)

input := `{"a": 1}`
var out bytes.Buffer

compactor := New(WithDriver(DriverJSONv2))
_ = compactor.CompactWriter(&out, strings.NewReader(input), 0)

Index

• func CompactToBuffer(r io.Reader, maxBytes int64) ([]byte, error)
• func CompactWriter(w io.Writer, r io.Reader, maxBytes int64) error
• type Compactor
  • func New(opts ...Option) Compactor
• type Driver
• type Option
  • func WithDriver(driver Driver) Option

Examples

• Package
• Package (PackageHelpers)
• Package (WithDriver)

Functions

func CompactToBuffer

func CompactToBuffer(r io.Reader, maxBytes int64) ([]byte, error)

CompactToBuffer compacts JSON into memory using the default internal driver.

func CompactWriter

func CompactWriter(w io.Writer, r io.Reader, maxBytes int64) error

CompactWriter compacts JSON using the default internal driver.

Types

type Compactor

type Compactor interface {
	CompactWriter(w io.Writer, r io.Reader, maxBytes int64) error
	CompactToBuffer(r io.Reader, maxBytes int64) ([]byte, error)
}

Compactor compacts JSON streams.

func New

func New(opts ...Option) Compactor

New returns a Compactor. The default driver is DriverInternal.

type Driver

type Driver string

Driver selects the compaction implementation.

const (
	// DriverInternal selects the internal compactor.
	DriverInternal Driver = "internal"
	// DriverJSONv2 selects the jsonv2 compactor.
	DriverJSONv2 Driver = "jsonv2"
)

type Option

type Option func(*options)

Option configures the jpact compactor.

func WithDriver

func WithDriver(driver Driver) Option

WithDriver selects a compaction driver.