@veap/database 0.0.0-stage → 0.1.1

package/dist/factory.js

@@ -0,0 +1,161 @@
+import { DatabaseError } from "./errors.js";
+export class Factory {
+    static get registry() {
+        const g = globalThis;
+        if (!g.__VEAP_FACTORY_REGISTRY__) {
+            g.__VEAP_FACTORY_REGISTRY__ = new Map();
+        }
+        return g.__VEAP_FACTORY_REGISTRY__;
+    }
+    /**
+     * Registers a factory class/instance for a model.
+     */
+    static register(modelClass, factoryOrFactoryFn) {
+        this.registry.set(modelClass, factoryOrFactoryFn);
+    }
+    /**
+     * Gets the registered factory for a model if one exists.
+     */
+    static getForModel(modelClass) {
+        return this.registry.get(modelClass);
+    }
+    modelClass;
+    countNumber = 1;
+    states = [];
+    sequenceItems = [];
+    constructor(modelClass) {
+        if (modelClass) {
+            this.modelClass = modelClass;
+        }
+    }
+    /**
+     * Sets the number of models that should be generated.
+     */
+    count(amount) {
+        this.countNumber = Math.max(1, amount);
+        return this;
+    }
+    /**
+     * Applies an attribute state transformation to the factory.
+     */
+    state(override) {
+        this.states.push(override);
+        return this;
+    }
+    /**
+     * Applies sequential states rotating through the given items.
+     */
+    sequence(...items) {
+        this.sequenceItems.push(...items);
+        return this;
+    }
+    /**
+     * Generates the raw attributes dictionary for a single model instance.
+     */
+    async raw(override = {}, index = 0) {
+        let attributes = await this.definition();
+        // Apply sequence if provided
+        if (this.sequenceItems.length > 0) {
+            const seqState = this.sequenceItems[index % this.sequenceItems.length];
+            attributes = { ...attributes, ...seqState };
+        }
+        // Apply states
+        for (const stateItem of this.states) {
+            if (typeof stateItem === "function") {
+                attributes = { ...attributes, ...stateItem(attributes) };
+            }
+            else {
+                attributes = { ...attributes, ...stateItem };
+            }
+        }
+        // Apply direct overrides
+        attributes = { ...attributes, ...override };
+        return attributes;
+    }
+    /**
+     * Creates a single model instance in memory without saving to database.
+     */
+    async makeOne(override = {}, index = 0) {
+        if (!this.modelClass) {
+            throw DatabaseError.Internal("[veap:Factory] Model class is not defined for this factory.");
+        }
+        const attributes = await this.raw(override, index);
+        return new this.modelClass(attributes, true);
+    }
+    /**
+     * Creates model instance(s) in memory without saving to database.
+     */
+    async make(override = {}) {
+        if (this.countNumber === 1) {
+            return await this.makeOne(override, 0);
+        }
+        const instances = [];
+        for (let i = 0; i < this.countNumber; i++) {
+            instances.push(await this.makeOne(override, i));
+        }
+        return instances;
+    }
+    /**
+     * Creates and persists a single model instance to the database.
+     */
+    async createOne(override = {}, index = 0) {
+        const instance = await this.makeOne(override, index);
+        await instance.save();
+        return instance;
+    }
+    /**
+     * Creates and persists model instance(s) to the database.
+     */
+    async create(override = {}) {
+        if (this.countNumber === 1) {
+            return await this.createOne(override, 0);
+        }
+        const instances = [];
+        for (let i = 0; i < this.countNumber; i++) {
+            instances.push(await this.createOne(override, i));
+        }
+        return instances;
+    }
+}
+/**
+ * Generic factory implementation used by defineFactory helper.
+ */
+class GenericFactory extends Factory {
+    definitionFn;
+    constructor(modelClass, definitionFn) {
+        super(modelClass);
+        this.definitionFn = definitionFn;
+    }
+    async definition() {
+        return await this.definitionFn();
+    }
+}
+/**
+ * Convenient helper to define a Model Factory in a single concise call.
+ */
+export function defineFactory(modelClass, definitionFn) {
+    const FactoryClass = class extends GenericFactory {
+        constructor() {
+            super(modelClass, definitionFn);
+        }
+    };
+    const factoryCallable = function (count) {
+        const instance = new FactoryClass();
+        if (count !== undefined) {
+            instance.count(count);
+        }
+        return instance;
+    };
+    // Attach static factory shortcuts
+    factoryCallable.count = (amount) => factoryCallable().count(amount);
+    factoryCallable.state = (override) => factoryCallable().state(override);
+    factoryCallable.sequence = (...items) => factoryCallable().sequence(...items);
+    factoryCallable.make = (override) => factoryCallable().make(override);
+    factoryCallable.makeOne = (override) => factoryCallable().makeOne(override);
+    factoryCallable.create = (override) => factoryCallable().create(override);
+    factoryCallable.createOne = (override) => factoryCallable().createOne(override);
+    // Allow `new UserFactory()`
+    Object.setPrototypeOf(factoryCallable, FactoryClass);
+    factoryCallable.prototype = FactoryClass.prototype;
+    return factoryCallable;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { default as knex, type Knex } from "knex";
+export * from "./casts.js";
+export * from "./composition.js";
+export * from "./connection.js";
+export * from "./errors.js";
+export * from "./events.js";
+export * from "./factory.js";
+export * from "./logger.js";
+export * from "./migration-provider.js";
+export * from "./migrations/index.js";
+export * from "./model.js";
+export * from "./provider.js";
+export * from "./query-builder.js";
+export * from "./relations/index.js";
+export * from "./scopes.js";
+export * from "./seeder.js";
+export * from "./tokens.js";
+export * from "./types.js";
+export * from "./utils.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+export { default as knex } from "knex";
+export * from "./casts.js";
+export * from "./composition.js";
+export * from "./connection.js";
+export * from "./errors.js";
+export * from "./events.js";
+export * from "./factory.js";
+export * from "./logger.js";
+export * from "./migration-provider.js";
+export * from "./migrations/index.js";
+export * from "./model.js";
+export * from "./provider.js";
+export * from "./query-builder.js";
+export * from "./relations/index.js";
+export * from "./scopes.js";
+export * from "./seeder.js";
+export * from "./tokens.js";
+export * from "./types.js";
+export * from "./utils.js";

package/dist/logger.d.ts

@@ -0,0 +1,11 @@
+export interface DatabaseLogger {
+    debug(channel: string, message: string, ...args: any[]): void;
+    info(channel: string, message: string, ...args: any[]): void;
+    warn(channel: string, message: string, ...args: any[]): void;
+    error(channel: string, message: string, ...args: any[]): void;
+}
+export declare function setDatabaseLogger(logger: DatabaseLogger): void;
+export declare function debug(channel: string, message: string, ...args: any[]): void;
+export declare function info(channel: string, message: string, ...args: any[]): void;
+export declare function warn(channel: string, message: string, ...args: any[]): void;
+export declare function error(channel: string, message: string, ...args: any[]): void;

package/dist/logger.js

@@ -0,0 +1,21 @@
+let activeLogger = {
+    debug: (_channel, _message, ..._args) => { },
+    info: (channel, message, ..._args) => console.info(`[${channel}] ${message}`),
+    warn: (channel, message, ..._args) => console.warn(`[${channel}] ${message}`),
+    error: (channel, message, ..._args) => console.error(`[${channel}] ${message}`),
+};
+export function setDatabaseLogger(logger) {
+    activeLogger = logger;
+}
+export function debug(channel, message, ...args) {
+    activeLogger.debug(channel, message, ...args);
+}
+export function info(channel, message, ...args) {
+    activeLogger.info(channel, message, ...args);
+}
+export function warn(channel, message, ...args) {
+    activeLogger.warn(channel, message, ...args);
+}
+export function error(channel, message, ...args) {
+    activeLogger.error(channel, message, ...args);
+}

package/dist/migration-provider.d.ts

@@ -0,0 +1,7 @@
+import { ServiceProvider } from "@veap/kernel";
+export declare class MigrationServiceProvider extends ServiceProvider {
+    private migrations?;
+    constructor(container: any, migrations?: any[]);
+    register(): void;
+    boot(): Promise<void>;
+}

package/dist/migration-provider.js

@@ -0,0 +1,36 @@
+import { ServiceProvider } from "@veap/kernel";
+import { runMigrations } from "./migrations/runner.js";
+import { APP_MIGRATIONS } from "./tokens.js";
+export class MigrationServiceProvider extends ServiceProvider {
+    migrations;
+    constructor(container, migrations) {
+        super(container);
+        this.migrations = migrations;
+    }
+    register() {
+        if (this.migrations?.length) {
+            this.container.register({
+                token: APP_MIGRATIONS,
+                useValue: this.migrations,
+            });
+            this.container.register({
+                token: "AppMigrations",
+                useValue: this.migrations,
+            });
+        }
+    }
+    async boot() {
+        let appMigrations = this.migrations;
+        if (!appMigrations?.length) {
+            if (this.container.has(APP_MIGRATIONS)) {
+                appMigrations = await this.container.resolve(APP_MIGRATIONS);
+            }
+            else if (this.container.has("AppMigrations")) {
+                appMigrations = await this.container.resolve("AppMigrations");
+            }
+        }
+        if (appMigrations?.length) {
+            await runMigrations("app", appMigrations);
+        }
+    }
+}

package/dist/migrations/generator.d.ts

@@ -0,0 +1,4 @@
+export declare function generateMigration(name: string, targetDir?: string): Promise<{
+    fileName: string;
+    filePath: string;
+}>;

package/dist/migrations/generator.js

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const stub = `import type { Schema } from "@veap/database";
+
+export default {
+  name: "{{name}}",
+  async up(_db: any, schema: Schema) {
+    await schema.createTable("{{tableName}}", (table) => {
+      table.increments("id");
+
+      table.timestamps();
+    });
+  },
+  async down(_db: any, schema: Schema) {
+    await schema.dropTableIfExists("{{tableName}}");
+  },
+};
+`;
+async function updateIndexFile(migrationsDir) {
+    const indexFile = path.join(migrationsDir, "index.ts");
+    const files = await fs.readdir(migrationsDir);
+    const migrationFiles = files
+        .filter((f) => f.endsWith(".ts") && f !== "index.ts")
+        .sort();
+    const imports = [];
+    const exports = [];
+    for (const file of migrationFiles) {
+        const name = file.replace(".ts", "");
+        const varName = `m${name.replace(/[^a-zA-Z0-9]/g, "_")}`;
+        imports.push(`import { default as ${varName} } from "./${name}";`);
+        exports.push(varName);
+    }
+    const content = `// This file is auto-generated by Veap CLI. Do not edit manually.
+${imports.join("\n")}
+
+export const appMigrations = [
+  ${exports.join(",\n  ")}
+];
+`;
+    await fs.writeFile(indexFile, content, "utf-8");
+}
+export async function generateMigration(name, targetDir) {
+    const timestamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+    const fileName = `${timestamp}_${name}`;
+    let tableName = name;
+    if (name.startsWith("create_") && name.endsWith("_table")) {
+        tableName = name.replace("create_", "").replace("_table", "");
+    }
+    const content = stub
+        .replace(/{{name}}/g, fileName)
+        .replace(/{{tableName}}/g, tableName);
+    const migrationsDir = targetDir || path.join(process.cwd(), "migrations");
+    await fs.mkdir(migrationsDir, { recursive: true });
+    const filePath = path.join(migrationsDir, `${fileName}.ts`);
+    await fs.writeFile(filePath, content, "utf-8");
+    await updateIndexFile(migrationsDir);
+    return { fileName, filePath };
+}

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./generator.js";
+export * from "./runner.js";
+export * from "./schema-builder.js";

package/dist/migrations/index.js

@@ -0,0 +1,3 @@
+export * from "./generator.js";
+export * from "./runner.js";
+export * from "./schema-builder.js";

package/dist/migrations/runner.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "./schema-builder.js";
+export interface Migration {
+    name: string;
+    up: (db: any, schema: Schema) => Promise<void>;
+    down?: (db: any, schema: Schema) => Promise<void>;
+}
+export declare function runMigrations(scope: string, migrations: Migration[]): Promise<void>;
+/**
+ * Modern static migration rollback runner.
+ * Reverts migrations in reverse order.
+ */
+export declare function rollbackMigrations(scope: string, migrations: Migration[]): Promise<void>;

package/dist/migrations/runner.js

@@ -0,0 +1,179 @@
+import crypto from "node:crypto";
+import { getKnex } from "../connection.js";
+import { debug, warn } from "../logger.js";
+import { Schema } from "./schema-builder.js";
+async function ensureMigrationsTable(knex = getKnex()) {
+    try {
+        const hasTable = await knex.schema.hasTable("migrations");
+        if (!hasTable) {
+            await knex.schema.createTable("migrations", (table) => {
+                table.text("id").primary();
+                table.text("name").notNullable();
+                table.integer("batch").notNullable();
+                table.timestamp("executed_at").defaultTo(knex.fn.now()).notNullable();
+                table.text("scope").notNullable().defaultTo("global");
+            });
+        }
+        else {
+            const hasScope = await knex.schema.hasColumn("migrations", "scope");
+            if (!hasScope) {
+                await knex.schema.alterTable("migrations", (table) => {
+                    table.text("scope").notNullable().defaultTo("global");
+                });
+            }
+        }
+    }
+    catch (error) {
+        warn("veap:migration", "Failed to ensure migrations table:", error);
+    }
+}
+async function acquireAdvisoryLockIfPostgres(tx, knex) {
+    const clientName = knex?.client?.config?.client || "";
+    if (typeof clientName === "string" &&
+        (clientName.includes("pg") || clientName.includes("postgres"))) {
+        const lockId = 123456;
+        try {
+            await tx.raw("SELECT pg_advisory_xact_lock(?)", [lockId]);
+        }
+        catch (_e) {
+            debug("veap:migration", "Could not acquire advisory lock, continuing...");
+        }
+    }
+}
+/**
+ * Creates a compatibility DB adapter for migrations that provides `.execute(query)`
+ * wrapping `trx.raw(query)`, while also being directly callable as a Knex query builder
+ * on the active migration transaction `trx(tableName)`.
+ */
+function createMigrationDbAdapter(trx) {
+    const adapter = (tableName) => trx(tableName);
+    adapter.raw = (query, ...bindings) => trx.raw(query, ...bindings);
+    adapter.execute = (query) => {
+        const sqlString = typeof query === "string"
+            ? query
+            : query?.query || query?.text || String(query);
+        return trx.raw(sqlString);
+    };
+    return new Proxy(adapter, {
+        get(target, prop, receiver) {
+            if (prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            return Reflect.get(trx, prop);
+        },
+        apply(target, thisArg, argArray) {
+            return trx(...argArray);
+        },
+    });
+}
+export async function runMigrations(scope, migrations) {
+    if (migrations.length === 0)
+        return;
+    let knex;
+    try {
+        knex = getKnex();
+    }
+    catch {
+        return;
+    }
+    if (!knex)
+        return;
+    await ensureMigrationsTable(knex);
+    await knex.transaction(async (tx) => {
+        // Acquire advisory lock only if running on PostgreSQL
+        await acquireAdvisoryLockIfPostgres(tx, knex);
+        debug("veap:migration", `Running migrations for scope: ${scope}`);
+        // 1. Get executed migrations for this scope
+        const executed = await tx("migrations")
+            .select("name")
+            .where("scope", scope);
+        const executedNames = executed.map((m) => m.name);
+        // 2. Find pending migrations
+        const pending = migrations.filter((m) => !executedNames.includes(m.name));
+        if (pending.length === 0) {
+            debug("veap:migration", `No new migrations for ${scope}.`);
+            return;
+        }
+        // 3. Get next batch number
+        const batchResult = await tx("migrations").max("batch as maxBatch").first();
+        const batch = (Number(batchResult?.maxBatch) || 0) + 1;
+        const dbAdapter = createMigrationDbAdapter(tx);
+        const schema = new Schema(tx);
+        // 4. Execute pending
+        for (const migration of pending) {
+            debug("veap:migration", `[${scope}] Running migration: ${migration.name}...`);
+            try {
+                await migration.up(dbAdapter, schema);
+                await tx("migrations").insert({
+                    id: crypto.randomUUID(),
+                    name: migration.name,
+                    scope: scope,
+                    batch: batch,
+                    executed_at: new Date(),
+                });
+                debug("veap:migration", `[${scope}] Successfully ran ${migration.name}.`);
+            }
+            catch (error) {
+                warn("veap:migration", `[${scope}] Failed to run ${migration.name}:`, error);
+                throw error; // Rollback the whole batch on error
+            }
+        }
+    });
+}
+/**
+ * Modern static migration rollback runner.
+ * Reverts migrations in reverse order.
+ */
+export async function rollbackMigrations(scope, migrations) {
+    if (migrations.length === 0)
+        return;
+    let knex;
+    try {
+        knex = getKnex();
+    }
+    catch {
+        return;
+    }
+    if (!knex)
+        return;
+    await ensureMigrationsTable(knex);
+    await knex.transaction(async (tx) => {
+        // Acquire advisory lock only if running on PostgreSQL
+        await acquireAdvisoryLockIfPostgres(tx, knex);
+        // 1. Get executed migrations for this scope ordered by batch desc
+        const executed = await tx("migrations")
+            .select("name", "batch")
+            .where("scope", scope)
+            .orderBy("batch", "desc");
+        if (executed.length === 0) {
+            debug("veap:migration", `No migrations to rollback for ${scope}.`);
+            return;
+        }
+        // Rollback the latest batch
+        const latestBatch = executed[0].batch;
+        const toRollbackNames = executed
+            .filter((m) => m.batch === latestBatch)
+            .map((m) => m.name);
+        const dbAdapter = createMigrationDbAdapter(tx);
+        const schema = new Schema(tx);
+        // Rollback in reverse order
+        for (const name of toRollbackNames) {
+            const migration = migrations.find((m) => m.name === name);
+            if (migration && migration.down) {
+                debug("veap:migration", `[${scope}] Rolling back migration: ${name}...`);
+                try {
+                    await migration.down(dbAdapter, schema);
+                    await tx("migrations")
+                        .where("name", name)
+                        .where("scope", scope)
+                        .delete();
+                    debug("veap:migration", `[${scope}] Rolled back ${name}.`);
+                }
+                catch (error) {
+                    warn("veap:migration", `[${scope}] Failed to rollback ${name}:`, error);
+                    throw error;
+                }
+            }
+        }
+    });
+}

package/dist/migrations/schema-builder.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Lightweight SQL helper for migrations, compatible with sql`...` template strings.
+ */
+export declare function sql(strings: TemplateStringsArray | string, ...values: any[]): any;
+export declare namespace sql {
+    var raw: (str: string) => string;
+}
+export type DatabaseDialect = "postgres" | "sqlite" | "mysql";
+export declare class ColumnBuilder {
+    type: string;
+    name: string;
+    private _notNull;
+    private _primaryKey;
+    private _unique;
+    private _default;
+    private _defaultNow;
+    private _references;
+    private _onDelete;
+    private _onUpdate;
+    constructor(type: string, name: string);
+    notNull(): this;
+    primaryKey(): this;
+    unique(): this;
+    default(value: any): this;
+    defaultNow(): this;
+    defaultFn(fn: any): this;
+    references(table: string, column?: string): this;
+    onDelete(action: "CASCADE" | "SET NULL" | "RESTRICT" | "NO ACTION"): this;
+    onUpdate(action: "CASCADE" | "SET NULL" | "RESTRICT" | "NO ACTION"): this;
+    toSql(dialect?: DatabaseDialect): string;
+}
+export declare class Blueprint {
+    private tableName;
+    private columns;
+    private _primaryKeys;
+    private _uniques;
+    constructor(tableName: string);
+    id(name?: string): ColumnBuilder;
+    uuid(name?: string): ColumnBuilder;
+    increments(name: string): ColumnBuilder;
+    text(name: string): ColumnBuilder;
+    varchar(name: string, length?: number): ColumnBuilder;
+    string(name: string, length?: number): ColumnBuilder;
+    integer(name: string): ColumnBuilder;
+    smallint(name: string): ColumnBuilder;
+    bigint(name: string): ColumnBuilder;
+    boolean(name: string): ColumnBuilder;
+    timestamp(name: string, precision?: number): ColumnBuilder;
+    timestamptz(name: string, precision?: number): ColumnBuilder;
+    timestamps(): void;
+    softDeletes(name?: string): ColumnBuilder;
+    date(name: string): ColumnBuilder;
+    json(name: string): ColumnBuilder;
+    jsonb(name: string): ColumnBuilder;
+    bytea(name: string): ColumnBuilder;
+    blob(name: string): ColumnBuilder;
+    decimal(name: string, precision?: number, scale?: number): ColumnBuilder;
+    float(name: string): ColumnBuilder;
+    double(name: string): ColumnBuilder;
+    custom(type: string, name: string): ColumnBuilder;
+    unique(columns: string[]): this;
+    primary(columns: string[]): this;
+    private addColumn;
+    toSql(dialect?: DatabaseDialect): string;
+    toAlterSql(dialect?: DatabaseDialect): string[];
+}
+export declare class Schema {
+    private db?;
+    constructor(db?: any | undefined);
+    getDialect(): DatabaseDialect;
+    get knex(): any;
+    private getKnexInstance;
+    hasTable(name: string): Promise<boolean>;
+    hasColumn(tableName: string, columnName: string): Promise<boolean>;
+    dropColumn(tableName: string, columnName: string): Promise<void>;
+    private runQuery;
+    createTable(name: string, callback: (table: Blueprint) => void): Promise<void>;
+    table(name: string, callback: (table: Blueprint) => void): Promise<void>;
+    dropTable(name: string): Promise<void>;
+    dropTableIfExists(name: string): Promise<void>;
+    createEnum(name: string, values: string[]): Promise<void>;
+    dropEnum(name: string): Promise<void>;
+    raw(query: string): Promise<void>;
+}