@shaferllc/keel 0.59.0 → 0.68.0

package/dist/core/logger.js

@@ -5,49 +5,135 @@
  *
  *   logger().info("user registered", { userId: user.id });
  *   logger().error("payment failed", { orderId, error });
+ *
+ * Output goes through a `Sink` — `console` by default, but any function, so logs
+ * can go to a file, an HTTP collector, or a buffer in tests. Register extra
+ * loggers by name (`setLogger(audit, "audit")`) when a subsystem needs its own
+ * level or destination.
  */
-const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const LEVELS = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+};
 const REDACTED = "[redacted]";
-/** Return a copy of `obj` with `path` (dot-separated) redacted — clones only along the path. */
-function redactPath(obj, keys) {
+function normalizeRedact(redact) {
+    if (!redact)
+        return undefined;
+    const options = Array.isArray(redact) ? { paths: redact } : redact;
+    if (!options.paths.length)
+        return undefined;
+    return { paths: options.paths, censor: options.censor ?? REDACTED, remove: options.remove ?? false };
+}
+/**
+ * Return a copy of `obj` with `keys` (a split dot path) redacted. Clones only
+ * along the path, so untouched branches keep their identity. A `*` segment
+ * matches every key at that level.
+ */
+function redactPath(obj, keys, options) {
     const [head, ...rest] = keys;
-    if (head === undefined || !(head in obj))
+    if (head === undefined)
+        return obj;
+    const targets = head === "*" ? Object.keys(obj) : head in obj ? [head] : [];
+    if (!targets.length)
         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);
+    for (const key of targets) {
+        if (rest.length === 0) {
+            if (options.remove)
+                delete clone[key];
+            else
+                clone[key] = options.censor;
+        }
+        else {
+            const child = clone[key];
+            if (child && typeof child === "object" && !Array.isArray(child)) {
+                clone[key] = redactPath(child, rest, options);
+            }
         }
     }
     return clone;
 }
+/** The default sink: JSON to stdout, or a pretty single line when `pretty`. */
+export function consoleSink(pretty = false) {
+    return ({ level, time, msg, fields }) => {
+        const write = level === "warn"
+            ? console.warn
+            : level === "error" || level === "fatal"
+                ? console.error
+                : console.log;
+        if (pretty) {
+            const extra = Object.keys(fields).length ? " " + JSON.stringify(fields) : "";
+            write(`[${time}] ${level.toUpperCase().padEnd(5)} ${msg}${extra}`);
+        }
+        else {
+            write(JSON.stringify({ level, time, msg, ...fields }));
+        }
+    };
+}
+/** A sink that collects records in memory — for tests. Assert on `.records`. */
+export class MemorySink {
+    records = [];
+    /** The sink function to hand to `LoggerOptions.sink`. */
+    sink = (record) => {
+        this.records.push(record);
+    };
+    /** Records at one level. */
+    at(level) {
+        return this.records.filter((r) => r.level === level);
+    }
+    /** The messages logged, in order. */
+    messages() {
+        return this.records.map((r) => r.msg);
+    }
+    clear() {
+        this.records.length = 0;
+    }
+}
 export class Logger {
     options;
     threshold;
+    redact;
+    sink;
     constructor(options = {}) {
         this.options = options;
         this.threshold = LEVELS[options.level ?? "info"];
+        this.redact = normalizeRedact(options.redact);
+        this.sink = options.sink ?? consoleSink(options.pretty);
+    }
+    /**
+     * Whether a level would be emitted. Check it before building an expensive
+     * context object — the work of assembling it happens whether or not the line
+     * is ever written.
+     *
+     *   if (logger().isLevelEnabled("debug")) {
+     *     logger().debug("state", { snapshot: expensiveSnapshot() });
+     *   }
+     */
+    isLevelEnabled(level) {
+        return this.options.enabled !== false && LEVELS[level] >= this.threshold;
+    }
+    /** Run `fn` only if `level` would be emitted — the callback form of the above. */
+    ifLevelEnabled(level, fn) {
+        if (this.isLevelEnabled(level))
+            fn(this);
     }
     write(level, message, context) {
-        if (LEVELS[level] < this.threshold)
+        if (!this.isLevelEnabled(level))
             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 = 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, ...fields }));
+        if (this.redact) {
+            for (const path of this.redact.paths) {
+                fields = redactPath(fields, path.split("."), this.redact);
+            }
         }
+        this.sink({ level, time: new Date().toISOString(), msg: message, fields });
+    }
+    trace(message, context) {
+        this.write("trace", message, context);
     }
     debug(message, context) {
         this.write("debug", message, context);
@@ -61,6 +147,14 @@ export class Logger {
     error(message, context) {
         this.write("error", message, context);
     }
+    /** An unrecoverable failure — the loudest level. */
+    fatal(message, context) {
+        this.write("fatal", message, context);
+    }
+    /** Log at a level chosen at runtime. */
+    log(level, message, context) {
+        this.write(level, message, context);
+    }
     /** A child logger with additional bound fields (e.g. a request id). */
     child(bindings) {
         return new Logger({
@@ -69,3 +163,27 @@ export class Logger {
         });
     }
 }
+/* -------------------------------- registry -------------------------------- */
+const loggers = new Map();
+/**
+ * Register a logger under a name, so a subsystem can have its own level or
+ * destination:
+ *
+ *   setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+ *   namedLogger("audit").trace("permission granted", { userId });
+ *
+ * The default logger is the application's `Logger` singleton — resolve that with
+ * the global `logger()` helper, not this.
+ */
+export function setLogger(instance, name) {
+    loggers.set(name, instance);
+    return instance;
+}
+/** A logger registered with `setLogger`. Throws for an unknown name. */
+export function namedLogger(name) {
+    const instance = loggers.get(name);
+    if (!instance) {
+        throw new Error(`No logger named "${name}". Register it with setLogger(logger, name).`);
+    }
+    return instance;
+}

package/dist/core/mail.d.ts

@@ -13,8 +13,28 @@
  *     .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 { Job } from "./queue.js";
+/** A file travelling with the message. */
+export interface Attachment {
+    filename: string;
+    /** Raw bytes, or a string (UTF-8 encoded). */
+    content: string | Uint8Array;
+    /** MIME type. Inferred from the filename's extension when omitted. */
+    contentType?: string;
+    /**
+     * A content id, for embedding in the HTML body: an attachment with `cid: "logo"`
+     * is referenced as `<img src="cid:logo">`. Implies an inline disposition.
+     */
+    cid?: string;
+}
 /** A normalized, ready-to-send message. */
 export interface Message {
     to: string[];
@@ -26,6 +46,7 @@ export interface Message {
     text?: string;
     html?: string;
     headers?: Record<string, string>;
+    attachments?: Attachment[];
 }
 /** The bridge to your email provider. */
 export interface Transport {
@@ -34,8 +55,10 @@ export interface Transport {
 export interface MailerOptions {
     /** Default `from` address for messages that don't set one. */
     from?: string;
+    /** Default `replyTo` for messages that don't set one. */
+    replyTo?: string;
 }
-/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+/** A fluent, immutable-ish builder — chain setters, then `send()` or `sendLater()`. */
 export declare class PendingMail {
     private mailer;
     private message;
@@ -49,23 +72,76 @@ export declare class PendingMail {
     text(text: string): this;
     html(html: string): this;
     header(name: string, value: string): this;
+    /** Attach a file. The content type is inferred from the extension if omitted. */
+    attach(filename: string, content: string | Uint8Array, contentType?: string): 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: string, content: string | Uint8Array, filename?: string, contentType?: string): this;
     /** Seed several fields at once (merges into what's been chained). */
     fill(partial: Partial<{
         to: string | string[];
         cc: string | string[];
         bcc: string | string[];
     } & Omit<Message, "to" | "cc" | "bcc">>): this;
+    /** The message as composed so far — before the mailer applies its defaults. */
+    toMessage(): Message;
     /** Freeze and hand the message to the mailer. */
     send(): Promise<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.
+     */
+    sendLater(): Promise<void>;
+}
+/**
+ * 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 declare abstract class BaseMail {
+    abstract build(message: PendingMail): void | Promise<void>;
+}
+/** The job that carries a queued message. Exported so a driver can recognize it. */
+export declare class SendMailJob extends Job {
+    readonly message: Message;
+    readonly mailerName: string;
+    constructor(message: Message, mailerName: string);
+    handle(): Promise<void>;
 }
 export declare class Mailer {
     private transport;
     private options;
-    constructor(transport: Transport, options?: MailerOptions);
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    readonly name: string;
+    constructor(transport: Transport, options?: MailerOptions, 
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    name?: string);
     /** Start composing a message. */
     message(): PendingMail;
+    /** Apply this mailer's defaults and check the message is sendable. */
+    protected prepare(message: Message): Message;
     /** Validate, apply defaults, and dispatch through the transport. */
     send(message: Message): Promise<Message>;
+    /** Validate, apply defaults, and put the message on the queue. */
+    sendLater(message: Message): Promise<Message>;
+    /** The underlying transport, for provider-specific operations. */
+    get driver(): Transport;
 }
 /** Collects sent messages in memory — the default, and ideal for tests. */
 export declare class ArrayTransport implements Transport {
@@ -86,9 +162,54 @@ export interface FetchTransportOptions {
 }
 /** A generic HTTP transport for provider APIs (Resend, Postmark, …), via `fetch`. */
 export declare function fetchTransport(options: FetchTransportOptions): Transport;
-/** Register the default mailer used by `mail()`. */
-export declare function setMailer(transport: Transport, options?: MailerOptions): Mailer;
+/** A message recorded by the fake, and whether it was sent now or queued. */
+export interface RecordedMail {
+    message: Message;
+    queued: boolean;
+}
+/**
+ * A `Mailer` that records instead of delivering, with assertions — what
+ * `fakeMail()` installs so tests never talk to a provider.
+ */
+export declare class FakeMailer extends Mailer {
+    readonly mails: RecordedMail[];
+    constructor(name?: string, options?: MailerOptions);
+    send(message: Message): Promise<Message>;
+    sendLater(message: Message): Promise<Message>;
+    /** Everything sent immediately. */
+    sent(): Message[];
+    /** Everything queued with `sendLater()`. */
+    queued(): Message[];
+    assertSent(where?: (message: Message) => boolean): void;
+    assertNotSent(where?: (message: Message) => boolean): void;
+    assertSentCount(expected: number): void;
+    assertQueued(where?: (message: Message) => boolean): void;
+    assertNotQueued(where?: (message: Message) => boolean): void;
+    assertQueuedCount(expected: number): void;
+    /** Nothing sent and nothing queued. */
+    assertNothingSent(): void;
+    private summary;
+}
+/** Register a mailer, optionally under a name (default: `"default"`). */
+export declare function setMailer(transport: Transport, options?: MailerOptions, name?: string): Mailer;
+/** The default mailer, or a named one registered with `setMailer(…, …, name)`. */
+export declare function mailer(name?: string): Mailer;
 /** The default mailer instance. */
 export declare function getMailer(): Mailer;
-/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
-export declare function mail(): PendingMail;
+/** Start a message on a mailer: `mail().to(…).subject(…).send()`. */
+export declare function mail(name?: string): PendingMail;
+/** Send a class-based mail now. */
+export declare function send(email: BaseMail, name?: string): Promise<Message>;
+/** Queue a class-based mail. */
+export declare function sendLater(email: BaseMail, name?: string): Promise<Message>;
+/**
+ * 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 declare function fakeMail(name?: string): FakeMailer;
+/** Restore the real mailer after `fakeMail()`. With no name, restores them all. */
+export declare function restoreMail(name?: string): void;