@toon-format/spec 1.3.0

package/tests/fixtures/encode/arrays-objects.json

@@ -0,0 +1,138 @@
+{
+  "version": "1.3",
+  "category": "encode",
+  "description": "Arrays of objects encoding - list format for non-uniform objects and complex structures",
+  "tests": [
+    {
+      "name": "uses list format for objects with different fields",
+      "input": {
+        "items": [
+          { "id": 1, "name": "First" },
+          { "id": 2, "name": "Second", "extra": true }
+        ]
+      },
+      "expected": "items[2]:\n  - id: 1\n    name: First\n  - id: 2\n    name: Second\n    extra: true",
+      "specSection": "7"
+    },
+    {
+      "name": "uses list format for objects with nested values",
+      "input": {
+        "items": [
+          { "id": 1, "nested": { "x": 1 } }
+        ]
+      },
+      "expected": "items[1]:\n  - id: 1\n    nested:\n      x: 1",
+      "specSection": "7"
+    },
+    {
+      "name": "preserves field order in list items - array first",
+      "input": {
+        "items": [{ "nums": [1, 2, 3], "name": "test" }]
+      },
+      "expected": "items[1]:\n  - nums[3]: 1,2,3\n    name: test",
+      "specSection": "7"
+    },
+    {
+      "name": "preserves field order in list items - primitive first",
+      "input": {
+        "items": [{ "name": "test", "nums": [1, 2, 3] }]
+      },
+      "expected": "items[1]:\n  - name: test\n    nums[3]: 1,2,3",
+      "specSection": "7"
+    },
+    {
+      "name": "uses list format for objects containing arrays of arrays",
+      "input": {
+        "items": [
+          { "matrix": [[1, 2], [3, 4]], "name": "grid" }
+        ]
+      },
+      "expected": "items[1]:\n  - matrix[2]:\n    - [2]: 1,2\n    - [2]: 3,4\n    name: grid",
+      "specSection": "7"
+    },
+    {
+      "name": "uses tabular format for nested uniform object arrays",
+      "input": {
+        "items": [
+          { "users": [{ "id": 1, "name": "Ada" }, { "id": 2, "name": "Bob" }], "status": "active" }
+        ]
+      },
+      "expected": "items[1]:\n  - users[2]{id,name}:\n    1,Ada\n    2,Bob\n    status: active",
+      "specSection": "7"
+    },
+    {
+      "name": "uses list format for nested object arrays with mismatched keys",
+      "input": {
+        "items": [
+          { "users": [{ "id": 1, "name": "Ada" }, { "id": 2 }], "status": "active" }
+        ]
+      },
+      "expected": "items[1]:\n  - users[2]:\n    - id: 1\n      name: Ada\n    - id: 2\n    status: active",
+      "specSection": "7"
+    },
+    {
+      "name": "uses list format for objects with multiple array fields",
+      "input": {
+        "items": [{ "nums": [1, 2], "tags": ["a", "b"], "name": "test" }]
+      },
+      "expected": "items[1]:\n  - nums[2]: 1,2\n    tags[2]: a,b\n    name: test",
+      "specSection": "7"
+    },
+    {
+      "name": "uses list format for objects with only array fields",
+      "input": {
+        "items": [{ "nums": [1, 2, 3], "tags": ["a", "b"] }]
+      },
+      "expected": "items[1]:\n  - nums[3]: 1,2,3\n    tags[2]: a,b",
+      "specSection": "7"
+    },
+    {
+      "name": "handles objects with empty arrays in list format",
+      "input": {
+        "items": [
+          { "name": "test", "data": [] }
+        ]
+      },
+      "expected": "items[1]:\n  - name: test\n    data[0]:",
+      "specSection": "7"
+    },
+    {
+      "name": "places first field of nested tabular arrays on hyphen line",
+      "input": {
+        "items": [{ "users": [{ "id": 1 }, { "id": 2 }], "note": "x" }]
+      },
+      "expected": "items[1]:\n  - users[2]{id}:\n    1\n    2\n    note: x",
+      "specSection": "7"
+    },
+    {
+      "name": "places empty arrays on hyphen line when first",
+      "input": {
+        "items": [{ "data": [], "name": "x" }]
+      },
+      "expected": "items[1]:\n  - data[0]:\n    name: x",
+      "specSection": "7"
+    },
+    {
+      "name": "uses field order from first object for tabular headers",
+      "input": {
+        "items": [
+          { "a": 1, "b": 2, "c": 3 },
+          { "c": 30, "b": 20, "a": 10 }
+        ]
+      },
+      "expected": "items[2]{a,b,c}:\n  1,2,3\n  10,20,30",
+      "specSection": "7.2"
+    },
+    {
+      "name": "uses list format when one object has nested column",
+      "input": {
+        "items": [
+          { "id": 1, "data": "string" },
+          { "id": 2, "data": { "nested": true } }
+        ]
+      },
+      "expected": "items[2]:\n  - id: 1\n    data: string\n  - id: 2\n    data:\n      nested: true",
+      "specSection": "7"
+    }
+  ]
+}

package/tests/fixtures/encode/arrays-primitive.json

@@ -0,0 +1,87 @@
+{
+  "version": "1.3",
+  "category": "encode",
+  "description": "Primitive array encoding - inline arrays of strings, numbers, booleans",
+  "tests": [
+    {
+      "name": "encodes string arrays inline",
+      "input": {
+        "tags": ["reading", "gaming"]
+      },
+      "expected": "tags[2]: reading,gaming",
+      "specSection": "7.1"
+    },
+    {
+      "name": "encodes number arrays inline",
+      "input": {
+        "nums": [1, 2, 3]
+      },
+      "expected": "nums[3]: 1,2,3",
+      "specSection": "7.1"
+    },
+    {
+      "name": "encodes mixed primitive arrays inline",
+      "input": {
+        "data": ["x", "y", true, 10]
+      },
+      "expected": "data[4]: x,y,true,10",
+      "specSection": "7.1"
+    },
+    {
+      "name": "encodes empty arrays",
+      "input": {
+        "items": []
+      },
+      "expected": "items[0]:",
+      "specSection": "7.1"
+    },
+    {
+      "name": "handles empty string in single-item array",
+      "input": {
+        "items": [""]
+      },
+      "expected": "items[1]: \"\"",
+      "specSection": "7.1"
+    },
+    {
+      "name": "handles empty string in multi-item array",
+      "input": {
+        "items": ["a", "", "b"]
+      },
+      "expected": "items[3]: a,\"\",b",
+      "specSection": "7.1"
+    },
+    {
+      "name": "handles whitespace-only strings in arrays",
+      "input": {
+        "items": [" ", "  "]
+      },
+      "expected": "items[2]: \" \",\"  \"",
+      "specSection": "7.1"
+    },
+    {
+      "name": "quotes array strings with comma",
+      "input": {
+        "items": ["a", "b,c", "d:e"]
+      },
+      "expected": "items[3]: a,\"b,c\",\"d:e\"",
+      "specSection": "7.1"
+    },
+    {
+      "name": "quotes strings that look like booleans in arrays",
+      "input": {
+        "items": ["x", "true", "42", "-3.14"]
+      },
+      "expected": "items[4]: x,\"true\",\"42\",\"-3.14\"",
+      "specSection": "7.1"
+    },
+    {
+      "name": "quotes strings with structural meanings in arrays",
+      "input": {
+        "items": ["[5]", "- item", "{key}"]
+      },
+      "expected": "items[3]: \"[5]\",\"- item\",\"{key}\"",
+      "specSection": "7.1"
+    }
+  ]
+}

package/tests/fixtures/encode/arrays-tabular.json

@@ -0,0 +1,62 @@
+{
+  "version": "1.3",
+  "category": "encode",
+  "description": "Tabular array encoding - arrays of uniform objects with primitive values",
+  "tests": [
+    {
+      "name": "encodes arrays of similar objects in tabular format",
+      "input": {
+        "items": [
+          { "sku": "A1", "qty": 2, "price": 9.99 },
+          { "sku": "B2", "qty": 1, "price": 14.5 }
+        ]
+      },
+      "expected": "items[2]{sku,qty,price}:\n  A1,2,9.99\n  B2,1,14.5",
+      "specSection": "7.2"
+    },
+    {
+      "name": "handles null values in tabular format",
+      "input": {
+        "items": [
+          { "id": 1, "value": null },
+          { "id": 2, "value": "test" }
+        ]
+      },
+      "expected": "items[2]{id,value}:\n  1,null\n  2,test",
+      "specSection": "7.2"
+    },
+    {
+      "name": "quotes strings containing delimiters in tabular rows",
+      "input": {
+        "items": [
+          { "sku": "A,1", "desc": "cool", "qty": 2 },
+          { "sku": "B2", "desc": "wip: test", "qty": 1 }
+        ]
+      },
+      "expected": "items[2]{sku,desc,qty}:\n  \"A,1\",cool,2\n  B2,\"wip: test\",1",
+      "specSection": "7.2"
+    },
+    {
+      "name": "quotes ambiguous strings in tabular rows",
+      "input": {
+        "items": [
+          { "id": 1, "status": "true" },
+          { "id": 2, "status": "false" }
+        ]
+      },
+      "expected": "items[2]{id,status}:\n  1,\"true\"\n  2,\"false\"",
+      "specSection": "7.2"
+    },
+    {
+      "name": "handles tabular arrays with keys needing quotes",
+      "input": {
+        "items": [
+          { "order:id": 1, "full name": "Ada" },
+          { "order:id": 2, "full name": "Bob" }
+        ]
+      },
+      "expected": "items[2]{\"order:id\",\"full name\"}:\n  1,Ada\n  2,Bob",
+      "specSection": "7.2"
+    }
+  ]
+}

package/tests/fixtures/encode/delimiters.json

@@ -0,0 +1,253 @@
+{
+  "version": "1.3",
+  "category": "encode",
+  "description": "Delimiter options - tab and pipe delimiters, delimiter-aware quoting",
+  "tests": [
+    {
+      "name": "encodes primitive arrays with tab delimiter",
+      "input": {
+        "tags": ["reading", "gaming", "coding"]
+      },
+      "expected": "tags[3\t]: reading\tgaming\tcoding",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes primitive arrays with pipe delimiter",
+      "input": {
+        "tags": ["reading", "gaming", "coding"]
+      },
+      "expected": "tags[3|]: reading|gaming|coding",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes primitive arrays with comma delimiter",
+      "input": {
+        "tags": ["reading", "gaming", "coding"]
+      },
+      "expected": "tags[3]: reading,gaming,coding",
+      "options": {
+        "delimiter": ","
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes tabular arrays with tab delimiter",
+      "input": {
+        "items": [
+          { "sku": "A1", "qty": 2, "price": 9.99 },
+          { "sku": "B2", "qty": 1, "price": 14.5 }
+        ]
+      },
+      "expected": "items[2\t]{sku\tqty\tprice}:\n  A1\t2\t9.99\n  B2\t1\t14.5",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes tabular arrays with pipe delimiter",
+      "input": {
+        "items": [
+          { "sku": "A1", "qty": 2, "price": 9.99 },
+          { "sku": "B2", "qty": 1, "price": 14.5 }
+        ]
+      },
+      "expected": "items[2|]{sku|qty|price}:\n  A1|2|9.99\n  B2|1|14.5",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes nested arrays with tab delimiter",
+      "input": {
+        "pairs": [["a", "b"], ["c", "d"]]
+      },
+      "expected": "pairs[2\t]:\n  - [2\t]: a\tb\n  - [2\t]: c\td",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes nested arrays with pipe delimiter",
+      "input": {
+        "pairs": [["a", "b"], ["c", "d"]]
+      },
+      "expected": "pairs[2|]:\n  - [2|]: a|b\n  - [2|]: c|d",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes root arrays with tab delimiter",
+      "input": ["x", "y", "z"],
+      "expected": "[3\t]: x\ty\tz",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes root arrays with pipe delimiter",
+      "input": ["x", "y", "z"],
+      "expected": "[3|]: x|y|z",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes root arrays of objects with tab delimiter",
+      "input": [{ "id": 1 }, { "id": 2 }],
+      "expected": "[2\t]{id}:\n  1\n  2",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "encodes root arrays of objects with pipe delimiter",
+      "input": [{ "id": 1 }, { "id": 2 }],
+      "expected": "[2|]{id}:\n  1\n  2",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "quotes strings containing tab delimiter",
+      "input": {
+        "items": ["a", "b\tc", "d"]
+      },
+      "expected": "items[3\t]: a\t\"b\\tc\"\td",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "quotes strings containing pipe delimiter",
+      "input": {
+        "items": ["a", "b|c", "d"]
+      },
+      "expected": "items[3|]: a|\"b|c\"|d",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "does not quote commas with tab delimiter",
+      "input": {
+        "items": ["a,b", "c,d"]
+      },
+      "expected": "items[2\t]: a,b\tc,d",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "does not quote commas with pipe delimiter",
+      "input": {
+        "items": ["a,b", "c,d"]
+      },
+      "expected": "items[2|]: a,b|c,d",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "quotes tabular values containing comma delimiter",
+      "input": {
+        "items": [
+          { "id": 1, "note": "a,b" },
+          { "id": 2, "note": "c,d" }
+        ]
+      },
+      "expected": "items[2]{id,note}:\n  1,\"a,b\"\n  2,\"c,d\"",
+      "options": {
+        "delimiter": ","
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "does not quote commas in tabular values with tab delimiter",
+      "input": {
+        "items": [
+          { "id": 1, "note": "a,b" },
+          { "id": 2, "note": "c,d" }
+        ]
+      },
+      "expected": "items[2\t]{id\tnote}:\n  1\ta,b\n  2\tc,d",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "does not quote commas in object values with pipe delimiter",
+      "input": {
+        "note": "a,b"
+      },
+      "expected": "note: a,b",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "does not quote commas in object values with tab delimiter",
+      "input": {
+        "note": "a,b"
+      },
+      "expected": "note: a,b",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "quotes nested array values containing pipe delimiter",
+      "input": {
+        "pairs": [["a", "b|c"]]
+      },
+      "expected": "pairs[1|]:\n  - [2|]: a|\"b|c\"",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "quotes nested array values containing tab delimiter",
+      "input": {
+        "pairs": [["a", "b\tc"]]
+      },
+      "expected": "pairs[1\t]:\n  - [2\t]: a\t\"b\\tc\"",
+      "options": {
+        "delimiter": "\t"
+      },
+      "specSection": "8"
+    },
+    {
+      "name": "preserves ambiguity quoting regardless of delimiter",
+      "input": {
+        "items": ["true", "42", "-3.14"]
+      },
+      "expected": "items[3|]: \"true\"|\"42\"|\"-3.14\"",
+      "options": {
+        "delimiter": "|"
+      },
+      "specSection": "8"
+    }
+  ]
+}

package/tests/fixtures/encode/normalization.json

@@ -0,0 +1,107 @@
+{
+  "version": "1.3",
+  "category": "encode",
+  "description": "Non-JSON type normalization - BigInt, Date, undefined, NaN, Infinity, functions, symbols",
+  "tests": [
+    {
+      "name": "converts BigInt to number",
+      "input": 123,
+      "expected": "123",
+      "specSection": "5",
+      "note": "BigInt(123) in JavaScript becomes 123"
+    },
+    {
+      "name": "converts BigInt in object to number",
+      "input": {
+        "id": 456
+      },
+      "expected": "id: 456",
+      "specSection": "5",
+      "note": "BigInt(456) in JavaScript becomes 456"
+    },
+    {
+      "name": "converts Date to ISO string",
+      "input": "2025-01-01T00:00:00.000Z",
+      "expected": "\"2025-01-01T00:00:00.000Z\"",
+      "specSection": "5",
+      "note": "new Date('2025-01-01T00:00:00.000Z') becomes quoted ISO string"
+    },
+    {
+      "name": "converts Date in object to ISO string",
+      "input": {
+        "created": "2025-01-01T00:00:00.000Z"
+      },
+      "expected": "created: \"2025-01-01T00:00:00.000Z\"",
+      "specSection": "5"
+    },
+    {
+      "name": "converts undefined to null",
+      "input": null,
+      "expected": "null",
+      "specSection": "5",
+      "note": "undefined in JavaScript becomes null"
+    },
+    {
+      "name": "converts undefined in object to null",
+      "input": {
+        "value": null
+      },
+      "expected": "value: null",
+      "specSection": "5",
+      "note": "undefined in JavaScript becomes null"
+    },
+    {
+      "name": "converts Infinity to null",
+      "input": null,
+      "expected": "null",
+      "specSection": "5",
+      "note": "Infinity becomes null"
+    },
+    {
+      "name": "converts negative Infinity to null",
+      "input": null,
+      "expected": "null",
+      "specSection": "5",
+      "note": "-Infinity becomes null"
+    },
+    {
+      "name": "converts NaN to null",
+      "input": null,
+      "expected": "null",
+      "specSection": "5",
+      "note": "Number.NaN becomes null"
+    },
+    {
+      "name": "converts function to null",
+      "input": null,
+      "expected": "null",
+      "specSection": "5",
+      "note": "Functions become null"
+    },
+    {
+      "name": "converts function in object to null",
+      "input": {
+        "fn": null
+      },
+      "expected": "fn: null",
+      "specSection": "5",
+      "note": "Functions become null"
+    },
+    {
+      "name": "converts symbol to null",
+      "input": null,
+      "expected": "null",
+      "specSection": "5",
+      "note": "Symbols become null"
+    },
+    {
+      "name": "converts symbol in object to null",
+      "input": {
+        "sym": null
+      },
+      "expected": "sym: null",
+      "specSection": "5",
+      "note": "Symbols become null"
+    }
+  ]
+}