mevn-orm 3.2.2 → 4.0.1

package/README.md

@@ -1,63 +1,385 @@
 # Mevn ORM
 
-![npm](https://img.shields.io/npm/v/mevn-orm?style=for-the-badge)  [![GitHub license](https://img.shields.io/github/license/stanleymasinde/mevn-orm?style=for-the-badge)](https://github.com/StanleyMasinde/mevn-orm/blob/master/LICENSE)  ![GitHub issues](https://img.shields.io/github/issues/stanleymasinde/mevn-orm?style=for-the-badge)
+![npm](https://img.shields.io/npm/v/mevn-orm?style=for-the-badge)
+[![GitHub license](https://img.shields.io/github/license/stanleymasinde/mevn-orm?style=for-the-badge)](https://github.com/StanleyMasinde/mevn-orm/blob/master/LICENSE)
+![GitHub issues](https://img.shields.io/github/issues/stanleymasinde/mevn-orm?style=for-the-badge)
 
-### Do not use This
-When I started this, I had so much intertest in the JS ecosytem and ORMs. I still have some intertest in javascript
-bit not ORMs.
+Mevn ORM is a small ActiveRecord-style ORM built on top of Knex.
 
-**Mevn ORM** is a lightweight ORM for Express.js and MySQL that provides a clean, fluent interface for building queries and managing models.
-It is under maintenance mode and receives security updates. Development is paused, but the core ORM functionality is complete and usable.
+It exports:
+- `Model`: base class for your models
+- `configureDatabase`: initialize with simple DB options by dialect
+- `configure`: initialize with raw Knex config (advanced)
+- migration helpers: `makeMigration`, `migrateLatest`, `migrateRollback`, `migrateList`, `migrateCurrentVersion`
+- `DB`: initialized Knex instance (after `configure`)
 
-## Getting Started
+## Status
 
-```javascript
-const { Model } = require('mevn-orm')
+This project is in maintenance mode. Core functionality works, but new features are limited.
 
-class User extends Model {}
+## Requirements
 
-const user = await User.create({
-  name: 'John Doe',
-  email: 'john@example.com',
-  password: 'secret' // hash before storing
+- Node.js 20+ (ESM runtime)
+- Database driver for your selected client (`mysql2`, `sqlite3`, etc.)
+
+## Installation
+
+```bash
+npm install mevn-orm knex mysql2
+```
+
+For SQLite development/testing:
+
+```bash
+npm install sqlite3
+```
+
+## Quick Start
+
+### 1) Configure Mevn ORM
+
+```ts
+import { configureDatabase } from 'mevn-orm'
+
+configureDatabase({
+  dialect: 'sqlite',
+  filename: './dev.sqlite'
+})
+```
+
+Supported dialects:
+- `sqlite`, `better-sqlite3`
+- `mysql`, `mysql2`
+- `postgres`, `postgresql`, `pg`, `pgnative`
+- `cockroachdb`, `redshift`
+- `mssql`
+- `oracledb`, `oracle`
+
+Connection styles:
+- `connectionString` for one-string connection setup
+- field-based setup (`host`, `port`, `user`, `password`, `database`)
+- sqlite file setup via `filename`
+
+### 2) Define a model
+
+```ts
+import { Model } from 'mevn-orm'
+
+class User extends Model {
+  override fillable = ['name', 'email', 'password']
+  override hidden = ['password']
+}
+```
+
+### 3) Use it
+
+```ts
+const created = await User.create({
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  password: 'hash-me-first'
+})
+
+const found = await User.find(created.id as number)
+await found?.update({ name: 'Jane Updated' })
+```
+
+## API Reference
+
+### 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>`
+
+## Using `DB` directly
+
+You can always drop down to Knex after configuration:
+
+```ts
+import { configureDatabase, DB } from 'mevn-orm'
+
+configureDatabase({
+  dialect: 'sqlite',
+  filename: './dev.sqlite'
+})
+const users = await DB('users').select('*')
+```
+
+## More Configuration Examples
+
+```ts
+import { configureDatabase } from 'mevn-orm'
+
+// MySQL / mysql2
+configureDatabase({
+  dialect: 'mysql',
+  host: '127.0.0.1',
+  port: 3306,
+  user: 'root',
+  password: 'secret',
+  database: 'app_db'
+})
+
+// Postgres
+configureDatabase({
+  dialect: 'postgres',
+  connectionString: process.env.DATABASE_URL
+})
+
+// MSSQL
+configureDatabase({
+  dialect: 'mssql',
+  host: '127.0.0.1',
+  user: 'sa',
+  password: 'StrongPassword!',
+  database: 'app_db',
+  ssl: true
+})
+```
+
+## Nuxt/Nitro Example
+
+Use a server plugin to initialize 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.
+
+`nuxt.config.ts`:
+
+```ts
+import { cp } from 'node:fs/promises'
+
+export default defineNuxtConfig({
+  nitro: {
+    hooks: {
+      compiled: async () => {
+        await cp('server/assets/migrations', '.output/server/assets/migrations', {
+          recursive: true
+        })
+      }
+    }
+  }
+})
+```
+
+`server/plugins/mevn-orm.ts`:
+
+```ts
+import { defineNitroPlugin } from 'nitropack/runtime'
+import { existsSync } from 'node:fs'
+import {
+  configureDatabase,
+  setMigrationConfig,
+  migrateLatest,
+  migrateRollback
+} from 'mevn-orm'
+
+const isIgnorableMigrationError = (error: unknown): boolean => {
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
+  return (
+    message.includes('already exists') ||
+    message.includes('duplicate') ||
+    message.includes('does not exist') ||
+    message.includes('no such table') ||
+    message.includes('the migration directory is corrupt')
+  )
+}
+
+export default defineNitroPlugin(async () => {
+  configureDatabase({
+    dialect: 'postgres',
+    connectionString: process.env.DATABASE_URL
+  })
+
+  // Nitro runtime path differs in dev vs built server.
+  const migrationDirectory = existsSync('./.output/server/assets/migrations')
+    ? './.output/server/assets/migrations'
+    : './server/assets/migrations'
+
+  setMigrationConfig({
+    directory: migrationDirectory,
+    extension: 'ts'
+  })
+
+  // Idempotent at boot: if already migrated, Knex returns empty log.
+  try {
+    await migrateLatest()
+  } catch (error) {
+    if (!isIgnorableMigrationError(error)) {
+      throw error
+    }
+  }
+
+  // Optional rollback at boot (usually only for dev/preview).
+  if (process.env.NITRO_ROLLBACK_ON_BOOT === 'true') {
+    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
+    }
+  }
+})
+```
+
+## Migrations
+
+Migrations are now programmatic and use Knex’s migration API under the hood.
+
+```ts
+import {
+  configureDatabase,
+  setMigrationConfig,
+  makeMigration,
+  migrateLatest,
+  migrateRollback,
+  migrateList
+} from 'mevn-orm'
+
+configureDatabase({
+  dialect: 'sqlite',
+  filename: './dev.sqlite'
 })
-````
 
-## Features
+setMigrationConfig({
+  directory: './migrations',
+  extension: 'ts'
+})
 
-* Model-based abstraction
-* Create, Read, Update, Delete support
-* Chainable query builder (`where`, `first`, `all`)
-* Timestamps
-* Soft deletes
-* SQLite support for testing
-* Knex-based migration support
+await makeMigration('create_users_table')
+await migrateLatest()
+const { completed, pending } = await migrateList()
+await migrateRollback(undefined, false) // rollback last batch
+```
 
-## ORM Basics Checklist
+Repository migration commands (no `knexfile` required):
 
-* [x] `Model` base class
-* [x] `.create`, `.find`, `.update`, `.delete`
-* [x] `.where()`, `.first()`, `.all()` chaining
-* [x] Table name inference
-* [x] Timestamps
-* [x] Soft deletes
-* [x] Basic relationship hooks (`hasOne`, `hasMany`, `belongsTo`)
-* [x] Raw queries
-* [x] Knex passthrough
-* [x] SQLite3 test DB
-* [x] Uses `mysql2` for production
-* [x] `dotenv` support
+```bash
+pnpm run migrate
+pnpm run migrate:make -- create_users_table
+pnpm run migrate:rollback
+pnpm run migrate:list
+pnpm run migrate:version
+```
 
-## Testing
+## Security Notes
 
-Use Node.js 24.x (LTS) with pnpm.
+- Hash passwords before calling `create()` or `save()`.
+- Validate and sanitize input before persisting.
+- Keep `knex`, DB drivers, and Node.js versions up to date.
 
-This project uses [Mocha](https://mochajs.org/) for testing.
+## Development (Repository)
 
 ```bash
 pnpm install
 pnpm run migrate
 pnpm run test
+pnpm run typecheck
 ```
 
 ## License

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, };