@zerotal/orm 1.8.1 → 1.10.0

package/src/model/BaseModel.ts

@@ -107,6 +107,8 @@ HookRegistry.onAfterRun = (ModelClass, hook, model): void => {
 /**
  * Register a named connection that models can select via `static connection`.
  * Stored on the current OrmContext (execution-scoped), not a global.
+ *
+ * @internal
  */
 export function registerModelConnection(name: string, conn: SQLInstance, dialect?: Dialect): void {
   currentOrmContext().namedConnections.set(name, conn);
@@ -159,6 +161,8 @@ export function _getModelConnection(): SQLInstance {
  * multi-database strategy: it returns the active tenant's connection so every model
  * query transparently hits the right database. Returns `null` to defer to the normal
  * resolution. Defaults to a no-op, so it changes nothing until something registers it.
+ *
+ * @internal
  */
 export type ContextConnectionResolver = (ModelClass?: typeof BaseModel) => SQLInstance | null;
 let _contextConnectionResolver: ContextConnectionResolver | null = null;
@@ -167,6 +171,8 @@ let _contextConnectionResolver: ContextConnectionResolver | null = null;
  * Register a context-aware connection resolver (pass `null` to clear). Consulted by
  * `_resolveConn` after explicit transactions and `static connection` named bindings,
  * but before the default connection — so transactions and pinned connections still win.
+ *
+ * @internal
  */
 export function registerConnectionResolver(fn: ContextConnectionResolver | null): void {
   _contextConnectionResolver = fn;

package/src/model/ModelQueryBuilder.ts

@@ -275,6 +275,7 @@ function _createPivotCollection<T extends BaseModel>(
 // BaseModel as a type only — no cycle.
 
 export type GlobalScopeCallback = (qb: ModelQueryBuilder<BaseModel>) => void;
+/** @internal */
 export function _globalScopeRegistry(): Map<ClassRef, Map<string, GlobalScopeCallback>> {
   return currentOrmContext().globalScopes as unknown as Map<
     ClassRef,

package/src/model/OrmContext.ts

@@ -18,6 +18,8 @@ import type { SQLInstance } from "../db/sql-types.ts";
  * } finally {
  *   useOrmContext(prev);
  * }
+ *
+ * @internal
  */
 export class OrmContext {
   /** Explicit connection override that wins over the resolved default (used by tests / `withDatabase`). */
@@ -34,7 +36,11 @@ export class OrmContext {
 
 let _ctx = new OrmContext();
 
-/** Return the currently active {@link OrmContext}. */
+/**
+ * Return the currently active {@link OrmContext}.
+ *
+ * @internal
+ */
 export function currentOrmContext(): OrmContext {
   return _ctx;
 }
@@ -45,6 +51,8 @@ export function currentOrmContext(): OrmContext {
  *
  * @param ctx The context to activate (defaults to a new, empty context).
  * @returns The context that was active before this call.
+ *
+ * @internal
  */
 export function useOrmContext(ctx: OrmContext = new OrmContext()): OrmContext {
   const prev = _ctx;
@@ -52,7 +60,11 @@ export function useOrmContext(ctx: OrmContext = new OrmContext()): OrmContext {
   return prev;
 }
 
-/** Replace the active context with a fresh, empty {@link OrmContext} (test/teardown reset). */
+/**
+ * Replace the active context with a fresh, empty {@link OrmContext} (test/teardown reset).
+ *
+ * @internal
+ */
 export function resetOrmContext(): void {
   _ctx = new OrmContext();
 }

package/src/model/decorators/belongsTo.ts

@@ -5,9 +5,9 @@ export interface BelongsToOptions {
   /** FK column on this (child) model pointing to the related row (e.g. `user_id`). */
   foreignKey: string;
   /** Key on the related model the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Return a default (unsaved) related model instead of null when absent. */
-  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void);
+  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void) | undefined;
 }
 
 /**

package/src/model/decorators/column.ts

@@ -82,11 +82,11 @@ export interface ColumnOptions {
    *
    * @default "string"
    */
-  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json";
+  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json" | undefined;
   /** Mark this column as the table's primary key. */
-  primary?: boolean;
+  primary?: boolean | undefined;
   /** Allow SQL `NULL` for this column. */
-  nullable?: boolean;
+  nullable?: boolean | undefined;
   /** Default value applied when none is provided. */
   default?: unknown;
   /**
@@ -96,9 +96,9 @@ export interface ColumnOptions {
    * usually a correctness property (a webhook idempotency key, an invoice number),
    * and `migrate:generate` can only emit constraints it can see declared.
    */
-  unique?: boolean;
+  unique?: boolean | undefined;
   /** Add a plain (non-unique) index on this column. */
-  index?: boolean;
+  index?: boolean | undefined;
   /**
    * Shorthand cast types automatically serialize/deserialize the column value.
    * Can also be a custom object with `get`/`set` functions for full control.
@@ -134,9 +134,10 @@ export interface ColumnOptions {
         get?: (dbValue: unknown) => unknown;
         set?: (jsValue: unknown) => unknown;
       }
-    | CastContract<unknown>;
+    | CastContract<unknown>
+    | undefined;
   /** Enum object (e.g. the imported TS enum) used alongside cast: 'enum'. */
-  enumValues?: Record<string, string | number>;
+  enumValues?: Record<string, string | number> | undefined;
 }
 
 /**

package/src/model/decorators/hasMany.ts

@@ -5,7 +5,7 @@ export interface HasManyOptions {
   /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
   foreignKey: string;
   /** Parent local key the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/hasManyThrough.ts

@@ -6,9 +6,9 @@ export interface HasManyThroughOptions {
   /** FK on the related table referencing the through model (e.g. 'user_id' on posts). */
   secondKey: string;
   /** Parent local key the firstKey references. Default 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Through local key the secondKey references. Default 'id'. */
-  throughLocalKey?: string;
+  throughLocalKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/hasOne.ts

@@ -5,7 +5,7 @@ export interface HasOneOptions {
   /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
   foreignKey: string;
   /** Parent local key the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/manyToMany.ts

@@ -9,13 +9,13 @@ export interface ManyToManyOptions {
   /** Pivot column referencing the related model (e.g. `role_id`). */
   pivotRelatedKey: string;
   /** Parent local key the pivot FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Related local key the pivot relatedKey references. Defaults to `'id'`. */
-  relatedKey?: string;
+  relatedKey?: string | undefined;
   /** Extra pivot columns to hydrate onto each related model's `pivot` bag. */
-  withPivot?: string[];
+  withPivot?: string[] | undefined;
   /** Maintain created_at / updated_at on the pivot table during attach/sync. */
-  withTimestamps?: boolean;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/morphMany.ts

@@ -7,7 +7,7 @@ export interface MorphManyOptions {
    */
   morphName: string;
   /** Override the local key. Defaults to 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/morphOne.ts

@@ -7,7 +7,7 @@ export interface MorphOneOptions {
    */
   morphName: string;
   /** Override the local key. Defaults to 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/morphTo.ts

@@ -7,12 +7,12 @@ export interface MorphToOptions {
    * Override the _type column name. Defaults to `<propertyName>_type`.
    * e.g. property `commentable` → `commentable_type`.
    */
-  morphTypeColumn?: string;
+  morphTypeColumn?: string | undefined;
   /**
    * Override the _id column name. Defaults to `<propertyName>_id`.
    * e.g. property `commentable` → `commentable_id`.
    */
-  morphForeignKey?: string;
+  morphForeignKey?: string | undefined;
 }
 
 function _toSnake(s: string): string {

package/src/model/decorators/morphToMany.ts

@@ -6,11 +6,11 @@ export interface MorphToManyOptions {
   /** FK on the pivot table referencing the related model (e.g. 'tag_id'). */
   relatedPivotKey: string;
   /** Pivot table name. Defaults to `{morphName}s`. */
-  pivotTable?: string;
+  pivotTable?: string | undefined;
   /** Extra pivot columns to hydrate. */
-  withPivot?: string[];
+  withPivot?: string[] | undefined;
   /** Maintain pivot timestamps. */
-  withTimestamps?: boolean;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/morphedByMany.ts

@@ -6,9 +6,9 @@ export interface MorphedByManyOptions {
   /** FK on the pivot referencing the parent model (e.g. 'tag_id'). */
   parentPivotKey: string;
   /** Pivot table name. Defaults to `{morphName}s`. */
-  pivotTable?: string;
-  withPivot?: string[];
-  withTimestamps?: boolean;
+  pivotTable?: string | undefined;
+  withPivot?: string[] | undefined;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/table.ts

@@ -11,9 +11,9 @@ import type { ClassRef } from "../../support/classRef.ts";
  */
 export interface TableOptions {
   /** Enable / disable automatic timestamp columns. @default true */
-  timestamps?: boolean;
+  timestamps?: boolean | undefined;
   /** Override the primary key column name. @default "id" */
-  primaryKey?: string;
+  primaryKey?: string | undefined;
 }
 
 /**

package/src/model/hooks/HookRegistry.ts

@@ -36,6 +36,8 @@ const _suppressCtx = new AsyncLocalStorage<true>();
 /**
  * Run `fn` with all model hooks and observers silenced.
  * Used internally by Factory when `dispatchEvents()` has NOT been called.
+ *
+ * @internal
  */
 export function _suppressHooks<T>(fn: () => Promise<T>): Promise<T> {
   return _suppressCtx.run(true, fn);

package/src/observability.ts

@@ -85,6 +85,8 @@ function _ctxPath(ctx: object): string {
 /**
  * Subscribe the ORM's events to every installed observer. Returns a disposer that
  * removes every subscription; call it from the ORM provider's `onStopping()`.
+ *
+ * @internal
  */
 export function installOrmObservability(app: Application): () => void {
   const unsubs: Array<() => void> = [];

package/src/provider/DatabaseProvider.ts

@@ -1,6 +1,6 @@
 import type { SQLInstance } from "../db/sql-types.ts";
 import { ServiceProvider, registerErrorDiagnoser, isProdLike, deployEnv } from "@zerotal/core";
-import type { AppEnvironment } from "@zerotal/core";
+import type { AppEnvironment, DoctorCheck } from "@zerotal/core";
 import type { ConfigManager } from "@zerotal/core/config";
 import { SQL } from "bun";
 import { DB, _getConnection } from "../db/DB.ts";
@@ -18,6 +18,7 @@ import { autoMigrateConcern } from "../schema/autoMigrate.ts";
 import { registerImplicitBinding } from "../implicitBinding.ts";
 import { installOrmObservability } from "../observability.ts";
 import { diagnoseMissingRelation } from "../diagnostics/missingRelation.ts";
+import { pendingMigrationsCheck } from "../diagnostics/pendingMigrationsCheck.ts";
 import {
   registerRunMigrationsEndpoint,
   RUN_MIGRATIONS_PATH,
@@ -207,6 +208,15 @@ export class DatabaseProvider extends ServiceProvider {
     }
   }
 
+  /**
+   * The overlay answers "why did this fail" after something already has. This asks
+   * the same question before anything breaks, which is the cheaper moment to hear
+   * it — `doctor` already boots the app and already holds the connection.
+   */
+  override doctorChecks(): DoctorCheck[] {
+    return [pendingMigrationsCheck];
+  }
+
   override async onBooted(): Promise<void> {
     // Forward the ORM's framework events to whatever observers are installed.
     this._disposeObservability = installOrmObservability(this.app);
@@ -256,6 +266,12 @@ export class DatabaseProvider extends ServiceProvider {
     runner.registerLazy("db:seed", () =>
       import("../commands/DbSeedCommand.ts").then((m) => m.DbSeedCommand),
     );
+    // The counterpart to every command above it. `migrate`, `migrate:fresh` and
+    // `db:seed` all assume the file will still be there; this is the one that
+    // makes that assumption survivable.
+    runner.registerLazy("db:backup", () =>
+      import("../commands/DbBackupCommand.ts").then((m) => m.DbBackupCommand),
+    );
     runner.registerLazy("make:seeder", () =>
       import("../commands/MakeSeederCommand.ts").then((m) => m.MakeSeederCommand),
     );

package/src/schema/MigrationCodegen.ts

@@ -111,6 +111,8 @@ function alterTableBlocks(newColumns: NewColumn[]): string {
  *   - Creates new tables with `Schema.create()`
  *   - Adds new columns with `Schema.table()` (ALTER TABLE ADD COLUMN)
  *   - Drops created tables in `down()` (column additions are left for manual rollback)
+ *
+ * @internal
  */
 export function generateMigrationContent(className: string, diff: DiffResult): string {
   const upParts: string[] = [];

package/src/schema/ModelInspector.ts

@@ -7,6 +7,7 @@ import type { ClassRef } from "../support/classRef.ts";
 
 // ── Model schema descriptor ───────────────────────────────────────────────────
 
+/** @internal */
 export interface ModelColumn {
   name: string;
   type: ColumnOptions["type"]; // 'string' | 'text' | 'number' | 'boolean' | 'datetime' | 'json'
@@ -19,6 +20,7 @@ export interface ModelColumn {
   index?: boolean;
 }
 
+/** @internal */
 export interface ModelSchema {
   table: string;
   primaryKey: string;
@@ -109,6 +111,8 @@ function encryptedColumns(
  * by child classes, matching normal TypeScript class semantics.
  *
  * Used by `migrate:generate` to compare model intent against the live DB.
+ *
+ * @internal
  */
 export const ModelInspector = {
   /**

package/src/schema/SchemaDiffer.ts

@@ -3,20 +3,24 @@ import { columnDbName, type ModelSchema, type ModelColumn } from "./ModelInspect
 
 // -- Diff result types ---------------------------------------------------------
 
+/** @internal */
 export interface NewTable {
   schema: ModelSchema;
 }
 
+/** @internal */
 export interface NewColumn {
   table: string;
   column: ModelColumn;
 }
 
+/** @internal */
 export interface DroppedColumn {
   table: string;
   column: string;
 }
 
+/** @internal */
 export interface DiffResult {
   newTables: NewTable[];
   newColumns: NewColumn[];
@@ -36,6 +40,8 @@ export interface DiffResult {
  *
  * Additive deltas (newTables, newColumns) are always safe to apply. Dropped
  * columns are reported separately and only applied by a disruptive synchronize.
+ *
+ * @internal
  */
 export const SchemaDiffer = {
   async diff(schemas: ModelSchema[]): Promise<DiffResult> {

package/src/schema/SchemaInspector.ts

@@ -3,6 +3,7 @@ import { _getDialect } from "../model/BaseModel.ts";
 
 // ── DB column descriptor (normalised across dialects) ─────────────────────────
 
+/** @internal */
 export interface LiveColumn {
   name: string;
   rawType: string; // original SQL type string from the DB (uppercase)
@@ -10,6 +11,7 @@ export interface LiveColumn {
   primary: boolean;
 }
 
+/** @internal */
 export interface LiveTable {
   name: string;
   columns: LiveColumn[];
@@ -38,6 +40,8 @@ async function queryParam<T>(sql: string, value: unknown): Promise<T[]> {
 /**
  * Queries the live database to enumerate tables and their column definitions.
  * Used by `migrate:generate` to compute what has changed since the last migration.
+ *
+ * @internal
  */
 export const SchemaInspector = {
   /** Return all user-defined table names in the current DB. */

package/src/schema/autoMigrate.ts

@@ -41,14 +41,18 @@ function applyColumn(table: TableBuilder, col: ModelColumn): void {
   else if (col.index) table.index(dbName);
 }
 
-/** Options for {@link synchronizeSchema}. */
+/**
+ * Options for {@link synchronizeSchema}.
+ *
+ * @internal
+ */
 export interface SynchronizeOptions {
   /**
    * When true, also DROP columns that exist in the database but are no longer
    * declared by any model. Off by default - additive changes are always safe,
    * drops can lose data.
    */
-  disruptive?: boolean;
+  disruptive?: boolean | undefined;
 }
 
 /**
@@ -61,6 +65,8 @@ export interface SynchronizeOptions {
  *
  * Returns the diff that was applied (additive deltas are empty when already in sync;
  * `droppedColumns` is populated but only acted on when `disruptive` is set).
+ *
+ * @internal
  */
 export async function synchronizeSchema(options: SynchronizeOptions = {}): Promise<DiffResult> {
   const diff = await SchemaDiffer.diff(ModelInspector.all());
@@ -112,7 +118,11 @@ export async function synchronizeSchema(options: SynchronizeOptions = {}): Promi
   return diff;
 }
 
-/** Resolved, normalised form of the `database.synchronize` config value. */
+/**
+ * Resolved, normalised form of the `database.synchronize` config value.
+ *
+ * @internal
+ */
 export interface ResolvedSyncOptions {
   enabled: boolean;
   disruptive: boolean;
@@ -124,6 +134,8 @@ export interface ResolvedSyncOptions {
  *   false / undefined        -> { enabled: false, disruptive: false }
  *   true                     -> { enabled: true,  disruptive: false }  (additive)
  *   { enabled, disruptive? } -> as given (enabled defaults true when the object is present)
+ *
+ * @internal
  */
 export function resolveSyncOptions(raw: unknown): ResolvedSyncOptions {
   if (raw === true) return { enabled: true, disruptive: false };