@remix-run/data-table 0.1.0 → 0.2.1

package/dist/lib/errors.d.ts

@@ -2,7 +2,13 @@
  * Base error for all `data-table` failures.
  */
 export declare class DataTableError extends Error {
+    /**
+     * Stable error code identifying the failure category.
+     */
     code: string;
+    /**
+     * Optional structured metadata attached to the failure.
+     */
     metadata?: Record<string, unknown>;
     constructor(message: string, options?: {
         code?: string;
@@ -14,6 +20,9 @@ export declare class DataTableError extends Error {
  * Thrown when input data fails schema validation.
  */
 export declare class DataTableValidationError extends DataTableError {
+    /**
+     * Validation issues reported by the schema validator.
+     */
     issues: ReadonlyArray<unknown>;
     constructor(message: string, issues: ReadonlyArray<unknown>, options?: {
         cause?: unknown;

package/dist/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAElC,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EAMF;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;IAC1D,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAE9B,YACE,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EAUF;CACF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EASF;CACF;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EASF;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;IAC1D,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EASF;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAElC,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EAMF;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;IAC1D;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAE9B,YACE,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EAUF;CACF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EASF;CACF;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EASF;CACF;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;IAC1D,YACE,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACnC,EASF;CACF"}

package/dist/lib/errors.js

@@ -2,7 +2,13 @@
  * Base error for all `data-table` failures.
  */
 export class DataTableError extends Error {
+    /**
+     * Stable error code identifying the failure category.
+     */
     code;
+    /**
+     * Optional structured metadata attached to the failure.
+     */
     metadata;
     constructor(message, options) {
         super(message, { cause: options?.cause });
@@ -15,6 +21,9 @@ export class DataTableError extends Error {
  * Thrown when input data fails schema validation.
  */
 export class DataTableValidationError extends DataTableError {
+    /**
+     * Validation issues reported by the schema validator.
+     */
     issues;
     constructor(message, issues, options) {
         super(message, {

package/dist/lib/migrations/filename.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parses a migration filename into `{ id, name }`.
+ *
+ * Expected format: `YYYYMMDDHHmmss_name.(ts|js|mts|mjs|cts|cjs)`.
+ * @param filename Migration file basename.
+ * @returns Parsed migration id and name.
+ */
+export declare function parseMigrationFilename(filename: string): {
+    id: string;
+    name: string;
+};
+//# sourceMappingURL=filename.d.ts.map

package/dist/lib/migrations/filename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../../../src/lib/migrations/filename.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAerF"}

package/dist/lib/migrations/filename.js

@@ -0,0 +1,20 @@
+const migrationFilenamePattern = /^(\d{14})_(.+)\.(?:m?ts|m?js|cts|cjs)$/;
+/**
+ * Parses a migration filename into `{ id, name }`.
+ *
+ * Expected format: `YYYYMMDDHHmmss_name.(ts|js|mts|mjs|cts|cjs)`.
+ * @param filename Migration file basename.
+ * @returns Parsed migration id and name.
+ */
+export function parseMigrationFilename(filename) {
+    let match = filename.match(migrationFilenamePattern);
+    if (!match) {
+        throw new Error('Invalid migration filename "' +
+            filename +
+            '". Expected format YYYYMMDDHHmmss_name.ts (or .js/.mts/.mjs/.cts/.cjs)');
+    }
+    return {
+        id: match[1],
+        name: match[2],
+    };
+}

package/dist/lib/migrations/helpers.d.ts

@@ -0,0 +1,11 @@
+import type { TableRef } from '../adapter.ts';
+import type { IndexColumns, KeyColumns } from '../migrations.ts';
+export declare function toTableRef(name: string): TableRef;
+export declare function normalizeIndexColumns(columns: IndexColumns): string[];
+export declare function normalizeKeyColumns(columns: KeyColumns): string[];
+export declare function createPrimaryKeyName(table: TableRef): string;
+export declare function createUniqueName(table: TableRef, columns: string[]): string;
+export declare function createForeignKeyName(table: TableRef, columns: string[], references: TableRef, referenceColumns: string[]): string;
+export declare function createCheckName(table: TableRef, expression: string): string;
+export declare function createIndexName(table: TableRef, columns: string[]): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/lib/migrations/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/migrations/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAEhE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAWjD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAErE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,EAAE,CAMjE;AAgDD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAE5D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3E;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,QAAQ,EACpB,gBAAgB,EAAE,MAAM,EAAE,GACzB,MAAM,CAWR;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1E"}

package/dist/lib/migrations/helpers.js

@@ -0,0 +1,77 @@
+export function toTableRef(name) {
+    let segments = name.split('.');
+    if (segments.length === 1) {
+        return { name };
+    }
+    return {
+        schema: segments[0],
+        name: segments.slice(1).join('.'),
+    };
+}
+export function normalizeIndexColumns(columns) {
+    return normalizeKeyColumns(columns);
+}
+export function normalizeKeyColumns(columns) {
+    if (Array.isArray(columns)) {
+        return [...columns];
+    }
+    return [columns];
+}
+function normalizeNamePart(value) {
+    let normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    if (normalized.length === 0) {
+        return 'item';
+    }
+    return normalized;
+}
+function tableNamePart(table) {
+    if (table.schema) {
+        return normalizeNamePart(table.schema + '_' + table.name);
+    }
+    return normalizeNamePart(table.name);
+}
+function hashString(value) {
+    let hash = 5381;
+    for (let index = 0; index < value.length; index++) {
+        hash = ((hash << 5) + hash) ^ value.charCodeAt(index);
+    }
+    return hash >>> 0;
+}
+function withNameLimit(name) {
+    let limit = 63;
+    if (name.length <= limit) {
+        return name;
+    }
+    let suffix = hashString(name).toString(36).padStart(8, '0').slice(0, 8);
+    return name.slice(0, limit - 9) + '_' + suffix;
+}
+function columnsNamePart(columns) {
+    return columns.map((column) => normalizeNamePart(column)).join('_');
+}
+export function createPrimaryKeyName(table) {
+    return withNameLimit(tableNamePart(table) + '_pk');
+}
+export function createUniqueName(table, columns) {
+    return withNameLimit(tableNamePart(table) + '_' + columnsNamePart(columns) + '_uq');
+}
+export function createForeignKeyName(table, columns, references, referenceColumns) {
+    let base = tableNamePart(table) +
+        '_' +
+        columnsNamePart(columns) +
+        '_' +
+        tableNamePart(references) +
+        '_' +
+        columnsNamePart(referenceColumns) +
+        '_fk';
+    return withNameLimit(base);
+}
+export function createCheckName(table, expression) {
+    let suffix = hashString(expression).toString(36);
+    return withNameLimit(tableNamePart(table) + '_chk_' + suffix);
+}
+export function createIndexName(table, columns) {
+    return withNameLimit(tableNamePart(table) + '_' + columnsNamePart(columns) + '_idx');
+}

package/dist/lib/migrations/journal-store.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseAdapter, TransactionToken } from '../adapter.ts';
+import type { MigrationDescriptor, MigrationJournalRow } from '../migrations.ts';
+export declare function normalizeChecksum(migration: MigrationDescriptor): string;
+export declare function ensureMigrationJournal(adapter: DatabaseAdapter, tableName: string): Promise<void>;
+export declare function hasMigrationJournal(adapter: DatabaseAdapter, tableName: string): Promise<boolean>;
+export declare function loadJournalRows(adapter: DatabaseAdapter, tableName: string): Promise<MigrationJournalRow[]>;
+export declare function insertJournalRow(adapter: DatabaseAdapter, tableName: string, row: {
+    id: string;
+    name: string;
+    checksum: string;
+    batch: number;
+}, transaction?: TransactionToken): Promise<void>;
+export declare function deleteJournalRow(adapter: DatabaseAdapter, tableName: string, id: string, transaction?: TransactionToken): Promise<void>;
+export declare function getBatch(rows: MigrationJournalRow[]): number;
+//# sourceMappingURL=journal-store.d.ts.map

package/dist/lib/migrations/journal-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-store.d.ts","sourceRoot":"","sources":["../../../src/lib/migrations/journal-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAEhF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAMxE;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAalB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAmBhC;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IACH,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd,EACD,WAAW,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,WAAW,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAO5D"}

package/dist/lib/migrations/journal-store.js

@@ -0,0 +1,83 @@
+import { rawSql } from "../sql.js";
+export function normalizeChecksum(migration) {
+    if (migration.checksum) {
+        return migration.checksum;
+    }
+    return migration.id + ':' + migration.name;
+}
+export async function ensureMigrationJournal(adapter, tableName) {
+    await adapter.migrate({
+        operation: {
+            kind: 'createTable',
+            table: { name: tableName },
+            ifNotExists: true,
+            columns: {
+                id: { type: 'varchar', length: 64, nullable: false, primaryKey: true },
+                name: { type: 'varchar', length: 255, nullable: false },
+                checksum: { type: 'varchar', length: 128, nullable: false },
+                batch: { type: 'integer', nullable: false },
+                applied_at: { type: 'timestamp', nullable: false, default: { kind: 'now' } },
+            },
+        },
+    });
+}
+export async function hasMigrationJournal(adapter, tableName) {
+    try {
+        await adapter.execute({
+            operation: {
+                kind: 'raw',
+                sql: rawSql('select 1 from ' + tableName + ' limit 1'),
+            },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function loadJournalRows(adapter, tableName) {
+    let result = await adapter.execute({
+        operation: {
+            kind: 'raw',
+            sql: rawSql('select id, name, checksum, batch, applied_at from ' + tableName + ' order by id asc'),
+        },
+    });
+    let rows = result.rows ?? [];
+    return rows.map((row) => ({
+        id: String(row.id),
+        name: String(row.name),
+        checksum: String(row.checksum),
+        batch: Number(row.batch),
+        appliedAt: new Date(String(row.applied_at)),
+    }));
+}
+export async function insertJournalRow(adapter, tableName, row, transaction) {
+    await adapter.execute({
+        operation: {
+            kind: 'raw',
+            sql: rawSql('insert into ' + tableName + ' (id, name, checksum, batch) values (?, ?, ?, ?)', [
+                row.id,
+                row.name,
+                row.checksum,
+                row.batch,
+            ]),
+        },
+        transaction,
+    });
+}
+export async function deleteJournalRow(adapter, tableName, id, transaction) {
+    await adapter.execute({
+        operation: {
+            kind: 'raw',
+            sql: rawSql('delete from ' + tableName + ' where id = ?', [id]),
+        },
+        transaction,
+    });
+}
+export function getBatch(rows) {
+    if (rows.length === 0) {
+        return 1;
+    }
+    let max = Math.max(...rows.map((row) => row.batch));
+    return max + 1;
+}

package/dist/lib/migrations/registry.d.ts

@@ -0,0 +1,27 @@
+import type { MigrationDescriptor, MigrationRegistry } from '../migrations.ts';
+/**
+ * Returns a new array of migrations ordered by migration id.
+ * @param migrations Migration descriptors to sort.
+ * @returns A newly sorted migration descriptor array.
+ */
+export declare function sortMigrations(migrations: MigrationDescriptor[]): MigrationDescriptor[];
+/**
+ * Resolves a migration source into a sorted migration list.
+ * @param input Migration list or registry.
+ * @returns A sorted migration descriptor list.
+ */
+export declare function resolveMigrations(input: MigrationDescriptor[] | MigrationRegistry): MigrationDescriptor[];
+/**
+ * Creates an in-memory migration registry.
+ * @param initial Optional initial migration list.
+ * @returns A migration registry with duplicate-id protection.
+ * @example
+ * ```ts
+ * import { createMigrationRegistry } from 'remix/data-table/migrations'
+ *
+ * let registry = createMigrationRegistry()
+ * registry.register({ id, name, migration })
+ * ```
+ */
+export declare function createMigrationRegistry(initial?: MigrationDescriptor[]): MigrationRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/lib/migrations/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/lib/migrations/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAE9E;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAEvF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,mBAAmB,EAAE,GAAG,iBAAiB,GAC/C,mBAAmB,EAAE,CAMvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,mBAAmB,EAAO,GAAG,iBAAiB,CAuB9F"}

package/dist/lib/migrations/registry.js

@@ -0,0 +1,51 @@
+/**
+ * Returns a new array of migrations ordered by migration id.
+ * @param migrations Migration descriptors to sort.
+ * @returns A newly sorted migration descriptor array.
+ */
+export function sortMigrations(migrations) {
+    return [...migrations].sort((left, right) => left.id.localeCompare(right.id));
+}
+/**
+ * Resolves a migration source into a sorted migration list.
+ * @param input Migration list or registry.
+ * @returns A sorted migration descriptor list.
+ */
+export function resolveMigrations(input) {
+    if (Array.isArray(input)) {
+        return sortMigrations(input);
+    }
+    return input.list();
+}
+/**
+ * Creates an in-memory migration registry.
+ * @param initial Optional initial migration list.
+ * @returns A migration registry with duplicate-id protection.
+ * @example
+ * ```ts
+ * import { createMigrationRegistry } from 'remix/data-table/migrations'
+ *
+ * let registry = createMigrationRegistry()
+ * registry.register({ id, name, migration })
+ * ```
+ */
+export function createMigrationRegistry(initial = []) {
+    let migrations = new Map();
+    for (let migration of initial) {
+        if (migrations.has(migration.id)) {
+            throw new Error('Duplicate migration id: ' + migration.id);
+        }
+        migrations.set(migration.id, migration);
+    }
+    return {
+        register(migration) {
+            if (migrations.has(migration.id)) {
+                throw new Error('Duplicate migration id: ' + migration.id);
+            }
+            migrations.set(migration.id, migration);
+        },
+        list() {
+            return sortMigrations(Array.from(migrations.values()));
+        },
+    };
+}

package/dist/lib/migrations/runner.d.ts

@@ -0,0 +1,20 @@
+import type { DatabaseAdapter } from '../adapter.ts';
+import type { MigrationDescriptor, MigrationRegistry, MigrationRunner, MigrationRunnerOptions } from '../migrations.ts';
+/**
+ * Creates a migration runner for applying/reverting migrations against an adapter.
+ * @param adapter Database adapter used to compile and execute migration operations.
+ * @param migrations Migration descriptors or registry.
+ * @param options Optional runner configuration.
+ * @returns A migration runner instance.
+ * @example
+ * ```ts
+ * import { createMigrationRunner } from 'remix/data-table/migrations'
+ *
+ * let runner = createMigrationRunner(adapter, migrations, {
+ *   journalTable: 'app_migrations',
+ * })
+ * await runner.up()
+ * ```
+ */
+export declare function createMigrationRunner(adapter: DatabaseAdapter, migrations: MigrationDescriptor[] | MigrationRegistry, options?: MigrationRunnerOptions): MigrationRunner;
+//# sourceMappingURL=runner.d.ts.map

package/dist/lib/migrations/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/lib/migrations/runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,eAAe,CAAA;AAEtE,OAAO,KAAK,EAIV,mBAAmB,EAGnB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EAGvB,MAAM,kBAAkB,CAAA;AAyRzB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,mBAAmB,EAAE,GAAG,iBAAiB,EACrD,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAwDjB"}

package/dist/lib/migrations/runner.js

@@ -0,0 +1,273 @@
+import { createDatabase, createDatabaseWithTransaction } from "../database.js";
+import { deleteJournalRow, ensureMigrationJournal, getBatch, hasMigrationJournal, insertJournalRow, loadJournalRows, normalizeChecksum, } from "./journal-store.js";
+import { resolveMigrations } from "./registry.js";
+import { createMigrationSchema } from "./schema-api.js";
+function assertStepOption(step) {
+    if (step === undefined) {
+        return;
+    }
+    if (!Number.isInteger(step) || step < 1) {
+        throw new Error('Invalid migration step option. Expected a positive integer.');
+    }
+}
+function assertMigrateOptions(options) {
+    if (options.to !== undefined && options.step !== undefined) {
+        throw new Error('Cannot combine "to" and "step" migration options in the same run');
+    }
+}
+function assertTargetOption(migrations, to) {
+    if (!to) {
+        return;
+    }
+    let target = migrations.find((migration) => migration.id === to);
+    if (!target) {
+        throw new Error('Unknown migration target: ' + to);
+    }
+}
+function assertNoMigrationDrift(migrations, journal) {
+    let migrationMap = new Map(migrations.map((migration) => [migration.id, migration]));
+    for (let row of journal) {
+        let migration = migrationMap.get(row.id);
+        if (!migration) {
+            continue;
+        }
+        let expected = normalizeChecksum(migration);
+        if (expected !== row.checksum) {
+            throw new Error('Migration checksum drift detected for "' +
+                row.id +
+                '" (journal=' +
+                row.checksum +
+                ', current=' +
+                expected +
+                ')');
+        }
+    }
+}
+function createDryRunDatabase(adapter) {
+    let error = new Error('Cannot execute data operations while running migrations with dryRun');
+    let throwDryRunError = async () => {
+        throw error;
+    };
+    let dryRunAdapter = {
+        dialect: adapter.dialect,
+        capabilities: adapter.capabilities,
+        compileSql(operation) {
+            return adapter.compileSql(operation);
+        },
+        async hasTable(table) {
+            return adapter.hasTable(table);
+        },
+        async hasColumn(table, column) {
+            return adapter.hasColumn(table, column);
+        },
+        execute: throwDryRunError,
+        migrate: throwDryRunError,
+        beginTransaction: throwDryRunError,
+        commitTransaction: throwDryRunError,
+        rollbackTransaction: throwDryRunError,
+        createSavepoint: throwDryRunError,
+        rollbackToSavepoint: throwDryRunError,
+        releaseSavepoint: throwDryRunError,
+    };
+    return createDatabase(dryRunAdapter);
+}
+async function runMigrations(input) {
+    let adapter = input.adapter;
+    let migrations = input.migrations;
+    let journalTable = input.journalTable;
+    let dryRun = Boolean(input.options.dryRun);
+    let target = input.options.to;
+    let step = input.options.step;
+    assertMigrateOptions(input.options);
+    assertStepOption(step);
+    assertTargetOption(migrations, target);
+    let sql = [];
+    await adapter.acquireMigrationLock?.();
+    try {
+        let journal = [];
+        if (dryRun) {
+            let canReadJournal = await hasMigrationJournal(adapter, journalTable);
+            if (canReadJournal) {
+                journal = await loadJournalRows(adapter, journalTable);
+            }
+        }
+        else {
+            await ensureMigrationJournal(adapter, journalTable);
+            journal = await loadJournalRows(adapter, journalTable);
+        }
+        let appliedMap = new Map(journal.map((row) => [row.id, row]));
+        assertNoMigrationDrift(migrations, journal);
+        let toRun = [];
+        if (input.direction === 'up') {
+            for (let migration of migrations) {
+                if (!appliedMap.has(migration.id)) {
+                    toRun.push(migration);
+                }
+            }
+            if (target) {
+                toRun = toRun.filter((migration) => migration.id <= target);
+            }
+            if (step !== undefined) {
+                toRun = toRun.slice(0, step);
+            }
+        }
+        else {
+            let appliedMigrations = migrations
+                .filter((migration) => appliedMap.has(migration.id))
+                .reverse();
+            if (target) {
+                appliedMigrations = appliedMigrations.filter((migration) => migration.id >= target);
+            }
+            if (step !== undefined) {
+                appliedMigrations = appliedMigrations.slice(0, step);
+            }
+            toRun = appliedMigrations;
+        }
+        let applied = [];
+        let reverted = [];
+        let batch = getBatch(journal);
+        for (let migration of toRun) {
+            if (migration.migration.transaction === 'required' &&
+                !adapter.capabilities.transactionalDdl) {
+                throw new Error('Migration "' +
+                    migration.id +
+                    '" requires transactional DDL, but adapter does not support it');
+            }
+            let shouldUseTransaction = !dryRun &&
+                migration.migration.transaction !== 'none' &&
+                adapter.capabilities.transactionalDdl;
+            let token;
+            if (shouldUseTransaction) {
+                token = await adapter.beginTransaction();
+            }
+            let db = dryRun
+                ? createDryRunDatabase(adapter)
+                : token
+                    ? createDatabaseWithTransaction(adapter, token)
+                    : createDatabase(adapter);
+            let schema = createMigrationSchema(db, async (operation) => {
+                let compiled = adapter.compileSql(operation);
+                sql.push(...compiled);
+                if (!dryRun) {
+                    await adapter.migrate({ operation, transaction: token });
+                }
+            }, { transaction: token });
+            let context = {
+                db,
+                schema,
+            };
+            try {
+                if (input.direction === 'up') {
+                    await migration.migration.up(context);
+                    if (!dryRun) {
+                        await insertJournalRow(adapter, journalTable, {
+                            id: migration.id,
+                            name: migration.name,
+                            checksum: normalizeChecksum(migration),
+                            batch,
+                        }, token);
+                    }
+                    applied.push({
+                        id: migration.id,
+                        name: migration.name,
+                        status: 'applied',
+                    });
+                }
+                else {
+                    await migration.migration.down(context);
+                    if (!dryRun) {
+                        await deleteJournalRow(adapter, journalTable, migration.id, token);
+                    }
+                    reverted.push({
+                        id: migration.id,
+                        name: migration.name,
+                        status: 'pending',
+                    });
+                }
+                if (token) {
+                    await adapter.commitTransaction(token);
+                }
+            }
+            catch (error) {
+                if (token) {
+                    await adapter.rollbackTransaction(token);
+                }
+                throw error;
+            }
+        }
+        return {
+            applied,
+            reverted,
+            sql,
+        };
+    }
+    finally {
+        await adapter.releaseMigrationLock?.();
+    }
+}
+/**
+ * Creates a migration runner for applying/reverting migrations against an adapter.
+ * @param adapter Database adapter used to compile and execute migration operations.
+ * @param migrations Migration descriptors or registry.
+ * @param options Optional runner configuration.
+ * @returns A migration runner instance.
+ * @example
+ * ```ts
+ * import { createMigrationRunner } from 'remix/data-table/migrations'
+ *
+ * let runner = createMigrationRunner(adapter, migrations, {
+ *   journalTable: 'app_migrations',
+ * })
+ * await runner.up()
+ * ```
+ */
+export function createMigrationRunner(adapter, migrations, options = {}) {
+    let journalTable = options.journalTable ?? 'data_table_migrations';
+    return {
+        async up(runOptions = {}) {
+            return runMigrations({
+                adapter,
+                migrations: resolveMigrations(migrations),
+                journalTable,
+                direction: 'up',
+                options: runOptions,
+            });
+        },
+        async down(runOptions = {}) {
+            return runMigrations({
+                adapter,
+                migrations: resolveMigrations(migrations),
+                journalTable,
+                direction: 'down',
+                options: runOptions,
+            });
+        },
+        async status() {
+            await ensureMigrationJournal(adapter, journalTable);
+            let journal = await loadJournalRows(adapter, journalTable);
+            let journalMap = new Map(journal.map((row) => [row.id, row]));
+            let sortedMigrations = resolveMigrations(migrations);
+            return sortedMigrations.map((migration) => {
+                let journalRow = journalMap.get(migration.id);
+                if (!journalRow) {
+                    return {
+                        id: migration.id,
+                        name: migration.name,
+                        status: 'pending',
+                    };
+                }
+                let checksum = normalizeChecksum(migration);
+                return {
+                    id: migration.id,
+                    name: migration.name,
+                    status: checksum === journalRow.checksum
+                        ? 'applied'
+                        : 'drifted',
+                    appliedAt: journalRow.appliedAt,
+                    batch: journalRow.batch,
+                    checksum: journalRow.checksum,
+                };
+            });
+        },
+    };
+}