@shaferllc/keel 0.35.0 → 0.36.0

package/README.md

@@ -178,6 +178,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Factories & Seeders](./docs/factories.md) | Built-in Faker, model factories, seeders |
 | [Mail](./docs/mail.md) | Fluent mailer, pluggable transports, edge-safe |
 | [Queues & Jobs](./docs/queues.md) | Dispatch jobs, pluggable drivers, workers |
+| [Notifications](./docs/notifications.md) | Multi-channel (mail/db), queueable |
 | [Events](./docs/events.md) | Emit/listen decoupling, async listeners |
 | [Cache](./docs/cache.md) | TTLs, the remember pattern, pluggable stores |
 | [Logger](./docs/logger.md) | Leveled structured logging, child loggers |
@@ -234,6 +235,7 @@ config, and the console. On deck:
 - [x] Model attribute casts + mass-assignment guarding — **v0.33.0**
 - [x] Mail (fluent mailer, pluggable transports) — **v0.34.0**
 - [x] Queues / background jobs (pluggable drivers) — **v0.35.0**
+- [x] Notifications (multi-channel, queueable) — **v0.36.0**
 - [ ] Publish `src/core` as the `@keel/core` package
 
 See [CHANGELOG.md](./CHANGELOG.md) for release history.

package/dist/core/index.d.ts

@@ -28,6 +28,8 @@ export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail
 export type { Message, Transport, MailerOptions, FetchTransportOptions } from "./mail.js";
 export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
 export type { Dispatchable, JobOptions, QueueDriver, Drainable, QueuedJob } from "./queue.js";
+export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
+export type { Notifiable, MailContent, Channel } from "./notification.js";
 export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
 export type { Migration } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";

package/dist/core/index.js

@@ -16,6 +16,7 @@ export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
 export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
 export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
+export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
 export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
 export { View } from "./view.js";

package/dist/core/notification.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Notifications — send a message to a recipient over one or more channels
+ * (mail, database, or your own), inline or through the queue. This is where the
+ * mail and queue layers compose: a notification declares *what* to say and
+ * *which channels* carry it, and each channel decides *how*.
+ *
+ *   class InvoicePaid extends Notification {
+ *     constructor(private amount: number) { super(); }
+ *     via() { return ["mail", "database"]; }
+ *     toMail() { return { subject: "Payment received", text: `Thanks for $${this.amount}.` }; }
+ *     toArray() { return { amount: this.amount }; }
+ *   }
+ *
+ *   await notify(user, new InvoicePaid(4200));   // user.email routes the mail
+ *
+ * Set `shouldQueue = true` on a notification to deliver it from a queued job
+ * instead of inline. Channels are pluggable, so `array` (for tests) or a custom
+ * push-to-provider channel slot in the same way transports and drivers do.
+ */
+/** A recipient. Anything with routing info — often a `User` model. */
+export interface Notifiable {
+    /** Return the address/id for a channel (e.g. an email). Falls back to `email`/`id`. */
+    routeNotificationFor?(channel: string): string | number | undefined;
+    [key: string]: unknown;
+}
+/** What a notification hands the mail channel. */
+export interface MailContent {
+    subject: string;
+    text?: string;
+    html?: string;
+    from?: string;
+    /** Override the resolved recipient address. */
+    to?: string;
+}
+export declare abstract class Notification {
+    /** Deliver from a queued job instead of inline. */
+    shouldQueue: boolean;
+    /** Channels to deliver on. Default: mail. */
+    via(_notifiable: Notifiable): string[];
+    /** Build the mail-channel content. Required if `via` includes "mail". */
+    toMail?(notifiable: Notifiable): MailContent;
+    /** Build the payload stored/serialized by the database and array channels. */
+    toArray?(notifiable: Notifiable): Record<string, unknown>;
+}
+/** Resolve where a notifiable receives a given channel. */
+export declare function routeFor(notifiable: Notifiable, channel: string): string | number | undefined;
+/** The bridge that actually delivers a notification on one channel. */
+export interface Channel {
+    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+}
+/** Delivers via the mailer, using the notification's `toMail`. */
+export declare class MailChannel implements Channel {
+    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+}
+/** Persists the notification's `toArray` payload to a table via the query builder. */
+export declare class DatabaseChannel implements Channel {
+    private table;
+    constructor(table?: string);
+    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+}
+/** Collects deliveries in memory — for tests. */
+export declare class ArrayChannel implements Channel {
+    readonly sent: {
+        notifiable: Notifiable;
+        notification: Notification;
+    }[];
+    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+}
+export declare class Notifier {
+    private channels;
+    /** Register (or replace) a channel by name. */
+    channel(name: string, channel: Channel): this;
+    private deliver;
+    /** Send a notification to one or many recipients. */
+    send(notifiables: Notifiable | Notifiable[], notification: Notification): Promise<void>;
+}
+/** Register the default notifier used by `notify()`. */
+export declare function setNotifier(instance: Notifier): Notifier;
+/** The default notifier instance (register channels on it). */
+export declare function getNotifier(): Notifier;
+/** Send a notification to one or many notifiables via the default notifier. */
+export declare function notify(notifiables: Notifiable | Notifiable[], notification: Notification): Promise<void>;

package/dist/core/notification.js

@@ -0,0 +1,129 @@
+/**
+ * Notifications — send a message to a recipient over one or more channels
+ * (mail, database, or your own), inline or through the queue. This is where the
+ * mail and queue layers compose: a notification declares *what* to say and
+ * *which channels* carry it, and each channel decides *how*.
+ *
+ *   class InvoicePaid extends Notification {
+ *     constructor(private amount: number) { super(); }
+ *     via() { return ["mail", "database"]; }
+ *     toMail() { return { subject: "Payment received", text: `Thanks for $${this.amount}.` }; }
+ *     toArray() { return { amount: this.amount }; }
+ *   }
+ *
+ *   await notify(user, new InvoicePaid(4200));   // user.email routes the mail
+ *
+ * Set `shouldQueue = true` on a notification to deliver it from a queued job
+ * instead of inline. Channels are pluggable, so `array` (for tests) or a custom
+ * push-to-provider channel slot in the same way transports and drivers do.
+ */
+import { db } from "./database.js";
+import { getMailer } from "./mail.js";
+import { dispatch } from "./queue.js";
+export class Notification {
+    /** Deliver from a queued job instead of inline. */
+    shouldQueue = false;
+    /** Channels to deliver on. Default: mail. */
+    via(_notifiable) {
+        return ["mail"];
+    }
+}
+/** Resolve where a notifiable receives a given channel. */
+export function routeFor(notifiable, channel) {
+    if (typeof notifiable.routeNotificationFor === "function") {
+        const route = notifiable.routeNotificationFor(channel);
+        if (route !== undefined && route !== null)
+            return route;
+    }
+    if (channel === "mail")
+        return notifiable.email;
+    return notifiable.id;
+}
+/* -------------------------------- channels -------------------------------- */
+/** Delivers via the mailer, using the notification's `toMail`. */
+export class MailChannel {
+    async send(notifiable, notification) {
+        if (!notification.toMail) {
+            throw new Error(`${notification.constructor.name} has no toMail() for the mail channel.`);
+        }
+        const content = notification.toMail(notifiable);
+        const to = content.to ?? routeFor(notifiable, "mail");
+        if (!to) {
+            throw new Error("Notification: no mail route (set `email` or `routeNotificationFor`).");
+        }
+        const message = getMailer().message().to(String(to)).subject(content.subject);
+        if (content.from)
+            message.from(content.from);
+        if (content.text)
+            message.text(content.text);
+        if (content.html)
+            message.html(content.html);
+        await message.send();
+    }
+}
+/** Persists the notification's `toArray` payload to a table via the query builder. */
+export class DatabaseChannel {
+    table;
+    constructor(table = "notifications") {
+        this.table = table;
+    }
+    async send(notifiable, notification) {
+        const data = notification.toArray ? notification.toArray(notifiable) : {};
+        await db(this.table).insert({
+            type: notification.constructor.name,
+            notifiable_id: routeFor(notifiable, "database") ?? null,
+            data: JSON.stringify(data),
+        });
+    }
+}
+/** Collects deliveries in memory — for tests. */
+export class ArrayChannel {
+    sent = [];
+    async send(notifiable, notification) {
+        this.sent.push({ notifiable, notification });
+    }
+}
+/* -------------------------------- notifier -------------------------------- */
+export class Notifier {
+    channels = new Map([["mail", new MailChannel()]]);
+    /** Register (or replace) a channel by name. */
+    channel(name, channel) {
+        this.channels.set(name, channel);
+        return this;
+    }
+    async deliver(notifiable, notification) {
+        for (const name of notification.via(notifiable)) {
+            const channel = this.channels.get(name);
+            if (!channel)
+                throw new Error(`No notification channel "${name}" registered.`);
+            await channel.send(notifiable, notification);
+        }
+    }
+    /** Send a notification to one or many recipients. */
+    async send(notifiables, notification) {
+        const recipients = Array.isArray(notifiables) ? notifiables : [notifiables];
+        const run = async () => {
+            for (const recipient of recipients)
+                await this.deliver(recipient, notification);
+        };
+        if (notification.shouldQueue)
+            await dispatch(run);
+        else
+            await run();
+    }
+}
+/* --------------------------------- global --------------------------------- */
+let notifier = new Notifier();
+/** Register the default notifier used by `notify()`. */
+export function setNotifier(instance) {
+    notifier = instance;
+    return notifier;
+}
+/** The default notifier instance (register channels on it). */
+export function getNotifier() {
+    return notifier;
+}
+/** Send a notification to one or many notifiables via the default notifier. */
+export function notify(notifiables, notification) {
+    return notifier.send(notifiables, notification);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -37,6 +37,7 @@
     "serve": "tsx bin/keel.ts serve",
     "dev": "tsx watch bin/keel.ts serve",
     "typecheck": "tsc --noEmit",
+    "typecheck:docs": "npm run build && tsc -p tsconfig.docs.json",
     "test": "node --import tsx --test tests/*.test.ts",
     "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='tests/**' tests/*.test.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json",