mevn-orm 3.2.1 → 4.0.0

package/README.md

@@ -1,61 +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'
+})
+
+setMigrationConfig({
+  directory: './migrations',
+  extension: 'ts'
 })
-````
 
-## Features
+await makeMigration('create_users_table')
+await migrateLatest()
+const { completed, pending } = await migrateList()
+await migrateRollback(undefined, false) // rollback last batch
+```
 
-* 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
+Repository migration commands (no `knexfile` required):
 
-## ORM Basics Checklist
+```bash
+pnpm run migrate
+pnpm run migrate:make -- create_users_table
+pnpm run migrate:rollback
+pnpm run migrate:list
+pnpm run migrate:version
+```
 
-* [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
+## Security Notes
 
-## Testing
+- 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 [Vitest](https://vitest.dev/) for testing.
+## Development (Repository)
 
 ```bash
-npm install
-npm run migrate
-npm run test
+pnpm install
+pnpm run migrate
+pnpm run test
+pnpm run typecheck
 ```
 
 ## License

package/index.ts

@@ -0,0 +1,31 @@
+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/initDb.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import 'dotenv/config'
+import type { Knex } from 'knex'
+import knexModule from 'knex'
+
+interface KnexEnvConfig {
+	development: Knex.Config
+	staging: Knex.Config
+	production: Knex.Config
+}
+
+type KnexFactory = (config: Knex.Config) => Knex
+
+const KnexFactoryImpl: KnexFactory =
+	(knexModule as unknown as { knex?: KnexFactory }).knex ??
+	(knexModule as unknown as KnexFactory)
+
+const knexfilePath = `${process.cwd()}/knexfile.ts`
+if (!existsSync(knexfilePath)) {
+	throw new Error('knexfile.ts not found in current working directory')
+}
+
+const knexConfigModule = await import(pathToFileURL(knexfilePath).href)
+const knexConfig = (knexConfigModule.default ?? knexConfigModule) as Partial<KnexEnvConfig>
+const { development, staging, production } = knexConfig
+
+if (!development || !staging || !production) {
+	throw new Error('knexfile.ts must export development, staging, and production config')
+}
+
+const config: Knex.Config = (() => {
+	switch (process.env.NODE_ENV) {
+	case 'testing':
+	case 'test':
+	case 'development':
+		return development
+	case 'staging':
+		return staging
+	default:
+		return production
+	}
+})()
+
+const initDatabase = async (): Promise<void> => {
+	const DB = KnexFactoryImpl(config)
+
+	try {
+		await DB.schema.dropTableIfExists('farmers')
+		await DB.schema.dropTableIfExists('farms')
+		await DB.schema.dropTableIfExists('profiles')
+		await DB.schema.dropTableIfExists('articles')
+
+		await DB.schema.createTable('farmers', (table: Knex.CreateTableBuilder) => {
+			table.bigIncrements('id')
+			table.string('name')
+			table.string('email').unique()
+			table.string('password')
+		})
+
+		await DB.schema.createTable('farms', (table: Knex.CreateTableBuilder) => {
+			table.bigIncrements('id')
+			table.bigInteger('farmer_id')
+			table.string('name')
+		})
+
+		await DB.schema.createTable('profiles', (table: Knex.CreateTableBuilder) => {
+			table.bigIncrements('id')
+			table.bigInteger('farmer_id')
+			table.string('bio')
+		})
+
+		await DB.schema.createTable('articles', (table: Knex.CreateTableBuilder) => {
+			table.bigIncrements('id')
+			table.string('title')
+			table.text('body')
+			table.bigInteger('postable_id')
+			table.string('postable_type')
+		})
+
+		await DB.table('Farmers').insert([
+			{ name: 'Jane Doe', email: 'jane@mail.com', password: 'pasword' },
+			{ name: 'Ashley Doe', email: 'ashley@mail.com', password: 'pasword' },
+			{ name: 'Alice Doe', email: 'alice@mail.com', password: 'pasword' },
+		])
+
+		await DB.table('farms').insert([
+			{ farmer_id: 1, name: 'Awesome Farm' },
+			{ farmer_id: 1, name: 'Awesome Farm two' },
+			{ farmer_id: 1, name: 'Awesome Farm three' },
+		])
+
+		await DB.table('profiles').insert([{ farmer_id: 1, bio: 'Profile for farmer one' }])
+
+		await DB.table('articles').insert([
+			{
+				title: 'Awesome Post',
+				body: 'fffgjdfjdbdb something #1',
+				postable_id: 1,
+				postable_type: 'Farmer',
+			},
+		])
+
+		process.exit(0)
+	} catch (error: unknown) {
+		console.error(error)
+		process.exit(1)
+	}
+}
+
+await initDatabase()

package/knexfile.ts

@@ -0,0 +1,46 @@
+import type { Knex } from 'knex'
+
+const config = {
+	development: {
+		client: 'sqlite3',
+		connection: {
+			filename: './dev.sqlite',
+		},
+		useNullAsDefault: true,
+		migrations: {
+			tableName: 'migrations',
+		},
+	},
+	staging: {
+		client: process.env.DB_CLIENT ?? 'mysql2',
+		connection: {
+			database: process.env.DB_DATABASE ?? 'my_db',
+			user: process.env.DB_USER ?? 'username',
+			password: process.env.DB_PASSWORD ?? 'password',
+		},
+		pool: {
+			min: 2,
+			max: 10,
+		},
+		migrations: {
+			tableName: 'migrations',
+		},
+	},
+	production: {
+		client: process.env.DB_CLIENT ?? 'mysql2',
+		connection: {
+			database: process.env.DB_DATABASE ?? 'my_db',
+			user: process.env.DB_USER ?? 'username',
+			password: process.env.DB_PASSWORD ?? 'password',
+		},
+		pool: {
+			min: 2,
+			max: 10,
+		},
+		migrations: {
+			tableName: 'migrations',
+		},
+	},
+} satisfies Record<'development' | 'staging' | 'production', Knex.Config>
+
+export default config

package/package.json

@@ -1,24 +1,13 @@
 {
   "name": "mevn-orm",
-  "version": "3.2.1",
+  "version": "4.0.0",
   "description": "simple ORM for express js",
-  "type": "commonjs",
-  "scripts": {
-    "pretest": "node initDb",
-    "test": "mocha --exit",
-    "init:db": "node initDb",
-    "migrate": "knex migrate:latest",
-    "lint": "eslint --ext .js ./"
-  },
+  "type": "module",
   "peerDependencies": {
-    "dotenv": "^17.0.1",
     "knex": "^3.0.0",
     "mysql2": "^3.9.3"
   },
   "peerDependenciesMeta": {
-    "dotenv": {
-      "optional": false
-    },
     "knex": {
       "optional": false
     }
@@ -46,16 +35,18 @@
     "@babel/core": "^7.24.5",
     "@babel/eslint-parser": "^7.24.3",
     "@babel/eslint-plugin": "^7.24.0",
-    "@faker-js/faker": "^9.8.0",
-    "chai": "^4.4.1",
+    "@types/node": "^24.6.0",
+    "@faker-js/faker": "^10.0.0",
     "dotenv": "^17.0.1",
     "knex": "^3.0.0",
-    "mocha": "^10.4.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
     "mysql": "^2.18.1",
     "sqlite3": "^5.1.7"
   },
   "directories": {
-    "lib": "lib",
+    "src": "src",
     "test": "test"
   },
   "private": false,
@@ -65,5 +56,17 @@
     "email": "stanleymasinde1@gmail.com"
   },
   "homepage": "https://github.com/StanleyMasinde/mevn-orm#readme",
-  "main": "index.js"
-}
+  "main": "index.ts",
+  "scripts": {
+    "pretest": "node --import tsx initDb.ts",
+    "test": "vitest run",
+    "init:db": "node --import tsx initDb.ts",
+    "typecheck": "tsc --noEmit",
+    "migrate": "node --import tsx scripts/migrate.ts latest",
+    "migrate:make": "node --import tsx scripts/migrate.ts make",
+    "migrate:rollback": "node --import tsx scripts/migrate.ts rollback",
+    "migrate:list": "node --import tsx scripts/migrate.ts list",
+    "migrate:version": "node --import tsx scripts/migrate.ts version",
+    "lint": "eslint --ext .js,.ts ./"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,9 @@
+onlyBuiltDependencies:
+  - esbuild
+  - sqlite3
+
+overrides:
+  diff@>=6.0.0 <8.0.3: '>=8.0.3'
+  tar@<7.5.7: '>=7.5.7'
+  tar@<=7.5.2: '>=7.5.3'
+  tar@<=7.5.3: '>=7.5.4'