A complete JSON parser ported from TypeScript to Zig 0.15.1, demonstrating faithful architectural patterns with memory safety and performance. Supports all JSON types, Unicode, and includes comprehensive testing.
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.
When working with this json-zig codebase, follow these guidelines:
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
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,
};
```
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
}
```
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)
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
};
```
| 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) |
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
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
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/json-parser-implementation-in-zig/raw