@spine-event-engine/storage 2.0.0-snapshot.2 → 2.0.0-snapshot.21

package/dist/memory/tenant-records.js

@@ -12,9 +12,11 @@
  * the License.
  */
 import { CanonicalUtf8 } from "./canonical-utf8.js";
-const tenantRecordsHost = globalThis;
 /**
- * Record slice owned by one tenant of an in-memory record storage.
+ * Record slice for one tenant of an in-memory record storage.
+ *
+ * @typeParam I Record identifier type.
+ * @typeParam R Stored Protobuf message type.
  */
 export class TenantRecords {
     #records = new Map();
@@ -86,22 +88,25 @@ export class TenantRecords {
         }
     }
     /**
-     * Copies the materialized rows for a provider-owned staged commit.
+     * Captures one complete materialized slot for an Entity commit.
      *
-     * @returns An independent snapshot of the current rows.
+     * @param id Identifies the affected slot.
+     * @returns The slot key and its prior entry, including materialized columns.
      */
-    snapshot() {
-        return tenantRecordsHost.structuredClone(this.#records);
+    capture(id) {
+        const key = StoredValues.key(id);
+        return { key, entry: this.#records.get(key) };
     }
     /**
-     * Replaces all rows from a fully validated staged snapshot.
+     * Applies or restores one prepared slot without recomputing its key.
      *
-     * @param snapshot Supplies the staged materialized rows.
+     * @param slot Supplies the prepared key and complete entry or prior absence.
      */
-    replace(snapshot) {
-        this.#records.clear();
-        for (const [key, value] of snapshot)
-            this.#records.set(key, value);
+    apply(slot) {
+        if (slot.entry === undefined)
+            this.#records.delete(slot.key);
+        else
+            this.#records.set(slot.key, slot.entry);
     }
 }
 /**
@@ -111,6 +116,11 @@ const StoredRecords = {
     // prettier-ignore
     /**
      * Determines whether two materialized records represent the same stored value.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param left Supplies the first materialized record, when present.
+     * @param right Supplies the second materialized record, when present.
+     * @returns Whether both records have the same stored value.
      */
     equal(left, right) {
         if (left === undefined || right === undefined)
@@ -124,7 +134,13 @@ const StoredRecords = {
 const TenantRecordQuery = {
     // prettier-ignore
     /**
-     * Produces logical entries for one tenant-scoped query.
+     * Returns logical entries for one tenant-scoped query.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entries Supplies this tenant's stored entries.
+     * @param spec Defines record identity and materialized columns.
+     * @param query Specifies filters, ordering, continuation, and windowing.
+     * @returns Matching logical record entries in query order.
      */
     entries(entries, spec, query) {
         const bounded = TenantRecordQuery.selectBounded(entries, spec, query);
@@ -143,38 +159,160 @@ const TenantRecordQuery = {
         }));
     },
     /**
-     * Selects the finite ordered window without retaining every matching entry.
+     * Returns the finite ordered window without retaining every matching entry.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entries Supplies this tenant's stored entries.
+     * @param spec Defines record identity and materialized columns.
+     * @param query Specifies filters, ordering, continuation, and windowing.
+     * @returns The selected window, or undefined when bounded selection does not apply.
      */
     selectBounded(entries, spec, query) {
-        if (query.limit === undefined || !Number.isFinite(query.limit))
+        const windowSize = TenantRecordQuery.boundedWindowSize(query.limit, query.offset);
+        if (windowSize === undefined)
             return undefined;
         const offset = query.offset ?? 0;
-        const windowSize = offset + query.limit;
-        if (!Number.isInteger(offset) ||
-            !Number.isInteger(query.limit) ||
-            offset < 0 ||
-            query.limit < 0) {
-            return undefined;
-        }
         if (windowSize === 0)
             return [];
         const orders = query.sort ?? [];
         const selected = [];
+        const filters = TenantRecordQuery.prepareFilters(query.filters);
+        const after = query.after === undefined ? undefined : TenantRecordQuery.prepareContinuation(query.after);
         for (const entry of entries) {
-            if (!TenantRecordQuery.matches(spec, entry, query) ||
-                (query.after !== undefined &&
-                    TenantRecordQuery.compareToContinuation(entry, orders, query.after) <= 0)) {
+            if (!TenantRecordQuery.matchesIds(spec, entry, query.ids) ||
+                !TenantRecordQuery.matchesPreparedFilters(entry.stored, filters))
+                continue;
+            const prepared = TenantRecordQuery.prepareEntry(entry, orders);
+            if (after !== undefined &&
+                TenantRecordQuery.comparePreparedAfter(prepared, orders, after) <= 0)
                 continue;
-            }
-            TenantRecordQuery.insertSelected(selected, entry, windowSize, orders);
+            TenantRecordQuery.insertSelected(selected, prepared, windowSize, orders);
         }
-        return selected.slice(offset);
+        return selected.slice(offset).map((candidate) => candidate.entry);
+    },
+    /**
+     * Determines the finite selection capacity of one bounded query.
+     * @param limit Maximum returned record count.
+     * @param offset Number of leading matches to skip.
+     * @returns Required capacity, or undefined for an unbounded query.
+     */
+    boundedWindowSize(limit, offset) {
+        if (limit === undefined || !Number.isFinite(limit))
+            return undefined;
+        const start = offset ?? 0;
+        if (!Number.isInteger(start) || !Number.isInteger(limit) || start < 0 || limit < 0)
+            return undefined;
+        return start + limit;
+    },
+    /**
+     * Prepares expected filter values once for a bounded query.
+     * @param filters Supplies the requested column filters.
+     * @returns Canonical expected values for each filter.
+     */
+    prepareFilters(filters) {
+        return filters?.map((filter) => ({
+            column: filter.column,
+            keys: (Array.isArray(filter.value) ? filter.value : [filter.value]).map((value) => StoredValues.key(value)),
+        }));
     },
     /**
-     * Inserts an entry into a bounded, ordered top window.
+     * Matches materialized columns against filter keys prepared for this query.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entry Supplies the materialized record.
+     * @param filters Supplies the prepared column filters, when present.
+     * @returns Whether every filter matches the record.
+     */
+    matchesPreparedFilters(entry, filters) {
+        if (filters === undefined || filters.length === 0)
+            return true;
+        return filters.every((filter) => filter.keys.includes(StoredValues.key(TenantRecordQuery.resolveValue(entry, filter.column))));
+    },
+    /**
+     * Normalizes an entry's identity and ordered fields once for this query.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entry Supplies the matching materialized record.
+     * @param orders Specifies the requested sort fields.
+     * @returns The prepared comparison values and original entry.
+     */
+    prepareEntry(entry, orders) {
+        const id = StoredValues.normalize(entry.slotId);
+        return {
+            entry,
+            id,
+            values: orders.map((order) => order.field === "id"
+                ? id
+                : StoredValues.normalize(TenantRecordQuery.resolveValue(entry.stored, order.field))),
+        };
+    },
+    /**
+     * Normalizes the requested keyset position once for this query.
+     * @typeParam I Record identifier type.
+     * @param after Supplies the keyset position.
+     * @returns The prepared continuation values.
+     */
+    prepareContinuation(after) {
+        return {
+            id: StoredValues.normalize(after.id),
+            values: after.values.map((value) => StoredValues.normalize(value.value)),
+        };
+    },
+    /**
+     * Compares prepared entries by requested fields and storage identity.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param left Supplies the first prepared entry.
+     * @param right Supplies the second prepared entry.
+     * @param orders Specifies the requested sort fields.
+     * @returns A negative, zero, or positive comparison result.
+     */
+    comparePrepared(left, right, orders) {
+        for (let index = 0; index < orders.length; index += 1) {
+            const order = orders[index];
+            if (order === undefined)
+                throw new Error("Record query sort order is invalid.");
+            const comparison = order.field === "id"
+                ? StoredValues.compareIdentityNormalized(left.id, right.id)
+                : StoredValues.compareNormalized(left.values[index], right.values[index]);
+            if (comparison !== 0)
+                return order.direction === "desc" ? comparison * -1 : comparison;
+        }
+        return StoredValues.compareIdentityNormalized(left.id, right.id);
+    },
+    /**
+     * Compares one prepared entry to a normalized keyset continuation.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entry Supplies the prepared entry.
+     * @param orders Specifies the requested sort fields.
+     * @param after Supplies the prepared continuation.
+     * @returns A negative, zero, or positive comparison result.
+     */
+    comparePreparedAfter(entry, orders, after) {
+        for (let index = 0; index < orders.length; index += 1) {
+            const order = orders[index];
+            if (order === undefined)
+                throw new Error("Record query continuation sort order is invalid.");
+            const comparison = order.field === "id"
+                ? StoredValues.compareIdentityNormalized(entry.id, after.values[index])
+                : StoredValues.compareNormalized(entry.values[index], after.values[index]);
+            if (comparison !== 0)
+                return order.direction === "desc" ? comparison * -1 : comparison;
+        }
+        return StoredValues.compareIdentityNormalized(entry.id, after.id);
+    },
+    /**
+     * Adds an entry to a bounded, ordered top window.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param selected Supplies the current prepared window to update.
+     * @param entry Supplies the prepared candidate entry.
+     * @param windowSize Sets the maximum number of entries to retain.
+     * @param orders Specifies the requested sort order.
      */
     insertSelected(selected, entry, windowSize, orders) {
-        const comparison = (candidate) => TenantRecordQuery.compareEntries(candidate, entry, orders);
+        const comparison = (candidate) => TenantRecordQuery.comparePrepared(candidate, entry, orders);
         let low = 0;
         let high = selected.length;
         while (low < high) {
@@ -195,6 +333,11 @@ const TenantRecordQuery = {
     },
     /**
      * Applies offset and limit after filtering, ordering, and continuation.
+     * @typeParam T Record entry type.
+     * @param records Supplies ordered matching records.
+     * @param offset Sets the number of leading records to skip.
+     * @param limit Sets the maximum number of records to return.
+     * @returns The requested record window.
      */
     applyWindow(records, offset, limit) {
         const start = offset ?? 0;
@@ -202,6 +345,12 @@ const TenantRecordQuery = {
     },
     /**
      * Removes entries at or before a keyset continuation.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param records Supplies ordered matching records.
+     * @param orders Specifies the requested sort order.
+     * @param after Supplies the continuation position, when present.
+     * @returns Records after the continuation position.
      */
     continueAfter(records, orders, after) {
         return after === undefined
@@ -209,7 +358,13 @@ const TenantRecordQuery = {
             : records.filter((entry) => TenantRecordQuery.compareToContinuation(entry, orders, after) > 0);
     },
     /**
-     * Orders entries by requested fields and storage-slot identity.
+     * Returns the comparison of entries by requested fields and storage-slot identity.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param left Supplies the first entry to compare.
+     * @param right Supplies the second entry to compare.
+     * @param orders Specifies the requested sort order.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareEntries(left, right, orders) {
         for (const order of orders) {
@@ -222,7 +377,13 @@ const TenantRecordQuery = {
         return StoredValues.compareIdentity(left.slotId, right.slotId);
     },
     /**
-     * Orders an entry relative to one keyset continuation.
+     * Returns the comparison of an entry with one keyset continuation.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entry Supplies the entry to compare.
+     * @param orders Specifies the requested sort order.
+     * @param after Supplies the continuation position.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareToContinuation(entry, orders, after) {
         for (let index = 0; index < orders.length; index += 1) {
@@ -239,6 +400,12 @@ const TenantRecordQuery = {
     },
     /**
      * Matches one entry against ID and column filters.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param spec Defines record identity and materialized columns.
+     * @param entry Supplies the candidate entry.
+     * @param query Specifies ID and column filters.
+     * @returns Whether the entry matches the query filters.
      */
     matches(spec, entry, query) {
         return (TenantRecordQuery.matchesIds(spec, entry, query.ids) &&
@@ -246,6 +413,11 @@ const TenantRecordQuery = {
     },
     /**
      * Matches materialized values against all requested column filters.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entry Supplies the materialized record and columns.
+     * @param filters Specifies column filters, when present.
+     * @returns Whether every filter matches the entry.
      */
     matchesFilters(entry, filters) {
         if (filters === undefined || filters.length === 0)
@@ -258,6 +430,12 @@ const TenantRecordQuery = {
     },
     /**
      * Matches an entry's storage slot against requested logical IDs.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param spec Defines how record identifiers are copied.
+     * @param entry Supplies the candidate entry.
+     * @param ids Specifies requested identifiers, when present.
+     * @returns Whether the entry matches a requested identifier.
      */
     matchesIds(spec, entry, ids) {
         if (ids === undefined || ids.length === 0)
@@ -266,6 +444,11 @@ const TenantRecordQuery = {
     },
     /**
      * Resolves an ID, materialized column, or record path value.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf message type.
+     * @param entry Supplies the materialized record.
+     * @param field Names the ID, column, or record path to read.
+     * @returns The resolved field value.
      */
     resolveValue(entry, field) {
         if (field === "id")
@@ -282,24 +465,35 @@ const StoredValues = {
     // prettier-ignore
     /**
      * Creates a canonical value key.
+     * @param value Supplies the value to encode.
+     * @returns A canonical key for the value.
      */
     key(value) {
-        return StoredValues.encode(StoredValues.normalize(value));
+        return JSON.stringify(StoredValues.encoded(value));
     },
     /**
      * Compares values with the storage ordering rules.
+     * @param left Supplies the first value.
+     * @param right Supplies the second value.
+     * @returns A negative, zero, or positive comparison result.
      */
     compare(left, right) {
         return StoredValues.compareNormalized(StoredValues.normalize(left), StoredValues.normalize(right));
     },
     /**
      * Compares storage slot identities with canonical UTF-8 text ordering.
+     * @param left Supplies the first identity.
+     * @param right Supplies the second identity.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareIdentity(left, right) {
         return StoredValues.compareIdentityNormalized(StoredValues.normalize(left), StoredValues.normalize(right));
     },
     /**
      * Reads a dot-separated path from an object value.
+     * @param value Supplies the value to inspect.
+     * @param path Names the dot-separated property path.
+     * @returns The value at the path, or undefined when absent.
      */
     readPath(value, path) {
         let current = value;
@@ -312,6 +506,9 @@ const StoredValues = {
     },
     /**
      * Compares normalized values of the same or distinct kinds.
+     * @param left Supplies the first normalized value.
+     * @param right Supplies the second normalized value.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareNormalized(left, right) {
         const leftKind = StoredValues.kind(left);
@@ -340,6 +537,9 @@ const StoredValues = {
     },
     /**
      * Compares normalized storage identities, treating text as canonical UTF-8 bytes.
+     * @param left Supplies the first normalized identity.
+     * @param right Supplies the second normalized identity.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareIdentityNormalized(left, right) {
         const leftKind = StoredValues.kind(left);
@@ -368,6 +568,9 @@ const StoredValues = {
     },
     /**
      * Compares numbers while placing NaN after other numbers.
+     * @param left Supplies the first number.
+     * @param right Supplies the second number.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareNumbers(left, right) {
         if (Number.isNaN(left) || Number.isNaN(right))
@@ -376,6 +579,9 @@ const StoredValues = {
     },
     /**
      * Compares encoded bigint payloads numerically.
+     * @param left Supplies the first encoded bigint.
+     * @param right Supplies the second encoded bigint.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareBigInts(left, right) {
         const l = BigInt(left);
@@ -384,6 +590,10 @@ const StoredValues = {
     },
     /**
      * Compares lists lexicographically.
+     * @typeParam T List element type.
+     * @param left Supplies the first list.
+     * @param right Supplies the second list.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareLists(left, right) {
         for (let index = 0; index < Math.min(left.length, right.length); index += 1) {
@@ -397,6 +607,9 @@ const StoredValues = {
     },
     /**
      * Compares normalized objects by keys and then values.
+     * @param left Supplies the first normalized object.
+     * @param right Supplies the second normalized object.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareObjects(left, right) {
         const leftKeys = Object.keys(left);
@@ -412,12 +625,18 @@ const StoredValues = {
     },
     /**
      * Compares strings in code-unit order.
+     * @param left Supplies the first string.
+     * @param right Supplies the second string.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareText(left, right) {
         return left < right ? -1 : left > right ? 1 : 0;
     },
     /**
      * Compares identity-value lists recursively.
+     * @param left Supplies the first normalized identity list.
+     * @param right Supplies the second normalized identity list.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareIdentityLists(left, right) {
         for (let index = 0; index < Math.min(left.length, right.length); index += 1) {
@@ -429,6 +648,9 @@ const StoredValues = {
     },
     /**
      * Compares object-shaped identities by canonical keys and values.
+     * @param left Supplies the first normalized identity object.
+     * @param right Supplies the second normalized identity object.
+     * @returns A negative, zero, or positive comparison result.
      */
     compareIdentityObjects(left, right) {
         const leftKeys = Object.keys(left);
@@ -445,6 +667,8 @@ const StoredValues = {
     },
     /**
      * Normalizes a value for canonical storage comparison.
+     * @param value Supplies the value to normalize.
+     * @returns The normalized value representation.
      */
     normalize(value) {
         if (typeof value === "bigint")
@@ -472,54 +696,39 @@ const StoredValues = {
         }, StoredValues.emptyObject());
     },
     /**
-     * Encodes a normalized value without type collisions.
-     */
-    encode(value) {
-        return JSON.stringify(StoredValues.encoded(value));
-    },
-    /**
-     * Converts a normalized value to its tagged JSON representation.
+     * Converts a raw value to its tagged JSON representation.
+     * @param value Supplies the raw value.
+     * @returns The tagged JSON representation.
      */
     encoded(value) {
-        const kind = StoredValues.kind(value);
-        switch (kind) {
-            case "undefined":
-                return ["undefined"];
-            case "null":
-                return ["null"];
-            case "boolean":
-                if (typeof value !== "boolean")
-                    throw new Error("Normalized boolean value has an unexpected type.");
-                return ["boolean", value];
-            case "number":
-                if (typeof value !== "number")
-                    throw new Error("Normalized number value has an unexpected type.");
-                return ["number", String(value)];
-            case "string":
-                if (typeof value !== "string")
-                    throw new Error("Normalized string value has an unexpected type.");
-                return ["string", value];
-            case "bigint":
-                return ["bigint", StoredValues.payload(value)];
-            case "bytes":
-                return ["bytes", StoredValues.payload(value)];
-            case "array":
-                return [
-                    "array",
-                    ...value.map((entry) => StoredValues.encoded(entry)),
-                ];
-            case "object":
-                return [
-                    "object",
-                    ...Object.keys(value).map((key) => [
-                        key,
-                        StoredValues.encoded(value[key]),
-                    ]),
-                ];
-        }
+        if (value === undefined)
+            return ["undefined"];
+        if (value === null)
+            return ["null"];
+        if (typeof value === "boolean")
+            return ["boolean", value];
+        if (typeof value === "number")
+            return ["number", String(value)];
+        if (typeof value === "string")
+            return ["string", value];
+        if (typeof value === "bigint")
+            return ["bigint", value.toString()];
+        if (value instanceof Uint8Array)
+            return ["bytes", [...value]];
+        if (Array.isArray(value))
+            return ["array", ...value.map((entry) => StoredValues.encoded(entry))];
+        if (typeof value !== "object")
+            return ["undefined"];
+        // Evaluate fields in lexical order, then use native numeric-name enumeration.
+        const entries = Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, StoredValues.encoded(Reflect.get(value, key))]));
+        return ["object", ...Object.entries(entries)];
     },
     /**
-     * Identifies a normalized value kind.
+     * Returns the kind of a normalized value.
+     * @param value Supplies the normalized value.
+     * @returns The normalized value kind.
      */
     kind(value) {
         if (value === undefined)
@@ -539,6 +748,11 @@ const StoredValues = {
     },
     /**
      * Creates a frozen tagged normalized value.
+     * @typeParam K Tag kind.
+     * @typeParam P Payload type.
+     * @param kind Identifies the tag kind.
+     * @param payload Supplies the tag payload.
+     * @returns The frozen tagged value.
      */
     tagged(kind, payload) {
         const tagged = Object.create(null);
@@ -550,6 +764,8 @@ const StoredValues = {
     },
     /**
      * Reads a recognized normalized tag.
+     * @param value Supplies the object to inspect.
+     * @returns The recognized tag, or undefined for an ordinary object.
      */
     tag(value) {
         const tag = value[normalizedKind];
@@ -557,12 +773,16 @@ const StoredValues = {
     },
     /**
      * Creates an object with no prototype for normalized fields.
+     * @returns An empty object without a prototype.
      */
     emptyObject() {
         return Object.create(null);
     },
     /**
      * Reads a tagged normalized payload.
+     * @typeParam P Payload type.
+     * @param value Supplies the tagged value.
+     * @returns The tagged payload.
      */
     payload(value) {
         return value[normalizedPayload];