mevn-orm 4.0.0 → 4.0.1

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';

package/dist/src/model.js

@@ -0,0 +1,243 @@
+import pluralize from 'pluralize';
+import { getDB } from './config.js';
+import { createRelationshipMethods } from './relationships.js';
+const toError = (error) => {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+};
+class Model {
+    #private;
+    static currentTable = pluralize(this.name.toLowerCase());
+    // `where()` stores a static scoped query consumed by `first()`.
+    static currentQuery;
+    fillable;
+    hidden;
+    modelName;
+    table;
+    id;
+    constructor(properties = {}) {
+        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() {
+        try {
+            const rows = {};
+            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();
+            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) {
+        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();
+            if (!fields) {
+                throw new Error(`Failed to load updated record for table "${this.table}"`);
+            }
+            const next = new this.constructor(fields);
+            return this.stripColumns(next);
+        }
+        catch (error) {
+            throw toError(error);
+        }
+    }
+    /** Deletes the current row by primary key. */
+    async delete() {
+        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) {
+        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() {
+        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(id, columns = '*') {
+        const table = pluralize(this.name.toLowerCase());
+        try {
+            const fields = await getDB()(table).where({ id }).first(columns);
+            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(id, columns = '*') {
+        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(properties) {
+        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();
+            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(properties) {
+        if (properties.length === 0) {
+            return [];
+        }
+        try {
+            const records = [];
+            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(attributes, values = {}) {
+        const table = pluralize(this.name.toLowerCase());
+        try {
+            const record = await getDB()(table).where(attributes).first();
+            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(conditions = {}) {
+        const table = pluralize(this.name.toLowerCase());
+        this.currentQuery = getDB()(table).where(conditions);
+        return this;
+    }
+    /** Returns the first model for the current scope (or table if unscoped). */
+    static async first(columns = '*') {
+        try {
+            const table = pluralize(this.name.toLowerCase());
+            const query = this.currentQuery ?? getDB()(table);
+            const rows = await query.first(columns);
+            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(columns = '*') {
+        try {
+            const table = pluralize(this.name.toLowerCase());
+            const query = this.currentQuery ?? getDB()(table);
+            const rows = await query.select(columns);
+            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(column = '*') {
+        try {
+            const table = pluralize(this.name.toLowerCase());
+            const query = this.currentQuery ?? getDB()(table);
+            const result = await query.count({ 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(model, keepInternalState = false) {
+        // 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;
+    }
+}
+Object.assign(Model.prototype, createRelationshipMethods(getDB));
+export { Model };
+export { DB, getDB, configure, createKnexConfig, configureDatabase, setMigrationConfig, getMigrationConfig, makeMigration, migrateLatest, migrateRollback, migrateCurrentVersion, migrateList, } from './config.js';

package/dist/src/relationships.d.ts

@@ -0,0 +1,18 @@
+import type { Knex } from 'knex';
+type Row = Record<string, unknown>;
+interface RelationshipModel {
+    [key: string]: unknown;
+    table: string;
+    modelName: string;
+    id?: number | string;
+    stripColumns<T extends RelationshipModel>(model: T, keepInternalState?: boolean): T;
+}
+type RelatedModelCtor = new (properties?: Row) => RelationshipModel;
+interface RelationshipMethods {
+    hasOne(this: RelationshipModel, Related: RelatedModelCtor, localKey?: number | string, foreignKey?: string): Promise<RelationshipModel | null>;
+    hasMany(this: RelationshipModel, Related: RelatedModelCtor, localKey?: number | string, foreignKey?: string): Promise<RelationshipModel[]>;
+    belongsTo(this: RelationshipModel, Related: RelatedModelCtor, foreignKey?: string, ownerKey?: string): Promise<RelationshipModel | null>;
+}
+/** Builds relationship methods that run against the active Knex instance. */
+declare const createRelationshipMethods: (getDB: () => Knex) => RelationshipMethods;
+export { createRelationshipMethods };

package/dist/src/relationships.js

@@ -0,0 +1,50 @@
+/** Builds relationship methods that run against the active Knex instance. */
+const createRelationshipMethods = (getDB) => ({
+    async hasOne(Related, localKey, foreignKey) {
+        const table = new Related().table;
+        const relation = {};
+        const keyValue = localKey ?? this.id;
+        const relationKey = foreignKey ?? `${this.modelName}_id`;
+        if (keyValue !== undefined) {
+            relation[relationKey] = keyValue;
+            const result = await getDB()(table).where(relation).first();
+            if (result) {
+                const related = new Related(result);
+                return related.stripColumns(related);
+            }
+        }
+        return null;
+    },
+    async hasMany(Related, localKey, foreignKey) {
+        const table = new Related().table;
+        const relation = {};
+        const keyValue = localKey ?? this.id;
+        const relationKey = foreignKey ?? `${this.modelName}_id`;
+        if (keyValue === undefined) {
+            return [];
+        }
+        relation[relationKey] = keyValue;
+        const rows = await getDB()(table).where(relation).select('*');
+        return rows.map((row) => {
+            const related = new Related(row);
+            return related.stripColumns(related);
+        });
+    },
+    async belongsTo(Related, foreignKey, ownerKey = 'id') {
+        const table = new Related().table;
+        const relation = {};
+        const relationKey = foreignKey ?? `${new Related().modelName}_id`;
+        const relationValue = this[relationKey];
+        if (relationValue === undefined || relationValue === null) {
+            return null;
+        }
+        relation[ownerKey] = relationValue;
+        const row = await getDB()(table).where(relation).first();
+        if (!row) {
+            return null;
+        }
+        const related = new Related(row);
+        return related.stripColumns(related);
+    },
+});
+export { createRelationshipMethods };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mevn-orm",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "simple ORM for express js",
   "type": "module",
   "peerDependencies": {
@@ -56,7 +56,18 @@
     "email": "stanleymasinde1@gmail.com"
   },
   "homepage": "https://github.com/StanleyMasinde/mevn-orm#readme",
-  "main": "index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "pretest": "node --import tsx initDb.ts",
     "test": "vitest run",
@@ -67,6 +78,7 @@
     "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 ./"
+    "lint": "eslint --ext .js,.ts ./",
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/.env.example

@@ -1,9 +0,0 @@
-NODE_ENV=testing
-
-DB_HOST=localhost
-DB_USER=root
-DB_PASSWORD=
-DB_DATABASE=mevn_orm
-DB_CLIENT=mysql2
-
-TESTING_DB=sqlite3