mevn-orm 4.0.1 → 4.0.3

package/README.md

@@ -8,10 +8,10 @@ Mevn ORM is a small ActiveRecord-style ORM built on top of Knex.
 
 It exports:
 - `Model`: base class for your models
-- `configureDatabase`: initialize with simple DB options by dialect
-- `configure`: initialize with raw Knex config (advanced)
+- `configureDatabase`: initialise with simple DB options by `client`
+- `configure`: initialise with raw Knex config (advanced)
 - migration helpers: `makeMigration`, `migrateLatest`, `migrateRollback`, `migrateList`, `migrateCurrentVersion`
-- `DB`: initialized Knex instance (after `configure`)
+- `DB`: initialised Knex instance (after `configure`)
 
 ## Status
 
@@ -20,18 +20,21 @@ This project is in maintenance mode. Core functionality works, but new features
 ## Requirements
 
 - Node.js 20+ (ESM runtime)
-- Database driver for your selected client (`mysql2`, `sqlite3`, etc.)
+- Database driver for your selected client (`mysql2`, `pg`, `sqlite3`, etc.)
 
 ## Installation
 
 ```bash
-npm install mevn-orm knex mysql2
-```
+npm install mevn-orm knex
+npm install mysql2
+````
 
 For SQLite development/testing:
 
 ```bash
 npm install sqlite3
+# or:
+npm install better-sqlite3
 ```
 
 ## Quick Start
@@ -42,23 +45,26 @@ npm install sqlite3
 import { configureDatabase } from 'mevn-orm'
 
 configureDatabase({
-  dialect: 'sqlite',
-  filename: './dev.sqlite'
+  client: 'sqlite3',
+  connection: {
+    filename: './dev.sqlite'
+  }
 })
 ```
 
-Supported dialects:
-- `sqlite`, `better-sqlite3`
-- `mysql`, `mysql2`
-- `postgres`, `postgresql`, `pg`, `pgnative`
-- `cockroachdb`, `redshift`
-- `mssql`
-- `oracledb`, `oracle`
+Supported clients (canonical Knex client names):
+
+* `sqlite3`, `better-sqlite3`
+* `mysql2`
+* `pg` (also used for CockroachDB/Redshift via the pg driver)
+* `mssql`
+* `oracledb`
 
 Connection styles:
-- `connectionString` for one-string connection setup
-- field-based setup (`host`, `port`, `user`, `password`, `database`)
-- sqlite file setup via `filename`
+
+* connection string: `connection: process.env.DATABASE_URL`
+* object: `connection: { host, port, user, password, database }`
+* sqlite file: `connection: { filename }`
 
 ### 2) Define a model
 
@@ -88,58 +94,19 @@ await found?.update({ name: 'Jane Updated' })
 
 ### Exports
 
-- `Model`
-- `configureDatabase(config): Knex`
-- `createKnexConfig(config): Knex.Config`
-- `configure(config: Knex.Config | Knex): Knex`
-- `getDB(): Knex`
-- `DB` (Knex instance once configured)
-- `setMigrationConfig(config): MigrationConfig`
-- `getMigrationConfig(): MigrationConfig`
-- `makeMigration(name, config?): Promise<string>`
-- `migrateLatest(config?): Promise<{ batch: number; log: string[] }>`
-- `migrateRollback(config?, all?): Promise<{ batch: number; log: string[] }>`
-- `migrateCurrentVersion(config?): Promise<string>`
-- `migrateList(config?): Promise<{ completed: string[]; pending: string[] }>`
-
-### Model instance members
-
-- `fillable: string[]`
-  - Attributes allowed through `save()`.
-- `hidden: string[]`
-  - Attributes removed when serializing model results.
-- `table: string`
-  - Inferred from class name using pluralization (for `User` -> `users`).
-- `id?: number`
-
-### Instance methods
-
-- `save(): Promise<this>`
-  - Inserts record using only `fillable` fields.
-- `update(properties): Promise<this>`
-  - Updates by `id`, then reloads from DB.
-- `delete(): Promise<void>`
-  - Deletes current row by `id`.
-- `hasOne(RelatedModel, localKey?, foreignKey?): Promise<Model | null>`
-  - Loads one related record.
-- `hasMany(RelatedModel, localKey?, foreignKey?): Promise<Model[]>`
-  - Loads related records by foreign key.
-- `belongsTo(RelatedModel, foreignKey?, ownerKey?): Promise<Model | null>`
-  - Loads the owning/parent record.
-
-### Static methods
-
-- `find(id, columns = '*'): Promise<Model | null>`
-- `findOrFail(id, columns = '*'): Promise<Model>`
-- `create(properties): Promise<Model>`
-- `createMany(properties[]): Promise<Model[]>`
-- `firstOrCreate(attributes, values = {}): Promise<Model>`
-- `where(conditions = {}): typeof Model`
-- `first(columns = '*'): Promise<Model | null>`
-- `all(columns = '*'): Promise<Model[]>`
-- `count(column = '*'): Promise<number>`
-- `update(properties): Promise<number | undefined>`
-- `destroy(): Promise<number | undefined>`
+* `Model`
+* `configureDatabase(config): Knex`
+* `createKnexConfig(config): Knex.Config`
+* `configure(config: Knex.Config | Knex): Knex`
+* `getDB(): Knex`
+* `DB` (Knex instance once configured)
+* `setMigrationConfig(config): MigrationConfig`
+* `getMigrationConfig(): MigrationConfig`
+* `makeMigration(name, config?): Promise<string>`
+* `migrateLatest(config?): Promise<{ batch: number; log: string[] }>`
+* `migrateRollback(config?, all?): Promise<{ batch: number; log: string[] }>`
+* `migrateCurrentVersion(config?): Promise<string>`
+* `migrateList(config?): Promise<{ completed: string[]; pending: string[] }>`
 
 ## Using `DB` directly
 
@@ -149,9 +116,12 @@ You can always drop down to Knex after configuration:
 import { configureDatabase, DB } from 'mevn-orm'
 
 configureDatabase({
-  dialect: 'sqlite',
-  filename: './dev.sqlite'
+  client: 'sqlite3',
+  connection: {
+    filename: './dev.sqlite'
+  }
 })
+
 const users = await DB('users').select('*')
 ```
 
@@ -162,34 +132,41 @@ import { configureDatabase } from 'mevn-orm'
 
 // MySQL / mysql2
 configureDatabase({
-  dialect: 'mysql',
-  host: '127.0.0.1',
-  port: 3306,
-  user: 'root',
-  password: 'secret',
-  database: 'app_db'
+  client: 'mysql2',
+  connection: {
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: 'secret',
+    database: 'app_db'
+  }
 })
 
-// Postgres
+// Postgres (connection string)
 configureDatabase({
-  dialect: 'postgres',
-  connectionString: process.env.DATABASE_URL
+  client: 'pg',
+  connection: process.env.DATABASE_URL
 })
 
 // MSSQL
 configureDatabase({
-  dialect: 'mssql',
-  host: '127.0.0.1',
-  user: 'sa',
-  password: 'StrongPassword!',
-  database: 'app_db',
-  ssl: true
+  client: 'mssql',
+  connection: {
+    host: '127.0.0.1',
+    user: 'sa',
+    password: 'StrongPassword!',
+    database: 'app_db',
+    // MSSQL driver options live under `options` (passed through to tedious)
+    options: {
+      encrypt: true
+    }
+  }
 })
 ```
 
 ## Nuxt/Nitro Example
 
-Use a server plugin to initialize the ORM once at Nitro startup.
+Use a server plugin to initialise the ORM once at Nitro startup.
 You can also run idempotent migrations (and optional rollback) during boot.
 
 Because Nitro bundles server code, migration files must be copied into the build output.
@@ -225,7 +202,9 @@ import {
 } from 'mevn-orm'
 
 const isIgnorableMigrationError = (error: unknown): boolean => {
-  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
+  const message =
+    error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
+
   return (
     message.includes('already exists') ||
     message.includes('duplicate') ||
@@ -237,8 +216,8 @@ const isIgnorableMigrationError = (error: unknown): boolean => {
 
 export default defineNitroPlugin(async () => {
   configureDatabase({
-    dialect: 'postgres',
-    connectionString: process.env.DATABASE_URL
+    client: 'pg',
+    connection: process.env.DATABASE_URL
   })
 
   // Nitro runtime path differs in dev vs built server.
@@ -255,9 +234,7 @@ export default defineNitroPlugin(async () => {
   try {
     await migrateLatest()
   } catch (error) {
-    if (!isIgnorableMigrationError(error)) {
-      throw error
-    }
+    if (!isIgnorableMigrationError(error)) throw error
   }
 
   // Optional rollback at boot (usually only for dev/preview).
@@ -265,63 +242,7 @@ export default defineNitroPlugin(async () => {
     try {
       await migrateRollback(undefined, false)
     } catch (error) {
-      if (!isIgnorableMigrationError(error)) {
-        throw error
-      }
-    }
-  }
-})
-```
-
-For fully idempotent behavior across SQL dialects, write migrations with guards
-(`createTableIfNotExists`, checking column existence, or raw `IF EXISTS/IF NOT EXISTS`).
-
-`server/models/User.ts`:
-
-```ts
-import { Model } from 'mevn-orm'
-
-export class User extends Model {
-  override fillable = ['name', 'email', 'password']
-  override hidden = ['password']
-}
-```
-
-`server/api/users.get.ts`:
-
-```ts
-import { User } from '../models/User'
-
-export default defineEventHandler(async () => {
-  return await User.all()
-})
-```
-
-`server/api/users.post.ts`:
-
-```ts
-import { User } from '../models/User'
-
-export default defineEventHandler(async (event) => {
-  const body = await readBody(event)
-  return await User.create({
-    name: body.name,
-    email: body.email,
-    password: body.password // hash before storing
-  })
-})
-```
-
-If you prefer Nuxt runtime config:
-
-`nuxt.config.ts`:
-
-```ts
-export default defineNuxtConfig({
-  runtimeConfig: {
-    db: {
-      dialect: 'postgres',
-      connectionString: process.env.DATABASE_URL
+      if (!isIgnorableMigrationError(error)) throw error
     }
   }
 })
@@ -329,7 +250,7 @@ export default defineNuxtConfig({
 
 ## Migrations
 
-Migrations are now programmatic and use Knex’s migration API under the hood.
+Migrations are programmatic and use Knex’s migration API under the hood.
 
 ```ts
 import {
@@ -342,8 +263,8 @@ import {
 } from 'mevn-orm'
 
 configureDatabase({
-  dialect: 'sqlite',
-  filename: './dev.sqlite'
+  client: 'sqlite3',
+  connection: { filename: './dev.sqlite' }
 })
 
 setMigrationConfig({
@@ -369,19 +290,6 @@ pnpm run migrate:version
 
 ## Security Notes
 
-- Hash passwords before calling `create()` or `save()`.
-- Validate and sanitize input before persisting.
-- Keep `knex`, DB drivers, and Node.js versions up to date.
-
-## Development (Repository)
-
-```bash
-pnpm install
-pnpm run migrate
-pnpm run test
-pnpm run typecheck
-```
-
-## License
-
-[MIT](./LICENSE)
+* Hash passwords before calling `create()` or `save()`.
+* Validate and sanitise input before persisting.
+* Keep `knex`, DB drivers, and Node.js versions up to date.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mevn-orm",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "simple ORM for express js",
   "type": "module",
   "peerDependencies": {
@@ -35,7 +35,7 @@
     "@babel/core": "^7.24.5",
     "@babel/eslint-parser": "^7.24.3",
     "@babel/eslint-plugin": "^7.24.0",
-    "@types/node": "^24.6.0",
+    "@types/node": "^25.3.3",
     "@faker-js/faker": "^10.0.0",
     "dotenv": "^17.0.1",
     "knex": "^3.0.0",