JSON Parser Implementation in Zig

A complete JSON parser implementation ported from TypeScript to Zig 0.15.1, demonstrating faithful architectural patterns while leveraging Zig's memory safety and performance characteristics.

Features

Instructions

When working with this json-zig codebase, follow these guidelines:

Architecture Understanding

1. **Recognize the modular design**:

- Each JSON type has its own parser module (string.zig, number.zig, array.zig, object.zig, etc.)

- Value parser (value.zig) acts as dispatcher to appropriate type parsers

- Recursive descent parsing pattern from original TypeScript implementation

2. **Project structure**:

- `lib/src/` contains core parsing library modules

- `cli/src/` contains command-line interface

- `typescript/` contains original TypeScript reference implementation

- All parsers follow consistent module structure with `parse()` and `deinit()` functions

Code Style Standards

1. **Follow Zig conventions**:

- Use `snake_case` for functions and variables

- Use `PascalCase` for types

- Include explicit error handling with `try` and error unions

2. **Memory management patterns**:

```zig

// Standard allocation pattern

var result = try parse(allocator, json_string);

defer result.deinit(allocator); // Always cleanup

// ArrayList pattern (Zig 0.15.1)

var list = ArrayList(ValueToken).init(allocator);

defer list.deinit();

```

3. **Error handling patterns**:

```zig

// Propagate errors up the call stack

return JsonError.UnexpectedCharacter;

// Handle specific errors

const result = parse(...) catch |err| switch (err) {

JsonError.InvalidInput => return null,

else => return err,

};

```

Parser Module Structure

When creating or modifying parsers:

```zig

pub fn parse(allocator: Allocator, expression: []const u8, pos: *usize) JsonError!?ValueToken {

// Implement parsing logic with proper error handling

// Use pos pointer to track current position in input

// Return error unions for robust error propagation

}

pub fn deinit(self: *SomeType, allocator: Allocator) void {

// Implement cleanup for allocated resources

}

```

Testing Patterns

1. **Write comprehensive tests** for all new functionality:

```zig

test "descriptive test name" {

var result = try parse(testing.allocator, "test_input");

defer result.deinit(testing.allocator);

// Assertions using std.testing

try testing.expect(condition);

}

```

2. **Test coverage should include**:

- Valid inputs (happy path)

- Edge cases (empty, whitespace, boundaries)

- Error cases (invalid syntax, incomplete input)

- Memory cleanup (no leaks)

Error Handling System

The parser uses these error types:

```zig

pub const JsonError = error{

InvalidInput, // Empty or null input

UnexpectedCharacter, // Invalid character in JSON

IncompleteExpression, // Truncated JSON

OutOfMemory, // Memory allocation failed

};

```

Supported JSON Features

| Feature | Implementation Notes |

| ---------- | -------------------------------------------------------- |

| Numbers | Integers, floats, scientific notation |

| Strings | UTF-8, escape sequences (\n, \t, \", \\, \/, \b, \f, \r) |

| Unicode | \uXXXX escape sequences with proper UTF-8 encoding |

| Booleans | `true`, `false` literals |

| Null | `null` literal |

| Arrays | Nested arrays, mixed types, comma separation |

| Objects | Nested objects, string keys, key-value pairs |

| Whitespace | Flexible whitespace handling (spaces, tabs, newlines) |

Adding New Features

1. Implement in the appropriate module under `lib/src/`

2. Add comprehensive unit tests

3. Document in code comments

4. Validate with `zig build test` and memory leak checks

5. Performance test with realistic JSON samples

Debugging Tips

Performance Characteristics

Best Practices

1. **Always use defer for cleanup**: Ensure `deinit()` is called even on error paths

2. **Prefer stack allocation**: Use heap only when necessary

3. **Test memory**: Run tests with allocator that detects leaks

4. **Follow TypeScript reference**: Maintain architectural consistency with original implementation

5. **Explicit error handling**: Never ignore errors, always propagate or handle appropriately

Technical References