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

package/dist/query/query-policy.js

@@ -0,0 +1,294 @@
+/*
+ * 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.
+ */
+const maximumPredicateDepth = 64;
+const maximumPredicateNodes = 10_000;
+const knownComparisons = new Set([
+    "equal",
+    "greaterThan",
+    "lessThan",
+    "greaterOrEqual",
+    "lessOrEqual",
+]);
+const knownFeatures = new Set(["either", "nested", "order", "mask", "limit"]);
+const knownPlanProperties = new Set(["predicate", "order", "mask", "limit", "candidateLimit"]);
+/**
+ * Shared fail-fast validation for normalized plans before provider execution.
+ */
+export const StorageQueryPolicy = Object.freeze({
+    validate(plan, capabilities) {
+        const normalizedPlan = QueryPlanValidator.requireRecord(plan, "query plan must be an object.");
+        const normalizedCapabilities = QueryPlanValidator.requireRecord(capabilities, "query capabilities must be an object.");
+        QueryPlanValidator.validatePlanProperties(normalizedPlan);
+        const comparisons = QueryCapabilities.validateComparisons(normalizedCapabilities.comparisons);
+        const features = QueryCapabilities.validateFeatures(normalizedCapabilities.features);
+        const requirements = {
+            comparisons: new Set(),
+            features: new Set(),
+        };
+        if (normalizedPlan.predicate !== undefined) {
+            QueryPlanValidator.validatePredicate(normalizedPlan.predicate, requirements);
+        }
+        QueryPlanValidator.validateOrder(normalizedPlan.order, requirements);
+        QueryPlanValidator.validateMask(normalizedPlan.mask, requirements);
+        QueryPlanValidator.validateLimit(normalizedPlan.limit, normalizedPlan.order, requirements);
+        QueryPlanValidator.validateCandidateLimit(normalizedPlan.candidateLimit);
+        QueryCapabilities.admit(requirements, comparisons, features);
+    },
+});
+/**
+ * Validates normalized plan values and accumulates their required capabilities.
+ */
+const QueryPlanValidator = {
+    // prettier-ignore
+    /**
+     * Rejects unsupported or misspelled normalized-plan properties.
+     */
+    validatePlanProperties(plan) {
+        if (Object.hasOwn(plan, "offset")) {
+            throw new TypeError("normalized query plans do not support offset.");
+        }
+        for (const property of Object.keys(plan)) {
+            if (!knownPlanProperties.has(property)) {
+                throw new TypeError("query plan property must be recognized.");
+            }
+        }
+    },
+    /**
+     * Validates the maximum materialized candidate count.
+     */
+    validateCandidateLimit(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+            throw new TypeError("query candidate limit must be a positive safe integer.");
+        }
+        if (value > 10_000)
+            throw new TypeError("query candidate limit must not exceed 10,000.");
+    },
+    /**
+     * Validates a normalized predicate tree and records its required capabilities.
+     */
+    validatePredicate(root, requirements) {
+        const pending = [
+            { predicate: root, depth: 0 },
+        ];
+        const seen = new WeakSet();
+        let visited = 0;
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined)
+                break;
+            visited += 1;
+            if (visited > maximumPredicateNodes) {
+                throw new TypeError(`query predicate exceeds maximum node count ${String(maximumPredicateNodes)}.`);
+            }
+            if (current.depth > maximumPredicateDepth) {
+                throw new TypeError(`query predicate exceeds maximum depth ${String(maximumPredicateDepth)}.`);
+            }
+            const predicate = QueryPlanValidator.requireRecord(current.predicate, "query predicate must be an object.");
+            if (seen.has(predicate))
+                throw new TypeError("query predicate must not contain cycles.");
+            seen.add(predicate);
+            if (predicate.kind === "ids") {
+                if (!Array.isArray(predicate.ids))
+                    throw new TypeError("ID predicate IDs must be an array.");
+                if (predicate.ids.length === 0)
+                    throw new TypeError("ID predicate must not be empty.");
+                for (let index = 0; index < predicate.ids.length; index += 1) {
+                    if (!Object.hasOwn(predicate.ids, index) || predicate.ids[index] === undefined) {
+                        throw new TypeError("ID predicate entries must be defined.");
+                    }
+                }
+                continue;
+            }
+            if (predicate.kind === "comparison") {
+                if (typeof predicate.column !== "string") {
+                    throw new TypeError("comparison column must be a string.");
+                }
+                if (predicate.column.trim().length === 0) {
+                    throw new TypeError("comparison column must not be blank.");
+                }
+                if (typeof predicate.operator !== "string" ||
+                    !knownComparisons.has(predicate.operator)) {
+                    throw new TypeError("comparison operator must be recognized.");
+                }
+                if (predicate.value === undefined)
+                    throw new TypeError("comparison value must be defined.");
+                requirements.comparisons.add(predicate.operator);
+                continue;
+            }
+            if (predicate.kind !== "all" && predicate.kind !== "either") {
+                throw new TypeError("query predicate kind must be recognized.");
+            }
+            if (!Array.isArray(predicate.predicates)) {
+                throw new TypeError(`${predicate.kind.toUpperCase()} predicate predicates must be an array.`);
+            }
+            if (predicate.predicates.length === 0) {
+                throw new TypeError(`${predicate.kind.toUpperCase()} predicate must not be empty.`);
+            }
+            if (predicate.kind === "either")
+                requirements.features.add("either");
+            if (current.depth > 0)
+                requirements.features.add("nested");
+            if (visited + pending.length + predicate.predicates.length > maximumPredicateNodes) {
+                throw new TypeError(`query predicate exceeds maximum node count ${String(maximumPredicateNodes)}.`);
+            }
+            for (let index = predicate.predicates.length - 1; index >= 0; index -= 1) {
+                if (!Object.hasOwn(predicate.predicates, index)) {
+                    throw new TypeError("query predicate entries must be defined.");
+                }
+                pending.push({ predicate: predicate.predicates[index], depth: current.depth + 1 });
+            }
+        }
+    },
+    /**
+     * Validates normalized ordering and records the ordering capability.
+     */
+    validateOrder(value, requirements) {
+        if (value === undefined)
+            return;
+        if (!Array.isArray(value))
+            throw new TypeError("query order must be an array.");
+        if (value.length === 0)
+            throw new TypeError("query order must not be empty.");
+        for (const candidate of value) {
+            const order = QueryPlanValidator.requireRecord(candidate, "query order entry must be an object.");
+            if (typeof order.column !== "string")
+                throw new TypeError("query order column must be a string.");
+            if (order.column.trim().length === 0)
+                throw new TypeError("query order column must not be blank.");
+            if (order.direction !== "asc" && order.direction !== "desc") {
+                throw new TypeError("query order direction must be asc or desc.");
+            }
+        }
+        requirements.features.add("order");
+    },
+    /**
+     * Validates a normalized field mask and records the mask capability.
+     */
+    validateMask(value, requirements) {
+        if (value === undefined)
+            return;
+        const mask = QueryPlanValidator.requireRecord(value, "field mask must be an object.");
+        if (!Array.isArray(mask.paths))
+            throw new TypeError("field-mask paths must be an array.");
+        if (mask.paths.length === 0)
+            throw new TypeError("field mask must not be empty.");
+        const paths = mask.paths;
+        for (let index = 0; index < paths.length; index += 1) {
+            const path = paths[index];
+            if (!Object.hasOwn(paths, index) || typeof path !== "string") {
+                throw new TypeError("field-mask paths must be strings.");
+            }
+            if (path.trim().length === 0)
+                throw new TypeError("field-mask paths must not be blank.");
+        }
+        requirements.features.add("mask");
+    },
+    /**
+     * Validates a result limit and records the limit capability.
+     */
+    validateLimit(value, order, requirements) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+            throw new TypeError("query limit must be a positive integer.");
+        }
+        if (!Array.isArray(order) || order.length === 0) {
+            throw new TypeError("query limit requires ordering.");
+        }
+        requirements.features.add("limit");
+    },
+    /**
+     * Requires a non-array object value and returns its properties.
+     */
+    requireRecord(value, message) {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            throw new TypeError(message);
+        }
+        return value;
+    },
+};
+/**
+ * Validates advertised capabilities and admits normalized query requirements.
+ */
+const QueryCapabilities = {
+    // prettier-ignore
+    /**
+     * Validates advertised comparison operators.
+     */
+    validateComparisons(value) {
+        if (!Array.isArray(value))
+            throw new TypeError("comparison capabilities must be an array.");
+        const validated = [];
+        for (const comparison of value) {
+            if (typeof comparison !== "string" || !knownComparisons.has(comparison)) {
+                throw new TypeError("comparison capability must be recognized.");
+            }
+            validated.push(comparison);
+        }
+        return new Set(validated);
+    },
+    /**
+     * Validates advertised normalized query features.
+     */
+    validateFeatures(value) {
+        if (!Array.isArray(value))
+            throw new TypeError("query features must be an array.");
+        const validated = [];
+        for (const feature of value) {
+            if (typeof feature !== "string" || !knownFeatures.has(feature)) {
+                throw new TypeError("query feature must be recognized.");
+            }
+            validated.push(feature);
+        }
+        return new Set(validated);
+    },
+    /**
+     * Rejects requirements that an advertised provider capability set does not satisfy.
+     */
+    admit(requirements, comparisons, features) {
+        for (const feature of requirements.features) {
+            QueryCapabilities.requireFeature(features, feature, QueryCapabilities.featureDescription(feature));
+        }
+        for (const comparison of requirements.comparisons) {
+            if (!comparisons.has(comparison)) {
+                throw new TypeError(`Storage provider does not support comparison operator "${comparison}".`);
+            }
+        }
+    },
+    /**
+     * Describes a capability in a provider-rejection message.
+     */
+    featureDescription(feature) {
+        if (feature === "either")
+            return "EITHER predicates";
+        if (feature === "nested")
+            return "nested predicates";
+        if (feature === "order")
+            return "ordering";
+        if (feature === "mask")
+            return "field masks";
+        return "limits";
+    },
+    /**
+     * Rejects a missing required feature with its provider-facing description.
+     */
+    requireFeature(features, feature, description) {
+        if (!features.has(feature)) {
+            throw new TypeError(`Storage provider does not support ${description}.`);
+        }
+    },
+};
+//# sourceMappingURL=query-policy.js.map

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

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

package/dist/record/column-mapping.d.ts

@@ -0,0 +1,41 @@
+import type { RecordColumnType } from "./column-type.js";
+/**
+ * Converts one typed record-column value to its provider representation.
+ *
+ * @param value The typed Protobuf value.
+ * @returns The provider representation.
+ */
+export type ColumnTypeMapping<V, R> = (value: V) => R;
+/**
+ * Supplies provider conversion rules for generated Protobuf column types.
+ */
+export interface ColumnMapping<R> {
+    /**
+     * Returns the conversion rule for a declared column type.
+     * @param type The generated Protobuf column type.
+     * @returns The provider conversion rule.
+     */
+    of<V>(type: RecordColumnType<V>): ColumnTypeMapping<V, R>;
+    /**
+     * Returns the provider conversion rule for an absent column value.
+     * @returns The provider null conversion rule.
+     */
+    ofNull(): ColumnTypeMapping<null, R>;
+}
+/**
+ * Applies one provider mapping to stored and queried column values.
+ */
+export declare const ColumnMappings: {
+    /**
+     * Converts a value through its declared provider rule.
+     *
+     * Both record materialization and query planning must call this operation.
+     *
+     * @param mapping The provider mapping.
+     * @param type The declared column type.
+     * @param value The stored or queried value.
+     * @returns The provider value.
+     */
+    readonly value: <V, R>(mapping: ColumnMapping<R>, type: RecordColumnType<V>, value: V | null | undefined) => R;
+};
+//# sourceMappingURL=column-mapping.d.ts.map

package/dist/record/column-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.d.ts","sourceRoot":"","sources":["../../src/record/column-mapping.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAG9B;;;;OAIG;IACH,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE1D;;;OAGG;IACH,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;IAGzB;;;;;;;;;OASG;qBACG,CAAC,EAAE,CAAC,WACC,aAAa,CAAC,CAAC,CAAC,QACnB,gBAAgB,CAAC,CAAC,CAAC,SAClB,CAAC,GAAG,IAAI,GAAG,SAAS,KAC1B,CAAC;CAKI,CAAC"}

package/dist/record/column-mapping.js

@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+/**
+ * Applies one provider mapping to stored and queried column values.
+ */
+export const ColumnMappings = {
+    // prettier-ignore
+    /**
+     * Converts a value through its declared provider rule.
+     *
+     * Both record materialization and query planning must call this operation.
+     *
+     * @param mapping The provider mapping.
+     * @param type The declared column type.
+     * @param value The stored or queried value.
+     * @returns The provider value.
+     */
+    value(mapping, type, value) {
+        return value === null || value === undefined
+            ? mapping.ofNull()(null)
+            : mapping.of(type)(value);
+    },
+};
+Object.freeze(ColumnMappings);
+//# sourceMappingURL=column-mapping.js.map

package/dist/record/column-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.js","sourceRoot":"","sources":["../../src/record/column-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgCH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,kBAAkB;IAElB;;;;;;;;;OASG;IACH,KAAK,CACH,OAAyB,EACzB,IAAyB,EACzB,KAA2B;QAE3B,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAC1C,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;YACxB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;CACO,CAAC;AACX,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC"}

package/dist/record/column-type.d.ts

@@ -0,0 +1,75 @@
+import type { DescEnum, DescField, DescMessage, ScalarType } from "@bufbuild/protobuf";
+declare const columnValueType: unique symbol;
+/**
+ * Generated Protobuf type retained for one materialized record column.
+ */
+export type RecordColumnType<V = unknown> = ({
+    /**
+     * Identifies a Protobuf scalar column.
+     */
+    readonly kind: "scalar";
+    /**
+     * Protobuf scalar kind retained by the column.
+     */
+    readonly scalar: ScalarType;
+    /**
+     * Whether generated code represents a 64-bit value as a string.
+     */
+    readonly longAsString: boolean;
+} | {
+    /**
+     * Identifies a Protobuf enum column.
+     */
+    readonly kind: "enum";
+    /**
+     * Generated enum descriptor retained by the column.
+     */
+    readonly enum: DescEnum;
+} | {
+    /**
+     * Identifies a Protobuf message column.
+     */
+    readonly kind: "message";
+    /**
+     * Generated message descriptor retained by the column.
+     */
+    readonly message: DescMessage;
+}) & {
+    /**
+     * Compile-time value type carried by the column declaration.
+     */
+    readonly [columnValueType]?: V;
+};
+/**
+ * Creates record-column types from generated Protobuf descriptors.
+ */
+export declare const ColumnTypes: {
+    /**
+     * Declares a scalar type for a derived column value.
+     * @param scalar The Protobuf scalar type.
+     * @param longAsString Whether a 64-bit value uses its generated string form.
+     * @returns The scalar column type.
+     */
+    readonly scalar: <V = unknown>(scalar: ScalarType, longAsString?: boolean) => RecordColumnType<V>;
+    /**
+     * Declares an enum type for a derived column value.
+     * @param schema The generated enum descriptor.
+     * @returns The enum column type.
+     */
+    readonly enum: <V = unknown>(schema: DescEnum) => RecordColumnType<V>;
+    /**
+     * Declares a message type for a derived column value.
+     * @param schema The generated message descriptor.
+     * @returns The message column type.
+     */
+    readonly message: <V = unknown>(schema: DescMessage) => RecordColumnType<V>;
+    /**
+     * Retains the singular value type declared by a generated Protobuf field.
+     * @param field The generated field descriptor.
+     * @returns The corresponding column type.
+     * @throws Error when the field is repeated or a map.
+     */
+    readonly fromField: <V = unknown>(field: DescField) => RecordColumnType<V>;
+};
+export {};
+//# sourceMappingURL=column-type.d.ts.map

package/dist/record/column-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-type.d.ts","sourceRoot":"","sources":["../../src/record/column-type.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEvF,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CACxC;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B,CACJ,GAAG;IAGF;;OAEG;IACH,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;CAChC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;IAGtB;;;;;OAKG;sBACI,CAAC,oBACE,UAAU,iBACH,OAAO,KACrB,gBAAgB,CAAC,CAAC,CAAC;IAItB;;;;OAIG;oBACE,CAAC,oBAAoB,QAAQ,KAAG,gBAAgB,CAAC,CAAC,CAAC;IAIxD;;;;OAIG;uBACK,CAAC,oBAAoB,WAAW,KAAG,gBAAgB,CAAC,CAAC,CAAC;IAI9D;;;;;OAKG;yBACO,CAAC,mBAAmB,SAAS,KAAG,gBAAgB,CAAC,CAAC,CAAC;CAiBrD,CAAC"}

package/dist/record/column-type.js

@@ -0,0 +1,69 @@
+/*
+ * 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.
+ */
+/**
+ * Creates record-column types from generated Protobuf descriptors.
+ */
+export const ColumnTypes = {
+    // prettier-ignore
+    /**
+     * Declares a scalar type for a derived column value.
+     * @param scalar The Protobuf scalar type.
+     * @param longAsString Whether a 64-bit value uses its generated string form.
+     * @returns The scalar column type.
+     */
+    scalar(scalar, longAsString) {
+        return Object.freeze({ kind: "scalar", scalar, longAsString: longAsString ?? false });
+    },
+    /**
+     * Declares an enum type for a derived column value.
+     * @param schema The generated enum descriptor.
+     * @returns The enum column type.
+     */
+    enum(schema) {
+        return Object.freeze({ kind: "enum", enum: schema });
+    },
+    /**
+     * Declares a message type for a derived column value.
+     * @param schema The generated message descriptor.
+     * @returns The message column type.
+     */
+    message(schema) {
+        return Object.freeze({ kind: "message", message: schema });
+    },
+    /**
+     * Retains the singular value type declared by a generated Protobuf field.
+     * @param field The generated field descriptor.
+     * @returns The corresponding column type.
+     * @throws Error when the field is repeated or a map.
+     */
+    fromField(field) {
+        switch (field.fieldKind) {
+            case "scalar":
+                return Object.freeze({
+                    kind: "scalar",
+                    scalar: field.scalar,
+                    longAsString: field.longAsString,
+                });
+            case "enum":
+                return Object.freeze({ kind: "enum", enum: field.enum });
+            case "message":
+                return Object.freeze({ kind: "message", message: field.message });
+            case "list":
+            case "map":
+                throw new Error(`Record column "${field.name}" must have one singular value.`);
+        }
+    },
+};
+Object.freeze(ColumnTypes);
+//# sourceMappingURL=column-type.js.map

package/dist/record/column-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-type.js","sourceRoot":"","sources":["../../src/record/column-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+DH;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,kBAAkB;IAElB;;;;;OAKG;IACH,MAAM,CACJ,MAAkB,EAClB,YAAsB;QAEtB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,IAAI,KAAK,EAAE,CAAC,CAAC;IACxF,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAc,MAAgB;QAChC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAc,MAAmB;QACtC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAc,KAAgB;QACrC,QAAQ,KAAK,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,QAAQ;gBACX,OAAO,MAAM,CAAC,MAAM,CAAC;oBACnB,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,YAAY,EAAE,KAAK,CAAC,YAAY;iBACjC,CAAC,CAAC;YACL,KAAK,MAAM;gBACT,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3D,KAAK,SAAS;gBACZ,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACpE,KAAK,MAAM,CAAC;YACZ,KAAK,KAAK;gBACR,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,CAAC,IAAI,iCAAiC,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;CACO,CAAC;AACX,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC"}

package/dist/record/record-column.d.ts

@@ -0,0 +1,23 @@
+import type { RecordColumnType } from "./column-type.js";
+/**
+ * Queryable column calculated from a stored record.
+ */
+export declare class RecordColumn<R extends object, V = unknown> {
+    #private;
+    readonly name: string;
+    readonly type: RecordColumnType<V>;
+    /**
+     * Creates a named column reader.
+     * @param name The stable column name.
+     * @param type The generated Protobuf value type.
+     * @param read The record value reader.
+     */
+    constructor(name: string, type: RecordColumnType<V>, read: (record: R) => V);
+    /**
+     * Reads the stored column value from a record snapshot.
+     * @param record The record snapshot.
+     * @returns The column value.
+     */
+    valueIn(record: R): V;
+}
+//# sourceMappingURL=record-column.d.ts.map

package/dist/record/record-column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-column.d.ts","sourceRoot":"","sources":["../../src/record/record-column.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;GAEG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO;;IAUnD,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;IARpC;;;;;OAKG;gBAEQ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAClC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC;IAKxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;CAGtB"}

package/dist/record/record-column.js

@@ -0,0 +1,41 @@
+/*
+ * 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.
+ */
+/**
+ * Queryable column calculated from a stored record.
+ */
+export class RecordColumn {
+    name;
+    type;
+    #read;
+    /**
+     * Creates a named column reader.
+     * @param name The stable column name.
+     * @param type The generated Protobuf value type.
+     * @param read The record value reader.
+     */
+    constructor(name, type, read) {
+        this.name = name;
+        this.type = type;
+        this.#read = read;
+    }
+    /**
+     * Reads the stored column value from a record snapshot.
+     * @param record The record snapshot.
+     * @returns The column value.
+     */
+    valueIn(record) {
+        return this.#read(record);
+    }
+}
+//# sourceMappingURL=record-column.js.map

package/dist/record/record-column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-column.js","sourceRoot":"","sources":["../../src/record/record-column.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;GAEG;AACH,MAAM,OAAO,YAAY;IAUZ;IACA;IAVF,KAAK,CAAmB;IAEjC;;;;;OAKG;IACH,YACW,IAAY,EACZ,IAAyB,EAClC,IAAsB;QAFb,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAqB;QAGlC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAS;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/record/record-mask.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents dotted record paths retained by a masked read.
+ */
+export type RecordMask = readonly string[];
+/**
+ * Provides record-mask operations.
+ */
+export declare const RecordMask: Readonly<{
+    apply<R>(record: R, mask: RecordMask | undefined): R;
+}>;
+//# sourceMappingURL=record-mask.d.ts.map

package/dist/record/record-mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-mask.d.ts","sourceRoot":"","sources":["../../src/record/record-mask.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,MAAM,EAAE,CAAC;AAM3C;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC;IAChC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,CAAC,CAAC;CACtD,CAkBC,CAAC"}