koda-format 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KODA Format Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# KODA — Compact Object Data Architecture
+
+**KODA** is a compact data format with a **text syntax** (`.koda`) and a **canonical binary encoding** (`.kod`). It is optimized for smaller payloads, efficient storage, and deterministic encoding—not for beating JSON on text parse speed. It wins on **size**, **IO**, and **storage** when using the binary format.
+
+[![npm version](https://img.shields.io/npm/v/koda-format.svg)](https://www.npmjs.com/package/koda-format)  
+**License:** MIT
+
+---
+
+## Quick start
+
+```bash
+npm install koda-format
+```
+
+```ts
+import { parse, stringify, encode, decode } from 'koda-format';
+
+// Text
+const value = parse(`
+  name: "my-app"
+  version: 1
+  enabled: true
+`);
+const back = stringify(value);
+
+// Binary (canonical, smaller, good for storage)
+const bytes = encode(value);
+const decoded = decode(bytes);
+```
+
+---
+
+## What’s in the box
+
+| Feature | Description |
+|--------|-------------|
+| **Text (`.koda`)** | Objects, arrays, `key: value`, optional commas, `//` and `/* */` comments, unquoted identifiers. |
+| **Binary (`.kod`)** | Magic + version, key dictionary (each key stored once), then typed data; big-endian; deterministic. |
+| **Security** | Configurable max depth, max input length, max dictionary/string size. |
+| **Optional C++ addon** | Faster encode/decode when built; same API, pure JS fallback. |
+
+Full grammar and binary layout: **[SPEC.md](./SPEC.md)**.
+
+---
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `parse(text, options?)` | Parse KODA text → value. Options: `maxDepth`, `maxInputLength`. |
+| `stringify(value, options?)` | Value → KODA text. Options: `indent`, `newline`. |
+| `encode(value, options?)` | Value → canonical binary `Uint8Array`. Options: `maxDepth`. |
+| `decode(buffer, options?)` | Binary → value. Options: `maxDepth`, `maxDictionarySize`, `maxStringLength`. |
+| `loadFile(path, options?)` | Read file (UTF-8) and parse. |
+| `saveFile(path, value, options?)` | Stringify and write file. |
+| `toJSON(value)` | Same as `JSON.stringify(value)`. |
+| `fromJSON(json)` | Same as `JSON.parse(json)`. |
+| `parseWithLexer(text, options?)` | Lexer-based parse (better error positions). |
+| `isNativeAvailable()` | `true` if the C++ addon is loaded. |
+
+Errors: `KodaParseError`, `KodaEncodeError`, `KodaDecodeError` (with `.position` or `.byteOffset`).
+
+---
+
+## Binary format (implemented)
+
+- **Magic:** 4 bytes `KODA` (0x4B 0x4F 0x44 0x41).  
+- **Version:** 1 byte (`1`).  
+- **Dictionary:** N unique keys (UTF-8), canonical order; each key: 4 bytes length (BE) + bytes.  
+- **Data:** Root value with type tags: null, false, true, int64, float64, string, array, object. Objects use key indices into the dictionary. Same value → same bytes.
+
+---
+
+## Storage (e.g. PostgreSQL BYTEA)
+
+```ts
+const bytes = encode(document);
+// store in BYTEA; later:
+const value = decode(row.bytes);
+```
+
+---
+
+## Build C++ addon (optional)
+
+Requires Node.js build tools and a C++ compiler:
+
+```bash
+npm run build:addon
+# or
+npm run build:all
+```
+
+---
+
+## Repo
+
+- **[SPEC.md](./SPEC.md)** — Grammar, data model, binary layout, canonicalization, security.
+- **Source:** `src/` (TypeScript). **Native:** `native/` (C++ N-API). **Tests:** `test/`. **Examples:** `examples/*.koda`.
+
+---
+
+**KODA** — Compact Object Data Architecture. MIT.

package/SPEC.md

@@ -0,0 +1,288 @@
+# KODA Data Format (KDF) — Specification
+
+**Full name:** Compact Object Data Architecture  
+**Specification name:** KDF (KODA Data Format)  
+**Version:** 1.0  
+**Status:** Draft
+
+---
+
+## 1. Introduction
+
+KODA (Compact Object Data Architecture) is a structured data format designed for storage efficiency, deterministic encoding, and human authorability. It has two representations:
+
+- **Text format** (`.koda`): A compact, JSON-like syntax with minimal overhead, comments, and optional commas.
+- **Binary format** (`.kod`): A canonical encoding optimized for storage, transport, and PostgreSQL BYTEA columns.
+
+KODA addresses limitations of JSON (verbosity, no comments, non-deterministic key order), YAML (complexity, security issues), and binary formats like MessagePack (non-canonical, key repetition).
+
+**Positioning:** KODA is a **compact binary data format** first. It is optimized for **smaller payloads**, **efficient storage**, **reduced IO**, and **fast binary encode/decode** — not for beating JSON on raw text parsing speed. In real systems, KODA wins on size, IO efficiency, storage, and scalability (see project docs).
+
+---
+
+## 2. Design Goals
+
+| Goal | Description |
+|------|-------------|
+| **Compactness** | Smaller than JSON; keys stored once per document in binary; minimal encoded size. |
+| **Determinism** | Canonical encoding enables hashing, caching, and comparison. |
+| **Safety** | Unambiguous parsing; secure against malformed and malicious input. |
+| **Human-authorable** | Readable text format with comments and flexible syntax. |
+| **Machine-efficient** | Efficient binary encode/decode; stream-friendly; low allocation; optional partial decode. |
+| **Storage-friendly** | Suitable for PostgreSQL BYTEA; minimal disk footprint; reduced IO. |
+| **Standardization** | Versioned format; forward-compatible extension points. |
+
+---
+
+## 3. Terminology
+
+- **Document**: A single KODA value (object, array, or top-level scalar).
+- **Value**: Any instance of the KODA data model (object, array, string, number, boolean, null).
+- **Key**: A string used as an object property name.
+- **Element**: A member of an array or a key-value pair in an object.
+- **Canonical encoding**: The unique binary representation of a value under KDF rules.
+- **Dictionary**: In binary format, the ordered set of unique keys used in the document.
+
+---
+
+## 4. Text Syntax (.koda)
+
+### 4.1 Overview
+
+- **Objects**: `{` ... `}`
+- **Arrays**: `[` ... `]`
+- **Key-value**: `key: value`
+- **Separators**: Whitespace (and optional commas) separate elements; commas are optional.
+- **Comments**: `//` (single-line) and `/*` `*/` (multi-line).
+- **Trailing commas**: Allowed in objects and arrays.
+
+### 4.2 EBNF Grammar
+
+```ebnf
+document     = value ;
+
+value        = object | array | string | number | boolean | null ;
+
+object       = "{" [ ( pair ( ws_or_comma pair )* [ ws_or_comma ] ) ] "}" ;
+pair         = key ":" value ;
+key          = identifier | quoted_string ;
+
+array        = "[" [ ( value ( ws_or_comma value )* [ ws_or_comma ] ) ] "]" ;
+
+string       = quoted_string | unquoted_string ;
+quoted_string = double_quote_string | single_quote_string ;
+double_quote_string = '"' ( escape | [^"\x00-\x1F] )* '"' ;
+single_quote_string = "'" ( escape_single | [^'\x00-\x1F] )* "'" ;
+unquoted_string = identifier ;  (* when value position allows *)
+
+identifier   = ( letter | "_" ) ( letter | digit | "_" | "-" )* ;
+letter       = "A" - "Z" | "a" - "z" ;
+digit        = "0" - "9" ;
+
+number       = integer | float ;
+integer      = [ "-" ] ( "0" | digit_nonzero digit* ) ;
+digit_nonzero = "1" - "9" ;
+float        = [ "-" ] ( digit+ "." digit* | "." digit+ ) ( "e" | "E" ) [ "+" | "-" ] digit+ 
+             | [ "-" ] digit+ "." digit* ;
+
+boolean      = "true" | "false" ;
+null         = "null" ;
+
+ws_or_comma  = ( whitespace | comment )+ | ( "," ( whitespace | comment )* ) ;
+whitespace   = " " | "\t" | "\r" | "\n" ;
+comment      = "//" [^\n]* | "/*" ( [^*] | "*" [^/] )* "*/" ;
+
+escape       = "\\" ( '"' | "\\" | "/" | "b" | "f" | "n" | "r" | "t" | "u" hex hex hex hex ) ;
+escape_single = "\\" ( "'" | "\\" | "/" | "b" | "f" | "n" | "r" | "t" | "u" hex hex hex hex ) ;
+hex          = digit | "A" - "F" | "a" - "f" ;
+```
+
+### 4.3 Lexical Rules
+
+- **Unquoted keys**: Keys may be identifiers (letters, digits, `_`, `-`; must not start with digit). Reserved words `true`, `false`, `null` are allowed as keys (context is key vs value).
+- **Unquoted string values**: Only in value position when the token is an identifier that is not `true`, `false`, or `null`; then it is interpreted as a string. Numbers (including those that look like integers) are always parsed as numbers when in value position.
+- **String quotes**: Double `"` and single `'` supported; same escape rules as JSON for `"` strings; for `'` strings, `\'` and `\\` apply.
+- **Numbers**: No leading zeros for integers (except `0`). Floats may use `e`/`E` exponent. Hex/octal not in scope for 1.0.
+- **Whitespace**: Space, tab, CR, LF separate tokens. At least one whitespace or comma is required between adjacent values or pairs when otherwise ambiguous (e.g. `}` and `{`).
+
+### 4.4 Example (Text)
+
+```koda
+// Config example
+name: "my-app"
+version: 1
+enabled: true
+
+vehicles[
+  { id: A speed: 60 }
+  { id: B speed: 40 }
+]
+```
+
+---
+
+## 5. Data Model
+
+KODA values map to these types:
+
+| Type    | Description | Text example |
+|---------|-------------|--------------|
+| Object  | Unordered map of string keys to values | `{ a: 1 b: 2 }` |
+| Array   | Ordered list of values | `[ 1 2 3 ]` |
+| String  | Unicode string | `"hello"` or `hello` (unquoted when safe) |
+| Integer | Signed 64-bit range; parsed from text | `42`, `-1` |
+| Float   | IEEE 754 double | `3.14`, `1e10` |
+| Boolean | true / false | `true`, `false` |
+| Null    | Null value | `null` |
+
+**Note:** For canonical encoding, object key order is defined by the canonicalization rules (e.g. lexicographic by key).
+
+---
+
+## 6. Binary Encoding (.kod)
+
+### 6.1 Overview
+
+- **Deterministic**: Same value always produces the same byte sequence.
+- **Key dictionary**: Each unique key appears once; values reference keys by index.
+- **Stream-friendly**: Header, then dictionary, then data; can be parsed in one pass.
+
+### 6.2 Layout
+
+```
++--------+--------+------------------+------------------+
+| Magic  | Version| Dictionary       | Data             |
+| 4 B    | 1 B    | (see below)      | (see below)      |
++--------+--------+------------------+------------------+
+```
+
+- **Magic**: 4 bytes, `0x4B 0x4F 0x44 0x41` ("KODA" ASCII).
+- **Version**: 1 byte. Current format version = `1`.
+
+### 6.3 Dictionary Section
+
+- **Dictionary length**: 4 bytes, unsigned big-endian, number of unique keys N.
+- **Keys**: For each of N keys:
+  - **Key length**: 4 bytes, unsigned big-endian, byte length L of key (UTF-8).
+  - **Key bytes**: L bytes UTF-8.
+
+Keys appear in **canonical order** (sorted lexicographically by UTF-8 bytes). Keys are deduplicated; first occurrence in document order defines the index (for building the dictionary during encoding).
+
+### 6.4 Data Section
+
+The root value is encoded as a single value. Values are encoded in order; no length prefix for the whole data section (parser knows end by stream length or by single root value).
+
+**Type tags** (1 byte):
+
+| Tag (hex) | Type    | Encoding |
+|-----------|---------|----------|
+| 0x01      | Null    | — |
+| 0x02      | False   | — |
+| 0x03      | True    | — |
+| 0x04      | Integer | 8 bytes signed big-endian (two's complement) |
+| 0x05      | Float   | 8 bytes IEEE 754 big-endian double |
+| 0x06      | String  | 4 bytes length (unsigned big-endian) + UTF-8 bytes |
+| 0x07      | Binary  | 4 bytes length + raw bytes (reserved/future) |
+| 0x10      | Array   | 4 bytes count N + N encoded values |
+| 0x11      | Object  | 4 bytes pair count K + K × (4 bytes key index + value) |
+
+**Integer**: Must be in range [-2^63, 2^63-1]. Encoded as 8 bytes signed big-endian.
+
+**Float**: IEEE 754 double, big-endian. NaN payloads canonicalized to a single NaN representation if required by spec (e.g. quiet NaN, zero payload).
+
+**String**: Length (4 bytes unsigned big-endian) + UTF-8 byte sequence.
+
+**Array**: Count N (4 bytes unsigned big-endian), then N values in order.
+
+**Object**: Pair count K (4 bytes). Each pair: key index (4 bytes unsigned, index into dictionary), then value. Pairs ordered by canonical key order (same as dictionary order).
+
+### 6.5 Canonicalization (Binary)
+
+1. **Key order**: Object keys sorted lexicographically by UTF-8 bytes.
+2. **Dictionary**: Built by traversing the value in document order, collecting unique keys, then sorting them; indices assigned by sorted order.
+3. **Number canonicalization**: Integers in range that fit in 64-bit signed are encoded as integer tag; otherwise float. Float: use IEEE 754 double; NaN → single canonical NaN.
+4. **No optional padding**: No trailing bytes; no alignment padding.
+
+---
+
+## 7. Canonicalization Rules
+
+- **Text → Value**: Parsing produces a unique value tree.
+- **Value → Binary**: Apply key ordering and number rules above; output is unique for that value.
+- **Value → Text**: Implementations may vary spacing/quoting; for a “canonical text” profile, keys in object order, consistent quoting (e.g. minimal quotes), no trailing commas (or always trailing comma)—to be defined in a future amendment if needed).
+
+---
+
+## 8. Error Handling Rules
+
+- **Fail-fast**: On first syntax or encoding error, processing stops.
+- **Diagnostics**: Errors MUST report line and column (text) or byte offset (binary) where available.
+- **Recoverable parsing**: Not required; implementations may offer best-effort recovery for tooling only.
+
+**Text errors**: Invalid token, unexpected character, unclosed string/comment, invalid number, unexpected end of input.
+
+**Binary errors**: Unknown magic, unsupported version, truncated dictionary or data, invalid type tag, out-of-range key index, invalid UTF-8.
+
+---
+
+## 9. Security Considerations
+
+- **Depth limit**: Parsers MUST support a configurable maximum nesting depth (e.g. default 256) to prevent stack overflow.
+- **Input size**: Implementations SHOULD support configurable maximum input size (bytes/chars) to mitigate DoS.
+- **Recursion**: Prefer iterative or bounded recursion when parsing nested structures.
+- **Malformed input**: Reject invalid input; do not interpret ambiguous or truncated data as valid.
+- **Binary**: Validate key indices against dictionary size; validate string lengths and UTF-8.
+- **Resource limits**: Limit size of dictionary and number of keys per object to prevent memory exhaustion.
+
+---
+
+## 10. Versioning Strategy
+
+- **Magic + Version**: Binary format carries version; parsers must reject unknown versions or document behavior.
+- **Forward compatibility**: New type tags or optional sections may be added; decoders must ignore unknown tags or sections if specified.
+- **Backward compatibility**: New versions should not change encoding of existing type tags for the same semantic value.
+
+---
+
+## 11. Examples
+
+### 11.1 Simple object (text)
+
+```koda
+name: "KODA"
+version: 1
+binary: true
+```
+
+### 11.2 Array of objects (text)
+
+```koda
+vehicles[
+  { id: A speed: 60 }
+  { id: B speed: 40 }
+]
+```
+
+### 11.3 With comments (text)
+
+```koda
+// Server config
+host: "0.0.0.0"
+port: 8080
+/* multi
+   line */
+debug: false
+```
+
+### 11.4 Binary encoding (conceptual)
+
+For `{ "a": 1 "b": 2 }` (keys canonical order `a`, `b`):
+
+- Magic: KODA
+- Version: 1
+- Dictionary: 2 keys → "a", "b" (lengths and UTF-8)
+- Data: Object, 2 pairs → (index 0, integer 1), (index 1, integer 2)
+
+---
+
+*End of specification.*

package/binding.gyp

@@ -0,0 +1,29 @@
+{
+  "targets": [
+    {
+      "target_name": "koda_format",
+      "sources": [
+        "native/binding.cc",
+        "native/koda_binary.cc",
+        "native/koda_parse.cc"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "native"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "defines": [ "NAPI_CPP_EXCEPTIONS" ],
+      "conditions": [
+        ["OS=='win'", { "msvs_settings": { "VCCLCompilerTool": { "ExceptionHandling": 1 } } }]
+      ],
+      "xcode_settings": {
+        "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+        "CLANG_CXX_LIBRARY": "libc++"
+      }
+    }
+  ]
+}

package/dist/ast.d.ts

@@ -0,0 +1,23 @@
+/**
+ * KODA Data Format — value types and positions.
+ * All runtime values are immutable; types align with SPEC data model.
+ */
+export interface SourcePosition {
+    line: number;
+    column: number;
+    offset: number;
+}
+/** KODA value types per SPEC §5 */
+export type KodaValue = KodaObject | KodaArray | string | number | boolean | null;
+export interface KodaObject {
+    [key: string]: KodaValue;
+}
+export type KodaArray = KodaValue[];
+/** Type guard for object (and not array, which is also typeof 'object' in JSON) */
+export declare function isKodaObject(v: KodaValue): v is KodaObject;
+export declare function isKodaArray(v: KodaValue): v is KodaArray;
+export declare function isKodaString(v: KodaValue): v is string;
+export declare function isKodaNumber(v: KodaValue): v is number;
+export declare function isKodaBoolean(v: KodaValue): v is boolean;
+export declare function isKodaNull(v: KodaValue): v is null;
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mCAAmC;AACnC,MAAM,MAAM,SAAS,GACjB,UAAU,GACV,SAAS,GACT,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,CAAC;AAET,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;AAEpC,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,UAAU,CAE1D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,SAAS,CAExD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,MAAM,CAEtD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,MAAM,CAEtD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,OAAO,CAExD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,IAAI,CAElD"}

package/dist/ast.js

@@ -0,0 +1,24 @@
+/**
+ * KODA Data Format — value types and positions.
+ * All runtime values are immutable; types align with SPEC data model.
+ */
+/** Type guard for object (and not array, which is also typeof 'object' in JSON) */
+export function isKodaObject(v) {
+    return typeof v === 'object' && v !== null && Array.isArray(v) === false;
+}
+export function isKodaArray(v) {
+    return Array.isArray(v);
+}
+export function isKodaString(v) {
+    return typeof v === 'string';
+}
+export function isKodaNumber(v) {
+    return typeof v === 'number';
+}
+export function isKodaBoolean(v) {
+    return typeof v === 'boolean';
+}
+export function isKodaNull(v) {
+    return v === null;
+}
+//# sourceMappingURL=ast.js.map

package/dist/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,CAAY;IACvC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAY;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAY;IACvC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAY;IACvC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAY;IACxC,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAY;IACrC,OAAO,CAAC,KAAK,IAAI,CAAC;AACpB,CAAC"}

package/dist/decoder.d.ts

@@ -0,0 +1,17 @@
+/**
+ * KODA binary decoding (.kod). SPEC §6.
+ */
+import type { KodaValue } from './ast.js';
+export interface DecodeOptions {
+    /** Max nesting depth (default 256) */
+    maxDepth?: number;
+    /** Max dictionary size (default 65536) */
+    maxDictionarySize?: number;
+    /** Max string length (default 1_000_000) */
+    maxStringLength?: number;
+}
+/**
+ * Decode KODA binary buffer to a KODA value.
+ */
+export declare function decode(buffer: Uint8Array, options?: DecodeOptions): KodaValue;
+//# sourceMappingURL=decoder.d.ts.map

package/dist/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../src/decoder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAkB1C,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;GAEG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,aAAkB,GAAG,SAAS,CA2HjF"}

package/dist/decoder.js

@@ -0,0 +1,147 @@
+/**
+ * KODA binary decoding (.kod). SPEC §6.
+ */
+import { KodaDecodeError } from './errors.js';
+const MAGIC = new Uint8Array([0x4b, 0x4f, 0x44, 0x41]);
+const VERSION = 1;
+var Tag;
+(function (Tag) {
+    Tag[Tag["Null"] = 1] = "Null";
+    Tag[Tag["False"] = 2] = "False";
+    Tag[Tag["True"] = 3] = "True";
+    Tag[Tag["Integer"] = 4] = "Integer";
+    Tag[Tag["Float"] = 5] = "Float";
+    Tag[Tag["String"] = 6] = "String";
+    Tag[Tag["Binary"] = 7] = "Binary";
+    Tag[Tag["Array"] = 16] = "Array";
+    Tag[Tag["Object"] = 17] = "Object";
+})(Tag || (Tag = {}));
+const DEFAULT_MAX_DEPTH = 256;
+const DEFAULT_MAX_DICT = 65536;
+const DEFAULT_MAX_STRING = 1_000_000;
+/**
+ * Decode KODA binary buffer to a KODA value.
+ */
+export function decode(buffer, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxDict = options.maxDictionarySize ?? DEFAULT_MAX_DICT;
+    const maxStr = options.maxStringLength ?? DEFAULT_MAX_STRING;
+    let offset = 0;
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.length);
+    function fail(message) {
+        throw new KodaDecodeError(message, { byteOffset: offset });
+    }
+    function ensure(n) {
+        if (offset + n > buffer.length)
+            fail('Truncated input');
+    }
+    function readU8() {
+        ensure(1);
+        return buffer[offset++];
+    }
+    function readU32() {
+        ensure(4);
+        const v = view.getUint32(offset, false);
+        offset += 4;
+        return v;
+    }
+    function readI64() {
+        ensure(8);
+        const v = view.getBigInt64(offset, false);
+        offset += 8;
+        return v;
+    }
+    function readF64() {
+        ensure(8);
+        const v = view.getFloat64(offset, false);
+        offset += 8;
+        return v;
+    }
+    function readBytes(n) {
+        ensure(n);
+        const slice = buffer.subarray(offset, offset + n);
+        offset += n;
+        return slice;
+    }
+    function decodeUtf8(bytes) {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    ensure(5);
+    for (let i = 0; i < 4; i++) {
+        if (buffer[offset + i] !== MAGIC[i])
+            fail('Invalid magic number');
+    }
+    offset += 4;
+    const version = readU8();
+    if (version !== VERSION)
+        fail(`Unsupported version: ${version}`);
+    const dictLen = readU32();
+    if (dictLen > maxDict)
+        fail('Dictionary too large');
+    const dictionary = new Array(dictLen);
+    for (let i = 0; i < dictLen; i++) {
+        const keyLen = readU32();
+        if (keyLen > maxStr)
+            fail('Key string too long');
+        const keyBytes = readBytes(keyLen);
+        dictionary[i] = decodeUtf8(keyBytes);
+    }
+    function decodeValue(depth) {
+        if (depth > maxDepth)
+            fail('Maximum nesting depth exceeded');
+        ensure(1);
+        const tag = readU8();
+        switch (tag) {
+            case Tag.Null:
+                return null;
+            case Tag.False:
+                return false;
+            case Tag.True:
+                return true;
+            case Tag.Integer: {
+                const big = readI64();
+                if (big >= Number.MIN_SAFE_INTEGER && big <= Number.MAX_SAFE_INTEGER) {
+                    return Number(big);
+                }
+                return Number(big);
+            }
+            case Tag.Float:
+                return readF64();
+            case Tag.String: {
+                const len = readU32();
+                if (len > maxStr)
+                    fail('String too long');
+                const bytes = readBytes(len);
+                return decodeUtf8(bytes);
+            }
+            case Tag.Binary:
+                fail('Binary type not supported in this version');
+            case Tag.Array: {
+                const count = readU32();
+                const arr = new Array(count);
+                for (let i = 0; i < count; i++)
+                    arr[i] = decodeValue(depth + 1);
+                return arr;
+            }
+            case Tag.Object: {
+                const count = readU32();
+                const obj = {};
+                for (let i = 0; i < count; i++) {
+                    const keyIdx = readU32();
+                    if (keyIdx >= dictionary.length)
+                        fail('Invalid key index');
+                    const key = dictionary[keyIdx];
+                    obj[key] = decodeValue(depth + 1);
+                }
+                return obj;
+            }
+            default:
+                fail(`Unknown type tag: 0x${tag.toString(16)}`);
+        }
+    }
+    const value = decodeValue(0);
+    if (offset !== buffer.length)
+        fail('Trailing bytes after root value');
+    return value;
+}
+//# sourceMappingURL=decoder.js.map

package/dist/decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.js","sourceRoot":"","sources":["../src/decoder.ts"],"names":[],"mappings":"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"}