ushman-equiv 0.4.0

package/dist/canonicalize.js

@@ -0,0 +1,525 @@
+// Matches the characterize serializer contract: default trace payloads are capped
+// at 50 MB and floats are rounded to 4 decimals for stable replay comparisons.
+import { compareStrings } from "./shared.js";
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+const DEFAULT_PRECISION = 4;
+const EXEMPT_FIELD_MARKER = '__ushman_exempt_field__';
+const CANONICALIZE_MISS = Symbol('canonicalize-miss');
+const asObject = (value) => value;
+const roundNumber = (value, precision) => {
+    const scale = 10 ** precision;
+    return Math.round(value * scale) / scale;
+};
+const assertWithinSizeLimit = (bytes, maxBytes) => {
+    if (bytes > maxBytes) {
+        throw new RangeError(`Canonicalized value exceeds maxBytes (${bytes} > ${maxBytes}).`);
+    }
+    return bytes;
+};
+const addSizedBytes = (current, delta, maxBytes) => assertWithinSizeLimit(current + delta, maxBytes);
+const jsonScalarByteLength = (value) => Buffer.byteLength(JSON.stringify(value));
+const sizedScalar = (value, state) => ({
+    bytes: assertWithinSizeLimit(jsonScalarByteLength(value), state.maxBytes),
+    value,
+});
+const sizedObject = (state, entries) => {
+    let bytes = assertWithinSizeLimit(2, state.maxBytes);
+    const value = {};
+    for (const [index, [key, entry]] of entries.entries()) {
+        const propertyBytes = jsonScalarByteLength(key) + 1 + entry.bytes + (index > 0 ? 1 : 0);
+        bytes = addSizedBytes(bytes, propertyBytes, state.maxBytes);
+        value[key] = entry.value;
+    }
+    return {
+        bytes,
+        value,
+    };
+};
+const sizedArray = (state, items) => {
+    let bytes = assertWithinSizeLimit(2, state.maxBytes);
+    const value = [];
+    for (const [index, item] of items.entries()) {
+        bytes = addSizedBytes(bytes, item.bytes + (index > 0 ? 1 : 0), state.maxBytes);
+        value.push(item.value);
+    }
+    return {
+        bytes,
+        value,
+    };
+};
+const createSizedArrayBuilder = (state) => {
+    let bytes = assertWithinSizeLimit(2, state.maxBytes);
+    const value = [];
+    return {
+        add(entry) {
+            bytes = addSizedBytes(bytes, entry.bytes + (value.length > 0 ? 1 : 0), state.maxBytes);
+            value.push(entry.value);
+        },
+        done() {
+            return {
+                bytes,
+                value,
+            };
+        },
+    };
+};
+const roundFiniteNumber = (value, state) => sizedScalar(roundNumber(value, state.precision), state);
+const canonicalizeNumber = (value, state) => {
+    if (Number.isNaN(value)) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Number', state)],
+            ['value', sizedScalar('NaN', state)],
+        ]);
+    }
+    if (value === Number.POSITIVE_INFINITY) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Number', state)],
+            ['value', sizedScalar('Infinity', state)],
+        ]);
+    }
+    if (value === Number.NEGATIVE_INFINITY) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Number', state)],
+            ['value', sizedScalar('-Infinity', state)],
+        ]);
+    }
+    if (Object.is(value, -0)) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Number', state)],
+            ['value', sizedScalar('-0', state)],
+        ]);
+    }
+    return roundFiniteNumber(value, state);
+};
+const isPlainObject = (value) => {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const encodeBytes = (bytes) => Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+const trackReference = (value, state) => {
+    const id = state.nextId;
+    state.seen.set(value, { id });
+    state.nextId += 1;
+    return id;
+};
+const canonicalizePrimitive = (value, state) => {
+    if (value === undefined) {
+        return sizedObject(state, [['__t', sizedScalar('Undefined', state)]]);
+    }
+    if (typeof value === 'number') {
+        return canonicalizeNumber(value, state);
+    }
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return sizedScalar(value, state);
+    }
+    if (typeof value === 'bigint') {
+        return sizedObject(state, [
+            ['__t', sizedScalar('BigInt', state)],
+            ['value', sizedScalar(value.toString(), state)],
+        ]);
+    }
+    if (typeof value === 'symbol') {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Symbol', state)],
+            ['value', sizedScalar(String(value), state)],
+        ]);
+    }
+    if (typeof value === 'function') {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Function', state)],
+            ['name', sizedScalar(value.name || 'anonymous', state)],
+        ]);
+    }
+    return CANONICALIZE_MISS;
+};
+const canonicalizeTypedArray = (value, state) => {
+    const base = sizedObject(state, [
+        ['__t', sizedScalar(value.constructor.name, state)],
+        [
+            'base64',
+            sizedScalar(encodeBytes(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)), state),
+        ],
+        ['byteLength', sizedScalar(value.byteLength, state)],
+    ]);
+    if (!('length' in value) || typeof value.length !== 'number') {
+        return {
+            bytes: base.bytes,
+            value: {
+                ...asObject(base.value),
+                length: undefined,
+            },
+        };
+    }
+    return sizedObject(state, [
+        ['__t', sizedScalar(value.constructor.name, state)],
+        [
+            'base64',
+            sizedScalar(encodeBytes(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)), state),
+        ],
+        ['byteLength', sizedScalar(value.byteLength, state)],
+        ['length', sizedScalar(value.length, state)],
+    ]);
+};
+const canonicalizeArrayItems = (value, state, pathParts) => {
+    const items = createSizedArrayBuilder(state);
+    for (const [index, entry] of value.entries()) {
+        items.add(visitValue(entry, state, [...pathParts, String(index)]));
+    }
+    return items.done();
+};
+const canonicalizeMapEntries = (value, state, pathParts) => {
+    const entries = createSizedArrayBuilder(state);
+    let index = 0;
+    for (const [key, entry] of value.entries()) {
+        entries.add(sizedArray(state, [
+            visitValue(key, state, [...pathParts, `${index}`, '0']),
+            visitValue(entry, state, [...pathParts, `${index}`, '1']),
+        ]));
+        index += 1;
+    }
+    return entries.done();
+};
+const canonicalizeSetValues = (value, state, pathParts) => {
+    const entries = createSizedArrayBuilder(state);
+    let index = 0;
+    for (const entry of value.values()) {
+        entries.add(visitValue(entry, state, [...pathParts, String(index)]));
+        index += 1;
+    }
+    return entries.done();
+};
+const canonicalizeObjectProps = (value, state, pathParts) => {
+    let bytes = assertWithinSizeLimit(2, state.maxBytes);
+    const props = {};
+    let propertyCount = 0;
+    for (const key of Object.keys(asObject(value))
+        // Characterize strips generic object UUIDs so replay fixtures stay stable
+        // across runs where transient object identities change.
+        .filter((entry) => entry !== 'uuid')
+        .sort(compareStrings)) {
+        const entry = visitValue(asObject(value)[key], state, [...pathParts, key]);
+        const propertyBytes = jsonScalarByteLength(key) + 1 + entry.bytes + (propertyCount > 0 ? 1 : 0);
+        bytes = addSizedBytes(bytes, propertyBytes, state.maxBytes);
+        props[key] = entry.value;
+        propertyCount += 1;
+    }
+    return {
+        bytes,
+        value: props,
+    };
+};
+const canonicalizeKnownObject = (value, state) => {
+    if (value instanceof Error) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Error', state)],
+            ['message', sizedScalar(value.message, state)],
+            ['name', sizedScalar(value.name, state)],
+        ]);
+    }
+    if (value instanceof Date) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('Date', state)],
+            ['iso', sizedScalar(value.toISOString(), state)],
+        ]);
+    }
+    if (value instanceof URL) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('URL', state)],
+            ['href', sizedScalar(value.href, state)],
+        ]);
+    }
+    if (value instanceof ArrayBuffer) {
+        return sizedObject(state, [
+            ['__t', sizedScalar('ArrayBuffer', state)],
+            ['base64', sizedScalar(encodeBytes(new Uint8Array(value)), state)],
+            ['byteLength', sizedScalar(value.byteLength, state)],
+        ]);
+    }
+    if (ArrayBuffer.isView(value)) {
+        return canonicalizeTypedArray(value, state);
+    }
+    return null;
+};
+const visitValue = (value, state, pathParts) => {
+    if (value === null) {
+        return sizedScalar(null, state);
+    }
+    const exemptKey = pathParts.join('.');
+    if (exemptKey && state.exemptFields.has(exemptKey)) {
+        return sizedScalar(EXEMPT_FIELD_MARKER, state);
+    }
+    const primitive = canonicalizePrimitive(value, state);
+    if (primitive !== CANONICALIZE_MISS) {
+        return primitive;
+    }
+    if (!(value instanceof Object)) {
+        return sizedScalar(String(value), state);
+    }
+    const seenReference = state.seen.get(value);
+    if (seenReference) {
+        return sizedObject(state, [['$ref', sizedScalar(seenReference.id, state)]]);
+    }
+    const knownObject = canonicalizeKnownObject(value, state);
+    if (knownObject !== null) {
+        return knownObject;
+    }
+    if (Array.isArray(value)) {
+        const id = trackReference(value, state);
+        return sizedObject(state, [
+            ['__id', sizedScalar(id, state)],
+            ['__t', sizedScalar('Array', state)],
+            ['items', canonicalizeArrayItems(value, state, pathParts)],
+        ]);
+    }
+    if (value instanceof Map) {
+        const id = trackReference(value, state);
+        return sizedObject(state, [
+            ['__id', sizedScalar(id, state)],
+            ['__t', sizedScalar('Map', state)],
+            ['entries', canonicalizeMapEntries(value, state, pathParts)],
+        ]);
+    }
+    if (value instanceof Set) {
+        const id = trackReference(value, state);
+        return sizedObject(state, [
+            ['__id', sizedScalar(id, state)],
+            ['__t', sizedScalar('Set', state)],
+            ['values', canonicalizeSetValues(value, state, pathParts)],
+        ]);
+    }
+    const id = trackReference(value, state);
+    const type = isPlainObject(value) ? 'Object' : 'Instance';
+    const entries = [
+        ['__id', sizedScalar(id, state)],
+        ['__t', sizedScalar(type, state)],
+        ['props', canonicalizeObjectProps(value, state, pathParts)],
+    ];
+    if (type === 'Instance' && typeof value.constructor?.name === 'string') {
+        entries.push(['ctor', sizedScalar(value.constructor.name, state)]);
+    }
+    return sizedObject(state, entries);
+};
+/**
+ * Converts replay values into the stable characterize-compatible wire shape.
+ * `exemptFields` uses dot-notation paths and `maxBytes` aborts once the
+ * canonicalized payload would exceed the configured UTF-8 byte budget.
+ */
+export const canonicalize = (value, options = {}) => {
+    const state = {
+        exemptFields: new Set(options.exemptFields ?? []),
+        maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+        nextId: 1,
+        precision: options.precision ?? DEFAULT_PRECISION,
+        seen: new WeakMap(),
+    };
+    return visitValue(value, state, []).value;
+};
+const decodeBytes = (base64) => {
+    const buffer = Buffer.from(base64, 'base64');
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+};
+const createHydrationState = () => ({
+    refs: new Map(),
+});
+const HYDRATION_MISS = Symbol('hydration-miss');
+const hydrateTaggedNumber = (value) => {
+    if (value === 'NaN') {
+        return Number.NaN;
+    }
+    if (value === 'Infinity') {
+        return Number.POSITIVE_INFINITY;
+    }
+    if (value === '-Infinity') {
+        return Number.NEGATIVE_INFINITY;
+    }
+    if (value === '-0') {
+        return -0;
+    }
+    return Number(value);
+};
+const hydrateArrayBuffer = (base64) => {
+    const bytes = decodeBytes(base64);
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy.buffer;
+};
+const hydrateTypedArray = (tag, base64) => {
+    const bytes = decodeBytes(base64);
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    switch (tag) {
+        case 'DataView':
+            return new DataView(buffer);
+        case 'Float32Array':
+            return new Float32Array(buffer);
+        case 'Float64Array':
+            return new Float64Array(buffer);
+        case 'Int16Array':
+            return new Int16Array(buffer);
+        case 'Int32Array':
+            return new Int32Array(buffer);
+        case 'Int8Array':
+            return new Int8Array(buffer);
+        case 'Uint16Array':
+            return new Uint16Array(buffer);
+        case 'Uint32Array':
+            return new Uint32Array(buffer);
+        case 'Uint8Array':
+            return new Uint8Array(buffer);
+        case 'Uint8ClampedArray':
+            return new Uint8ClampedArray(buffer);
+        default:
+            return new Uint8Array(buffer);
+    }
+};
+const hydrateScalarTaggedValue = (entry) => {
+    const hydrateSymbol = (value) => {
+        if (!value.startsWith('Symbol(') || !value.endsWith(')')) {
+            return Symbol(value);
+        }
+        const description = value.slice('Symbol('.length, -1);
+        return description.length > 0 ? Symbol(description) : Symbol();
+    };
+    const hydrateFunction = (name) => {
+        const placeholder = () => undefined;
+        Object.defineProperty(placeholder, 'name', {
+            configurable: true,
+            value: name,
+        });
+        return placeholder;
+    };
+    switch (entry.__t) {
+        case 'Undefined':
+            return undefined;
+        case 'Number':
+            return typeof entry.value === 'string' ? hydrateTaggedNumber(entry.value) : HYDRATION_MISS;
+        case 'BigInt':
+            return typeof entry.value === 'string' ? BigInt(entry.value) : HYDRATION_MISS;
+        case 'Symbol':
+            return typeof entry.value === 'string' ? hydrateSymbol(entry.value) : HYDRATION_MISS;
+        case 'Function':
+            return typeof entry.name === 'string' ? hydrateFunction(entry.name) : HYDRATION_MISS;
+        case 'Date':
+            return typeof entry.iso === 'string' ? new Date(entry.iso) : HYDRATION_MISS;
+        case 'URL':
+            return typeof entry.href === 'string' ? new URL(entry.href) : HYDRATION_MISS;
+        case 'Error':
+            return new Error(typeof entry.message === 'string' ? entry.message : '');
+        default:
+            return HYDRATION_MISS;
+    }
+};
+const hydrateBinaryTaggedValue = (entry) => {
+    if (entry.__t === 'ArrayBuffer' && typeof entry.base64 === 'string') {
+        return hydrateArrayBuffer(entry.base64);
+    }
+    if (entry.__t === 'DataView' && typeof entry.base64 === 'string') {
+        return hydrateTypedArray('DataView', entry.base64);
+    }
+    if (typeof entry.__t === 'string' && typeof entry.base64 === 'string' && entry.__t.endsWith('Array')) {
+        return hydrateTypedArray(entry.__t, entry.base64);
+    }
+    return HYDRATION_MISS;
+};
+const hydrateSimpleTaggedValue = (entry) => {
+    const scalarValue = hydrateScalarTaggedValue(entry);
+    if (scalarValue !== HYDRATION_MISS) {
+        return scalarValue;
+    }
+    return hydrateBinaryTaggedValue(entry);
+};
+const hydrateTrackedArray = (entry, state) => {
+    if (entry.__t !== 'Array' || !Array.isArray(entry.items)) {
+        return HYDRATION_MISS;
+    }
+    const hydratedArray = [];
+    if (typeof entry.__id === 'number') {
+        state.refs.set(entry.__id, hydratedArray);
+    }
+    hydratedArray.push(...entry.items.map((item) => hydrateCanonicalized(item, state)));
+    return hydratedArray;
+};
+const hydrateTrackedMap = (entry, state) => {
+    if (entry.__t !== 'Map' || !Array.isArray(entry.entries)) {
+        return HYDRATION_MISS;
+    }
+    const hydratedMap = new Map();
+    if (typeof entry.__id === 'number') {
+        state.refs.set(entry.__id, hydratedMap);
+    }
+    for (const item of entry.entries) {
+        if (Array.isArray(item) && item.length === 2) {
+            hydratedMap.set(hydrateCanonicalized(item[0], state), hydrateCanonicalized(item[1], state));
+        }
+    }
+    return hydratedMap;
+};
+const hydrateTrackedSet = (entry, state) => {
+    if (entry.__t !== 'Set' || !Array.isArray(entry.values)) {
+        return HYDRATION_MISS;
+    }
+    const hydratedSet = new Set();
+    if (typeof entry.__id === 'number') {
+        state.refs.set(entry.__id, hydratedSet);
+    }
+    for (const item of entry.values) {
+        hydratedSet.add(hydrateCanonicalized(item, state));
+    }
+    return hydratedSet;
+};
+const hydrateTrackedObject = (entry, state) => {
+    if ((entry.__t !== 'Object' && entry.__t !== 'Instance') || !entry.props || typeof entry.props !== 'object') {
+        return HYDRATION_MISS;
+    }
+    const target = entry.__t === 'Instance' && typeof entry.ctor === 'string'
+        ? Object.create({ constructor: { name: entry.ctor } })
+        : {};
+    if (typeof entry.__id === 'number') {
+        state.refs.set(entry.__id, target);
+    }
+    for (const [key, item] of Object.entries(asObject(entry.props))) {
+        target[key] = hydrateCanonicalized(item, state);
+    }
+    return target;
+};
+const hydrateTrackedValue = (entry, state) => {
+    const trackedArray = hydrateTrackedArray(entry, state);
+    if (trackedArray !== HYDRATION_MISS) {
+        return trackedArray;
+    }
+    const trackedMap = hydrateTrackedMap(entry, state);
+    if (trackedMap !== HYDRATION_MISS) {
+        return trackedMap;
+    }
+    const trackedSet = hydrateTrackedSet(entry, state);
+    if (trackedSet !== HYDRATION_MISS) {
+        return trackedSet;
+    }
+    return hydrateTrackedObject(entry, state);
+};
+/**
+ * Hydrates a canonicalized replay payload back into runtime values for replay.
+ */
+export const hydrateCanonicalized = (value, state = createHydrationState()) => {
+    if (Array.isArray(value)) {
+        return value.map((entry) => hydrateCanonicalized(entry, state));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const entry = asObject(value);
+    if (typeof entry.$ref === 'number') {
+        return state.refs.get(entry.$ref);
+    }
+    const simpleHydratedValue = hydrateSimpleTaggedValue(entry);
+    if (simpleHydratedValue !== HYDRATION_MISS) {
+        return simpleHydratedValue;
+    }
+    const trackedHydratedValue = hydrateTrackedValue(entry, state);
+    if (trackedHydratedValue !== HYDRATION_MISS) {
+        return trackedHydratedValue;
+    }
+    return Object.fromEntries(Object.entries(entry).map(([key, item]) => [key, hydrateCanonicalized(item, state)]));
+};

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare const runWithHeapGuard: (runner: () => Promise<number>) => Promise<number>;
+export declare const main: (argv?: readonly string[]) => Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA6BA,eAAO,MAAM,gBAAgB,GAAU,QAAQ,MAAM,OAAO,CAAC,MAAM,CAAC,KAAG,OAAO,CAAC,MAAM,CAuBpF,CAAC;AAkRF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAc1F,CAAC"}