@ghom/orm 1.10.0 → 2.1.0

package/dist/app/table.d.ts

@@ -1,11 +1,24 @@
-import { Knex } from "knex";
-import { ORM } from "./orm.js";
 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;
 }
-export interface TableOptions<Type extends object = object> {
+/**
+ * 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>>, Migrations extends Record<string, MigrationValue> = {}> {
     name: string;
     description?: string;
     priority?: number;
@@ -14,24 +27,89 @@ export interface TableOptions<Type extends object = object> {
      * Default is `Infinity`.
      */
     caching?: number;
-    migrations?: {
-        [version: number]: (table: Knex.CreateTableBuilder) => void;
-    };
-    then?: (this: Table<Type>, table: Table<Type>) => unknown;
-    setup: (table: Knex.CreateTableBuilder) => void;
+    /**
+     * 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.
+     *
+     * @example
+     * columns: (col) => ({
+     *   id: col.increments(),
+     *   username: col.string().unique(),
+     *   age: col.integer().nullable(),
+     *   role: col.enum(["admin", "user"]),
+     * })
+     */
+    columns: (col: typeof import("./column.js").col) => Columns;
 }
-export declare class Table<Type extends object = object> {
-    readonly options: TableOptions<Type>;
+/**
+ * Represents a database table with typed columns and migrations.
+ *
+ * @example
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     username: col.string().unique(),
+ *     age: col.integer().nullable(),
+ *   }),
+ * })
+ * // 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>>, Migrations extends Record<string, MigrationValue> = {}> {
+    readonly options: TableOptions<Columns, Migrations>;
     orm?: ORM;
     _whereCache?: CachedQuery<[
-        cb: (query: Table<Type>["query"]) => unknown
+        cb: (query: Table<Columns, Migrations>["query"]) => unknown
     ], unknown>;
     _countCache?: CachedQuery<[where: string | null], number>;
-    constructor(options: TableOptions<Type>);
+    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 db(): Knex;
-    get query(): Knex.QueryBuilder<Type, {
-        _base: Type;
+    get client(): Knex;
+    get query(): Knex.QueryBuilder<InferColumns<Columns>, {
+        _base: InferColumns<Columns>;
         _hasSelection: false;
         _keys: never;
         _aliases: {};
@@ -40,17 +118,29 @@ export declare class Table<Type extends object = object> {
         _unionProps: never;
     }[]>;
     get cache(): {
-        get: <Return>(id: string, cb: (table: Pick<Table<Type>["query"], "select" | "count" | "avg" | "sum" | "countDistinct" | "avgDistinct" | "sumDistinct">) => Return) => Return;
-        set: <Return>(cb: (table: Pick<Table<Type>["query"], "update" | "delete" | "insert" | "upsert" | "truncate" | "jsonInsert">) => Return) => Return;
+        get: <Return>(id: string, cb: (table: Pick<Table<Columns>["query"], "select" | "count" | "avg" | "sum" | "countDistinct" | "avgDistinct" | "sumDistinct">) => Return) => Return;
+        set: <Return>(cb: (table: Pick<Table<Columns>["query"], "update" | "delete" | "insert" | "upsert" | "truncate" | "jsonInsert">) => Return) => Return;
         count: (where?: string) => Promise<number>;
         invalidate: () => void;
     };
     count(where?: string): Promise<number>;
-    hasColumn(name: keyof Type & string): Promise<boolean>;
-    getColumn(name: keyof Type & string): Promise<Knex.ColumnInfo>;
-    getColumns(): Promise<Record<keyof Type & string, Knex.ColumnInfo>>;
-    getColumnNames(): Promise<Array<keyof Type & string>>;
+    hasColumn(name: keyof InferColumns<Columns> & string): Promise<boolean>;
+    getColumn(name: keyof InferColumns<Columns> & string): Promise<Knex.ColumnInfo>;
+    getColumns(): Promise<Record<keyof InferColumns<Columns> & string, Knex.ColumnInfo>>;
+    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

@@ -1,5 +1,35 @@
-import { styled } from "./util.js";
 import { CachedQuery } from "@ghom/query";
+import { buildColumnsSchema, col } from "./column.js";
+import { styled } from "./util.js";
+/**
+ * Represents a database table with typed columns and migrations.
+ *
+ * @example
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     username: col.string().unique(),
+ *     age: col.integer().nullable(),
+ *   }),
+ * })
+ * // 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;
     orm;
@@ -11,15 +41,15 @@ export class Table {
     requireOrm() {
         if (!this.orm)
             throw new Error("missing ORM");
-        if (!this.orm.client)
+        if (!this.orm._client)
             throw new Error("ORM client is not initialized");
     }
-    get db() {
+    get client() {
         this.requireOrm();
         return this.orm.client;
     }
     get query() {
-        return this.db(this.options.name);
+        return this.client(this.options.name);
     }
     get cache() {
         if (!this._whereCache || !this._countCache)
@@ -46,18 +76,18 @@ export class Table {
     }
     async count(where) {
         return this.query
-            .select(this.db.raw("count(*) as total"))
+            .select(this.client.raw("count(*) as total"))
             .whereRaw(where ?? "1=1")
             .then((rows) => +(rows?.[0] ?? { total: 0 }).total);
     }
     async hasColumn(name) {
-        return this.db.schema.hasColumn(this.options.name, name);
+        return this.client.schema.hasColumn(this.options.name, name);
     }
     async getColumn(name) {
-        return this.db(this.options.name).columnInfo(name);
+        return this.client(this.options.name).columnInfo(name);
     }
     async getColumns() {
-        return this.db(this.options.name).columnInfo();
+        return this.client(this.options.name).columnInfo();
     }
     async getColumnNames() {
         return this.getColumns().then(Object.keys);
@@ -74,12 +104,15 @@ export class Table {
             ? ` ${styled(this.orm, this.options.description, "description")}`
             : ""}`;
         try {
-            await this.db.schema.createTable(this.options.name, this.options.setup);
+            await this.client.schema.createTable(this.options.name, (builder) => {
+                const columns = this.options.columns(col);
+                buildColumnsSchema(builder, columns);
+            });
             this.orm.config.logger?.log(`created table ${tableNameLog}`);
         }
         catch (error) {
             if (error.toString().includes("syntax error")) {
-                this.orm.config.logger?.error(`you need to implement the "setup" method in options of your ${styled(this.orm, this.options.name, "highlight")} table!`);
+                this.orm.config.logger?.error(`you need to implement the "columns" callback in options of your ${styled(this.orm, this.options.name, "highlight")} table!`);
                 throw error;
             }
             else {
@@ -96,36 +129,106 @@ export class Table {
             this.orm.config.logger?.error(error);
             throw error;
         }
-        if ((await this.count()) === 0)
-            await this.options.then?.bind(this)(this);
+        if ((await this.count()) === 0) {
+            const thenFn = this.options.then;
+            await thenFn?.bind(this)(this);
+        }
         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 fromDatabase = await this.db("migration")
+        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) {
-            await this.db.schema.alterTable(this.options.name, (builder) => {
-                if (version <= data.version)
-                    return;
-                migration(builder);
-                data.version = version;
+        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 (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.db("migration")
-            .insert(data)
-            .onConflict("table")
-            .merge();
+        await this.client("migration").insert(data).onConflict("table").merge();
         return baseVersion === data.version ? false : data.version;
     }
 }

package/dist/app/util.d.ts

@@ -4,7 +4,7 @@ export type TextStyle = Parameters<typeof util.styleText>[0];
 export declare const DEFAULT_BACKUP_LOCATION: string;
 export declare const DEFAULT_BACKUP_CHUNK_SIZE: number;
 export declare const DEFAULT_LOGGER_HIGHLIGHT = "blueBright";
-export declare const DEFAULT_LOGGER_DESCRIPTION = "grey";
+export declare const DEFAULT_LOGGER_DESCRIPTION = "gray";
 export declare const DEFAULT_LOGGER_RAW_VALUE = "magentaBright";
 declare let isCJS: boolean;
 export { isCJS };

package/dist/app/util.js

@@ -1,15 +1,15 @@
-import util from "node:util";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
+import util from "node:util";
 export const DEFAULT_BACKUP_LOCATION = path.join(process.cwd(), "backup");
 export const DEFAULT_BACKUP_CHUNK_SIZE = 5 * 1024 * 1024; // 5MB
 export const DEFAULT_LOGGER_HIGHLIGHT = "blueBright";
-export const DEFAULT_LOGGER_DESCRIPTION = "grey";
+export const DEFAULT_LOGGER_DESCRIPTION = "gray";
 export const DEFAULT_LOGGER_RAW_VALUE = "magentaBright";
 let isCJS = false;
 try {
     const pack = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
-    isCJS = pack.type === "commonjs" || pack.type == void 0;
+    isCJS = pack.type === "commonjs" || pack.type === void 0;
 }
 catch {
     throw new Error("Missing package.json: Can't detect the type of modules.\n" +

package/dist/index.d.ts

@@ -1,4 +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/backup.js";
 export * from "./app/util.js";

package/dist/index.js

@@ -1,4 +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/backup.js";
 export * from "./app/util.js";

package/package.json

@@ -1,47 +1,42 @@
-{
-  "name": "@ghom/orm",
-  "version": "1.10.0",
-  "license": "MIT",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "description": "TypeScript KnexJS ORM & handler",
-  "homepage": "https://github.com/GhomKrosmonaute/orm",
-  "prettier": {
-    "semi": false
-  },
-  "scripts": {
-    "format": "prettier --write src tsconfig.json tests",
-    "build": "rimraf dist && tsc",
-    "test": "npm run build && node --experimental-vm-modules node_modules/jest/bin/jest.js tests/test.js --detectOpenHandles",
-    "prepublishOnly": "npm run format && npm test"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.6",
-    "@types/node": "^22.0.0",
-    "dotenv": "^16.3.1",
-    "jest": "^29.7.0",
-    "prettier": "^3.0.3",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.2.2"
-  },
-  "optionalDependencies": {
-    "mysql2": "^3.6.2",
-    "pg": "^8.11.3",
-    "sqlite3": "^5.1.6"
-  },
-  "dependencies": {
-    "@ghom/handler": "^3.1.0",
-    "@ghom/query": "1.0.0",
-    "csv-parser": "^3.0.0",
-    "json-2-csv": "^5.5.6",
-    "knex": "^3.0.1"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "repository": {
-    "url": "https://github.com/GhomKrosmonaute/orm.git",
-    "type": "git"
-  }
-}
+{
+  "name": "@ghom/orm",
+  "version": "2.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "description": "TypeScript KnexJS ORM & handler",
+  "homepage": "https://github.com/GhomKrosmonaute/orm",
+  "scripts": {
+    "format": "biome format --write .",
+    "check": "biome check --write .",
+    "build": "rimraf dist && tsc",
+    "test": "bun test",
+    "prepublishOnly": "npm run check && npm run build && npm test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/bun": "^1.1.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.2.2"
+  },
+  "optionalDependencies": {
+    "mysql2": "^3.6.2",
+    "pg": "^8.11.3",
+    "sqlite3": "^5.1.6"
+  },
+  "dependencies": {
+    "@ghom/handler": "^3.1.0",
+    "@ghom/query": "1.0.0",
+    "csv-parser": "^3.0.0",
+    "json-2-csv": "^5.5.6",
+    "knex": "^3.0.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "url": "https://github.com/GhomKrosmonaute/orm.git",
+    "type": "git"
+  }
+}