@zerotal/orm 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @zerotal/orm
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Notes
+
+- Conforms to the Zerotal package conventions (provider in `src/provider/`, PascalCase config factory, `ZerotalError`-based errors, test coverage).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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

@@ -0,0 +1,170 @@
+# @zerotal/orm
+
+> Active Record ORM for Bun — models, migrations, and a fluent query builder on top of `Bun.sql`.
+
+`@zerotal/orm` maps TypeScript classes to database tables: declare columns with decorators, define relationships, and read/write data through a chainable query builder. It supports SQLite, PostgreSQL, and MySQL with the same model code, plus migrations, soft deletes, eager loading, and pagination.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/orm
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { DatabaseProvider } from "@zerotal/orm";
+
+export default [
+  // …your other providers
+  DatabaseProvider,
+];
+```
+
+Configure a connection in `config/database.ts`:
+
+```ts
+import { DatabaseConfig } from "@zerotal/orm";
+import { env } from "@zerotal/core";
+
+export default DatabaseConfig({
+  driver: env("DB_DRIVER", "sqlite"), // 'sqlite' | 'postgres' | 'mysql'
+  url: env("DATABASE_URL", "./database/db.sqlite"),
+  replicas: [], // optional read-replica URLs
+});
+```
+
+## Usage
+
+### Define a model
+
+```ts
+import { BaseModel, column, table, belongsTo, hasMany } from "@zerotal/orm";
+import type { Columns } from "@zerotal/orm";
+
+@(table("posts").withTimestamps().withSoftDeletes())
+export class Post extends BaseModel {
+  static fillable: Columns<Post>[] = ["title", "body", "status", "userId"];
+
+  @column("string") title!: string;
+  @column("text") body!: string;
+  @column("string") status!: string;
+  @column("integer") userId!: number;
+
+  @belongsTo(() => User, { foreignKey: "userId" })
+  author!: User;
+
+  @hasMany(() => Comment, { foreignKey: "postId" })
+  comments!: Comment[];
+}
+```
+
+### Query records
+
+```ts
+const post = await Post.find(1); // or findOrFail(1) to throw
+const published = await Post.query()
+  .where("status", "published")
+  .orderBy("created_at", "desc")
+  .get<Post>();
+
+const created = await Post.create({ title: "Hello", body: "…", status: "draft" });
+
+post.fill({ title: "Updated" });
+await post.save();
+
+await post.delete(); // soft delete (table has .withSoftDeletes())
+await post.restore(); // un-delete
+await post.forceDelete(); // permanent
+```
+
+### Paginate
+
+```ts
+const page = await Post.query()
+  .where("status", "published")
+  .orderBy("created_at", "desc")
+  .paginate(15, Number(http.query("page", "1")));
+
+page.data; // Post[] for this page
+page.total; // total matching rows
+page.lastPage; // number of pages
+```
+
+### Migrations
+
+```ts
+import { Migration, Schema } from "@zerotal/orm";
+
+export default class CreatePostsTable extends Migration {
+  async up(): Promise<void> {
+    await Schema.create("posts", (t) => {
+      t.increments("id");
+      t.integer("user_id").index();
+      t.string("title");
+      t.text("body");
+      t.softDeletes();
+      t.timestamps();
+    });
+  }
+
+  async down(): Promise<void> {
+    await Schema.drop("posts");
+  }
+}
+```
+
+Run them with `bun zt migrate` (`--fresh`, `migrate:rollback`, `migrate:status` also available).
+
+### Raw query builder
+
+```ts
+import { DB } from "@zerotal/orm";
+
+const rows = await DB.table("settings").where("key", "theme").first();
+await DB.table("settings").upsert(
+  { key: "theme", value: "dark" },
+  { key: "theme" },
+  { value: "dark" },
+);
+```
+
+## Exports
+
+This package exposes two subpath entry points:
+
+| Subpath       | Contents                                                                          |
+| ------------- | --------------------------------------------------------------------------------- |
+| `.` (default) | The full ORM runtime — see the table below.                                       |
+| `./commands`  | CLI command classes used by the `zerotal` binary (`make:model`, `migrate`, etc.). |
+
+Main exports from the default entry point:
+
+- **Models** — `BaseModel` / `Model`, `ModelQueryBuilder`, `DB`, `QueryBuilder`
+- **Decorators** — `column`, `table`, `belongsTo`, `hasMany`, `hasOne`, `manyToMany`, `morphTo`, `morphMany`, `morphOne`, `hasManyThrough`, `hasOneThrough`, `morphToMany`, `morphedByMany`
+- **Schema / migrations** — `Schema`, `Blueprint`, `Migration`, `MigrationRunner`, `SchemaInspector`, `ModelInspector`, `SchemaDiffer`, `synchronizeSchema`
+- **Seeding** — `Seeder`
+- **Casts** — `Cast`, `JsonCast`, `ArrayCast`, `json`, `objectOf`, `arrayOf`
+- **Hooks & observers** — `HookRegistry`, `ModelObserver`
+- **N+1 detection** — `preventNPlusOne`, `allowNPlusOne`, `NPlusOneError`
+- **Errors** — `ModelNotFoundError`, `RelationNotLoadedError`, `TransactionError`, `MigrationError`, `StateError`
+- **Provider & config** — `DatabaseProvider`, `DatabaseConfig`
+- **Types** — `Columns`, `InsertPayload`, `UpdatePayload`, `PaginateResult`, `CursorPaginateResult`, and more
+
+## Documentation
+
+- [ORM overview](../../docs/orm/index.md)
+- [Queries](../../docs/orm/queries.md)
+- [Relationships](../../docs/orm/relationships.md)
+- [Casts & Mutators](../../docs/orm/casts.md)
+- [Lifecycle & Events](../../docs/orm/lifecycle.md)
+- [Serialization](../../docs/orm/serialization.md)
+- [Factories](../../docs/orm/factories.md)
+- [Query Builder](../../docs/query-builder.md)
+- [Migrations](../../docs/migrations.md)
+- [Pagination](../../docs/pagination.md)
+- [Seeding](../../docs/seeding.md)

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zerotal/orm",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "stable",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./commands": "./src/commands/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0",
+    "@zerotal/validator": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Active Record ORM for Zerotal built on Bun.sql — models, relations, query builder, migrations, and schema.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "orm",
+    "active-record",
+    "sql",
+    "database",
+    "migrations"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/orm"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/orm#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/casts/Cast.ts

@@ -0,0 +1,200 @@
+/**
+ * Column casts — convert a stored DB value to a rich model value on read, and
+ * back on write. The framework already accepts any `{ get, set }` object as a
+ * cast; `Cast` is the ergonomic, reusable base for custom ones (put yours in
+ * `app/casts/`), plus built-in JSON/array casters.
+ *
+ * @example
+ * // app/casts/MoneyCast.ts
+ * export class MoneyCast extends Cast<number> {
+ *   get(db: unknown) { return Number(db) / 100; }   // cents → dollars
+ *   set(v: number)   { return Math.round(v * 100); }
+ * }
+ *
+ * // model
+ * @column({ cast: new MoneyCast() })       price!: number;
+ * @column({ cast: arrayOf(Address) })       addresses!: Address[];
+ * @column({ cast: json<Settings>() })       settings!: Settings;
+ */
+
+/**
+ * A reusable column caster: DB value ⇄ model value.
+ *
+ * Any object with these two methods can be passed to `@column({ cast })`; the
+ * ORM calls `get` when hydrating an attribute from the database and `set` when
+ * writing it back.
+ *
+ * @typeParam T - The model-side (deserialized) value type.
+ * @category Casts
+ */
+export interface CastContract<T = unknown> {
+  /** DB value → model value (on read). */
+  get(dbValue: unknown): T;
+  /** Model value → DB value (on write). */
+  set(value: T): unknown;
+}
+
+/**
+ * Base class for custom casts. Extend it, implement `get`/`set`, and reference an
+ * instance from a column: `@column({ cast: new MoneyCast() })`.
+ *
+ * @typeParam T - The model-side (deserialized) value type.
+ * @category Casts
+ *
+ * @example
+ * ```ts
+ * // app/casts/MoneyCast.ts
+ * export class MoneyCast extends Cast<number> {
+ *   get(db: unknown) { return Number(db) / 100; } // cents → dollars
+ *   set(v: number)   { return Math.round(v * 100); }
+ * }
+ * ```
+ */
+export abstract class Cast<T = unknown> implements CastContract<T> {
+  abstract get(dbValue: unknown): T;
+  abstract set(value: T): unknown;
+}
+
+/** A class constructor or mapper function used to hydrate a JSON value. */
+export type CastMapper<T> = ((raw: unknown) => T) | (new (...args: never[]) => T);
+
+function _parse(v: unknown): unknown {
+  if (v === null || v === undefined) return v;
+  if (typeof v === "string") {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v;
+    }
+  }
+  return v;
+}
+
+function _isClass(fn: unknown): boolean {
+  return typeof fn === "function" && /^class[\s{]/.test(Function.prototype.toString.call(fn));
+}
+
+function _hydrate<T>(mapper: CastMapper<T> | undefined, raw: unknown): T {
+  if (mapper === undefined || raw === null || raw === undefined) return raw as T;
+  if (_isClass(mapper)) {
+    const C = mapper as unknown as { fromJSON?: (r: unknown) => T; prototype: object };
+    if (typeof C.fromJSON === "function") return C.fromJSON(raw);
+    // Hydrate without invoking the constructor (data/value objects).
+    return Object.assign(Object.create(C.prototype) as object, raw) as T;
+  }
+  return (mapper as (raw: unknown) => T)(raw);
+}
+
+/** A sub-field discovered on a cast's mapper class — consumed by the admin UI. */
+export interface CastField {
+  name: string;
+  label: string;
+  type: string;
+}
+
+function _titleField(s: string): string {
+  return s
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}
+
+function _widgetForValue(v: unknown): string {
+  if (typeof v === "boolean") return "toggle";
+  if (typeof v === "number") return "number";
+  return "text";
+}
+
+/** Introspect a mapper class into a field list (keys + inferred types from defaults). */
+function _introspectFields(mapper: unknown): CastField[] {
+  if (!_isClass(mapper)) return [];
+  let inst: Record<string, unknown>;
+  try {
+    inst = new (mapper as new () => Record<string, unknown>)();
+  } catch {
+    return [];
+  }
+  return Object.entries(inst)
+    .filter(([, v]) => typeof v !== "function")
+    .map(([k, v]) => ({ name: k, label: _titleField(k), type: _widgetForValue(v) }));
+}
+
+/**
+ * Cast a JSON column to a typed object, optionally hydrated into a class.
+ * On read the stored JSON is parsed (and mapped via the constructor's `fromJSON`
+ * or prototype hydration when a class mapper is given); on write it is stringified.
+ * Usually created via the {@link json} / {@link objectOf} helpers.
+ * @category Casts
+ */
+export class JsonCast<T = unknown> extends Cast<T | null> {
+  /** Structural hint for the admin UI: a single nested object. */
+  readonly shape = "object" as const;
+  constructor(private readonly mapper?: CastMapper<T>) {
+    super();
+  }
+  /** Sub-fields derived from the mapper class (empty for plain JSON). */
+  fields(): CastField[] {
+    return _introspectFields(this.mapper);
+  }
+  get(dbValue: unknown): T | null {
+    const v = _parse(dbValue);
+    return v === null || v === undefined ? (v as null) : _hydrate(this.mapper, v);
+  }
+  set(value: T | null): unknown {
+    return value === null || value === undefined ? null : JSON.stringify(value);
+  }
+}
+
+/**
+ * Cast a JSON column to an array of typed values, optionally hydrated. Non-array
+ * stored values read back as `[]`; on write the array is stringified. Usually
+ * created via the {@link arrayOf} helper.
+ * @category Casts
+ */
+export class ArrayCast<T = unknown> extends Cast<T[]> {
+  /** Structural hint for the admin UI: a repeating list of nested objects. */
+  readonly shape = "array" as const;
+  constructor(private readonly mapper?: CastMapper<T>) {
+    super();
+  }
+  /** Sub-fields of each element, derived from the mapper class. */
+  fields(): CastField[] {
+    return _introspectFields(this.mapper);
+  }
+  get(dbValue: unknown): T[] {
+    const v = _parse(dbValue);
+    if (!Array.isArray(v)) return [];
+    return v.map((x) => _hydrate(this.mapper, x));
+  }
+  set(value: T[]): unknown {
+    return JSON.stringify(value ?? []);
+  }
+}
+
+/**
+ * Typed JSON object cast: `@column({ cast: json<Settings>() })`.
+ * @param mapper - Optional class or function to hydrate the parsed value into.
+ * @category Casts
+ */
+export function json<T = unknown>(mapper?: CastMapper<T>): JsonCast<T> {
+  return new JsonCast<T>(mapper);
+}
+
+/**
+ * Alias of {@link json}, reads nicely with a class: `objectOf(Address)`.
+ * @param mapper - Optional class or function to hydrate the parsed value into.
+ * @category Casts
+ */
+export function objectOf<T = unknown>(mapper?: CastMapper<T>): JsonCast<T> {
+  return new JsonCast<T>(mapper);
+}
+
+/**
+ * Typed JSON list cast: `@column({ cast: arrayOf(Address) })`.
+ * @param mapper - Optional class or function to hydrate each element into.
+ * @category Casts
+ */
+export function arrayOf<T = unknown>(mapper?: CastMapper<T>): ArrayCast<T> {
+  return new ArrayCast<T>(mapper);
+}

package/src/commands/DbSeedCommand.ts

@@ -0,0 +1,71 @@
+import { Command } from "@zerotal/core";
+import type { Seeder } from "../seeding/Seeder.ts";
+
+/**
+ * Runs the application's database seeders (`bun zt db:seed`).
+ *
+ * Imports `database/seeders/DatabaseSeeder.ts` and invokes its `run()` method,
+ * falling back to a legacy `database/seeders/index.ts` default-export function
+ * when the class-based seeder is absent.
+ *
+ * @example
+ * ```bash
+ * bun zt db:seed
+ * ```
+ *
+ * @category Seeding
+ */
+export class DbSeedCommand extends Command {
+  static commandName = "db:seed";
+  static description = "Run database seeders from database/seeders/";
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    const cwd = process.cwd();
+    const seederPath = `${cwd}/database/seeders/DatabaseSeeder.ts`;
+
+    const file = Bun.file(seederPath);
+    if (!(await file.exists())) {
+      // Fall back to legacy index.ts seeder format
+      const legacyPath = `${cwd}/database/seeders/index.ts`;
+      if (await Bun.file(legacyPath).exists()) {
+        try {
+          const mod = await import(legacyPath);
+          const seed = mod.default as (() => Promise<void>) | undefined;
+          if (!seed) {
+            this.error("Seeder index must export a default async function.");
+            return;
+          }
+          await seed();
+          this.info("Database seeded.");
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          this.error(`Failed to run seeders: ${msg}`);
+        }
+        return;
+      }
+
+      this.error(`Seeder not found: ${seederPath}`);
+      this.dim("Create it with: bun zerotal.ts make:seeder DatabaseSeeder");
+      return;
+    }
+
+    try {
+      const mod = await import(seederPath);
+      const SeederClass = (mod.DatabaseSeeder ?? mod.default) as (new () => Seeder) | undefined;
+
+      if (!SeederClass) {
+        this.error("DatabaseSeeder not found as a named or default export.");
+        return;
+      }
+
+      this.section("Database Seeding");
+      const seeder = new SeederClass();
+      await seeder.run();
+      this.info("Database seeded successfully.");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.error(`Failed to run seeders: ${msg}`);
+    }
+  }
+}

package/src/commands/MakeFactoryCommand.ts

@@ -0,0 +1,59 @@
+import { Command, Str } from "@zerotal/core";
+
+/**
+ * Scaffolds a new model factory (`bun zt make:factory`).
+ *
+ * Writes `database/factories/<Model>Factory.ts` defining a `Factory` for the
+ * named model, ready to be imported in tests to build and persist records.
+ *
+ * @example
+ * ```bash
+ * bun zt make:factory User
+ * ```
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeFactoryCommand extends Command {
+  static commandName = "make:factory";
+  static description = "Create a new model factory";
+  static needsApp = false;
+  static args = [{ name: "model", required: true, description: "Model name (e.g. User)" }];
+
+  async run(): Promise<void> {
+    const model = this.args["model"]!;
+    const path = `database/factories/${model}Factory.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, factoryStub(model));
+    this.info(`Created: ${path}`);
+    this.dim(
+      `Import in tests: import { ${model}Factory } from '../database/factories/${model}Factory.ts';`,
+    );
+  }
+}
+
+/**
+ * Returns the source text of a factory file for the given model name.
+ */
+export function factoryStub(model: string): string {
+  const modelVar = Str.lcfirst(model);
+  return `import { Factory } from '@zerotal/testing';
+import { ${model} } from '../../app/models/${model}.ts';
+
+export const ${model}Factory = Factory.define(${model}, (fake) => ({
+  // Define default attributes here. Use fake for generated values:
+  // name:  fake.string(10),
+  // email: fake.email(),
+}));
+
+// Usage in tests:
+//   const ${modelVar}  = await ${model}Factory.create();
+//   const ${modelVar}s = await ${model}Factory.createMany(5);
+//   const draft = ${model}Factory.make({ published: false });
+//   const post  = await PostFactory.for(${modelVar}).create();
+`;
+}