@zerotal/orm 1.8.1 → 1.9.0

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,7 +41,11 @@ 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
@@ -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 };