@spine-event-engine/storage-mysql 2.0.0-snapshot.13

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

@@ -0,0 +1,379 @@
+import { type Message } from "@bufbuild/protobuf";
+import { StringifierRegistry } from "@spine-event-engine/core";
+import type { NormalizedQueryPlan, RecordEntry, RecordQuery, RecordSpec, StorageQueryCapabilities, StorageContext } from "@spine-event-engine/storage";
+import { RecordStorage } from "@spine-event-engine/storage";
+import type { MysqlResolvedTable, MysqlTableSpec } from "./table-spec.js";
+/**
+ * Describes the private connection lifecycle for a record-family handle.
+ */
+export interface MysqlRecordLifecycle {
+    /**
+     * Names the selected physical MySQL database.
+     */
+    readonly databaseName: string;
+    /**
+     * Acquires one MySQL connection.
+     *
+     * @returns Resolves to an acquired connection.
+     */
+    acquire(): Promise<import("mysql2/promise").PoolConnection>;
+    /**
+     * Returns one MySQL connection to its pool.
+     *
+     * @param connection Provides the connection to release.
+     */
+    release(connection: import("mysql2/promise").PoolConnection): void;
+}
+/**
+ * Stores one record family in one physical MySQL table.
+ *
+ * @typeParam I The record identifier type.
+ * @typeParam R The stored Protobuf record type.
+ */
+export declare class MysqlRecordStorage<I, R extends Message> extends RecordStorage<I, R> {
+    #private;
+    private readonly table;
+    private readonly lifecycle;
+    private readonly onClose;
+    private readonly createOperation?;
+    /**
+     * Declares support for atomic compare-and-set operations.
+     */
+    readonly atomicCompareAndSet = true;
+    /**
+     * Returns the physical table name.
+     *
+     * @returns Returns the physical table name.
+     */
+    get tableName(): string;
+    /**
+     * Prepares the table before a coordinator transaction begins.
+     *
+     * @returns Resolves after table creation and inspection complete.
+     */
+    prepare(): Promise<void>;
+    /**
+     * Creates a MySQL record-family storage handle.
+     *
+     * @param context Provides the storage context.
+     * @param recordSpec Describes stored records.
+     * @param table Describes the resolved physical table.
+     * @param lifecycle Acquires and releases MySQL connections.
+     * @param onClose Removes this handle from its provider.
+     * @param createOperation Creates optional table-creation SQL.
+     * @param tableSpec Supplies the canonical table layout.
+     * @param stringifiers The schema-bound message stringifiers.
+     */
+    constructor(context: StorageContext, recordSpec: RecordSpec<I, R>, table: MysqlResolvedTable, lifecycle: MysqlRecordLifecycle, onClose: () => void, createOperation?: (() => string) | undefined, tableSpec?: MysqlTableSpec<I, R>, stringifiers?: StringifierRegistry);
+    private readonly tableSpec;
+    /**
+     * Closes this record-family storage handle.
+     */
+    close(): void;
+    /**
+     * Deletes the record identified by an ID.
+     *
+     * @param id Identifies the record to delete.
+     * @returns Resolves whether a record was deleted.
+     */
+    delete(id: I): Promise<boolean>;
+    /**
+     * Reads the record identified by an ID.
+     *
+     * @param id Identifies the record to read.
+     * @param options Configures record reading.
+     * @returns Resolves to the stored record when present.
+     */
+    read(id: I, options?: import("@spine-event-engine/storage").RecordReadOptions): Promise<R | undefined>;
+    /**
+     * Writes one record.
+     *
+     * @param record Provides the record to write.
+     * @returns Resolves after the record is written.
+     */
+    write(record: R): Promise<void>;
+    /**
+     * Writes a sequence of records.
+     *
+     * @param records Provides the records to write.
+     * @returns Resolves after the records are written.
+     */
+    writeAll(records: Iterable<R>): Promise<void>;
+    /**
+     * Rejects an oversized storage slot before beginning compare-and-set work.
+     *
+     * @param id Identifies the storage slot.
+     * @param expected Provides the expected stored record.
+     * @param next Provides the replacement record.
+     * @returns Resolves whether the conditional mutation was applied.
+     */
+    compareAndSet(id: I, expected: R | undefined, next: R | undefined): Promise<boolean>;
+    /**
+     * Writes an immutable record when an identical record is absent.
+     *
+     * @param record Provides the immutable record.
+     * @returns Resolves after the record is written or confirmed identical.
+     */
+    writeImmutable(record: R): Promise<void>;
+    /**
+     * Checks an immutable record without creating it.
+     *
+     * @param record Provides the immutable record to check.
+     * @returns Resolves when the record is absent or identical.
+     */
+    assertImmutable(record: R): Promise<void>;
+    /**
+     * Binds nested storage calls to a coordinator-owned connection.
+     *
+     * @param connection Provides the coordinator-owned connection.
+     * @param work Performs the bound storage work.
+     * @typeParam T The bound work's result type.
+     * @returns Returns the work result.
+     */
+    withConnection<T>(connection: import("mysql2/promise").PoolConnection, work: () => Promise<T>): Promise<T>;
+    /**
+     * Reads one record with the coordinator transaction's row/gap lock.
+     *
+     * @param id Identifies the record.
+     * @returns Resolves to the stored record when present.
+     */
+    readLocked(id: I): Promise<R | undefined>;
+    /**
+     * Deletes one stored record.
+     *
+     * @param id Identifies the record to delete.
+     * @returns Resolves whether a record was deleted.
+     */
+    protected deleteRecord(id: I): Promise<boolean>;
+    /**
+     * Reads one stored record.
+     *
+     * @param id Identifies the record to read.
+     * @returns Resolves to the stored record when present.
+     */
+    protected readRecord(id: I): Promise<R | undefined>;
+    /**
+     * Reads stored record entries matching a query.
+     *
+     * @param query Specifies the record query.
+     * @returns Resolves to matching record entries.
+     */
+    protected queryRecordEntries(query: RecordQuery<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Returns the normalized query features genuinely executed by MySQL.
+     * @returns The normalized features executed by this provider.
+     */
+    protected queryCapabilities(): StorageQueryCapabilities;
+    /**
+     * Executes the complete candidate selection in contained, bound MySQL SQL.
+     * @param plan The validated normalized query plan.
+     * @returns The selected record entries.
+     */
+    protected queryPlanRecordEntries(plan: NormalizedQueryPlan<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Compares and conditionally replaces one stored record.
+     *
+     * @param id Identifies the record to replace.
+     * @param expected Provides the expected current record.
+     * @param next Provides the replacement record.
+     * @returns Resolves whether the replacement was applied.
+     */
+    protected compareAndSetRecord(id: I, expected: ReturnType<RecordSpec<I, R>["materialize"]> | undefined, next: ReturnType<RecordSpec<I, R>["materialize"]> | undefined): Promise<boolean>;
+    /**
+     * Performs one compare-and-set attempt on a single connection.
+     *
+     * @param id Identifies the record slot.
+     * @param expected Provides the expected materialized record.
+     * @param next Provides the replacement materialized record.
+     * @returns Resolves whether the replacement was applied.
+     */
+    private compareAndSetOnce;
+    /**
+     * Acquires the advisory lock for a non-transactional record slot.
+     *
+     * @param connection Provides the lock connection.
+     * @param id Identifies the record slot.
+     * @returns Resolves after the lock is acquired.
+     */
+    private acquireCasLock;
+    /**
+     * Applies a compare-and-set while the record slot is protected.
+     *
+     * @param connection Provides the protected connection.
+     * @param transactional Tells whether the connection has an active transaction.
+     * @param id Identifies the record slot.
+     * @param expected Provides the expected materialized record.
+     * @param next Provides the replacement materialized record.
+     * @returns Resolves whether the replacement was applied.
+     */
+    private applyCompareAndSet;
+    /**
+     * Writes materialized records in one transaction.
+     *
+     * @param records Provides the materialized records.
+     * @returns Resolves after the records are written.
+     */
+    protected writeAllRecords(records: readonly ReturnType<RecordSpec<I, R>["materialize"]>[]): Promise<void>;
+    /**
+     * Writes one materialized record.
+     *
+     * @param record Provides the materialized record.
+     * @returns Resolves after the record is written.
+     */
+    protected writeRecord(record: ReturnType<RecordSpec<I, R>["materialize"]>): Promise<void>;
+    /**
+     * Executes work with the coordinator-bound connection or a temporary connection.
+     *
+     * @param work Performs the database operation.
+     * @typeParam T The database operation result type.
+     * @returns Resolves to the operation result.
+     */
+    private using;
+    /**
+     * Creates and validates the physical table once for this handle.
+     *
+     * @param connection Provides the connection used for preparation.
+     * @returns Resolves when the table is ready.
+     */
+    private ready;
+    /**
+     * Creates the table when absent and verifies its stored schema.
+     *
+     * @param connection Provides the connection used for schema operations.
+     * @returns Resolves after schema verification.
+     */
+    private createAndInspect;
+    /**
+     * Verifies one physical column against the canonical table specification.
+     *
+     * @param expected Describes the required column.
+     * @param actual Describes the stored column.
+     */
+    private assertCompatibleColumn;
+    /**
+     * Reads one record on the supplied connection.
+     *
+     * @param connection Provides the connection used for reading.
+     * @param id Identifies the record.
+     * @param lock Requests a row or gap lock when supported.
+     * @returns Resolves to the stored record when present.
+     */
+    private readOn;
+    /**
+     * Determines whether the physical table supports transactions.
+     *
+     * @param connection Provides the connection used for metadata inspection.
+     * @returns Resolves whether the table uses InnoDB.
+     */
+    private isTransactional;
+    /**
+     * Calculates the fixed-width advisory-lock key for one record slot.
+     *
+     * @param id Identifies the record slot.
+     * @returns The advisory-lock key.
+     */
+    private casLockKey;
+    /**
+     * Checks that an immutable slot is absent or stores identical bytes.
+     *
+     * @param connection Provides the connection used for reading.
+     * @param id Identifies the immutable slot.
+     * @param record Provides the proposed immutable record.
+     * @returns Resolves whether the slot is absent.
+     */
+    private immutableAbsent;
+    /**
+     * Writes one record on the supplied connection.
+     *
+     * @param connection Provides the connection used for writing.
+     * @param record Provides the record to store.
+     * @returns Resolves after the write.
+     */
+    private writeOn;
+    /**
+     * Tries to insert one immutable record without replacing an existing row.
+     *
+     * @param connection Provides the connection used for writing.
+     * @param record Provides the immutable record.
+     * @returns Resolves to the insertion result.
+     */
+    private insertImmutableOn;
+    /**
+     * Builds parameterized SQL for a legacy record query.
+     *
+     * @param query Specifies the legacy query.
+     * @returns The SQL statement and bound values.
+     */
+    private querySql;
+    /**
+     * Builds parameterized SQL for a normalized query plan.
+     *
+     * @param plan Specifies the normalized query plan.
+     * @returns The SQL statement and bound values.
+     */
+    private planSql;
+    /**
+     * Builds SQL for one normalized predicate and appends its bound values.
+     *
+     * @param predicate Specifies the predicate to compile.
+     * @param values Receives the predicate's bound values.
+     * @returns The predicate SQL.
+     */
+    private planPredicate;
+    /**
+     * Returns the SQL spelling of a declared query column.
+     *
+     * @param column Specifies the column name.
+     * @returns The column's SQL spelling.
+     */
+    private planColumn;
+    /**
+     * Converts a normalized query value for its declared column type.
+     *
+     * @param column Specifies the declared column.
+     * @param value Provides the query value.
+     * @returns The value accepted by the MySQL driver.
+     */
+    private planValue;
+    /**
+     * Validates all identifiers and columns in a legacy query.
+     *
+     * @param query Specifies the query to validate.
+     */
+    private validateQuery;
+    /**
+     * Validates that a query column is declared by this storage.
+     *
+     * @param name Specifies the physical column name.
+     */
+    private assertColumn;
+    /**
+     * Converts a record identifier for use by the MySQL driver.
+     *
+     * @param id Provides the record identifier.
+     * @returns The corresponding database value.
+     */
+    private idKey;
+    /**
+     * Validates that a record identifier can be stored.
+     *
+     * @param id Provides the record identifier.
+     */
+    private validateId;
+    /**
+     * Decodes a record identifier from a database value.
+     *
+     * @param key Provides the stored database value.
+     * @returns The reconstructed record identifier.
+     */
+    private decodeId;
+    /**
+     * Converts a legacy query value for its declared column type.
+     *
+     * @param name Specifies the physical column name.
+     * @param value Provides the query value.
+     * @returns The value accepted by the MySQL driver.
+     */
+    private queryValue;
+}
+//# sourceMappingURL=record-storage.d.ts.map

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

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