@bobfrankston/mailx-store 0.1.21 → 0.1.22

package/index.d.ts

@@ -4,4 +4,5 @@
  */
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
+export { parseSerial } from "./parse-serial.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -4,4 +4,5 @@
  */
 export { MailxDB } from "./db.js";
 export { FileMessageStore } from "./file-store.js";
+export { parseSerial } from "./parse-serial.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,7 +10,8 @@
   "license": "ISC",
   "dependencies": {
     "@bobfrankston/mailx-types": "^0.1.11",
-    "@bobfrankston/mailx-settings": "^0.1.16"
+    "@bobfrankston/mailx-settings": "^0.1.16",
+    "mailparser": "^3.7.2"
   },
   "repository": {
     "type": "git",
@@ -21,12 +22,14 @@
   },
   ".dependencies": {
     "@bobfrankston/mailx-types": "file:../mailx-types",
-    "@bobfrankston/mailx-settings": "file:../mailx-settings"
+    "@bobfrankston/mailx-settings": "file:../mailx-settings",
+    "mailparser": "^3.7.2"
   },
   ".transformedSnapshot": {
     "dependencies": {
       "@bobfrankston/mailx-types": "^0.1.11",
-      "@bobfrankston/mailx-settings": "^0.1.16"
+      "@bobfrankston/mailx-settings": "^0.1.16",
+      "mailparser": "^3.7.2"
     }
   }
 }

package/parse-serial.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-wide serialized simpleParser.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { type ParsedMail, type Source } from "mailparser";
+/** Serialized wrapper around `mailparser.simpleParser`. Drop-in replacement —
+ *  same signature, same return value. */
+export declare function parseSerial(source: Source): Promise<ParsedMail>;
+//# sourceMappingURL=parse-serial.d.ts.map

package/parse-serial.js

@@ -0,0 +1,38 @@
+/**
+ * Process-wide serialized simpleParser.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { simpleParser } from "mailparser";
+let _chain = Promise.resolve();
+/** Serialized wrapper around `mailparser.simpleParser`. Drop-in replacement —
+ *  same signature, same return value. */
+export async function parseSerial(source) {
+    const queued = _chain.then(() => simpleParser(source));
+    _chain = queued.catch(() => undefined);
+    return queued;
+}
+//# sourceMappingURL=parse-serial.js.map