@bobfrankston/mailx-store 0.1.24 → 0.1.26

package/bus.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=bus.d.ts.map

package/bus.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=bus.js.map

package/charset.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Charset normalization for incoming email bodies.
+ *
+ * Many senders (esp. PHPMailer-driven marketing) declare
+ * `charset=iso-8859-1` but emit UTF-8 bytes. simpleParser honors the
+ * declared charset and produces "â??" garbage for every non-ASCII
+ * codepoint (em-dash, smart quotes, …). When the raw body bytes are
+ * valid UTF-8, rewrite the charset header before parsing. We only
+ * override the obviously-wrong legacy declarations; explicit utf-8 /
+ * koi8 / etc. pass through.
+ */
+/** Returns either the original buffer (no change needed) or a copy with
+ *  the leading charset declaration rewritten to utf-8. */
+export declare function sniffAndFixCharset(raw: Buffer): Buffer;
+//# sourceMappingURL=charset.d.ts.map

package/charset.js

@@ -0,0 +1,61 @@
+/**
+ * Charset normalization for incoming email bodies.
+ *
+ * Many senders (esp. PHPMailer-driven marketing) declare
+ * `charset=iso-8859-1` but emit UTF-8 bytes. simpleParser honors the
+ * declared charset and produces "â??" garbage for every non-ASCII
+ * codepoint (em-dash, smart quotes, …). When the raw body bytes are
+ * valid UTF-8, rewrite the charset header before parsing. We only
+ * override the obviously-wrong legacy declarations; explicit utf-8 /
+ * koi8 / etc. pass through.
+ */
+/** Returns either the original buffer (no change needed) or a copy with
+ *  the leading charset declaration rewritten to utf-8. */
+export function sniffAndFixCharset(raw) {
+    const HEAD_LIMIT = 16384;
+    const head = raw.subarray(0, Math.min(HEAD_LIMIT, raw.length)).toString("latin1");
+    const re = /charset\s*=\s*"?(iso-8859-1|us-ascii|windows-1252|latin1)"?/gi;
+    if (!re.test(head))
+        return raw;
+    if (!isValidUtf8(raw))
+        return raw;
+    const fixed = head.replace(/charset\s*=\s*"?(iso-8859-1|us-ascii|windows-1252|latin1)"?/gi, "charset=utf-8");
+    return Buffer.concat([Buffer.from(fixed, "latin1"), raw.subarray(head.length)]);
+}
+/** Strict UTF-8 validity check: rejects overlong forms, invalid start
+ *  bytes, and dangling continuations. Used to confirm the body is really
+ *  UTF-8 before overriding a Latin-1 declaration. */
+function isValidUtf8(buf) {
+    let i = 0;
+    while (i < buf.length) {
+        const b = buf[i];
+        if (b < 0x80) {
+            i++;
+            continue;
+        }
+        let need;
+        if ((b & 0xE0) === 0xC0) {
+            if (b < 0xC2)
+                return false;
+            need = 1;
+        }
+        else if ((b & 0xF0) === 0xE0)
+            need = 2;
+        else if ((b & 0xF8) === 0xF0) {
+            if (b > 0xF4)
+                return false;
+            need = 3;
+        }
+        else
+            return false;
+        if (i + need >= buf.length)
+            return false;
+        for (let k = 1; k <= need; k++) {
+            if ((buf[i + k] & 0xC0) !== 0x80)
+                return false;
+        }
+        i += need + 1;
+    }
+    return true;
+}
+//# sourceMappingURL=charset.js.map

package/index.d.ts

@@ -4,5 +4,9 @@
  */
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
-export { parseSerial } from "./parse-serial.js";
+export { parseSerial, prewarmParseWorker } from "./parse-serial.js";
+export { Store } from "./store.js";
+export type { StoreMessage } from "./store.js";
+export { StoreBus, storeBus } from "@bobfrankston/mailx-bus";
+export type { StoreEvent, StoreEventKind, StoreEventHandler } from "@bobfrankston/mailx-bus";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -4,5 +4,12 @@
  */
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
-export { parseSerial } from "./parse-serial.js";
+export { parseSerial, prewarmParseWorker } from "./parse-serial.js";
+// Store — the nexus. Owns DB + .eml files + operations + bus.
+export { Store } from "./store.js";
+// Store-event bus lives in `@bobfrankston/mailx-bus` so the browser-side
+// store (mailx-store-web) and the desktop-side store (this package) share
+// the same bus. Re-exported here so existing callers don't have to learn
+// the new import path.
+export { StoreBus, storeBus } from "@bobfrankston/mailx-bus";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,8 +9,9 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.11",
-    "@bobfrankston/mailx-settings": "^0.1.16",
+    "@bobfrankston/mailx-types": "^0.1.13",
+    "@bobfrankston/mailx-settings": "^0.1.17",
+    "@bobfrankston/mailx-bus": "^0.1.2",
     "mailparser": "^3.7.2"
   },
   "repository": {
@@ -23,12 +24,14 @@
   ".dependencies": {
     "@bobfrankston/mailx-types": "file:../mailx-types",
     "@bobfrankston/mailx-settings": "file:../mailx-settings",
+    "@bobfrankston/mailx-bus": "file:../mailx-bus",
     "mailparser": "^3.7.2"
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/mailx-types": "^0.1.11",
-      "@bobfrankston/mailx-settings": "^0.1.16",
+      "@bobfrankston/mailx-types": "^0.1.13",
+      "@bobfrankston/mailx-settings": "^0.1.17",
+      "@bobfrankston/mailx-bus": "^0.1.2",
       "mailparser": "^3.7.2"
     }
   }

package/parse-serial.d.ts

@@ -1,34 +1,50 @@
 /**
- * Process-wide serialized simpleParser.
+ * Worker-thread-backed simpleParser dispatcher.
  *
  * mailparser's `simpleParser` is declared `async` but its work is CPU-bound
- * (Node Streams + libmime decoding). When N parses run concurrently on the
- * single-threaded event loop they share CPU and each finishes at roughly
- * N× wall-clock. Real evidence (2026-05-13): four near-concurrent parses
- * each reported `14691ms for 3 KB` — pure contention, not size.
+ * (Node Streams + libmime decoding). When it runs on the main event loop:
+ *   - The first parse after a fresh process takes 14-25 seconds (cold V8
+ *     JIT + libmime + iconv-lite + charset-table loading). See log
+ *     2026-05-14 01:11:44 — simpleParser 14524ms for 5 KB.
+ *   - Every parse, cold or warm, blocks the IPC stdin pump for its
+ *     duration. A 200 ms parse delays every queued IPC message by 200 ms.
  *
- * The downstream symptom is the IPC pipe: while the event loop is
- * saturated by interleaving parses, unrelated IPC operations (mark-as-spam,
- * move, delete) wait their turn and the WebView-side `mailxapi` shim
- * times out at 120s with a misleading "stayed in the list" alert.
+ * Moving the parse to a `worker_threads` Worker fixes both problems:
+ *   - The main event loop stays responsive — IPC, sync, timers all run
+ *     during the parse. Click-to-render latency is bounded by post-message
+ *     RTT (sub-ms) + parse time on the worker, but the rest of the app
+ *     stays alive.
+ *   - The worker absorbs cold-start once. Subsequent parses ride the
+ *     worker's warm JIT and run in their natural 50-500 ms budget.
  *
- * Serializing through a module-level promise chain bounds the damage with
- * minimal plumbing: a single parse runs at full CPU and finishes in its
- * natural ~50-500ms budget; the next parse starts when it's done. Each
- * UI click produces a clean preview latency instead of a 14-second stall.
+ * Priority queue: foreground (UI clicks) jumps over background (sync /
+ * prefetch) when more than one parse is pending. Each parse still runs
+ * sequentially on the worker — the single-worker design intentionally
+ * mirrors the prior in-process serialization to keep CPU bounded.
  *
- * Lives in mailx-store rather than mailx-service so both the UI-hot path
- * (mailx-service/local-store.ts) and the sync path (mailx-imap) can share
- * one queue — otherwise sync-time parses would still contend with UI
- * parses through the event loop, just not through this module's chain.
+ * Lazy spawn: the worker is created on first call. boot/setup code that
+ * runs no parses pays nothing.
+ *
+ * Worker lifecycle: the worker is process-singleton, never explicitly
+ * terminated. Node exits cleanly because the worker is `unref()`d so it
+ * doesn't keep the event loop alive.
  *
- * Future work: replace the in-process chain with a `node:worker_threads`
- * pool. The chain is the precursor that bounds the worst case while the
- * pool is built.
+ * Lives in mailx-store rather than mailx-service so both the UI-hot path
+ * (mailx-service/local-store.ts) and the sync path (mailx-imap) share one
+ * worker — otherwise each module would spawn its own (parallel workers
+ * would defeat the bound on CPU, and each pays its own cold start).
  */
-import { type ParsedMail, type Source } from "mailparser";
-/** Serialized wrapper around `mailparser.simpleParser`. `priority` defaults
- *  to "foreground" — only sync/background callers should pass "background"
- *  so user clicks aren't stuck behind a back-fill. */
+import type { ParsedMail, Source } from "mailparser";
+/** Spawn the parse worker early so its cold-start (mailparser module
+ *  loading, V8 JIT, libmime / iconv-lite tables — empirically 14-25 s)
+ *  runs in parallel with the rest of boot. Safe to call multiple times;
+ *  the worker is a process-singleton. Returns immediately; the actual
+ *  cold-start completes in the worker's internal self-warm. */
+export declare function prewarmParseWorker(): void;
+/** Serialized wrapper around `mailparser.simpleParser` running in a worker
+ *  thread. `priority` defaults to "foreground" — only sync/background
+ *  callers should pass "background" so user clicks aren't stuck behind a
+ *  back-fill. If the worker can't be spawned (rare), falls back to an
+ *  in-main-thread serial pump so the system still functions. */
 export declare function parseSerial(source: Source, priority?: "foreground" | "background"): Promise<ParsedMail>;
 //# sourceMappingURL=parse-serial.d.ts.map