zikzak_json #

A best-effort JSON parser for Dart. Uses simdjson_dart for speed on standard JSON and falls back to json5_plus for comments, trailing commas, unquoted keys, and numeric object keys. The caller never needs to think about which engine is running — zikzak_json handles everything and always returns clean raw Dart types (Map, List, String, num, bool, null).

Features #

• Dual-engine architecture — simdjson for strict JSON (>3x faster), json5_plus for everything else
• Transparent fallback — feed it any JSON or JSON5, get raw Dart types back
• Fast-path heuristic — detects JSON5 features (comments, unquoted keys, trailing commas) in the first 4KB to skip simdjson when failure is predictable
• No Json5 wrapper objects — recursive toRaw() conversion strips wrapper types so you always get plain Map/List/primitives
• Extract paths — dot-notation or JSONPath extraction without full document traversal
• Thread-safe — all decode calls are independent, no mutable global state

Getting started #

zikzak_json is a pure Dart package with zero Flutter dependencies.

dependencies:
  zikzak_json: ^0.1.0

Usage #

Basic decode #

import 'package:zikzak_json/zikzak_json.dart';

// Standard JSON → simdjson (fast path)
final data = ZikZakJson.decode('{"a": 1, "b": "hello"}');
print(data['a']); // 1

// JSON5 with comments → auto-detected, json5_plus path
final config = ZikZakJson.decode('''
{
  site: "lowes",          // unquoted key
  channel: "mobile",
  timeout: 2000,          // trailing comma
}
''');
print(config['site']); // "lowes"

// Numeric keys → json5_plus handles what simdjson rejects
final cats = ZikZakJson.decode('{102717: "PADLOCKS"}');
print(cats['102717']); // "PADLOCKS"

Convenience methods #

final map = ZikZakJson.decodeMap('{"a": 1}');     // throws if not object
final list = ZikZakJson.decodeList('[1, 2, 3]');   // throws if not array
final str = ZikZakJson.decodeString('"hello"');    // throws if not string

Detection helpers #

ZikZakJson.isJson('{"a": 1}');   // true
ZikZakJson.isJson('hello');      // false
ZikZakJson.isJson5('{a: 1}');    // true  (valid JSON5, not valid JSON)
ZikZakJson.isJson5('{"a": 1}');  // false (valid JSON, not JSON5-only)

Options & engine selection #

// Force a specific engine
ZikZakJson.decode(source, options: ZikZakJsonOptions(
  forceEngine: ZikZakJsonEngine.json5,  // skip simdjson
));

// Strict mode — throw on first failure, no fallback
ZikZakJson.decode(source, options: ZikZakJsonOptions(
  strict: true,
  forceEngine: ZikZakJsonEngine.simdjson,
));

// Verbose timing
ZikZakJson.decode(source, options: ZikZakJsonOptions(verbose: true));

Path extraction #

final json = ZikZakJson.decode(largePayload);
final brand = ZikZakJson.get(json, 'itemList.0.product.brand');
// → "Master Lock"

Engine Architecture #

Input String
    │
    ├── forceEngine == simdjson ───→ simdjson_dart ──→ raw types
    │
    ├── forceEngine == json5 ──────→ json5_plus ─────→ toRaw() ──→ raw types
    │
    └── auto (default)
          │
          ├── fast-path heuristic
          │     └── JSON5 indicators? ──yes──→ json5_plus
          │
          └── try simdjson_dart
                ├── success ──→ return
                └── fail ─────→ json5_plus fallback

Why two engines? #

Similar packages #

• json5 — Standard JSON5 parser, rejects numeric object keys (102717: "val")
• json5_plus — JSON5 parser with typed accessors and $include support
• simdjson_dart — Raw simdjson bindings for Dart

Powered by ZikZak AI #

zikzak_json is developed by ZikZak AI to serve as the JSON backbone for high-throughput price comparison, and data extraction workloads.

• 🌐 zuzu.dev
• 🐙 GitHub
• 🐛 Issue Tracker

Sponsors #

Thanks to ZikZak AI for sponsoring this project!

ZikZak AI is an AI-Powered Price Comparison app that you scan barcodes, and discover amazing savings instantly. Your personal shopping assistant that never sleeps.

Licensed under the Apache License, Version 2.0.