@veap/database 0.0.0-stage → 0.1.0

package/dist/relations/morph-to-many.js

@@ -0,0 +1,215 @@
+import { getKnex } from "../connection";
+import { MorphMap } from "./morph-map";
+import { Relation } from "./relation";
+/**
+ * MorphToMany represents a many-to-many polymorphic relation where the parent
+ * owns the polymorphic side of the pivot table (e.g. BlogPost -> tags via taggables).
+ * Pivot columns: ${morphName}_id, ${morphName}_type, ${relatedPivotKey}
+ */
+export class MorphToMany extends Relation {
+    morphName;
+    pivotTable;
+    foreignPivotKey;
+    relatedPivotKey;
+    morphTypeColumn;
+    relatedKey;
+    morphType;
+    constructor(parent, related, morphName, pivotTable, foreignPivotKey, relatedPivotKey, morphTypeColumn, localKey = parent.constructor.primaryKey || "id", relatedKey = related.primaryKey || "id") {
+        super(parent, related, foreignPivotKey, localKey);
+        this.morphName = morphName;
+        this.pivotTable = pivotTable;
+        this.foreignPivotKey = foreignPivotKey;
+        this.relatedPivotKey = relatedPivotKey;
+        this.morphTypeColumn = morphTypeColumn;
+        this.relatedKey = relatedKey;
+        this.morphType = MorphMap.getMorphAlias(parent);
+    }
+    query() {
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        const relatedTable = this.related.table;
+        return this.related
+            .query()
+            .join(this.pivotTable, `${relatedTable}.${this.relatedKey}`, `${this.pivotTable}.${this.relatedPivotKey}`)
+            .where(`${this.pivotTable}.${this.foreignPivotKey}`, localKeyValue)
+            .where(`${this.pivotTable}.${this.morphTypeColumn}`, this.morphType);
+    }
+    async get() {
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        if (localKeyValue === null || localKeyValue === undefined) {
+            return [];
+        }
+        return await this.query().get();
+    }
+    async attach(relatedId, extraAttributes = {}) {
+        const knex = getKnex();
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        const ids = Array.isArray(relatedId) ? relatedId : [relatedId];
+        const rows = ids.map((id) => ({
+            [this.foreignPivotKey]: localKeyValue,
+            [this.morphTypeColumn]: this.morphType,
+            [this.relatedPivotKey]: id,
+            ...extraAttributes,
+        }));
+        await knex(this.pivotTable).insert(rows);
+    }
+    async detach(relatedId) {
+        const knex = getKnex();
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        let q = knex(this.pivotTable)
+            .where(this.foreignPivotKey, localKeyValue)
+            .where(this.morphTypeColumn, this.morphType);
+        if (relatedId !== undefined) {
+            if (Array.isArray(relatedId)) {
+                q = q.whereIn(this.relatedPivotKey, relatedId);
+            }
+            else {
+                q = q.where(this.relatedPivotKey, relatedId);
+            }
+        }
+        await q.delete();
+    }
+    async sync(ids) {
+        await this.detach();
+        if (ids.length > 0) {
+            await this.attach(ids);
+        }
+    }
+    async match(parents, relationName) {
+        const localKeys = Array.from(new Set(parents
+            .map((p) => p.getAttribute(this.localKey))
+            .filter((key) => key !== null && key !== undefined)));
+        if (localKeys.length === 0) {
+            for (const parent of parents) {
+                parent.setRelation(relationName, []);
+            }
+            return;
+        }
+        const knex = getKnex();
+        const relatedTable = this.related.table;
+        const rows = await knex(relatedTable)
+            .join(this.pivotTable, `${relatedTable}.${this.relatedKey}`, `${this.pivotTable}.${this.relatedPivotKey}`)
+            .whereIn(`${this.pivotTable}.${this.foreignPivotKey}`, localKeys)
+            .where(`${this.pivotTable}.${this.morphTypeColumn}`, this.morphType)
+            .select(`${relatedTable}.*`, `${this.pivotTable}.${this.foreignPivotKey} as _pivot_foreign_key`);
+        const lookup = new Map();
+        for (const row of rows) {
+            const parentFk = row._pivot_foreign_key;
+            delete row._pivot_foreign_key;
+            const model = new this.related(row, false);
+            if (!lookup.has(parentFk)) {
+                lookup.set(parentFk, []);
+            }
+            lookup.get(parentFk).push(model);
+        }
+        for (const parent of parents) {
+            const lk = parent.getAttribute(this.localKey);
+            parent.setRelation(relationName, lookup.get(lk) || []);
+        }
+    }
+}
+/**
+ * MorphedByMany represents the inverse of MorphToMany (e.g. Tag -> posts via taggables).
+ * Pivot columns: ${relatedPivotKey} (tag_id), ${foreignPivotKey} (taggable_id), ${morphTypeColumn} (taggable_type)
+ */
+export class MorphedByMany extends Relation {
+    morphName;
+    pivotTable;
+    foreignPivotKey;
+    relatedPivotKey;
+    morphTypeColumn;
+    relatedKey;
+    morphType;
+    constructor(parent, related, morphName, pivotTable, foreignPivotKey, relatedPivotKey, morphTypeColumn, localKey = parent.constructor.primaryKey || "id", relatedKey = related.primaryKey || "id") {
+        super(parent, related, foreignPivotKey, localKey);
+        this.morphName = morphName;
+        this.pivotTable = pivotTable;
+        this.foreignPivotKey = foreignPivotKey;
+        this.relatedPivotKey = relatedPivotKey;
+        this.morphTypeColumn = morphTypeColumn;
+        this.relatedKey = relatedKey;
+        // In inverse, the morphType is the target related model (e.g. "post")
+        this.morphType = MorphMap.getMorphAlias(related);
+    }
+    query() {
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        const relatedTable = this.related.table;
+        return this.related
+            .query()
+            .join(this.pivotTable, `${relatedTable}.${this.relatedKey}`, `${this.pivotTable}.${this.foreignPivotKey}`)
+            .where(`${this.pivotTable}.${this.relatedPivotKey}`, localKeyValue)
+            .where(`${this.pivotTable}.${this.morphTypeColumn}`, this.morphType);
+    }
+    async get() {
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        if (localKeyValue === null || localKeyValue === undefined) {
+            return [];
+        }
+        return await this.query().get();
+    }
+    async attach(relatedId, extraAttributes = {}) {
+        const knex = getKnex();
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        const ids = Array.isArray(relatedId) ? relatedId : [relatedId];
+        const rows = ids.map((id) => ({
+            [this.relatedPivotKey]: localKeyValue,
+            [this.morphTypeColumn]: this.morphType,
+            [this.foreignPivotKey]: id,
+            ...extraAttributes,
+        }));
+        await knex(this.pivotTable).insert(rows);
+    }
+    async detach(relatedId) {
+        const knex = getKnex();
+        const localKeyValue = this.parent.getAttribute(this.localKey);
+        let q = knex(this.pivotTable)
+            .where(this.relatedPivotKey, localKeyValue)
+            .where(this.morphTypeColumn, this.morphType);
+        if (relatedId !== undefined) {
+            if (Array.isArray(relatedId)) {
+                q = q.whereIn(this.foreignPivotKey, relatedId);
+            }
+            else {
+                q = q.where(this.foreignPivotKey, relatedId);
+            }
+        }
+        await q.delete();
+    }
+    async sync(ids) {
+        await this.detach();
+        if (ids.length > 0) {
+            await this.attach(ids);
+        }
+    }
+    async match(parents, relationName) {
+        const localKeys = Array.from(new Set(parents
+            .map((p) => p.getAttribute(this.localKey))
+            .filter((key) => key !== null && key !== undefined)));
+        if (localKeys.length === 0) {
+            for (const parent of parents) {
+                parent.setRelation(relationName, []);
+            }
+            return;
+        }
+        const knex = getKnex();
+        const relatedTable = this.related.table;
+        const rows = await knex(relatedTable)
+            .join(this.pivotTable, `${relatedTable}.${this.relatedKey}`, `${this.pivotTable}.${this.foreignPivotKey}`)
+            .whereIn(`${this.pivotTable}.${this.relatedPivotKey}`, localKeys)
+            .where(`${this.pivotTable}.${this.morphTypeColumn}`, this.morphType)
+            .select(`${relatedTable}.*`, `${this.pivotTable}.${this.relatedPivotKey} as _pivot_parent_key`);
+        const lookup = new Map();
+        for (const row of rows) {
+            const parentFk = row._pivot_parent_key;
+            delete row._pivot_parent_key;
+            const model = new this.related(row, false);
+            if (!lookup.has(parentFk)) {
+                lookup.set(parentFk, []);
+            }
+            lookup.get(parentFk).push(model);
+        }
+        for (const parent of parents) {
+            const lk = parent.getAttribute(this.localKey);
+            parent.setRelation(relationName, lookup.get(lk) || []);
+        }
+    }
+}

package/dist/relations/morph-to.d.ts

@@ -0,0 +1,19 @@
+import type { Model } from "../model";
+import type { ModelQueryBuilder } from "../query-builder";
+import { Relation } from "./relation";
+export declare class MorphTo<Child extends Model = any, Parent extends Model = any> extends Relation<Child, Parent> {
+    morphName: string;
+    typeColumn: string;
+    idColumn: string;
+    constructor(parent: Child, morphName: string, typeColumn: string, idColumn: string);
+    /**
+     * Resolves the parent model class based on child's type column value.
+     */
+    resolveModel(): any;
+    query(): ModelQueryBuilder<Parent>;
+    get(): Promise<Parent | null>;
+    /**
+     * Eager load polymorphic parents for multiple children in bulk queries grouped by morph type.
+     */
+    match(children: Child[], relationName: string): Promise<void>;
+}

package/dist/relations/morph-to.js

@@ -0,0 +1,90 @@
+import { DatabaseError } from "../errors";
+import { MorphMap } from "./morph-map";
+import { Relation } from "./relation";
+export class MorphTo extends Relation {
+    morphName;
+    typeColumn;
+    idColumn;
+    constructor(parent, morphName, typeColumn, idColumn) {
+        // The related model class will be dynamically resolved from typeColumn
+        super(parent, null, idColumn, "id");
+        this.morphName = morphName;
+        this.typeColumn = typeColumn;
+        this.idColumn = idColumn;
+    }
+    /**
+     * Resolves the parent model class based on child's type column value.
+     */
+    resolveModel() {
+        const typeValue = this.parent.getAttribute(this.typeColumn);
+        if (!typeValue) {
+            return null;
+        }
+        const modelClass = MorphMap.getModel(typeValue);
+        if (!modelClass) {
+            throw DatabaseError.Internal(`[veap:ORM] Cannot resolve polymorphic model for morph type "${typeValue}". Did you register it with MorphMap.register()?`);
+        }
+        return modelClass;
+    }
+    query() {
+        const modelClass = this.resolveModel();
+        if (!modelClass) {
+            throw DatabaseError.Internal(`[veap:ORM] Cannot create query for morphTo relation "${this.morphName}" because type column "${this.typeColumn}" is null.`);
+        }
+        const idValue = this.parent.getAttribute(this.idColumn);
+        const pk = modelClass.primaryKey || "id";
+        return modelClass.query().where(pk, idValue);
+    }
+    async get() {
+        const modelClass = this.resolveModel();
+        const idValue = this.parent.getAttribute(this.idColumn);
+        if (!modelClass || !idValue) {
+            return null;
+        }
+        const pk = modelClass.primaryKey || "id";
+        const result = await modelClass.query().where(pk, idValue).first();
+        return result || null;
+    }
+    /**
+     * Eager load polymorphic parents for multiple children in bulk queries grouped by morph type.
+     */
+    async match(children, relationName) {
+        // Group child records by morph type: typeValue -> ids
+        const typeToIds = new Map();
+        for (const child of children) {
+            const typeValue = child.getAttribute(this.typeColumn);
+            const idValue = child.getAttribute(this.idColumn);
+            if (typeValue && idValue) {
+                if (!typeToIds.has(typeValue)) {
+                    typeToIds.set(typeValue, new Set());
+                }
+                typeToIds.get(typeValue).add(idValue);
+            }
+        }
+        // Lookup map: `${typeValue}:${idValue}` -> Parent instance
+        const lookup = new Map();
+        // For each unique type, execute ONE bulk query (e.g. BlogPost.query().whereIn('id', ids))
+        for (const [typeValue, idSet] of typeToIds.entries()) {
+            const modelClass = MorphMap.getModel(typeValue);
+            if (!modelClass) {
+                continue;
+            }
+            const pk = modelClass.primaryKey || "id";
+            const parents = await modelClass
+                .query()
+                .whereIn(pk, Array.from(idSet))
+                .get();
+            for (const parent of parents) {
+                const id = parent.getAttribute(pk);
+                lookup.set(`${typeValue}:${id}`, parent);
+            }
+        }
+        // Attach resolved parent to each child
+        for (const child of children) {
+            const typeValue = child.getAttribute(this.typeColumn);
+            const idValue = child.getAttribute(this.idColumn);
+            const key = `${typeValue}:${idValue}`;
+            child.setRelation(relationName, lookup.get(key) || null);
+        }
+    }
+}

package/dist/relations/relation.d.ts

@@ -0,0 +1,22 @@
+import type { Model } from "../model";
+import type { ModelQueryBuilder } from "../query-builder";
+export declare abstract class Relation<Parent extends Model = any, Related extends Model = any> {
+    parent: Parent;
+    related: any;
+    foreignKey: string;
+    localKey: string;
+    constructor(parent: Parent, related: any, // typeof Model
+    foreignKey: string, localKey: string);
+    /**
+     * Returns a new query builder pre-scoped for this relation.
+     */
+    abstract query(): ModelQueryBuilder<Related>;
+    /**
+     * Fetches the related model(s) for the parent instance.
+     */
+    abstract get(): Promise<any>;
+    /**
+     * Eager loads related models for an array of parents in a single bulk query (N+1 solver).
+     */
+    abstract match(parents: Parent[], relationName: string): Promise<void>;
+}

package/dist/relations/relation.js

@@ -0,0 +1,13 @@
+export class Relation {
+    parent;
+    related;
+    foreignKey;
+    localKey;
+    constructor(parent, related, // typeof Model
+    foreignKey, localKey) {
+        this.parent = parent;
+        this.related = related;
+        this.foreignKey = foreignKey;
+        this.localKey = localKey;
+    }
+}

package/dist/scopes.d.ts

@@ -0,0 +1,16 @@
+import type { Model } from "./model";
+import type { ModelQueryBuilder } from "./query-builder";
+/**
+ * Callback function for applying a global scope.
+ */
+export type GlobalScopeCallback<M extends Model = any> = (builder: ModelQueryBuilder<M>, modelClass: any) => void;
+/**
+ * Interface for class-based global scopes.
+ */
+export interface Scope<M extends Model = any> {
+    apply(builder: ModelQueryBuilder<M>, modelClass: any): void;
+}
+/**
+ * Type representing either a callback or a Scope object.
+ */
+export type GlobalScope<M extends Model = any> = GlobalScopeCallback<M> | Scope<M>;

package/dist/scopes.js

@@ -0,0 +1 @@
+export {};

package/dist/seeder.d.ts

@@ -0,0 +1,25 @@
+export type SeederClass = new () => Seeder;
+/**
+ * Base Database Seeder class.
+ */
+export declare abstract class Seeder {
+    /**
+     * Run the database seeds.
+     */
+    abstract run(): Promise<void>;
+    /**
+     * Run additional seeders sequentially.
+     */
+    call(seeders: SeederClass[] | SeederClass): Promise<void>;
+}
+export interface RunSeedersOptions {
+    /**
+     * Whether to wrap all seeders execution inside a single database transaction.
+     * Defaults to false.
+     */
+    inTransaction?: boolean;
+}
+/**
+ * Runs one or multiple Seeders.
+ */
+export declare function runSeeders(seeders: SeederClass[] | SeederClass, options?: RunSeedersOptions): Promise<void>;

package/dist/seeder.js

@@ -0,0 +1,49 @@
+import { transaction } from "./connection";
+import { debug, info, warn } from "./logger";
+/**
+ * Base Database Seeder class.
+ */
+export class Seeder {
+    /**
+     * Run additional seeders sequentially.
+     */
+    async call(seeders) {
+        const list = Array.isArray(seeders) ? seeders : [seeders];
+        for (const SeederCtor of list) {
+            const seederName = SeederCtor.name || "Seeder";
+            info("veap:Seeder", `Running seeder: ${seederName}`);
+            const startTime = Date.now();
+            try {
+                const instance = new SeederCtor();
+                await instance.run();
+                const duration = Date.now() - startTime;
+                debug("veap:Seeder", `Completed seeder: ${seederName} (${duration}ms)`);
+            }
+            catch (error) {
+                warn("veap:Seeder", `Failed to run seeder: ${seederName}`, error);
+                throw error;
+            }
+        }
+    }
+}
+/**
+ * Runs one or multiple Seeders.
+ */
+export async function runSeeders(seeders, options = {}) {
+    const runner = async () => {
+        const rootSeeder = new (class extends Seeder {
+            async run() {
+                await this.call(seeders);
+            }
+        })();
+        await rootSeeder.run();
+    };
+    if (options.inTransaction) {
+        await transaction(async () => {
+            await runner();
+        });
+    }
+    else {
+        await runner();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+import type { Knex } from "knex";
+export interface DatabaseConfig extends Knex.Config {
+    driver?: "postgres" | "sqlite" | "mysql";
+}
+export interface PostgresSslOptions {
+    databaseUrl: string;
+    isProd: boolean;
+    rejectUnauthorizedEnv?: string;
+    caCert?: string;
+}
+export type PostgresSslConfig = false | {
+    rejectUnauthorized: boolean;
+    ca?: string;
+};
+export interface TransactionOptions {
+    /**
+     * When true and called inside an existing transaction, creates a SAVEPOINT
+     * instead of reusing the outer transaction directly. This allows catching
+     * errors in the inner transaction without aborting the outer transaction.
+     *
+     * @default false (Propagation: REQUIRED - reuses outer transaction)
+     */
+    savepoint?: boolean;
+}
+export interface PaginationResult<T> {
+    data: T[];
+    total: number;
+    perPage: number;
+    currentPage: number;
+    lastPage: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts camelCase to snake_case.
+ * Handles dotted notation (e.g. 'table.columnName' -> 'table.column_name').
+ */
+export declare function toSnakeCase(str: string): string;
+/**
+ * Converts snake_case to camelCase.
+ */
+export declare function toCamelCase(str: string): string;

package/dist/utils.js

@@ -0,0 +1,20 @@
+/**
+ * Converts camelCase to snake_case.
+ * Handles dotted notation (e.g. 'table.columnName' -> 'table.column_name').
+ */
+export function toSnakeCase(str) {
+    if (!str)
+        return str;
+    if (str.includes(".")) {
+        return str.split(".").map(toSnakeCase).join(".");
+    }
+    return str.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+/**
+ * Converts snake_case to camelCase.
+ */
+export function toCamelCase(str) {
+    if (!str)
+        return str;
+    return str.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@veap/database",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Eloquent-like Active Record ORM powered by Knex with AsyncLocalStorage transactions",
+  "bugs": "https://github.com/veapjs/veap-database/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/veapjs/veap-database.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "rimraf dist && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@veap/kernel": "^0.1.0",
+    "better-sqlite3": "^13.0.3",
+    "knex": "^3.3.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.16.3"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^22.20.2",
+    "@types/pg": "^8.16.0",
+    "pg": "^8.16.3",
+    "rimraf": "^6.1.3",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.0"
+  }
+}