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

package/dist/datastore/id-column.js

@@ -0,0 +1,103 @@
+/*
+ * 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.
+ */
+import { StringifierRegistry } from "@spine-event-engine/core";
+/**
+ * Converts a declared record ID to and from a Spine JVM Datastore key name.
+ */
+export class DatastoreIdColumn {
+    type;
+    #stringifiers;
+    /**
+     * Creates the ID conversion.
+     *
+     * @param type The generated message schema or supported primitive ID kind.
+     * @param stringifiers The schema-bound message stringifiers.
+     */
+    constructor(type, stringifiers = new StringifierRegistry()) {
+        this.type = type;
+        this.#stringifiers = new StringifierRegistry(stringifiers);
+        DatastoreIds.validateType(type);
+    }
+    /**
+     * Converts a logical ID to a Datastore key name.
+     *
+     * @param id The logical record identifier.
+     * @returns The JVM-compatible key name.
+     */
+    value(id) {
+        const value = typeof this.type === "string"
+            ? DatastoreIds.primitive(this.type, id)
+            : this.#stringifiers.forMessage(this.type).toString(id);
+        return DatastoreIds.keyName(value);
+    }
+    /**
+     * Restores a logical ID from a Datastore key name.
+     *
+     * @param value The Datastore key name.
+     * @returns The restored record identifier.
+     */
+    read(value) {
+        DatastoreIds.keyName(value);
+        if (typeof this.type !== "string")
+            return this.#stringifiers.forMessage(this.type).fromString(value);
+        switch (this.type) {
+            case "string":
+                return value;
+            case "int32": {
+                const number = Number(value);
+                DatastoreIds.primitive("int32", number);
+                return number;
+            }
+            case "int64": {
+                const integer = BigInt(value);
+                DatastoreIds.primitive("int64", integer);
+                return integer;
+            }
+            default:
+                throw new Error(`Datastore storage does not support primitive ID kind "${this.type}".`);
+        }
+    }
+}
+const DatastoreIds = Object.freeze({
+    validateType(type) {
+        if (typeof type !== "string")
+            return;
+        if (!["string", "int32", "int64"].includes(type))
+            throw new Error(`Datastore storage does not support primitive ID kind "${type}".`);
+    },
+    primitive(type, value) {
+        if (type === "string" && typeof value === "string")
+            return value;
+        if (type === "int32" &&
+            typeof value === "number" &&
+            Number.isInteger(value) &&
+            value >= -2_147_483_648 &&
+            value <= 2_147_483_647)
+            return String(value);
+        if (type === "int64" &&
+            typeof value === "bigint" &&
+            value >= -(1n << 63n) &&
+            value <= (1n << 63n) - 1n)
+            return value.toString();
+        throw new Error(`Datastore ${type} identifier is invalid.`);
+    },
+    keyName(value) {
+        if (value.length === 0)
+            throw new Error("Datastore storage identifier must be non-empty.");
+        if (Buffer.byteLength(value, "utf8") > 1_500)
+            throw new Error("Datastore record key exceeds the 1,500-byte provider limit.");
+        return value;
+    },
+});
+//# sourceMappingURL=id-column.js.map

package/dist/datastore/id-column.js.map

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

package/dist/datastore/namespace.d.ts

@@ -0,0 +1,81 @@
+import { type TenantId } from "@spine-event-engine/proto";
+/**
+ * Converts complete tenant identifiers to and from Datastore namespaces.
+ *
+ * A converter must return a non-empty namespace and be injective over every
+ * admitted tenant. Converting in either direction and back must restore the
+ * exact complete tenant or namespace. Return `undefined` only for native
+ * namespaces that the converter does not own.
+ */
+export interface NamespaceConverter {
+    /**
+     * Converts an owned namespace to a complete tenant identifier.
+     *
+     * @param namespace The native Datastore namespace.
+     * @returns The tenant, or `undefined` when this converter does not own the namespace.
+     */
+    fromNamespace(namespace: string): TenantId | undefined;
+    /**
+     * Converts a complete tenant identifier to its native namespace.
+     *
+     * @param tenantId The complete tenant identifier.
+     * @returns The native Datastore namespace.
+     */
+    toNamespace(tenantId: TenantId): string;
+}
+/**
+ * Safe Spine JVM-compatible `D` and `V` Datastore namespace conversion.
+ */
+export declare class DefaultNamespaceConverter implements NamespaceConverter {
+    /**
+     * Restores a tenant from an owned prefixed namespace.
+     *
+     * @param namespace The native Datastore namespace.
+     * @returns The restored tenant, or `undefined` for another namespace.
+     */
+    fromNamespace(namespace: string): TenantId | undefined;
+    /**
+     * Converts a complete tenant to the Spine JVM-prefixed namespace.
+     *
+     * The Spine JVM email conversion replaces `@` with `-at-`. That mapping is
+     * not reversible and can assign distinct tenants to the same namespace, so
+     * this safe default rejects email tenants. Applications that use email
+     * tenant IDs must install the same injective custom converter in both
+     * runtimes.
+     *
+     * @param tenantId The complete tenant identifier.
+     * @returns The native Datastore namespace.
+     */
+    toNamespace(tenantId: TenantId): string;
+}
+/**
+ * Validates reversible tenant-to-namespace assignments.
+ *
+ * The same instance serves catalog admission and storage creation. A mapping
+ * is accepted only when applying the converter in the opposite direction
+ * restores the exact complete tenant or namespace.
+ */
+export declare class NamespaceAssignments implements NamespaceConverter {
+    private readonly converter;
+    /**
+     * Creates an assignment validator around an application converter.
+     *
+     * @param converter The converter whose mappings are validated.
+     */
+    constructor(converter: NamespaceConverter);
+    /**
+     * Restores and validates an owned namespace.
+     *
+     * @param namespace The native namespace.
+     * @returns The restored tenant, or `undefined` when not owned.
+     */
+    fromNamespace(namespace: string): TenantId | undefined;
+    /**
+     * Converts and validates a complete tenant.
+     *
+     * @param tenantId The complete tenant identifier.
+     * @returns Its unique, reversible native namespace.
+     */
+    toNamespace(tenantId: TenantId): string;
+}
+//# sourceMappingURL=namespace.d.ts.map

package/dist/datastore/namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/datastore/namespace.ts"],"names":[],"mappings":"AAeA,OAAO,EAAwC,KAAK,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGhG;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAGjC;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEvD;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;CACzC;AAED;;GAEG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IAGlE;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAiBtD;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM;CAexC;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,kBAAkB;IAQjD,OAAO,CAAC,QAAQ,CAAC,SAAS;IALtC;;;;OAIG;gBAC0B,SAAS,EAAE,kBAAkB;IAE1D;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAWtD;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM;CAUxC"}

package/dist/datastore/namespace.js

@@ -0,0 +1,123 @@
+/*
+ * 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.
+ */
+import { create } from "@bufbuild/protobuf";
+import { InternetDomainSchema, TenantIdSchema } from "@spine-event-engine/proto";
+import { TenantBoundary } from "@spine-event-engine/storage/provider";
+/**
+ * Safe Spine JVM-compatible `D` and `V` Datastore namespace conversion.
+ */
+export class DefaultNamespaceConverter {
+    // prettier-ignore
+    /**
+     * Restores a tenant from an owned prefixed namespace.
+     *
+     * @param namespace The native Datastore namespace.
+     * @returns The restored tenant, or `undefined` for another namespace.
+     */
+    fromNamespace(namespace) {
+        if (namespace.length < 2)
+            return undefined;
+        const value = namespace.slice(1);
+        switch (namespace[0]) {
+            case "D":
+                return create(TenantIdSchema, {
+                    kind: { case: "domain", value: create(InternetDomainSchema, { value }) },
+                });
+            case "E":
+                return undefined;
+            case "V":
+                return create(TenantIdSchema, { kind: { case: "value", value } });
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Converts a complete tenant to the Spine JVM-prefixed namespace.
+     *
+     * The Spine JVM email conversion replaces `@` with `-at-`. That mapping is
+     * not reversible and can assign distinct tenants to the same namespace, so
+     * this safe default rejects email tenants. Applications that use email
+     * tenant IDs must install the same injective custom converter in both
+     * runtimes.
+     *
+     * @param tenantId The complete tenant identifier.
+     * @returns The native Datastore namespace.
+     */
+    toNamespace(tenantId) {
+        TenantBoundary.from(tenantId);
+        const kind = tenantId.kind;
+        if (kind.case === "email")
+            throw new Error("The default email namespace mapping is unsafe; install a reversible custom namespace converter.");
+        const namespace = kind.case === "domain"
+            ? `D${kind.value.value}`
+            : kind.case === "value"
+                ? `V${kind.value}`
+                : "";
+        return namespace;
+    }
+}
+/**
+ * Validates reversible tenant-to-namespace assignments.
+ *
+ * The same instance serves catalog admission and storage creation. A mapping
+ * is accepted only when applying the converter in the opposite direction
+ * restores the exact complete tenant or namespace.
+ */
+export class NamespaceAssignments {
+    converter;
+    // prettier-ignore
+    /**
+     * Creates an assignment validator around an application converter.
+     *
+     * @param converter The converter whose mappings are validated.
+     */
+    constructor(converter) {
+        this.converter = converter;
+    }
+    /**
+     * Restores and validates an owned namespace.
+     *
+     * @param namespace The native namespace.
+     * @returns The restored tenant, or `undefined` when not owned.
+     */
+    fromNamespace(namespace) {
+        if (namespace.length === 0)
+            return undefined;
+        const tenantId = this.converter.fromNamespace(namespace);
+        if (tenantId === undefined)
+            return undefined;
+        TenantBoundary.from(tenantId);
+        const roundTrip = this.converter.toNamespace(tenantId);
+        if (roundTrip !== namespace)
+            throw new Error("Datastore namespace conversion must round trip exactly.");
+        return tenantId;
+    }
+    /**
+     * Converts and validates a complete tenant.
+     *
+     * @param tenantId The complete tenant identifier.
+     * @returns Its unique, reversible native namespace.
+     */
+    toNamespace(tenantId) {
+        const boundary = TenantBoundary.from(tenantId);
+        const namespace = this.converter.toNamespace(tenantId);
+        if (namespace.trim().length === 0)
+            throw new Error("Datastore multitenancy requires a non-empty native namespace.");
+        const restored = this.converter.fromNamespace(namespace);
+        if (restored === undefined || TenantBoundary.from(restored).key !== boundary.key)
+            throw new Error("Datastore namespace conversion must round trip exactly.");
+        return namespace;
+    }
+}
+//# sourceMappingURL=namespace.js.map

package/dist/datastore/namespace.js.map

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

package/dist/datastore/record-storage.d.ts

@@ -0,0 +1,223 @@
+import { type Message } from "@bufbuild/protobuf";
+import { Datastore } from "@google-cloud/datastore";
+import { StringifierRegistry } from "@spine-event-engine/core";
+import { RecordStorage, type NormalizedQueryPlan, type RecordEntry, type RecordQuery, type RecordSpec, type StorageContext, type StorageGroup, type StorageQueryCapabilities } from "@spine-event-engine/storage";
+import { type NamespaceConverter } from "./namespace.js";
+/**
+ * Describes one provider-side Datastore range filter.
+ *
+ * This is deliberately package-private adapter machinery. It is used by the
+ * generated Entity-history implementation to keep large histories on the
+ * provider rather than materializing them in Node.js.
+ */
+export interface DatastoreRangeFilter {
+    /**
+     * Names the Datastore property compared by this filter.
+     */
+    readonly property: string;
+    /**
+     * Selects the comparison applied by Datastore.
+     */
+    readonly operator: "=" | "<" | "<=" | ">" | ">=";
+    /**
+     * Provides the value on the right side of the comparison.
+     */
+    readonly value: unknown;
+}
+/**
+ * Describes a bounded provider-side page over one Datastore record kind.
+ */
+export interface DatastorePageQuery {
+    /**
+     * Narrows the page with provider-side comparisons.
+     */
+    readonly filters?: readonly DatastoreRangeFilter[];
+    /**
+     * Defines the stable provider-side ordering of the page.
+     */
+    readonly order?: readonly {
+        readonly property: string;
+        readonly direction: "asc" | "desc";
+    }[];
+    /**
+     * Continues after the last row returned by the preceding provider page.
+     */
+    readonly cursor?: DatastorePageCursor;
+    /**
+     * Limits the number of rows decoded for this page.
+     */
+    readonly limit: number;
+}
+/**
+ * Returns one bounded Datastore page and its explicit keyset continuation.
+ */
+export interface DatastorePage<I, R extends Message> {
+    /**
+     * Contains the decoded records in provider order.
+     */
+    readonly entries: readonly RecordEntry<I, R>[];
+    /**
+     * Continues the next request after this page.
+     */
+    readonly cursor: DatastorePageCursor | undefined;
+    /**
+     * Tells whether Datastore reported another page.
+     */
+    readonly hasMore: boolean;
+}
+/**
+ * Identifies the last provider row in a stable ordered page.
+ */
+export interface DatastorePageCursor {
+    /**
+     * Values for the requested provider ordering.
+     */
+    readonly values: readonly unknown[];
+    /**
+     * Physical key used as the deterministic final tie-breaker.
+     */
+    readonly key: unknown;
+}
+/**
+ * Provides one Datastore-backed storage handle for a record family.
+ */
+export declare class DatastoreRecordStorage<I, R extends Message> extends RecordStorage<I, R> {
+    #private;
+    readonly client: Datastore;
+    /**
+     * Declares atomic conditional mutations for compatible Datastore handles.
+     */
+    readonly atomicCompareAndSet = true;
+    /**
+     * Creates a Datastore-backed record storage handle.
+     *
+     * @param context Storage tenancy and naming context.
+     * @param recordSpec Schema, identifier, and column materialization contract.
+     * @param client Injected Datastore client owned by the factory.
+     * @param maxClientSideScan Maximum candidate records to materialize locally.
+     * @param group The optional generated storage group.
+     * @param kind The optional physical Datastore kind override.
+     * @param namespaceConverter Converts complete tenants to native namespaces.
+     * @param stringifiers Converts message-valued IDs and declared columns.
+     */
+    constructor(context: StorageContext, recordSpec: RecordSpec<I, R>, client: Datastore, maxClientSideScan: number, group?: StorageGroup, kind?: string, namespaceConverter?: NamespaceConverter, stringifiers?: StringifierRegistry);
+    /**
+     * Prepares one resolved physical row for an enclosing transaction.
+     *
+     * @param record The record to materialize.
+     * @returns The Datastore key and property map.
+     * @internal
+     */
+    transactionEntity(record: R): {
+        readonly key: ReturnType<Datastore["key"]>;
+        readonly data: Record<string, unknown>;
+        readonly excludeFromIndexes: readonly string[];
+    };
+    /**
+     * Decodes one entity read by a provider-owned multi-record transaction.
+     *
+     * @param entity The raw Datastore entity returned inside that transaction.
+     * @returns The decoded record.
+     * @internal
+     */
+    decodeTransactionEntity(entity: Record<string | symbol, unknown>): R;
+    /**
+     * Checks whether one transaction-read entity is the exact expected record.
+     *
+     * @param entity The raw Datastore entity returned inside that transaction.
+     * @param expected The expected record snapshot.
+     * @returns Whether the persisted payload exactly matches the snapshot.
+     * @internal
+     */
+    matchesTransactionEntity(entity: Record<string | symbol, unknown>, expected: R): boolean;
+    /**
+     * Reads one bounded, fully provider-executed page.
+     *
+     * Entity history uses this internal seam for records that would otherwise
+     * exceed the public query materialization budget.
+     *
+     * @param request The provider filters, ordering, continuation, and row limit.
+     * @returns The decoded page and an explicit continuation when more rows remain.
+     * @internal
+     */
+    queryProviderPage(request: DatastorePageQuery): Promise<DatastorePage<I, R>>;
+    /**
+     * Deletes a bounded group of provider entries.
+     *
+     * @param entries The entries selected by a preceding provider page.
+     * @returns Completes after the provider deletes the group.
+     * @internal
+     */
+    deleteProviderEntries(entries: readonly RecordEntry<I, R>[]): Promise<void>;
+    /**
+     * Deletes the record at one storage slot.
+     * @param id The storage slot identifier.
+     * @returns Whether a record was deleted.
+     */
+    protected deleteRecord(id: I): Promise<boolean>;
+    /**
+     * Returns records matching a query.
+     * @param _query The record query.
+     * @returns The matching storage entries.
+     */
+    protected queryRecordEntries(_query: RecordQuery<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Returns the supported Datastore query capabilities.
+     * @returns The supported query capabilities.
+     */
+    protected queryCapabilities(): StorageQueryCapabilities;
+    /**
+     * Returns candidate records for a normalized query plan.
+     * @param plan The normalized query plan.
+     * @returns The candidate storage entries.
+     */
+    protected queryPlanRecordEntries(plan: NormalizedQueryPlan<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Reads the record at one storage slot.
+     * @param id The storage slot identifier.
+     * @returns The stored record, if present.
+     */
+    protected readRecord(id: I): Promise<R | undefined>;
+    /**
+     * Compares and conditionally replaces the record at one storage slot.
+     * @param id The storage slot identifier.
+     * @param expected The expected materialized record.
+     * @param next The replacement materialized record, if any.
+     * @returns Whether the conditional mutation was applied.
+     */
+    protected compareAndSetRecord(id: I, expected: ReturnType<RecordSpec<I, R>["materialize"]> | undefined, next: ReturnType<RecordSpec<I, R>["materialize"]> | undefined): Promise<boolean>;
+    private attemptCompareAndSet;
+    /**
+     * Writes materialized records.
+     * @param records The materialized records to write.
+     * @returns Completes when the records are written.
+     */
+    protected writeAllRecords(records: readonly ReturnType<RecordSpec<I, R>["materialize"]>[]): Promise<void>;
+    /**
+     * Writes one materialized record.
+     * @param record The materialized record to write.
+     * @returns Completes when the record is written.
+     */
+    protected writeRecord(record: ReturnType<RecordSpec<I, R>["materialize"]>): Promise<void>;
+    private provider;
+    /**
+     * Creates a transaction scoped to this handle's selected namespace.
+     *
+     * @returns The namespace-scoped Datastore transaction.
+     * @internal
+     */
+    transaction(): ReturnType<Datastore["transaction"]>;
+}
+/**
+ * Raised when a query would exceed the adapter's configured finite client-side scan budget.
+ */
+export declare class DatastoreQueryLimitError extends Error {
+    readonly maxClientSideScan: number;
+    /**
+     * Creates the scan-budget error.
+     *
+     * @param maxClientSideScan Configured maximum number of locally scanned candidates.
+     */
+    constructor(maxClientSideScan: number);
+}
+//# sourceMappingURL=record-storage.d.ts.map

package/dist/datastore/record-storage.d.ts.map

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