@ghom/orm 2.1.0 → 2.1.1

package/dist/app/migration.d.ts

@@ -17,31 +17,98 @@ export interface TypedMigration<From = {}, To = {}> {
      */
     apply: (builder: Knex.AlterTableBuilder) => void;
 }
+/**
+ * Represents a sequence of typed migrations.
+ * Used internally by migrate.sequence() to preserve individual migration types.
+ *
+ * @template Migrations - Tuple of migrations in the sequence
+ */
+export interface TypedMigrationSequence<Migrations extends TypedMigration<any, any>[]> {
+    /** @internal The individual migrations in the sequence */
+    readonly __migrations__: Migrations;
+    /** @internal Type marker for columns being removed (computed from sequence) */
+    readonly _from: SequenceFromType<Migrations>;
+    /** @internal Type marker for columns being added (computed from sequence) */
+    readonly _to: SequenceToType<Migrations>;
+    /**
+     * Apply all migrations in sequence to the table builder.
+     */
+    apply: (builder: Knex.AlterTableBuilder) => void;
+}
+/**
+ * Unwrap a migration array to get the individual migration types.
+ * If M is an array, extracts the element type; otherwise returns M as-is.
+ */
+type UnwrapMigrationArray<M> = M extends readonly (infer U)[] ? U : M;
+/**
+ * Extract "From" keys from a single TypedMigration or TypedMigrationSequence.
+ * For sequences, excludes intermediate columns (those that are also in _to).
+ */
+type ExtractFromKeysSingle<M> = M extends {
+    __migrations__: infer Migrations;
+} ? Migrations extends TypedMigration<any, any>[] ? Exclude<keyof UnionToIntersection<Migrations[number]["_from"]>, keyof UnionToIntersection<Migrations[number]["_to"]>> : never : M extends TypedMigration<infer From, any> ? keyof From : never;
 /**
  * Extract all "From" keys from a union of TypedMigration.
  * These are the columns that will be removed/renamed.
+ * Handles both single migrations and arrays of migrations.
+ * Uses distributive conditional types to handle unions correctly.
  */
-type ExtractFromKeys<M> = M extends TypedMigration<infer From, any> ? keyof From : never;
+type ExtractFromKeys<M> = M extends any ? UnwrapMigrationArray<M> extends infer U ? U extends any ? ExtractFromKeysSingle<U> : never : never : never;
+/**
+ * Extract "To" type from a single TypedMigration or TypedMigrationSequence.
+ * For sequences, excludes intermediate columns (those that are also in _from).
+ */
+type ExtractToTypesSingle<M> = M extends {
+    __migrations__: infer Migrations;
+} ? Migrations extends TypedMigration<any, any>[] ? Omit<UnionToIntersection<Migrations[number]["_to"]>, keyof UnionToIntersection<Migrations[number]["_from"]>> : never : M extends TypedMigration<any, infer To> ? To : never;
 /**
  * Extract all "To" types from a union of TypedMigration and intersect them.
  * These are the columns that will be added.
+ * Handles both single migrations and arrays of migrations.
+ * Uses distributive conditional types to handle unions correctly.
  */
-type ExtractToTypes<M> = M extends TypedMigration<any, infer To> ? To : never;
+type ExtractToTypes<M> = M extends any ? UnwrapMigrationArray<M> extends infer U ? U extends any ? ExtractToTypesSingle<U> : never : never : never;
 /**
  * Convert a union to an intersection.
  * Used to combine all "To" types from migrations.
  */
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Force TypeScript to evaluate a type (expands type aliases).
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Combine all "from" types from a tuple of migrations.
+ */
+type CombineFromTypes<T extends TypedMigration<any, any>[]> = UnionToIntersection<T[number]["_from"]>;
+/**
+ * Combine all "to" types from a tuple of migrations.
+ */
+type CombineToTypes<T extends TypedMigration<any, any>[]> = UnionToIntersection<T[number]["_to"]>;
+/**
+ * Compute the final "from" type for a sequence of migrations.
+ * Excludes columns that are also added (intermediate renames).
+ */
+type SequenceFromType<T extends TypedMigration<any, any>[]> = Simplify<Omit<CombineFromTypes<T>, keyof CombineToTypes<T>>>;
+/**
+ * Compute the final "to" type for a sequence of migrations.
+ * Excludes columns that are also removed (intermediate renames).
+ */
+type SequenceToType<T extends TypedMigration<any, any>[]> = Simplify<Omit<CombineToTypes<T>, keyof CombineFromTypes<T>>>;
 /**
  * Apply all migrations to compute the final type.
  * 1. Remove all columns specified in migration "From" types
  * 2. Add all columns specified in migration "To" types
+ * Handles both single migrations and arrays of migrations.
  */
-export type ApplyMigrations<Base, Migrations extends Record<string, TypedMigration<any, any>>> = Migrations[keyof Migrations] extends infer M ? Omit<Base, ExtractFromKeys<M>> & UnionToIntersection<ExtractToTypes<M>> : Base;
+export type ApplyMigrations<Base, Migrations extends Record<string, any>> = Migrations[keyof Migrations] extends infer M ? Omit<Base, ExtractFromKeys<M>> & UnionToIntersection<ExtractToTypes<M>> : Base;
 /**
  * Compute the final table type from base columns and migrations.
+ * Supports both single migrations and arrays of migrations.
  */
-export type FinalTableType<Columns extends Record<string, ColumnDef<any, any>>, Migrations extends Record<string, TypedMigration<any, any>> = {}> = ApplyMigrations<InferColumns<Columns>, Migrations>;
+export type FinalTableType<Columns extends Record<string, ColumnDef<any, any>>, Migrations extends Record<string, any> = {}> = ApplyMigrations<InferColumns<Columns>, Migrations>;
 /**
  * Migration helpers for creating typed migrations.
  * Each helper returns a TypedMigration with appropriate type transformations.
@@ -167,5 +234,25 @@ export declare const migrate: {
      * })
      */
     raw<From = {}, To = {}>(fn: (builder: Knex.AlterTableBuilder) => void): TypedMigration<From, To>;
+    /**
+     * Combine multiple migrations into a single migration.
+     * All migrations are applied sequentially within the same alter table call.
+     * Type information from all migrations is preserved and combined.
+     *
+     * Intermediate columns (added then removed in the sequence) are excluded from the final type.
+     * For example: renameColumn("a", "b") + renameColumn("b", "c") results in only "c" being added.
+     *
+     * @param migrations - The migrations to combine
+     * @returns A typed migration sequence combining all type transformations
+     *
+     * @example
+     * migrate.sequence(
+     *   migrate.addColumn("phone", col.string()),
+     *   migrate.addColumn("address", col.string().nullable()),
+     *   migrate.addIndex(["phone"]),
+     * )
+     * // Combines: removes nothing, adds { phone: string; address: string | null }
+     */
+    sequence<T extends TypedMigration<any, any>[]>(...migrations: T): TypedMigrationSequence<T>;
 };
 export {};

package/dist/app/migration.js

@@ -195,4 +195,35 @@ export const migrate = {
             apply: fn,
         };
     },
+    /**
+     * Combine multiple migrations into a single migration.
+     * All migrations are applied sequentially within the same alter table call.
+     * Type information from all migrations is preserved and combined.
+     *
+     * Intermediate columns (added then removed in the sequence) are excluded from the final type.
+     * For example: renameColumn("a", "b") + renameColumn("b", "c") results in only "c" being added.
+     *
+     * @param migrations - The migrations to combine
+     * @returns A typed migration sequence combining all type transformations
+     *
+     * @example
+     * migrate.sequence(
+     *   migrate.addColumn("phone", col.string()),
+     *   migrate.addColumn("address", col.string().nullable()),
+     *   migrate.addIndex(["phone"]),
+     * )
+     * // Combines: removes nothing, adds { phone: string; address: string | null }
+     */
+    sequence(...migrations) {
+        return {
+            __migrations__: migrations,
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                for (const migration of migrations) {
+                    migration.apply(builder);
+                }
+            },
+        };
+    },
 };

package/dist/app/table.d.ts

@@ -1,12 +1,13 @@
 import { CachedQuery } from "@ghom/query";
 import type { Knex } from "knex";
 import { type ColumnDef, type InferColumns } from "./column.js";
-import type { FinalTableType, TypedMigration } from "./migration.js";
+import type { FinalTableType, TypedMigration, TypedMigrationSequence } from "./migration.js";
 import type { ORM } from "./orm.js";
 /**
- * A migration can be either a callback function or a TypedMigration object.
+ * A migration value is a TypedMigration or TypedMigrationSequence.
+ * Use migrate.sequence() to combine multiple migrations.
  */
-export type MigrationValue = ((builder: Knex.CreateTableBuilder) => void) | TypedMigration<any, any>;
+export type MigrationValue = TypedMigration<any, any> | TypedMigrationSequence<any>;
 export interface MigrationData {
     table: string;
     version: string;
@@ -28,25 +29,32 @@ export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>
      */
     caching?: number;
     /**
-     * Database migrations to apply.
+     * Database migrations to apply using typed migrations.
      *
      * Supports three key patterns:
      * - **Numeric keys** (`"1"`, `"2"`): Sorted numerically
      * - **Numeric-prefixed keys** (`"001_init"`, `"002_add"`): Sorted by prefix
      * - **Pure string keys** (`"init"`, `"add"`): Uses insertion order
      *
-     * Can use either callback functions or TypedMigration objects.
+     * @example
+     * // Single migration
+     * migrations: {
+     *   "001_add_email": migrate.addColumn("email", col.string()),
+     * }
      *
      * @example
-     * // Using callbacks
+     * // Multiple migrations in sequence
      * migrations: {
-     *   "1": (builder) => builder.dropColumn("oldField"),
+     *   "002_add_fields": migrate.sequence(
+     *     migrate.addColumn("phone", col.string()),
+     *     migrate.addColumn("address", col.string().nullable()),
+     *   ),
      * }
      *
      * @example
-     * // Using typed migrations
+     * // Raw migration for advanced use cases
      * migrations: {
-     *   "001_add_email": migrate.addColumn("email", col.string()),
+     *   "003_custom": migrate.raw((builder) => builder.dropColumn("oldField")),
      * }
      */
     migrations?: Migrations;
@@ -104,8 +112,9 @@ export declare class Table<Columns extends Record<string, ColumnDef<any, any>> =
     /**
      * The inferred TypeScript type for rows of this table.
      * Includes base columns and all migration type transforms.
+     * Supports both single migrations and arrays of migrations.
      */
-    readonly $type: Migrations extends Record<string, TypedMigration<any, any>> ? FinalTableType<Columns, Migrations> : InferColumns<Columns>;
+    readonly $type: FinalTableType<Columns, Migrations>;
     private requireOrm;
     get client(): Knex;
     get query(): Knex.QueryBuilder<InferColumns<Columns>, {

package/dist/app/table.js

@@ -151,8 +151,26 @@ export class Table {
         const allPureString = keys.every((k) => !/^\d/.test(k));
         // Validate: no mixing allowed
         if (!allPureNumeric && !allNumericPrefix && !allPureString) {
-            throw new Error(`Table "${this.options.name}": Cannot mix migration key patterns. ` +
-                `Use one of: pure numbers (1, 2), prefixed strings ("001_x", "002_y"), or pure strings ("add_x").`);
+            // Categorize keys for helpful error message
+            const numericKeys = keys.filter((k) => /^\d+$/.test(k));
+            const prefixedKeys = keys.filter((k) => /^\d+[_\-a-zA-Z]/.test(k));
+            const stringKeys = keys.filter((k) => !/^\d/.test(k));
+            const parts = [];
+            if (numericKeys.length > 0) {
+                parts.push(`numeric keys: ${numericKeys.map((k) => `"${k}"`).join(", ")}`);
+            }
+            if (prefixedKeys.length > 0) {
+                parts.push(`prefixed keys: ${prefixedKeys.map((k) => `"${k}"`).join(", ")}`);
+            }
+            if (stringKeys.length > 0) {
+                parts.push(`string keys: ${stringKeys.map((k) => `"${k}"`).join(", ")}`);
+            }
+            throw new Error(`Table "${this.options.name}": Migration keys use mixed patterns which prevents reliable ordering.\n\n` +
+                `Found: ${parts.join(" AND ")}\n\n` +
+                `Choose ONE pattern for all keys:\n` +
+                `  - Pure numbers: "1", "2", "10" (sorted numerically)\n` +
+                `  - Prefixed strings: "001_init", "002_add" (sorted by prefix)\n` +
+                `  - Pure strings: "init", "add_email" (insertion order)`);
         }
         if (allPureNumeric) {
             // Sort purely numeric keys numerically: 1, 2, 10, 20
@@ -217,14 +235,7 @@ export class Table {
             }
             const migration = migrations[key];
             await this.client.schema.alterTable(this.options.name, (builder) => {
-                if (typeof migration === "function") {
-                    // Callback function migration
-                    migration(builder);
-                }
-                else if (migration && typeof migration === "object" && "apply" in migration) {
-                    // TypedMigration object
-                    migration.apply(builder);
-                }
+                migration.apply(builder);
             });
             data.version = key;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghom/orm",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -9,8 +9,8 @@
   "homepage": "https://github.com/GhomKrosmonaute/orm",
   "scripts": {
     "format": "biome format --write .",
-    "check": "biome check --write .",
-    "build": "rimraf dist && tsc",
+    "check": "biome check --write . && tsc --noEmit",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
     "test": "bun test",
     "prepublishOnly": "npm run check && npm run build && npm test"
   },

package/tests/orm.test.ts

@@ -141,6 +141,94 @@ describe("typed migrations", () => {
       age: null,
     }
   })
+
+  test("Table accepts migrate.sequence for multiple typed migrations", () => {
+    const userTable = new Table({
+      name: "test_sequence_migrations",
+      columns: (col) => ({
+        id: col.increments(),
+        name: col.string(),
+      }),
+      migrations: {
+        "001_multiple_changes": migrate.sequence(
+          migrate.addColumn("phone", col.string()),
+          migrate.addColumn("address", col.string().nullable()),
+          migrate.addIndex(["phone"], "idx_phone"),
+          migrate.renameColumn("name", "username"),
+          migrate.renameColumn("username", "fullname"),
+        ),
+      },
+    })
+
+    expect(userTable).toBeInstanceOf(Table)
+    expect(userTable.options.migrations).toBeDefined()
+    expect(Object.keys(userTable.options.migrations!).length).toBe(1)
+
+    // Type inference check - sequence migrations should infer types correctly
+    type ExpectedType = typeof userTable.$type
+    const _typeCheck: ExpectedType = {
+      id: 1,
+      // @ts-expect-error - name is removed by renameColumn
+      name: "test",
+      // @ts-expect-error - username is removed by renameColumn
+      username: "test",
+      fullname: "test",
+      phone: "123456789",
+      address: null,
+    }
+  })
+
+  test("Table accepts mixed single and sequence migrations", () => {
+    const userTable = new Table({
+      name: "test_mixed_migrations",
+      columns: (col) => ({
+        id: col.increments(),
+        name: col.string(),
+      }),
+      migrations: {
+        "001_add_email": migrate.addColumn("email", col.string()),
+        "002_multiple_changes": migrate.sequence(
+          migrate.addColumn("phone", col.string()),
+          migrate.addColumn("age", col.integer().nullable()),
+        ),
+        "003_add_active": migrate.addColumn("isActive", col.boolean().defaultTo(true)),
+      },
+    })
+
+    expect(userTable).toBeInstanceOf(Table)
+    expect(userTable.options.migrations).toBeDefined()
+    expect(Object.keys(userTable.options.migrations!).length).toBe(3)
+
+    // Type inference check - mixed migrations should infer all types
+    type ExpectedType = typeof userTable.$type
+    const _typeCheck: ExpectedType = {
+      id: 1,
+      name: "test",
+      email: "test@example.com",
+      phone: "123456789",
+      age: null,
+      isActive: true,
+    }
+  })
+
+  test("Table accepts migrate.sequence with raw migrations", () => {
+    const table = new Table({
+      name: "test_sequence_raw_migrations",
+      columns: (col) => ({
+        id: col.increments(),
+      }),
+      migrations: {
+        "001_multiple_raw": migrate.sequence(
+          migrate.raw((builder) => builder.string("field1")),
+          migrate.raw((builder) => builder.integer("field2")),
+        ),
+      },
+    })
+
+    expect(table).toBeInstanceOf(Table)
+    expect(table.options.migrations).toBeDefined()
+    expect(table.options.migrations!["001_multiple_raw"]).toBeDefined()
+  })
 })
 
 describe("migration key patterns", () => {
@@ -151,9 +239,9 @@ describe("migration key patterns", () => {
         id: col.increments(),
       }),
       migrations: {
-        "1": (_builder) => {},
-        "2": (_builder) => {},
-        "10": (_builder) => {},
+        1: migrate.raw(() => {}),
+        2: migrate.raw(() => {}),
+        10: migrate.raw(() => {}),
       },
     })
 
@@ -168,9 +256,9 @@ describe("migration key patterns", () => {
         id: col.increments(),
       }),
       migrations: {
-        "001_init": (_builder) => {},
-        "002_add_column": (_builder) => {},
-        "010_fix": (_builder) => {},
+        "001_init": migrate.raw(() => {}),
+        "002_add_column": migrate.raw(() => {}),
+        "010_fix": migrate.raw(() => {}),
       },
     })
 
@@ -189,15 +277,36 @@ describe("migration key patterns", () => {
         id: col.increments(),
       }),
       migrations: {
-        init: (_builder) => {},
-        add_column: (_builder) => {},
-        fix: (_builder) => {},
+        init: migrate.raw(() => {}),
+        add_column: migrate.raw(() => {}),
+        fix: migrate.raw(() => {}),
       },
     })
 
     expect(table.options.migrations).toBeDefined()
     expect(Object.keys(table.options.migrations!)).toEqual(["init", "add_column", "fix"])
   })
+
+  test("Table rejects mixed key patterns at migration time", () => {
+    const table = new Table({
+      name: "test_mixed_keys",
+      columns: (col) => ({
+        id: col.increments(),
+      }),
+      migrations: {
+        1: migrate.raw(() => {}),
+        "001_init": migrate.raw(() => {}),
+        init: migrate.raw(() => {}),
+      },
+    })
+
+    // The error is thrown when getMigrationKeys() is called during migration
+    // This happens during make(), not during construction
+    expect(() => {
+      // Access private method to test key validation
+      ;(table as any).getMigrationKeys()
+    }).toThrow(/Migration keys use mixed patterns/)
+  })
 })
 
 describe("unconnected ORM", () => {

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["tests/**/*"]
+}

package/tsconfig.json

@@ -1,7 +1,6 @@
 {
   "compilerOptions": {
     "strict": true,
-    "rootDir": "src",
     "outDir": "dist",
     "module": "NodeNext",
     "target": "ESNext",
@@ -12,5 +11,6 @@
     "skipLibCheck": true,
     "typeRoots": ["./node_modules/@types", "./dist/typings"]
   },
-  "include": ["src/**/*", "dist/typings/**/*"]
+  "include": ["src/**/*", "dist/typings/**/*"],
+  "exclude": ["tests/**/*"]
 }