@hops-ops/distributed 0.0.0

package/dist/internal/cache-engine/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class CacheRevisionConflictError extends Error {
+    readonly dependency: string;
+    readonly revision: string;
+    constructor(dependency: string, revision: bigint);
+}

package/dist/internal/cache-engine/errors.js

@@ -0,0 +1,10 @@
+export class CacheRevisionConflictError extends Error {
+    dependency;
+    revision;
+    constructor(dependency, revision) {
+        super(`conflicting cache values at revision ${revision} for ${dependency}`);
+        this.name = 'CacheRevisionConflictError';
+        this.dependency = dependency;
+        this.revision = revision.toString(10);
+    }
+}

package/dist/internal/cache-engine/helpers.d.ts

@@ -0,0 +1,55 @@
+import type { CacheEngineSnapshot, CacheIndexCoverage, CacheIndexMetadata, CacheValue, DerivedIndexMutation, DerivedIndexOperation, DerivedIndexReconciler, IndexKey, OptimisticLayerView, OverlayOperation, RecordKey, RecordLink, Revision, StoredIndex, StoredRecord, VisibleRecord } from './types.js';
+import { assertName } from '../../lib/assert-name.js';
+import { deepEqual } from '../../lib/deep-equal.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import { reportSafely, reportUnhandledError } from '../../lib/report.js';
+export declare function parseSnapshot(snapshot: CacheEngineSnapshot): {
+    records: Map<RecordKey, StoredRecord>;
+    indexes: Map<IndexKey, StoredIndex>;
+};
+export declare function runDerivedIndexReconciler(reconciler: DerivedIndexReconciler, confirmed: CacheEngineSnapshot, layers: readonly OptimisticLayerView[]): readonly DerivedIndexMutation[];
+export declare function cloneDerivedIndexOperations(input: readonly DerivedIndexMutation[]): readonly DerivedIndexOperation[];
+export declare function derivedIndexKeys(operations: readonly DerivedIndexOperation[]): readonly IndexKey[];
+export declare function derivedIndexOperationKey(operation: DerivedIndexOperation): IndexKey;
+export declare function assertExactKeys(value: Record<string, unknown>, allowed: readonly string[], description: string, required?: readonly string[]): void;
+export declare function operationDependencies(operation: OverlayOperation): readonly string[];
+export declare function recordSeenDependency(key: RecordKey): string;
+export declare function recordWildcardDependency(key: RecordKey): string;
+export declare function recordFieldDependency(key: RecordKey, field: string): string;
+export declare function indexDependency(key: IndexKey): string;
+export declare function dependenciesChanged(dependencies: ReadonlySet<string>, changed: ReadonlySet<string>): boolean;
+export declare function emptyVisibleRecord(): VisibleRecord;
+export declare function isVisibleRecordLive(record: VisibleRecord | undefined): boolean;
+export declare function validateRecordKey(key: RecordKey): void;
+export declare function validateIndexWrite(write: {
+    key: IndexKey;
+    records: readonly RecordKey[];
+    metadata?: CacheIndexMetadata;
+}): void;
+export declare function indexMetadataWithoutStaleReason(metadata: CacheIndexMetadata | undefined): Omit<CacheIndexMetadata, 'staleReason'> | undefined;
+export declare function isOrderedSubsequence(known: readonly RecordKey[], complete: readonly RecordKey[]): boolean;
+export declare function refinementMetadataCompatible(current: CacheIndexMetadata | undefined, next: CacheIndexMetadata | undefined): boolean;
+export declare function refinementMetadataIdentity(metadata: CacheIndexMetadata): unknown;
+export declare function coverageRequestIdentity(coverage: CacheIndexCoverage): unknown;
+export declare function cloneIndexMetadata(metadata: CacheIndexMetadata): CacheIndexMetadata;
+export declare function cloneIndexCoverage(coverage: CacheIndexCoverage): CacheIndexCoverage;
+export declare function assertNonNegativeSafeInteger(value: number, description: string): void;
+export declare function assertWriterActive(active: boolean): void;
+export declare function assertSynchronousResult(result: unknown, description: string): void;
+export declare function validateRecordKeys(keys: readonly RecordKey[]): void;
+export declare function revisionToken(value: Revision): bigint;
+export declare function compareRecordTuple(leftIncarnation: bigint, leftRevision: bigint, rightIncarnation: bigint, rightRevision: bigint): -1 | 0 | 1;
+export declare function revisionString(value: bigint): string;
+export declare function cloneFields(fields: Readonly<Record<string, CacheValue>> | undefined): Readonly<Record<string, CacheValue>>;
+export declare function cloneLinks(links: Readonly<Record<string, RecordLink>> | undefined): Readonly<Record<string, RecordLink>>;
+export declare function cloneLink(value: RecordLink): RecordLink;
+export declare function linkKeys(value: RecordLink): readonly RecordKey[];
+export declare function cloneCacheValue(value: CacheValue, ancestors?: Set<object>): CacheValue;
+export declare function canonicalValue(value: CacheValue): string;
+export declare function cacheIndexKey(input: {
+    parent?: RecordKey;
+    field: string;
+    arguments?: Readonly<Record<string, CacheValue>>;
+}): IndexKey;
+export { assertName, deepEqual, freezeRecord, reportSafely };
+export declare const reportUnhandledWatcherError: typeof reportUnhandledError;

package/dist/internal/cache-engine/helpers.js

@@ -0,0 +1,545 @@
+import { assertName } from '../../lib/assert-name.js';
+import { deepEqual } from '../../lib/deep-equal.js';
+import { freezeRecord } from '../../lib/freeze-record.js';
+import { reportSafely, reportUnhandledError } from '../../lib/report.js';
+export function parseSnapshot(snapshot) {
+    if (!snapshot || snapshot.version !== 1)
+        throw new TypeError('unsupported cache snapshot');
+    if (!Array.isArray(snapshot.records) || !Array.isArray(snapshot.indexes)) {
+        throw new TypeError('invalid cache snapshot collections');
+    }
+    const records = new Map();
+    for (const input of snapshot.records) {
+        validateRecordKey(input.key);
+        if (records.has(input.key))
+            throw new TypeError(`duplicate snapshot record: ${input.key}`);
+        const revision = revisionToken(input.revision);
+        const incarnation = revisionToken(input.incarnation ?? input.revision);
+        const tombstoneRevision = input.tombstoneRevision === undefined
+            ? undefined
+            : revisionToken(input.tombstoneRevision);
+        if (tombstoneRevision !== undefined && tombstoneRevision !== revision) {
+            throw new TypeError(`invalid tombstone revision for ${input.key}`);
+        }
+        const fields = new Map();
+        for (const [name, field] of Object.entries(input.fields)) {
+            assertName(name, 'record field');
+            const fieldRevision = revisionToken(field.revision);
+            if (fieldRevision > revision)
+                throw new TypeError(`field revision exceeds ${input.key}`);
+            fields.set(name, { revision: fieldRevision, value: cloneCacheValue(field.value) });
+        }
+        const links = new Map();
+        for (const [name, link] of Object.entries(input.links)) {
+            assertName(name, 'record link');
+            const linkRevision = revisionToken(link.revision);
+            if (linkRevision > revision)
+                throw new TypeError(`link revision exceeds ${input.key}`);
+            links.set(name, { revision: linkRevision, value: cloneLink(link.value) });
+        }
+        if (tombstoneRevision !== undefined && (fields.size > 0 || links.size > 0)) {
+            throw new TypeError(`tombstone record contains live fields: ${input.key}`);
+        }
+        records.set(input.key, {
+            revision,
+            incarnation,
+            tombstoneRevision,
+            fields,
+            links
+        });
+    }
+    const indexes = new Map();
+    for (const input of snapshot.indexes) {
+        validateIndexWrite(input);
+        if (indexes.has(input.key))
+            throw new TypeError(`duplicate snapshot index: ${input.key}`);
+        validateRecordKeys(input.records);
+        const revision = revisionToken(input.revision);
+        const staleRevision = input.staleRevision === undefined
+            ? undefined
+            : revisionToken(input.staleRevision);
+        if (staleRevision !== undefined && staleRevision < revision) {
+            throw new TypeError(`stale index revision precedes its snapshot: ${input.key}`);
+        }
+        indexes.set(input.key, {
+            revision,
+            staleRevision,
+            records: [...input.records],
+            complete: Boolean(input.complete),
+            deleted: Boolean(input.deleted),
+            metadata: input.metadata === undefined ? undefined : cloneIndexMetadata(input.metadata)
+        });
+    }
+    return { records, indexes };
+}
+export function runDerivedIndexReconciler(reconciler, confirmed, layers) {
+    const result = reconciler(confirmed, Object.freeze([...layers]));
+    assertSynchronousResult(result, 'derived index reconciler');
+    if (!Array.isArray(result)) {
+        throw new TypeError('derived index reconciler must return an array');
+    }
+    return result;
+}
+export function cloneDerivedIndexOperations(input) {
+    const operations = [];
+    const keys = new Set();
+    for (const [index, value] of input.entries()) {
+        const path = `derived index mutation ${index}`;
+        if (value === null ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            (Object.getPrototypeOf(value) !== Object.prototype &&
+                Object.getPrototypeOf(value) !== null)) {
+            throw new TypeError(`${path} must be a plain object`);
+        }
+        if (value.kind === 'write') {
+            assertExactKeys(value, ['kind', 'write'], path);
+            const write = value.write;
+            if (write === null ||
+                typeof write !== 'object' ||
+                Array.isArray(write) ||
+                (Object.getPrototypeOf(write) !== Object.prototype &&
+                    Object.getPrototypeOf(write) !== null)) {
+                throw new TypeError(`${path}.write must be a plain object`);
+            }
+            assertExactKeys(write, ['key', 'records', 'complete', 'metadata'], `${path}.write`, ['key', 'records']);
+            validateIndexWrite(write);
+            if (write.complete !== undefined &&
+                typeof write.complete !== 'boolean') {
+                throw new TypeError(`${path}.write.complete must be a boolean`);
+            }
+            if (keys.has(write.key)) {
+                throw new TypeError(`duplicate derived index mutation: ${write.key}`);
+            }
+            keys.add(write.key);
+            operations.push(Object.freeze({
+                kind: 'write-index',
+                write: Object.freeze({
+                    key: write.key,
+                    records: Object.freeze([...write.records]),
+                    complete: write.complete ?? false,
+                    ...(write.metadata === undefined
+                        ? {}
+                        : { metadata: cloneIndexMetadata(write.metadata) })
+                })
+            }));
+            continue;
+        }
+        if (value.kind === 'stale') {
+            assertExactKeys(value, ['kind', 'key', 'reason'], path);
+            assertName(value.key, `${path} key`);
+            assertName(value.reason, `${path} reason`);
+            if (keys.has(value.key)) {
+                throw new TypeError(`duplicate derived index mutation: ${value.key}`);
+            }
+            keys.add(value.key);
+            operations.push(Object.freeze({
+                kind: 'mark-index-stale',
+                key: value.key,
+                reason: value.reason
+            }));
+            continue;
+        }
+        if (value.kind === 'delete') {
+            assertExactKeys(value, ['kind', 'key'], path);
+            assertName(value.key, `${path} key`);
+            if (keys.has(value.key)) {
+                throw new TypeError(`duplicate derived index mutation: ${value.key}`);
+            }
+            keys.add(value.key);
+            operations.push(Object.freeze({ kind: 'delete-index', key: value.key }));
+            continue;
+        }
+        throw new TypeError(`${path} has unsupported kind`);
+    }
+    return Object.freeze(operations.sort((left, right) => derivedIndexOperationKey(left).localeCompare(derivedIndexOperationKey(right))));
+}
+export function derivedIndexKeys(operations) {
+    return Object.freeze([...new Set(operations.map(derivedIndexOperationKey))].sort());
+}
+export function derivedIndexOperationKey(operation) {
+    return operation.kind === 'write-index'
+        ? operation.write.key
+        : operation.key;
+}
+export function assertExactKeys(value, allowed, description, required = allowed) {
+    const allowedKeys = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key)) {
+            throw new TypeError(`${description} contains unknown field ${key}`);
+        }
+    }
+    for (const key of required) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            throw new TypeError(`${description} is missing field ${key}`);
+        }
+    }
+}
+export function operationDependencies(operation) {
+    if (operation.kind === 'write-record') {
+        return [
+            recordSeenDependency(operation.write.key),
+            ...Object.keys(operation.write.fields ?? {}).map((name) => recordFieldDependency(operation.write.key, `field:${name}`)),
+            ...Object.keys(operation.write.links ?? {}).map((name) => recordFieldDependency(operation.write.key, `link:${name}`))
+        ];
+    }
+    if (operation.kind === 'tombstone-record') {
+        return [recordSeenDependency(operation.key), recordWildcardDependency(operation.key)];
+    }
+    return [indexDependency(operation.kind === 'write-index' ? operation.write.key : operation.key)];
+}
+export function recordSeenDependency(key) {
+    return JSON.stringify(['record-seen', key]);
+}
+export function recordWildcardDependency(key) {
+    return JSON.stringify(['record', key, '*']);
+}
+export function recordFieldDependency(key, field) {
+    return JSON.stringify(['record', key, field]);
+}
+export function indexDependency(key) {
+    return JSON.stringify(['index', key]);
+}
+export function dependenciesChanged(dependencies, changed) {
+    if (changed.size === 0 || changed.has('*'))
+        return true;
+    for (const dependency of dependencies) {
+        if (changed.has(dependency))
+            return true;
+    }
+    return false;
+}
+export function emptyVisibleRecord() {
+    return {
+        revision: 0n,
+        incarnation: 0n,
+        tombstoned: false,
+        fields: new Map(),
+        links: new Map()
+    };
+}
+export function isVisibleRecordLive(record) {
+    return record !== undefined && !record.tombstoned;
+}
+export function validateRecordKey(key) {
+    assertName(key, 'record key');
+}
+export function validateIndexWrite(write) {
+    assertName(write.key, 'index key');
+    if (!Array.isArray(write.records))
+        throw new TypeError('index records must be an array');
+    validateRecordKeys(write.records);
+    if ('metadata' in write && write.metadata !== undefined) {
+        const metadata = cloneIndexMetadata(write.metadata);
+        const expectedKey = cacheIndexKey({
+            ...(metadata.parent === undefined ? {} : { parent: metadata.parent }),
+            field: metadata.field,
+            arguments: metadata.arguments
+        });
+        if (write.key !== expectedKey) {
+            throw new TypeError(`index key does not match its metadata: expected ${expectedKey}`);
+        }
+    }
+}
+export function indexMetadataWithoutStaleReason(metadata) {
+    if (metadata === undefined)
+        return undefined;
+    const { staleReason: _staleReason, ...rest } = metadata;
+    return rest;
+}
+export function isOrderedSubsequence(known, complete) {
+    let knownIndex = 0;
+    for (const key of complete) {
+        if (key === known[knownIndex])
+            knownIndex += 1;
+    }
+    return knownIndex === known.length;
+}
+export function refinementMetadataCompatible(current, next) {
+    if (current === undefined || next === undefined)
+        return current === next;
+    return deepEqual(refinementMetadataIdentity(current), refinementMetadataIdentity(next));
+}
+export function refinementMetadataIdentity(metadata) {
+    return {
+        parent: metadata.parent,
+        parentRevision: metadata.parentRevision,
+        parentIncarnation: metadata.parentIncarnation,
+        field: metadata.field,
+        arguments: metadata.arguments,
+        dependencies: metadata.dependencies,
+        nullValue: metadata.nullValue,
+        coverage: coverageRequestIdentity(metadata.coverage)
+    };
+}
+export function coverageRequestIdentity(coverage) {
+    if (coverage.kind === 'complete' || coverage.kind === 'unknown') {
+        return { kind: coverage.kind };
+    }
+    if (coverage.kind === 'offset') {
+        return { kind: coverage.kind, offset: coverage.offset, limit: coverage.limit };
+    }
+    return {
+        kind: coverage.kind,
+        after: coverage.after,
+        before: coverage.before,
+        first: coverage.first,
+        last: coverage.last
+    };
+}
+export function cloneIndexMetadata(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+        throw new TypeError('index metadata must be an object');
+    }
+    assertName(metadata.field, 'index field');
+    if (metadata.parent !== undefined)
+        validateRecordKey(metadata.parent);
+    if (metadata.parentRevision !== undefined)
+        revisionToken(metadata.parentRevision);
+    if (metadata.parentIncarnation !== undefined)
+        revisionToken(metadata.parentIncarnation);
+    const argumentsValue = cloneCacheValue(metadata.arguments);
+    if (argumentsValue === null ||
+        Array.isArray(argumentsValue) ||
+        typeof argumentsValue !== 'object') {
+        throw new TypeError('index arguments must be a plain object');
+    }
+    if (!Array.isArray(metadata.dependencies)) {
+        throw new TypeError('index dependencies must be an array');
+    }
+    const dependencies = [...metadata.dependencies];
+    const seen = new Set();
+    for (const dependency of dependencies) {
+        assertName(dependency, 'index dependency');
+        if (seen.has(dependency)) {
+            throw new TypeError(`duplicate index dependency: ${dependency}`);
+        }
+        seen.add(dependency);
+    }
+    if (metadata.staleReason !== undefined) {
+        assertName(metadata.staleReason, 'index stale reason');
+    }
+    if (metadata.nullValue !== undefined && typeof metadata.nullValue !== 'boolean') {
+        throw new TypeError('index nullValue must be a boolean');
+    }
+    const coverage = cloneIndexCoverage(metadata.coverage);
+    return Object.freeze({
+        ...(metadata.parent === undefined ? {} : { parent: metadata.parent }),
+        ...(metadata.parentRevision === undefined
+            ? {}
+            : { parentRevision: metadata.parentRevision }),
+        ...(metadata.parentIncarnation === undefined
+            ? {}
+            : { parentIncarnation: metadata.parentIncarnation }),
+        field: metadata.field,
+        arguments: argumentsValue,
+        coverage,
+        dependencies: Object.freeze(dependencies),
+        ...(metadata.staleReason === undefined
+            ? {}
+            : { staleReason: metadata.staleReason }),
+        ...(metadata.nullValue === undefined ? {} : { nullValue: metadata.nullValue })
+    });
+}
+export function cloneIndexCoverage(coverage) {
+    if (!coverage || typeof coverage !== 'object') {
+        throw new TypeError('index coverage must be an object');
+    }
+    if (coverage.kind === 'complete' || coverage.kind === 'unknown') {
+        return Object.freeze({ kind: coverage.kind });
+    }
+    if (coverage.kind === 'offset') {
+        assertNonNegativeSafeInteger(coverage.offset, 'offset coverage offset');
+        if (coverage.limit !== undefined) {
+            assertNonNegativeSafeInteger(coverage.limit, 'offset coverage limit');
+        }
+        if (coverage.returned !== undefined) {
+            assertNonNegativeSafeInteger(coverage.returned, 'offset coverage returned');
+        }
+        if (coverage.hasNext !== undefined && typeof coverage.hasNext !== 'boolean') {
+            throw new TypeError('offset coverage hasNext must be a boolean');
+        }
+        return Object.freeze({
+            kind: 'offset',
+            offset: coverage.offset,
+            ...(coverage.limit === undefined ? {} : { limit: coverage.limit }),
+            ...(coverage.returned === undefined ? {} : { returned: coverage.returned }),
+            ...(coverage.hasNext === undefined ? {} : { hasNext: coverage.hasNext })
+        });
+    }
+    if (coverage.kind === 'cursor') {
+        if (coverage.first !== undefined) {
+            assertNonNegativeSafeInteger(coverage.first, 'cursor coverage first');
+        }
+        if (coverage.last !== undefined) {
+            assertNonNegativeSafeInteger(coverage.last, 'cursor coverage last');
+        }
+        if (coverage.hasNext !== undefined && typeof coverage.hasNext !== 'boolean') {
+            throw new TypeError('cursor coverage hasNext must be a boolean');
+        }
+        if (coverage.hasPrevious !== undefined &&
+            typeof coverage.hasPrevious !== 'boolean') {
+            throw new TypeError('cursor coverage hasPrevious must be a boolean');
+        }
+        return Object.freeze({
+            kind: 'cursor',
+            ...(coverage.after === undefined
+                ? {}
+                : { after: cloneCacheValue(coverage.after) }),
+            ...(coverage.before === undefined
+                ? {}
+                : { before: cloneCacheValue(coverage.before) }),
+            ...(coverage.first === undefined ? {} : { first: coverage.first }),
+            ...(coverage.last === undefined ? {} : { last: coverage.last }),
+            ...(coverage.start === undefined
+                ? {}
+                : { start: cloneCacheValue(coverage.start) }),
+            ...(coverage.end === undefined ? {} : { end: cloneCacheValue(coverage.end) }),
+            ...(coverage.hasNext === undefined ? {} : { hasNext: coverage.hasNext }),
+            ...(coverage.hasPrevious === undefined
+                ? {}
+                : { hasPrevious: coverage.hasPrevious })
+        });
+    }
+    throw new TypeError('unsupported index coverage kind');
+}
+export function assertNonNegativeSafeInteger(value, description) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${description} must be a non-negative safe integer`);
+    }
+}
+export function assertWriterActive(active) {
+    if (!active)
+        throw new Error('cache writer is no longer active');
+}
+export function assertSynchronousResult(result, description) {
+    if (result !== null &&
+        (typeof result === 'object' || typeof result === 'function') &&
+        typeof result.then === 'function') {
+        void Promise.resolve(result).catch(() => undefined);
+        throw new TypeError(`${description} must be synchronous`);
+    }
+}
+export function validateRecordKeys(keys) {
+    const seen = new Set();
+    for (const key of keys) {
+        validateRecordKey(key);
+        if (seen.has(key))
+            throw new TypeError(`duplicate record in index: ${key}`);
+        seen.add(key);
+    }
+}
+export function revisionToken(value) {
+    if (typeof value === 'bigint') {
+        if (value < 0n)
+            throw new TypeError('revision must be an unsigned integer');
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new TypeError('numeric revision must be an unsigned safe integer');
+        }
+        return BigInt(value);
+    }
+    if (!/^(0|[1-9][0-9]*)$/.test(value)) {
+        throw new TypeError('string revision must be a canonical unsigned integer');
+    }
+    return BigInt(value);
+}
+export function compareRecordTuple(leftIncarnation, leftRevision, rightIncarnation, rightRevision) {
+    if (leftIncarnation < rightIncarnation)
+        return -1;
+    if (leftIncarnation > rightIncarnation)
+        return 1;
+    if (leftRevision < rightRevision)
+        return -1;
+    if (leftRevision > rightRevision)
+        return 1;
+    return 0;
+}
+export function revisionString(value) {
+    return value.toString(10);
+}
+export function cloneFields(fields) {
+    if (fields === undefined)
+        return Object.freeze({});
+    return freezeRecord(Object.entries(fields).map(([name, value]) => {
+        assertName(name, 'record field');
+        return [name, cloneCacheValue(value)];
+    }));
+}
+export function cloneLinks(links) {
+    if (links === undefined)
+        return Object.freeze({});
+    return freezeRecord(Object.entries(links).map(([name, value]) => {
+        assertName(name, 'record link');
+        return [name, cloneLink(value)];
+    }));
+}
+export function cloneLink(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string') {
+        validateRecordKey(value);
+        return value;
+    }
+    if (!Array.isArray(value))
+        throw new TypeError('record link must be a key, key array, or null');
+    validateRecordKeys(value);
+    return Object.freeze([...value]);
+}
+export function linkKeys(value) {
+    if (value === null)
+        return [];
+    return typeof value === 'string' ? [value] : value;
+}
+export function cloneCacheValue(value, ancestors = new Set()) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        typeof value === 'number') {
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            throw new TypeError('cache numbers must be finite');
+        }
+        return value;
+    }
+    if (typeof value !== 'object') {
+        throw new TypeError('cache fields must contain JSON-compatible values; omit absent fields');
+    }
+    if (ancestors.has(value))
+        throw new TypeError('cache fields must not contain cycles');
+    ancestors.add(value);
+    let cloned;
+    if (Array.isArray(value)) {
+        cloned = Object.freeze(value.map((entry) => cloneCacheValue(entry, ancestors)));
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError('cache objects must be plain JSON objects');
+        }
+        cloned = freezeRecord(Object.entries(value).map(([key, entry]) => [key, cloneCacheValue(entry, ancestors)]));
+    }
+    ancestors.delete(value);
+    return cloned;
+}
+export function canonicalValue(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalValue).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalValue(record[key])}`)
+        .join(',')}}`;
+}
+export function cacheIndexKey(input) {
+    assertName(input.field, 'index field');
+    if (input.parent !== undefined)
+        validateRecordKey(input.parent);
+    const argumentsValue = cloneCacheValue(input.arguments ?? {});
+    return `${input.parent ?? '$root'}.${input.field}(${canonicalValue(argumentsValue)})`;
+}
+export { assertName, deepEqual, freezeRecord, reportSafely };
+export const reportUnhandledWatcherError = reportUnhandledError;

package/dist/internal/cache-engine/index.d.ts

@@ -0,0 +1,3 @@
+export type { BaseCacheWriter, BaseRecordClock, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheIndex, CacheIndexCoverage, CacheIndexMetadata, CacheListener, CachePresence, CacheReader, CacheSelector, CacheValue, DerivedIndexMutation, DerivedIndexReconciler, IndexKey, IndexWrite, OptimisticCacheWriter, OptimisticIndexWrite, OptimisticLayerContext, OptimisticLayerState, OptimisticLayerView, OptimisticRecordWrite, RecordKey, RecordLink, RecordWrite, Revision, SparseRecord, SparseRecordMeta, WatchOptions } from './types.js';
+export { CacheRevisionConflictError } from './errors.js';
+export { cacheIndexKey, createCacheEngine } from './create.js';

package/dist/internal/cache-engine/index.js

@@ -0,0 +1,2 @@
+export { CacheRevisionConflictError } from './errors.js';
+export { cacheIndexKey, createCacheEngine } from './create.js';