circuitjson-toolkit 1.0.17 → 1.1.1

package/src/core/context/BinaryDataSnapshot.mjs

@@ -0,0 +1,217 @@
+const ARRAY_BUFFER_LENGTH = Object.getOwnPropertyDescriptor(
+    ArrayBuffer.prototype,
+    'byteLength'
+)?.get
+const SHARED_ARRAY_BUFFER_LENGTH =
+    typeof SharedArrayBuffer === 'function'
+        ? Object.getOwnPropertyDescriptor(
+              SharedArrayBuffer.prototype,
+              'byteLength'
+          )?.get
+        : null
+const TYPED_ARRAY_PROTOTYPE = Object.getPrototypeOf(Uint8Array.prototype)
+const TYPED_ARRAY_BUFFER = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    'buffer'
+)?.get
+const TYPED_ARRAY_OFFSET = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    'byteOffset'
+)?.get
+const TYPED_ARRAY_LENGTH = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    'byteLength'
+)?.get
+const DATA_VIEW_BUFFER = Object.getOwnPropertyDescriptor(
+    DataView.prototype,
+    'buffer'
+)?.get
+const DATA_VIEW_OFFSET = Object.getOwnPropertyDescriptor(
+    DataView.prototype,
+    'byteOffset'
+)?.get
+const DATA_VIEW_LENGTH = Object.getOwnPropertyDescriptor(
+    DataView.prototype,
+    'byteLength'
+)?.get
+const UINT8_ARRAY_SET = Uint8Array.prototype.set
+
+/**
+ * Reads and copies binary platform objects through captured intrinsic slots.
+ */
+export class BinaryDataSnapshot {
+    /**
+     * Describes one ArrayBuffer, SharedArrayBuffer, typed array, or DataView.
+     * @param {unknown} value Binary candidate.
+     * @returns {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number, kind: 'buffer' | 'typed-array' | 'data-view' } | null} Intrinsic binary range.
+     */
+    static describe(value) {
+        const arrayBufferLength = BinaryDataSnapshot.#callLength(
+            ARRAY_BUFFER_LENGTH,
+            value
+        )
+        if (arrayBufferLength !== null) {
+            return {
+                buffer: value,
+                byteOffset: 0,
+                byteLength: arrayBufferLength,
+                kind: 'buffer'
+            }
+        }
+        const sharedLength = BinaryDataSnapshot.#callLength(
+            SHARED_ARRAY_BUFFER_LENGTH,
+            value
+        )
+        if (sharedLength !== null) {
+            return {
+                buffer: value,
+                byteOffset: 0,
+                byteLength: sharedLength,
+                kind: 'buffer'
+            }
+        }
+
+        const typed = BinaryDataSnapshot.#view(
+            value,
+            TYPED_ARRAY_BUFFER,
+            TYPED_ARRAY_OFFSET,
+            TYPED_ARRAY_LENGTH,
+            'typed-array'
+        )
+        if (typed) return typed
+        return BinaryDataSnapshot.#view(
+            value,
+            DATA_VIEW_BUFFER,
+            DATA_VIEW_OFFSET,
+            DATA_VIEW_LENGTH,
+            'data-view'
+        )
+    }
+
+    /**
+     * Returns the exact intrinsic binary byte length.
+     * @param {unknown} value Binary candidate.
+     * @returns {number | null} Byte length or null for non-binary input.
+     */
+    static byteLength(value) {
+        return BinaryDataSnapshot.describe(value)?.byteLength ?? null
+    }
+
+    /**
+     * Copies the exact visible byte range into isolated non-shared memory.
+     * @param {unknown} value Binary candidate.
+     * @param {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number } | null} [capturedRange] Previously captured intrinsic range.
+     * @returns {Uint8Array} Isolated bytes.
+     */
+    static copyBytes(value, capturedRange = null) {
+        const range = capturedRange || BinaryDataSnapshot.describe(value)
+        if (!range) throw new TypeError('Expected binary data.')
+        try {
+            const source = new Uint8Array(
+                range.buffer,
+                range.byteOffset,
+                range.byteLength
+            )
+            const result = new Uint8Array(range.byteLength)
+            UINT8_ARRAY_SET.call(result, source)
+            return result
+        } catch {
+            throw new TypeError('Binary data changed during capture.')
+        }
+    }
+
+    /**
+     * Copies one binary metadata value while retaining its common view type.
+     * @param {unknown} value Binary metadata.
+     * @param {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number, kind: 'buffer' | 'typed-array' | 'data-view' } | null} [capturedRange] Previously captured intrinsic range.
+     * @returns {ArrayBuffer | Uint8Array | DataView} Isolated binary value.
+     */
+    static clone(value, capturedRange = null) {
+        const range = capturedRange || BinaryDataSnapshot.describe(value)
+        if (!range) throw new TypeError('Expected binary data.')
+        const bytes = BinaryDataSnapshot.copyBytes(value, range)
+        if (range.kind === 'buffer') return bytes.buffer
+        if (range.kind === 'data-view') return new DataView(bytes.buffer)
+
+        const prototype = Object.getPrototypeOf(value)
+        const Constructor = BinaryDataSnapshot.#typedArrayConstructor(prototype)
+        if (!Constructor || Constructor === Uint8Array) return bytes
+        const bytesPerElement = Constructor.BYTES_PER_ELEMENT
+        if (bytes.byteLength % bytesPerElement !== 0) return bytes
+        return new Constructor(bytes.buffer)
+    }
+
+    /**
+     * Calls a captured buffer length getter as a brand check.
+     * @param {Function | null | undefined} getter Intrinsic getter.
+     * @param {unknown} value Candidate value.
+     * @returns {number | null} Intrinsic length or null.
+     */
+    static #callLength(getter, value) {
+        if (typeof getter !== 'function') return null
+        try {
+            return getter.call(value)
+        } catch {
+            return null
+        }
+    }
+
+    /**
+     * Reads captured intrinsic view slots without ordinary property access.
+     * @param {unknown} value View candidate.
+     * @param {Function | undefined} bufferGetter Buffer getter.
+     * @param {Function | undefined} offsetGetter Offset getter.
+     * @param {Function | undefined} lengthGetter Length getter.
+     * @param {'typed-array' | 'data-view'} kind View kind.
+     * @returns {{ buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, byteLength: number, kind: 'typed-array' | 'data-view' } | null} Intrinsic view range.
+     */
+    static #view(value, bufferGetter, offsetGetter, lengthGetter, kind) {
+        if (
+            typeof bufferGetter !== 'function' ||
+            typeof offsetGetter !== 'function' ||
+            typeof lengthGetter !== 'function'
+        ) {
+            return null
+        }
+        try {
+            return {
+                buffer: bufferGetter.call(value),
+                byteOffset: offsetGetter.call(value),
+                byteLength: lengthGetter.call(value),
+                kind
+            }
+        } catch {
+            return null
+        }
+    }
+
+    /**
+     * Maps a genuine typed-array prototype to its platform constructor.
+     * @param {object | null} prototype Candidate prototype.
+     * @returns {Function | null} Matching typed-array constructor.
+     */
+    static #typedArrayConstructor(prototype) {
+        const constructors = [
+            Int8Array,
+            Uint8Array,
+            Uint8ClampedArray,
+            Int16Array,
+            Uint16Array,
+            Int32Array,
+            Uint32Array,
+            Float32Array,
+            Float64Array,
+            ...(typeof BigInt64Array === 'function'
+                ? [BigInt64Array, BigUint64Array]
+                : [])
+        ]
+        return (
+            constructors.find(
+                (Constructor) => Constructor.prototype === prototype
+            ) || null
+        )
+    }
+}
+
+Object.freeze(BinaryDataSnapshot.prototype)
+Object.freeze(BinaryDataSnapshot)

package/src/core/context/CircuitJsonContextIndexes.mjs

@@ -0,0 +1,96 @@
+import { CircuitJsonIndexer } from '../CircuitJsonIndexer.mjs'
+import { CircuitJsonValidationProof } from './CircuitJsonValidationProof.mjs'
+
+const INDEX_NAMES = new Set([
+    'elements',
+    'identifiers',
+    'relations',
+    'connectivity',
+    'spatial'
+])
+
+/**
+ * Owns lazily prepared named indexes for one document context.
+ */
+export class CircuitJsonContextIndexes {
+    #builds
+    #document
+    #indexes = new Map()
+    #model
+
+    /**
+     * Creates a context-owned index registry.
+     * @param {Record<string, any>} document Proven document envelope.
+     * @param {object[]} model Proven CircuitJSON model.
+     * @param {Record<string, number>} builds Named index build counters.
+     */
+    constructor(document, model, builds) {
+        this.#document = document
+        this.#model = model
+        this.#builds = builds
+    }
+
+    /**
+     * Ensures every requested named index is available.
+     * @param {unknown} names Requested index names.
+     * @returns {CircuitJsonContextIndexes} This registry.
+     */
+    ensure(names = []) {
+        for (const name of CircuitJsonContextIndexes.#names(names)) {
+            if (!INDEX_NAMES.has(name)) {
+                throw new RangeError(
+                    `Unsupported CircuitJSON context index: ${name}.`
+                )
+            }
+            if (this.#indexes.has(name)) continue
+
+            this.#indexes.set(name, this.#build(name))
+            this.#builds[name] = (this.#builds[name] || 0) + 1
+        }
+        return this
+    }
+
+    /**
+     * Returns one named index, creating it when first requested.
+     * @param {unknown} name Requested index name.
+     * @returns {Record<string, any>} Prepared index.
+     */
+    get(name) {
+        const normalized = String(name || '').trim()
+        this.ensure([normalized])
+        return this.#indexes.get(normalized)
+    }
+
+    /**
+     * Returns true when one named index is already prepared.
+     * @param {unknown} name Requested index name.
+     * @returns {boolean} Whether the named index exists.
+     */
+    has(name) {
+        return this.#indexes.has(String(name || '').trim())
+    }
+
+    /**
+     * Creates only the work family requested by one named index.
+     * @param {string} name Requested index name.
+     * @returns {Record<string, any>} Named index view.
+     */
+    #build(name) {
+        return CircuitJsonIndexer.index(
+            this.#model,
+            CircuitJsonValidationProof.indexOptions(this.#document, [name])
+        )
+    }
+
+    /**
+     * Normalizes an index name request.
+     * @param {unknown} names Requested names.
+     * @returns {string[]} Normalized names.
+     */
+    static #names(names) {
+        const candidates = Array.isArray(names) ? names : [names]
+        return [
+            ...new Set(candidates.map(String).map((name) => name.trim()))
+        ].filter(Boolean)
+    }
+}

package/src/core/context/CircuitJsonDerivedCache.mjs

@@ -0,0 +1,114 @@
+const VALUE_OWNERS = new WeakMap()
+
+/**
+ * Stores request-scoped derived values by namespace and key.
+ */
+export class CircuitJsonDerivedCache {
+    #builds
+    #namespaces = new Map()
+
+    /**
+     * Creates a request-scoped derived cache.
+     * @param {Record<string, number>} builds Successful build counters.
+     */
+    constructor(builds) {
+        this.#builds = builds
+    }
+
+    /**
+     * Returns an existing value or creates and caches one successful result.
+     * @param {string} namespace Cache namespace.
+     * @param {string} key Cache key.
+     * @param {() => any} factory Value factory.
+     * @returns {any} Cached or newly built value.
+     */
+    getOrCreate(namespace, key, factory) {
+        if (typeof factory !== 'function') {
+            throw new TypeError('A derived value factory is required.')
+        }
+
+        const entries = this.#entries(namespace)
+        if (entries.has(key)) return entries.get(key)
+
+        const value = factory()
+        if (
+            value &&
+            (typeof value === 'object' || typeof value === 'function') &&
+            typeof value.then === 'function'
+        ) {
+            throw new TypeError(
+                'Derived value factories must return synchronous values.'
+            )
+        }
+        CircuitJsonDerivedCache.#bindValue(this, namespace, key, value)
+        entries.set(key, value)
+        const statisticKey = `${namespace}:${key}`
+        this.#builds[statisticKey] = (this.#builds[statisticKey] || 0) + 1
+        return value
+    }
+
+    /**
+     * Returns whether an object value belongs to this exact cache entry.
+     * @param {string} namespace Cache namespace.
+     * @param {string} key Cache key.
+     * @param {unknown} value Derived value candidate.
+     * @returns {boolean} Whether ownership matches cache, namespace, and key.
+     */
+    owns(namespace, key, value) {
+        if (!CircuitJsonDerivedCache.#isObject(value)) return false
+        const owner = VALUE_OWNERS.get(value)
+        return (
+            owner?.cache === this &&
+            owner.namespace === namespace &&
+            owner.key === key
+        )
+    }
+
+    /**
+     * Returns the cache map for one namespace.
+     * @param {string} namespace Cache namespace.
+     * @returns {Map<string, any>} Namespace entries.
+     */
+    #entries(namespace) {
+        if (!this.#namespaces.has(namespace)) {
+            this.#namespaces.set(namespace, new Map())
+        }
+        return this.#namespaces.get(namespace)
+    }
+
+    /**
+     * Binds one object value to exactly one request-scoped cache entry.
+     * @param {CircuitJsonDerivedCache} cache Owning cache.
+     * @param {string} namespace Cache namespace.
+     * @param {string} key Cache key.
+     * @param {unknown} value Derived value.
+     * @returns {void}
+     */
+    static #bindValue(cache, namespace, key, value) {
+        if (!CircuitJsonDerivedCache.#isObject(value)) return
+        const owner = VALUE_OWNERS.get(value)
+        if (
+            owner &&
+            (owner.cache !== cache ||
+                owner.namespace !== namespace ||
+                owner.key !== key)
+        ) {
+            throw new TypeError(
+                'Derived object values cannot be transplanted between cache entries.'
+            )
+        }
+        VALUE_OWNERS.set(value, { cache, namespace, key })
+    }
+
+    /**
+     * Returns whether a value can be owned through a WeakMap.
+     * @param {unknown} value Value candidate.
+     * @returns {boolean} Whether the value is an object or function.
+     */
+    static #isObject(value) {
+        return (
+            value !== null &&
+            (typeof value === 'object' || typeof value === 'function')
+        )
+    }
+}