@shaferllc/keel 0.35.0 → 0.58.0

package/dist/core/http/router.js

@@ -70,6 +70,11 @@ export class Route {
         this.def.domain = pattern;
         return this;
     }
+    /** Attach arbitrary metadata to the route — read it via `request.route.config`. */
+    config(data) {
+        Object.assign(this.def.config, data);
+        return this;
+    }
 }
 /** A group of routes sharing a prefix, middleware, and/or name prefix. */
 export class RouteGroup {
@@ -93,6 +98,12 @@ export class RouteGroup {
     use(mw) {
         return this.middleware(mw);
     }
+    /** Attach metadata to every route in the group (a route's own config wins). */
+    config(data) {
+        for (const r of this.routes)
+            r.config = { ...data, ...r.config };
+        return this;
+    }
     /** Constrain a parameter across every route in the group. */
     where(param, matcher) {
         for (const r of this.routes) {
@@ -317,10 +328,26 @@ export class Router {
             handler,
             middleware: [...this.group_mw],
             wheres: {},
+            config: {},
         };
         this.routes.push(def);
+        for (const hook of this.routeHooks)
+            hook(def);
         return new Route(def);
     }
+    routeHooks = [];
+    /**
+     * Observe route registration — called with each route's definition as it's
+     * added (and replayed for routes already registered). Handy for logging or
+     * building an API map. The `def` is live, so reading it later reflects fluent
+     * config (`.name()`, `.middleware()`) applied after registration.
+     */
+    onRoute(hook) {
+        for (const def of this.routes)
+            hook(def);
+        this.routeHooks.push(hook);
+        return this;
+    }
     /** Register a global parameter constraint, applied to every matching route. */
     where(param, matcher) {
         this.globalWheres[param] = matcherSource(matcher);
@@ -344,7 +371,9 @@ export class Router {
             throw new Error(`No route named [${name}].`);
         let path = def.path;
         for (const [k, v] of Object.entries(params)) {
-            path = path.replace(new RegExp(`:${k}\\??`), encodeURIComponent(String(v)));
+            // Global + word-boundary: replace every `:k` occurrence, and don't let
+            // `:id` match inside `:idx`.
+            path = path.replace(new RegExp(`:${k}\\b\\??`, "g"), encodeURIComponent(String(v)));
         }
         path = path.replace(/\/:[^/]+\?/g, "").replace(/:[^/]+/g, "");
         if (options.qs && Object.keys(options.qs).length) {

package/dist/core/index.d.ts

@@ -2,23 +2,27 @@
 export { Container } from "./container.js";
 export type { Token, Constructor, Factory } from "./container.js";
 export { Application } from "./application.js";
-export type { BootOptions } from "./application.js";
+export type { BootOptions, LifecycleHook, Configurator } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
 export type { LogLevel, LoggerOptions } from "./logger.js";
+export { requestLogger, requestLog } from "./request-logger.js";
+export type { RequestLoggerOptions } from "./request-logger.js";
 export { Events } from "./events.js";
 export type { Listener } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export type { CacheStore } from "./cache.js";
 export { serveStatic } from "./static.js";
 export type { StaticOptions } from "./static.js";
+export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
+export type { Disk, Contents } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
 export type { RateLimiterOptions } from "./rate-limit.js";
 export { db, setConnection, QueryBuilder } from "./database.js";
-export type { Connection, WriteResult, Row, Dialect, Operator } from "./database.js";
+export type { Connection, WriteResult, Row, Dialect, Operator, Paginated } from "./database.js";
 export { Model } from "./model.js";
 export type { CastType, Casts } from "./casts.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
@@ -28,12 +32,23 @@ 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 { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
+export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
+export type { Broadcaster, Subscriber, ChannelAuthorizer } from "./broadcasting.js";
+export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";
+export type { RedisConnection, SetOptions } from "./redis.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";
+export { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clearRequestDecorators, } from "./decorators.js";
+export type { RequestResolver } from "./decorators.js";
 export type { ConfigData } from "./config.js";
 export { View } from "./view.js";
 export type { Renderable, ViewConfig } from "./view.js";
+export { TemplateEngine, escapeHtml, templates, setTemplateEngine, render, } from "./template.js";
+export type { Filter, RenderContext } from "./template.js";
 export { ServiceProvider } from "./provider.js";
 export type { ProviderClass } from "./provider.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
@@ -41,10 +56,19 @@ export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher, MiddlewareRef
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export type { InertiaPage, InertiaOptions } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
-export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
-export { validate } from "./validation.js";
-export type { Schema } from "./validation.js";
+export { TestClient, TestResponse, testClient } from "./testing.js";
+export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
+export { validate, validateRequest, validated } from "./validation.js";
+export type { Schema, RequestSchemas } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export type { SessionOptions } from "./session.js";
 export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
 export type { UserProvider } from "./auth.js";
+export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export type { GateCallback, BeforeCallback } from "./authorization.js";
+export { Transformer } from "./transformer.js";
+export type { Attributes, DocumentOptions } from "./transformer.js";
+export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";
+export type { ServiceSchema, Context, ActionHandler, EventHandler, ActionDef, ActionSchema, ActionHooks, EventSchema, ServiceHooks, Visibility, EventType, BeforeHook, AfterHook, ErrorHook, Transporter, BrokerOptions, BrokerMiddleware, CallOptions, EmitOptions, MCallDefs, MCallOptions, } from "./broker.js";
+export { Vite, viteTags, viteAsset, viteReactRefresh } from "./vite.js";
+export type { ViteOptions, Manifest, ManifestChunk, Attributes as ViteAttributes, AttrValue, } from "./vite.js";

package/dist/core/index.js

@@ -2,11 +2,13 @@
 export { Container } from "./container.js";
 export { Application } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
+export { requestLogger, requestLog } from "./request-logger.js";
 export { Events } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
+export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
@@ -16,14 +18,25 @@ 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 { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
+export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
+export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.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 { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clearRequestDecorators, } from "./decorators.js";
 export { View } from "./view.js";
+export { TemplateEngine, escapeHtml, templates, setTemplateEngine, render, } from "./template.js";
 export { ServiceProvider } from "./provider.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
-export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
-export { validate } from "./validation.js";
+export { TestClient, TestResponse, testClient } from "./testing.js";
+export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
+export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
+export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export { Transformer } from "./transformer.js";
+export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";
+export { Vite, viteTags, viteAsset, viteReactRefresh } from "./vite.js";

package/dist/core/logger.d.ts

@@ -14,6 +14,11 @@ export interface LoggerOptions {
     pretty?: boolean;
     /** Fields merged into every log line. */
     bindings?: Record<string, unknown>;
+    /**
+     * Field paths to redact from log output — top-level keys (`"password"`) or dot
+     * paths (`"req.headers.authorization"`). Matched values become `"[redacted]"`.
+     */
+    redact?: string[];
 }
 export declare class Logger {
     private options;

package/dist/core/logger.js

@@ -7,6 +7,24 @@
  *   logger().error("payment failed", { orderId, error });
  */
 const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const REDACTED = "[redacted]";
+/** Return a copy of `obj` with `path` (dot-separated) redacted — clones only along the path. */
+function redactPath(obj, keys) {
+    const [head, ...rest] = keys;
+    if (head === undefined || !(head in obj))
+        return obj;
+    const clone = { ...obj };
+    if (rest.length === 0) {
+        clone[head] = REDACTED;
+    }
+    else {
+        const child = clone[head];
+        if (child && typeof child === "object") {
+            clone[head] = redactPath(child, rest);
+        }
+    }
+    return clone;
+}
 export class Logger {
     options;
     threshold;
@@ -18,13 +36,17 @@ export class Logger {
         if (LEVELS[level] < this.threshold)
             return;
         const time = new Date().toISOString();
+        let fields = { ...this.options.bindings, ...context };
+        for (const path of this.options.redact ?? []) {
+            fields = redactPath(fields, path.split("."));
+        }
         if (this.options.pretty) {
-            const extra = context ? " " + JSON.stringify(context) : "";
+            const extra = Object.keys(fields).length ? " " + JSON.stringify(fields) : "";
             const fn = level === "warn" ? console.warn : level === "error" ? console.error : console.log;
             fn(`[${time}] ${level.toUpperCase().padEnd(5)} ${message}${extra}`);
         }
         else {
-            console.log(JSON.stringify({ level, time, msg: message, ...this.options.bindings, ...context }));
+            console.log(JSON.stringify({ level, time, msg: message, ...fields }));
         }
     }
     debug(message, context) {

package/dist/core/migrations.js

@@ -165,11 +165,11 @@ export class Migrator {
     /** Names of migrations already applied. */
     async ran() {
         await this.ensure();
-        const rows = await this.conn.select("SELECT name FROM migrations", []);
+        const rows = (await this.conn.select("SELECT name FROM migrations", []));
         return rows.map((r) => String(r.name));
     }
     async maxBatch() {
-        const rows = await this.conn.select("SELECT MAX(batch) AS b FROM migrations", []);
+        const rows = (await this.conn.select("SELECT MAX(batch) AS b FROM migrations", []));
         return Number(rows[0]?.b ?? 0);
     }
     /** Run all pending migrations. Returns the names applied. */
@@ -196,7 +196,7 @@ export class Migrator {
         const batch = await this.maxBatch();
         if (!batch)
             return [];
-        const rows = await this.conn.select(this.ph("SELECT name FROM migrations WHERE batch = ?"), [batch]);
+        const rows = (await this.conn.select(this.ph("SELECT name FROM migrations WHERE batch = ?"), [batch]));
         const schema = new SchemaBuilder(this.conn, this.dialect);
         const rolled = [];
         for (const name of rows.map((r) => String(r.name)).reverse()) {

package/dist/core/model.d.ts

@@ -15,7 +15,7 @@
  *   user.email = "new@x.com";
  *   await user.save();
  */
-import { type QueryBuilder, type Row } from "./database.js";
+import { type QueryBuilder, type Row, type Paginated } from "./database.js";
 import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relations.js";
 import { type Casts } from "./casts.js";
 type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
@@ -28,6 +28,10 @@ export declare class Model {
     static guarded: string[];
     /** Column -> cast type; values round-trip as real JS types. */
     static casts: Casts;
+    /** Auto-manage `created_at` / `updated_at` on write. Off by default. */
+    static timestamps: boolean;
+    static createdAtColumn: string;
+    static updatedAtColumn: string;
     [key: string]: unknown;
     constructor(attributes?: Row);
     /** A raw query builder scoped to this model's table. */
@@ -36,6 +40,8 @@ export declare class Model {
     static filterFillable(attributes: Row): Row;
     /** Cast attributes to their storable primitives for a write. */
     static toDatabase(attributes: Row): Row;
+    /** Stamp created_at/updated_at onto a write payload when timestamps are on. */
+    static stampTimestamps(data: Row, forInsert: boolean): Row;
     static all<T extends Model>(this: ModelClass<T>): Promise<T[]>;
     static find<T extends Model>(this: ModelClass<T>, id: unknown): Promise<T | null>;
     static findOrFail<T extends Model>(this: ModelClass<T>, id: unknown): Promise<T>;
@@ -43,6 +49,14 @@ export declare class Model {
     /** Fetch models matching a simple equality condition. */
     static where<T extends Model>(this: ModelClass<T>, column: string, value: unknown): Promise<T[]>;
     static create<T extends Model>(this: ModelClass<T>, attributes: Row): Promise<T>;
+    /** A page of models plus pagination metadata. */
+    static paginate<T extends Model>(this: ModelClass<T>, page?: number, perPage?: number): Promise<Paginated<T>>;
+    /** Find the first row matching `match`, or create one from `{ ...match, ...values }`. */
+    static firstOrCreate<T extends Model>(this: ModelClass<T>, match: Row, values?: Row): Promise<T>;
+    /** Update the first row matching `match` with `values`, or create it. */
+    static updateOrCreate<T extends Model>(this: ModelClass<T>, match: Row, values?: Row): Promise<T>;
+    /** A query scoped to every column/value in `match`. */
+    private static matching;
     /**
      * Eager-load relations onto an array of models with one extra query each —
      * the fix for N+1. Each name must be a relationship method on the model.
@@ -65,6 +79,10 @@ export declare class Model {
     getRelation<T = unknown>(name: string): T | undefined;
     /** Insert (no primary key) or update (has one). */
     save(): Promise<this>;
+    /** Mass-assign then save — `fill` + `save` in one call. */
+    update(attributes: Row): Promise<this>;
+    /** Reload this model's columns from the database. */
+    refresh(): Promise<this>;
     delete(): Promise<void>;
     /** Merge mass-assignable attributes into the model (cast, not saved). */
     fill(attributes: Row): this;

package/dist/core/model.js

@@ -40,6 +40,10 @@ export class Model {
     static guarded = [];
     /** Column -> cast type; values round-trip as real JS types. */
     static casts = {};
+    /** Auto-manage `created_at` / `updated_at` on write. Off by default. */
+    static timestamps = false;
+    static createdAtColumn = "created_at";
+    static updatedAtColumn = "updated_at";
     constructor(attributes = {}) {
         // Hydration is unguarded (rows come from the database) but always cast.
         Object.assign(this, applyCasts(attributes, this.constructor.casts, castGet));
@@ -70,6 +74,17 @@ export class Model {
     static toDatabase(attributes) {
         return applyCasts(attributes, this.casts, castSet);
     }
+    /** Stamp created_at/updated_at onto a write payload when timestamps are on. */
+    static stampTimestamps(data, forInsert) {
+        if (!this.timestamps)
+            return data;
+        const now = new Date().toISOString();
+        const out = { ...data };
+        if (forInsert)
+            out[this.createdAtColumn] = now;
+        out[this.updatedAtColumn] = now;
+        return out;
+    }
     static async all() {
         const rows = await db(this.table).get();
         return rows.map((row) => new this(row));
@@ -95,12 +110,46 @@ export class Model {
     }
     static async create(attributes) {
         const filtered = this.filterFillable(attributes);
-        const id = await db(this.table).insertGetId(this.toDatabase(filtered));
+        const write = this.stampTimestamps(this.toDatabase(filtered), true);
+        const id = await db(this.table).insertGetId(write);
         const model = new this(filtered);
+        if (this.timestamps) {
+            model[this.createdAtColumn] = write[this.createdAtColumn];
+            model[this.updatedAtColumn] = write[this.updatedAtColumn];
+        }
         if (id != null)
             model[this.primaryKey] = id;
         return model;
     }
+    /** A page of models plus pagination metadata. */
+    static async paginate(page = 1, perPage = 15) {
+        const result = await db(this.table).paginate(page, perPage);
+        return { ...result, data: result.data.map((row) => new this(row)) };
+    }
+    /** Find the first row matching `match`, or create one from `{ ...match, ...values }`. */
+    static async firstOrCreate(match, values = {}) {
+        const row = await this.matching(match).first();
+        if (row)
+            return new this(row);
+        return this.create({ ...match, ...values });
+    }
+    /** Update the first row matching `match` with `values`, or create it. */
+    static async updateOrCreate(match, values = {}) {
+        const row = await this.matching(match).first();
+        if (row) {
+            const model = new this(row);
+            await model.forceFill(values).save();
+            return model;
+        }
+        return this.create({ ...match, ...values });
+    }
+    /** A query scoped to every column/value in `match`. */
+    static matching(match) {
+        let q = db(this.table);
+        for (const [column, value] of Object.entries(match))
+            q = q.where(column, value);
+        return q;
+    }
     /**
      * Eager-load relations onto an array of models with one extra query each —
      * the fix for N+1. Each name must be a relationship method on the model.
@@ -161,10 +210,17 @@ export class Model {
     async save() {
         const ctor = this.ctor();
         const { table, primaryKey } = ctor;
-        const data = ctor.toDatabase({ ...this });
-        const idValue = data[primaryKey];
+        const idValue = this[primaryKey];
+        const forInsert = idValue == null;
+        const data = ctor.stampTimestamps(ctor.toDatabase({ ...this }), forInsert);
+        // Reflect the stamps back onto the instance.
+        if (ctor.timestamps) {
+            if (forInsert)
+                this[ctor.createdAtColumn] = data[ctor.createdAtColumn];
+            this[ctor.updatedAtColumn] = data[ctor.updatedAtColumn];
+        }
         delete data[primaryKey];
-        if (idValue != null) {
+        if (!forInsert) {
             await db(table).where(primaryKey, idValue).update(data);
         }
         else {
@@ -174,6 +230,18 @@ export class Model {
         }
         return this;
     }
+    /** Mass-assign then save — `fill` + `save` in one call. */
+    async update(attributes) {
+        return this.fill(attributes).save();
+    }
+    /** Reload this model's columns from the database. */
+    async refresh() {
+        const ctor = this.ctor();
+        const row = await db(ctor.table).where(ctor.primaryKey, this[ctor.primaryKey]).first();
+        if (row)
+            Object.assign(this, applyCasts(row, ctor.casts, castGet));
+        return this;
+    }
     async delete() {
         const { table, primaryKey } = this.ctor();
         await db(table).where(primaryKey, this[primaryKey]).delete();

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);
+}