mevn-orm 4.0.0 → 4.0.2

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/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { Model, DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList } from './src/model.js';
+export { Model, DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { Model, DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, } from './src/model.js';
+export { Model, DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, };

package/dist/src/config.d.ts

@@ -0,0 +1,46 @@
+import type { Knex } from 'knex';
+declare let DB: Knex | undefined;
+type SimpleDialect = 'sqlite' | 'better-sqlite3' | 'mysql' | 'mysql2' | 'postgres' | 'postgresql' | 'pg' | 'pgnative' | 'cockroachdb' | 'redshift' | 'mssql' | 'oracledb' | 'oracle';
+interface SimpleDatabaseConfig {
+    dialect: SimpleDialect;
+    connectionString?: string;
+    filename?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    ssl?: boolean | Record<string, unknown>;
+    debug?: boolean;
+    pool?: Knex.PoolConfig;
+}
+interface MigrationResult {
+    batch: number;
+    log: string[];
+}
+/** Returns the active Knex instance or throws if the ORM has not been configured. */
+declare const getDB: () => Knex;
+/** Configures the ORM using a Knex config object or an existing Knex instance. */
+declare const configure: (config: Knex.Config | Knex) => Knex;
+/** Sets default migration options used by migration helpers. */
+declare const setMigrationConfig: (config: Knex.MigratorConfig) => Knex.MigratorConfig;
+/** Returns the currently configured default migration options. */
+declare const getMigrationConfig: () => Knex.MigratorConfig;
+/** Builds a Knex config from a simplified, dialect-first configuration object. */
+declare const createKnexConfig: (config: SimpleDatabaseConfig) => Knex.Config;
+/** Configures the ORM from simplified database options. */
+declare const configureDatabase: (config: SimpleDatabaseConfig) => Knex;
+/** Generates a migration file and returns its path. */
+declare const makeMigration: (name: string, config?: Knex.MigratorConfig) => Promise<string>;
+/** Runs pending migrations and returns the batch number and migration filenames. */
+declare const migrateLatest: (config?: Knex.MigratorConfig) => Promise<MigrationResult>;
+/** Rolls back migrations. Set `all` to true to rollback all completed batches. */
+declare const migrateRollback: (config?: Knex.MigratorConfig, all?: boolean) => Promise<MigrationResult>;
+/** Returns the current migration version recorded by Knex. */
+declare const migrateCurrentVersion: (config?: Knex.MigratorConfig) => Promise<string>;
+/** Returns completed and pending migration filenames. */
+declare const migrateList: (config?: Knex.MigratorConfig) => Promise<{
+    completed: string[];
+    pending: string[];
+}>;
+export { DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, };

package/dist/src/config.js

@@ -0,0 +1,196 @@
+import knexModule from 'knex';
+const knexFactory = knexModule.knex ??
+    knexModule;
+const toError = (error) => {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+};
+let DB;
+let defaultMigrationConfig = {};
+/** Returns the active Knex instance or throws if the ORM has not been configured. */
+const getDB = () => {
+    if (!DB) {
+        throw new Error('Mevn ORM is not configured. Call configure({ client, connection, ... }) before using Model.');
+    }
+    return DB;
+};
+/** Configures the ORM using a Knex config object or an existing Knex instance. */
+const configure = (config) => {
+    if (typeof config === 'function') {
+        DB = config;
+        return DB;
+    }
+    DB = knexFactory(config);
+    return DB;
+};
+/** Sets default migration options used by migration helpers. */
+const setMigrationConfig = (config) => {
+    defaultMigrationConfig = { ...config };
+    return { ...defaultMigrationConfig };
+};
+/** Returns the currently configured default migration options. */
+const getMigrationConfig = () => ({ ...defaultMigrationConfig });
+const resolveMigrationConfig = (config) => ({
+    ...defaultMigrationConfig,
+    ...(config ?? {}),
+});
+const normalizeDialect = (dialect) => {
+    switch (dialect) {
+        case 'sqlite':
+            return 'sqlite3';
+        case 'mysql':
+            return 'mysql2';
+        case 'postgres':
+        case 'postgresql':
+        case 'pg':
+            return 'pg';
+        case 'oracle':
+            return 'oracledb';
+        default:
+            return dialect;
+    }
+};
+const requireField = (value, field, dialect) => {
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`Missing required field "${field}" for dialect "${dialect}".`);
+    }
+};
+const buildConnection = (config) => {
+    if (config.connectionString) {
+        return config.connectionString;
+    }
+    const client = normalizeDialect(config.dialect);
+    if (client === 'sqlite3' || client === 'better-sqlite3') {
+        requireField(config.filename, 'filename', config.dialect);
+        return { filename: config.filename };
+    }
+    if (client === 'mssql') {
+        const server = config.host;
+        requireField(server, 'host', config.dialect);
+        requireField(config.user, 'user', config.dialect);
+        requireField(config.database, 'database', config.dialect);
+        const connection = {
+            server: server,
+            user: config.user,
+            database: config.database,
+        };
+        if (typeof config.port === 'number') {
+            connection.port = config.port;
+        }
+        if (config.password !== undefined) {
+            connection.password = config.password;
+        }
+        if (config.ssl) {
+            connection.options = { encrypt: true };
+        }
+        return connection;
+    }
+    requireField(config.host, 'host', config.dialect);
+    requireField(config.user, 'user', config.dialect);
+    requireField(config.database, 'database', config.dialect);
+    const connection = {
+        host: config.host,
+        user: config.user,
+        database: config.database,
+    };
+    if (typeof config.port === 'number') {
+        connection.port = config.port;
+    }
+    if (config.password !== undefined) {
+        connection.password = config.password;
+    }
+    if (config.ssl !== undefined) {
+        connection.ssl = config.ssl;
+    }
+    return connection;
+};
+/** Builds a Knex config from a simplified, dialect-first configuration object. */
+const createKnexConfig = (config) => {
+    const client = normalizeDialect(config.dialect);
+    const base = {
+        client,
+        connection: buildConnection(config),
+    };
+    if (config.pool) {
+        base.pool = config.pool;
+    }
+    if (typeof config.debug === 'boolean') {
+        base.debug = config.debug;
+    }
+    if (client === 'sqlite3') {
+        base.useNullAsDefault = true;
+    }
+    return base;
+};
+/** Configures the ORM from simplified database options. */
+const configureDatabase = (config) => configure(createKnexConfig(config));
+/** Generates a migration file and returns its path. */
+const makeMigration = async (name, config) => {
+    try {
+        return await getDB().migrate.make(name, resolveMigrationConfig(config));
+    }
+    catch (error) {
+        throw toError(error);
+    }
+};
+/** Runs pending migrations and returns the batch number and migration filenames. */
+const migrateLatest = async (config) => {
+    try {
+        const [batch, log] = await getDB().migrate.latest(resolveMigrationConfig(config));
+        return { batch, log };
+    }
+    catch (error) {
+        throw toError(error);
+    }
+};
+/** Rolls back migrations. Set `all` to true to rollback all completed batches. */
+const migrateRollback = async (config, all = false) => {
+    try {
+        const [batch, log] = all
+            ? await getDB().migrate.rollback(resolveMigrationConfig(config), true)
+            : await getDB().migrate.rollback(resolveMigrationConfig(config));
+        return { batch, log };
+    }
+    catch (error) {
+        throw toError(error);
+    }
+};
+/** Returns the current migration version recorded by Knex. */
+const migrateCurrentVersion = async (config) => {
+    try {
+        return await getDB().migrate.currentVersion(resolveMigrationConfig(config));
+    }
+    catch (error) {
+        throw toError(error);
+    }
+};
+/** Returns completed and pending migration filenames. */
+const migrateList = async (config) => {
+    try {
+        const [completed, pending] = await getDB().migrate.list(resolveMigrationConfig(config));
+        const toName = (entry) => {
+            if (typeof entry === 'string') {
+                return entry;
+            }
+            if (entry && typeof entry === 'object') {
+                if ('name' in entry) {
+                    return String(entry.name);
+                }
+                if ('file' in entry) {
+                    return String(entry.file);
+                }
+            }
+            return String(entry);
+        };
+        return {
+            completed: completed.map(toName),
+            pending: pending.map(toName),
+        };
+    }
+    catch (error) {
+        throw toError(error);
+    }
+};
+export { DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, };

package/dist/src/model.d.ts

@@ -0,0 +1,51 @@
+import type { Knex } from 'knex';
+type Row = Record<string, unknown>;
+declare class Model {
+    #private;
+    [key: string]: any;
+    static currentTable: string;
+    static currentQuery: Knex.QueryBuilder<Row, Row[]> | undefined;
+    fillable: string[];
+    hidden: string[];
+    modelName: string;
+    table: string;
+    id?: number;
+    constructor(properties?: Row);
+    /** Inserts the current model using `fillable` attributes and reloads it from the database. */
+    save(): Promise<this>;
+    /** Updates the current row by primary key and returns a refreshed model instance. */
+    update(properties: Row): Promise<this>;
+    /** Deletes the current row by primary key. */
+    delete(): Promise<void>;
+    /** Updates rows in the model table, optionally scoped by `where()`. */
+    static update(properties: Row): Promise<number | undefined>;
+    /** Deletes rows in the model table, optionally scoped by `where()`. */
+    static destroy(): Promise<number | undefined>;
+    /** Finds a single model by primary key. */
+    static find(this: typeof Model, id: number | string, columns?: string | string[]): Promise<Model | null>;
+    /** Finds a model by primary key or throws if it does not exist. */
+    static findOrFail(this: typeof Model, id: number | string, columns?: string | string[]): Promise<Model>;
+    /** Creates and returns a single model record. */
+    static create(this: typeof Model, properties: Row): Promise<Model>;
+    /** Creates multiple model records and returns created model instances. */
+    static createMany(this: typeof Model, properties: Row[]): Promise<Model[]>;
+    /** Returns the first matching row or creates it with merged values when missing. */
+    static firstOrCreate(this: typeof Model, attributes: Row, values?: Row): Promise<Model>;
+    /** Applies a query scope used by chained static query methods. */
+    static where(this: typeof Model, conditions?: Row): typeof Model;
+    /** Returns the first model for the current scope (or table if unscoped). */
+    static first(this: typeof Model, columns?: string | string[]): Promise<Model | null>;
+    /** Returns all models for the current scope (or table if unscoped). */
+    static all(this: typeof Model, columns?: string | string[]): Promise<Model[]>;
+    /** Returns a row count for the current scope (or table if unscoped). */
+    static count(this: typeof Model, column?: string): Promise<number>;
+    /** Removes internal and hidden fields from a model instance. */
+    stripColumns<T extends Model>(model: T, keepInternalState?: boolean): T;
+}
+interface Model {
+    hasOne(Related: typeof Model, localKey?: number | string, foreignKey?: string): Promise<Model | null>;
+    hasMany(Related: typeof Model, localKey?: number | string, foreignKey?: string): Promise<Model[]>;
+    belongsTo(Related: typeof Model, foreignKey?: string, ownerKey?: string): Promise<Model | null>;
+}
+export { Model };
+export { DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, } from './config.js';