@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/serial-json.compat.test.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_vm_1 = require("node:vm");
+const msgpack_1 = require("@msgpack/msgpack");
+const serial_json_1 = require("./serial-json");
+const oracle = require("./serial-json.oracle");
+// Strings and keys that exercise every marker the decoder interprets. "__WINDOW" is left out
+// because the oracle decodes it to `window`, which throws in Node.
+const STRINGS = [
+    "",
+    "plain",
+    "héllo 世界 🚀",
+    "$dollar",
+    "__",
+    "__UNDEFINED",
+    "__NAN",
+    "__INFINITY",
+    "__DATE 2023-01-01T00:00:00.000Z",
+    "__DATE garbage",
+    "__REGEXP /a.c/g",
+    "__ERROR Error: x\n    at nowhere",
+    "__UINT8ARRAY AQID",
+    "__BUFFER AQID",
+    "__HTML <b>x</b>",
+    "__FUNCTION f(){}",
+    "__duplicate_ref_obj_7",
+    "__duplicate_ref_ary_3",
+    "__this_ref:__duplicate_ref_ary_5",
+    "__DOLLAR_x",
+];
+const KEYS = ["a", "b", "c", "0", "$a", "$", "__DOLLAR_b", "__this_ref", "constructor", "toString"];
+const NUMBERS = [0, 1, -1, 1.5, -0, NaN, Infinity, -Infinity, 1e21, Number.MAX_SAFE_INTEGER];
+/** Deterministic PRNG (mulberry32), so a failure names a reproducible seed. */
+function prng(seed) {
+    let state = seed;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** A random value graph mixing extended types, marker-like strings, shared nodes and cycles. */
+function generate(seed) {
+    const random = prng(seed);
+    const pick = (items) => items[Math.floor(random() * items.length)];
+    const pool = [];
+    const ancestors = [];
+    function leaf() {
+        switch (Math.floor(random() * 11)) {
+            case 0:
+            case 1:
+                return pick(STRINGS);
+            case 2:
+                return pick(NUMBERS);
+            case 3:
+                return random() < 0.5;
+            case 4:
+                return null;
+            case 5:
+                return undefined;
+            case 6:
+                return new Date(Math.floor(random() * 4e12));
+            case 7:
+                return random() < 0.5 ? new Uint8Array([1, 2, 3]) : Buffer.from([4, 5]);
+            case 8:
+                return new RegExp(pick(["a.c", "^x$", "[0-9]+"]), pick(["", "g", "gi"]));
+            case 9:
+                return new Error(pick(["boom", ""]));
+            default:
+                return () => 1;
+        }
+    }
+    function value(depth) {
+        const roll = random();
+        if (roll < 0.06 && pool.length)
+            return pick(pool);
+        if (roll < 0.09 && ancestors.length)
+            return pick(ancestors);
+        if (depth <= 0 || roll > 0.45)
+            return leaf();
+        const container = random() < 0.5 ? [] : {};
+        ancestors.push(container);
+        const size = Math.floor(random() * 5);
+        for (let i = 0; i < size; i++) {
+            const child = value(depth - 1);
+            if (Array.isArray(container))
+                container.push(child);
+            else
+                container[pick(KEYS)] = child;
+        }
+        ancestors.pop();
+        pool.push(container);
+        return container;
+    }
+    // Top level is always a container, as in columns, change values and messages.
+    let root = value(4);
+    while (root === null || typeof root !== "object" || root instanceof Date)
+        root = value(4);
+    return root;
+}
+function deepFreeze(value) {
+    // Typed arrays with elements can't be frozen; nothing writes to them anyway.
+    if (value && typeof value === "object" && !ArrayBuffer.isView(value) && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+/**
+ * First difference between two value graphs, or null. Compares types, prototypes, values, key
+ * order, and sharing: a node shared (or cyclic) in one graph must be shared the same way in the other.
+ */
+function graphDiff(actual, expected, path = "$", pairs = new Map(), reversePairs = new Map()) {
+    if (typeof actual !== typeof expected)
+        return `${path}: ${typeof actual} vs ${typeof expected}`;
+    if (typeof actual === "number")
+        return Object.is(actual, expected) ? null : `${path}: ${actual} vs ${expected}`;
+    if (actual === null || expected === null || typeof actual !== "object") {
+        return actual === expected ? null : `${path}: ${String(actual)} vs ${String(expected)}`;
+    }
+    const a = actual;
+    const b = expected;
+    if (pairs.has(a) || reversePairs.has(b)) {
+        return pairs.get(a) === b ? null : `${path}: sharing differs`;
+    }
+    pairs.set(a, b);
+    reversePairs.set(b, a);
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b))
+        return `${path}: prototype differs`;
+    if (Array.isArray(a) && a.length !== b.length)
+        return `${path}: array length differs`;
+    if (a instanceof Date)
+        return Object.is(a.getTime(), b.getTime()) ? null : `${path}: date differs`;
+    if (a instanceof RegExp)
+        return String(a) === String(b) ? null : `${path}: regexp differs`;
+    if (a instanceof Error)
+        return a.stack === b.stack ? null : `${path}: error stack differs`;
+    if (a instanceof Uint8Array)
+        return Buffer.compare(a, b) === 0 ? null : `${path}: bytes differ`;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length || keysA.some((key, index) => key !== keysB[index])) {
+        return `${path}: keys [${keysA}] vs [${keysB}]`;
+    }
+    for (const key of keysA) {
+        const diff = graphDiff(a[key], b[key], `${path}.${key}`, pairs, reversePairs);
+        if (diff)
+            return diff;
+    }
+    return null;
+}
+const SEEDS = Array.from({ length: 1500 }, (_, i) => i + 1);
+/**
+ * True when an encoded tree tags an object with an `_ary_` marker or an array with an `_obj_`
+ * one. toJSON only writes that when a user string collides with a marker; the live decoder no
+ * longer merges such a pair (see "does not let an object fill an array target" in
+ * serial-json.test.ts), so those seeds are compared separately.
+ */
+function hasMixedKindTag(encoded) {
+    if (Array.isArray(encoded)) {
+        const [first] = encoded;
+        if (typeof first === "string" && first.startsWith("__this_ref:") && first.includes("_obj_")) {
+            return true;
+        }
+        return encoded.some(hasMixedKindTag);
+    }
+    if (encoded && typeof encoded === "object") {
+        const tag = encoded.__this_ref;
+        if (typeof tag === "string" && tag.includes("_ary_"))
+            return true;
+        return Object.values(encoded).some(hasMixedKindTag);
+    }
+    return false;
+}
+describe("serial-json compatibility with the frozen oracle", () => {
+    // The corpus holds marker-like strings with no target; the live decoder warns about those.
+    beforeAll(() => {
+        jest.spyOn(console, "warn").mockImplementation(() => undefined);
+    });
+    afterAll(() => {
+        jest.restoreAllMocks();
+    });
+    it("detects differences in values, key order, sparse lengths and sharing", () => {
+        const shared = {};
+        expect(graphDiff({ x: 1 }, { x: 2 })).not.toBeNull();
+        expect(graphDiff({ x: 1, y: 2 }, { y: 2, x: 1 })).not.toBeNull();
+        expect(graphDiff({ "a\u0000b": undefined }, { a: undefined, b: undefined })).not.toBeNull();
+        expect(graphDiff([], new Array(1))).not.toBeNull();
+        expect(graphDiff([shared, shared], [{}, {}])).not.toBeNull();
+        expect(graphDiff([{}, {}], [shared, shared])).not.toBeNull();
+        const cycle = {};
+        cycle.self = cycle;
+        expect(graphDiff(cycle, { self: {} })).not.toBeNull();
+    });
+    it.each([
+        ["sparse arrays", () => ({ a: new Array(3), b: Object.assign(new Array(3), { 0: 1, 2: 3 }) })],
+        ["null prototypes", () => Object.assign(Object.create(null), { a: 1, $b: {} })],
+        ["boxed strings", () => ({ a: new String("__DATE 2000-01-01") })],
+        [
+            "another realm",
+            () => (0, node_vm_1.runInNewContext)("({ a: [1, , 3], d: new Date(0), r: /x/g, u: new Uint8Array([1]) })"),
+        ],
+        [
+            "getters that change later properties",
+            () => {
+                const value = {
+                    a: {
+                        get x() {
+                            value.b = 2;
+                            return value;
+                        },
+                    },
+                    b: 1,
+                };
+                return value;
+            },
+        ],
+        [
+            "callables inheriting from RegExp",
+            () => {
+                const value = () => 1;
+                Object.setPrototypeOf(value, RegExp.prototype);
+                value.toString = () => "/x/g";
+                return value;
+            },
+        ],
+    ])("encodes %s exactly like the oracle", (_name, makeValue) => {
+        expect((0, serial_json_1.toJSONString)(makeValue())).toBe(oracle.toJSONString(makeValue()));
+        expect(graphDiff((0, serial_json_1.toJSON)(makeValue()), oracle.toJSON(makeValue()))).toBeNull();
+    });
+    // A tag that names a target of the other kind (object vs array) is an intended difference; see
+    // serial-json.test.ts.
+    it.each([
+        [["__this_ref:__duplicate_ref_obj_1", 1, 2], "__duplicate_ref_obj_1"],
+        [
+            { __this_ref: "__duplicate_ref_obj_1", a: 1 },
+            { __this_ref: "__duplicate_ref_obj_1", b: 2 },
+            "__duplicate_ref_obj_1",
+        ],
+        [
+            "__duplicate_ref_ary_1",
+            ["__this_ref:__duplicate_ref_ary_1", "first", "extra"],
+            ["__this_ref:__duplicate_ref_ary_1", "last"],
+        ],
+        ["__this_ref:__duplicate_ref_ary_1:ignored", "__duplicate_ref_ary_1"],
+        [
+            { __this_ref: 1, a: 1 },
+            { __this_ref: "1", b: 2 },
+        ],
+    ].map((value) => [value]))("decodes unusual and repeated tags: %j", (value) => {
+        expect(graphDiff((0, serial_json_1.fromJSON)(deepFreeze(value)), oracle.fromJSON(value))).toBeNull();
+    });
+    it.each([
+        "plain",
+        "__UNDEFINED",
+        "__NAN",
+        "__DATE 2000-01-01",
+        "__REGEXP /x/g",
+        "__BUFFER AQID",
+        "__duplicate_ref_obj_boxed",
+    ])("decodes boxed strings like the oracle: %s", (text) => {
+        expect(graphDiff((0, serial_json_1.fromJSON)(new String(text)), oracle.fromJSON(new String(text)))).toBeNull();
+    });
+    it("recognizes a boxed array tag", () => {
+        const value = [new String("__this_ref:__duplicate_ref_ary_1"), "__duplicate_ref_ary_1"];
+        expect(graphDiff((0, serial_json_1.fromJSON)(value), oracle.fromJSON(value))).toBeNull();
+    });
+    it("generates graphs with sharing, cycles and every marker", () => {
+        // Guards the corpus itself: if the generator stops producing these, the checks below go soft.
+        let sharing = false;
+        let cycles = false;
+        const visit = (value, seen, ancestors) => {
+            if (!value || typeof value !== "object")
+                return;
+            if (ancestors.has(value))
+                cycles = true;
+            if (seen.has(value)) {
+                sharing = true;
+                return;
+            }
+            seen.add(value);
+            ancestors.add(value);
+            for (const child of Object.values(value))
+                visit(child, seen, ancestors);
+            ancestors.delete(value);
+        };
+        for (const seed of SEEDS)
+            visit(generate(seed), new Set(), new Set());
+        expect(sharing).toBe(true);
+        expect(cycles).toBe(true);
+        const encoded = SEEDS.map((seed) => oracle.toJSONString(generate(seed))).join("\n");
+        for (const marker of [
+            "__this_ref",
+            "__duplicate_ref_ary_",
+            "__DOLLAR_",
+            "__DATE",
+            "__ERROR",
+            "__BUFFER",
+            "__UINT8ARRAY",
+            "__UNDEFINED",
+            "__NAN",
+            "__INFINITY",
+            "__REGEXP",
+            "__FUNCTION",
+        ]) {
+            expect(encoded).toContain(marker);
+        }
+    });
+    it("encodes byte-identically, as text and as an in-memory tree", () => {
+        for (const seed of SEEDS) {
+            const value = generate(seed);
+            expect({ seed, text: (0, serial_json_1.toJSONString)(value) }).toEqual({
+                seed,
+                text: oracle.toJSONString(value),
+            });
+            expect({ seed, diff: graphDiff((0, serial_json_1.toJSON)(value), oracle.toJSON(value)) }).toEqual({
+                seed,
+                diff: null,
+            });
+        }
+    });
+    const MIXED_KIND_SEEDS = new Set(SEEDS.filter((seed) => hasMixedKindTag(oracle.toJSON(generate(seed)))));
+    it("has a few mixed-kind tags from marker-like strings, and decodes them differently", () => {
+        expect(MIXED_KIND_SEEDS.size).toBeGreaterThan(0);
+        expect(MIXED_KIND_SEEDS.size).toBeLessThan(SEEDS.length / 20);
+        let differing = 0;
+        for (const seed of MIXED_KIND_SEEDS) {
+            const text = oracle.toJSONString(generate(seed));
+            if (graphDiff((0, serial_json_1.fromJSON)(JSON.parse(text)), oracle.fromJSON(JSON.parse(text))))
+                differing++;
+        }
+        expect(differing).toBeGreaterThan(0);
+    });
+    it("decodes the oracle's JSON text the same way, without mutating it", () => {
+        for (const seed of SEEDS) {
+            if (MIXED_KIND_SEEDS.has(seed))
+                continue;
+            const text = oracle.toJSONString(generate(seed));
+            const decoded = (0, serial_json_1.fromJSON)(deepFreeze(JSON.parse(text)));
+            const expected = oracle.fromJSON(deepFreeze(JSON.parse(text)));
+            expect({ seed, diff: graphDiff(decoded, expected) }).toEqual({ seed, diff: null });
+        }
+    });
+    it("decodes msgpack-decoded trees (the device wire) the same way", () => {
+        for (const seed of SEEDS) {
+            if (MIXED_KIND_SEEDS.has(seed))
+                continue;
+            const bytes = (0, msgpack_1.encode)(oracle.toJSON(generate(seed)));
+            const decoded = (0, serial_json_1.fromJSON)(deepFreeze((0, msgpack_1.decode)(bytes)));
+            const expected = oracle.fromJSON(deepFreeze((0, msgpack_1.decode)(bytes)));
+            expect({ seed, diff: graphDiff(decoded, expected) }).toEqual({ seed, diff: null });
+        }
+    });
+    it("produces output the oracle decodes the same way as its own", () => {
+        for (const seed of SEEDS) {
+            const value = generate(seed);
+            const decoded = oracle.fromJSON(JSON.parse((0, serial_json_1.toJSONString)(value)));
+            const expected = oracle.fromJSON(JSON.parse(oracle.toJSONString(value)));
+            expect({ seed, diff: graphDiff(decoded, expected) }).toEqual({ seed, diff: null });
+        }
+    });
+    it("never mutates the value it encodes", () => {
+        for (const seed of SEEDS.slice(0, 300)) {
+            expect(() => (0, serial_json_1.toJSONString)(deepFreeze(generate(seed)))).not.toThrow();
+        }
+    });
+});

package/dist/serial-json.d.ts

@@ -1,13 +1,49 @@
-/** True for plain object literals (excludes array, Date, and null). */
+/**
+ * True for any non-null object or function that isn't an array or a Date. Despite the name, class
+ * instances, Maps and RegExps count.
+ */
 export declare function isObject(x: any): x is Record<string, any>;
 /**
- * Clones a value into a JSON-serializable tree: Dates, Buffers, cycles, `undefined`, `NaN`, RegExp, etc. use sentinel strings.
- * Shared references are preserved with `__duplicate_ref_*` and `__this_ref` markers for {@link fromJSON}.
+ * Encodes a value as a JSON-safe tree, using in-band sentinel strings for what JSON can't hold:
+ * - `undefined`, `NaN`, `Infinity` → `"__UNDEFINED"`, `"__NAN"`, `"__INFINITY"`
+ * - Date → `"__DATE <ISO>"`, RegExp → `"__REGEXP /src/flags"`, Error → `"__ERROR <stack>"`
+ * - Buffer → `"__BUFFER <base64>"`, Uint8Array → `"__UINT8ARRAY <base64>"`
+ * - functions → `"__FUNCTION <source>"` (one-way: {@link fromJSON} leaves the string)
+ * - keys starting with `$` → `__DOLLAR_…`
+ *
+ * A shared object or array (including a cycle) is copied once: the first copy is tagged with a
+ * `__this_ref` key (objects) or a `"__this_ref:<marker>"` first element (arrays), and every other
+ * occurrence becomes the `__duplicate_ref_obj_N` / `__duplicate_ref_ary_N` marker string. The
+ * markers only resolve when the whole tree is decoded together.
+ *
+ * Map, Set and class instances become plain objects, `-Infinity` and `-0` survive the tree but
+ * not `JSON.stringify`. BigInt and symbols remain in the tree; JSON text throws on BigInt and
+ * drops symbols (or writes null in arrays). Invalid Dates throw, and own `__proto__` keys aren't
+ * emitted. Strings that look like sentinels aren't escaped, so they decode as the value they spell.
+ *
+ * The output is signed (`canonicalJSONString` in keys.ts), so it must stay byte-identical across
+ * versions; `serial-json.compat.test.ts` checks it against a frozen copy.
+ * @returns A new tree; the input is never modified. Top-level primitives are returned as-is.
  */
 export declare function toJSON(obj: any): any;
 /**
- * Reverses {@link toJSON}: restores special values, shared references, and keys escaped with `__DOLLAR_`.
- * @param _externalReferences Reserved for future use (function revival, etc.)
+ * Reverses {@link toJSON}: restores the sentinel values, shared objects and cycles, and keys
+ * escaped with `__DOLLAR_`.
+ *
+ * Input may come from another device. Shared-reference tags never resolve to a prototype or to a
+ * target of the other kind (object vs array), `__proto__` keys are dropped, and `__HTML` /
+ * `__WINDOW` stay plain strings. A marker with no accepted target in the same tree decodes to an
+ * empty object or array and warns once per distinct marker, up to 100 warnings per process.
+ *
+ * Only arrays and objects are walked. Values that are already decoded (Date, RegExp, Error, Buffer
+ * and any other typed array or DataView) are returned as they are, so decoding a partly decoded
+ * tree preserves these instances. Marker-like strings may decode again; live cycles aren't supported.
+ * @param obj Parsed JSON, a msgpack-decoded tree, or a mix with decoded values. Never modified.
+ * @param _externalReferences Unused. Callers pass `.map` indexes into it, so it must stay ignored.
+ * @returns A new tree for walked arrays and objects. Passed-through values retain their identity
+ * and properties.
+ * @throws SyntaxError for a `__REGEXP` sentinel that isn't a valid regular expression; RangeError
+ * when the tree is nested deeper than the call stack allows.
  */
 export declare function fromJSON(obj: any, _externalReferences?: any): any;
 /**