@ghom/orm 2.1.1 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghom/orm",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/readme.md

@@ -21,12 +21,12 @@ const orm = new ORM({
   // tables directory
   tableLocation: "./tables",
   
-  // knex config (sqlite3 by default)
-  database: { ... },
+  // knex config (sqlite3 in-memory by default)
+  database: { client: "sqlite3", connection: { filename: ":memory:" } },
   
-  // custom logger (console by default)
+  // optional custom logger (must have log, error, warn methods)
   logger: console,
-  loggerColors: { ... },
+  loggerStyles: { highlight: "cyan", rawValue: "yellow", description: "dim" },
   
   // caching options for all tables and rawCache queries (default to Infinity)
   caching: 10 * 60 * 1000,
@@ -34,6 +34,12 @@ const orm = new ORM({
   // configuration for the database backups
   backups: {
     location: "./backups",
+    chunkSize: 1000, // rows per backup file chunk
+  },
+
+  // migration behavior configuration
+  migrations: {
+    alphabeticalOrder: false // default
   }
 })
 
@@ -67,11 +73,14 @@ The tables are automatically loaded from the `tableLocation` directory. Types ar
 ```typescript
 // tables/user.ts
 
-import { Table, col } from "@ghom/orm"
+import { Table, col, migrate } from "@ghom/orm"
 
 export default new Table({
   name: "user",
   
+  // optional description for logging
+  description: "User accounts",
+  
   // the higher the priority, the earlier the table is compiled
   priority: 0,
   
@@ -81,32 +90,108 @@ export default new Table({
     username: col.string().unique(),
     password: col.string(),
     age: col.integer().nullable(),
-    role: col.enum(["admin", "user"]).defaultTo("user"),
+    role: col.enum(["admin", "user"] as const).defaultTo("user"),
   }),
   
   // migrations are executed in order based on key pattern (see Migration Keys section)
   migrations: {
-    "1": (table) => {
-      table.renameColumn("name", "username")
-    }
+    "001_add_email": migrate.addColumn("email", col.string()),
   },
   
   // 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", role: "admin" })
+  then: (table) => {
+    table.query.insert({ username: "admin", password: "admin", role: "admin", email: "admin@admin.com" })
   },
   
   caching: 10 * 60 * 1000 // The table cache. Default to the ORM cache or Infinity
 })
+```
+
+The type is automatically inferred from columns + migrations:
+
+```typescript
+// { id: number; username: string; password: string; age: number | null; role: "admin" | "user"; email: string }
+```
+
+You can export and use the type from another file:
+
+```typescript
+// somewhere else in your code
+import userTable from "./tables/user"
 
-// Type is automatically inferred:
-// { id: number; username: string; password: string; age: number | null; role: "admin" | "user" }
 type User = typeof userTable.$type
 ```
 
-### Typed Migrations
+## Column Types
+
+All available column types with their TypeScript types:
+
+```typescript
+import { col } from "@ghom/orm"
+
+// Numeric types
+col.increments()       // number - auto-incrementing primary key
+col.bigIncrements()    // bigint - big auto-incrementing primary key
+col.integer()          // number
+col.bigInteger()       // bigint
+col.tinyint()          // number (0-255)
+col.smallint()         // number
+col.mediumint()        // number
+col.float(precision?, scale?)    // number
+col.double(precision?, scale?)   // number
+col.decimal(precision?, scale?)  // number
+
+// String types
+col.string(length?)    // string (default: 255)
+col.text(textType?)    // string - "text" | "mediumtext" | "longtext"
+col.uuid()             // string
+
+// Boolean
+col.boolean()          // boolean
+
+// Date/Time types
+col.date()             // Date
+col.datetime(options?) // Date - { useTz?: boolean; precision?: number }
+col.timestamp(options?) // Date - { useTz?: boolean; precision?: number }
+col.time()             // string
+
+// Other types
+col.binary(length?)    // Buffer
+col.enum(values)       // union of values - col.enum(["a", "b"] as const) => "a" | "b"
+col.json<T>()          // T (default: unknown)
+col.jsonb<T>()         // T (PostgreSQL)
+col.specificType<T>(type) // T - database-specific type
+```
+
+### Column Modifiers
+
+```typescript
+col.string()
+  .nullable()           // allows null values
+  .defaultTo(value)     // sets default value
+  .unique()             // adds unique constraint
+  .primary()            // sets as primary key
+  .index(indexName?)    // adds an index
+  .comment(comment)     // adds a column comment
+  .collate(collation)   // sets collation
+
+col.integer()
+  .unsigned()           // only positive values (numeric columns only)
+```
+
+### Foreign Key References
+
+```typescript
+col.integer()
+  .references("id")           // column name in referenced table
+  .inTable("users")           // referenced table name
+  .onDelete("CASCADE")        // CASCADE | SET NULL | RESTRICT | NO ACTION
+  .onUpdate("CASCADE")        // CASCADE | SET NULL | RESTRICT | NO ACTION
+```
+
+## Typed Migrations
 
-You can also use typed migrations that automatically update the TypeScript type:
+Use typed migrations that automatically update the TypeScript type:
 
 ```typescript
 import { Table, col, migrate } from "@ghom/orm"
@@ -127,7 +212,8 @@ export default new Table({
 // Final type: { id: number; username: string; email: string; age: number | null }
 ```
 
-Available migration helpers:
+### Migration Helpers
+
 - `migrate.addColumn(name, columnDef)` - Add a new column
 - `migrate.dropColumn(name)` - Remove a column
 - `migrate.renameColumn(oldName, newName)` - Rename a column
@@ -136,7 +222,25 @@ Available migration helpers:
 - `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
+- `migrate.raw<From, To>(callback)` - Custom migration callback
+- `migrate.sequence(...migrations)` - Combine multiple migrations
+
+### Migration Sequences
+
+Use `migrate.sequence()` to combine multiple migrations in a single migration key:
+
+```typescript
+migrations: {
+  "001_user_updates": migrate.sequence(
+    migrate.addColumn("phone", col.string()),
+    migrate.addColumn("address", col.string().nullable()),
+    migrate.addIndex(["phone"], "idx_phone"),
+    migrate.renameColumn("name", "username"),
+  ),
+}
+```
+
+Intermediate columns (added then removed in the sequence) are excluded from the final type automatically.
 
 ## Migration Keys
 
@@ -176,21 +280,44 @@ The ORM performs a runtime check on initialization and will throw an error if th
 ## Launch a query
 
 For more information about the query builder, see [knexjs.org](https://knexjs.org/).  
-You can launch a SQL query on a table like that
+You can launch a SQL query on a table like this:
 
 ```typescript
-import user from "./tables/user"
+import userTable from "./tables/user"
 
-export async function compareHash(username, hash): Promise<boolean> {
-  const user = await user.query
+export async function compareHash(username: string, hash: string): Promise<boolean> {
+  const user = await userTable.query
     .select()
     .where("username", username)
     .first()
 
-  return user && user.password === hash
+  return user !== undefined && user.password === hash
 }
 ```
 
+### Table Utilities
+
+```typescript
+// Check if a column exists
+await table.hasColumn("email") // boolean
+
+// Get column info
+await table.getColumn("email") // Knex.ColumnInfo
+
+// Get all columns info
+await table.getColumns() // Record<string, Knex.ColumnInfo>
+
+// Get column names
+await table.getColumnNames() // string[]
+
+// Check if table is empty
+await table.isEmpty() // boolean
+
+// Count rows
+await table.count() // number
+await table.count("status = 'active'") // number with where clause
+```
+
 ## Backup
 
 You can backup the database by calling the `createBackup` and `restoreBackup` methods on the ORM instance. The backup is stored in the `config.backups.location` directory.
@@ -210,33 +337,38 @@ The cache is automatically managed by the ORM. When a table is requested from th
 ```typescript
 // get the number of rows in the table with caching
 await table.cache.count() // => 10
+await table.cache.count("status = 'active'") // with where clause
 
-// add a row with caching
+// add a row with caching (automatically invalidates cache)
 await table.cache.set((query) => {
   return query.insert({ name: "test" })
 })
 
 await table.cache.count() // => 11
 
-// Get the row with caching.
-// After the first call, the row is cached until
-// the cache is invalidate by a "cache.set" or "cache.invalidate" call
-await table.cache.get("named test", (query) => {
-  return query.where("name", "test").first()
-}) // => { name: "test" }
+// Get data with caching.
+// After the first call, the result is cached until
+// the cache is invalidated by a "cache.set" or "cache.invalidate" call
+await table.cache.get("all users", (query) => {
+  return query.select("*")
+}) // => [{ name: "test" }, ...]
 
 // delete the row without caching
 await table.query.delete().where("name", "test")
 
-await table.cache.count() // => 11 (unchanged)
+await table.cache.count() // => 11 (unchanged - cache not invalidated)
 
-// indicate that the cache is invalidate
-// and force the cache to be updated
+// manually invalidate cache
 table.cache.invalidate()
 
 await table.cache.count() // => 10
 await table.cache.count() // => 10 (no more query to the database)
 
+// update with caching (automatically invalidates cache)
+await table.cache.set((query) => {
+  return query.update({ status: "inactive" }).where("id", 1)
+})
+
 // remove all rows from a table with caching
 await table.cache.set((query) => {
   return query.truncate()
@@ -249,15 +381,21 @@ await table.cache.count() // => 0
 
 ### Raw cache
 
-You can also cache raw queries with the `<ORM>.cache.raw` property. The raw cache is useful when you have a complex query that you want to cache.
+You can also cache raw queries with the `<ORM>.cache.raw` method. The raw cache is useful when you have a complex query that you want to cache.
 
 ```typescript
 const fooUser = await orm.cache.raw("select * from user where name = 'foo'") // query the database
 const barUser = await orm.cache.raw("select * from user where name = 'bar'") // query the database
-const fooUserCached = await orm.cache.raw("select * from user where name = 'foo'") // no query to the database
+const fooUserCached = await orm.cache.raw("select * from user where name = 'foo'") // cached - no query
+
+// To invalidate the cache when you know data has changed externally:
+const result = await orm.cache.raw("select * from user", true) // anyDataUpdated = true
 ```
 
-The cache of the `<ORM>.cache.raw` method is automatically invalidated when the database is updated.
+The raw cache is invalidated when:
+- You call `orm.cache.invalidate()`
+- You use `table.cache.set()` to modify data
+- You pass `true` as the second argument to `orm.cache.raw()`
 
 ## Future features