compact

package
v0.5.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 9, 2026 License: MIT Imports: 6 Imported by: 0

README

Compact Codec for JSON Patch Operations

The compact codec provides a highly optimized array-based encoding format for JSON Patch operations, achieving 35.9% space savings compared to standard JSON format while maintaining full compatibility with all operation types.

🎯 Key Benefits: Space efficiency, performance optimization, flexible opcode formats, perfect round-trip compatibility.

Format Comparison & Space Savings

Standard Struct API:
{Op: "add", Path: "/foo/bar", Value: 123}
Standard JSON format:
{"op": "add", "path": "/foo/bar", "value": 123}
Compact format (numeric opcodes):
[0, "/foo/bar", 123]
Compact format (string opcodes):
["add", "/foo/bar", 123]

Space Savings: 35.9% reduction in data size with numeric opcodes!

Usage

Basic Operations with Struct API
package main

import (
    "fmt"
    "github.com/kaptinlin/jsonpatch"
    "github.com/kaptinlin/jsonpatch/codec/compact"
)

func main() {
    // Create operations using struct API
    operations := []jsonpatch.Operation{
        {Op: "add", Path: "/foo", Value: "bar"},
        {Op: "replace", Path: "/baz", Value: 42},
        {Op: "inc", Path: "/counter", Inc: 5},
        {Op: "str_ins", Path: "/text", Pos: 0, Str: "Hello "},
    }
    
    // Encode to compact format (numeric opcodes for max space savings)
    encoder := compact.NewEncoder(compact.WithStringOpcode(false))
    encoded, err := encoder.EncodeJSON(operations)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Compact JSON: %s\n", encoded)
    // Output: [[0,"/foo","bar"],[2,"/baz",42],[9,"/counter",5],[6,"/text",0,"Hello "]]
    
    // Decode back to operations
    decoder := compact.NewDecoder()
    decoded, err := decoder.DecodeJSON(encoded)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Decoded: %d operations\n", len(decoded))
    // Space savings: ~35.9% compared to standard JSON format
}
String Opcodes
// Use string opcodes instead of numeric ones
encoder := compact.NewEncoder(compact.WithStringOpcode(true))
encoded, err := encoder.Encode(ops)
// Result: [["add" "/foo" "bar"] ["replace" "/baz" 42]]
JSON Marshaling
// Encode to JSON bytes
jsonData, err := compact.EncodeJSON(ops)
if err != nil {
    panic(err)
}

// Decode from JSON bytes
decoded, err := compact.DecodeJSON(jsonData)
if err != nil {
    panic(err)
}

Complete Operation Mapping (From Code Analysis)

Based on decode.go implementation, here are all supported operations:

Standard JSON Patch Operations (RFC 6902)
Operation Numeric Code String Code Compact Format Example
add 0 "add" [0, path, value] [0, "/foo", 123]
remove 1 "remove" [1, path] [1, "/foo"]
replace 2 "replace" [2, path, value] [2, "/foo", 456]
copy 3 "copy" [3, path, from] [3, "/bar", "/foo"]
move 4 "move" [4, path, from] [4, "/bar", "/foo"]
test 5 "test" [5, path, value] [5, "/foo", 123]
String Operations
Operation Numeric Code String Code Compact Format Example
str_ins 6 "str_ins" [6, path, pos, str] [6, "/text", 0, "Hi "]
str_del 7 "str_del" [7, path, pos, len] [7, "/text", 5, 3]
Extended Operations
Operation Numeric Code String Code Compact Format Example
flip 8 "flip" [8, path] [8, "/active"]
inc 9 "inc" [9, path, delta] [9, "/count", 5]
split 10 "split" [10, path, pos, props?] [10, "/obj", 2]
merge 11 "merge" [11, path, pos, props?] [11, "/obj", 0]
extend 12 "extend" [12, path, props, deleteNull?] [12, "/config", {...}]
JSON Predicate Operations
Operation Numeric Code String Code Compact Format Example
contains 30 "contains" [30, path, value, ignoreCase?] [30, "/text", "hello"]
defined 31 "defined" [31, path] [31, "/field"]
ends 32 "ends" [32, path, value, ignoreCase?] [32, "/text", ".com"]
in 33 "in" [33, path, values] [33, "/role", ["admin","user"]]
less 34 "less" [34, path, value] [34, "/age", 30]
matches 35 "matches" [35, path, pattern, ignoreCase?] [35, "/email", ".*@.*"]
more 36 "more" [36, path, value] [36, "/score", 100]
starts 37 "starts" [37, path, value, ignoreCase?] [37, "/text", "Hello"]
undefined 38 "undefined" [38, path] [38, "/optional"]
test_type 39 "test_type" [39, path, types] [39, "/data", ["string","number"]]
test_string 40 "test_string" [40, path, pos, str, not?] [40, "/text", 5, "test"]
test_string_len 41 "test_string_len" [41, path, len, not?] [41, "/text", 10]
type 42 "type" [42, path, type] [42, "/data", "string"]
Second-Order Predicates
Operation Numeric Code String Code Compact Format Example
and 43 "and" [43, path, ops[]] [43, "", [[31,"/a"],[42,"/b","string"]]]
not 44 "not" [44, path, ops[]] [44, "", [[31,"/field"]]]
or 45 "or" [45, path, ops[]] [45, "", [[31,"/a"],[31,"/b"]]]

API Reference

Encoder
type Encoder struct { ... }

// Create a new encoder
func NewEncoder(opts ...EncoderOption) *Encoder

// Encode a single operation
func (e *Encoder) Encode(op internal.Op) (CompactOp, error)

// Encode multiple operations
func (e *Encoder) EncodeSlice(ops []internal.Op) ([]CompactOp, error)
Decoder
type Decoder struct { ... }

// Create a new decoder
func NewDecoder(opts ...DecoderOption) *Decoder

// Decode a single compact operation
func (d *Decoder) Decode(compactOp CompactOp) (internal.Op, error)

// Decode multiple compact operations
func (d *Decoder) DecodeSlice(compactOps []CompactOp) ([]internal.Op, error)
Standalone Functions
// Encode operations using default options
func Encode(ops []internal.Op, opts ...EncoderOption) ([]CompactOp, error)

// Encode operations to JSON bytes
func EncodeJSON(ops []internal.Op, opts ...EncoderOption) ([]byte, error)

// Decode compact operations using default options
func Decode(compactOps []CompactOp, opts ...DecoderOption) ([]internal.Op, error)

// Decode compact operations from JSON bytes
func DecodeJSON(data []byte, opts ...DecoderOption) ([]internal.Op, error)
Options
// Use string opcodes instead of numeric codes
func WithStringOpcode(useString bool) EncoderOption

Features

  • Space Efficient: Significantly smaller than standard JSON format
  • Fast: Optimized encoding and decoding performance
  • Flexible: Supports both numeric and string opcodes
  • Compatible: Works with all existing operation types
  • Type Safe: Full Go type safety and error handling

Supported Operations

The compact codec now supports all JSON Patch operations with full encoding and decoding:

Standard JSON Patch (RFC 6902)

✅ add, remove, replace, move, copy, test

Extended Operations

✅ flip, inc, str_ins, str_del, split, merge, extend

JSON Predicate Operations

✅ defined, undefined, contains, starts, ends, matches, type, test_type, test_string, test_string_len, in, less, more

Second-Order Predicates (Composite Operations)

✅ and, or, not

Documentation

Overview

Package compact implements a compact array-based codec for JSON Patch operations. This codec uses arrays instead of objects to represent operations, significantly reducing the physical space required for encoding while maintaining readability.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrOpMinLength indicates compact operation must have at least opcode and path.
	ErrOpMinLength = errors.New("compact operation must have at least opcode and path")
	// ErrOpPathNotString indicates compact operation path must be a string.
	ErrOpPathNotString = errors.New("compact operation path must be a string")
)
View Source 
var (
	// ErrAddOpMissingValue indicates add operation is missing value.
	ErrAddOpMissingValue = errors.New("add operation requires value")
	// ErrReplaceOpMissingValue indicates replace operation is missing value.
	ErrReplaceOpMissingValue = errors.New("replace operation requires value")
	// ErrMoveOpMissingFrom indicates move operation is missing from path.
	ErrMoveOpMissingFrom = errors.New("move operation requires from path")
	// ErrMoveOpFromNotString indicates move operation from must be a string.
	ErrMoveOpFromNotString = errors.New("move operation from must be a string")
	// ErrCopyOpMissingFrom indicates copy operation is missing from path.
	ErrCopyOpMissingFrom = errors.New("copy operation requires from path")
	// ErrCopyOpFromNotString indicates copy operation from must be a string.
	ErrCopyOpFromNotString = errors.New("copy operation from must be a string")
	// ErrTestOpMissingValue indicates test operation is missing value.
	ErrTestOpMissingValue = errors.New("test operation requires value")
)
View Source 
var (
	// ErrIncOpMissingDelta indicates inc operation is missing delta.
	ErrIncOpMissingDelta = errors.New("inc operation requires delta")
	// ErrIncOpDeltaNotNumber indicates inc operation delta must be a number.
	ErrIncOpDeltaNotNumber = errors.New("inc operation delta must be a number")
	// ErrStrInsOpMissingFields indicates str_ins operation is missing pos and str.
	ErrStrInsOpMissingFields = errors.New("str_ins operation requires pos and str")
	// ErrStrInsOpPosNotNumber indicates str_ins operation pos must be a number.
	ErrStrInsOpPosNotNumber = errors.New("str_ins operation pos must be a number")
	// ErrStrInsOpStrNotString indicates str_ins operation str must be a string.
	ErrStrInsOpStrNotString = errors.New("str_ins operation str must be a string")
	// ErrStrDelOpMissingFields indicates str_del operation is missing pos and len.
	ErrStrDelOpMissingFields = errors.New("str_del operation requires pos and len")
	// ErrStrDelOpPosNotNumber indicates str_del operation pos must be a number.
	ErrStrDelOpPosNotNumber = errors.New("str_del operation pos must be a number")
	// ErrStrDelOpLenNotNumber indicates str_del operation len must be a number.
	ErrStrDelOpLenNotNumber = errors.New("str_del operation len must be a number")
	// ErrSplitOpMissingPos indicates split operation is missing pos.
	ErrSplitOpMissingPos = errors.New("split operation requires pos")
	// ErrSplitOpPosNotNumber indicates split operation pos must be a number.
	ErrSplitOpPosNotNumber = errors.New("split operation pos must be a number")
	// ErrMergeOpMissingPos indicates merge operation is missing pos.
	ErrMergeOpMissingPos = errors.New("merge operation requires pos")
	// ErrMergeOpPosNotNumber indicates merge operation pos must be a number.
	ErrMergeOpPosNotNumber = errors.New("merge operation pos must be a number")
	// ErrExtendOpMissingProps indicates extend operation is missing props.
	ErrExtendOpMissingProps = errors.New("extend operation requires props")
	// ErrExtendOpPropsNotObject indicates extend operation props must be an object.
	ErrExtendOpPropsNotObject = errors.New("extend operation props must be an object")
)
View Source 
var (
	// ErrContainsOpMissingValue indicates contains operation is missing value.
	ErrContainsOpMissingValue = errors.New("contains operation requires value")
	// ErrContainsOpValueNotString indicates contains operation value must be a string.
	ErrContainsOpValueNotString = errors.New("contains operation value must be a string")
	// ErrStartsOpMissingValue indicates starts operation is missing value.
	ErrStartsOpMissingValue = errors.New("starts operation requires value")
	// ErrStartsOpValueNotString indicates starts operation value must be a string.
	ErrStartsOpValueNotString = errors.New("starts operation value must be a string")
	// ErrEndsOpMissingValue indicates ends operation is missing value.
	ErrEndsOpMissingValue = errors.New("ends operation requires value")
	// ErrEndsOpValueNotString indicates ends operation value must be a string.
	ErrEndsOpValueNotString = errors.New("ends operation value must be a string")
	// ErrTypeOpMissingType indicates type operation is missing type.
	ErrTypeOpMissingType = errors.New("type operation requires type")
	// ErrTypeOpTypeNotString indicates type operation type must be a string.
	ErrTypeOpTypeNotString = errors.New("type operation type must be a string")
	// ErrTestTypeOpMissingTypes indicates test_type operation is missing types.
	ErrTestTypeOpMissingTypes = errors.New("test_type operation requires types")
	// ErrTestTypeOpTypesNotArray indicates test_type operation types must be an array.
	ErrTestTypeOpTypesNotArray = errors.New("test_type operation types must be an array")
	// ErrTestStringOpMissingStr indicates test_string operation is missing str.
	ErrTestStringOpMissingStr = errors.New("test_string operation requires str")
	// ErrTestStringOpStrNotString indicates test_string operation str must be a string.
	ErrTestStringOpStrNotString = errors.New("test_string operation str must be a string")
	// ErrTestStringLenOpMissingLen indicates test_string_len operation is missing len.
	ErrTestStringLenOpMissingLen = errors.New("test_string_len operation requires len")
	// ErrTestStringLenOpLenNotNumber indicates test_string_len operation len must be a number.
	ErrTestStringLenOpLenNotNumber = errors.New("test_string_len operation len must be a number")
	// ErrInOpMissingValues indicates in operation is missing values.
	ErrInOpMissingValues = errors.New("in operation requires values")
	// ErrInOpValuesNotArray indicates in operation values must be an array.
	ErrInOpValuesNotArray = errors.New("in operation values must be an array")
	// ErrLessOpMissingValue indicates less operation is missing value.
	ErrLessOpMissingValue = errors.New("less operation requires value")
	// ErrLessOpValueNotNumber indicates less operation value must be a number.
	ErrLessOpValueNotNumber = errors.New("less operation value must be a number")
	// ErrMoreOpMissingValue indicates more operation is missing value.
	ErrMoreOpMissingValue = errors.New("more operation requires value")
	// ErrMoreOpValueNotNumber indicates more operation value must be a number.
	ErrMoreOpValueNotNumber = errors.New("more operation value must be a number")
	// ErrMatchesOpMissingPattern indicates matches operation is missing pattern.
	ErrMatchesOpMissingPattern = errors.New("matches operation requires pattern")
	// ErrMatchesOpPatternNotString indicates matches operation pattern must be a string.
	ErrMatchesOpPatternNotString = errors.New("matches operation pattern must be a string")
)
View Source 
var (
	// ErrAndOpMissingOps indicates and operation is missing ops.
	ErrAndOpMissingOps = errors.New("and operation requires ops")
	// ErrOrOpMissingOps indicates or operation is missing ops.
	ErrOrOpMissingOps = errors.New("or operation requires ops")
	// ErrNotOpMissingOps indicates not operation is missing ops.
	ErrNotOpMissingOps = errors.New("not operation requires ops")
	// ErrPredicateOpsNotArray indicates predicate ops must be an array.
	ErrPredicateOpsNotArray = errors.New("predicate ops must be an array")
	// ErrPredicateOpNotArray indicates predicate op must be an array.
	ErrPredicateOpNotArray = errors.New("predicate op must be an array")
	// ErrDecodedOpNotPredicate indicates decoded operation is not a predicate.
	ErrDecodedOpNotPredicate = errors.New("decoded operation is not a predicate")
)
View Source 
var (
	// ErrUnsupportedOp indicates unsupported operation type.
	ErrUnsupportedOp = errors.New("unsupported operation type")
	// ErrUnknownStringOpcode indicates unknown string opcode.
	ErrUnknownStringOpcode = errors.New("unknown string opcode")
	// ErrInvalidOpcodeType indicates invalid opcode type.
	ErrInvalidOpcodeType = errors.New("invalid opcode type")
	// ErrUnknownNumericOpcode indicates unknown numeric opcode.
	ErrUnknownNumericOpcode = errors.New("unknown numeric opcode")
)
View Source 
var (
	// ErrCannotConvertToFloat64 indicates value cannot be converted to float64.
	ErrCannotConvertToFloat64 = errors.New("cannot convert to float64")
	// ErrExpectedArray indicates expected array value.
	ErrExpectedArray = errors.New("expected array")
	// ErrExpectedStringInArray indicates expected string in array.
	ErrExpectedStringInArray = errors.New("expected string in array")
)

Functions

func Decode 

func Decode(compactOps []Op, opts ...DecoderOption) ([]internal.Op, error)

Decode decodes compact format operations using default options.

func DecodeJSON 

func DecodeJSON(data []byte, opts ...DecoderOption) ([]internal.Op, error)

DecodeJSON decodes compact format JSON bytes into operations.

func EncodeJSON 

func EncodeJSON(ops []internal.Op, opts ...EncoderOption) ([]byte, error)

EncodeJSON encodes operations into compact format JSON bytes.

Types

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder decodes compact format operations into operation instances.

func NewDecoder 

func NewDecoder(opts ...DecoderOption) *Decoder

NewDecoder creates a new compact decoder with the given options.

func (*Decoder) Decode 

func (d *Decoder) Decode(compactOp Op) (internal.Op, error)

Decode decodes a single compact operation into an operation instance.

func (*Decoder) DecodeSlice 

func (d *Decoder) DecodeSlice(compactOps []Op) ([]internal.Op, error)

DecodeSlice decodes multiple compact operations into operation instances.

type DecoderOption 

type DecoderOption func(*DecoderOptions)

DecoderOption is a functional option for configuring the decoder.

type DecoderOptions 

type DecoderOptions struct{}

DecoderOptions configures the compact decoder behavior.

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder encodes operations into compact format.

func NewEncoder 

func NewEncoder(opts ...EncoderOption) *Encoder

NewEncoder creates a new compact encoder with the given options.

func (*Encoder) Encode 

func (e *Encoder) Encode(op internal.Op) (Op, error)

Encode encodes a single operation into compact format.

func (*Encoder) EncodeSlice 

func (e *Encoder) EncodeSlice(ops []internal.Op) ([]Op, error)

EncodeSlice encodes multiple operations into compact format.

type EncoderOption 

type EncoderOption func(*EncoderOptions)

EncoderOption is a functional option for configuring the encoder.

func WithStringOpcode 

func WithStringOpcode(useString bool) EncoderOption

WithStringOpcode configures the encoder to use string opcodes.

type EncoderOptions 

type EncoderOptions struct {
	// StringOpcode uses string opcodes instead of numeric ones.
	StringOpcode bool
}

EncoderOptions configures the compact encoder behavior.

type Op added in v0.4.3 

type Op []any

Op represents a compact format operation as an array.

func Encode 

func Encode(ops []internal.Op, opts ...EncoderOption) ([]Op, error)

Encode encodes operations into compact format using default options.

type OpCode 

type OpCode int

OpCode represents operation codes for compact format. 

const (
	// JSON Patch (RFC 6902) operations
	OpCodeAdd     OpCode = OpCode(internal.OpAddCode)
	OpCodeRemove  OpCode = OpCode(internal.OpRemoveCode)
	OpCodeReplace OpCode = OpCode(internal.OpReplaceCode)
	OpCodeCopy    OpCode = OpCode(internal.OpCopyCode)
	OpCodeMove    OpCode = OpCode(internal.OpMoveCode)
	OpCodeTest    OpCode = OpCode(internal.OpTestCode)

	// String editing
	OpCodeStrIns OpCode = OpCode(internal.OpStrInsCode)
	OpCodeStrDel OpCode = OpCode(internal.OpStrDelCode)

	// Extra
	OpCodeFlip OpCode = OpCode(internal.OpFlipCode)
	OpCodeInc  OpCode = OpCode(internal.OpIncCode)

	// Slate.js
	OpCodeSplit  OpCode = OpCode(internal.OpSplitCode)
	OpCodeMerge  OpCode = OpCode(internal.OpMergeCode)
	OpCodeExtend OpCode = OpCode(internal.OpExtendCode)

	// JSON Predicate operations
	OpCodeContains      OpCode = OpCode(internal.OpContainsCode)
	OpCodeDefined       OpCode = OpCode(internal.OpDefinedCode)
	OpCodeEnds          OpCode = OpCode(internal.OpEndsCode)
	OpCodeIn            OpCode = OpCode(internal.OpInCode)
	OpCodeLess          OpCode = OpCode(internal.OpLessCode)
	OpCodeMatches       OpCode = OpCode(internal.OpMatchesCode)
	OpCodeMore          OpCode = OpCode(internal.OpMoreCode)
	OpCodeStarts        OpCode = OpCode(internal.OpStartsCode)
	OpCodeUndefined     OpCode = OpCode(internal.OpUndefinedCode)
	OpCodeTestType      OpCode = OpCode(internal.OpTestTypeCode)
	OpCodeTestString    OpCode = OpCode(internal.OpTestStringCode)
	OpCodeTestStringLen OpCode = OpCode(internal.OpTestStringLenCode)
	OpCodeType          OpCode = OpCode(internal.OpTypeCode)
	OpCodeAnd           OpCode = OpCode(internal.OpAndCode)
	OpCodeNot           OpCode = OpCode(internal.OpNotCode)
	OpCodeOr            OpCode = OpCode(internal.OpOrCode)
)

Operation codes for compact format - derived from internal constants.

type Operation 

type Operation = internal.CompactOperation

Operation represents a compact format operation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.