@ghom/orm 2.0.0 → 2.1.0

package/biome.json

@@ -24,6 +24,9 @@
     "enabled": true,
     "rules": {
       "recommended": true,
+      "complexity": {
+        "noBannedTypes": "off"
+      },
       "suspicious": {
         "noExplicitAny": "off",
         "noThenProperty": "off",
@@ -32,6 +35,10 @@
       "style": {
         "noNonNullAssertion": "off",
         "useNodejsImportProtocol": "off"
+      },
+      "correctness": {
+        "noUnusedVariables": "off",
+        "noUnusedImports": "off"
       }
     }
   },

package/dist/app/migration.d.ts

@@ -0,0 +1,171 @@
+import type { Knex } from "knex";
+import { type ColumnDef, type InferColumns, type InferColumnType } from "./column.js";
+/**
+ * Represents a typed migration that transforms the table schema.
+ * Carries type information about what columns are removed and added.
+ *
+ * @template From - The type of columns being removed/modified
+ * @template To - The type of columns being added/modified
+ */
+export interface TypedMigration<From = {}, To = {}> {
+    /** @internal Type marker for columns being removed */
+    readonly _from: From;
+    /** @internal Type marker for columns being added */
+    readonly _to: To;
+    /**
+     * Apply the migration to the table builder.
+     */
+    apply: (builder: Knex.AlterTableBuilder) => void;
+}
+/**
+ * Extract all "From" keys from a union of TypedMigration.
+ * These are the columns that will be removed/renamed.
+ */
+type ExtractFromKeys<M> = M extends TypedMigration<infer From, any> ? keyof From : never;
+/**
+ * Extract all "To" types from a union of TypedMigration and intersect them.
+ * These are the columns that will be added.
+ */
+type ExtractToTypes<M> = M extends TypedMigration<any, infer To> ? To : 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;
+/**
+ * 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
+ */
+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;
+/**
+ * Compute the final table type from base columns and migrations.
+ */
+export type FinalTableType<Columns extends Record<string, ColumnDef<any, any>>, Migrations extends Record<string, TypedMigration<any, any>> = {}> = ApplyMigrations<InferColumns<Columns>, Migrations>;
+/**
+ * Migration helpers for creating typed migrations.
+ * Each helper returns a TypedMigration with appropriate type transformations.
+ *
+ * @example
+ * ```typescript
+ * import { migrate, col } from "@ghom/orm"
+ *
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     name: col.string(),
+ *   }),
+ *   migrations: {
+ *     "001_rename_name": migrate.renameColumn("name", "username"),
+ *     "002_add_email": migrate.addColumn("email", col.string()),
+ *   },
+ * })
+ * ```
+ */
+export declare const migrate: {
+    /**
+     * Add a new column to the table.
+     *
+     * @param name - The column name
+     * @param column - The column definition
+     * @returns A typed migration that adds the column
+     *
+     * @example
+     * migrate.addColumn("email", col.string())
+     * // Adds: { email: string }
+     */
+    addColumn<K extends string, C extends ColumnDef<any, any>>(name: K, column: C): TypedMigration<{}, { [P in K]: InferColumnType<C>; }>;
+    /**
+     * Drop a column from the table.
+     *
+     * @param name - The column name to drop
+     * @returns A typed migration that removes the column
+     *
+     * @example
+     * migrate.dropColumn("oldField")
+     * // Removes: { oldField: any }
+     */
+    dropColumn<K extends string>(name: K): TypedMigration<{ [P in K]: unknown; }, {}>;
+    /**
+     * Rename a column.
+     *
+     * @param oldName - The current column name
+     * @param newName - The new column name
+     * @returns A typed migration that renames the column
+     *
+     * @example
+     * migrate.renameColumn("name", "username")
+     * // Removes: { name: any }, Adds: { username: any }
+     */
+    renameColumn<Old extends string, New extends string>(oldName: Old, newName: New): TypedMigration<{ [P in Old]: unknown; }, { [P in New]: unknown; }>;
+    /**
+     * Alter a column's type or constraints.
+     *
+     * @param name - The column name
+     * @param column - The new column definition
+     * @returns A typed migration that alters the column
+     *
+     * @example
+     * migrate.alterColumn("age", col.integer().nullable())
+     * // Changes type: { age: number | null }
+     */
+    alterColumn<K extends string, C extends ColumnDef<any, any>>(name: K, column: C): TypedMigration<{ [P in K]: unknown; }, { [P in K]: InferColumnType<C>; }>;
+    /**
+     * Add an index on one or more columns.
+     *
+     * @param columns - Array of column names to index
+     * @param name - Optional index name
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.addIndex(["email"], "idx_email")
+     */
+    addIndex(columns: string[], name?: string): TypedMigration<{}, {}>;
+    /**
+     * Drop an index by name.
+     *
+     * @param name - The index name to drop
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.dropIndex("idx_email")
+     */
+    dropIndex(name: string): TypedMigration<{}, {}>;
+    /**
+     * Add a unique constraint on one or more columns.
+     *
+     * @param columns - Array of column names
+     * @param name - Optional constraint name
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.addUnique(["email"], "uniq_email")
+     */
+    addUnique(columns: string[], name?: string): TypedMigration<{}, {}>;
+    /**
+     * Drop a unique constraint by name.
+     *
+     * @param name - The constraint name to drop
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.dropUnique("uniq_email")
+     */
+    dropUnique(name: string): TypedMigration<{}, {}>;
+    /**
+     * Custom migration with a raw callback.
+     * Use this when the built-in helpers don't cover your use case.
+     *
+     * @param fn - The migration callback
+     * @returns A typed migration (no type change by default)
+     *
+     * @example
+     * migrate.raw((builder) => {
+     *   builder.dropColumn("temp")
+     *   builder.string("new_col")
+     * })
+     */
+    raw<From = {}, To = {}>(fn: (builder: Knex.AlterTableBuilder) => void): TypedMigration<From, To>;
+};
+export {};

package/dist/app/migration.js

@@ -0,0 +1,198 @@
+import { buildColumnsSchema, } from "./column.js";
+/**
+ * Migration helpers for creating typed migrations.
+ * Each helper returns a TypedMigration with appropriate type transformations.
+ *
+ * @example
+ * ```typescript
+ * import { migrate, col } from "@ghom/orm"
+ *
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     name: col.string(),
+ *   }),
+ *   migrations: {
+ *     "001_rename_name": migrate.renameColumn("name", "username"),
+ *     "002_add_email": migrate.addColumn("email", col.string()),
+ *   },
+ * })
+ * ```
+ */
+export const migrate = {
+    /**
+     * Add a new column to the table.
+     *
+     * @param name - The column name
+     * @param column - The column definition
+     * @returns A typed migration that adds the column
+     *
+     * @example
+     * migrate.addColumn("email", col.string())
+     * // Adds: { email: string }
+     */
+    addColumn(name, column) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                buildColumnsSchema(builder, { [name]: column });
+            },
+        };
+    },
+    /**
+     * Drop a column from the table.
+     *
+     * @param name - The column name to drop
+     * @returns A typed migration that removes the column
+     *
+     * @example
+     * migrate.dropColumn("oldField")
+     * // Removes: { oldField: any }
+     */
+    dropColumn(name) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.dropColumn(name);
+            },
+        };
+    },
+    /**
+     * Rename a column.
+     *
+     * @param oldName - The current column name
+     * @param newName - The new column name
+     * @returns A typed migration that renames the column
+     *
+     * @example
+     * migrate.renameColumn("name", "username")
+     * // Removes: { name: any }, Adds: { username: any }
+     */
+    renameColumn(oldName, newName) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.renameColumn(oldName, newName);
+            },
+        };
+    },
+    /**
+     * Alter a column's type or constraints.
+     *
+     * @param name - The column name
+     * @param column - The new column definition
+     * @returns A typed migration that alters the column
+     *
+     * @example
+     * migrate.alterColumn("age", col.integer().nullable())
+     * // Changes type: { age: number | null }
+     */
+    alterColumn(name, column) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.dropColumn(name);
+                buildColumnsSchema(builder, { [name]: column });
+            },
+        };
+    },
+    /**
+     * Add an index on one or more columns.
+     *
+     * @param columns - Array of column names to index
+     * @param name - Optional index name
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.addIndex(["email"], "idx_email")
+     */
+    addIndex(columns, name) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.index(columns, name);
+            },
+        };
+    },
+    /**
+     * Drop an index by name.
+     *
+     * @param name - The index name to drop
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.dropIndex("idx_email")
+     */
+    dropIndex(name) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.dropIndex([], name);
+            },
+        };
+    },
+    /**
+     * Add a unique constraint on one or more columns.
+     *
+     * @param columns - Array of column names
+     * @param name - Optional constraint name
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.addUnique(["email"], "uniq_email")
+     */
+    addUnique(columns, name) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.unique(columns, { indexName: name });
+            },
+        };
+    },
+    /**
+     * Drop a unique constraint by name.
+     *
+     * @param name - The constraint name to drop
+     * @returns A typed migration (no type change)
+     *
+     * @example
+     * migrate.dropUnique("uniq_email")
+     */
+    dropUnique(name) {
+        return {
+            _from: {},
+            _to: {},
+            apply: (builder) => {
+                builder.dropUnique([], name);
+            },
+        };
+    },
+    /**
+     * Custom migration with a raw callback.
+     * Use this when the built-in helpers don't cover your use case.
+     *
+     * @param fn - The migration callback
+     * @returns A typed migration (no type change by default)
+     *
+     * @example
+     * migrate.raw((builder) => {
+     *   builder.dropColumn("temp")
+     *   builder.string("new_col")
+     * })
+     */
+    raw(fn) {
+        return {
+            _from: {},
+            _to: {},
+            apply: fn,
+        };
+    },
+};

package/dist/app/orm.d.ts

@@ -43,6 +43,21 @@ export interface ORMConfig {
      * Default is `Infinity`.
      */
     caching?: number;
+    /**
+     * Configuration for migration behavior.
+     */
+    migrations?: {
+        /**
+         * Force alphabetical sorting for string migration keys instead of insertion order.
+         *
+         * **NOT RECOMMENDED**: If your keys start with numbers (e.g., "001_init", "002_add_users"),
+         * they are automatically sorted by those numbers, not alphabetically.
+         * Prefer insertion order or purely numeric keys instead.
+         *
+         * @default false
+         */
+        alphabeticalOrder?: boolean;
+    };
 }
 /**
  * The main ORM class that manages database connections, tables, and caching.
@@ -85,7 +100,7 @@ export declare class ORM {
      * Returns true if the ORM has a database client connected.
      */
     get isConnected(): boolean;
-    get cachedTables(): Table<any>[];
+    get cachedTables(): Table<any, {}>[];
     get cachedTableNames(): string[];
     hasCachedTable(name: string): boolean;
     hasTable(name: string): Promise<boolean>;
@@ -109,4 +124,9 @@ export declare class ORM {
      * @warning This will delete all the data in the tables.
      */
     restoreBackup(dirname?: string): Promise<void>;
+    /**
+     * Upgrade the migration table from integer version to string version.
+     * This is needed for projects that were using the old migration system.
+     */
+    private upgradeMigrationTableIfNeeded;
 }

package/dist/app/orm.js

@@ -5,6 +5,16 @@ import { default as knex } from "knex";
 import { backupTable, disableForeignKeys, enableForeignKeys, restoreBackup } from "./backup.js";
 import { Table } from "./table.js";
 import { isCJS } from "./util.js";
+/**
+ * Verify that the environment supports ES2015+ object key ordering.
+ * In ES2015+, integer keys are sorted numerically first, then string keys
+ * maintain their insertion order.
+ */
+function checkES2015KeyOrder() {
+    const test = { "2": "a", "1": "b", c: "d" };
+    const keys = Object.keys(test);
+    return keys[0] === "1" && keys[1] === "2" && keys[2] === "c";
+}
 /**
  * The main ORM class that manages database connections, tables, and caching.
  *
@@ -41,6 +51,9 @@ export class ORM {
      */
     constructor(config) {
         this.config = config;
+        if (!checkES2015KeyOrder()) {
+            throw new Error("@ghom/orm requires ES2015+ environment for guaranteed object key ordering");
+        }
         if (config === false)
             return;
         this._client = knex(config.database ?? {
@@ -105,9 +118,11 @@ export class ORM {
             priority: Infinity,
             columns: (col) => ({
                 table: col.string().unique(),
-                version: col.integer(),
+                version: col.string(),
             }),
         }));
+        // Auto-migrate version column from integer to string for existing projects
+        await this.upgradeMigrationTableIfNeeded();
         const sortedTables = this.cachedTables.toSorted((a, b) => (b.options.priority ?? 0) - (a.options.priority ?? 0));
         for (const table of sortedTables) {
             await table.make(this);
@@ -162,4 +177,39 @@ export class ORM {
         });
         console.log("Database restored from backup.");
     }
+    /**
+     * Upgrade the migration table from integer version to string version.
+     * This is needed for projects that were using the old migration system.
+     */
+    async upgradeMigrationTableIfNeeded() {
+        this.requireClient();
+        const hasMigrationTable = await this._client.schema.hasTable("migration");
+        if (!hasMigrationTable)
+            return;
+        const columnInfo = await this._client("migration").columnInfo("version");
+        const columnType = columnInfo?.type ?? "";
+        // Check if version column is integer type (varies by database)
+        const isIntegerType = columnType.includes("int") ||
+            columnType.includes("INT") ||
+            columnType === "integer" ||
+            columnType === "INTEGER";
+        if (!isIntegerType)
+            return;
+        // Migrate: convert integer versions to strings
+        // SQLite doesn't support column alterations well, so we use a temp column approach
+        await this._client.schema.alterTable("migration", (t) => {
+            t.string("version_new");
+        });
+        await this._client("migration").update({
+            version_new: this._client.raw("CAST(version AS TEXT)"),
+        });
+        await this._client.schema.alterTable("migration", (t) => {
+            t.dropColumn("version");
+        });
+        await this._client.schema.alterTable("migration", (t) => {
+            t.renameColumn("version_new", "version");
+        });
+        this.config !== false &&
+            this.config.logger?.log("Upgraded migration table: version column converted to string");
+    }
 }

package/dist/app/table.d.ts

@@ -1,16 +1,24 @@
 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 { ORM } from "./orm.js";
+/**
+ * A migration can be either a callback function or a TypedMigration object.
+ */
+export type MigrationValue = ((builder: Knex.CreateTableBuilder) => void) | TypedMigration<any, any>;
 export interface MigrationData {
     table: string;
-    version: number;
+    version: string;
 }
 /**
- * Table options with typed columns.
- * Type is automatically inferred from the column definitions.
+ * Table options with typed columns and optional typed migrations.
+ * Type is automatically inferred from the column definitions and migrations.
+ *
+ * @template Columns - Record of column definitions
+ * @template Migrations - Record of migration definitions (optional)
  */
-export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>>> {
+export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>>, Migrations extends Record<string, MigrationValue> = {}> {
     name: string;
     description?: string;
     priority?: number;
@@ -19,10 +27,30 @@ export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>
      * Default is `Infinity`.
      */
     caching?: number;
-    migrations?: {
-        [version: number]: (builder: Knex.CreateTableBuilder) => void;
-    };
-    then?: (this: Table<Columns>, table: Table<Columns>) => unknown;
+    /**
+     * Database migrations to apply.
+     *
+     * 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
+     * // Using callbacks
+     * migrations: {
+     *   "1": (builder) => builder.dropColumn("oldField"),
+     * }
+     *
+     * @example
+     * // Using typed migrations
+     * migrations: {
+     *   "001_add_email": migrate.addColumn("email", col.string()),
+     * }
+     */
+    migrations?: Migrations;
+    then?: (this: Table<Columns, Migrations>, table: Table<Columns, Migrations>) => unknown;
     /**
      * Typed columns definition with automatic type inference.
      *
@@ -37,7 +65,7 @@ export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>
     columns: (col: typeof import("./column.js").col) => Columns;
 }
 /**
- * Represents a database table with typed columns.
+ * Represents a database table with typed columns and migrations.
  *
  * @example
  * const userTable = new Table({
@@ -49,15 +77,35 @@ export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>
  *   }),
  * })
  * // Type is automatically inferred as { id: number; username: string; age: number | null }
+ *
+ * @example
+ * // With typed migrations
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     name: col.string(),
+ *   }),
+ *   migrations: {
+ *     "001_rename": migrate.renameColumn("name", "username"),
+ *     "002_add_email": migrate.addColumn("email", col.string()),
+ *   },
+ * })
+ * // Type includes migration transforms: { id: number; username: string; email: string }
  */
-export declare class Table<Columns extends Record<string, ColumnDef<any, any>> = Record<string, ColumnDef<any, any>>> {
-    readonly options: TableOptions<Columns>;
+export declare class Table<Columns extends Record<string, ColumnDef<any, any>> = Record<string, ColumnDef<any, any>>, Migrations extends Record<string, MigrationValue> = {}> {
+    readonly options: TableOptions<Columns, Migrations>;
     orm?: ORM;
-    _whereCache?: CachedQuery<[cb: (query: Table<Columns>["query"]) => unknown], unknown>;
+    _whereCache?: CachedQuery<[
+        cb: (query: Table<Columns, Migrations>["query"]) => unknown
+    ], unknown>;
     _countCache?: CachedQuery<[where: string | null], number>;
-    constructor(options: TableOptions<Columns>);
-    /** The inferred TypeScript type for rows of this table */
-    readonly $type: InferColumns<Columns>;
+    constructor(options: TableOptions<Columns, Migrations>);
+    /**
+     * The inferred TypeScript type for rows of this table.
+     * Includes base columns and all migration type transforms.
+     */
+    readonly $type: Migrations extends Record<string, TypedMigration<any, any>> ? FinalTableType<Columns, Migrations> : InferColumns<Columns>;
     private requireOrm;
     get client(): Knex;
     get query(): Knex.QueryBuilder<InferColumns<Columns>, {
@@ -82,5 +130,17 @@ export declare class Table<Columns extends Record<string, ColumnDef<any, any>> =
     getColumnNames(): Promise<Array<keyof InferColumns<Columns> & string>>;
     isEmpty(): Promise<boolean>;
     make(orm: ORM): Promise<this>;
+    /**
+     * Get sorted migration keys based on their pattern.
+     * - Pure numeric keys ("1", "2", "10") are sorted numerically
+     * - Numeric-prefixed keys ("001_add", "010_rename") are sorted by prefix
+     * - Pure string keys ("add_email", "rename") use insertion order or alphabetical
+     */
+    private getMigrationKeys;
+    /**
+     * Compare migration keys for determining if one is greater than another.
+     * Handles both numeric and string comparisons appropriately.
+     */
+    private compareMigrationKeys;
     private migrate;
 }

package/dist/app/table.js

@@ -2,7 +2,7 @@ import { CachedQuery } from "@ghom/query";
 import { buildColumnsSchema, col } from "./column.js";
 import { styled } from "./util.js";
 /**
- * Represents a database table with typed columns.
+ * Represents a database table with typed columns and migrations.
  *
  * @example
  * const userTable = new Table({
@@ -14,6 +14,21 @@ import { styled } from "./util.js";
  *   }),
  * })
  * // Type is automatically inferred as { id: number; username: string; age: number | null }
+ *
+ * @example
+ * // With typed migrations
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     name: col.string(),
+ *   }),
+ *   migrations: {
+ *     "001_rename": migrate.renameColumn("name", "username"),
+ *     "002_add_email": migrate.addColumn("email", col.string()),
+ *   },
+ * })
+ * // Type includes migration transforms: { id: number; username: string; email: string }
  */
 export class Table {
     options;
@@ -120,27 +135,98 @@ export class Table {
         }
         return this;
     }
+    /**
+     * Get sorted migration keys based on their pattern.
+     * - Pure numeric keys ("1", "2", "10") are sorted numerically
+     * - Numeric-prefixed keys ("001_add", "010_rename") are sorted by prefix
+     * - Pure string keys ("add_email", "rename") use insertion order or alphabetical
+     */
+    getMigrationKeys() {
+        const keys = Object.keys(this.options.migrations ?? {});
+        if (keys.length === 0)
+            return [];
+        // Detect key type patterns
+        const allPureNumeric = keys.every((k) => /^\d+$/.test(k));
+        const allNumericPrefix = keys.every((k) => /^\d+/.test(k));
+        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").`);
+        }
+        if (allPureNumeric) {
+            // Sort purely numeric keys numerically: 1, 2, 10, 20
+            return keys.sort((a, b) => Number(a) - Number(b));
+        }
+        if (allNumericPrefix) {
+            // Sort by numeric prefix: "001_x" < "002_y" < "010_z"
+            const getNumericPrefix = (key) => parseInt(key.match(/^(\d+)/)?.[1] ?? "0", 10);
+            return keys.sort((a, b) => getNumericPrefix(a) - getNumericPrefix(b));
+        }
+        // Pure strings: alphabetical order OR insertion order
+        // Get ORM config if available (and not false for unconnected ORM)
+        const ormConfig = this.orm?.config === false ? undefined : this.orm?.config;
+        if (ormConfig?.migrations?.alphabeticalOrder) {
+            return keys.sort((a, b) => a.localeCompare(b));
+        }
+        // Warning for insertion order (Git merge risks)
+        if (keys.length > 1 && ormConfig) {
+            ormConfig.logger?.warn?.(`Table "${this.options.name}": Using insertion order for string migration keys. ` +
+                `This may cause issues with Git merges. Consider using numeric prefixes (e.g., "001_init").`);
+        }
+        return keys; // Insertion order (ES2015+)
+    }
+    /**
+     * Compare migration keys for determining if one is greater than another.
+     * Handles both numeric and string comparisons appropriately.
+     */
+    compareMigrationKeys(a, b) {
+        const aIsNumeric = /^\d+$/.test(a);
+        const bIsNumeric = /^\d+$/.test(b);
+        if (aIsNumeric && bIsNumeric) {
+            return Number(a) - Number(b);
+        }
+        const aHasPrefix = /^\d+/.test(a);
+        const bHasPrefix = /^\d+/.test(b);
+        if (aHasPrefix && bHasPrefix) {
+            const aPrefix = parseInt(a.match(/^(\d+)/)?.[1] ?? "0", 10);
+            const bPrefix = parseInt(b.match(/^(\d+)/)?.[1] ?? "0", 10);
+            return aPrefix - bPrefix;
+        }
+        return a.localeCompare(b);
+    }
     async migrate() {
         if (!this.options.migrations)
             return false;
-        const migrations = new Map(Object.entries(this.options.migrations)
-            .sort((a, b) => Number(a[0]) - Number(b[0]))
-            .map((entry) => [Number(entry[0]), entry[1]]));
+        const sortedKeys = this.getMigrationKeys();
+        if (sortedKeys.length === 0)
+            return false;
+        const migrations = this.options.migrations;
         const fromDatabase = await this.client("migration")
             .where("table", this.options.name)
             .first();
         const data = fromDatabase || {
             table: this.options.name,
-            version: -Infinity,
+            version: "",
         };
         const baseVersion = data.version;
-        for (const [version, migration] of migrations) {
+        for (const key of sortedKeys) {
+            // Skip migrations that have already been applied
+            if (data.version !== "" && this.compareMigrationKeys(key, data.version) <= 0) {
+                continue;
+            }
+            const migration = migrations[key];
             await this.client.schema.alterTable(this.options.name, (builder) => {
-                if (version <= data.version)
-                    return;
-                migration(builder);
-                data.version = version;
+                if (typeof migration === "function") {
+                    // Callback function migration
+                    migration(builder);
+                }
+                else if (migration && typeof migration === "object" && "apply" in migration) {
+                    // TypedMigration object
+                    migration.apply(builder);
+                }
             });
+            data.version = key;
         }
         await this.client("migration").insert(data).onConflict("table").merge();
         return baseVersion === data.version ? false : data.version;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./app/backup.js";
 export * from "./app/column.js";
+export * from "./app/migration.js";
 export * from "./app/orm.js";
 export * from "./app/table.js";
 export * from "./app/util.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./app/backup.js";
 export * from "./app/column.js";
+export * from "./app/migration.js";
 export * from "./app/orm.js";
 export * from "./app/table.js";
 export * from "./app/util.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghom/orm",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,7 @@
   "description": "TypeScript KnexJS ORM & handler",
   "homepage": "https://github.com/GhomKrosmonaute/orm",
   "scripts": {
-    "format": "biome format --write src",
-    "lint": "biome lint .",
+    "format": "biome format --write .",
     "check": "biome check --write .",
     "build": "rimraf dist && tsc",
     "test": "bun test",

package/readme.md

@@ -62,46 +62,117 @@ orm.raw("SELECT 1") // throws Error
 
 ## Add tables
 
-The tables are automatically loaded from the `location` directory.
+The tables are automatically loaded from the `tableLocation` directory. Types are automatically inferred from the column definitions.
 
 ```typescript
 // tables/user.ts
 
-import { Table } from "@ghom/orm"
+import { Table, col } from "@ghom/orm"
 
-interface User {
-  username: string
-  password: string
-}
-
-export default new Table<User>({
+export default new Table({
   name: "user",
   
   // the higher the priority, the earlier the table is compiled
   priority: 0,
   
-  // the migration are executed in order of version number
+  // typed columns definition with automatic type inference
+  columns: (col) => ({
+    id: col.increments(),
+    username: col.string().unique(),
+    password: col.string(),
+    age: col.integer().nullable(),
+    role: col.enum(["admin", "user"]).defaultTo("user"),
+  }),
+  
+  // migrations are executed in order based on key pattern (see Migration Keys section)
   migrations: {
-    1: (table) => {
+    "1": (table) => {
       table.renameColumn("name", "username")
     }
   },
   
-  // the setup is executed only once for table creation
-  setup: (table) => {
-    table.string("name").notNullable()
-    table.string("password").notNullable()
-  },
-  
-  // the then is executed after the table is created and the migrations are runned
+  // then is executed after the table is created and the migrations are run (only if table is empty)
   then: ({ query }) => {
-    query.insert({ username: "admin", password: "admin" })
+    query.insert({ username: "admin", password: "admin", role: "admin" })
   },
   
   caching: 10 * 60 * 1000 // The table cache. Default to the ORM cache or Infinity
 })
+
+// Type is automatically inferred:
+// { id: number; username: string; password: string; age: number | null; role: "admin" | "user" }
+type User = typeof userTable.$type
+```
+
+### Typed Migrations
+
+You can also use typed migrations that automatically update the TypeScript type:
+
+```typescript
+import { Table, col, migrate } from "@ghom/orm"
+
+export default new Table({
+  name: "user",
+  columns: (col) => ({
+    id: col.increments(),
+    name: col.string(),  // will be renamed to username
+  }),
+  migrations: {
+    "001_rename_name": migrate.renameColumn("name", "username"),
+    "002_add_email": migrate.addColumn("email", col.string()),
+    "003_add_age": migrate.addColumn("age", col.integer().nullable()),
+  },
+})
+
+// Final type: { id: number; username: string; email: string; age: number | null }
+```
+
+Available migration helpers:
+- `migrate.addColumn(name, columnDef)` - Add a new column
+- `migrate.dropColumn(name)` - Remove a column
+- `migrate.renameColumn(oldName, newName)` - Rename a column
+- `migrate.alterColumn(name, newColumnDef)` - Change column type/constraints
+- `migrate.addIndex(columns, name?)` - Add an index
+- `migrate.dropIndex(name)` - Remove an index
+- `migrate.addUnique(columns, name?)` - Add a unique constraint
+- `migrate.dropUnique(name)` - Remove a unique constraint
+- `migrate.raw(callback)` - Custom migration callback
+
+## Migration Keys
+
+The ORM supports three patterns for migration keys:
+
+1. **Numeric keys** (`"1"`, `"2"`, `"10"`): Sorted numerically
+2. **Numeric-prefixed keys** (`"001_init"`, `"002_add_users"`, `"010_fix"`): Sorted by numeric prefix
+3. **Pure string keys** (`"init"`, `"add_users"`): Uses insertion order (ES2015+)
+
+> **Warning**: Mixing key patterns is not allowed and will throw an error at runtime.
+
+### Migration Configuration
+
+```typescript
+const orm = new ORM({
+  tableLocation: "./tables",
+  migrations: {
+    /**
+     * NOT RECOMMENDED
+     * Force alphabetical sorting for string migration keys.
+     * 
+     * If your keys start with numbers (e.g., "001_init"), 
+     * they are automatically sorted by those numbers, 
+     * not alphabetically.
+     */
+    alphabeticalOrder: false // default
+  }
+})
 ```
 
+### ES2015+ Requirement
+
+This ORM requires ES2015+ for guaranteed object key insertion order. Node.js 6+ and all modern browsers are supported.
+
+The ORM performs a runtime check on initialization and will throw an error if the environment doesn't support ES2015+ key ordering.
+
 ## Launch a query
 
 For more information about the query builder, see [knexjs.org](https://knexjs.org/).  
@@ -192,8 +263,9 @@ The cache of the `<ORM>.cache.raw` method is automatically invalidated when the
 
 - [x] Add timed caching system
 - [x] Add backup option
+- [x] Auto typings for tables from the column definitions
+- [x] Typed migrations with automatic type inference
 - [ ] Dependency management between tables
-- [ ] Auto typings for tables from the column definitions
 - [ ] Add specific methods for relations and joins
 - [ ] Add admin panel
 - [ ] Make possible to switch the data between all possible clients (pg, mysql, sqlite3)

package/tests/orm.test.ts

@@ -3,7 +3,7 @@ import fs from "fs"
 import path from "path"
 import { rimraf } from "rimraf"
 
-import { col, ORM, type ORMConfig, Table } from "../src"
+import { col, migrate, ORM, type ORMConfig, Table } from "../src"
 
 import a from "./tables/a"
 import b from "./tables/b"
@@ -57,6 +57,149 @@ describe("typed columns", () => {
   })
 })
 
+describe("typed migrations", () => {
+  test("migrate.addColumn creates TypedMigration", () => {
+    const migration = migrate.addColumn("email", col.string())
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+    expect("_from" in migration).toBe(true)
+    expect("_to" in migration).toBe(true)
+  })
+
+  test("migrate.dropColumn creates TypedMigration", () => {
+    const migration = migrate.dropColumn("oldField")
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+  })
+
+  test("migrate.renameColumn creates TypedMigration", () => {
+    const migration = migrate.renameColumn("name", "username")
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+  })
+
+  test("migrate.alterColumn creates TypedMigration", () => {
+    const migration = migrate.alterColumn("age", col.integer().nullable())
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+  })
+
+  test("migrate.addIndex creates TypedMigration", () => {
+    const migration = migrate.addIndex(["email"], "idx_email")
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+  })
+
+  test("migrate.addUnique creates TypedMigration", () => {
+    const migration = migrate.addUnique(["email"], "uniq_email")
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+  })
+
+  test("migrate.raw creates TypedMigration", () => {
+    const migration = migrate.raw((builder) => {
+      builder.dropColumn("temp")
+    })
+
+    expect(migration).toBeDefined()
+    expect(migration.apply).toBeInstanceOf(Function)
+  })
+
+  test("Table with typed migrations has correct options", () => {
+    const userTable = new Table({
+      name: "test_typed_migrations",
+      columns: (col) => ({
+        id: col.increments(),
+        name: col.string(),
+      }),
+      migrations: {
+        "001_add_email": migrate.addColumn("email", col.string()),
+        "002_add_age": migrate.addColumn("age", col.integer().nullable()),
+        "003_rename_name": migrate.renameColumn("name", "username"),
+      },
+    })
+
+    expect(userTable).toBeInstanceOf(Table)
+    expect(userTable.options.migrations).toBeDefined()
+    expect(Object.keys(userTable.options.migrations!).length).toBe(3)
+
+    // Type inference check - final type includes base columns + migrations
+    // "name" is removed by renameColumn, "username" is added
+    type ExpectedType = typeof userTable.$type
+    const _typeCheck: ExpectedType = {
+      id: 1,
+      username: "test", // renamed from "name"
+      // @ts-expect-error - name is removed by renameColumn
+      name: "test",
+      email: "test@example.com",
+      age: null,
+    }
+  })
+})
+
+describe("migration key patterns", () => {
+  test("Table accepts pure numeric keys", () => {
+    const table = new Table({
+      name: "test_numeric_keys",
+      columns: (col) => ({
+        id: col.increments(),
+      }),
+      migrations: {
+        "1": (_builder) => {},
+        "2": (_builder) => {},
+        "10": (_builder) => {},
+      },
+    })
+
+    expect(table.options.migrations).toBeDefined()
+    expect(Object.keys(table.options.migrations!)).toEqual(["1", "2", "10"])
+  })
+
+  test("Table accepts numeric-prefixed keys", () => {
+    const table = new Table({
+      name: "test_prefixed_keys",
+      columns: (col) => ({
+        id: col.increments(),
+      }),
+      migrations: {
+        "001_init": (_builder) => {},
+        "002_add_column": (_builder) => {},
+        "010_fix": (_builder) => {},
+      },
+    })
+
+    expect(table.options.migrations).toBeDefined()
+    expect(Object.keys(table.options.migrations!)).toEqual([
+      "001_init",
+      "002_add_column",
+      "010_fix",
+    ])
+  })
+
+  test("Table accepts pure string keys", () => {
+    const table = new Table({
+      name: "test_string_keys",
+      columns: (col) => ({
+        id: col.increments(),
+      }),
+      migrations: {
+        init: (_builder) => {},
+        add_column: (_builder) => {},
+        fix: (_builder) => {},
+      },
+    })
+
+    expect(table.options.migrations).toBeDefined()
+    expect(Object.keys(table.options.migrations!)).toEqual(["init", "add_column", "fix"])
+  })
+})
+
 describe("unconnected ORM", () => {
   test("can be initialized with false", () => {
     const unconnectedOrm = new ORM(false)

package/tests/tables/d.ts

@@ -1,9 +1,5 @@
 import { Table } from "../../src"
 
-/**
- * Table using the new typed columns system.
- * Type is automatically inferred from the column definitions.
- */
 export default new Table({
   name: "d",
   priority: 0,