mevn-orm 3.2.2 → 4.0.1

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,17 +1,13 @@
 {
   "name": "mevn-orm",
-  "version": "3.2.2",
+  "version": "4.0.1",
   "description": "simple ORM for express js",
-  "type": "commonjs",
+  "type": "module",
   "peerDependencies": {
-    "dotenv": "^17.0.1",
     "knex": "^3.0.0",
     "mysql2": "^3.9.3"
   },
   "peerDependenciesMeta": {
-    "dotenv": {
-      "optional": false
-    },
     "knex": {
       "optional": false
     }
@@ -39,16 +35,18 @@
     "@babel/core": "^7.24.5",
     "@babel/eslint-parser": "^7.24.3",
     "@babel/eslint-plugin": "^7.24.0",
+    "@types/node": "^24.6.0",
     "@faker-js/faker": "^10.0.0",
-    "chai": "^6.2.0",
     "dotenv": "^17.0.1",
     "knex": "^3.0.0",
-    "mocha": "^11.7.4",
+    "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,
@@ -58,12 +56,29 @@
     "email": "stanleymasinde1@gmail.com"
   },
   "homepage": "https://github.com/StanleyMasinde/mevn-orm#readme",
-  "main": "index.js",
+  "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 initDb",
-    "test": "mocha --exit",
-    "init:db": "node initDb",
-    "migrate": "knex migrate:latest",
-    "lint": "eslint --ext .js ./"
+    "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 ./",
+    "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

package/.eslintrc.json

@@ -1,36 +0,0 @@
-{
-    "env": {
-        "commonjs": true,
-        "es2021": true,
-        "node": true
-    },
-    "extends": "eslint:recommended",
-    "plugins": ["@babel"],
-    "parser": "@babel/eslint-parser",
-    "parserOptions": {
-        "ecmaVersion": 12
-    },
-    "rules": {
-        "no-console":"warn",
-        "constructor-super":"off",
-        "no-this-before-super":"off",
-        "arrow-parens":"error",
-        "class-methods-use-this":"error",
-        "indent": [
-            "error",
-            "tab"
-        ],
-        "linebreak-style": [
-            "error",
-            "unix"
-        ],
-        "quotes": [
-            "error",
-            "single"
-        ],
-        "semi": [
-            "error",
-            "never"
-        ]
-    }
-}

package/.gitattributes

@@ -1,8 +0,0 @@
-.github export-ignore
-_config.yml export-ignore
-.gitignore export-ignore
-CODE_OF_CONDUCT.md export-ignore
-SECURITY.md export-ignore
-test export-ignore
-test.sh export-ignore
-initDb export-ignore

package/CODE_OF_CONDUCT.md

@@ -1,76 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
- advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
- address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
- professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at stanleyoren@gmail.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq