@ghom/orm 2.0.0 → 2.1.1

package/dist/app/table.d.ts

@@ -1,16 +1,25 @@
 import { CachedQuery } from "@ghom/query";
 import type { Knex } from "knex";
 import { type ColumnDef, type InferColumns } from "./column.js";
+import type { FinalTableType, TypedMigration, TypedMigrationSequence } from "./migration.js";
 import type { ORM } from "./orm.js";
+/**
+ * A migration value is a TypedMigration or TypedMigrationSequence.
+ * Use migrate.sequence() to combine multiple migrations.
+ */
+export type MigrationValue = TypedMigration<any, any> | TypedMigrationSequence<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 +28,37 @@ 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 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
+     *
+     * @example
+     * // Single migration
+     * migrations: {
+     *   "001_add_email": migrate.addColumn("email", col.string()),
+     * }
+     *
+     * @example
+     * // Multiple migrations in sequence
+     * migrations: {
+     *   "002_add_fields": migrate.sequence(
+     *     migrate.addColumn("phone", col.string()),
+     *     migrate.addColumn("address", col.string().nullable()),
+     *   ),
+     * }
+     *
+     * @example
+     * // Raw migration for advanced use cases
+     * migrations: {
+     *   "003_custom": migrate.raw((builder) => builder.dropColumn("oldField")),
+     * }
+     */
+    migrations?: Migrations;
+    then?: (this: Table<Columns, Migrations>, table: Table<Columns, Migrations>) => unknown;
     /**
      * Typed columns definition with automatic type inference.
      *
@@ -37,7 +73,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 +85,36 @@ 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.
+     * Supports both single migrations and arrays of migrations.
+     */
+    readonly $type: FinalTableType<Columns, Migrations>;
     private requireOrm;
     get client(): Knex;
     get query(): Knex.QueryBuilder<InferColumns<Columns>, {
@@ -82,5 +139,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,109 @@ 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) {
+            // 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
+            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;
+                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.1",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -8,10 +8,9 @@
   "description": "TypeScript KnexJS ORM & handler",
   "homepage": "https://github.com/GhomKrosmonaute/orm",
   "scripts": {
-    "format": "biome format --write src",
-    "lint": "biome lint .",
-    "check": "biome check --write .",
-    "build": "rimraf dist && tsc",
+    "format": "biome format --write .",
+    "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/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)