mevn-orm 3.2.1 → 4.0.0

package/scripts/migrate.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import {
+	configureDatabase,
+	setMigrationConfig,
+	makeMigration,
+	migrateLatest,
+	migrateRollback,
+	migrateList,
+	migrateCurrentVersion,
+} from '../index.js'
+
+const [command = 'latest', name] = process.argv.slice(2)
+
+const databaseConfig: Parameters<typeof configureDatabase>[0] = {
+	dialect: (process.env.DB_DIALECT as
+		| 'sqlite'
+		| 'better-sqlite3'
+		| 'mysql'
+		| 'mysql2'
+		| 'postgres'
+		| 'postgresql'
+		| 'pg'
+		| 'pgnative'
+		| 'cockroachdb'
+		| 'redshift'
+		| 'mssql'
+		| 'oracledb'
+		| 'oracle') ?? 'sqlite',
+	filename: process.env.DB_FILENAME ?? './dev.sqlite',
+}
+
+if (process.env.DATABASE_URL) {
+	databaseConfig.connectionString = process.env.DATABASE_URL
+}
+if (process.env.DB_HOST) {
+	databaseConfig.host = process.env.DB_HOST
+}
+if (process.env.DB_PORT) {
+	databaseConfig.port = Number(process.env.DB_PORT)
+}
+if (process.env.DB_USER) {
+	databaseConfig.user = process.env.DB_USER
+}
+if (process.env.DB_PASSWORD) {
+	databaseConfig.password = process.env.DB_PASSWORD
+}
+if (process.env.DB_NAME) {
+	databaseConfig.database = process.env.DB_NAME
+}
+if (process.env.DB_SSL === 'true') {
+	databaseConfig.ssl = true
+}
+
+configureDatabase(databaseConfig)
+
+setMigrationConfig({
+	directory: process.env.MIGRATIONS_DIR ?? './migrations',
+	extension: process.env.MIGRATIONS_EXT ?? 'ts',
+})
+
+const run = async (): Promise<void> => {
+	switch (command) {
+	case 'make': {
+		if (!name) {
+			throw new Error('Usage: node --import tsx scripts/migrate.ts make <name>')
+		}
+		const file = await makeMigration(name)
+		console.log(file)
+		return
+	}
+	case 'latest': {
+		const result = await migrateLatest()
+		console.log(JSON.stringify(result, null, 2))
+		return
+	}
+	case 'rollback': {
+		const all = process.argv.includes('--all')
+		const result = await migrateRollback(undefined, all)
+		console.log(JSON.stringify(result, null, 2))
+		return
+	}
+	case 'list': {
+		const result = await migrateList()
+		console.log(JSON.stringify(result, null, 2))
+		return
+	}
+	case 'version': {
+		const version = await migrateCurrentVersion()
+		console.log(version)
+		return
+	}
+	default:
+		throw new Error(`Unknown command "${command}". Use make|latest|rollback|list|version`)
+	}
+}
+
+await run()

package/src/config.ts

@@ -0,0 +1,270 @@
+import type { Knex } from 'knex'
+import knexModule from 'knex'
+
+type KnexFactory = (config: Knex.Config) => Knex
+
+const knexFactory: KnexFactory =
+	(knexModule as unknown as { knex?: KnexFactory }).knex ??
+	(knexModule as unknown as KnexFactory)
+
+const toError = (error: unknown): Error => {
+	if (error instanceof Error) {
+		return error
+	}
+
+	return new Error(String(error))
+}
+
+let DB: Knex | undefined
+let defaultMigrationConfig: Knex.MigratorConfig = {}
+
+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. */
+const getDB = (): Knex => {
+	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: Knex.Config | Knex): Knex => {
+	if (typeof config === 'function') {
+		DB = config
+		return DB
+	}
+
+	DB = knexFactory(config)
+	return DB
+}
+
+/** Sets default migration options used by migration helpers. */
+const setMigrationConfig = (config: Knex.MigratorConfig): Knex.MigratorConfig => {
+	defaultMigrationConfig = { ...config }
+	return { ...defaultMigrationConfig }
+}
+
+/** Returns the currently configured default migration options. */
+const getMigrationConfig = (): Knex.MigratorConfig => ({ ...defaultMigrationConfig })
+
+const resolveMigrationConfig = (config?: Knex.MigratorConfig): Knex.MigratorConfig => ({
+	...defaultMigrationConfig,
+	...(config ?? {}),
+})
+
+const normalizeDialect = (dialect: SimpleDialect): string => {
+	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: unknown, field: string, dialect: string): void => {
+	if (value === undefined || value === null || value === '') {
+		throw new Error(`Missing required field "${field}" for dialect "${dialect}".`)
+	}
+}
+
+const buildConnection = (config: SimpleDatabaseConfig): NonNullable<Knex.Config['connection']> => {
+	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 as string }
+	}
+
+	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: Record<string, unknown> = {
+			server: server as string,
+			user: config.user as string,
+			database: config.database as string,
+		}
+		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: Record<string, unknown> = {
+		host: config.host as string,
+		user: config.user as string,
+		database: config.database as string,
+	}
+	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: SimpleDatabaseConfig): Knex.Config => {
+	const client = normalizeDialect(config.dialect)
+	const base: Knex.Config = {
+		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: SimpleDatabaseConfig): Knex => configure(createKnexConfig(config))
+
+/** Generates a migration file and returns its path. */
+const makeMigration = async (name: string, config?: Knex.MigratorConfig): Promise<string> => {
+	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?: Knex.MigratorConfig): Promise<MigrationResult> => {
+	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?: Knex.MigratorConfig, all = false): Promise<MigrationResult> => {
+	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?: Knex.MigratorConfig): Promise<string> => {
+	try {
+		return await getDB().migrate.currentVersion(resolveMigrationConfig(config))
+	} catch (error) {
+		throw toError(error)
+	}
+}
+
+/** Returns completed and pending migration filenames. */
+const migrateList = async (config?: Knex.MigratorConfig): Promise<{ completed: string[]; pending: string[] }> => {
+	try {
+		const [completed, pending] = await getDB().migrate.list(resolveMigrationConfig(config))
+		const toName = (entry: unknown): string => {
+			if (typeof entry === 'string') {
+				return entry
+			}
+			if (entry && typeof entry === 'object') {
+				if ('name' in entry) {
+					return String((entry as { name: unknown }).name)
+				}
+				if ('file' in entry) {
+					return String((entry as { file: unknown }).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/src/model.ts

@@ -0,0 +1,301 @@
+import type { Knex } from 'knex'
+import pluralize from 'pluralize'
+import { getDB } from './config.js'
+import { createRelationshipMethods } from './relationships.js'
+
+type Row = Record<string, unknown>
+
+const toError = (error: unknown): Error => {
+	if (error instanceof Error) {
+		return error
+	}
+
+	return new Error(String(error))
+}
+
+class Model {
+	[key: string]: any
+
+	#private: string[]
+
+	static currentTable: string = pluralize(this.name.toLowerCase())
+	// `where()` stores a static scoped query consumed by `first()`.
+	static currentQuery: Knex.QueryBuilder<Row, Row[]> | undefined
+
+	fillable: string[]
+	hidden: string[]
+	modelName: string
+	table: string
+	id?: number
+
+	constructor(properties: Row = {}) {
+		Object.assign(this, properties)
+		this.fillable = []
+		this.hidden = []
+		this.#private = ['fillable', 'hidden']
+		this.modelName = this.constructor.name.toLowerCase()
+		this.table = pluralize(this.constructor.name.toLowerCase())
+	}
+
+	/** Inserts the current model using `fillable` attributes and reloads it from the database. */
+	async save(): Promise<this> {
+		try {
+			const rows: Row = {}
+			for (const field of this.fillable) {
+				rows[field] = this[field]
+			}
+
+			const inserted = await getDB()(this.table).insert(rows)
+			const idValue = Array.isArray(inserted) ? inserted[0] : inserted
+			const id = typeof idValue === 'bigint' ? Number(idValue) : Number(idValue)
+			const fields = await getDB()(this.table).where({ id }).first<Row>()
+
+			if (!fields) {
+				throw new Error(`Failed to load inserted record for table "${this.table}"`)
+			}
+
+			Object.assign(this, fields)
+			this.id = id
+			return this.stripColumns(this, true)
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Updates the current row by primary key and returns a refreshed model instance. */
+	async update(properties: Row): Promise<this> {
+		if (this.id === undefined) {
+			throw new Error('Cannot update model without id')
+		}
+
+		try {
+			await getDB()(this.table).where({ id: this.id }).update(properties)
+			const fields = await getDB()(this.table).where({ id: this.id }).first<Row>()
+
+			if (!fields) {
+				throw new Error(`Failed to load updated record for table "${this.table}"`)
+			}
+
+			const next = new (this.constructor as new (props: Row) => this)(fields)
+			return this.stripColumns(next)
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Deletes the current row by primary key. */
+	async delete(): Promise<void> {
+		if (this.id === undefined) {
+			throw new Error('Cannot delete model without id')
+		}
+
+		try {
+			await getDB()(this.table).where({ id: this.id }).del()
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Updates rows in the model table, optionally scoped by `where()`. */
+	static async update(properties: Row): Promise<number | undefined> {
+		try {
+			const table = pluralize(this.name.toLowerCase())
+			const query = this.currentQuery ?? getDB()(table)
+			return await query.update(properties)
+		} catch (error) {
+			throw toError(error)
+		} finally {
+			this.currentQuery = undefined
+		}
+	}
+
+	/** Deletes rows in the model table, optionally scoped by `where()`. */
+	static async destroy(): Promise<number | undefined> {
+		try {
+			const table = pluralize(this.name.toLowerCase())
+			const query = this.currentQuery ?? getDB()(table)
+			return await query.delete()
+		} catch (error) {
+			throw toError(error)
+		} finally {
+			this.currentQuery = undefined
+		}
+	}
+
+	/** Finds a single model by primary key. */
+	static async find(this: typeof Model, id: number | string, columns: string | string[] = '*'): Promise<Model | null> {
+		const table = pluralize(this.name.toLowerCase())
+
+		try {
+			const fields = await getDB()(table).where({ id }).first<Row>(columns as never)
+			return fields ? new this(fields) : null
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Finds a model by primary key or throws if it does not exist. */
+	static async findOrFail(this: typeof Model, id: number | string, columns: string | string[] = '*'): Promise<Model> {
+		const found = await this.find(id, columns)
+		if (!found) {
+			throw new Error(`${this.name} with id "${id}" not found`)
+		}
+
+		return found
+	}
+
+	/** Creates and returns a single model record. */
+	static async create(this: typeof Model, properties: Row): Promise<Model> {
+		const table = pluralize(this.name.toLowerCase())
+
+		try {
+			const inserted = await getDB()(table).insert(properties)
+			const idValue = Array.isArray(inserted) ? inserted[0] : inserted
+			const id = typeof idValue === 'bigint' ? Number(idValue) : Number(idValue)
+			const record = await getDB()(table).where({ id }).first<Row>()
+
+			if (!record) {
+				throw new Error(`Failed to load created record for table "${table}"`)
+			}
+
+			const model = new this(record)
+			return model.stripColumns(model)
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Creates multiple model records and returns created model instances. */
+	static async createMany(this: typeof Model, properties: Row[]): Promise<Model[]> {
+		if (properties.length === 0) {
+			return []
+		}
+
+		try {
+			const records: Model[] = []
+			for (const property of properties) {
+				records.push(await this.create(property))
+			}
+			return records
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Returns the first matching row or creates it with merged values when missing. */
+	static async firstOrCreate(this: typeof Model, attributes: Row, values: Row = {}): Promise<Model> {
+		const table = pluralize(this.name.toLowerCase())
+		try {
+			const record = await getDB()(table).where(attributes).first<Row>()
+			if (record) {
+				const model = new this(record)
+				return model.stripColumns(model)
+			}
+
+			return this.create({ ...attributes, ...values })
+		} catch (error) {
+			throw toError(error)
+		}
+	}
+
+	/** Applies a query scope used by chained static query methods. */
+	static where(this: typeof Model, conditions: Row = {}): typeof Model {
+		const table = pluralize(this.name.toLowerCase())
+		this.currentQuery = getDB()(table).where(conditions) as Knex.QueryBuilder<Row, Row[]>
+		return this
+	}
+
+	/** Returns the first model for the current scope (or table if unscoped). */
+	static async first(this: typeof Model, columns: string | string[] = '*'): Promise<Model | null> {
+		try {
+			const table = pluralize(this.name.toLowerCase())
+			const query = this.currentQuery ?? getDB()(table)
+			const rows = await query.first<Row>(columns as never)
+			return rows ? new this(rows) : null
+		} catch (error) {
+			throw toError(error)
+		} finally {
+			this.currentQuery = undefined
+		}
+	}
+
+	/** Returns all models for the current scope (or table if unscoped). */
+	static async all(this: typeof Model, columns: string | string[] = '*'): Promise<Model[]> {
+		try {
+			const table = pluralize(this.name.toLowerCase())
+			const query = this.currentQuery ?? getDB()(table)
+			const rows = await query.select<Row[]>(columns as never)
+			return rows.map((row) => new this(row))
+		} catch (error) {
+			throw toError(error)
+		} finally {
+			this.currentQuery = undefined
+		}
+	}
+
+	/** Returns a row count for the current scope (or table if unscoped). */
+	static async count(this: typeof Model, column = '*'): Promise<number> {
+		try {
+			const table = pluralize(this.name.toLowerCase())
+			const query = this.currentQuery ?? getDB()(table)
+			const result = await query.count<{ count: string | number }>({ count: column }).first()
+			if (!result) {
+				return 0
+			}
+
+			return Number(result.count)
+		} catch (error) {
+			throw toError(error)
+		} finally {
+			this.currentQuery = undefined
+		}
+	}
+
+	/** Removes internal and hidden fields from a model instance. */
+	stripColumns<T extends Model>(model: T, keepInternalState = false): T {
+		// Hide internal ORM fields and caller-defined hidden attributes.
+		const privateKeys = keepInternalState ? [] : this.#private
+		const hiddenKeys = Array.isArray(this.hidden) ? this.hidden : []
+		for (const key of [...privateKeys, ...hiddenKeys]) {
+			delete model[key]
+		}
+
+		return model
+	}
+}
+
+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>
+}
+
+Object.assign(Model.prototype, createRelationshipMethods(getDB) as Pick<Model, 'hasOne' | 'hasMany' | 'belongsTo'>)
+
+export { Model }
+export {
+	DB,
+	getDB,
+	configure,
+	createKnexConfig,
+	configureDatabase,
+	setMigrationConfig,
+	getMigrationConfig,
+	makeMigration,
+	migrateLatest,
+	migrateRollback,
+	migrateCurrentVersion,
+	migrateList,
+} from './config.js'