@zerotal/notifications 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-08-31
+
+### Changed
+
+- **The database channel is built on first use, not at construction.** Registering the
+  provider used to open a `DatabaseChannel` against `database.table` — default
+  `notifications` — and create that table, whether or not any notification ever routed
+  there. An app that never uses the channel now never touches the table, and the
+  manager no longer resolves a database connection while it is being constructed.
+
+### Added
+
+- **A doctor check for a `notifications` table that is not the framework's.**
+  `notifications` is a very ordinary name for a table an app already owns, and one
+  app's was a completely different shape — `household_id`, `title`, `body`,
+  `action_url`, with an in-app inbox reading it. The only thing between the
+  framework's channel and a wrong-shaped insert into that inbox was that no
+  notification's `channels()` happened to return `"database"`. A convention holding
+  back data corruption is a convention that will lose, so `zt doctor` now says so
+  before the first notification does. Silent when the table does not exist yet, which
+  is every fresh checkout.
+
 ## [1.10.0] — 2026-08-30
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/notifications",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,12 +30,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.10.0",
-    "@zerotal/orm": "1.10.0",
-    "@zerotal/queue": "1.10.0"
+    "@zerotal/core": "1.11.0",
+    "@zerotal/orm": "1.11.0",
+    "@zerotal/queue": "1.11.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.10.0",
+    "@zerotal/broadcasting": "1.11.0",
     "typescript": "^5.8.0"
   },
   "description": "Multi-channel notifications for Zerotal — mail (SMTP/Resend), database, broadcast, Slack, and SMS.",

package/src/NotificationManager.ts

@@ -23,13 +23,29 @@ export class NotificationManager {
   private readonly _resolvers = new Map<string, ChannelResolver>();
   /** Resolved channel instances, memoized per name. */
   private readonly _channels = new Map<string, NotificationChannel>();
-  private readonly _db: DatabaseChannel;
+  /**
+   * The database channel, built on first use rather than at construction.
+   *
+   * It used to be built in the constructor, which meant every app that registered
+   * this provider opened a `DatabaseChannel` against `database.table` — default
+   * `notifications` — whether or not any notification ever routed there. `notifications`
+   * is a very ordinary name for a table an app already owns, and one app's is a
+   * completely different shape: `household_id`, `user_id`, `title`, `body`,
+   * `action_url`, with an in-app inbox reading it. The only thing standing between
+   * the framework's channel and a wrong-shaped insert into that inbox was that no
+   * notification's `channels()` happened to return `"database"`. A convention holding
+   * back data corruption is a convention that will lose.
+   *
+   * Building it lazily does not make the collision safe — `notificationsTableCheck`
+   * is what reports that — but it means an app that never uses the channel never
+   * touches the table, and it stops the manager resolving a database connection at
+   * construction time.
+   */
+  private _dbChannel: DatabaseChannel | undefined;
 
   constructor(private readonly config: NotificationConfigShape) {
-    this._db = new DatabaseChannel(config.database.table, _getConnection());
-
     this._resolvers.set("mail", () => new MailChannel(config.mail));
-    this._resolvers.set("database", () => this._db);
+    this._resolvers.set("database", () => this.database);
     this._resolvers.set("broadcast", () => new BroadcastChannel());
 
     this._resolvers.set("slack", () => {
@@ -241,7 +257,8 @@ export class NotificationManager {
 
   /** Expose the database channel for direct queries (unread, markAsRead). */
   get database(): DatabaseChannel {
-    return this._db;
+    this._dbChannel ??= new DatabaseChannel(this.config.database.table, _getConnection());
+    return this._dbChannel;
   }
 
   private async _dispatch(

package/src/provider/NotificationProvider.ts

@@ -7,6 +7,7 @@ import { installNotificationsObservability } from "../observability.ts";
 import { installNotificationStats } from "../stats.ts";
 import { installNotificationsAdmin } from "../admin.ts";
 import { mailDriverCheck } from "../doctor.ts";
+import { notificationsTableCheck } from "../tableDoctor.ts";
 
 declare module "@zerotal/core" {
   interface ContainerBindings {
@@ -40,6 +41,7 @@ export class NotificationProvider extends ServiceProvider {
     // `zt doctor`, and through it `zt deploy`: mail going to a log file in
     // production is the quietest failure this package has.
     this.app.registerDoctorCheck?.(mailDriverCheck);
+    this.app.registerDoctorCheck?.(notificationsTableCheck);
   }
 
   override async onBooted(): Promise<void> {

package/src/tableDoctor.ts

@@ -0,0 +1,92 @@
+/**
+ * The check for a `notifications` table that is not the framework's.
+ *
+ * `database.table` defaults to `notifications`, which is a very ordinary name for a
+ * table an app already owns. One app's was a completely different shape —
+ * `household_id`, `user_id`, `title`, `body`, `action_url`, with an in-app inbox
+ * reading it — and the only thing standing between the framework's channel and a
+ * wrong-shaped insert into that inbox was that no notification's `channels()`
+ * happened to return `"database"`.
+ *
+ * A convention holding back data corruption is a convention that will lose. This
+ * says so at `zt doctor` time, before the first notification does.
+ *
+ * @module
+ */
+import type { Application } from "@zerotal/core";
+import type { DoctorCheck, DoctorCheckResult } from "@zerotal/core";
+import { NotificationConfig } from "./config.ts";
+import type { NotificationConfigShape } from "./types.ts";
+
+/** Columns `DatabaseChannel` writes on every insert. */
+const REQUIRED = [
+  "id",
+  "notifiable_type",
+  "notifiable_id",
+  "type",
+  "data",
+  "read_at",
+  "created_at",
+] as const;
+
+/** The table's column names, or `null` when it does not exist / cannot be read. */
+async function _columnsOf(sql: unknown, table: string): Promise<Set<string> | null> {
+  const query = sql as (strings: TemplateStringsArray, ...v: unknown[]) => Promise<unknown[]>;
+  try {
+    // `pragma_table_info` is the table-valued form, so the name binds as a parameter
+    // rather than being concatenated into the statement.
+    const rows = (await query`SELECT name FROM pragma_table_info(${table})`) as {
+      name?: string;
+    }[];
+    if (rows.length === 0) return null;
+    return new Set(rows.map((r) => String(r.name)));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Report a configured notifications table whose shape is not the one the channel
+ * writes.
+ *
+ * Silent when the table does not exist yet — that is the normal state before the
+ * migration runs, and warning about it would fire on every fresh checkout.
+ */
+export const notificationsTableCheck: DoctorCheck = {
+  id: "notifications-table",
+  label: "Notifications table",
+  async run(app: Application): Promise<DoctorCheckResult> {
+    let table = "notifications";
+    let sql: unknown;
+    try {
+      const config = app.container.makeSync("config") as { get<T>(k: string, d: T): T };
+      table = config.get<NotificationConfigShape>("notifications", NotificationConfig()).database
+        .table;
+      sql = app.container.makeSync("db");
+    } catch {
+      return { status: "ok", message: "no database connection to check" };
+    }
+    if (!sql) return { status: "ok", message: "no database connection to check" };
+
+    const columns = await _columnsOf(sql, table);
+    if (columns === null) {
+      // Not created yet, or not SQLite. Either way there is nothing to compare.
+      return { status: "ok", message: `${table} not present yet` };
+    }
+
+    const missing = REQUIRED.filter((name) => !columns.has(name));
+    if (missing.length === 0) return { status: "ok", message: `${table} matches` };
+
+    return {
+      status: "fail",
+      message:
+        `The table "${table}" exists but is missing ${missing.join(", ")} — so it is not the ` +
+        `table @zerotal/notifications writes, and a notification routed to the "database" ` +
+        `channel would insert the wrong shape into it.`,
+      fix:
+        `Point the framework elsewhere with database.table in config/notifications.ts ` +
+        `(e.g. "framework_notifications"), or run the package's migration to create the ` +
+        `table it expects.`,
+    };
+  },
+};