@spine-event-engine/storage 2.0.0-snapshot.10

package/dist/query/query-execution.d.ts

@@ -0,0 +1,50 @@
+import type { NormalizedQueryPlan } from "./query-policy.js";
+/**
+ * Finite default number of provider candidates a normalized plan may materialize.
+ */
+export declare const defaultQueryCandidateLimit = 10000;
+/**
+ * One materialized storage row accepted by the shared normalized evaluator.
+ */
+export interface NormalizedQueryEntry<Id, Record> {
+    /**
+     * Identifies the stored row.
+     */
+    readonly id: Id;
+    /**
+     * Carries the materialized stored record.
+     */
+    readonly record: Record;
+    /**
+     * Maps normalized query columns to row values.
+     */
+    readonly columns: ReadonlyMap<string, unknown>;
+}
+/**
+ * Raised before evaluating a plan that exceeded its finite candidate budget.
+ */
+export declare class QueryCandidateLimitError extends Error {
+    readonly candidateLimit: number;
+    /**
+     * Creates a candidate-limit error.
+     *
+     * @param candidateLimit Specifies the exceeded candidate budget.
+     */
+    constructor(candidateLimit: number);
+}
+/**
+ * Shared complete in-process semantics for one validated normalized query plan.
+ */
+export declare const StorageQueryEvaluator: Readonly<{
+    evaluate<Id, Record>(entries: readonly NormalizedQueryEntry<Id, Record>[], plan: NormalizedQueryPlan<Id>): readonly NormalizedQueryEntry<Id, Record>[];
+}>;
+/**
+ * Shared deterministic value semantics for provider-side query adapters.
+ *
+ * @internal
+ */
+export declare const StorageQueryValues: Readonly<{
+    equal(left: unknown, right: unknown): boolean;
+    compare(left: unknown, right: unknown): number;
+}>;
+//# sourceMappingURL=query-execution.d.ts.map

package/dist/query/query-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-execution.d.ts","sourceRoot":"","sources":["../../src/query/query-execution.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,mBAAmB,EAEpB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,EAAE,EAAE,MAAM;IAG9C;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAQrC,QAAQ,CAAC,cAAc,EAAE,MAAM;IAL3C;;;;OAIG;gBACkB,cAAc,EAAE,MAAM;CAI5C;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,oBAAoB,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,EACpD,IAAI,EAAE,mBAAmB,CAAC,EAAE,CAAC,GAC5B,SAAS,oBAAoB,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;CAChD,CAaC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC;IACxC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAC9C,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;CAChD,CAQC,CAAC"}

package/dist/query/query-execution.js

@@ -0,0 +1,222 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Finite default number of provider candidates a normalized plan may materialize.
+ */
+export const defaultQueryCandidateLimit = 10_000;
+/**
+ * Raised before evaluating a plan that exceeded its finite candidate budget.
+ */
+export class QueryCandidateLimitError extends Error {
+    candidateLimit;
+    // prettier-ignore
+    /**
+     * Creates a candidate-limit error.
+     *
+     * @param candidateLimit Specifies the exceeded candidate budget.
+     */
+    constructor(candidateLimit) {
+        super(`Storage query exceeded the candidate limit of ${String(candidateLimit)}.`);
+        this.candidateLimit = candidateLimit;
+        this.name = "QueryCandidateLimitError";
+    }
+}
+/**
+ * Shared complete in-process semantics for one validated normalized query plan.
+ */
+export const StorageQueryEvaluator = Object.freeze({
+    evaluate(entries, plan) {
+        const predicate = plan.predicate;
+        const matching = predicate === undefined
+            ? [...entries]
+            : entries.filter((entry) => QueryPredicateMatcher.matches(entry, predicate));
+        const ordered = matching.sort((left, right) => QueryOrdering.compareEntries(left, right, plan));
+        return plan.limit === undefined ? ordered : ordered.slice(0, plan.limit);
+    },
+});
+/**
+ * Shared deterministic value semantics for provider-side query adapters.
+ *
+ * @internal
+ */
+export const StorageQueryValues = Object.freeze({
+    equal(left, right) {
+        return QueryPredicateMatcher.equalValues(left, right);
+    },
+    compare(left, right) {
+        return QueryOrdering.compareStable(left, right);
+    },
+});
+/**
+ * Matches normalized predicates against materialized storage rows.
+ */
+const QueryPredicateMatcher = {
+    // prettier-ignore
+    /**
+     * Matches a row against one normalized predicate.
+     */
+    matches(entry, predicate) {
+        switch (predicate.kind) {
+            case "ids":
+                return predicate.ids.some((id) => QueryPredicateMatcher.equalValues(id, entry.id));
+            case "comparison":
+                return QueryPredicateMatcher.comparePredicate(entry.columns.get(predicate.column), predicate.operator, predicate.value);
+            case "all":
+                return predicate.predicates.every((child) => QueryPredicateMatcher.matches(entry, child));
+            case "either":
+                return predicate.predicates.some((child) => QueryPredicateMatcher.matches(entry, child));
+        }
+    },
+    /**
+     * Evaluates one normalized comparison predicate.
+     */
+    comparePredicate(actual, operator, expected) {
+        if (operator === "equal")
+            return QueryPredicateMatcher.equalValues(actual, expected);
+        if (QueryOrdering.isMissing(actual) || QueryOrdering.isMissing(expected))
+            return false;
+        const result = QueryOrdering.compareOrdered(actual, expected);
+        if (operator === "greaterThan")
+            return result > 0;
+        if (operator === "lessThan")
+            return result < 0;
+        if (operator === "greaterOrEqual")
+            return result >= 0;
+        return result <= 0;
+    },
+    /**
+     * Compares values using normalized query equality semantics.
+     */
+    equalValues(left, right) {
+        if (QueryOrdering.isMissing(left) || QueryOrdering.isMissing(right)) {
+            return QueryOrdering.isMissing(left) && QueryOrdering.isMissing(right);
+        }
+        return QueryOrdering.stableKey(left) === QueryOrdering.stableKey(right);
+    },
+};
+/**
+ * Orders normalized query values and materialized rows deterministically.
+ */
+const QueryOrdering = {
+    // prettier-ignore
+    /**
+     * Compares two rows by requested ordering and stable ID tie-breaker.
+     */
+    compareEntries(left, right, plan) {
+        for (const order of plan.order ?? []) {
+            const comparison = QueryOrdering.compareWithMissing(left.columns.get(order.column), right.columns.get(order.column));
+            if (comparison !== 0)
+                return order.direction === "desc" ? comparison * -1 : comparison;
+        }
+        return QueryOrdering.compareStable(left.id, right.id);
+    },
+    /**
+     * Compares values while placing missing values before present values.
+     */
+    compareWithMissing(left, right) {
+        if (QueryOrdering.isMissing(left) || QueryOrdering.isMissing(right)) {
+            if (QueryOrdering.isMissing(left) && QueryOrdering.isMissing(right))
+                return 0;
+            return QueryOrdering.isMissing(left) ? -1 : 1;
+        }
+        return QueryOrdering.compareOrdered(left, right);
+    },
+    /**
+     * Compares values supported by normalized query ordering.
+     */
+    compareOrdered(left, right) {
+        if (typeof left === "number" && typeof right === "number")
+            return QueryOrdering.compareNumber(left, right);
+        if (typeof left === "bigint" && typeof right === "bigint") {
+            return left < right ? -1 : left > right ? 1 : 0;
+        }
+        if (typeof left === "string" && typeof right === "string")
+            return QueryOrdering.compareText(left, right);
+        if (QueryOrdering.isOrderedMessage(left) &&
+            QueryOrdering.isOrderedMessage(right) &&
+            left.$typeName === right.$typeName) {
+            if (left.$typeName === "google.protobuf.Timestamp") {
+                return QueryOrdering.comparePair(left.seconds, left.nanos, right.seconds, right.nanos);
+            }
+            return QueryOrdering.comparePair(left.number, left.timestamp, right.number, right.timestamp);
+        }
+        throw new TypeError("Normalized query ordering value has an unsupported type.");
+    },
+    /**
+     * Compares ordered-message major and minor components.
+     */
+    comparePair(leftMajor, leftMinor, rightMajor, rightMinor) {
+        const major = QueryOrdering.compareStable(leftMajor, rightMajor);
+        return major === 0 ? QueryOrdering.compareStable(leftMinor, rightMinor) : major;
+    },
+    /**
+     * Compares values with a deterministic fallback for distinct shapes.
+     */
+    compareStable(left, right) {
+        if (QueryOrdering.isMissing(left) || QueryOrdering.isMissing(right))
+            return QueryOrdering.compareWithMissing(left, right);
+        if (typeof left === typeof right && ["number", "bigint", "string"].includes(typeof left)) {
+            return QueryOrdering.compareOrdered(left, right);
+        }
+        return QueryOrdering.compareText(QueryOrdering.stableKey(left), QueryOrdering.stableKey(right));
+    },
+    /**
+     * Creates a deterministic value representation for equality and tie-breaking.
+     */
+    stableKey(value) {
+        if (value instanceof Uint8Array)
+            return `bytes:${[...value].join(".")}`;
+        if (typeof value === "bigint")
+            return `bigint:${value.toString()}`;
+        if (typeof value !== "object" || value === null)
+            return `${typeof value}:${String(value)}`;
+        if (Array.isArray(value))
+            return `array:[${value.map((item) => QueryOrdering.stableKey(item)).join(",")}]`;
+        return `object:{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${QueryOrdering.stableKey(Reflect.get(value, key))}`)
+            .join(",")}}`;
+    },
+    /**
+     * Identifies ordered Protobuf timestamp and version values.
+     */
+    isOrderedMessage(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            (Reflect.get(value, "$typeName") === "google.protobuf.Timestamp" ||
+                Reflect.get(value, "$typeName") === "spine.core.Version"));
+    },
+    /**
+     * Compares finite numeric values.
+     */
+    compareNumber(left, right) {
+        if (!Number.isFinite(left) || !Number.isFinite(right)) {
+            throw new TypeError("Normalized query ordering numbers must be finite.");
+        }
+        return left < right ? -1 : left > right ? 1 : 0;
+    },
+    /**
+     * Compares text values in code-unit order.
+     */
+    compareText(left, right) {
+        return left < right ? -1 : left > right ? 1 : 0;
+    },
+    /**
+     * Identifies absent normalized query values.
+     */
+    isMissing(value) {
+        return value === undefined || value === null;
+    },
+};
+//# sourceMappingURL=query-execution.js.map

package/dist/query/query-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-execution.js","sourceRoot":"","sources":["../../src/query/query-execution.ts"],"names":[],"mappings":"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"}

package/dist/query/query-policy.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Normalized comparison operators understood by storage providers.
+ */
+export type NormalizedComparisonOperator = "equal" | "greaterThan" | "lessThan" | "greaterOrEqual" | "lessOrEqual";
+/**
+ * Provider-independent normalized query predicate.
+ */
+export type NormalizedQueryPredicate<Id> = Readonly<{
+    /**
+     * Identifies the predicate as an explicit ID set.
+     */
+    kind: "ids";
+    /**
+     * Lists the IDs selected by the predicate.
+     */
+    ids: readonly Id[];
+}> | Readonly<{
+    /**
+     * Identifies the predicate as a column comparison.
+     */
+    kind: "comparison";
+    /**
+     * Names the compared record column.
+     */
+    column: string;
+    /**
+     * Selects the comparison operator.
+     */
+    operator: NormalizedComparisonOperator;
+    /**
+     * Provides the value compared against the column.
+     */
+    value: unknown;
+}> | Readonly<{
+    /**
+     * Identifies the predicate as an all-or-either composition.
+     */
+    kind: "all" | "either";
+    /**
+     * Lists the component predicates.
+     */
+    predicates: readonly NormalizedQueryPredicate<Id>[];
+}>;
+/**
+ * Provider-independent normalized query ordering.
+ */
+export interface NormalizedQueryOrder {
+    /**
+     * Names the column used for ordering.
+     */
+    readonly column: string;
+    /**
+     * Selects ascending or descending order.
+     */
+    readonly direction: "asc" | "desc";
+}
+/**
+ * Provider-independent normalized field mask.
+ */
+export interface NormalizedQueryMask {
+    /**
+     * Lists the record paths retained by the mask.
+     */
+    readonly paths: readonly string[];
+}
+/**
+ * Canonical query plan accepted at the storage-provider boundary.
+ */
+export interface NormalizedQueryPlan<Id> {
+    /**
+     * Defines the optional predicate.
+     */
+    readonly predicate?: NormalizedQueryPredicate<Id>;
+    /**
+     * Defines the optional ordering.
+     */
+    readonly order?: readonly NormalizedQueryOrder[];
+    /**
+     * Defines the optional field mask.
+     */
+    readonly mask?: NormalizedQueryMask;
+    /**
+     * Limits matching rows after ordering.
+     */
+    readonly limit?: number;
+    /**
+     * Maximum provider rows materialized before semantic evaluation. Values must
+     * be positive safe integers; the default and inclusive maximum are 10,000.
+     */
+    readonly candidateLimit?: number;
+}
+/**
+ * Optional normalized query features a storage provider can execute.
+ */
+export type StorageQueryFeature = "either" | "nested" | "order" | "mask" | "limit";
+/**
+ * Explicit query capabilities advertised by a storage provider.
+ */
+export interface StorageQueryCapabilities {
+    /**
+     * Lists supported comparison operators.
+     */
+    readonly comparisons: readonly NormalizedComparisonOperator[];
+    /**
+     * Lists supported normalized query features.
+     */
+    readonly features: readonly StorageQueryFeature[];
+}
+/**
+ * Shared fail-fast validation for normalized plans before provider execution.
+ */
+export declare const StorageQueryPolicy: Readonly<{
+    validate<Id>(plan: NormalizedQueryPlan<Id>, capabilities: StorageQueryCapabilities): void;
+}>;
+//# sourceMappingURL=query-policy.d.ts.map

package/dist/query/query-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-policy.d.ts","sourceRoot":"","sources":["../../src/query/query-policy.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,MAAM,4BAA4B,GACtC,OAAO,GAAG,aAAa,GAAG,UAAU,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAAC,EAAE,IACnC,QAAQ,CAAC;IAGP;;OAEG;IACH,IAAI,EAAE,KAAK,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;CACpB,CAAC,GACF,QAAQ,CAAC;IAGP;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,4BAA4B,CAAC;IAEvC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC,GACF,QAAQ,CAAC;IAGP;;OAEG;IACH,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAEvB;;OAEG;IACH,UAAU,EAAE,SAAS,wBAAwB,CAAC,EAAE,CAAC,EAAE,CAAC;CACrD,CAAC,CAAC;AAEP;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,EAAE;IAGrC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,wBAAwB,CAAC,EAAE,CAAC,CAAC;IAElD;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAEjD;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,wBAAwB;IAGvC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,4BAA4B,EAAE,CAAC;IAE9D;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AAcD;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC;IACxC,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,mBAAmB,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC3F,CAwBC,CAAC"}