@workglow/storage 0.2.30 → 0.2.32

package/dist/sql/Dialect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Abstracts the dialect-specific differences between SQLite and PostgreSQL
+ * for the parts of the storage layer that build SQL by string concatenation.
+ *
+ * The two things that differ are:
+ *   - Identifier quoting (backticks vs double quotes)
+ *   - Parameter placeholders (`?` vs `$N`)
+ *
+ * Keeping these in one place lets the predicate builder, prefix DDL helpers
+ * and migrations runner emit the same SQL shape against either backend.
+ */
+export interface ISqlDialect {
+    readonly name: "sqlite" | "postgres";
+    /** Quote a table or column identifier so it survives unsafe characters. */
+    quoteId(id: string): string;
+    /** Render a parameter placeholder for the given 1-based index. */
+    placeholder(index: number): string;
+}
+export declare const SqliteDialect: ISqlDialect;
+export declare const PostgresDialect: ISqlDialect;
+//# sourceMappingURL=Dialect.d.ts.map

package/dist/sql/Dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dialect.d.ts","sourceRoot":"","sources":["../../src/sql/Dialect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IACrC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,kEAAkE;IAClE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,eAAO,MAAM,aAAa,EAAE,WAQ3B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAQ7B,CAAC"}

package/dist/sql/PredicateBuilder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type DeleteSearchCriteria, type ValueOptionType } from "../tabular/ITabularStorage";
+import type { ISqlDialect } from "./Dialect";
+/**
+ * Result of {@link buildSearchWhere} — a parameterized WHERE-clause body
+ * (without the leading `WHERE` keyword) and its ordered parameters.
+ */
+export interface BuiltWhereClause {
+    readonly whereClause: string;
+    readonly params: ValueOptionType[];
+}
+/**
+ * Builds a parameterized AND-joined WHERE clause from a {@link DeleteSearchCriteria}.
+ * Used by every SQL tabular backend so the operator handling stays consistent.
+ *
+ * @param dialect       Identifier-quoting + placeholder rules for the target DB.
+ * @param criteria      Per-column equality value or {@link SearchOperator} condition.
+ * @param schemaProps   Schema property bag — unknown columns throw, preventing
+ *                      callers from accidentally letting user input pick a column.
+ * @param convertValue  Backend-specific JS-to-SQL coercion (e.g. boolean → 0/1).
+ * @param startIndex    1-based starting parameter index (defaults to 1).
+ *                      PostgreSQL callers use this when other params have already
+ *                      been bound; SQLite ignores it because placeholders are positional.
+ */
+export declare function buildSearchWhere<Entity>(dialect: ISqlDialect, criteria: DeleteSearchCriteria<Entity>, schemaProps: Record<string, unknown>, convertValue: (column: string, value: Entity[keyof Entity]) => ValueOptionType, startIndex?: number): BuiltWhereClause;
+//# sourceMappingURL=PredicateBuilder.d.ts.map

package/dist/sql/PredicateBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PredicateBuilder.d.ts","sourceRoot":"","sources":["../../src/sql/PredicateBuilder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,oBAAoB,EAGzB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EACrC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,oBAAoB,CAAC,MAAM,CAAC,EACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,MAAM,CAAC,KAAK,eAAe,EAC9E,UAAU,GAAE,MAAU,GACrB,gBAAgB,CAgClB"}

package/dist/sql/PrefixDdl.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ISqlDialect } from "./Dialect";
+/**
+ * Minimal column descriptor used by the prefix-DDL helpers. This mirrors the
+ * `PrefixColumn` shape that backends like the job queue and rate limiter use,
+ * without forcing `@workglow/storage` to take a dependency on those packages.
+ *
+ * Backends that have their own `PrefixColumn`-like type pass instances of it
+ * directly — the structural match is enough.
+ */
+export interface ISqlPrefixColumn {
+    readonly name: string;
+    readonly type: "uuid" | "number";
+}
+/**
+ * Throws if any prefix column name would be unsafe to splice into DDL.
+ *
+ * Beyond shape-checking via {@link SAFE_IDENTIFIER}, this also rejects names
+ * that match a common SQL reserved word ({@link SQL_RESERVED_WORDS}) since
+ * they're spliced unquoted and would otherwise produce confusing syntax
+ * errors at the database level. Every helper in this module that splices
+ * `prefix.name` into SQL calls this first, so storage backends don't need to
+ * remember to validate at construction time.
+ */
+export declare function assertPrefixesSafe(prefixes: readonly ISqlPrefixColumn[]): void;
+/**
+ * Throws if any declared prefix column lacks a value in `prefixValues`.
+ *
+ * Prefix columns are declared `NOT NULL` in the DDL helpers; binding
+ * `undefined` for them later yields opaque database errors ("invalid input
+ * syntax for type X" / "null value violates not-null constraint"). Catch the
+ * misconfiguration at the call site instead.
+ */
+export declare function assertPrefixValuesPresent(prefixes: readonly ISqlPrefixColumn[], prefixValues: Readonly<Record<string, string | number>>): void;
+/** Returns the SQL column type for a {@link ISqlPrefixColumn} on the given dialect. */
+export declare function prefixColumnType(dialect: ISqlDialect, type: ISqlPrefixColumn["type"]): string;
+/**
+ * Builds the prefix portion of a CREATE TABLE column list, e.g.
+ * `tenant_id UUID NOT NULL,\n  project_id INTEGER NOT NULL,\n  `
+ *
+ * Returns an empty string when there are no prefixes so callers can splice it
+ * directly into a column list without a trailing comma.
+ */
+export declare function buildPrefixColumnsSql(dialect: ISqlDialect, prefixes: readonly ISqlPrefixColumn[]): string;
+/** Returns prefix column names in declaration order. */
+export declare function getPrefixColumnNames(prefixes: readonly ISqlPrefixColumn[]): string[];
+/**
+ * Comma-joined prefix column list with a trailing `, ` for index/insert use,
+ * or an empty string when there are no prefixes.
+ */
+export declare function getPrefixIndexPrefix(prefixes: readonly ISqlPrefixColumn[]): string;
+/** Returns the index-name suffix derived from prefix columns. */
+export declare function getPrefixIndexSuffix(prefixes: readonly ISqlPrefixColumn[]): string;
+/**
+ * Builds an ` AND col1 = ? AND col2 = ?` (or `$N` for Postgres) suffix.
+ *
+ * @param startParam 1-based starting parameter index (Postgres only — SQLite
+ *                   placeholders are positional and ignore this).
+ */
+export declare function buildPrefixWhereClause(dialect: ISqlDialect, prefixes: readonly ISqlPrefixColumn[], prefixValues: Readonly<Record<string, string | number>>, startParam?: number): {
+    conditions: string;
+    params: Array<string | number>;
+};
+/** Returns prefix values in column order for binding to placeholders. */
+export declare function getPrefixParamValues(prefixes: readonly ISqlPrefixColumn[], prefixValues: Readonly<Record<string, string | number>>): Array<string | number>;
+/**
+ * Builds the prefix-portion of an INSERT column list and its placeholder list,
+ * starting at parameter index `startParam`. Returns empty strings when there
+ * are no prefixes so callers can concatenate without a trailing comma.
+ */
+export declare function buildPrefixInsertFragments(dialect: ISqlDialect, prefixes: readonly ISqlPrefixColumn[], startParam?: number): {
+    columns: string;
+    placeholders: string;
+};
+//# sourceMappingURL=PrefixDdl.d.ts.map

package/dist/sql/PrefixDdl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrefixDdl.d.ts","sourceRoot":"","sources":["../../src/sql/PrefixDdl.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;CAClC;AA0FD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAa9E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GACtD,IAAI,CAUN;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,MAAM,CAK7F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,MAAM,CAQR;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAEpF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAIlF;AAED,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAIlF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EACvD,UAAU,GAAE,MAAU,GACrB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;CAAE,CASxD;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GACtD,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAIxB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,UAAU,GAAE,MAAU,GACrB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAO3C"}

package/dist/sql/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./Dialect";
+export * from "./PredicateBuilder";
+export * from "./PrefixDdl";
+//# sourceMappingURL=index.d.ts.map

package/dist/sql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sql/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC"}

package/dist/tabular/BaseSqlTabularStorage.d.ts

@@ -5,7 +5,7 @@
  */
 import { DataPortSchemaObject, FromSchema, JsonSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
 import { BaseTabularStorage, ClientProvidedKeysOption } from "./BaseTabularStorage";
-import { AutoGeneratedKeys, InsertEntity, SimplifyPrimaryKey, ValueOptionType } from "./ITabularStorage";
+import { AutoGeneratedKeys, InsertEntity, OrderBy, Page, PageRequest, SearchCriteria, SimplifyPrimaryKey, ValueOptionType } from "./ITabularStorage";
 /**
  * Base class for SQL-based tabular repositories that implements common functionality
  * for both SQLite and PostgreSQL database implementations.
@@ -29,7 +29,7 @@ export declare abstract class BaseSqlTabularStorage<Schema extends DataPortSchem
     private readonly _valColsCache;
     private readonly _pkColListCache;
     private readonly _valColListCache;
-    constructor(table: string | undefined, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], clientProvidedKeys?: ClientProvidedKeysOption);
+    constructor(table: string | undefined, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], clientProvidedKeys?: ClientProvidedKeysOption, tabularMigrations?: ReadonlyArray<import("../migrations").ITabularMigration>, migrationName?: string);
     /**
      * Maps JavaScript/TypeScript types to their corresponding SQL type
      * Must be implemented by derived classes for specific SQL dialects
@@ -96,5 +96,66 @@ export declare abstract class BaseSqlTabularStorage<Schema extends DataPortSchem
      * @throws Error if validation fails
      */
     protected validateTableAndSchema(): void;
+    /**
+     * Builds a keyset (seek) WHERE clause that selects rows strictly after
+     * the cursor position according to the provided ordering. Handles mixed
+     * ASC/DESC by expanding into the OR-of-AND form:
+     *
+     *   (col1 OP1 v1)
+     *   OR (col1 = v1 AND col2 OP2 v2)
+     *   OR (col1 = v1 AND col2 = v2 AND col3 OP3 v3)
+     *   ...
+     *
+     * NULL handling. We adopt the same NULL ordering as the in-memory
+     * comparator: NULLs sort *before* non-null values for ASC, *after* them
+     * for DESC. The pair `runSqlPage` / `buildKeysetWhere` enforce this with
+     * explicit `NULLS FIRST` / `NULLS LAST` in the ORDER BY plus NULL-aware
+     * predicates here. Because the cursor's values are known at SQL-build
+     * time, we branch at build time on NULL vs non-NULL rather than relying
+     * on dialect-specific operators like `IS NOT DISTINCT FROM`:
+     *
+     *   - Equality on a preceding column:
+     *       NULL  -> `col IS NULL`
+     *       value -> `col = ?`
+     *   - Strict comparison on the i-th column:
+     *       ASC, NULL  -> `col IS NOT NULL`              (NULL is the smallest)
+     *       ASC, value -> `col > ?`                       (NULLs sort before, excluded)
+     *       DESC, NULL -> `1 = 0`                         (nothing comes after a NULL trailer)
+     *       DESC, value-> `(col < ? OR col IS NULL)`      (smaller, then NULLs)
+     *
+     * @param effectiveOrderBy - Ordering to satisfy; must include the primary
+     *   key columns at the tail so the comparison is total.
+     * @param cursorValues - Values pulled from the cursor in the same order
+     *   as `effectiveOrderBy`.
+     * @param quote - Identifier quote character (e.g. `` ` `` or `"`).
+     * @param placeholder - Function returning the placeholder string for the
+     *   given 1-based parameter index.
+     * @param startIndex - Param index to start numbering from. Returns the
+     *   index to use after this clause's params.
+     */
+    protected buildKeysetWhere(effectiveOrderBy: ReadonlyArray<OrderBy<Entity>>, cursorValues: ReadonlyArray<ValueOptionType>, quote: string, placeholder: (index: number) => string, startIndex: number): {
+        whereClause: string;
+        params: ValueOptionType[];
+        nextIndex: number;
+    };
+    /**
+     * Shared SQL `getPage`/`queryPage` driver. Builds a single SELECT that
+     * pushes the keyset predicate, ordering, and limit down to the database
+     * so memory and wire traffic are O(pageSize) regardless of table size.
+     *
+     * Concrete SQL backends call this from their `getPage`/`queryPage`
+     * overrides, supplying the dialect-specific quoting, placeholder
+     * formatting, search-criteria WHERE builder, and select executor.
+     */
+    protected runSqlPage(criteria: SearchCriteria<Entity> | undefined, request: PageRequest<Entity>, dialect: {
+        readonly quote: string;
+        readonly placeholder: (index: number) => string;
+        readonly buildSearchWhere: (criteria: SearchCriteria<Entity>, startIndex: number) => {
+            whereClause: string;
+            params: ValueOptionType[];
+            nextIndex: number;
+        };
+        readonly executeSelect: (sql: string, params: ValueOptionType[]) => Promise<Entity[]>;
+    }): Promise<Page<Entity>>;
 }
 //# sourceMappingURL=BaseSqlTabularStorage.d.ts.map

package/dist/tabular/BaseSqlTabularStorage.d.ts.map

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

package/dist/tabular/BaseTabularStorage.d.ts

@@ -5,7 +5,9 @@
  */
 import { EventEmitter } from "@workglow/util";
 import { DataPortSchemaObject, FromSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
-import { AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, ITabularStorage, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularEventListener, TabularEventListeners, TabularEventName, TabularEventParameters, TabularSubscribeOptions, ValueOptionType } from "./ITabularStorage";
+import { AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, ITabularStorage, OrderBy, Page, PageRequest, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularEventListener, TabularEventListeners, TabularEventName, TabularEventParameters, TabularSubscribeOptions, ValueOptionType } from "./ITabularStorage";
+import { CursorPayload, PageCursor } from "./Cursor";
+import { ITabularMigration, ITabularMigrationApplier, RunTabularMigrationsOptions } from "../migrations";
 export declare const TABULAR_REPOSITORY: import("@workglow/util").ServiceToken<AnyTabularStorage>;
 /**
  * Options for controlling how client-provided values for auto-generated keys are handled
@@ -32,6 +34,18 @@ export declare abstract class BaseTabularStorage<Schema extends DataPortSchemaOb
     protected indexes: Array<keyof Entity>[];
     protected primaryKeySchema: DataPortSchemaObject;
     protected valueSchema: DataPortSchemaObject;
+    /**
+     * Optional declarative migrations evolving older deployments to the
+     * current target schema. When set + non-empty, `setupDatabase()` on
+     * concrete subclasses delegates to {@link applyTabularMigrations}.
+     */
+    protected readonly tabularMigrations: ReadonlyArray<ITabularMigration> | undefined;
+    /**
+     * Default component name used when an `ITabularMigration.component` is
+     * omitted. Defaults to `tabular:${storageName}` once the subclass has
+     * supplied a name.
+     */
+    protected migrationComponent: string;
     /** Name of the auto-generated key column (at most one primary key column may be auto-generated) */
     protected autoGeneratedKeyName: keyof Entity | null;
     /** Strategy for generating the auto-generated key */
@@ -46,7 +60,7 @@ export declare abstract class BaseTabularStorage<Schema extends DataPortSchemaOb
      *                    while each array creates a compound index with columns in the specified order.
      * @param clientProvidedKeys - How to handle client-provided values for auto-generated keys
      */
-    constructor(schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], clientProvidedKeys?: ClientProvidedKeysOption);
+    constructor(schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], clientProvidedKeys?: ClientProvidedKeysOption, tabularMigrations?: ReadonlyArray<ITabularMigration>, migrationName?: string);
     protected filterCompoundKeys(primaryKey: Array<keyof Entity>, potentialKeys: Array<keyof Entity>[]): Array<keyof Entity>[];
     /**
      * Adds an event listener for a specific event
@@ -127,18 +141,72 @@ export declare abstract class BaseTabularStorage<Schema extends DataPortSchemaOb
     abstract getBulk(offset: number, limit: number): Promise<Entity[] | undefined>;
     /**
      * Async generator that yields records one at a time.
-     * Uses getBulk internally to fetch pages of data.
+     *
+     * Backed by cursor-based pagination so iteration is stable when rows are
+     * inserted or deleted concurrently — unlike offset paging, which can skip
+     * or duplicate rows under those conditions.
+     *
      * @param pageSize - Number of records to fetch per page (default: 100)
-     * @yields Individual entity records
      */
     records(pageSize?: number): AsyncGenerator<Entity, void, undefined>;
     /**
      * Async generator that yields pages of records.
-     * Uses getBulk internally to fetch pages of data.
+     *
+     * Backed by cursor-based pagination — stable under concurrent writes.
+     * Each yielded array is a fresh copy of `Page.items`; mutating the
+     * yielded array won't affect the underlying storage or subsequent
+     * pages, at the cost of one allocation per page.
+     *
      * @param pageSize - Number of records per page (default: 100)
-     * @yields Arrays of entities
      */
     pages(pageSize?: number): AsyncGenerator<Entity[], void, undefined>;
+    /**
+     * Default keyset-pagination implementation. Backends that can express
+     * tuple comparison natively (SQL row-value comparisons) should override
+     * this for efficiency, but the default works against any implementation
+     * of {@link query} / {@link getAll}.
+     */
+    getPage(request?: PageRequest<Entity>): Promise<Page<Entity>>;
+    /** Default cursor-paginated form of {@link query}. */
+    queryPage(criteria: SearchCriteria<Entity>, request?: PageRequest<Entity>): Promise<Page<Entity>>;
+    /**
+     * Shared keyset-pagination engine for both {@link getPage} and
+     * {@link queryPage}. Translates the cursor into AND criteria using the
+     * primary key column(s) and runs the existing {@link query}/{@link getAll}
+     * machinery, then re-encodes the position of the last returned row.
+     *
+     * For composite primary keys this performs the keyset comparison in
+     * memory after fetching a candidate window. SQL backends should override
+     * {@link getPage}/{@link queryPage} to push it down to the database.
+     */
+    protected runPage(criteria: SearchCriteria<Entity> | undefined, request: PageRequest<Entity>): Promise<Page<Entity>>;
+    /**
+     * Returns the order spec actually used to drive a keyset page: the
+     * caller's `orderBy` (if any) followed by every primary-key column as a
+     * stable tiebreaker. PK columns are appended in ASC direction unless the
+     * caller already specified a direction for them.
+     */
+    protected buildEffectiveOrderBy(orderBy: ReadonlyArray<OrderBy<Entity>> | undefined, pkColumns: ReadonlyArray<keyof Entity>): ReadonlyArray<OrderBy<Entity>>;
+    /**
+     * Sorts rows in place by the given order spec, using the same null-first
+     * comparison rules as the cursor filter so results are consistent.
+     */
+    protected sortInMemory(rows: Entity[], orderBy: ReadonlyArray<OrderBy<Entity>>): Entity[];
+    /**
+     * In-memory keyset filter: drops rows that come at or before the cursor
+     * row according to `orderBy + primaryKey`. Used by the default
+     * implementation when the backend can't express tuple comparison.
+     */
+    protected applyKeysetFilter(rows: Entity[], cursor: CursorPayload, effectiveOrderBy: ReadonlyArray<OrderBy<Entity>>, _pkColumns: ReadonlyArray<keyof Entity>): Entity[];
+    /**
+     * Encodes the position of `row` as an opaque cursor. The caller passes
+     * the effective ordering it just used — caller-supplied `orderBy`
+     * followed by any primary-key columns not already covered by `orderBy`
+     * — and this writes one value per effective column, in the same order.
+     * Computing that ordering is the caller's responsibility because they
+     * already have it in hand and we don't want to recompute it here.
+     */
+    protected buildCursor(row: Entity, effectiveOrderBy: ReadonlyArray<OrderBy<Entity>>): PageCursor;
     /**
      * Subscribes to changes in the repository (including remote changes).
      * Default implementation throws an error - override in subclasses that support subscriptions.
@@ -161,6 +229,25 @@ export declare abstract class BaseTabularStorage<Schema extends DataPortSchemaOb
      * Validates getAll options (orderBy, limit, offset) without criteria.
      */
     protected validateGetAllOptions(options?: QueryOptions<Entity>): void;
+    /**
+     * Validates the `orderBy` clause of a {@link PageRequest}: column names
+     * must exist in the schema and directions must be `"ASC"` or `"DESC"`.
+     *
+     * Page paths (`getPage`/`queryPage`) must call this before any backend
+     * builds SQL, because column names from `request.orderBy` end up
+     * interpolated directly into `ORDER BY` and the keyset `WHERE` clauses.
+     * Without this guard a caller passing arbitrary strings would either
+     * trigger a backend SQL error or, worse, allow SQL injection on backends
+     * that emit unquoted identifiers.
+     */
+    protected validateOrderBy(orderBy: ReadonlyArray<OrderBy<Entity>> | undefined): void;
+    /**
+     * Validates the components of a cursor-paginated request that are about
+     * to be used to build a query. Centralises the schema-level guarantees
+     * that `runPage`/`runSqlPage`/Supabase's `runSupabasePage` all rely on
+     * before they interpolate column names into SQL or PostgREST filters.
+     */
+    protected validatePageRequest(request: PageRequest<Entity>): void;
     /**
      * Validates the `select` array in a {@link CoveringIndexQueryOptions}.
      * Throws {@link StorageValidationError} when `select` is empty or contains
@@ -226,6 +313,24 @@ export declare abstract class BaseTabularStorage<Schema extends DataPortSchemaOb
      * @returns The generated key value
      */
     protected generateKeyValue(columnName: string, strategy: KeyGenerationStrategy): Promise<string | number> | string | number;
+    /**
+     * Runs `fn` inside a transaction. The default implementation provides no
+     * rollback semantics — it simply invokes `fn(this)`. Concrete subclasses
+     * with native transaction support (SQLite, PostgreSQL) override this.
+     */
+    withTransaction<T>(fn: (tx: this) => Promise<T>): Promise<T>;
+    /**
+     * Subclass override returning a backend-specific applier. Returning `null`
+     * disables tabular migrations for the storage. The base class returns
+     * `null`; only backends that have wired up their applier override this.
+     */
+    getMigrationApplier(): ITabularMigrationApplier | null;
+    /**
+     * Runs `this.tabularMigrations` through the orchestrator using the
+     * backend-supplied applier. Idempotent (no-op when no migrations are
+     * declared, or when all are already applied).
+     */
+    protected applyTabularMigrations(options?: RunTabularMigrationsOptions): Promise<void>;
     /**
      * Sets up the database/storage for the repository.
      * Must be called before using any other methods (except for in-memory implementations).

package/dist/tabular/BaseTabularStorage.d.ts.map

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

package/dist/tabular/CachedTabularStorage.d.ts

@@ -5,6 +5,7 @@
  */
 import { DataPortSchemaObject, FromSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
 import { BaseTabularStorage, ClientProvidedKeysOption } from "./BaseTabularStorage";
+import type { ITabularMigrationApplier } from "../migrations";
 import { AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, ITabularStorage, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularSubscribeOptions } from "./ITabularStorage";
 export declare const CACHED_TABULAR_REPOSITORY: import("@workglow/util").ServiceToken<AnyTabularStorage>;
 /**
@@ -105,6 +106,31 @@ export declare class CachedTabularStorage<Schema extends DataPortSchemaObject, P
      * @param criteria - Object with column names as keys and values or SearchConditions
      */
     deleteSearch(criteria: DeleteSearchCriteria<Entity>): Promise<void>;
+    /**
+     * Runs `fn` inside the durable store's transaction. The cache layer is
+     * intentionally bypassed for the transaction's duration — coordinating
+     * two-phase commit between the durable store and an in-memory cache is
+     * out of scope, and callers asking for `withTransaction` are asking for
+     * atomicity, which only the durable can provide. Inside `fn`, reads and
+     * writes go straight through the durable's transaction handle.
+     *
+     * **`tx` identity:** the handle passed to `fn` is the durable store's
+     * transaction proxy, not a `CachedTabularStorage`, despite the `(tx: this)`
+     * type. Wrapper-specific members like `tx.cache` or `tx.invalidateCache()`
+     * therefore type-check but throw at runtime — call them on the original
+     * wrapper after `withTransaction` resolves instead.
+     *
+     * **Cache freshness on commit/rollback:** any rows the transaction touched
+     * (committed inserts/updates/deletes, or rolled-back attempts that were
+     * already mirrored into the cache via earlier non-tx writes) leave the
+     * cache potentially out of step with durable. Invalidate unconditionally
+     * after `fn` resolves so the next read repopulates the cache from durable
+     * — over-invalidating on rollback is cheap and avoids leaking the
+     * rollback boundary into the cache layer. Inheriting `BaseTabularStorage`'s
+     * no-op default here would silently lose the rollback / atomicity guarantee,
+     * since the default just runs `fn(this)` against the cached wrapper itself.
+     */
+    withTransaction<T>(fn: (tx: this) => Promise<T>): Promise<T>;
     /**
      * Invalidates the cache by clearing it and resetting initialization flag
      */
@@ -123,6 +149,18 @@ export declare class CachedTabularStorage<Schema extends DataPortSchemaObject, P
      * @returns Unsubscribe function
      */
     subscribeToChanges(callback: (change: any) => void, options?: TabularSubscribeOptions): () => void;
+    /**
+     * Forwards `setupDatabase` to the durable storage (which owns any
+     * declared tabular migrations) and to the cache. Migrations themselves
+     * are passed when constructing the inner durable storage; the wrapper
+     * does not declare its own.
+     */
+    setupDatabase(): Promise<void>;
+    /**
+     * Delegates to the durable storage's applier so callers that use the
+     * wrapper observe migrations declared on the inner durable layer.
+     */
+    getMigrationApplier(): ITabularMigrationApplier | null;
     /**
      * Destroys the durable and cache repositories.
      */

package/dist/tabular/CachedTabularStorage.d.ts.map

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

package/dist/tabular/Cursor.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Opaque cursor token returned by paginated queries.
+ *
+ * Encodes the position of the last seen row so the next page can resume
+ * from there using keyset (a.k.a. seek) pagination. Callers must treat
+ * cursors as opaque — the encoding is an implementation detail.
+ *
+ * Named `PageCursor` (not `Cursor`) to avoid colliding with the unrelated
+ * generic iterator type `Cursor<T>` exported from `@workglow/util`.
+ */
+export type PageCursor = string & {
+    readonly __pageCursorBrand: unique symbol;
+};
+/**
+ * Internal cursor payload.
+ *
+ * - `v` is a format version (currently 1) so older cursors can be rejected
+ *   if the encoding ever changes.
+ * - `n` (names), `d` (directions, `"a"` ASC / `"d"` DESC), and `c` (column
+ *   values) are parallel arrays describing the effective ordering of the
+ *   row the cursor is parked on: caller-supplied `orderBy` columns first,
+ *   then any primary-key columns not already covered by `orderBy` as a
+ *   tiebreaker. The flat layout means columns that appear in both the
+ *   user's `orderBy` and the primary key are stored exactly once (avoids
+ *   double-encoding the value in DESC-by-PK pagination). Storing column
+ *   names AND directions lets us reject cursors handed back with a
+ *   different ordering — same-name + flipped direction would otherwise
+ *   compute the next page with the wrong comparison operators.
+ */
+export interface CursorPayload {
+    readonly v: 1;
+    readonly n: ReadonlyArray<string>;
+    readonly d: ReadonlyArray<"a" | "d">;
+    readonly c: ReadonlyArray<string | number | boolean | null>;
+}
+/** Cursor format version recognised by this build. */
+export declare const CURSOR_VERSION: 1;
+/**
+ * Maximum accepted cursor length, in characters of the encoded form.
+ * Real cursors are well under 1 KB (a few primary-key values plus an
+ * orderBy worth of column names); the cap exists so a hostile client
+ * can't force the server to base64-decode and JSON-parse arbitrarily
+ * large strings, which would be cheap memory/CPU abuse.
+ */
+export declare const MAX_CURSOR_LENGTH: number;
+/**
+ * Encodes a cursor payload as an opaque, URL-safe string.
+ *
+ * The transport is base64url(JSON(payload)). The format is intentionally
+ * not documented for callers — it's an implementation detail and may be
+ * tightened in future versions (signed, length-limited, etc.).
+ */
+export declare function encodeCursor(payload: CursorPayload): PageCursor;
+/**
+ * Decodes an opaque cursor string into its payload.
+ *
+ * @throws {StorageValidationError} when the cursor is malformed, exceeds
+ *   {@link MAX_CURSOR_LENGTH}, or the format version is unknown. Callers
+ *   should surface these as 4xx errors rather than retrying.
+ */
+export declare function decodeCursor(cursor: PageCursor | string): CursorPayload;
+/**
+ * Validates that a decoded cursor matches the effective ordering the
+ * current request would use, by exact column-name AND direction sequence.
+ * A mismatch usually means the caller switched ordering mid-iteration —
+ * e.g. asked for `orderBy: [a ASC]` on page 1 and `orderBy: [a DESC]` on
+ * page 2, or swapped to a different column entirely — both of which would
+ * produce nonsensical results that arity matching alone can't catch.
+ */
+export declare function assertCursorMatches(payload: CursorPayload, effectiveOrder: ReadonlyArray<{
+    readonly column: string;
+    readonly direction: "ASC" | "DESC";
+}>): void;
+//# sourceMappingURL=Cursor.d.ts.map

package/dist/tabular/Cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cursor.d.ts","sourceRoot":"","sources":["../../src/tabular/Cursor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,QAAQ,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,CAAC,EAAE,aAAa,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;IACrC,QAAQ,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,sDAAsD;AACtD,eAAO,MAAM,cAAc,EAAG,CAAU,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAW,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,CAwC/D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,aAAa,CA0DvE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,cAAc,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,CAAC,GAC7F,IAAI,CAqBN"}