imapflow 2.3.0 → 2.4.0

package/dist/cjs/imap-flow.js

@@ -85,6 +85,10 @@ const RAW_SENSITIVE_COMMANDS = new Set(['LOGIN', 'AUTHENTICATE']);
 // Stand-in payload for a withheld raw client frame. Fixed width, so the entry says nothing
 // about the length of what it replaced.
 const RAW_HIDDEN_PLACEHOLDER = Buffer.from('(* value hidden *)\r\n').toString('base64');
+// From this size up, a Buffer written as the last part of a command gets its CRLF as a socket
+// write of its own instead of being copied to append it (see write())
+const SEPARATE_LINE_BREAK_SIZE = 64 * 1024;
+const CRLF = Buffer.from('\r\n');
 // Servers, matched by the name in their ID response, that advertise IMAP4rev2 next to
 // IMAP4rev1 and accept ENABLE IMAP4rev2, but misbehave once it is enabled. ENABLE cannot
 // be undone (RFC 5161), so these are kept in IMAP4rev1 mode from the start. Strato's
@@ -385,43 +389,47 @@ class ImapFlow extends node_events_1.EventEmitter {
         // commandParts holds the remaining parts (literal data, continuation); the CRLF
         // delimiter is only added when no more parts remain (the command is complete).
         let addLineBreak = !this.commandParts.length;
-        let data;
+        // What goes to the socket, one write per entry. A large Buffer (the data of a literal)
+        // gets its CRLF as a write of its own, as concatenating would copy all of it.
+        let frames;
         if (typeof chunk === 'string') {
             if (addLineBreak) {
                 chunk += '\r\n';
             }
-            data = Buffer.from(chunk, 'binary');
+            frames = [Buffer.from(chunk, 'binary')];
         }
         else if (Buffer.isBuffer(chunk)) {
-            if (addLineBreak) {
-                data = Buffer.concat([chunk, Buffer.from('\r\n')]);
+            if (!addLineBreak) {
+                frames = [chunk];
             }
             else {
-                data = chunk;
+                frames = chunk.length >= SEPARATE_LINE_BREAK_SIZE ? [chunk, CRLF] : [Buffer.concat([chunk, CRLF])];
             }
         }
         else {
             return false;
         }
-        if (this.logRaw) {
-            // Client frames of an authentication exchange carry credentials: the LOGIN
-            // arguments, and for AUTHENTICATE also the continuation writes (SASL PLAIN
-            // response, AUTH=LOGIN password, OAuth token payload) that bypass send(). The
-            // parsed command log masks these, so the raw log must withhold them too, but
-            // `data` still carries the placeholder rather than being dropped - the field is
-            // part of the documented log format and consumers decode it unconditionally.
-            this.log.trace({
-                src: 'c',
-                msg: 'write to socket',
-                data: this.rawSensitiveCommand ? RAW_HIDDEN_PLACEHOLDER : data.toString('base64'),
-                ...(this.rawSensitiveCommand ? { hidden: true } : {}),
-                compress: !!this._deflate,
-                secure: !!this.secureConnection,
-                cid: this.id
-            });
+        for (let data of frames) {
+            if (this.logRaw) {
+                // Client frames of an authentication exchange carry credentials: the LOGIN
+                // arguments, and for AUTHENTICATE also the continuation writes (SASL PLAIN
+                // response, AUTH=LOGIN password, OAuth token payload) that bypass send(). The
+                // parsed command log masks these, so the raw log must withhold them too, but
+                // `data` still carries the placeholder rather than being dropped - the field is
+                // part of the documented log format and consumers decode it unconditionally.
+                this.log.trace({
+                    src: 'c',
+                    msg: 'write to socket',
+                    data: this.rawSensitiveCommand ? RAW_HIDDEN_PLACEHOLDER : data.toString('base64'),
+                    ...(this.rawSensitiveCommand ? { hidden: true } : {}),
+                    compress: !!this._deflate,
+                    secure: !!this.secureConnection,
+                    cid: this.id
+                });
+            }
+            this.writeBytesCounter += data.length;
+            this.writeSocket.write(data);
         }
-        this.writeBytesCounter += data.length;
-        this.writeSocket.write(data);
     }
     /**
      * Returns byte counters for the current connection.
@@ -447,6 +455,9 @@ class ImapFlow extends node_events_1.EventEmitter {
     // and once as a string (for logging, with sensitive data masked).
     // When LITERAL- or LITERAL+ extensions are available, the compiler can use
     // non-synchronizing literals to avoid waiting for server "+" continuation.
+    // Async although nothing in it awaits: a failure inside it rejects one microtask later, so a
+    // close() in the same tick settles the command with NoConnection first (see
+    // test/unhandled-rejection-test.ts)
     /** @internal */
     async send(data) {
         if (this.state === this.states.LOGOUT) {
@@ -456,11 +467,11 @@ class ImapFlow extends node_events_1.EventEmitter {
             // the socket watchdog.
             throw this.createNoConnectionError(false, { rejectedFrom: 'sendAfterLogout', command: data.command });
         }
-        // Classify before the first await. Every frame of this command - the command line and
-        // any continuation write that follows it - belongs to it until the next send(), because
+        // Classify once per command. Every frame of this command - the command line and any
+        // continuation write that follows it - belongs to it until the next send(), because
         // trySend() keeps one command in flight at a time. Reading currentRequest inside write()
-        // instead would be racy: rejectCurrentRequest() can clear it while the two compiler
-        // awaits below are pending, and the credential frame would then be logged in the clear.
+        // instead would be racy: rejectCurrentRequest() can clear it before a continuation frame
+        // is written, and the credential frame would then be logged in the clear.
         // Uppercased because the wire protocol is case-insensitive and exec() passes the
         // caller's spelling through unchanged. The command list covers the mechanisms whose
         // secret arrives in a continuation frame, which carries no attributes of its own; the
@@ -471,7 +482,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // Compile with asArray=true: splits output into parts for literal handling.
         // First part is the command text up to the first literal, remaining parts
         // are stored in this.commandParts and sent after server "+" continuations.
-        let compiled = await (0, imap_handler_js_1.compiler)(data, {
+        let compiled = (0, imap_handler_js_1.compiler)(data, {
             asArray: true,
             // LITERAL- is part of base IMAP4rev2
             literalMinus: (0, tools_js_1.hasCapability)(this, 'LITERAL-') || this.capabilities.has('LITERAL+')
@@ -482,7 +493,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // Compile again for logging with isLogging=true: masks sensitive values
         // like passwords while producing a human-readable command string
         if (this.isLogLevelEnabled('debug')) {
-            let logCompiled = await (0, imap_handler_js_1.compiler)(data, {
+            let logCompiled = (0, imap_handler_js_1.compiler)(data, {
                 isLogging: true
             });
             this.log.debug({ src: 'c', msg: logCompiled.toString(), cid: this.id, comment: options.comment });
@@ -739,9 +750,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 // parser would keep waiting on its backpressure callback forever, which is a
                 // silent permanent hang. Fail closed instead.
                 keepReading = false;
-                let error = new Error('Failed to process server response');
-                error.code = 'ResponseProcessingFailed';
-                error._err = err;
+                let error = (0, errors_js_1.createImapError)('Failed to process server response', 'ResponseProcessingFailed', { _err: err });
                 this.log.error({ msg: 'Failed to process server response', err, cid: this.id });
                 this.rejectCurrentRequest(error);
                 this.failProtocol(error);
@@ -864,7 +873,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // skipped when the level is off.
         let logLevel = /^\d+$/.test(parsed.command || '') && parsed.attributes && parsed.attributes[0] && parsed.attributes[0].value === 'FETCH' ? 'trace' : 'debug';
         if (this.isLogLevelEnabled(logLevel)) {
-            let logCompiled = await (0, imap_handler_js_1.compiler)(parsed, {
+            let logCompiled = (0, imap_handler_js_1.compiler)(parsed, {
                 isLogging: true
             });
             this.log[logLevel]({ src: 's', msg: logCompiled.toString(), cid: this.id, nullBytesRemoved: parsed.nullBytesRemoved });
@@ -970,12 +979,12 @@ class ImapFlow extends node_events_1.EventEmitter {
                 // response ambiguous, so reject this request and fail the connection closed.
                 let request = this.requestTagMap.get(parsed.tag);
                 this.requestTagMap.delete(parsed.tag);
-                let err = new Error('Server sent a tagged response for a command that was not in flight');
-                err.code = 'UnexpectedTag';
-                err.details = {
-                    received: parsed.tag,
-                    expected: this.currentRequest ? this.currentRequest.tag : null
-                };
+                let err = (0, errors_js_1.createImapError)('Server sent a tagged response for a command that was not in flight', 'UnexpectedTag', {
+                    details: {
+                        received: parsed.tag,
+                        expected: this.currentRequest ? this.currentRequest.tag : null
+                    }
+                });
                 this.log.error({ msg: 'Protocol desynchronization', err, cid: this.id });
                 request.reject(err);
                 this.failProtocol(err);
@@ -1019,9 +1028,9 @@ class ImapFlow extends node_events_1.EventEmitter {
                 try {
                     err.executedCommand =
                         parsed.tag +
-                            (await (0, imap_handler_js_1.compiler)(request, {
+                            (0, imap_handler_js_1.compiler)(request, {
                                 isLogging: true
-                            })).toString();
+                            }).toString();
                 }
                 catch {
                     // ignore
@@ -1074,9 +1083,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                 break;
             }
             default: {
-                let err = new Error('Invalid server response');
-                err.code = 'InvalidResponse';
-                err.response = parsed;
+                let err = (0, errors_js_1.createImapError)('Invalid server response', 'InvalidResponse', { response: parsed });
                 request.reject(err);
                 break;
             }
@@ -1177,11 +1184,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         this._socketTimeout =
             this._socketTimeout ||
                 (() => {
-                    const timeoutError = () => {
-                        const err = new Error('Socket timeout');
-                        err.code = 'ETIMEOUT';
-                        return err;
-                    };
+                    const timeoutError = () => (0, errors_js_1.createImapError)('Socket timeout', 'ETIMEOUT');
                     if (!this.usable || !this.socket || this.socket.destroyed) {
                         this.emitError(timeoutError());
                         return;
@@ -1365,7 +1368,10 @@ class ImapFlow extends node_events_1.EventEmitter {
         // to call deflate.flush() after each IMAP command to push all pending
         // compressed bytes to the server immediately (IMAP is request-response).
         const writeSocket = new node_stream_1.PassThrough({
-            highWaterMark: 64 * 1024 // 64KB buffer limit to prevent excessive memory usage
+            highWaterMark: 64 * 1024, // 64KB buffer limit to prevent excessive memory usage
+            // read() hands out each written chunk as is: in byte mode it joins whatever is
+            // queued into a new Buffer, which copies every large literal once more
+            readableObjectMode: true
         });
         this.writeSocket = writeSocket;
         /* c8 ignore start */ // destroySoon override is never invoked by ImapFlow (close() calls destroy()); kept for stream API completeness
@@ -1493,9 +1499,7 @@ class ImapFlow extends node_events_1.EventEmitter {
         // socket; injection that still races in afterwards corrupts the TLS handshake and
         // is rejected there instead (with a generic TLS error rather than STARTTLS_INJECTION).
         const failSTARTTLSInjection = () => {
-            let err = new Error('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack');
-            err.code = 'STARTTLS_INJECTION';
-            err.tlsFailed = true;
+            let err = (0, errors_js_1.createImapError)('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack', 'STARTTLS_INJECTION', { tlsFailed: true });
             this.closeAfter();
             return err;
         };
@@ -1578,8 +1582,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             socketPlain.on('error', settle);
             /* c8 ignore start */ // UPGRADE_TIMEOUT is 10s; firing it deterministically would make the test suite hang
             this.upgradeTimeout = setTimeout(() => {
-                let err = new Error('Failed to upgrade connection in required time');
-                err.code = 'UPGRADE_TIMEOUT';
+                let err = (0, errors_js_1.createImapError)('Failed to upgrade connection in required time', 'UPGRADE_TIMEOUT');
                 settle(err);
             }, UPGRADE_TIMEOUT);
             /* c8 ignore stop */
@@ -2083,9 +2086,7 @@ class ImapFlow extends node_events_1.EventEmitter {
     async connect() {
         if (this._connectCalled) {
             // Prevent re-using ImapFlow instances by allowing to call connect just once.
-            let err = new Error('Can not re-use ImapFlow instance');
-            err.code = 'InstanceReused';
-            throw err;
+            throw (0, errors_js_1.createImapError)('Can not re-use ImapFlow instance', 'InstanceReused');
         }
         this._connectCalled = true;
         let closedError = () => this.createNoConnectionError(this.byeReason, { rejectedFrom: 'connect' });
@@ -2173,14 +2174,14 @@ class ImapFlow extends node_events_1.EventEmitter {
                     (0, proxy_connection_js_1.detachEarlyErrorHandler)(socket);
                     this.configureSocket(this.socket);
                     this.greetingTimeout = setTimeout(() => {
-                        let err = new Error(
+                        let err = (0, errors_js_1.createImapError)(
                         /* c8 ignore next */ // the greeting-timeout test uses a plaintext socket; the secure-socket branch of this hint is not separately exercised
-                        `Failed to receive greeting from server in required time${!this.secureConnection ? '. Maybe should use TLS?' : ''}`);
-                        err.code = 'GREETING_TIMEOUT';
-                        err.details = {
-                            /* c8 ignore next */ // firing the timeout with the default (large) value would hang the suite, so only the explicit-option path is tested
-                            greetingTimeout: this.options.greetingTimeout || GREETING_TIMEOUT
-                        };
+                        `Failed to receive greeting from server in required time${!this.secureConnection ? '. Maybe should use TLS?' : ''}`, 'GREETING_TIMEOUT', {
+                            details: {
+                                /* c8 ignore next */ // firing the timeout with the default (large) value would hang the suite, so only the explicit-option path is tested
+                                greetingTimeout: this.options.greetingTimeout || GREETING_TIMEOUT
+                            }
+                        });
                         this.log.error({ err, cid: this.id });
                         this.closeAfter();
                         reject(err);
@@ -2404,9 +2405,9 @@ class ImapFlow extends node_events_1.EventEmitter {
             let reject = this.initialReject;
             this.initialResolve = false;
             this.initialReject = false;
-            let err = new Error('Unexpected close');
+            let err = (0, errors_js_1.createImapError)('Unexpected close', 
             /* c8 ignore next */ // closing a pending connect over an already-secure socket (the TLS branch) is not separately exercised
-            err.code = `ClosedAfterConnect${this.secureConnection ? 'TLS' : 'Text'}`;
+            this.secureConnection ? 'ClosedAfterConnectTLS' : 'ClosedAfterConnectText');
             // Surface the server's BYE reason (e.g. "Too many connections") when the
             // connection was closed by an untagged BYE, so the caller sees why.
             if (this.byeReason) {
@@ -2917,7 +2918,7 @@ class ImapFlow extends node_events_1.EventEmitter {
      * Appends a new message to a mailbox
      *
      * @param path Mailbox path to upload the message to (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
-     * @param content RFC822 formatted email message
+     * @param content RFC822 formatted email message, as a Buffer, Uint8Array or string
      * @param flags an array of flags to be set for the uploaded message
      * @param idate internal date to be set for the message
      * @returns info about uploaded message
@@ -3219,7 +3220,8 @@ class ImapFlow extends node_events_1.EventEmitter {
      * // download body part nr '1.2' from latest message
      * let download = await client.download('*', '1.2');
      * if (download.content) {
-     *     download.content.pipe(fs.createWriteStream(download.meta.filename));
+     *     // pipeline() rejects when the download fails, a plain .pipe() would not report it
+     *     await stream.promises.pipeline(download.content, fs.createWriteStream(download.meta.filename));
      * }
      */
     async download(range, part, options) {
@@ -3556,9 +3558,7 @@ class ImapFlow extends node_events_1.EventEmitter {
                     const idx = this.locks.indexOf(lockEntry);
                     if (idx !== -1) {
                         this.locks.splice(idx, 1);
-                        let err = new Error('Timed out waiting for mailbox lock');
-                        err.code = 'LockTimeout';
-                        err.lockId = lockEntry.lockId;
+                        let err = (0, errors_js_1.createImapError)('Timed out waiting for mailbox lock', 'LockTimeout', { lockId: lockEntry.lockId });
                         reject(err);
                     }
                 }, Number(lockOptions.acquireTimeout));

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.3.0";
+export declare const version = "2.4.0";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.3.0";
+exports.version = "2.4.0";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/proxy-connection.js

@@ -10,6 +10,7 @@ const node_net_1 = __importDefault(require("node:net"));
 const node_tls_1 = __importDefault(require("node:tls"));
 const connection_deadline_js_1 = require("./connection-deadline.js");
 const tools_js_1 = require("./tools.js");
+const errors_js_1 = require("./errors.js");
 // Cap the CONNECT response buffered before the header terminator, so a proxy that never sends
 // \r\n\r\n cannot grow memory without bound.
 const MAX_RESPONSE_HEADER_BYTES = 64 * 1024;
@@ -33,11 +34,7 @@ const redactUrl = (proxyUrl) => {
     }
     return redacted.href;
 };
-const proxyError = (message, code) => {
-    let err = new Error(message);
-    err.code = code || 'ProxyError';
-    return err;
-};
+const proxyError = (message, code) => (0, errors_js_1.createImapError)(message, code || 'ProxyError');
 // URL userinfo is percent-encoded, so it has to be decoded before it can be used as credentials.
 // A password containing a bare '%' is not valid percent-encoding and makes decodeURIComponent
 // throw, so such values are used as they came in rather than failing the connection.

package/dist/cjs/search-compiler.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchCompiler = void 0;
 const tools_js_1 = require("./tools.js");
+const errors_js_1 = require("./errors.js");
 // Matches any character outside the ASCII range
 const UNICODE_PATTERN = /[^\x00-\x7F]/;
 /**
@@ -104,9 +105,7 @@ let processDateField = (attributes, term, value) => {
  * @param message - Error message
  */
 let fail = (code, message) => {
-    let error = new Error(message);
-    error.code = code;
-    throw error;
+    throw (0, errors_js_1.createImapError)(message, code);
 };
 /**
  * Checks whether any search value was compiled into a literal, which only

package/dist/cjs/tools.d.ts

@@ -1,6 +1,6 @@
 import type { Transform } from 'node:stream';
 import type { ImapFlow } from './imap-flow.js';
-import { type ConnectionErrorSite, type ImapFlowError } from './errors.js';
+import { ImapFlowErrorCode, type ConnectionErrorSite, type ImapFlowError } from './errors.js';
 import type { ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
 import type { FetchMessageObject, ListResponse, ListTreeResponse, MailboxObject, MessageEnvelopeObject, MessageStructureObject, ImapFlowEvents, StatusQuery } from './types.js';
 export { AuthenticationFailure } from './errors.js';
@@ -33,7 +33,7 @@ export type CharsetDecoder = Transform & {
  * @param meta - Fields to stamp on the error
  * @returns The stamped error
  */
-export declare function buildConnectionError(cid: string, code: string, message: string, meta?: ConnectionErrorSite | undefined): ImapFlowError;
+export declare function buildConnectionError(cid: string, code: ImapFlowErrorCode, message: string, meta?: ConnectionErrorSite | undefined): ImapFlowError;
 /**
  * Re-stamps an existing connection error for a different rejection site.
  *

package/dist/cjs/tools.js

@@ -146,13 +146,7 @@ const CONNECTION_ERROR_SITE_KEYS = ['rejectedFrom', 'command', 'path'];
  * @returns The stamped error
  */
 function buildConnectionError(cid, code, message, meta) {
-    const error = new Error(message);
-    error.code = code;
-    error.cid = cid;
-    if (meta) {
-        Object.assign(error, meta);
-    }
-    return error;
+    return (0, errors_js_1.createImapError)(message, code, { cid, ...meta });
 }
 /**
  * Re-stamps an existing connection error for a different rejection site.
@@ -174,6 +168,7 @@ function buildConnectionError(cid, code, message, meta) {
  * @returns A separate error describing the same failure at the new site
  */
 function restampConnectionError(err, meta) {
+    // the original code is carried over unchanged, whatever its origin
     let error = buildConnectionError(err.cid, err.code, err.message, err);
     for (let key of CONNECTION_ERROR_SITE_KEYS) {
         delete error[key];
@@ -527,12 +522,13 @@ function getTextValues(attributes) {
  * @param response - Parsed IMAP server response
  * @returns Compiled response text, or false if no response
  */
+// Async although nothing in it awaits any more: `imapflow/lib/tools` deep imports may chain on the promise
 async function getErrorText(response) {
     if (!response) {
         return false;
     }
     try {
-        return (await (0, imap_handler_js_1.compiler)(response)).toString();
+        return (0, imap_handler_js_1.compiler)(response).toString();
     }
     catch {
         // The wire encoder refuses values that cannot be expressed as a valid IMAP
@@ -541,7 +537,7 @@ async function getErrorText(response) {
         // tolerates stray bytes inside an OK/NO/BAD atom, and those bytes then have
         // no valid re-encoding. This text is diagnostic, so fall back to the logging
         // encoder rather than replacing the server's error with an encoding failure.
-        return (await (0, imap_handler_js_1.compiler)(response, { isLogging: true })).toString();
+        return (0, imap_handler_js_1.compiler)(response, { isLogging: true }).toString();
     }
 }
 /**
@@ -755,6 +751,7 @@ function mergeFetchRows(rows) {
  * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
+// Async although nothing in it awaits any more: `imapflow/lib/tools` deep imports may chain on the promise
 async function formatMessageResponse(untagged, mailbox, idHashAlgorithm, connection) {
     let map = {};
     // The sequence number indexes into mailbox state, so an unusable one is dropped rather
@@ -777,9 +774,9 @@ async function formatMessageResponse(untagged, mailbox, idHashAlgorithm, connect
         let attribute = attributes[i];
         if (i % 2 === 0) {
             origin = false;
-            key = (await (0, imap_handler_js_1.compiler)({
+            key = (0, imap_handler_js_1.compiler)({
                 attributes: [attribute]
-            }))
+            })
                 .toString()
                 .toLowerCase()
                 .replace(/<(\d+)(\.\d+)?>$/, (match, start) => {

package/dist/esm/commands/append.d.ts

@@ -19,4 +19,4 @@ export interface AppendResult extends AppendResponseObject {
  * @returns Append result with UID info if available, or undefined if preconditions not met
  * @throws {Error} If the APPEND command fails or message exceeds APPENDLIMIT
  */
-export default function append(connection: ImapFlow, destination: string | string[], content: Buffer | string, flags?: string | string[] | undefined, idate?: Date | string | false | undefined): Promise<AppendResult | undefined>;
+export default function append(connection: ImapFlow, destination: string | string[], content: Buffer | Uint8Array | string, flags?: string | string[] | undefined, idate?: Date | string | false | undefined): Promise<AppendResult | undefined>;

package/dist/esm/commands/append.js

@@ -1,4 +1,5 @@
 import { formatFlag, canUseFlag, formatDateTime, normalizePath, encodePath, comparePaths, parseBigIntValue, parseUintValue, MAX_UINT32_DIGITS, getSelectedMailbox, emitSafe, isAuthenticatedState, reportCommandError, logConnectionError } from '../tools.js';
+import { createImapError } from '../errors.js';
 /**
  * Appends a message to a mailbox.
  *
@@ -15,14 +16,24 @@ export default async function append(connection, destination, content, flags, id
         // nothing to do here
         return;
     }
+    // The literal size marker is announced from these bytes, so anything that is not
+    // bytes (a Readable, a plain object) is refused here instead of desyncing the session
+    let message;
     if (typeof content === 'string') {
-        content = Buffer.from(content);
+        message = Buffer.from(content);
+    }
+    else if (content instanceof Uint8Array) {
+        // a Buffer as is, any other Uint8Array as a view over the same memory, not a copy
+        message = Buffer.isBuffer(content) ? content : Buffer.from(content.buffer, content.byteOffset, content.byteLength);
+    }
+    else {
+        throw createImapError('Message content must be a Buffer, Uint8Array or string', 'InvalidMessageContent');
     }
     // APPENDLIMIT capability (RFC 7889): server may advertise the maximum message
     // size it accepts. Check before sending to avoid a wasted round-trip.
     if (connection.capabilities.has('APPENDLIMIT')) {
         let appendLimit = connection.capabilities.get('APPENDLIMIT');
-        if (typeof appendLimit === 'number' && appendLimit < content.length) {
+        if (typeof appendLimit === 'number' && appendLimit < message.length) {
             let err = new Error('Message content too big for APPENDLIMIT=' + appendLimit);
             err.serverResponseCode = 'APPENDLIMIT';
             throw err;
@@ -79,9 +90,9 @@ export default async function append(connection, destination, content, flags, id
     // Regular literals cannot contain NUL bytes per the IMAP grammar.
     let isLiteral8 = false;
     if (connection.capabilities.has('BINARY') && !connection.disableBinary) {
-        isLiteral8 = content.indexOf(Buffer.from([0])) >= 0;
+        isLiteral8 = message.indexOf(0) >= 0;
     }
-    attributes.push({ type: 'LITERAL', value: content, isLiteral8 });
+    attributes.push({ type: 'LITERAL', value: message, isLiteral8 });
     let map = { destination };
     if (connection.mailbox && connection.mailbox.path) {
         map.path = connection.mailbox.path;

package/dist/esm/commands/compress.js

@@ -1,3 +1,4 @@
+import { createImapError } from '../errors.js';
 /**
  * Requests DEFLATE compression from the server.
  *
@@ -33,8 +34,7 @@ export default async function compress(connection) {
     // back its unconsumed tail on unpipe so the transport can feed it into the
     // inflater - not something a command module can reach from here.
     if (response.hasTrailingData) {
-        let error = new Error('Server sent data between the COMPRESS response and the compression layer switch');
-        error.code = 'COMPRESS_TRAILING_DATA';
+        let error = createImapError('Server sent data between the COMPRESS response and the compression layer switch', 'COMPRESS_TRAILING_DATA');
         connection.log.error({ err: error, cid: connection.id });
         // Schedule the close before releasing parser backpressure, so the buffered
         // deflate-framed bytes cannot settle anything before teardown begins. This is

package/dist/esm/commands/idle.js

@@ -1,4 +1,5 @@
 import { guardedPromise, hasCapability, isServerRefusal, logConnectionError, restampConnectionError, unrefTimer, clearTimer, getSelectedMailbox } from '../tools.js';
+import { createImapError } from '../errors.js';
 const NOOP_INTERVAL = 2 * 60 * 1000;
 /**
  * Marks the connection as idling on behalf of one session and returns a release function.
@@ -189,9 +190,7 @@ async function pollOnce(connection, session) {
                 highestModseq: true
             });
             if (!status) {
-                let err = new Error('STATUS poll failed');
-                err.code = 'PollFailed';
-                throw err;
+                throw createImapError('STATUS poll failed', 'PollFailed');
             }
             break;
         }

package/dist/esm/commands/status.js

@@ -1,5 +1,6 @@
 import { encodePath, normalizePath, buildStatusQueryAttributes, isRev2Active, isAuthenticatedState, emitSafe, getSelectedMailbox, logConnectionError } from '../tools.js';
 import { parseStatusList } from './status-fields.js';
+import { createImapError } from '../errors.js';
 // STATUS fields that also refresh the live mailbox state when the queried mailbox is the
 // currently selected one. Keyed by the output property name parseStatusList() reports.
 const MAILBOX_UPDATERS = {
@@ -96,10 +97,7 @@ export default async function status(connection, path, query) {
                 return false;
             });
             if (folders && !folders.length) {
-                let error = new Error(`Mailbox doesn't exist: ${path}`);
-                error.code = 'NotFound';
-                error.response = err;
-                throw error;
+                throw createImapError(`Mailbox doesn't exist: ${path}`, 'NotFound', { response: err });
             }
         }
         connection.log.warn({ err, cid: connection.id });

package/dist/esm/connection-deadline.d.ts

@@ -1,4 +1,4 @@
-import type { ImapFlowError } from './errors.js';
+import { type ImapFlowError } from './errors.js';
 export declare const CONNECT_TIMEOUT: number;
 /**
  * One deadline for an entire connection attempt.

package/dist/esm/connection-deadline.js

@@ -1,4 +1,5 @@
 import { clearTimer } from './tools.js';
+import { createImapError } from './errors.js';
 // Default upper bound for establishing a usable transport, including DNS and proxy negotiation.
 export const CONNECT_TIMEOUT = 90 * 1000;
 /**
@@ -28,10 +29,7 @@ export class ConnectionDeadline {
      * @returns The shared `CONNECT_TIMEOUT` error.
      */
     error() {
-        let err = new Error('Failed to establish connection in required time');
-        err.code = 'CONNECT_TIMEOUT';
-        err.details = { connectionTimeout: this.timeout };
-        return err;
+        return createImapError('Failed to establish connection in required time', 'CONNECT_TIMEOUT', { details: { connectionTimeout: this.timeout } });
     }
     /**
      * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one