@bobfrankston/iflow-direct 0.1.15 → 0.1.17

package/README.md

@@ -0,0 +1,117 @@
+# @bobfrankston/iflow-direct
+
+Transport-agnostic IMAP client. Zero Node.js deps — works in Node, Electron, and
+the browser (via a bridge transport). Caller supplies a `TransportFactory`, OAuth
+token provider (if needed), and drives the client.
+
+See [MIGRATION.md](./MIGRATION.md) for the split from legacy `@bobfrankston/iflow`
+and the desktop/browser architecture diagram.
+
+## Install
+
+```bash
+npm install @bobfrankston/iflow-direct
+# desktop TCP transport:
+npm install @bobfrankston/tcp-transport
+```
+
+## Quick start (desktop)
+
+```typescript
+import { NativeImapClient } from "@bobfrankston/iflow-direct";
+import { TcpTransport } from "@bobfrankston/tcp-transport";
+
+const client = new NativeImapClient(
+    { server: "imap.example.com", port: 993, username: "me", password: "..." },
+    () => new TcpTransport(),
+);
+await client.connect();
+await client.select("INBOX");
+const msgs = await client.fetchMessages("1:50", { source: false });
+await client.logout();
+```
+
+For the legacy API shape (`getFolderList`, etc.) use `CompatImapClient` from the
+same package.
+
+## Batch body retrieval
+
+Two APIs for pulling bodies across many UIDs in a single `UID FETCH` round trip,
+with per-message streaming as responses arrive (not buffered until the tagged OK).
+
+### `fetchMessagesStream(range, options, onMessage?)`
+
+Streaming variant of `fetchMessages`. `range` accepts any IMAP sequence set —
+single UID (`"42"`), range (`"100:200"`), comma list (`"1,5,10,42"`), or mixed
+(`"1:10,42,50:55"`). The server handles all forms.
+
+```typescript
+await client.select("INBOX");
+await client.fetchMessagesStream(
+    "1,5,10,42,100:150",
+    { source: true, headers: false },
+    (msg) => {
+        // Called once per message as soon as its FETCH response
+        // (literals included) is fully received. Tagged OK has not arrived yet.
+        console.log(msg.uid, msg.source.length);
+    },
+);
+```
+
+Returns the parsed messages at the tagged OK; if `onMessage` is omitted, behaves
+like `fetchMessages` (collect-all).
+
+### `fetchBodiesBatch(folderPath, uids, onBody)`
+
+Folder-scoped convenience. Selects the folder (skips if already selected), issues
+one `UID FETCH <comma-list> (UID FLAGS ENVELOPE RFC822.SIZE INTERNALDATE BODY.PEEK[])`,
+streams each `(uid, source)` through `onBody`, returns on tagged OK.
+
+```typescript
+await client.fetchBodiesBatch("INBOX", [1, 5, 10, 42], (uid, source) => {
+    store.saveBody(uid, source);
+});
+```
+
+Intended for prefetch pipelines — e.g. mailx-imap's body-prefetch path — that
+would otherwise issue one SELECT+FETCH per message.
+
+### Streaming guarantees
+
+- `onMessage` / `onBody` fires on the same event-loop turn that the server's
+  FETCH response (with any literal bodies) is fully parsed.
+- Ordering matches server response order. For a comma list, servers typically
+  return in the order requested, but RFC 3501 does not require it — treat order
+  as server-defined.
+- Callback exceptions are caught and logged (verbose mode) so one bad message
+  doesn't abort the batch. Throw only if you want that behavior and wrap your
+  own try/catch.
+- The tagged-OK promise still resolves with the full response list; callers
+  needing both streaming and a terminal "all done" signal should `await` the
+  returned promise.
+
+## Other APIs
+
+`NativeImapClient` exposes the usual IMAP surface: `select`, `examine`,
+`listFolders`, `getStatus`, `search`, `fetchMessage`, `fetchSinceUid`,
+`fetchByDate` (both with optional `onChunk` chunked callbacks), `addFlags`,
+`removeFlags`, `copyMessage`, `moveMessage`, `deleteMessage`, `expunge`,
+`appendMessage`, `startIdle`, `logout`. See `imap-native.ts` for signatures.
+
+IDLE auto-suspends when any other command is issued on the same connection and
+re-enters afterwards — safe to interleave commands with a long-running IDLE.
+
+## Configuration
+
+`ImapClientConfig` fields relevant to throughput/resilience:
+
+| Field | Default | Notes |
+|---|---|---|
+| `inactivityTimeout` | 60000 | ms with no data before connection is declared dead. Timer resets on every byte. Slow Dovecot often needs 180000+. |
+| `fetchChunkSize` | 25 | Initial chunk size for `fetchSinceUid`/`fetchByDate`. |
+| `fetchChunkSizeMax` | 500 | Ramps up 4× per chunk. Batch APIs above bypass chunking — caller decides. |
+| `verbose` | false | Log every command/response line + literal bookkeeping. |
+
+## Files
+
+See [MIGRATION.md § Files in iflow-direct](./MIGRATION.md#files-in-iflow-direct).

package/imap-compat.d.ts

@@ -38,6 +38,11 @@ export declare class CompatImapClient {
     fetchMessagesSinceUid(mailbox: string, sinceUid: number, options?: {
         source?: boolean;
     }): Promise<FetchedMessage[]>;
+    /** Batch-fetch bodies for many UIDs in one folder on one connection. Streams
+     *  each body through `onBody` as it arrives. No per-message round trips —
+     *  one SELECT, one UID FETCH, streaming response. Required by mailx-imap's
+     *  batch prefetch path. */
+    fetchBodiesBatch(mailbox: string, uids: number[], onBody: (uid: number, source: string) => void): Promise<void>;
     /** Fetch messages by date range. Optional onChunk callback for incremental processing. */
     fetchMessageByDate(mailbox: string, start: Date, end?: Date, options?: {
         source?: boolean;

package/imap-compat.js

@@ -93,6 +93,16 @@ export class CompatImapClient {
         await this.native.closeMailbox();
         return msgs.map(m => new FetchedMessage(m));
     }
+    /** Batch-fetch bodies for many UIDs in one folder on one connection. Streams
+     *  each body through `onBody` as it arrives. No per-message round trips —
+     *  one SELECT, one UID FETCH, streaming response. Required by mailx-imap's
+     *  batch prefetch path. */
+    async fetchBodiesBatch(mailbox, uids, onBody) {
+        if (uids.length === 0)
+            return;
+        await this.ensureConnected();
+        await this.native.fetchBodiesBatch(mailbox, uids, onBody);
+    }
     /** Fetch messages by date range. Optional onChunk callback for incremental processing. */
     async fetchMessageByDate(mailbox, start, end, options, onChunk) {
         await this.ensureConnected();

package/imap-native.d.ts

@@ -79,11 +79,31 @@ export declare class NativeImapClient {
     createMailbox(mailbox: string): Promise<void>;
     deleteMailbox(mailbox: string): Promise<void>;
     renameMailbox(from: string, to: string): Promise<void>;
-    /** Fetch messages by UID range */
+    /** Fetch messages by UID range. Range may be sequence set (e.g. "1:100"), comma list ("1,5,10"), or mix ("1:10,42,50:55"). */
     fetchMessages(range: string, options?: {
         source?: boolean;
         headers?: boolean;
     }): Promise<NativeFetchedMessage[]>;
+    /**
+     * Fetch messages by UID range/list, streaming each parsed message through `onMessage`
+     * as soon as its server response (including any literal bodies) is received, instead
+     * of buffering the entire batch until the tagged OK. Returns all parsed messages at end.
+     *
+     * Pass a comma list (`"1,5,10,42"`) or sequence set (`"100:200"`) — the server handles either.
+     */
+    fetchMessagesStream(range: string, options?: {
+        source?: boolean;
+        headers?: boolean;
+    }, onMessage?: (msg: NativeFetchedMessage) => void): Promise<NativeFetchedMessage[]>;
+    /**
+     * Folder-scoped batch body fetch. Selects `folderPath`, issues a single
+     * `UID FETCH <uids> (BODY.PEEK[] ...)`, streams each body through `onBody`
+     * as it arrives, and returns when the tagged OK is received.
+     *
+     * Eliminates per-message SELECT+FETCH round trips for callers like mailx-imap's
+     * prefetch path.
+     */
+    fetchBodiesBatch(folderPath: string, uids: number[], onBody: (uid: number, source: string) => void): Promise<void>;
     /** Fetch messages since a UID */
     fetchSinceUid(sinceUid: number, options?: {
         source?: boolean;

package/imap-native.js

@@ -281,16 +281,56 @@ export class NativeImapClient {
             throw new Error(`RENAME failed: ${tagged?.text || "unknown"}`);
     }
     // ── Message Operations ──
-    /** Fetch messages by UID range */
+    /** Fetch messages by UID range. Range may be sequence set (e.g. "1:100"), comma list ("1,5,10"), or mix ("1:10,42,50:55"). */
     async fetchMessages(range, options = {}) {
+        return this.fetchMessagesStream(range, options);
+    }
+    /**
+     * Fetch messages by UID range/list, streaming each parsed message through `onMessage`
+     * as soon as its server response (including any literal bodies) is received, instead
+     * of buffering the entire batch until the tagged OK. Returns all parsed messages at end.
+     *
+     * Pass a comma list (`"1,5,10,42"`) or sequence set (`"100:200"`) — the server handles either.
+     */
+    async fetchMessagesStream(range, options = {}, onMessage) {
         const items = ["UID", "FLAGS", "ENVELOPE", "RFC822.SIZE", "INTERNALDATE"];
         if (options.headers !== false)
             items.push("BODY.PEEK[HEADER]");
         if (options.source)
             items.push("BODY.PEEK[]");
         const tag = proto.nextTag();
-        const responses = await this.sendCommand(tag, proto.fetchCommand(tag, range, items));
-        return this.parseFetchResponses(responses);
+        const streamed = [];
+        const cb = onMessage
+            ? (resp) => {
+                if (resp.tag !== "*" || resp.type !== "FETCH")
+                    return;
+                const parsed = this.parseFetchResponses([resp]);
+                for (const msg of parsed) {
+                    streamed.push(msg);
+                    onMessage(msg);
+                }
+            }
+            : undefined;
+        const responses = await this.sendCommand(tag, proto.fetchCommand(tag, range, items), cb);
+        return onMessage ? streamed : this.parseFetchResponses(responses);
+    }
+    /**
+     * Folder-scoped batch body fetch. Selects `folderPath`, issues a single
+     * `UID FETCH <uids> (BODY.PEEK[] ...)`, streams each body through `onBody`
+     * as it arrives, and returns when the tagged OK is received.
+     *
+     * Eliminates per-message SELECT+FETCH round trips for callers like mailx-imap's
+     * prefetch path.
+     */
+    async fetchBodiesBatch(folderPath, uids, onBody) {
+        if (uids.length === 0)
+            return;
+        if (this.selectedMailbox !== folderPath)
+            await this.select(folderPath);
+        await this.fetchMessagesStream(uids.join(","), { source: true, headers: false }, (msg) => {
+            if (msg.uid && msg.source)
+                onBody(msg.uid, msg.source);
+        });
     }
     /** Fetch messages since a UID */
     async fetchSinceUid(sinceUid, options = {}, onChunk) {
@@ -527,7 +567,7 @@ export class NativeImapClient {
     fetchChunkSizeMax;
     /** Active command timer — reset by handleData on every data arrival */
     commandTimer = null;
-    sendCommand(tag, command) {
+    sendCommand(tag, command, onUntagged) {
         return new Promise((resolve, reject) => {
             if (this.verbose && !command.includes("LOGIN") && !command.includes("AUTHENTICATE")) {
                 console.log(`  [imap] > ${command.trimEnd()}`);
@@ -546,6 +586,7 @@ export class NativeImapClient {
                     clearTimeout(this.commandTimer); this.commandTimer = null; resolve(responses); },
                 reject: (err) => { if (this.commandTimer)
                     clearTimeout(this.commandTimer); this.commandTimer = null; reject(err); },
+                onUntagged,
             };
             this.transport.write(command).catch((err) => { if (this.commandTimer)
                 clearTimeout(this.commandTimer); this.commandTimer = null; reject(err); });
@@ -696,6 +737,15 @@ export class NativeImapClient {
             // Collect untagged responses for the pending command
             if (resp.tag === "*" && this.pendingCommand) {
                 this.pendingCommand.responses.push(resp);
+                if (this.pendingCommand.onUntagged) {
+                    try {
+                        this.pendingCommand.onUntagged(resp);
+                    }
+                    catch (err) {
+                        if (this.verbose)
+                            console.error(`  [imap] onUntagged callback threw: ${err.message}`);
+                    }
+                }
                 continue;
             }
             // Continuation response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/iflow-direct",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",
@@ -19,7 +19,7 @@
   "author": "Bob Frankston",
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/tcp-transport": "^0.1.0"
+    "@bobfrankston/tcp-transport": "^0.1.3"
   },
   "exports": {
     ".": {
@@ -47,7 +47,7 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/tcp-transport": "^0.1.0"
+      "@bobfrankston/tcp-transport": "^0.1.3"
     }
   }
 }