@elaraai/east 1.0.70 → 1.0.71

package/dist/src/serialization/json_schema.js

@@ -0,0 +1,290 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { toEastTypeValue } from "../type_of_type.js";
+import { isVariant } from "../containers/variant.js";
+const SCHEMA_URI = {
+    "2020-12": "https://json-schema.org/draft/2020-12/schema",
+    "draft-07": "http://json-schema.org/draft-07/schema#",
+    // OpenAPI 3.0 schema objects live inside an OpenAPI document and carry no
+    // $schema of their own; stamping one would make the fragment invalid.
+    "openapi-3.0": null,
+};
+/** i64 bounds, as the decoder enforces them. */
+const I64_MAX = "9223372036854775807";
+const I64_MIN_ABS = "9223372036854775808";
+/**
+ * A regex alternation matching every decimal string from `"1"` to `max`, with
+ * no leading zeros. Zero is excluded so the sign can be attached without
+ * admitting `"-0"`, which the encoder never emits.
+ *
+ * @param max - The inclusive upper bound, as decimal digits
+ * @returns An un-anchored alternation body
+ *
+ * @remarks
+ * Generated rather than hand-written because the obvious approximation —
+ * `[1-9][0-9]{0,18}` for i64 — accepts every 19-digit value up to
+ * 9999999999999999999, so an unsigned 64-bit id passes a producer's validator
+ * and then fails on receipt. The construction fixes each prefix of `max` in
+ * turn and lets the digit at that position range below `max`'s.
+ */
+function boundedDigitPattern(max) {
+    const k = max.length;
+    const alts = [];
+    // Every shorter length is unconditionally below the bound; there are none
+    // to add when the bound is itself a single digit.
+    if (k >= 2)
+        alts.push(k === 2 ? "[1-9]" : `[1-9][0-9]{0,${k - 2}}`);
+    let prefix = "";
+    for (let i = 0; i < k; i++) {
+        const digit = max.charCodeAt(i) - 48;
+        const lo = i === 0 ? 1 : 0;
+        if (digit > lo) {
+            const cls = digit - 1 === lo ? `${lo}` : `[${lo}-${digit - 1}]`;
+            const rest = k - i - 1;
+            alts.push(`${prefix}${cls}${rest === 0 ? "" : rest === 1 ? "[0-9]" : `[0-9]{${rest}}`}`);
+        }
+        prefix += max[i];
+    }
+    alts.push(max);
+    return alts.join("|");
+}
+/** The exact accepted form of East JSON's `Integer` encoding. */
+function integerPattern() {
+    return `^(?:0|(?:${boundedDigitPattern(I64_MAX)})|-(?:${boundedDigitPattern(I64_MIN_ABS)}))$`;
+}
+/**
+ * The canonical text `DateTime` encodes to — always UTC, always three
+ * fractional digits, always an explicit `+00:00` offset.
+ *
+ * @remarks
+ * Stricter than the decoder, deliberately: the decoder also accepts a `Z`
+ * suffix and any numeric offset, neither of which the encoder ever emits.
+ * The year is pinned to `0001`–`9999`, the range every runtime reads (python's
+ * datetime starts at year 1), so `0000` is refused by the validator rather
+ * than only by the reader. Every digit class is spelled `[0-9]`, never `\d`:
+ * a validator built on python's `re` reads `\d` as any Unicode digit, so a
+ * timestamp written in Arabic-Indic digits would pass a partner's check and
+ * then fail on receipt. Calendar-impossible dates such as `2026-02-30` still
+ * match — no regex a schema can carry rules them out — and are rejected when
+ * the date is constructed.
+ */
+const DATETIME_PATTERN = "^(?:000[1-9]|00[1-9][0-9]|0[1-9][0-9]{2}|[1-9][0-9]{3})" +
+    "-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])" +
+    "T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\\.[0-9]{3}\\+00:00$";
+/** The canonical text `Blob` encodes to — `0x` and an even count of lowercase hex. */
+const BLOB_PATTERN = "^0x(?:[0-9a-f]{2})*$";
+/** The non-finite floats JSON cannot hold, as the encoder spells them. Sorted for determinism. */
+const FLOAT_SPECIALS = ["-0.0", "-Infinity", "Infinity", "NaN"];
+/**
+ * The exact lexical forms East JSON's scalar encodings take.
+ *
+ * @remarks
+ * Published so a reader can enforce precisely what {@link jsonSchemaFor}
+ * describes — the contract and the check are then one definition, not two that
+ * have to be kept in step by hand. Each is stricter than the historic decoder,
+ * which also accepts hexadecimal and whitespace-padded integers, a `Z` suffix
+ * or any numeric offset on a timestamp, and uppercase hex blobs.
+ */
+export const EAST_JSON_PATTERNS = {
+    /** Decimal i64, no leading zeros, no sign on zero. */
+    get integer() { return integerPattern(); },
+    /** RFC 3339 in UTC with three fractional digits and an explicit `+00:00`. */
+    datetime: DATETIME_PATTERN,
+    /** `0x` followed by an even count of lowercase hex digits. */
+    blob: BLOB_PATTERN,
+    /** The non-finite floats, as strings, in the order the schema lists them. */
+    floatSpecials: FLOAT_SPECIALS,
+};
+/** Where definitions live, and how they are referenced, in a given release. */
+function defsKeyword(draft) {
+    return draft === "2020-12" ? "$defs" : "definitions";
+}
+/**
+ * Emits a JSON Schema describing the East-JSON encoding of an East type.
+ *
+ * @param type - The East type to describe
+ * @param options - Which release to emit
+ * @returns A JSON Schema document
+ * @throws {Error} When the type has no JSON form — `Never`, `Function` or
+ * `AsyncFunction` — naming the offending type
+ *
+ * @remarks
+ * The schema describes what `East.String.printJson` emits and what a strict
+ * reader accepts, so a producer validating against it cannot send a payload
+ * that would then be rejected. It pins the **encoder's** canonical output
+ * rather than the decoder's tolerance: the decoder accepts hexadecimal and
+ * whitespace-padded integers, a `Z` suffix on timestamps and uppercase hex
+ * blobs, and none of those appear here.
+ *
+ * The document is deterministic — key order, `$defs` names and case order are
+ * fixed by the type, not by process state — so the TypeScript and Python
+ * implementations emit byte-identical bytes for the same type and release.
+ *
+ * @example
+ * ```ts
+ * const ReadingType = StructType({ sensor: StringType, litres: IntegerType });
+ * const schema = jsonSchemaFor(ArrayType(ReadingType), { draft: "draft-07" });
+ * writeFileSync("contract.schema.json", JSON.stringify(schema, null, 2));
+ * ```
+ */
+export function jsonSchemaFor(type, options = {}) {
+    const draft = options.draft ?? "2020-12";
+    const typeValue = isVariant(type) ? type : toEastTypeValue(type);
+    const ctx = { draft, defs: {}, names: new Map() };
+    const body = schemaOf(typeValue, ctx);
+    const out = {};
+    const uri = SCHEMA_URI[draft];
+    if (uri !== null)
+        out["$schema"] = uri;
+    for (const [k, v] of Object.entries(body))
+        out[k] = v;
+    if (Object.keys(ctx.defs).length > 0)
+        out[defsKeyword(draft)] = ctx.defs;
+    return out;
+}
+/** The schema for one type node, accumulating any recursive definitions into `ctx`. */
+function schemaOf(t, ctx) {
+    switch (t.type) {
+        case "Never":
+            throw new Error("jsonSchemaFor cannot describe Never — it has no values, so no JSON document satisfies it");
+        case "Function":
+            throw new Error("jsonSchemaFor cannot describe Function — JSON has no function form");
+        case "AsyncFunction":
+            throw new Error("jsonSchemaFor cannot describe AsyncFunction — JSON has no function form");
+        case "Null":
+            // OpenAPI 3.0 predates the "null" type; `nullable` plus a closed enum is
+            // the documented equivalent.
+            return ctx.draft === "openapi-3.0"
+                ? { nullable: true, enum: [null] }
+                : { type: "null" };
+        case "Boolean":
+            return { type: "boolean" };
+        case "String":
+            return { type: "string" };
+        case "Integer":
+            // A JSON number cannot round-trip the upper half of i64, so East JSON
+            // encodes Integer as a decimal string and the pattern pins the range.
+            return { type: "string", pattern: integerPattern(), "x-east-type": "Integer" };
+        case "Float":
+            return {
+                oneOf: [{ type: "number" }, { type: "string", enum: [...FLOAT_SPECIALS] }],
+                "x-east-type": "Float",
+            };
+        case "DateTime":
+            return {
+                type: "string",
+                format: "date-time",
+                pattern: DATETIME_PATTERN,
+                "x-east-type": "DateTime",
+            };
+        case "Blob":
+            return { type: "string", pattern: BLOB_PATTERN, "x-east-type": "Blob" };
+        case "Array":
+            return { type: "array", items: schemaOf(t.value, ctx) };
+        case "Set":
+            return {
+                type: "array",
+                items: schemaOf(t.value, ctx),
+                uniqueItems: true,
+                "x-east-type": "Set",
+            };
+        case "Vector":
+            return {
+                type: "array",
+                items: schemaOf(t.value, ctx),
+                "x-east-type": "Vector",
+            };
+        case "Matrix":
+            // Rows are equal-length, which no release can express without $data; the
+            // reader enforces it.
+            return {
+                type: "array",
+                items: { type: "array", items: schemaOf(t.value, ctx) },
+                "x-east-type": "Matrix",
+            };
+        case "Ref": {
+            // A Ref encodes as a one-element array. The encoder ALSO writes
+            // `{"$ref": …}` once the same target has been written before, but no
+            // reader resolves that back — a streaming reader cannot, having discarded
+            // what the pointer refers to — so advertising it would describe documents
+            // the reader then rejects. It is excluded for the same reason aliasing is
+            // excluded for Array/Set/Dict, and with the same consequence, stated in
+            // the docs: a value with shared references does not validate against its
+            // own published schema.
+            return {
+                type: "array",
+                items: schemaOf(t.value, ctx),
+                minItems: 1,
+                maxItems: 1,
+                "x-east-type": "Ref",
+            };
+        }
+        case "Dict": {
+            const d = t.value;
+            return {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: { key: schemaOf(d.key, ctx), value: schemaOf(d.value, ctx) },
+                    required: ["key", "value"],
+                    additionalProperties: false,
+                },
+                uniqueItems: true,
+                "x-east-type": "Dict",
+            };
+        }
+        case "Struct": {
+            const fields = t.value;
+            const properties = {};
+            for (const f of fields)
+                properties[f.name] = schemaOf(f.type, ctx);
+            return {
+                type: "object",
+                properties,
+                required: fields.map(f => f.name),
+                additionalProperties: false,
+            };
+        }
+        case "Variant": {
+            const cases = t.value;
+            return {
+                oneOf: cases.map(c => ({
+                    type: "object",
+                    properties: {
+                        // draft-04 (and so OpenAPI 3.0) has no `const`; a single-valued
+                        // enum asserts the same thing.
+                        type: ctx.draft === "openapi-3.0" ? { enum: [c.name] } : { const: c.name },
+                        value: schemaOf(c.type, ctx),
+                    },
+                    required: ["type", "value"],
+                    additionalProperties: false,
+                })),
+            };
+        }
+        case "Recursive": {
+            const rec = t.value;
+            if (rec.type === "ref") {
+                const name = ctx.names.get(rec.value);
+                if (name === undefined) {
+                    throw new Error(`jsonSchemaFor: unresolved recursive reference ${rec.value}`);
+                }
+                return { $ref: `#/${defsKeyword(ctx.draft)}/${name}` };
+            }
+            const w = rec.value;
+            // Named by first-encounter order, never by type id: ids come from a
+            // process-global counter, so using them would make the document differ
+            // between runs and between languages.
+            const name = `Recursive${ctx.names.size + 1}`;
+            ctx.names.set(w.id, name);
+            // Reserve the slot before recursing so a back-reference resolves.
+            ctx.defs[name] = {};
+            ctx.defs[name] = schemaOf(w.inner, ctx);
+            return { $ref: `#/${defsKeyword(ctx.draft)}/${name}` };
+        }
+        default:
+            throw new Error(`jsonSchemaFor: unhandled type ${t.type}`);
+    }
+}
+//# sourceMappingURL=json_schema.js.map

package/dist/src/serialization/json_schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json_schema.js","sourceRoot":"","sources":["../../../src/serialization/json_schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAsB,MAAM,oBAAoB,CAAC;AAEzE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAwBrD,MAAM,UAAU,GAA2C;IACzD,SAAS,EAAE,8CAA8C;IACzD,UAAU,EAAE,yCAAyC;IACrD,0EAA0E;IAC1E,sEAAsE;IACtE,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,gDAAgD;AAChD,MAAM,OAAO,GAAG,qBAAqB,CAAC;AACtC,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,SAAS,mBAAmB,CAAC,GAAW;IACtC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IACrB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,kDAAkD;IAClD,IAAI,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEpE,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,GAAG,CAAC,GAAG,CAAC;YAChE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC,CAAC;QAC3F,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,iEAAiE;AACjE,SAAS,cAAc;IACrB,OAAO,YAAY,mBAAmB,CAAC,OAAO,CAAC,SAAS,mBAAmB,CAAC,WAAW,CAAC,KAAK,CAAC;AAChG,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,gBAAgB,GACpB,yDAAyD;IACzD,+CAA+C;IAC/C,iEAAiE,CAAC;AAEpE,sFAAsF;AACtF,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,kGAAkG;AAClG,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,sDAAsD;IACtD,IAAI,OAAO,KAAa,OAAO,cAAc,EAAE,CAAC,CAAC,CAAC;IAClD,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB;IAC1B,8DAA8D;IAC9D,IAAI,EAAE,YAAY;IAClB,6EAA6E;IAC7E,aAAa,EAAE,cAAmC;CAC1C,CAAC;AAUX,+EAA+E;AAC/E,SAAS,WAAW,CAAC,KAAsB;IACzC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,aAAa,CAAC,IAA8B,EAAE,UAA6B,EAAE;IAC3F,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;IACzC,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAsB,CAAC,CAAC,CAAC,eAAe,CAAC,IAAgB,CAAC,CAAC;IAEhG,MAAM,GAAG,GAAgB,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAC/D,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAEtC,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,IAAI;QAAE,GAAG,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC;IACzE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uFAAuF;AACvF,SAAS,QAAQ,CAAC,CAAgB,EAAE,GAAgB;IAClD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,OAAO;YACV,MAAM,IAAI,KAAK,CACb,0FAA0F,CAAC,CAAC;QAChG,KAAK,UAAU;YACb,MAAM,IAAI,KAAK,CACb,oEAAoE,CAAC,CAAC;QAC1E,KAAK,eAAe;YAClB,MAAM,IAAI,KAAK,CACb,yEAAyE,CAAC,CAAC;QAE/E,KAAK,MAAM;YACT,yEAAyE;YACzE,6BAA6B;YAC7B,OAAO,GAAG,CAAC,KAAK,KAAK,aAAa;gBAChC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE;gBAClC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAEvB,KAAK,SAAS;YACZ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAE7B,KAAK,QAAQ;YACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAE5B,KAAK,SAAS;YACZ,sEAAsE;YACtE,sEAAsE;YACtE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;QAEjF,KAAK,OAAO;YACV,OAAO;gBACL,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,cAAc,CAAC,EAAE,CAAC;gBAC1E,aAAa,EAAE,OAAO;aACvB,CAAC;QAEJ,KAAK,UAAU;YACb,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,WAAW;gBACnB,OAAO,EAAE,gBAAgB;gBACzB,aAAa,EAAE,UAAU;aAC1B,CAAC;QAEJ,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;QAE1E,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAsB,EAAE,GAAG,CAAC,EAAE,CAAC;QAE3E,KAAK,KAAK;YACR,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAsB,EAAE,GAAG,CAAC;gBAC9C,WAAW,EAAE,IAAI;gBACjB,aAAa,EAAE,KAAK;aACrB,CAAC;QAEJ,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAsB,EAAE,GAAG,CAAC;gBAC9C,aAAa,EAAE,QAAQ;aACxB,CAAC;QAEJ,KAAK,QAAQ;YACX,yEAAyE;YACzE,sBAAsB;YACtB,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAsB,EAAE,GAAG,CAAC,EAAE;gBACxE,aAAa,EAAE,QAAQ;aACxB,CAAC;QAEJ,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,gEAAgE;YAChE,qEAAqE;YACrE,0EAA0E;YAC1E,0EAA0E;YAC1E,0EAA0E;YAC1E,wEAAwE;YACxE,yEAAyE;YACzE,wBAAwB;YACxB,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAsB,EAAE,GAAG,CAAC;gBAC9C,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,CAAC;gBACX,aAAa,EAAE,KAAK;aACrB,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,CAAC,GAAG,CAAC,CAAC,KAAqD,CAAC;YAClE,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE;oBACxE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC;oBAC1B,oBAAoB,EAAE,KAAK;iBAC5B;gBACD,WAAW,EAAE,IAAI;gBACjB,aAAa,EAAE,MAAM;aACtB,CAAC;QACJ,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,CAAC,CAAC,KAAgD,CAAC;YAClE,MAAM,UAAU,GAAe,EAAE,CAAC;YAClC,KAAK,MAAM,CAAC,IAAI,MAAM;gBAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACnE,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU;gBACV,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBACjC,oBAAoB,EAAE,KAAK;aAC5B,CAAC;QACJ,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,KAAK,GAAG,CAAC,CAAC,KAAgD,CAAC;YACjE,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;oBACrB,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,gEAAgE;wBAChE,+BAA+B;wBAC/B,IAAI,EAAE,GAAG,CAAC,KAAK,KAAK,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE;wBAC1E,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC;qBAC7B;oBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;oBAC3B,oBAAoB,EAAE,KAAK;iBAC5B,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;QAED,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,MAAM,GAAG,GAAG,CAAC,CAAC,KAAgD,CAAC;YAC/D,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;gBACvB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAe,CAAC,CAAC;gBAChD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACvB,MAAM,IAAI,KAAK,CAAC,iDAAiD,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;gBAChF,CAAC;gBACD,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;YACzD,CAAC;YACD,MAAM,CAAC,GAAG,GAAG,CAAC,KAA6C,CAAC;YAC5D,oEAAoE;YACpE,uEAAuE;YACvE,sCAAsC;YACtC,MAAM,IAAI,GAAG,YAAY,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAC1B,kEAAkE;YAClE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACpB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;QACzD,CAAC;QAED;YACE,MAAM,IAAI,KAAK,CAAC,iCAAkC,CAAyB,CAAC,IAAI,EAAE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC"}

package/dist/src/serialization/json_schema.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=json_schema.spec.d.ts.map

package/dist/src/serialization/json_schema.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json_schema.spec.d.ts","sourceRoot":"","sources":["../../../src/serialization/json_schema.spec.ts"],"names":[],"mappings":""}

package/dist/src/serialization/json_schema.spec.js

@@ -0,0 +1,327 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { ArrayType, AsyncFunctionType, BlobType, BooleanType, DateTimeType, DictType, FloatType, FunctionType, IntegerType, MatrixType, NeverType, NullType, OptionType, RecursiveType, RefType, SetType, StringType, StructType, VariantType, VectorType, } from "../types.js";
+import { EAST_JSON_PATTERNS, jsonSchemaFor } from "./json_schema.js";
+import { toJSONFor } from "./json.js";
+/** The pattern a leaf type's schema pins, as a compiled regex. */
+function patternOf(schema) {
+    const pattern = schema["pattern"];
+    assert.equal(typeof pattern, "string", "expected the schema to carry a pattern");
+    return new RegExp(pattern);
+}
+/** A schema with `$schema` dropped, for comparing the body alone. */
+function body(schema) {
+    const { $schema: _drop, ...rest } = schema;
+    return rest;
+}
+describe("jsonSchemaFor", () => {
+    describe("primitives", () => {
+        test("describes Null, Boolean and String directly", () => {
+            assert.deepEqual(body(jsonSchemaFor(NullType)), { type: "null" });
+            assert.deepEqual(body(jsonSchemaFor(BooleanType)), { type: "boolean" });
+            assert.deepEqual(body(jsonSchemaFor(StringType)), { type: "string" });
+        });
+        test("describes Float as a number or one of the non-finite spellings", () => {
+            assert.deepEqual(body(jsonSchemaFor(FloatType)), {
+                oneOf: [
+                    { type: "number" },
+                    { type: "string", enum: ["-0.0", "-Infinity", "Infinity", "NaN"] },
+                ],
+                "x-east-type": "Float",
+            });
+        });
+        test("stamps $schema for the releases that carry one", () => {
+            assert.equal(jsonSchemaFor(StringType)["$schema"], "https://json-schema.org/draft/2020-12/schema");
+            assert.equal(jsonSchemaFor(StringType, { draft: "draft-07" })["$schema"], "http://json-schema.org/draft-07/schema#");
+            // An OpenAPI 3.0 schema object lives inside an OpenAPI document and
+            // has no $schema of its own.
+            assert.equal(jsonSchemaFor(StringType, { draft: "openapi-3.0" })["$schema"], undefined);
+        });
+    });
+    describe("Integer", () => {
+        const pattern = patternOf(jsonSchemaFor(IntegerType));
+        test("accepts exactly the i64 range", () => {
+            for (const ok of ["0", "1", "-1", "42", "9223372036854775807", "-9223372036854775808"]) {
+                assert.ok(pattern.test(ok), `${ok} should be accepted`);
+            }
+            for (const bad of ["9223372036854775808", "-9223372036854775809"]) {
+                assert.ok(!pattern.test(bad), `${bad} should be rejected`);
+            }
+        });
+        test("rejects an unsigned 64-bit id", () => {
+            // The naive `^(0|-?[1-9][0-9]{0,18})$` admits this, so a producer
+            // would validate it and we would then reject it on receipt.
+            assert.ok(!pattern.test("18446744073709551615"));
+            assert.ok(!pattern.test("9999999999999999999"));
+        });
+        test("rejects everything the decoder tolerates but the encoder never emits", () => {
+            // BigInt() accepts all of these; the published contract must not.
+            for (const bad of ["0x10", "0b101", "0o17", " 7 ", "+7", "007", "-0", "", "1e3", "7.5"]) {
+                assert.ok(!pattern.test(bad), `${JSON.stringify(bad)} should be rejected`);
+            }
+        });
+        test("accepts everything the encoder emits", () => {
+            const encode = toJSONFor(IntegerType);
+            const values = [
+                0n, 1n, -1n, 7n, -7n, 10n, 99n, 100n, 12345n, -12345n,
+                9007199254740993n, -9007199254740993n,
+                9223372036854775807n, -9223372036854775808n,
+            ];
+            for (const v of values) {
+                assert.ok(pattern.test(encode(v)), `encoder output for ${v} should validate`);
+            }
+        });
+    });
+    describe("DateTime", () => {
+        const pattern = patternOf(jsonSchemaFor(DateTimeType));
+        test("accepts the canonical form the encoder emits", () => {
+            const encode = toJSONFor(DateTimeType);
+            for (const d of [new Date(0), new Date("2022-06-29T13:43:00.123Z"), new Date("2026-12-31T23:59:59.999Z")]) {
+                assert.ok(pattern.test(encode(d)), `${encode(d)} should validate`);
+            }
+        });
+        test("rejects the offsets the decoder tolerates", () => {
+            // The decoder takes a Z suffix or any numeric offset; the encoder
+            // only ever writes +00:00, so the contract pins that.
+            assert.ok(!pattern.test("2022-06-29T13:43:00.123Z"));
+            assert.ok(!pattern.test("2022-06-29T13:43:00.123+05:00"));
+            assert.ok(!pattern.test("2022-06-29T13:43:00.123-08:00"));
+        });
+        test("rejects out-of-range calendar fields", () => {
+            for (const bad of [
+                "0000-01-01T00:00:00.000+00:00", // year 0, below the range every runtime reads
+                "2022-13-29T13:43:00.123+00:00", // month 13
+                "2022-06-32T13:43:00.123+00:00", // day 32
+                "2022-06-29T24:43:00.123+00:00", // hour 24
+                "2022-06-29T13:60:00.123+00:00", // minute 60
+                "2022-06-29T13:43:60.123+00:00", // second 60
+                "2022-06-29T13:43:00+00:00", // no milliseconds
+                "2022-06-29 13:43:00.123+00:00", // space, not T
+            ]) {
+                assert.ok(!pattern.test(bad), `${bad} should be rejected`);
+            }
+        });
+        test("accepts the first and last years the reader does", () => {
+            assert.ok(pattern.test("0001-01-01T00:00:00.000+00:00"));
+            assert.ok(pattern.test("9999-12-31T23:59:59.999+00:00"));
+        });
+    });
+    describe("digit classes", () => {
+        test("spells every digit as [0-9], never \\d", () => {
+            // A validator built on python's `re` reads \d as any Unicode digit,
+            // so a timestamp in Arabic-Indic digits would pass a partner's check
+            // and then fail on receipt. The contract has to read the same on
+            // every regex engine a partner might use.
+            for (const p of [EAST_JSON_PATTERNS.integer, EAST_JSON_PATTERNS.datetime, EAST_JSON_PATTERNS.blob]) {
+                assert.ok(!p.includes("\\d"), `${p} must not use \\d`);
+            }
+        });
+    });
+    describe("Blob", () => {
+        const pattern = patternOf(jsonSchemaFor(BlobType));
+        test("accepts the lowercase hex the encoder emits", () => {
+            const encode = toJSONFor(BlobType);
+            assert.ok(pattern.test(encode(new Uint8Array([]))));
+            assert.ok(pattern.test(encode(new Uint8Array([1, 3, 3, 7]))));
+            assert.ok(pattern.test(encode(new Uint8Array([0xde, 0xad, 0xbe, 0xef]))));
+        });
+        test("rejects uppercase hex, which only the decoder allows", () => {
+            assert.ok(!pattern.test("0xDEADBEEF"));
+            assert.ok(!pattern.test("0xAb"));
+        });
+        test("rejects a missing prefix or an odd digit count", () => {
+            assert.ok(!pattern.test("deadbeef"));
+            assert.ok(!pattern.test("0x123"));
+            assert.ok(!pattern.test("0xgg"));
+        });
+    });
+    describe("collections", () => {
+        test("describes Array as an array of its element", () => {
+            assert.deepEqual(body(jsonSchemaFor(ArrayType(StringType))), {
+                type: "array",
+                items: { type: "string" },
+            });
+        });
+        test("marks Set unique", () => {
+            assert.deepEqual(body(jsonSchemaFor(SetType(StringType))), {
+                type: "array",
+                items: { type: "string" },
+                uniqueItems: true,
+                "x-east-type": "Set",
+            });
+        });
+        test("describes Dict as its array-of-entries encoding", () => {
+            assert.deepEqual(body(jsonSchemaFor(DictType(StringType, BooleanType))), {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: { key: { type: "string" }, value: { type: "boolean" } },
+                    required: ["key", "value"],
+                    additionalProperties: false,
+                },
+                uniqueItems: true,
+                "x-east-type": "Dict",
+            });
+        });
+        test("closes Struct to its declared fields, all required", () => {
+            const schema = body(jsonSchemaFor(StructType({ a: StringType, b: BooleanType })));
+            assert.equal(schema["type"], "object");
+            assert.deepEqual(schema["required"], ["a", "b"]);
+            assert.equal(schema["additionalProperties"], false);
+        });
+        test("describes Vector and Matrix as arrays", () => {
+            assert.deepEqual(body(jsonSchemaFor(VectorType(FloatType)))["type"], "array");
+            const m = body(jsonSchemaFor(MatrixType(IntegerType)));
+            assert.equal(m["type"], "array");
+            assert.equal(m["items"]["type"], "array");
+        });
+        test("describes Ref as a one-element array, without the aliasing form", () => {
+            // The encoder ALSO writes {"$ref": …} for a target it has already
+            // written, but no reader resolves that back — a streaming reader has
+            // discarded what the pointer refers to — so advertising it would
+            // describe documents the reader then rejects. Excluded for the same
+            // reason as Array/Set/Dict aliasing, with the same stated
+            // consequence: a value with shared references does not validate
+            // against its own published schema.
+            assert.deepEqual(body(jsonSchemaFor(RefType(StringType))), {
+                type: "array",
+                items: { type: "string" },
+                minItems: 1,
+                maxItems: 1,
+                "x-east-type": "Ref",
+            });
+        });
+    });
+    describe("Variant", () => {
+        test("pins each case's tag and closes the object", () => {
+            const schema = body(jsonSchemaFor(VariantType({ ok: IntegerType, err: StringType })));
+            const alternatives = schema["oneOf"];
+            // VariantType sorts its cases, so the order is fixed by the type.
+            assert.equal(alternatives.length, 2);
+            const tags = alternatives.map(a => a["properties"]["type"]["const"]);
+            assert.deepEqual(tags, ["err", "ok"]);
+            for (const a of alternatives) {
+                assert.deepEqual(a["required"], ["type", "value"]);
+                assert.equal(a["additionalProperties"], false);
+            }
+        });
+        test("uses a single-valued enum where the release has no const", () => {
+            const schema = body(jsonSchemaFor(OptionType(StringType), { draft: "openapi-3.0" }));
+            const alternatives = schema["oneOf"];
+            const tag = alternatives[0]["properties"]["type"];
+            assert.deepEqual(tag["enum"], ["none"]);
+            assert.equal(tag["const"], undefined);
+        });
+    });
+    describe("recursive types", () => {
+        const LinkedListType = RecursiveType((self) => VariantType({
+            nil: NullType,
+            cons: StructType({ head: IntegerType, tail: self }),
+        }));
+        test("lifts the body into $defs and refers to it", () => {
+            const schema = jsonSchemaFor(LinkedListType);
+            assert.deepEqual(body(schema)["$ref"], "#/$defs/Recursive1");
+            const defs = schema["$defs"];
+            assert.ok(defs["Recursive1"] !== undefined);
+        });
+        test("names definitions by encounter order, not by type id", () => {
+            // Type ids come from a process-global counter, so a document keyed
+            // on them would differ between runs and between languages.
+            const a = JSON.stringify(jsonSchemaFor(LinkedListType));
+            const b = JSON.stringify(jsonSchemaFor(LinkedListType));
+            assert.equal(a, b);
+            assert.ok(a.includes("Recursive1"));
+            assert.ok(!/Recursive[0-9]{2,}/.test(a));
+        });
+        test("uses the release's definitions keyword", () => {
+            const seven = jsonSchemaFor(LinkedListType, { draft: "draft-07" });
+            assert.deepEqual(body(seven)["$ref"], "#/definitions/Recursive1");
+            assert.ok(seven["definitions"] !== undefined);
+            assert.equal(seven["$defs"], undefined);
+        });
+    });
+    describe("releases", () => {
+        test("spells Null without a null type on OpenAPI 3.0", () => {
+            assert.deepEqual(body(jsonSchemaFor(NullType, { draft: "openapi-3.0" })), {
+                nullable: true,
+                enum: [null],
+            });
+        });
+        test("pins the same integer range in every release", () => {
+            const p2020 = jsonSchemaFor(IntegerType)["pattern"];
+            const p07 = jsonSchemaFor(IntegerType, { draft: "draft-07" })["pattern"];
+            const pOas = jsonSchemaFor(IntegerType, { draft: "openapi-3.0" })["pattern"];
+            assert.equal(p2020, p07);
+            assert.equal(p07, pOas);
+        });
+    });
+    describe("types with no JSON form", () => {
+        test("refuses Never, naming it", () => {
+            assert.throws(() => jsonSchemaFor(NeverType), /cannot describe Never/);
+        });
+        test("refuses functions, naming them", () => {
+            assert.throws(() => jsonSchemaFor(FunctionType([], IntegerType)), /cannot describe Function/);
+            assert.throws(() => jsonSchemaFor(AsyncFunctionType([], IntegerType)), /cannot describe AsyncFunction/);
+        });
+        test("refuses a function nested inside a collection", () => {
+            assert.throws(() => jsonSchemaFor(StructType({ f: FunctionType([], IntegerType) })), /cannot describe Function/);
+        });
+    });
+    test("matches the cross-language corpus digest", () => {
+        // The python twin asserts this same digest over the same corpus in the
+        // same order (east-py tests/serialization/test_json_schema.py). Two
+        // languages agreeing on one hash is what keeps a partner from being
+        // handed different contracts; changing the emitted bytes deliberately
+        // means updating both constants, which is the point.
+        const RecursiveCorpusType = RecursiveType((self) => VariantType({
+            nil: NullType,
+            cons: StructType({ head: IntegerType, tail: self }),
+        }));
+        const corpus = [
+            ["Null", NullType], ["Boolean", BooleanType], ["Integer", IntegerType],
+            ["Float", FloatType], ["String", StringType], ["DateTime", DateTimeType],
+            ["Blob", BlobType],
+            ["Array", ArrayType(IntegerType)], ["Set", SetType(StringType)],
+            ["Dict", DictType(StringType, IntegerType)],
+            ["Struct", StructType({ a: StringType, b: IntegerType, c: DateTimeType })],
+            ["Variant", VariantType({ ok: IntegerType, err: StringType })],
+            ["Option", OptionType(StringType)],
+            ["Ref", RefType(IntegerType)],
+            ["Vector", VectorType(FloatType)], ["Matrix", MatrixType(IntegerType)],
+            ["nested", ArrayType(StructType({
+                    id: IntegerType, tags: SetType(StringType),
+                    note: OptionType(StringType), when: DateTimeType,
+                }))],
+            ["recursive", RecursiveCorpusType],
+            ["arrayRecursive", ArrayType(RecursiveCorpusType)],
+        ];
+        const lines = [];
+        for (const draft of ["2020-12", "draft-07", "openapi-3.0"]) {
+            for (const [name, type] of corpus) {
+                lines.push(`${draft}|${name}=${JSON.stringify(jsonSchemaFor(type, { draft }))}`);
+            }
+        }
+        assert.equal(lines.length, 57);
+        assert.equal(createHash("sha256").update(lines.join("\n")).digest("hex"), "7083a9ae6f830e8724c707c0f0636a57be01fe2085874e83fea00883401c1a6b");
+    });
+    test("emits byte-identical documents for the same type and release", () => {
+        const T = StructType({
+            id: IntegerType,
+            at: DateTimeType,
+            tags: SetType(StringType),
+            note: OptionType(StringType),
+            blob: BlobType,
+        });
+        for (const draft of ["2020-12", "draft-07", "openapi-3.0"]) {
+            const first = JSON.stringify(jsonSchemaFor(ArrayType(T), { draft }));
+            const second = JSON.stringify(jsonSchemaFor(ArrayType(T), { draft }));
+            assert.equal(first, second, `${draft} output should be stable`);
+        }
+    });
+});
+//# sourceMappingURL=json_schema.spec.js.map