@ghom/orm 2.0.0 → 2.1.1

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,258 @@
+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;
+}
+/**
+ * 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 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 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, 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, 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>;
+    /**
+     * 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

@@ -0,0 +1,229 @@
+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,
+        };
+    },
+    /**
+     * 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/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");
+    }
 }