@veap/database 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damian Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+[![CI](https://github.com/veapjs/veap-database/actions/workflows/ci.yml/badge.svg)](https://github.com/veapjs/veap-database/actions/workflows/ci.yml)
+[![Release](https://github.com/veapjs/veap-database/actions/workflows/release.yml/badge.svg)](https://github.com/veapjs/veap-database/actions/workflows/release.yml)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @veap/database
+
+Eloquent-inspired Active Record ORM powered by Knex with AsyncLocalStorage
+transaction scoping and automatic migrations for PostgreSQL, MySQL, and SQLite.
+
+## Overview
+
+`@veap/database` brings expressive, developer-friendly Active Record modeling to
+TypeScript. It combines the ergonomic query building of Laravel Eloquent with
+the battle-tested reliability of Knex. With built-in `AsyncLocalStorage`
+context propagation, database transactions flow seamlessly across function and
+module boundaries without manual transaction object passing.
+
+## Features
+
+- **Active Record models**: Clean declarative models with timestamps, UUID
+  primary keys, attribute casting (JSON, dates, booleans), and local scopes.
+- **AsyncLocalStorage transactions**: Zero-boilerplate `transaction()` blocks
+  that bind nested queries automatically to the current transaction.
+- **Expressive relations**: Full relation graph support including `belongsTo`,
+  `hasMany`, `hasOne`, `belongsToMany`, and polymorphic variants (`morphTo`,
+  `morphMany`, `morphOne`, `morphToMany`).
+- **Eager loading & query builder**: Fluid chainable queries with `.with()`,
+  `.where()`, `.orderBy()`, `.paginate()`, and `.first()`.
+- **Knex proxy & raw queries**: Direct access to Knex via `getKnex()` and the
+  convenient dynamic proxy `dbClient`.
+- **Migration & Schema runner**: Declarative `Schema` builder and automated
+  migration runner supporting versioned schema updates.
+- **IoC integration**: Ships with `DatabaseServiceProvider` and
+  `MigrationServiceProvider` for modular Veap applications.
+
+## Installation
+
+```bash
+# Using bun
+bun add @veap/database better-sqlite3 # or pg / mysql2
+
+# Using pnpm
+pnpm add @veap/database better-sqlite3
+
+# Using npm
+npm install @veap/database better-sqlite3
+```
+
+## Usage
+
+### Define Active Record Models
+
+Create models extending the base `Model` class:
+
+```ts
+import { Model, belongsTo, hasMany } from "@veap/database";
+import type { BelongsTo, HasMany } from "@veap/database";
+
+export class Author extends Model {
+  static override tableName = "authors";
+
+  declare id: string;
+  declare name: string;
+  declare email: string;
+
+  public posts(): HasMany<Post> {
+    return hasMany(this, Post, "author_id");
+  }
+}
+
+export class Post extends Model {
+  static override tableName = "posts";
+
+  declare id: string;
+  declare title: string;
+  declare content: string;
+  declare author_id: string;
+
+  public author(): BelongsTo<Author> {
+    return belongsTo(this, Author, "author_id");
+  }
+}
+```
+
+### Querying and CRUD Operations
+
+Perform common queries and persistence operations:
+
+```ts
+// Create
+const author = await Author.create({
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+});
+
+// Find and update
+const post = await Post.query().where("slug", "first-post").first();
+if (post) {
+  post.title = "Updated Title";
+  await post.save();
+}
+
+// Eager loading relations
+const postsWithAuthors = await Post.query()
+  .with("author")
+  .where("status", "published")
+  .orderBy("created_at", "desc")
+  .get();
+```
+
+### Seamless Transactions with AsyncLocalStorage
+
+Run operations inside a transaction without passing around connection objects:
+
+```ts
+import { transaction } from "@veap/database";
+
+await transaction(async () => {
+  const author = await Author.create({
+    name: "Grace Hopper",
+    email: "grace@example.com",
+  });
+
+  await Post.create({
+    title: "Compilers and Nanoseconds",
+    content: "...",
+    author_id: author.id,
+  });
+  // If any error is thrown, the entire block rolls back automatically.
+});
+```
+
+### Standalone Database Initialization
+
+When using outside the Veap application builder:
+
+```ts
+import { initDatabase } from "@veap/database";
+
+initDatabase({
+  client: "better-sqlite3",
+  connection: {
+    filename: "./data/app.sqlite",
+  },
+  useNullAsDefault: true,
+});
+```
+
+### IoC Service Provider Setup
+
+When composing inside a Veap application:
+
+```ts
+import { Application } from "@veap/kernel";
+import { DatabaseServiceProvider } from "@veap/database";
+
+export const app = Application.configure()
+  .use(DatabaseServiceProvider)
+  .create();
+```
+
+## Subpath Exports
+
+| Export Path      | Content                                                                 |
+| ---------------- | ----------------------------------------------------------------------- |
+| `@veap/database` | Core ORM, Model, relations, transactions, schema builder, and providers |
+
+## Documentation
+
+For full guides and relational modeling patterns, visit:
+
+- **Official Website**: [https://veap.pl](https://veap.pl)
+- **Documentation**: [https://veap.pl/docs](https://veap.pl/docs)
+- **GitHub Repository**: [https://github.com/veapjs/veap-database](https://github.com/veapjs/veap-database)
+
+## License
+
+MIT

package/dist/casts.d.ts

@@ -0,0 +1,9 @@
+export type CastType = "string" | "number" | "boolean" | "json" | "datetime" | "date" | (string & {});
+/**
+ * Casts raw database value to application/model representation.
+ */
+export declare function castAttribute(value: any, type: CastType): any;
+/**
+ * Prepares model attribute value for database storage based on dialect.
+ */
+export declare function serializeForStorage(value: any, type: CastType | undefined, clientType?: string): any;

package/dist/casts.js

@@ -0,0 +1,78 @@
+/**
+ * Casts raw database value to application/model representation.
+ */
+export function castAttribute(value, type) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    switch (type) {
+        case "string":
+            return String(value);
+        case "number": {
+            const num = Number(value);
+            return Number.isNaN(num) ? value : num;
+        }
+        case "boolean":
+            return value === 1 || value === "1" || value === true || value === "true";
+        case "json":
+            if (typeof value === "string") {
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return value;
+                }
+            }
+            return value;
+        case "datetime":
+        case "date":
+            if (value instanceof Date) {
+                return value;
+            }
+            return new Date(value);
+        default:
+            return value;
+    }
+}
+/**
+ * Prepares model attribute value for database storage based on dialect.
+ */
+export function serializeForStorage(value, type, clientType) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (!type) {
+        if (value instanceof Date) {
+            if (clientType?.includes("sqlite")) {
+                return value.toISOString();
+            }
+            return value;
+        }
+        if (typeof value === "object" && !(value instanceof Date)) {
+            if (clientType?.includes("sqlite")) {
+                return JSON.stringify(value);
+            }
+        }
+        return value;
+    }
+    switch (type) {
+        case "json":
+            return JSON.stringify(value);
+        case "boolean":
+            if (clientType?.includes("sqlite")) {
+                return value ? 1 : 0;
+            }
+            return Boolean(value);
+        case "datetime":
+        case "date":
+            if (value instanceof Date) {
+                if (clientType?.includes("sqlite")) {
+                    return value.toISOString();
+                }
+                return value;
+            }
+            return value;
+        default:
+            return value;
+    }
+}

package/dist/connection.d.ts

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { type Knex } from "knex";
+import type { DatabaseConfig, PostgresSslConfig, PostgresSslOptions, TransactionOptions } from "./types";
+/**
+ * AsyncLocalStorage holding the currently active Knex transaction for the asynchronous execution context.
+ */
+export declare const transactionStorage: AsyncLocalStorage<Knex.Transaction>;
+/**
+ * Returns the currently active transaction if inside a transaction() callback.
+ */
+export declare function getActiveTransaction(): Knex.Transaction | undefined;
+/**
+ * Injects or overrides the global Knex database instance.
+ */
+export declare function setKnex(instance: Knex): Knex;
+export declare function isSqliteDatabase(url?: string): boolean;
+/**
+ * Resolves PostgreSQL TLS/SSL configuration based on environment, connection string parameters,
+ * and security settings.
+ */
+export declare function resolvePostgresSslConfig(options: PostgresSslOptions): PostgresSslConfig;
+/**
+ * Resolves SQLite database filename, automatically redirecting to /tmp on serverless (Vercel/Lambda)
+ * where the root deployment filesystem is read-only.
+ */
+export declare function resolveSqliteFilename(filename: string): string;
+/**
+ * Initializes a new Knex instance from a configuration object.
+ */
+export declare function initDatabase(config: DatabaseConfig): Knex;
+/**
+ * Returns the active Knex database instance or active transaction if inside a transaction context.
+ */
+/**
+ * Checks whether the global Knex database instance is currently initialized.
+ */
+export declare function isDatabaseInitialized(): boolean;
+export declare function getKnex(): Knex;
+/**
+ * Dynamic proxy for knex queries.
+ * Can be called as a function: dbClient('users').where(...)
+ * or accessed via properties: dbClient.schema, dbClient.raw, dbClient.transaction
+ */
+export declare const dbClient: Knex;
+/**
+ * Executes a callback within a database transaction managed via AsyncLocalStorage.
+ * Automatically commits if callback succeeds, and rolls back if an error is thrown.
+ */
+export declare function transaction<T>(callback: (trx: Knex.Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;

package/dist/connection.js

@@ -0,0 +1,189 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import fs from "node:fs";
+import path from "node:path";
+import knex from "knex";
+import { DatabaseError } from "./errors";
+import { debug, warn } from "./logger";
+const globalForDb = globalThis;
+/**
+ * AsyncLocalStorage holding the currently active Knex transaction for the asynchronous execution context.
+ */
+export const transactionStorage = globalForDb.__VEAP_TRANSACTION_STORAGE__ ||
+    (globalForDb.__VEAP_TRANSACTION_STORAGE__ =
+        new AsyncLocalStorage());
+/**
+ * Returns the currently active transaction if inside a transaction() callback.
+ */
+export function getActiveTransaction() {
+    return transactionStorage.getStore();
+}
+/**
+ * Injects or overrides the global Knex database instance.
+ */
+export function setKnex(instance) {
+    globalForDb.__VEAP_KNEX__ = instance;
+    debug("veap:database", "Knex database instance registered.");
+    return instance;
+}
+export function isSqliteDatabase(url) {
+    if (!url)
+        return false;
+    return (url.startsWith("sqlite:") ||
+        url.startsWith("file:") ||
+        url.endsWith(".sqlite") ||
+        url.endsWith(".db"));
+}
+/**
+ * Resolves PostgreSQL TLS/SSL configuration based on environment, connection string parameters,
+ * and security settings.
+ */
+export function resolvePostgresSslConfig(options) {
+    const { databaseUrl, isProd, rejectUnauthorizedEnv, caCert } = options;
+    if (databaseUrl.includes("sslmode=disable")) {
+        return false;
+    }
+    const isSslRequested = isProd ||
+        databaseUrl.includes("sslmode=require") ||
+        databaseUrl.includes("ssl=true") ||
+        databaseUrl.includes("sslmode=no-verify");
+    if (!isSslRequested) {
+        return false;
+    }
+    let rejectUnauthorized = true;
+    if (rejectUnauthorizedEnv !== undefined) {
+        rejectUnauthorized =
+            rejectUnauthorizedEnv !== "false" && rejectUnauthorizedEnv !== "0";
+    }
+    else if (databaseUrl.includes("sslmode=no-verify") ||
+        databaseUrl.includes("rejectUnauthorized=false")) {
+        rejectUnauthorized = false;
+    }
+    const sslConfig = {
+        rejectUnauthorized,
+    };
+    if (caCert) {
+        sslConfig.ca = caCert;
+    }
+    return sslConfig;
+}
+/**
+ * Resolves SQLite database filename, automatically redirecting to /tmp on serverless (Vercel/Lambda)
+ * where the root deployment filesystem is read-only.
+ */
+export function resolveSqliteFilename(filename) {
+    let clean = filename.replace(/^(?:sqlite|file):(\/\/)?/, "");
+    if (!clean)
+        clean = "veap.sqlite";
+    const isServerless = process.env.VERCEL === "1" ||
+        !!process.env.AWS_LAMBDA_FUNCTION_NAME ||
+        !!process.env.LAMBDA_TASK_ROOT;
+    if (isServerless &&
+        !clean.startsWith("/tmp") &&
+        !clean.startsWith(":memory:")) {
+        const base = clean.split(/[\/\\]/).pop() || "dev.sqlite";
+        const redirected = `/tmp/${base}`;
+        warn("veap:database", `Running SQLite on Vercel/Serverless environment where filesystem (/var/task) is read-only. ` +
+            `Redirecting SQLite database file from "${clean}" to writable temporary path "${redirected}". ` +
+            `WARNING: SQLite storage on serverless functions is ephemeral and wiped across function cold starts. ` +
+            `For persistent production deployments on Vercel, set a PostgreSQL DATABASE_URL in Vercel Environment Variables.`);
+        return redirected;
+    }
+    if (!clean.startsWith(":memory:")) {
+        try {
+            fs.mkdirSync(path.dirname(path.resolve(clean)), {
+                recursive: true,
+            });
+        }
+        catch {
+            // Read-only filesystem etc. Let the driver surface its own error.
+        }
+    }
+    return clean;
+}
+/**
+ * Initializes a new Knex instance from a configuration object.
+ */
+export function initDatabase(config) {
+    let client = config.client;
+    if (!client && config.driver) {
+        if (config.driver === "postgres")
+            client = "pg";
+        else if (config.driver === "sqlite")
+            client = "better-sqlite3";
+        else if (config.driver === "mysql")
+            client = "mysql2";
+    }
+    if ((client === "better-sqlite3" || config.driver === "sqlite") &&
+        typeof config.connection === "object" &&
+        config.connection !== null) {
+        const conn = config.connection;
+        if (conn.filename) {
+            conn.filename = resolveSqliteFilename(conn.filename);
+        }
+    }
+    const finalConfig = {
+        ...config,
+        client: client || "pg",
+        useNullAsDefault: config.useNullAsDefault ?? true,
+    };
+    const instance = knex(finalConfig);
+    return setKnex(instance);
+}
+/**
+ * Returns the active Knex database instance or active transaction if inside a transaction context.
+ */
+/**
+ * Checks whether the global Knex database instance is currently initialized.
+ */
+export function isDatabaseInitialized() {
+    return Boolean(getActiveTransaction() || globalForDb.__VEAP_KNEX__);
+}
+export function getKnex() {
+    const activeTrx = getActiveTransaction();
+    if (activeTrx) {
+        return activeTrx;
+    }
+    if (globalForDb.__VEAP_KNEX__) {
+        return globalForDb.__VEAP_KNEX__;
+    }
+    throw DatabaseError.Internal("[veap:ORM] Database not initialized. Please call initDatabase() or register DatabaseServiceProvider.");
+}
+/**
+ * Dynamic proxy for knex queries.
+ * Can be called as a function: dbClient('users').where(...)
+ * or accessed via properties: dbClient.schema, dbClient.raw, dbClient.transaction
+ */
+export const dbClient = new Proxy((() => { }), {
+    apply(_target, _thisArg, argArray) {
+        const k = getKnex();
+        return k(...argArray);
+    },
+    get(_target, prop) {
+        const k = getKnex();
+        const value = k[prop];
+        return typeof value === "function" ? value.bind(k) : value;
+    },
+});
+/**
+ * Executes a callback within a database transaction managed via AsyncLocalStorage.
+ * Automatically commits if callback succeeds, and rolls back if an error is thrown.
+ */
+export async function transaction(callback, options) {
+    const currentTrx = getActiveTransaction();
+    if (currentTrx) {
+        if (options?.savepoint) {
+            return await currentTrx.transaction(async (spTrx) => {
+                return await transactionStorage.run(spTrx, async () => {
+                    return await callback(spTrx);
+                });
+            });
+        }
+        return await callback(currentTrx);
+    }
+    const k = getKnex();
+    return await k.transaction(async (trx) => {
+        return await transactionStorage.run(trx, async () => {
+            return await callback(trx);
+        });
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class DatabaseError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+    static NotFound(message?: string): DatabaseError;
+    static Internal(message?: string): DatabaseError;
+    static QueryFailed(message: string): DatabaseError;
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+export class DatabaseError extends Error {
+    code;
+    constructor(message, code = "DATABASE_ERROR") {
+        super(message);
+        this.code = code;
+        this.name = "DatabaseError";
+    }
+    static NotFound(message = "Record not found") {
+        return new DatabaseError(message, "NOT_FOUND");
+    }
+    static Internal(message = "Internal database error") {
+        return new DatabaseError(message, "INTERNAL_ERROR");
+    }
+    static QueryFailed(message) {
+        return new DatabaseError(message, "QUERY_FAILED");
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,5 @@
+export interface DatabaseEventDispatcher {
+    publish(event: string, payload: any): Promise<void> | void;
+}
+export declare function setDatabaseEventDispatcher(dispatcher: DatabaseEventDispatcher | null): void;
+export declare function getDatabaseEventDispatcher(): DatabaseEventDispatcher | null;

package/dist/events.js

@@ -0,0 +1,7 @@
+let activeDispatcher = null;
+export function setDatabaseEventDispatcher(dispatcher) {
+    activeDispatcher = dispatcher;
+}
+export function getDatabaseEventDispatcher() {
+    return activeDispatcher;
+}

package/dist/factory.d.ts

@@ -0,0 +1,68 @@
+import type { Model } from "./model";
+export declare abstract class Factory<M extends Model = any> {
+    private static get registry();
+    /**
+     * Registers a factory class/instance for a model.
+     */
+    static register(modelClass: any, factoryOrFactoryFn: any): void;
+    /**
+     * Gets the registered factory for a model if one exists.
+     */
+    static getForModel(modelClass: any): any;
+    protected modelClass: any;
+    protected countNumber: number;
+    protected states: Array<Record<string, any> | ((attributes: Record<string, any>) => Record<string, any>)>;
+    protected sequenceItems: Array<Record<string, any>>;
+    constructor(modelClass?: any);
+    /**
+     * Defines the default model attributes.
+     */
+    abstract definition(): Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * Sets the number of models that should be generated.
+     */
+    count(amount: number): this;
+    /**
+     * Applies an attribute state transformation to the factory.
+     */
+    state(override: Record<string, any> | ((attributes: Record<string, any>) => Record<string, any>)): this;
+    /**
+     * Applies sequential states rotating through the given items.
+     */
+    sequence(...items: Record<string, any>[]): this;
+    /**
+     * Generates the raw attributes dictionary for a single model instance.
+     */
+    raw(override?: Record<string, any>, index?: number): Promise<Record<string, any>>;
+    /**
+     * Creates a single model instance in memory without saving to database.
+     */
+    makeOne(override?: Record<string, any>, index?: number): Promise<M>;
+    /**
+     * Creates model instance(s) in memory without saving to database.
+     */
+    make(override?: Record<string, any>): Promise<M | M[]>;
+    /**
+     * Creates and persists a single model instance to the database.
+     */
+    createOne(override?: Record<string, any>, index?: number): Promise<M>;
+    /**
+     * Creates and persists model instance(s) to the database.
+     */
+    create(override?: Record<string, any>): Promise<M | M[]>;
+}
+export interface FactoryConstructor<M extends Model = any> {
+    new (): Factory<M>;
+    (count?: number): Factory<M>;
+    count(amount: number): Factory<M>;
+    state(override: Record<string, any> | ((attrs: any) => Record<string, any>)): Factory<M>;
+    sequence(...items: Record<string, any>[]): Factory<M>;
+    make(override?: Record<string, any>): Promise<M | M[]>;
+    makeOne(override?: Record<string, any>): Promise<M>;
+    create(override?: Record<string, any>): Promise<M | M[]>;
+    createOne(override?: Record<string, any>): Promise<M>;
+}
+/**
+ * Convenient helper to define a Model Factory in a single concise call.
+ */
+export declare function defineFactory<M extends Model = any>(modelClass: new (...args: any[]) => M, definitionFn: () => Record<string, any> | Promise<Record<string, any>>): FactoryConstructor<M>;