@shaferllc/keel 0.59.0 → 0.68.0

package/dist/core/mail.js

@@ -13,15 +13,33 @@
  *     .html("<h1>Hi</h1>")
  *     .send();
  *
- * In tests, register an `ArrayTransport` and assert on `transport.sent`.
+ * Sending is slow and it fails — which is exactly what a queue is for. `sendLater()`
+ * puts the message on the queue instead of holding the request open for an SMTP
+ * round trip:
+ *
+ *   await mail().to(user.email).subject("Welcome").html(body).sendLater();
+ *
+ * In tests, `fakeMail()` swaps the transport for one that records and asserts.
+ */
+import { logger, emit, hasApplication } from "./helpers.js";
+import { dispatch, Job } from "./queue.js";
+import { contentTypeFor } from "./storage.js";
+/**
+ * Fire a mail lifecycle event, but only if there's an application to fire it on —
+ * the mailer has to work in a unit test that never bootstrapped one. A listener
+ * that throws still surfaces; it's only the missing-app case we skip.
  */
-import { logger } from "./helpers.js";
+async function notify(event, message) {
+    if (hasApplication())
+        await emit(event, message);
+}
 function list(value) {
     if (value === undefined)
         return [];
     return Array.isArray(value) ? value : [value];
 }
-/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+/* --------------------------------- builder -------------------------------- */
+/** A fluent, immutable-ish builder — chain setters, then `send()` or `sendLater()`. */
 export class PendingMail {
     mailer;
     message = { to: [], subject: "" };
@@ -64,6 +82,29 @@ export class PendingMail {
         (this.message.headers ??= {})[name] = value;
         return this;
     }
+    /** Attach a file. The content type is inferred from the extension if omitted. */
+    attach(filename, content, contentType) {
+        (this.message.attachments ??= []).push({
+            filename,
+            content,
+            contentType: contentType ?? contentTypeFor(filename),
+        });
+        return this;
+    }
+    /**
+     * Attach an image and give it a content id, so the HTML body can show it inline:
+     *
+     *   .embed("logo", bytes, "logo.png").html(`<img src="cid:logo">`)
+     */
+    embed(cid, content, filename = cid, contentType) {
+        (this.message.attachments ??= []).push({
+            filename,
+            content,
+            contentType: contentType ?? contentTypeFor(filename),
+            cid,
+        });
+        return this;
+    }
     /** Seed several fields at once (merges into what's been chained). */
     fill(partial) {
         const { to, cc, bcc, ...rest } = partial;
@@ -76,25 +117,79 @@ export class PendingMail {
         Object.assign(this.message, rest);
         return this;
     }
+    /** The message as composed so far — before the mailer applies its defaults. */
+    toMessage() {
+        return { ...this.message };
+    }
     /** Freeze and hand the message to the mailer. */
     async send() {
         return this.mailer.send(this.message);
     }
+    /**
+     * Queue the message instead of sending it now — the request returns without
+     * waiting on the provider, and a failed send retries on the queue rather than
+     * failing the user's action.
+     *
+     * With the default `SyncDriver` this still sends inline; register a real queue
+     * driver to actually defer it.
+     */
+    async sendLater() {
+        await this.mailer.sendLater(this.message);
+    }
+}
+/* ------------------------------- class mails ------------------------------ */
+/**
+ * A reusable, testable email as a class — the mail equivalent of a `Job`.
+ * Implement `build()` to compose the message; the mailer calls it for you.
+ *
+ *   export class WelcomeEmail extends BaseMail {
+ *     constructor(private user: User) { super(); }
+ *
+ *     build(message: PendingMail) {
+ *       message.to(this.user.email).subject("Welcome").html(`<h1>Hi ${this.user.name}</h1>`);
+ *     }
+ *   }
+ *
+ *   await send(new WelcomeEmail(user));       // or sendLater(new WelcomeEmail(user))
+ */
+export class BaseMail {
+}
+/** The job that carries a queued message. Exported so a driver can recognize it. */
+export class SendMailJob extends Job {
+    message;
+    mailerName;
+    constructor(message, mailerName) {
+        super();
+        this.message = message;
+        this.mailerName = mailerName;
+    }
+    async handle() {
+        await mailer(this.mailerName).send(this.message);
+    }
 }
+/* --------------------------------- mailer --------------------------------- */
 export class Mailer {
     transport;
     options;
-    constructor(transport, options = {}) {
+    name;
+    constructor(transport, options = {}, 
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    name = "default") {
         this.transport = transport;
         this.options = options;
+        this.name = name;
     }
     /** Start composing a message. */
     message() {
         return new PendingMail(this);
     }
-    /** Validate, apply defaults, and dispatch through the transport. */
-    async send(message) {
-        const final = { ...message, from: message.from ?? this.options.from };
+    /** Apply this mailer's defaults and check the message is sendable. */
+    prepare(message) {
+        const final = {
+            ...message,
+            from: message.from ?? this.options.from,
+            replyTo: message.replyTo ?? this.options.replyTo,
+        };
         if (!final.to.length)
             throw new Error("Mail: at least one recipient (to) is required.");
         if (!final.subject)
@@ -103,9 +198,29 @@ export class Mailer {
             throw new Error("Mail: a text or html body is required.");
         if (!final.from)
             throw new Error("Mail: a from address is required (set one or a default).");
+        return final;
+    }
+    /** Validate, apply defaults, and dispatch through the transport. */
+    async send(message) {
+        const final = this.prepare(message);
+        await notify("mail.sending", final);
         await this.transport.send(final);
+        await notify("mail.sent", final);
+        return final;
+    }
+    /** Validate, apply defaults, and put the message on the queue. */
+    async sendLater(message) {
+        // Validate *now*, not on the worker: a malformed message should blow up at
+        // the call site, where the stack trace means something.
+        const final = this.prepare(message);
+        await dispatch(new SendMailJob(final, this.name));
+        await notify("mail.queued", final);
         return final;
     }
+    /** The underlying transport, for provider-specific operations. */
+    get driver() {
+        return this.transport;
+    }
 }
 /* ------------------------------- transports ------------------------------- */
 /** Collects sent messages in memory — the default, and ideal for tests. */
@@ -140,18 +255,151 @@ export function fetchTransport(options) {
         },
     };
 }
+/**
+ * A `Mailer` that records instead of delivering, with assertions — what
+ * `fakeMail()` installs so tests never talk to a provider.
+ */
+export class FakeMailer extends Mailer {
+    mails = [];
+    constructor(name = "default", options = {}) {
+        // A from address so a fake never trips the "from is required" check.
+        super(new ArrayTransport(), { from: "fake@example.com", ...options }, name);
+    }
+    async send(message) {
+        const final = await super.send(message);
+        this.mails.push({ message: final, queued: false });
+        return final;
+    }
+    async sendLater(message) {
+        // Validate exactly as a real mailer would, but don't touch the queue —
+        // recording the intent *is* the point.
+        const final = this.prepare(message);
+        this.mails.push({ message: final, queued: true });
+        await notify("mail.queued", final);
+        return final;
+    }
+    /** Everything sent immediately. */
+    sent() {
+        return this.mails.filter((m) => !m.queued).map((m) => m.message);
+    }
+    /** Everything queued with `sendLater()`. */
+    queued() {
+        return this.mails.filter((m) => m.queued).map((m) => m.message);
+    }
+    assertSent(where) {
+        const matches = this.sent().filter((m) => where?.(m) ?? true);
+        if (matches.length)
+            return;
+        throw new Error(where && this.sent().length
+            ? `Expected a sent mail matching the predicate. ${this.sent().length} were sent, but none matched.`
+            : `Expected a mail to be sent, but none was. ${this.summary()}`);
+    }
+    assertNotSent(where) {
+        const found = this.sent().filter((m) => where?.(m) ?? true).length;
+        if (found)
+            throw new Error(`Expected no matching mail to be sent, but ${found} was.`);
+    }
+    assertSentCount(expected) {
+        const found = this.sent().length;
+        if (found !== expected) {
+            throw new Error(`Expected ${expected} mail(s) to be sent, but ${found} were.`);
+        }
+    }
+    assertQueued(where) {
+        const matches = this.queued().filter((m) => where?.(m) ?? true);
+        if (matches.length)
+            return;
+        throw new Error(where && this.queued().length
+            ? `Expected a queued mail matching the predicate. ${this.queued().length} were queued, but none matched.`
+            : `Expected a mail to be queued, but none was. ${this.summary()}`);
+    }
+    assertNotQueued(where) {
+        const found = this.queued().filter((m) => where?.(m) ?? true).length;
+        if (found)
+            throw new Error(`Expected no matching mail to be queued, but ${found} was.`);
+    }
+    assertQueuedCount(expected) {
+        const found = this.queued().length;
+        if (found !== expected) {
+            throw new Error(`Expected ${expected} mail(s) to be queued, but ${found} were.`);
+        }
+    }
+    /** Nothing sent and nothing queued. */
+    assertNothingSent() {
+        if (this.mails.length) {
+            throw new Error(`Expected no mail at all, but ${this.mails.length} were recorded. ${this.summary()}`);
+        }
+    }
+    summary() {
+        if (!this.mails.length)
+            return "No mail was sent or queued.";
+        const subjects = this.mails.map((m) => `"${m.message.subject}"`).join(", ");
+        return `Recorded: ${subjects}.`;
+    }
+}
 /* --------------------------------- global --------------------------------- */
-let mailer = new Mailer(new ArrayTransport());
-/** Register the default mailer used by `mail()`. */
-export function setMailer(transport, options = {}) {
-    mailer = new Mailer(transport, options);
-    return mailer;
+const mailers = new Map([["default", new Mailer(new ArrayTransport())]]);
+/** Mailers displaced by `fakeMail()`, so `restoreMail()` can put them back. */
+const realMailers = new Map();
+/** Register a mailer, optionally under a name (default: `"default"`). */
+export function setMailer(transport, options = {}, name = "default") {
+    const instance = new Mailer(transport, options, name);
+    mailers.set(name, instance);
+    return instance;
+}
+/** The default mailer, or a named one registered with `setMailer(…, …, name)`. */
+export function mailer(name = "default") {
+    const instance = mailers.get(name);
+    if (!instance)
+        throw new Error(`No mailer named "${name}". Register it with setMailer().`);
+    return instance;
 }
 /** The default mailer instance. */
 export function getMailer() {
-    return mailer;
+    return mailer();
+}
+/** Start a message on a mailer: `mail().to(…).subject(…).send()`. */
+export function mail(name = "default") {
+    return mailer(name).message();
+}
+/** Build a `BaseMail` into a message on the given mailer. */
+async function build(email, name) {
+    const pending = mailer(name).message();
+    await email.build(pending);
+    return pending.toMessage();
 }
-/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
-export function mail() {
-    return mailer.message();
+/** Send a class-based mail now. */
+export async function send(email, name = "default") {
+    return mailer(name).send(await build(email, name));
+}
+/** Queue a class-based mail. */
+export async function sendLater(email, name = "default") {
+    return mailer(name).sendLater(await build(email, name));
+}
+/**
+ * Swap a mailer for a `FakeMailer` so tests never talk to a provider, and assert
+ * on what was sent or queued. Undo with `restoreMail()`.
+ *
+ *   const mail = fakeMail();
+ *   await registerUser();
+ *   mail.assertQueued((m) => m.subject === "Welcome");
+ */
+export function fakeMail(name = "default") {
+    const existing = mailers.get(name);
+    // Only remember the *real* mailer — faking twice must not stash a fake.
+    if (existing && !realMailers.has(name))
+        realMailers.set(name, existing);
+    const fake = new FakeMailer(name);
+    mailers.set(name, fake);
+    return fake;
+}
+/** Restore the real mailer after `fakeMail()`. With no name, restores them all. */
+export function restoreMail(name) {
+    const names = name ? [name] : [...realMailers.keys()];
+    for (const key of names) {
+        const real = realMailers.get(key);
+        if (real)
+            mailers.set(key, real);
+        realMailers.delete(key);
+    }
 }

package/dist/core/model.d.ts

@@ -22,6 +22,8 @@ type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
 export declare class Model {
     static table: string;
     static primaryKey: string;
+    /** Which registered connection this model uses; the default when unset. */
+    static connection: string | undefined;
     /** Columns mass-assignable via `create`/`fill` (allowlist). */
     static fillable: string[];
     /** Columns NOT mass-assignable (denylist). Ignored when `fillable` is set. */

package/dist/core/model.js

@@ -34,6 +34,8 @@ function serialize(value) {
 export class Model {
     static table = "";
     static primaryKey = "id";
+    /** Which registered connection this model uses; the default when unset. */
+    static connection = undefined;
     /** Columns mass-assignable via `create`/`fill` (allowlist). */
     static fillable = [];
     /** Columns NOT mass-assignable (denylist). Ignored when `fillable` is set. */
@@ -51,7 +53,7 @@ export class Model {
     /* ------------------------------ static -------------------------------- */
     /** A raw query builder scoped to this model's table. */
     static query() {
-        return db(this.table);
+        return db(this.table, this.connection);
     }
     /** Keep only the attributes mass-assignment allows (fillable / guarded). */
     static filterFillable(attributes) {
@@ -86,11 +88,11 @@ export class Model {
         return out;
     }
     static async all() {
-        const rows = await db(this.table).get();
+        const rows = await db(this.table, this.connection).get();
         return rows.map((row) => new this(row));
     }
     static async find(id) {
-        const row = await db(this.table).where(this.primaryKey, id).first();
+        const row = await db(this.table, this.connection).where(this.primaryKey, id).first();
         return row ? new this(row) : null;
     }
     static async findOrFail(id) {
@@ -100,18 +102,18 @@ export class Model {
         return model;
     }
     static async first() {
-        const row = await db(this.table).first();
+        const row = await db(this.table, this.connection).first();
         return row ? new this(row) : null;
     }
     /** Fetch models matching a simple equality condition. */
     static async where(column, value) {
-        const rows = await db(this.table).where(column, value).get();
+        const rows = await db(this.table, this.connection).where(column, value).get();
         return rows.map((row) => new this(row));
     }
     static async create(attributes) {
         const filtered = this.filterFillable(attributes);
         const write = this.stampTimestamps(this.toDatabase(filtered), true);
-        const id = await db(this.table).insertGetId(write);
+        const id = await db(this.table, this.connection).insertGetId(write);
         const model = new this(filtered);
         if (this.timestamps) {
             model[this.createdAtColumn] = write[this.createdAtColumn];
@@ -123,7 +125,7 @@ export class Model {
     }
     /** A page of models plus pagination metadata. */
     static async paginate(page = 1, perPage = 15) {
-        const result = await db(this.table).paginate(page, perPage);
+        const result = await db(this.table, this.connection).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 }`. */
@@ -145,7 +147,7 @@ export class Model {
     }
     /** A query scoped to every column/value in `match`. */
     static matching(match) {
-        let q = db(this.table);
+        let q = db(this.table, this.connection);
         for (const [column, value] of Object.entries(match))
             q = q.where(column, value);
         return q;
@@ -209,7 +211,7 @@ export class Model {
     /** Insert (no primary key) or update (has one). */
     async save() {
         const ctor = this.ctor();
-        const { table, primaryKey } = ctor;
+        const { table, primaryKey, connection } = ctor;
         const idValue = this[primaryKey];
         const forInsert = idValue == null;
         const data = ctor.stampTimestamps(ctor.toDatabase({ ...this }), forInsert);
@@ -221,10 +223,10 @@ export class Model {
         }
         delete data[primaryKey];
         if (!forInsert) {
-            await db(table).where(primaryKey, idValue).update(data);
+            await db(table, connection).where(primaryKey, idValue).update(data);
         }
         else {
-            const id = await db(table).insertGetId(data);
+            const id = await db(table, connection).insertGetId(data);
             if (id != null)
                 this[primaryKey] = id;
         }
@@ -237,14 +239,14 @@ export class Model {
     /** 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();
+        const row = await db(ctor.table, ctor.connection).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();
+        const { table, primaryKey, connection } = this.ctor();
+        await db(table, connection).where(primaryKey, this[primaryKey]).delete();
     }
     /** Merge mass-assignable attributes into the model (cast, not saved). */
     fill(attributes) {

package/dist/core/provider.d.ts

@@ -6,6 +6,11 @@
  *             here — nothing is guaranteed to be registered yet.
  * boot():     called after every provider has registered. Safe to resolve
  *             and wire things together here.
+ * ready():    called once the whole app has booted (after every provider's
+ *             boot() and any onReady hooks). For work that needs a fully-live
+ *             app — attaching to the running server, warming a cache.
+ * shutdown(): called during graceful termination, in reverse registration
+ *             order (LIFO). Close connections, flush queues, cancel timers.
  *
  * Register with options to make a provider reusable:
  *
@@ -21,5 +26,7 @@ export declare abstract class ServiceProvider<O = Record<string, unknown>> {
     constructor(app: Application, options?: O);
     register(): void | Promise<void>;
     boot(): void | Promise<void>;
+    ready(): void | Promise<void>;
+    shutdown(): void | Promise<void>;
 }
 export type ProviderClass = new (app: Application, options?: any) => ServiceProvider;

package/dist/core/provider.js

@@ -6,6 +6,11 @@
  *             here — nothing is guaranteed to be registered yet.
  * boot():     called after every provider has registered. Safe to resolve
  *             and wire things together here.
+ * ready():    called once the whole app has booted (after every provider's
+ *             boot() and any onReady hooks). For work that needs a fully-live
+ *             app — attaching to the running server, warming a cache.
+ * shutdown(): called during graceful termination, in reverse registration
+ *             order (LIFO). Close connections, flush queues, cancel timers.
  *
  * Register with options to make a provider reusable:
  *
@@ -23,4 +28,6 @@ export class ServiceProvider {
     }
     register() { }
     boot() { }
+    ready() { }
+    shutdown() { }
 }