@bobfrankston/rmfmail 1.0.708 → 1.1.3

package/packages/mailx-bus/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/packages/mailx-bus/index.ts

@@ -0,0 +1,275 @@
+/**
+ * @bobfrankston/mailx-bus
+ *
+ * Typed message bus that connects mailx's factors. Each factor (DB, sync,
+ * UI, compose, calendar, …) is a peer that publishes/subscribes to events
+ * and serves/calls request-reply methods over the same bus.
+ *
+ * **Why this exists.** mailx historically had one monolithic service on one
+ * Node event loop: UI reads, IMAP sync, body parsing, OAuth refresh, prefetch,
+ * calendar polling — all on the same thread. A 14-minute synchronous freeze
+ * in any one path froze every other path. There was no separation between
+ * "answer a click" and "wait for Dovecot." The bus is the mechanism that
+ * makes those independent: a factor freezing is local; other factors keep
+ * answering.
+ *
+ * **Shape.** A bus exposes two primitives:
+ *   - `publish(topic, payload)` / `subscribe(topic, handler)` — fire-and-
+ *     forget events. Many subscribers per topic.
+ *   - `request(method, args) → Promise<result>` / `register(method, handler)`
+ *     — RPC. One handler per method. Caller awaits the reply.
+ *
+ * No method-name dispatch on a god object. Each factor declares the topics
+ * and methods it owns. Other factors hold a reference to the bus, not to
+ * each other.
+ *
+ * **Two transports, one interface.**
+ *   - `InProcessBus`: in-memory Map of handlers. Used in tests, in Android
+ *     (single-threaded JS), and for the same-thread half of a bridge.
+ *   - `WorkerBus`: connects to a peer via `worker_threads.MessagePort` (Node)
+ *     or `MessagePort` (browser). Uses `postMessage`, with structured
+ *     clone, so the two sides can live in different threads.
+ *
+ * Both implement `Bus`. Callers write against `Bus`. Where the peer lives is
+ * a deploy decision, not an API decision.
+ *
+ * **Buffer/Uint8Array note (Node).** `worker_threads.postMessage` clones a
+ * Node `Buffer` as a plain `Uint8Array`. Callers passing binary data through
+ * the bus across a worker boundary must accept that the receiving side sees
+ * `Uint8Array` — they should re-wrap with `Buffer.from(u.buffer, u.byteOffset,
+ * u.byteLength)` before handing the value to APIs that test
+ * `Buffer.isBuffer(x)`. The bus does not do this transparently; it is a
+ * transport concern that varies by what the payload actually is.
+ *
+ * **Errors.** A handler that throws is converted to a rejection on the
+ * caller's `request()` promise. The error's `message` survives the
+ * structured-clone barrier; the stack trace does not (Node strips it).
+ *
+ * **Lifecycle.** Subscribers receive a `dispose()` function from `subscribe`.
+ * Registered methods receive one from `register`. Dispose unhooks. A bus
+ * itself has no global teardown — closing the underlying port (when using
+ * `WorkerBus`) is the caller's responsibility.
+ */
+
+/** Method handler — receives the request payload, returns the response. May
+ *  be async. A throw becomes a request() rejection on the caller. */
+export type MethodHandler<A = any, R = any> = (args: A) => R | Promise<R>;
+
+/** Topic handler — fire-and-forget; the return value is ignored. */
+export type TopicHandler<P = any> = (payload: P) => void;
+
+/** Unsubscribe / unregister token returned from `subscribe` / `register`. */
+export type Dispose = () => void;
+
+export interface Bus {
+    /** Fire an event. Returns synchronously; subscribers are invoked
+     *  asynchronously (next microtask) so a publisher doesn't observe its
+     *  own re-entry. */
+    publish<P = any>(topic: string, payload: P): void;
+    /** Listen to events on `topic`. Returns a dispose function. */
+    subscribe<P = any>(topic: string, handler: TopicHandler<P>): Dispose;
+    /** Call `method` on its registered handler. The result Promise resolves
+     *  with whatever the handler returned, or rejects with the error. */
+    request<A = any, R = any>(method: string, args: A): Promise<R>;
+    /** Register the handler for `method`. Only one handler per method —
+     *  registering twice throws on the second call. Returns a dispose
+     *  function that unregisters. */
+    register<A = any, R = any>(method: string, handler: MethodHandler<A, R>): Dispose;
+}
+
+// ── In-process implementation ─────────────────────────────────────────────
+
+/** Single-process bus. Both sides of every call share a JavaScript heap.
+ *  Used in tests, in Android (single-threaded JS), and on whichever side of
+ *  a worker boundary is the host.
+ *
+ *  publish() defers subscriber dispatch to the next microtask so a
+ *  publisher's stack doesn't deepen indefinitely if a handler republishes
+ *  on the same topic. */
+export class InProcessBus implements Bus {
+    private topics = new Map<string, Set<TopicHandler>>();
+    private methods = new Map<string, MethodHandler>();
+
+    publish<P>(topic: string, payload: P): void {
+        const handlers = this.topics.get(topic);
+        if (!handlers || handlers.size === 0) return;
+        // Snapshot so a subscriber that disposes itself during dispatch
+        // doesn't perturb iteration of the live set.
+        const snapshot = Array.from(handlers);
+        queueMicrotask(() => {
+            for (const h of snapshot) {
+                try { h(payload); } catch (e: any) { console.error(`[bus] subscriber for "${topic}" threw: ${e?.message || e}`); }
+            }
+        });
+    }
+
+    subscribe<P>(topic: string, handler: TopicHandler<P>): Dispose {
+        let set = this.topics.get(topic);
+        if (!set) { set = new Set(); this.topics.set(topic, set); }
+        set.add(handler as TopicHandler);
+        return () => { set!.delete(handler as TopicHandler); };
+    }
+
+    async request<A, R>(method: string, args: A): Promise<R> {
+        const handler = this.methods.get(method);
+        if (!handler) throw new Error(`bus: no handler registered for "${method}"`);
+        // Always async — a handler that throws synchronously would otherwise
+        // bypass the Promise rejection path. Wrap in Promise.resolve().
+        return Promise.resolve().then(() => handler(args)) as Promise<R>;
+    }
+
+    register<A, R>(method: string, handler: MethodHandler<A, R>): Dispose {
+        if (this.methods.has(method)) {
+            throw new Error(`bus: "${method}" is already registered`);
+        }
+        this.methods.set(method, handler as MethodHandler);
+        return () => { this.methods.delete(method); };
+    }
+}
+
+// ── Worker / MessagePort implementation ───────────────────────────────────
+
+/** Anything that quacks like a MessagePort — Node's `worker_threads.parentPort`
+ *  and `Worker` instances, browser's `MessagePort`, etc. */
+export interface MessagePortLike {
+    postMessage(value: any): void;
+    on?(event: "message", handler: (value: any) => void): void;       // Node
+    addEventListener?(event: "message", handler: (e: MessageEvent) => void): void;  // browser
+}
+
+interface WireMessage {
+    kind: "publish" | "request" | "reply" | "subscribe-add" | "subscribe-remove" | "register-add" | "register-remove";
+    topic?: string;
+    method?: string;
+    payload?: any;
+    args?: any;
+    result?: any;
+    error?: string;
+    /** Correlation id for request/reply. */
+    id?: number;
+}
+
+/** Cross-thread bus. Each side instantiates a `WorkerBus` over its end of a
+ *  `MessageChannel`. The two sides are mirror images: subscribing on side A
+ *  causes events published on side B to flow over the wire to A. Requests
+ *  initiated on side A are served by whoever registered the method on side B.
+ *
+ *  Topology assumed by this implementation: exactly two endpoints. Multi-
+ *  party busses (>2 peers) need a hub topology and aren't covered here. */
+export class WorkerBus implements Bus {
+    private port: MessagePortLike;
+    private localSubs = new Map<string, Set<TopicHandler>>();
+    /** Methods registered on THIS side. Requests arriving over the wire
+     *  for these methods are dispatched locally. */
+    private localMethods = new Map<string, MethodHandler>();
+    /** Pending requests we sent to the peer, awaiting reply. */
+    private pending = new Map<number, { resolve: (r: any) => void; reject: (e: any) => void }>();
+    private nextId = 1;
+
+    constructor(port: MessagePortLike) {
+        this.port = port;
+        const onMessage = (raw: any): void => {
+            const msg = (raw && typeof raw === "object" && "data" in raw) ? (raw as MessageEvent).data : raw;
+            this.handleIncoming(msg as WireMessage);
+        };
+        if (typeof port.on === "function") port.on("message", onMessage);
+        else if (typeof port.addEventListener === "function") port.addEventListener("message", onMessage);
+    }
+
+    publish<P>(topic: string, payload: P): void {
+        // Local subscribers fire immediately (same-side publish/subscribe is
+        // allowed). The peer receives a publish message and dispatches there.
+        const local = this.localSubs.get(topic);
+        if (local && local.size > 0) {
+            const snapshot = Array.from(local);
+            queueMicrotask(() => {
+                for (const h of snapshot) {
+                    try { h(payload); } catch (e: any) { console.error(`[bus] subscriber for "${topic}" threw: ${e?.message || e}`); }
+                }
+            });
+        }
+        this.port.postMessage({ kind: "publish", topic, payload } as WireMessage);
+    }
+
+    subscribe<P>(topic: string, handler: TopicHandler<P>): Dispose {
+        let set = this.localSubs.get(topic);
+        if (!set) { set = new Set(); this.localSubs.set(topic, set); }
+        set.add(handler as TopicHandler);
+        return () => { set!.delete(handler as TopicHandler); };
+    }
+
+    async request<A, R>(method: string, args: A): Promise<R> {
+        // Prefer local handler if one is registered on this side (allows a
+        // factor to bundle with the bus for in-process testing).
+        const local = this.localMethods.get(method);
+        if (local) return Promise.resolve().then(() => local(args)) as Promise<R>;
+        const id = this.nextId++;
+        return new Promise<R>((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.port.postMessage({ kind: "request", method, args, id } as WireMessage);
+        });
+    }
+
+    register<A, R>(method: string, handler: MethodHandler<A, R>): Dispose {
+        if (this.localMethods.has(method)) {
+            throw new Error(`bus: "${method}" is already registered`);
+        }
+        this.localMethods.set(method, handler as MethodHandler);
+        return () => { this.localMethods.delete(method); };
+    }
+
+    private handleIncoming(msg: WireMessage): void {
+        if (!msg || typeof msg !== "object") return;
+        switch (msg.kind) {
+            case "publish": {
+                if (typeof msg.topic !== "string") return;
+                const subs = this.localSubs.get(msg.topic);
+                if (!subs || subs.size === 0) return;
+                const snapshot = Array.from(subs);
+                queueMicrotask(() => {
+                    for (const h of snapshot) {
+                        try { h(msg.payload); } catch (e: any) { console.error(`[bus] subscriber for "${msg.topic}" threw: ${e?.message || e}`); }
+                    }
+                });
+                return;
+            }
+            case "request": {
+                if (typeof msg.method !== "string" || typeof msg.id !== "number") return;
+                const handler = this.localMethods.get(msg.method);
+                if (!handler) {
+                    this.port.postMessage({ kind: "reply", id: msg.id, error: `no handler registered for "${msg.method}"` } as WireMessage);
+                    return;
+                }
+                Promise.resolve()
+                    .then(() => handler(msg.args))
+                    .then(result => this.port.postMessage({ kind: "reply", id: msg.id, result } as WireMessage))
+                    .catch(e => this.port.postMessage({ kind: "reply", id: msg.id, error: e?.message || String(e) } as WireMessage));
+                return;
+            }
+            case "reply": {
+                if (typeof msg.id !== "number") return;
+                const entry = this.pending.get(msg.id);
+                if (!entry) return;
+                this.pending.delete(msg.id);
+                if (msg.error) entry.reject(new Error(msg.error));
+                else entry.resolve(msg.result);
+                return;
+            }
+            // subscribe-add/remove/register-add/remove are reserved for a
+            // future optimisation where the bus only forwards events the
+            // peer is interested in. Today every publish crosses the wire;
+            // subscribers filter locally. Cheap enough at our volumes.
+        }
+    }
+}
+
+// ── Store-event bus ───────────────────────────────────────────────────────
+//
+// Typed, batch-coalescing pub/sub specifically for mailx-store mutations.
+// Lives in this package (zero deps) so both `mailx-store` (desktop, Node +
+// better-sqlite3) and `mailx-store-web` (Android/browser, sql.js + IDB)
+// import the SAME bus. That is the load-bearing property for code sharing
+// across platforms — a Store event published in either implementation is
+// indistinguishable to subscribers.
+export { StoreBus, storeBus } from "./store-events.js";
+export type { StoreEvent, StoreEventKind, StoreEventHandler } from "./store-events.js";

package/packages/mailx-bus/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@bobfrankston/mailx-bus",
+  "version": "0.1.2",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "release": "npmglobalize"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BobFrankston/mailx-bus.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/mailx-bus/store-events.d.ts

@@ -0,0 +1,79 @@
+/**
+ * StoreBus — typed pub/sub for Store events.
+ *
+ * Postmessage-style: subscribers register a topic string + handler; publishers
+ * emit a {topic, kind, ...} object. The exact same shape works inside Node,
+ * across worker_threads (postMessage), and across the WebView⇄host boundary
+ * (also postMessage). That's the load-bearing property: one mental model from
+ * DB write to UI re-render, on any platform.
+ *
+ * Topics
+ * ──────
+ *   `message:<uuid>`   — a specific message changed (flags, body, removal)
+ *   `folder:<id>`      — anything inside folder <id> changed; the bus fans
+ *                        out per-message events to the parent folder topic
+ *                        automatically (see fanOutToFolder())
+ *   `account:<id>`     — account-scoped event (sync status, auth, quota)
+ *   `*`                — wildcard; receives every event. Use for the IPC
+ *                        forwarder that pushes to the WebView, and for
+ *                        diagnostics. Avoid in normal UI subscribers.
+ *
+ * Batching
+ * ────────
+ * Bulk writes (sync round inserts 200 envelopes) would emit 200 events. The
+ * `withBatch(fn)` wrapper buffers events fired during fn() and coalesces
+ * per-topic into one {kind:"batch", changedUuids, summary} event at the end.
+ * Subscribers either iterate `changedUuids` or treat batch as "rerender this
+ * topic." Nested withBatch() is supported; inner scopes just append to the
+ * outer's buffer.
+ */
+export type StoreEventKind = "messageInserted" | "messageUpdated" | "messageRemoved" | "messageMoved" | "flagsChanged" | "bodyAvailable" | "bodyFetchError" | "folderCountsChanged" | "draftSaved" | "draftSaveDeferred" | "batch";
+export interface StoreEvent {
+    topic: string;
+    kind: StoreEventKind;
+    accountId?: string;
+    folderId?: number;
+    targetFolderId?: number;
+    uid?: number;
+    msgUuid?: string;
+    flags?: string[];
+    error?: string;
+    /** Set on `batch` events. UUIDs of every message touched in the scope. */
+    changedUuids?: string[];
+    /** Set on `batch` events. */
+    summary?: {
+        inserted: number;
+        updated: number;
+        deleted: number;
+    };
+    /** Arbitrary additional payload for kind-specific data the typed fields
+     *  above don't cover (e.g. flag-set details, body path). Keep small. */
+    [extra: string]: unknown;
+}
+export type StoreEventHandler = (event: StoreEvent) => void;
+export declare class StoreBus {
+    private subscribers;
+    private batchDepth;
+    private buffer;
+    subscribe(topic: string, handler: StoreEventHandler): () => void;
+    /** Publish an event. If a folderId is set and the topic is a message
+     *  topic, the bus also publishes a copy to the parent folder topic so
+     *  list views (subscribed to folder:<id>) wake without subscribing to
+     *  every message individually. */
+    publish(event: StoreEvent): void;
+    /** Run `fn` with publishes buffered. On exit, coalesces per-topic and
+     *  delivers either the single event (when only one fired for that topic)
+     *  or a synthetic batch event summarizing the changes. */
+    withBatch<T>(fn: () => T): T;
+    private flush;
+    private deliver;
+    /** When a message-topic event fires and carries a folderId, generate
+     *  the parallel folder-topic event so folder subscribers don't have to
+     *  also subscribe to every message individually. Returns null when no
+     *  fan-out applies. */
+    private fanOutToFolder;
+}
+/** Singleton bus shared by every Store consumer in the process. Workers
+ *  get their own; the worker boundary serializes events via postMessage. */
+export declare const storeBus: StoreBus;
+//# sourceMappingURL=store-events.d.ts.map

package/packages/mailx-bus/store-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-events.d.ts","sourceRoot":"","sources":["store-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,cAAc,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,qBAAqB,GACrB,YAAY,GACZ,mBAAmB,GACnB,OAAO,CAAC;AAEd,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,6BAA6B;IAC7B,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE;4EACwE;IACxE,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAE5D,qBAAa,QAAQ;IACjB,OAAO,CAAC,WAAW,CAA6C;IAChE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAoB;IAElC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAgBhE;;;sCAGkC;IAClC,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAahC;;8DAE0D;IAC1D,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAU5B,OAAO,CAAC,KAAK;IAwBb,OAAO,CAAC,OAAO;IAWf;;;2BAGuB;IACvB,OAAO,CAAC,cAAc;CAMzB;AAED;4EAC4E;AAC5E,eAAO,MAAM,QAAQ,UAAiB,CAAC"}

package/packages/mailx-bus/store-events.js

@@ -0,0 +1,155 @@
+/**
+ * StoreBus — typed pub/sub for Store events.
+ *
+ * Postmessage-style: subscribers register a topic string + handler; publishers
+ * emit a {topic, kind, ...} object. The exact same shape works inside Node,
+ * across worker_threads (postMessage), and across the WebView⇄host boundary
+ * (also postMessage). That's the load-bearing property: one mental model from
+ * DB write to UI re-render, on any platform.
+ *
+ * Topics
+ * ──────
+ *   `message:<uuid>`   — a specific message changed (flags, body, removal)
+ *   `folder:<id>`      — anything inside folder <id> changed; the bus fans
+ *                        out per-message events to the parent folder topic
+ *                        automatically (see fanOutToFolder())
+ *   `account:<id>`     — account-scoped event (sync status, auth, quota)
+ *   `*`                — wildcard; receives every event. Use for the IPC
+ *                        forwarder that pushes to the WebView, and for
+ *                        diagnostics. Avoid in normal UI subscribers.
+ *
+ * Batching
+ * ────────
+ * Bulk writes (sync round inserts 200 envelopes) would emit 200 events. The
+ * `withBatch(fn)` wrapper buffers events fired during fn() and coalesces
+ * per-topic into one {kind:"batch", changedUuids, summary} event at the end.
+ * Subscribers either iterate `changedUuids` or treat batch as "rerender this
+ * topic." Nested withBatch() is supported; inner scopes just append to the
+ * outer's buffer.
+ */
+export class StoreBus {
+    subscribers = new Map();
+    batchDepth = 0;
+    buffer = [];
+    subscribe(topic, handler) {
+        let set = this.subscribers.get(topic);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(topic, set);
+        }
+        set.add(handler);
+        return () => {
+            const s = this.subscribers.get(topic);
+            if (s) {
+                s.delete(handler);
+                if (s.size === 0)
+                    this.subscribers.delete(topic);
+            }
+        };
+    }
+    /** Publish an event. If a folderId is set and the topic is a message
+     *  topic, the bus also publishes a copy to the parent folder topic so
+     *  list views (subscribed to folder:<id>) wake without subscribing to
+     *  every message individually. */
+    publish(event) {
+        if (this.batchDepth > 0) {
+            this.buffer.push(event);
+            // Folder fan-out also buffers; coalesces at flush time.
+            const fanned = this.fanOutToFolder(event);
+            if (fanned)
+                this.buffer.push(fanned);
+            return;
+        }
+        this.deliver(event);
+        const fanned = this.fanOutToFolder(event);
+        if (fanned)
+            this.deliver(fanned);
+    }
+    /** Run `fn` with publishes buffered. On exit, coalesces per-topic and
+     *  delivers either the single event (when only one fired for that topic)
+     *  or a synthetic batch event summarizing the changes. */
+    withBatch(fn) {
+        this.batchDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            this.batchDepth--;
+            if (this.batchDepth === 0)
+                this.flush();
+        }
+    }
+    flush() {
+        const buf = this.buffer;
+        this.buffer = [];
+        if (buf.length === 0)
+            return;
+        const byTopic = new Map();
+        for (const e of buf) {
+            let arr = byTopic.get(e.topic);
+            if (!arr) {
+                arr = [];
+                byTopic.set(e.topic, arr);
+            }
+            arr.push(e);
+        }
+        for (const [topic, events] of byTopic) {
+            if (events.length === 1) {
+                this.deliver(events[0]);
+                continue;
+            }
+            const summary = { inserted: 0, updated: 0, deleted: 0 };
+            const uuids = new Set();
+            for (const e of events) {
+                if (e.kind === "messageInserted")
+                    summary.inserted++;
+                else if (e.kind === "messageRemoved")
+                    summary.deleted++;
+                else
+                    summary.updated++;
+                if (e.msgUuid)
+                    uuids.add(e.msgUuid);
+            }
+            this.deliver({ topic, kind: "batch", changedUuids: [...uuids], summary });
+        }
+    }
+    deliver(event) {
+        const exact = this.subscribers.get(event.topic);
+        if (exact)
+            for (const h of exact) {
+                try {
+                    h(event);
+                }
+                catch (e) {
+                    console.error("[store-bus]", e);
+                }
+            }
+        const wild = this.subscribers.get("*");
+        if (wild)
+            for (const h of wild) {
+                try {
+                    h(event);
+                }
+                catch (e) {
+                    console.error("[store-bus]", e);
+                }
+            }
+    }
+    /** When a message-topic event fires and carries a folderId, generate
+     *  the parallel folder-topic event so folder subscribers don't have to
+     *  also subscribe to every message individually. Returns null when no
+     *  fan-out applies. */
+    fanOutToFolder(event) {
+        if (event.kind === "batch")
+            return null;
+        if (!event.topic.startsWith("message:"))
+            return null;
+        if (event.folderId == null)
+            return null;
+        return { ...event, topic: `folder:${event.folderId}` };
+    }
+}
+/** Singleton bus shared by every Store consumer in the process. Workers
+ *  get their own; the worker boundary serializes events via postMessage. */
+export const storeBus = new StoreBus();
+//# sourceMappingURL=store-events.js.map

package/packages/mailx-bus/store-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-events.js","sourceRoot":"","sources":["store-events.ts"],"names":[],"mappings":"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"}