@ghom/orm 1.10.0 → 2.1.0

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

@@ -0,0 +1,431 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import fs from "fs"
+import path from "path"
+import { rimraf } from "rimraf"
+
+import { col, migrate, ORM, type ORMConfig, Table } from "../src"
+
+import a from "./tables/a"
+import b from "./tables/b"
+import c from "./tables/c"
+import d from "./tables/d"
+
+describe("typed columns", () => {
+  test("new Table() infers types correctly", () => {
+    const userTable = new Table({
+      name: "test_user",
+      columns: (col) => ({
+        id: col.increments(),
+        username: col.string().unique(),
+        age: col.integer().nullable(),
+        role: col.enum(["admin", "user"] as const),
+        isActive: col.boolean().defaultTo(true),
+      }),
+    })
+
+    expect(userTable).toBeInstanceOf(Table)
+    expect(userTable.options.name).toBe("test_user")
+    expect("columns" in userTable.options).toBe(true)
+
+    // Type inference check - this line would fail at compile time if types weren't inferred
+    type ExpectedType = typeof userTable.$type
+    const _typeCheck: ExpectedType = {
+      id: 1,
+      username: "test",
+      age: null,
+      role: "admin",
+      isActive: true,
+    }
+  })
+
+  test("col factory creates column definitions", () => {
+    const idCol = col.increments()
+    const stringCol = col.string()
+    const nullableInt = col.integer().nullable()
+    const enumCol = col.enum(["a", "b", "c"] as const)
+
+    expect(idCol).toBeDefined()
+    expect(stringCol).toBeDefined()
+    expect(nullableInt._isNullable).toBe(true)
+    expect(enumCol).toBeDefined()
+  })
+
+  test("typed table d has correct options", () => {
+    expect(d).toBeInstanceOf(Table)
+    expect(d.options.name).toBe("d")
+    expect("columns" in d.options).toBe(true)
+  })
+})
+
+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)
+
+    expect(unconnectedOrm).toBeInstanceOf(ORM)
+    expect(unconnectedOrm.isConnected).toBe(false)
+    expect(unconnectedOrm.config).toBe(false)
+    expect(unconnectedOrm.handler).toBeUndefined()
+    expect(unconnectedOrm.cachedTables).toEqual([])
+    expect(unconnectedOrm.cachedTableNames).toEqual([])
+  })
+
+  test("throws when calling methods requiring client", async () => {
+    const unconnectedOrm = new ORM(false)
+
+    expect(() => unconnectedOrm.client).toThrow()
+    expect(unconnectedOrm.init()).rejects.toThrow()
+    expect(unconnectedOrm.hasTable("test")).rejects.toThrow()
+    expect(() => unconnectedOrm.raw("SELECT 1")).toThrow()
+    expect(unconnectedOrm.createBackup()).rejects.toThrow()
+    expect(unconnectedOrm.restoreBackup()).rejects.toThrow()
+  })
+})
+
+const orm = new ORM({
+  tableLocation: path.join(process.cwd(), "tests", "tables"),
+  backups: {
+    location: path.join(process.cwd(), "backups"),
+  },
+})
+
+beforeAll(async () => {
+  await orm.init()
+})
+
+describe("table management", () => {
+  test("tables created", async () => {
+    expect(await orm.hasTable("migration")).toBeTruthy()
+    expect(await orm.hasTable("a")).toBeTruthy()
+    expect(await orm.hasTable("b")).toBeTruthy()
+    expect(await orm.hasTable("c")).toBeTruthy()
+    expect(await orm.hasTable("d")).toBeTruthy()
+  })
+
+  test("table cached", () => {
+    expect(orm.hasCachedTable("migration")).toBeTruthy()
+    expect(orm.hasCachedTable("a")).toBeTruthy()
+    expect(orm.hasCachedTable("b")).toBeTruthy()
+    expect(orm.hasCachedTable("c")).toBeTruthy()
+    expect(orm.hasCachedTable("d")).toBeTruthy()
+  })
+
+  test("table migrations ran", async () => {
+    expect(await b.hasColumn("c_id")).toBeTruthy()
+  })
+
+  test("table then ran", async () => {
+    const rows = await a.query.select()
+    expect(rows.length).toBe(1)
+  })
+
+  test("typed table d was created with correct columns", async () => {
+    expect(await d.hasColumn("id")).toBeTruthy()
+    expect(await d.hasColumn("name")).toBeTruthy()
+    expect(await d.hasColumn("email")).toBeTruthy()
+    expect(await d.hasColumn("age")).toBeTruthy()
+    expect(await d.hasColumn("role")).toBeTruthy()
+    expect(await d.hasColumn("isActive")).toBeTruthy()
+    expect(await d.hasColumn("metadata")).toBeTruthy()
+    expect(await d.hasColumn("createdAt")).toBeTruthy()
+  })
+
+  test("typed table d then ran", async () => {
+    const rows = await d.query.select()
+    expect(rows.length).toBe(1)
+    expect(rows[0].name).toBe("Test User")
+    expect(rows[0].role).toBe("admin")
+  })
+})
+
+describe("table column types", () => {
+  test("increments", async () => {
+    const info = await orm.client!("a").columnInfo("id")
+    expect(info.type).toMatch(/^int/)
+  })
+
+  test("integer", async () => {
+    const info = await orm.client!("a").columnInfo("b_id")
+    expect(info.type).toMatch(/^int/)
+  })
+
+  test("typed table d column types", async () => {
+    const nameInfo = await orm.client!("d").columnInfo("name")
+    expect(nameInfo.type).toMatch(/varchar|text|character/i)
+
+    const ageInfo = await orm.client!("d").columnInfo("age")
+    expect(ageInfo.type).toMatch(/^int/)
+    expect(ageInfo.nullable).toBe(true)
+  })
+})
+
+describe("database extraction", () => {
+  test("create backup", async () => {
+    await orm.createBackup()
+
+    const config = orm.config as ORMConfig
+    expect(fs.existsSync(path.join(config.backups!.location!, "a_chunk_0.csv"))).toBeTruthy()
+    expect(fs.existsSync(path.join(config.backups!.location!, "b_chunk_0.csv"))).toBeTruthy()
+    expect(fs.existsSync(path.join(config.backups!.location!, "c_chunk_0.csv"))).toBeTruthy()
+    expect(fs.existsSync(path.join(config.backups!.location!, "d_chunk_0.csv"))).toBeTruthy()
+  })
+
+  test("cascade delete", async () => {
+    expect(await a.isEmpty()).toBeFalsy()
+    await c.query.del()
+    expect(await a.isEmpty()).toBeTruthy()
+  })
+
+  test("restore backup", async () => {
+    await orm.restoreBackup()
+
+    expect(await a.isEmpty()).toBeFalsy()
+    expect(await b.isEmpty()).toBeFalsy()
+    expect(await c.isEmpty()).toBeFalsy()
+    expect(await d.isEmpty()).toBeFalsy()
+  })
+
+  afterAll(async () => {
+    const config = orm.config as ORMConfig
+    await rimraf(config.backups!.location!)
+  })
+})
+
+describe("table getters", () => {
+  test("table info", async () => {
+    expect(await a.getColumnNames()).toContain("id")
+    expect(await a.getColumnNames()).toContain("b_id")
+
+    expect(await b.getColumnNames()).toContain("id")
+    expect(await b.getColumnNames()).toContain("c_id")
+
+    expect(await c.getColumnNames()).toContain("id")
+
+    expect(await d.getColumnNames()).toContain("id")
+    expect(await d.getColumnNames()).toContain("name")
+    expect(await d.getColumnNames()).toContain("role")
+  })
+
+  test("table names", () => {
+    expect(orm.cachedTableNames).toContain("a")
+    expect(orm.cachedTableNames).toContain("b")
+    expect(orm.cachedTableNames).toContain("c")
+    expect(orm.cachedTableNames).toContain("d")
+  })
+})
+
+describe("data caching", () => {
+  beforeAll(async () => {
+    await c.query.del()
+    await c.query.insert([{ id: 1 }, { id: 2 }, { id: 3 }])
+    await b.query.insert([
+      { id: 1, c_id: 1 },
+      { id: 2, c_id: 2 },
+      { id: 3, c_id: 3 },
+    ])
+    await a.query.insert([
+      { id: 1, b_id: 1 },
+      { id: 2, b_id: 2 },
+      { id: 3, b_id: 3 },
+    ])
+  })
+
+  test("select with caching", async () => {
+    const rows = await a.cache.get("all a", (query) => {
+      return query.select("*")
+    })
+
+    expect(rows.length).toBe(3)
+  })
+
+  test("insert with caching", async () => {
+    await a.cache.set((query) => {
+      return query.insert({ id: 4, b_id: 1 })
+    })
+
+    expect(await a.cache.count()).toBe(4)
+  })
+
+  test("update with caching", async () => {
+    await a.cache.set((query) => {
+      return query.update({ b_id: 3 }).where({ id: 1 })
+    })
+
+    const row = await a.cache.get("a 1", (query) => {
+      return query.select("b_id").where({ id: 1 }).first()
+    })
+
+    expect(row!.b_id).toBe(3)
+  })
+
+  test("delete with caching", async () => {
+    await a.cache.set((query) => {
+      return query.delete().where({ id: 1 })
+    })
+
+    expect(await a.cache.count()).toBe(3)
+  })
+
+  test("cache invalidation", async () => {
+    expect(await a.cache.count()).toBe(3)
+
+    await a.query.insert({ id: 5, b_id: 1 })
+
+    expect(await a.cache.count()).toBe(3)
+
+    orm.cache.invalidate()
+
+    expect(await a.cache.count()).toBe(4)
+  })
+})
+
+afterAll(async () => {
+  await orm.client!.schema.dropTable("migration")
+  await orm.client!.schema.dropTable("a")
+  await orm.client!.schema.dropTable("b")
+  await orm.client!.schema.dropTable("c")
+  await orm.client!.schema.dropTable("d")
+  await orm.client!.destroy()
+})

package/tests/tables/a.ts

@@ -0,0 +1,16 @@
+import { Table } from "../../src"
+
+export default new Table({
+  name: "a",
+  priority: 0,
+  columns: (col) => ({
+    id: col.increments(),
+    b_id: col.integer().unsigned().references("id").inTable("b").onDelete("CASCADE"),
+  }),
+  async then({ query }) {
+    await query.insert({
+      id: 1,
+      b_id: 1,
+    })
+  },
+})

package/tests/tables/b.ts

@@ -0,0 +1,16 @@
+import { Table } from "../../src"
+
+export default new Table({
+  name: "b",
+  priority: 1,
+  columns: (col) => ({
+    id: col.increments(),
+    c_id: col.integer().unsigned().references("id").inTable("c").onDelete("CASCADE"),
+  }),
+  async then({ query }) {
+    await query.insert({
+      id: 1,
+      c_id: 1,
+    })
+  },
+})

package/tests/tables/c.ts

@@ -0,0 +1,14 @@
+import { Table } from "../../src"
+
+export default new Table({
+  name: "c",
+  priority: 2,
+  columns: (col) => ({
+    id: col.increments(),
+  }),
+  async then({ query }) {
+    await query.insert({
+      id: 1,
+    })
+  },
+})

package/tests/tables/d.ts

@@ -0,0 +1,28 @@
+import { Table } from "../../src"
+
+export default new Table({
+  name: "d",
+  priority: 0,
+  columns: (col) => ({
+    id: col.increments(),
+    name: col.string(100).unique(),
+    email: col.string(255),
+    age: col.integer().nullable().unsigned(),
+    role: col.enum(["admin", "user", "guest"] as const).defaultTo("user"),
+    isActive: col.boolean().defaultTo(true),
+    metadata: col.json<{ tags: string[]; score: number }>().nullable(),
+    createdAt: col.timestamp().nullable(),
+  }),
+  async then({ query }) {
+    await query.insert({
+      id: 1,
+      name: "Test User",
+      email: "test@example.com",
+      age: 25,
+      role: "admin",
+      isActive: true,
+      metadata: { tags: ["test"], score: 100 },
+      createdAt: new Date(),
+    })
+  },
+})

package/tsconfig.json

@@ -9,6 +9,7 @@
     "moduleResolution": "NodeNext",
     "esModuleInterop": true,
     "declaration": true,
+    "skipLibCheck": true,
     "typeRoots": ["./node_modules/@types", "./dist/typings"]
   },
   "include": ["src/**/*", "dist/typings/**/*"]

package/tests/tables/a.js

@@ -1,25 +0,0 @@
-import { Table } from "../.."
-
-/**
- * @type {Table<{ id: number; b_id: number }>}
- */
-export default new Table({
-  name: "a",
-  priority: 0,
-  setup(table) {
-    table.increments("id").primary().notNullable()
-    table
-      .integer("b_id")
-      .unsigned()
-      .references("id")
-      .inTable("b")
-      .onDelete("cascade")
-      .notNullable()
-  },
-  async then({ query }) {
-    await query.insert({
-      id: 1,
-      b_id: 1,
-    })
-  },
-})