@zerotal/orm 1.0.0

package/src/db/types.ts

@@ -0,0 +1,296 @@
+import { pageElements } from "@zerotal/core";
+
+/** Operators accepted by {@link QueryBuilder.where} and its variants. */
+export type WhereOperator =
+  "=" | "!=" | ">" | ">=" | "<" | "<=" | "like" | "not like" | "in" | "not in";
+/** Sort direction for `ORDER BY`. */
+export type OrderDirection = "asc" | "desc";
+
+/** @internal One accumulated WHERE predicate in the builder's query state. */
+export interface WhereClause {
+  column: string;
+  /** Broad string so the builder can store the standard operators plus
+   *  internal markers ('is null', '__raw__', 'between', 'column', 'exists', …). */
+  operator: string;
+  value: unknown;
+  boolean: "and" | "or";
+  /** Second column name — used by whereColumn(). */
+  column2?: string;
+  /**
+   * Nested predicates, present only when `operator === "__group__"`. Rendered inside
+   * parentheses, which is what keeps an `OR` chain from escaping the surrounding `AND`s.
+   */
+  group?: WhereClause[];
+}
+
+/** @internal One accumulated ORDER BY term in the builder's query state. */
+export interface OrderClause {
+  column: string;
+  /** `"__raw__"` marks a raw `orderByRaw()` expression (column holds the raw SQL). */
+  direction: OrderDirection | "__raw__";
+}
+
+/** @internal One accumulated HAVING predicate in the builder's query state. */
+export interface HavingClause {
+  column: string;
+  operator: string;
+  value: unknown;
+}
+
+/** The kinds of join the builder can emit. */
+export type JoinType = "inner" | "left" | "right" | "cross";
+
+/** @internal One accumulated JOIN clause in the builder's query state. */
+export interface JoinClause {
+  type: JoinType;
+  /** Table expression — a bare table name or `(subquery) AS alias`. */
+  table: string;
+  first?: string;
+  operator?: string;
+  second?: string;
+  /** Bindings introduced by a subquery join (joinSub). */
+  bindings?: unknown[];
+}
+
+/** @internal One accumulated UNION arm (a compiled subquery + bindings). */
+export interface UnionClause {
+  sql: string;
+  bindings: unknown[];
+  all: boolean;
+}
+
+/** @internal The full mutable state a {@link QueryBuilder} compiles into SQL. */
+export interface QueryState {
+  table: string;
+  selects: string[];
+  distinct: boolean;
+  joins: JoinClause[];
+  wheres: WhereClause[];
+  orders: OrderClause[];
+  groupBys: string[];
+  havings: HavingClause[];
+  unions: UnionClause[];
+  limit: number | undefined;
+  offset: number | undefined;
+  /** Pessimistic-lock suffix, e.g. 'FOR UPDATE' / 'FOR SHARE'. */
+  lock: string | undefined;
+}
+
+/** Standard pagination metadata block. */
+export interface PaginateMeta {
+  /** Index (1-based) of the first item on the current page, or null when empty. */
+  from: number | null;
+  /** Index (1-based) of the last item on the current page, or null when empty. */
+  to: number | null;
+  /** Current page number. */
+  currentPage: number;
+  /** Last (highest) page number. */
+  lastPage: number;
+  /** Items per page. */
+  perPage: number;
+  /** Total number of matching rows. */
+  total: number;
+  /** Base URL used for link generation. */
+  path: string;
+}
+
+/**
+ * Result of {@link QueryBuilder.paginate} — a full offset paginator with total
+ * row count, page metadata and URL helpers.
+ */
+export interface PaginateResult<T = Record<string, unknown>> {
+  data: T[];
+  total: number;
+  page: number;
+  perPage: number;
+  lastPage: number;
+  /** Index (1-based) of the first item on this page, or null when the page is empty. */
+  from: number | null;
+  /** Index (1-based) of the last item on this page, or null when the page is empty. */
+  to: number | null;
+  /** Standard metadata block (from/to/path/total/…) for driving UI components. */
+  meta: PaginateMeta;
+  /**
+   * URL for the next page, or null on the last page.
+   * Extra query params (e.g. filters) are merged and preserved.
+   * @example result.nextPageUrl('/posts', { search: 'bun' })
+   */
+  nextPageUrl(baseUrl?: string, query?: Record<string, string>): string | null;
+  /**
+   * URL for the previous page, or null on the first page.
+   * Extra query params are merged and preserved.
+   */
+  previousPageUrl(baseUrl?: string, query?: Record<string, string>): string | null;
+  /**
+   * Build the URL for any page number (relative to `baseUrl`, default the
+   * paginator's configured `path`).
+   * @example result.url(3) // '/posts?page=3'
+   */
+  url(page: number, baseUrl?: string, query?: Record<string, string>): string;
+  /** True when there is at least one more page after the current one. */
+  hasMorePages: boolean;
+  /** True when the current page is the first page. */
+  onFirstPage: boolean;
+  /** True when the current page is the last page. */
+  onLastPage: boolean;
+  /**
+   * Page-number window for a numbered pager, with `"..."` gaps —
+   * e.g. `[1, "...", 4, 5, 6, "...", 20]`.
+   * @param each - Page links on each side of the current page (default `1`).
+   */
+  elements(each?: number): (number | "...")[];
+  /**
+   * Array of page links — useful for rendering pagination UI.
+   * Extra query params are merged onto every link URL.
+   * @example result.links('/posts', { search: 'bun' })
+   */
+  links(
+    baseUrl?: string,
+    query?: Record<string, string>,
+  ): Array<{ page: number; url: string; active: boolean }>;
+}
+
+/** Build a query-string from a page number plus optional extra params. */
+function _pageUrl(baseUrl: string, page: number, extra: Record<string, string> = {}): string {
+  const params = new URLSearchParams({ ...extra, page: String(page) });
+  return `${baseUrl}?${params.toString()}`;
+}
+
+/** Options accepted by the pagination helper factories. */
+export interface PaginationHelperOptions {
+  /** Base path used by no-argument URL helpers and `meta.path`. Default: `''`. */
+  path?: string;
+}
+
+/** Attach URL helper methods + metadata to a plain paginate result object. */
+export function withPaginationHelpers<T>(
+  raw: {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    lastPage: number;
+  },
+  options: PaginationHelperOptions = {},
+): PaginateResult<T> {
+  const r = raw as PaginateResult<T>;
+  const path = options.path ?? "";
+
+  const from = raw.total === 0 ? null : (raw.page - 1) * raw.perPage + 1;
+  const to = raw.total === 0 || raw.data.length === 0 ? null : (from ?? 0) + raw.data.length - 1;
+
+  r.from = from;
+  r.to = to;
+  r.meta = {
+    from,
+    to,
+    currentPage: raw.page,
+    lastPage: raw.lastPage,
+    perPage: raw.perPage,
+    total: raw.total,
+    path,
+  };
+
+  r.url = (page, baseUrl = path, query = {}) => _pageUrl(baseUrl, page, query);
+  r.nextPageUrl = (baseUrl = path, query = {}) =>
+    raw.page < raw.lastPage ? _pageUrl(baseUrl, raw.page + 1, query) : null;
+  r.previousPageUrl = (baseUrl = path, query = {}) =>
+    raw.page > 1 ? _pageUrl(baseUrl, raw.page - 1, query) : null;
+  r.hasMorePages = raw.page < raw.lastPage;
+  r.onFirstPage = raw.page <= 1;
+  r.onLastPage = raw.page >= raw.lastPage;
+  r.elements = (each = 1) => pageElements(raw.page, raw.lastPage, each);
+  r.links = (baseUrl = path, query = {}) =>
+    Array.from({ length: raw.lastPage }, (_, i) => ({
+      page: i + 1,
+      url: _pageUrl(baseUrl, i + 1, query),
+      active: i + 1 === raw.page,
+    }));
+  return r;
+}
+
+/**
+ * Result of {@link QueryBuilder.simplePaginate} — "next/prev only" pagination
+ * that skips the expensive `COUNT(*)` query. There is no `total` or `lastPage`.
+ */
+export interface SimplePaginateResult<T = Record<string, unknown>> {
+  data: T[];
+  perPage: number;
+  page: number;
+  /** Index (1-based) of the first item on this page, or null when empty. */
+  from: number | null;
+  /** Index (1-based) of the last item on this page, or null when empty. */
+  to: number | null;
+  /** True when another page follows (a `perPage + 1` probe row was found). */
+  hasMorePages: boolean;
+  /** True when the current page is the first page. */
+  onFirstPage: boolean;
+  nextPageUrl(baseUrl?: string, query?: Record<string, string>): string | null;
+  previousPageUrl(baseUrl?: string, query?: Record<string, string>): string | null;
+  url(page: number, baseUrl?: string, query?: Record<string, string>): string;
+}
+
+/** Attach URL helpers + metadata to a simple-paginate result object. */
+export function withSimplePaginationHelpers<T>(
+  raw: {
+    data: T[];
+    perPage: number;
+    page: number;
+    hasMore: boolean;
+  },
+  options: PaginationHelperOptions = {},
+): SimplePaginateResult<T> {
+  const { hasMore, ...rest } = raw;
+  const r = rest as unknown as SimplePaginateResult<T>;
+  const path = options.path ?? "";
+
+  const from = raw.data.length === 0 ? null : (raw.page - 1) * raw.perPage + 1;
+  const to = raw.data.length === 0 ? null : (from ?? 0) + raw.data.length - 1;
+  r.from = from;
+  r.to = to;
+
+  r.url = (page, baseUrl = path, query = {}) => _pageUrl(baseUrl, page, query);
+  r.hasMorePages = hasMore;
+  r.onFirstPage = raw.page <= 1;
+  r.nextPageUrl = (baseUrl = path, query = {}) =>
+    hasMore ? _pageUrl(baseUrl, raw.page + 1, query) : null;
+  r.previousPageUrl = (baseUrl = path, query = {}) =>
+    raw.page > 1 ? _pageUrl(baseUrl, raw.page - 1, query) : null;
+  return r;
+}
+
+/** Result of {@link QueryBuilder.cursorPaginate} — id-based cursor pagination. */
+export interface CursorPaginateResult<T = Record<string, unknown>> {
+  data: T[];
+  /** Cursor pointing past the last item, or null on the final page. */
+  nextCursor: number | null;
+  /** Cursor for the page that preceded this one, or null on the first page. */
+  prevCursor: number | null;
+  /** True when another page follows (equivalent to `nextCursor !== null`). */
+  hasMore: boolean;
+}
+
+/** Options for {@link QueryBuilder.keysetPaginate}. */
+export interface KeysetOptions {
+  /**
+   * Opaque cursor string from the previous page's `nextCursor`.
+   * `null` or omitted = first page.
+   */
+  cursor?: string | null;
+  /** Column used for keyset ordering. Must be a safe SQL identifier. Default: `'id'`. */
+  column?: string;
+  /** Sort direction. Default: `'asc'`. */
+  direction?: "asc" | "desc";
+  /** Items per page. Default: `15`. */
+  limit?: number;
+}
+
+/** Result of {@link QueryBuilder.keysetPaginate} — opaque-cursor keyset pagination. */
+export interface KeysetPaginateResult<T = Record<string, unknown>> {
+  data: T[];
+  /**
+   * Opaque base64 cursor pointing past the last item, or `null` on the final page.
+   * Pass this directly to the next `keysetPaginate({ cursor })` call.
+   */
+  nextCursor: string | null;
+}

package/src/errors/MassAssignmentError.ts

@@ -0,0 +1,25 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when `fill()` / `create()` receives an attribute that the model's
+ * mass-assignment rules do not allow.
+ *
+ * Zerotal guards by default: a model that declares neither `fillable` nor
+ * `guarded` (and has not opted into `static unguarded = true`) rejects every
+ * mass-assigned attribute, so a stray `role`/`is_admin`/`id` in a request body
+ * can never reach the database. Declare `fillable` to allow specific columns,
+ * or use `forceFill()` / `forceCreate()` for trusted, framework-internal writes.
+ */
+export class MassAssignmentError extends ZerotalError {
+  constructor(model: string, attribute: string) {
+    super(
+      `[Zerotal ORM] "${attribute}" is not mass-assignable on ${model}. ` +
+        `Add it to \`static fillable\`, or use forceFill()/forceCreate() for trusted data. ` +
+        `Models guard all attributes by default — set \`static unguarded = true\` to opt out.`,
+      "E_MASS_ASSIGNMENT",
+      422,
+      { model, attribute },
+    );
+    this.name = "MassAssignmentError";
+  }
+}

package/src/errors/MigrationError.ts

@@ -0,0 +1,18 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when a migration's `up`/`down` throws, wrapping the underlying error with
+ * the failing migration's name for context.
+ *
+ * @param migrationName - The migration that failed.
+ * @param cause - The underlying error thrown by the migration.
+ */
+export class MigrationError extends ZerotalError {
+  constructor(migrationName: string, cause: Error) {
+    super(`Migration '${migrationName}' failed: ${cause.message}`, "E_MIGRATION_FAILED", 500, {
+      migration: migrationName,
+    });
+    // Preserve the original error so its stack and message survive re-throwing.
+    this.cause = cause;
+  }
+}

package/src/errors/ModelNotFoundError.ts

@@ -0,0 +1,21 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when a query that requires a result finds none — e.g. `findOrFail()`,
+ * `firstOrFail()`, or implicit route-model binding. Carries an HTTP 404 status.
+ *
+ * @param model - The model name for the message.
+ * @param id - The looked-up id, when the failure was a by-id lookup.
+ */
+export class ModelNotFoundError extends ZerotalError {
+  constructor(model: string, id?: number | string) {
+    super(
+      id === undefined
+        ? `No ${model} record found for the given query`
+        : `No ${model} record found for ID: ${String(id)}`,
+      "E_MODEL_NOT_FOUND",
+      404,
+      id === undefined ? { model } : { model, id },
+    );
+  }
+}

package/src/errors/NPlusOneError.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export of the error thrown by the N+1 query detector when a relation is
+ * lazily loaded more times than the configured threshold in `mode: "throw"`.
+ * Defined in `../db/NPlusOneDetector.ts`.
+ */
+export { NPlusOneError } from "../db/NPlusOneDetector.ts";

package/src/errors/RelationNotLoadedError.ts

@@ -0,0 +1,19 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when a relation is accessed on a model that was not eager-loaded with
+ * `.with('relation')`, guarding against accidental lazy loads / N+1 queries.
+ *
+ * @param relation - The relation name that was accessed.
+ * @param model - The model the relation was accessed on.
+ */
+export class RelationNotLoadedError extends ZerotalError {
+  constructor(relation: string, model: string) {
+    super(
+      `Relation "${relation}" was accessed on ${model} without eager loading. Use .with('${relation}') in your query.`,
+      "E_RELATION_NOT_LOADED",
+      500,
+      { relation, model },
+    );
+  }
+}

package/src/errors/StateError.ts

@@ -0,0 +1,18 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when `model.transitionTo()` is called with a state that is not
+ * reachable from the model's current state, or when a target-state guard
+ * rejects the transition.
+ */
+export class StateError extends ZerotalError {
+  constructor(model: string, from: string, to: string, detail?: string) {
+    super(
+      detail ?? `Illegal transition on ${model}: cannot move from '${from}' to '${to}'.`,
+      "E_INVALID_TRANSITION",
+      422,
+      { model, from, to },
+    );
+    this.name = "StateError";
+  }
+}

package/src/errors/TransactionError.ts

@@ -0,0 +1,13 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when a database transaction cannot proceed — e.g. committing or rolling
+ * back outside an active transaction, or nesting/savepoint misuse.
+ *
+ * @param message - Human-readable description of the transaction failure.
+ */
+export class TransactionError extends ZerotalError {
+  constructor(message: string) {
+    super(message, "E_TRANSACTION_ERROR", 500);
+  }
+}

package/src/errors/UnsupportedDialectError.ts

@@ -0,0 +1,18 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown when a feature is invoked on a database dialect that cannot support
+ * it — e.g. `DB.advisoryLock()` on SQLite, which has no advisory-lock
+ * primitive. Failing loudly beats silently emitting another engine's SQL.
+ */
+export class UnsupportedDialectError extends ZerotalError {
+  constructor(feature: string, dialect: string) {
+    super(
+      `${feature} is not supported on the "${dialect}" dialect.`,
+      "E_UNSUPPORTED_DIALECT",
+      500,
+      { feature, dialect },
+    );
+    this.name = "UnsupportedDialectError";
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export { ModelNotFoundError } from "./ModelNotFoundError.ts";
+export { RelationNotLoadedError } from "./RelationNotLoadedError.ts";
+export { TransactionError } from "./TransactionError.ts";
+export { MigrationError } from "./MigrationError.ts";
+export { StateError } from "./StateError.ts";
+export { MassAssignmentError } from "./MassAssignmentError.ts";
+export { UnsupportedDialectError } from "./UnsupportedDialectError.ts";

package/src/events.ts

@@ -0,0 +1,112 @@
+/**
+ * The ORM's framework-event vocabulary. These are emitted on core's synchronous
+ * {@link FrameworkEvents} bus by the ORM's query, transaction, migration, and
+ * model-lifecycle machinery; observability packages subscribe to them by kind
+ * (their class name) without importing the classes.
+ *
+ * `ctx` is typed as `object` (the request `HttpContext` when inside a request)
+ * so these events carry no dependency back into the kernel or the pipeline.
+ */
+
+/**
+ * Emitted after every SQL query completes — carries the SQL, its bindings,
+ * timing, row count, and the active request context when inside one. Powers the
+ * query log, slow-query warnings, and the N+1 detector.
+ *
+ * @category Database
+ */
+export class QueryExecuted {
+  constructor(
+    readonly sql: string,
+    readonly bindings: unknown[],
+    readonly startMs: number,
+    readonly durationMs: number,
+    readonly rowCount: number,
+    /** Active HttpContext object, or undefined when outside a request. */
+    readonly ctx: object | undefined,
+  ) {}
+}
+
+/**
+ * Emitted when the N+1 detector fires for a repeated query pattern (the same
+ * SQL fingerprint run `count` times within one request).
+ *
+ * @category Database
+ */
+export class NPlusOneDetected {
+  constructor(
+    /** Normalised SQL fingerprint (parameter placeholders replaced with \x00). */
+    readonly fingerprint: string,
+    readonly count: number,
+    readonly ctx: object | undefined,
+  ) {}
+}
+
+/**
+ * Emitted when a database transaction begins.
+ * @category Database
+ */
+export class TransactionStarted {
+  constructor(
+    readonly txId: string,
+    readonly ctx: object | undefined,
+  ) {}
+}
+
+/**
+ * Emitted when a database transaction commits successfully.
+ * @category Database
+ */
+export class TransactionCommitted {
+  constructor(
+    readonly txId: string,
+    readonly durationMs: number,
+    readonly ctx: object | undefined,
+  ) {}
+}
+
+/**
+ * Emitted when a database transaction rolls back. `reason` is set when the
+ * rollback was triggered by a caught error.
+ * @category Database
+ */
+export class TransactionRolledBack {
+  constructor(
+    readonly txId: string,
+    readonly durationMs: number,
+    readonly reason: string | undefined,
+    readonly ctx: object | undefined,
+  ) {}
+}
+
+/**
+ * Emitted after a single migration runs up or down; `ok` is false and `error`
+ * is set when it failed.
+ * @category Database
+ */
+export class MigrationRan {
+  constructor(
+    readonly name: string,
+    readonly direction: "up" | "down",
+    readonly durationMs: number,
+    readonly ok: boolean,
+    readonly error?: string,
+  ) {}
+}
+
+/**
+ * Emitted after a model row is created, updated, or deleted. The panel aggregates
+ * these into per-model change counts. Suppressed during factory seeding (it rides
+ * the hook system, which mutes there).
+ *
+ * @category Database
+ */
+export class ModelChanged {
+  constructor(
+    /** Model class name, e.g. "User". */
+    readonly model: string,
+    /** Backing table, e.g. "users". */
+    readonly table: string,
+    readonly operation: "created" | "updated" | "deleted",
+  ) {}
+}

package/src/global.d.ts

@@ -0,0 +1,17 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// Bun extends Request with native route params (e.g. /users/:id → { id: '42' })
+interface Request {
+  readonly params?: Record<string, string>;
+}
+
+// Ambient mirror of the exported SQLInstance (see ./db/sql-types.ts) so test files
+// that reference it without an import still resolve. Source files import the exported
+// type, which shadows this within those modules.
+interface SQLInstance {
+  <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}

package/src/implicitBinding.ts

@@ -0,0 +1,73 @@
+import { setImplicitModelResolver, Str, singularize } from "@zerotal/core";
+import type { ModelBindingResolver, HttpContext } from "@zerotal/core";
+import { modelsByName } from "./model/decorators/_metadata.ts";
+
+interface ImplicitModel {
+  name: string;
+  implicitBinding?: boolean;
+  implicitBindingKey?: string;
+  findOrFail(id: number | string): Promise<unknown>;
+  resolveRouteBinding?(value: string, ctx: HttpContext, param: string): Promise<unknown>;
+}
+
+/**
+ * Find the registered model that should resolve a given route param, or undefined.
+ *
+ * Resolution order:
+ *   1. A model whose `static implicitBindingKey` equals the param name.
+ *   2. Class-name convention: `:user` -> `User`, `:blogPost` -> `BlogPost`, `:users` -> `User`.
+ * Models with `static implicitBinding = false` are skipped.
+ *
+ * @param paramName - The route parameter name (without the leading colon).
+ * @returns The matching model class, or `undefined` if none resolves.
+ * @internal
+ */
+export function modelForParam(paramName: string): ImplicitModel | undefined {
+  // 1. Explicit implicitBindingKey wins.
+  for (const ctor of modelsByName.values()) {
+    const M = ctor as unknown as ImplicitModel;
+    if (M.implicitBinding === false) continue;
+    if (M.implicitBindingKey && M.implicitBindingKey === paramName) return M;
+  }
+  // 2. Class-name convention.
+  // A model that set an explicit implicitBindingKey claims only that key (handled above),
+  // so it no longer answers to its class name here.
+  for (const candidate of [Str.pascalCase(paramName), Str.pascalCase(singularize(paramName))]) {
+    const ctor = modelsByName.get(candidate);
+    if (!ctor) continue;
+    const M = ctor as unknown as ImplicitModel;
+    if (M.implicitBinding === false) continue;
+    if (M.implicitBindingKey) continue;
+    return M;
+  }
+  return undefined;
+}
+
+/**
+ * Install the implicit route-model-binding resolver into the core Router. Called by
+ * `DatabaseProvider.onRegister()`. The resolver reads the model registry lazily (at route
+ * compile time), so it works no matter when models register during boot.
+ * @internal
+ */
+/**
+ * Build the binding resolver for a route param, or undefined when no model claims it.
+ *
+ * A model may own its lookup by declaring `static resolveRouteBinding` — resolving by a slug
+ * or username, scoping to the tenant, eager-loading a relation. It receives the param name,
+ * so one model can answer differently for `:user` and `:username` without matching on the
+ * URL. Without it, the default is a primary-key `findOrFail`.
+ *
+ * @internal
+ */
+export function resolverForParam(paramName: string): ModelBindingResolver | undefined {
+  const M = modelForParam(paramName);
+  if (!M) return undefined;
+  return (value, ctx) =>
+    typeof M.resolveRouteBinding === "function"
+      ? M.resolveRouteBinding(value, ctx, paramName)
+      : M.findOrFail(value);
+}
+
+export function registerImplicitBinding(): void {
+  setImplicitModelResolver(resolverForParam);
+}