imapflow 1.2.8 → 1.2.10

package/.ncurc.js

@@ -1,4 +1,4 @@
 module.exports = {
     upgrade: true,
-    reject: ['jsdoc', 'grunt-eslint']
+    reject: ['grunt-eslint']
 };

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.2.8"
+    ".": "1.2.10"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.2.10](https://github.com/postalsys/imapflow/compare/v1.2.9...v1.2.10) (2026-02-19)
+
+
+### Bug Fixes
+
+* add null guards in compress() to prevent crash on TLS teardown ([84cd3ff](https://github.com/postalsys/imapflow/commit/84cd3ff8815d8ba37a37c1e7a09c244e80b61948))
+
+## [1.2.9](https://github.com/postalsys/imapflow/compare/v1.2.8...v1.2.9) (2026-02-06)
+
+
+### Bug Fixes
+
+* trigger build ([fd7a4c2](https://github.com/postalsys/imapflow/commit/fd7a4c2012d0b7742c45a2aced2d05da8401aa9a))
+
 ## [1.2.8](https://github.com/postalsys/imapflow/compare/v1.2.7...v1.2.8) (2026-01-28)
 
 

package/README.md

@@ -1,109 +1,87 @@
 # ImapFlow
 
-ImapFlow is a modern and easy-to-use IMAP client library for Node.js.
+Modern and easy-to-use IMAP client library for Node.js.
 
-> [!NOTE]
-> Managing an IMAP connection is cool, but if you are only looking for an easy way to integrate email accounts, then ImapFlow was built for [EmailEngine Email API](https://emailengine.app/). It's a self-hosted software that converts all IMAP accounts to easy-to-use REST interfaces.
-
-The focus for ImapFlow is to provide easy to use API over IMAP. Using ImapFlow does not expect knowledge about specific IMAP details. A general understanding is good enough.
-
-IMAP extensions are handled in the background, so, for example, you can always request `labels` value from a {@link FetchQueryObject|fetch()} call, but if the IMAP server does not support `X-GM-EXT-1` extension, then `labels` value is not included in the response.
+[![npm](https://img.shields.io/npm/v/imapflow)](https://www.npmjs.com/package/imapflow)
+[![license](https://img.shields.io/npm/l/imapflow)](https://github.com/postalsys/imapflow/blob/master/LICENSE)
 
-## Source
+ImapFlow provides a clean, promise-based API for working with IMAP, so you don't need in-depth knowledge of the protocol. IMAP extensions are detected and handled automatically. You write the same code regardless of server capabilities, and ImapFlow adapts behind the scenes.
 
-Source code is available from [Github](https://github.com/postalsys/imapflow).
+## Features
 
-## Usage
+- **Async/await API** - all methods return Promises
+- **Automatic IMAP extension handling** - CONDSTORE, QRESYNC, IDLE, COMPRESS, and [more](https://imapflow.com/docs/)
+- **Message streaming** - async iterators for efficient processing
+- **Mailbox locking** - built-in locking mechanism for safe concurrent access
+- **TypeScript support** - type definitions included
+- **Proxy support** - SOCKS and HTTP CONNECT proxies
+- **Gmail support** - labels, raw search via X-GM-EXT-1
 
-First install the module from npm:
+## Installation
 
-```
+```bash
 npm install imapflow
 ```
 
-next import the ImapFlow class into your script:
+## Quick Example
 
 ```js
 const { ImapFlow } = require('imapflow');
-```
-
-### Promises
 
-All ImapFlow methods use Promises, so you need to wait using `await` or wait for the `then()` method to fire until you get the response.
-
-```js
-const { ImapFlow } = require('imapflow');
 const client = new ImapFlow({
-    host: 'ethereal.email',
+    host: 'imap.example.com',
     port: 993,
     secure: true,
     auth: {
-        user: 'garland.mcclure71@ethereal.email',
-        pass: 'mW6e4wWWnEd3H4hT5B'
+        user: 'user@example.com',
+        pass: 'password'
     }
 });
 
 const main = async () => {
-    // Wait until client connects and authorizes
     await client.connect();
 
-    // Select and lock a mailbox. Throws if mailbox does not exist
     let lock = await client.getMailboxLock('INBOX');
     try {
-        // fetch latest message source
-        // client.mailbox includes information about currently selected mailbox
-        // "exists" value is also the largest sequence number available in the mailbox
+        // fetch latest message
         let message = await client.fetchOne(client.mailbox.exists, { source: true });
         console.log(message.source.toString());
 
         // list subjects for all messages
-        // uid value is always included in FETCH response, envelope strings are in unicode.
         for await (let message of client.fetch('1:*', { envelope: true })) {
             console.log(`${message.uid}: ${message.envelope.subject}`);
         }
     } finally {
-        // Make sure lock is released, otherwise next `getMailboxLock()` never returns
+        // always release the lock
         lock.release();
     }
 
-    // log out and close connection
     await client.logout();
 };
 
-main().catch(err => console.error(err));
+main().catch(console.error);
 ```
 
-### Admin Impersonation / Delegation (SASL PLAIN with authzid)
+See the [Quick Start guide](https://imapflow.com/docs/getting-started/quick-start) for more examples, including Gmail, Outlook, and Yahoo configuration.
 
-ImapFlow supports admin impersonation for mail systems like Zimbra that allow administrators to access user mailboxes. This is done using the SASL PLAIN mechanism with an authorization identity (`authzid`).
-
-```js
-const { ImapFlow } = require('imapflow');
-const client = new ImapFlow({
-    host: 'mail.example.com',
-    port: 993,
-    secure: true,
-    auth: {
-        user: 'admin@example.com', // Admin credentials (authentication identity)
-        pass: 'adminpassword',
-        authzid: 'user@example.com', // User to impersonate (authorization identity)
-        loginMethod: 'AUTH=PLAIN' // Must use PLAIN mechanism for authzid
-    }
-});
+## Documentation
 
-// Connection will authenticate as admin but authorize as the specified user
-await client.connect();
-// Now operating on user@example.com's mailbox as admin
-```
+Full documentation is available at **[imapflow.com](https://imapflow.com/docs/)**.
 
-**Note:** The `authzid` parameter only works with the `AUTH=PLAIN` mechanism. The server must support admin delegation/impersonation for this to work.
+- [Installation](https://imapflow.com/docs/getting-started/installation) - requirements and setup
+- [Quick Start](https://imapflow.com/docs/getting-started/quick-start) - your first ImapFlow application
+- [Basic Usage](https://imapflow.com/docs/guides/basic-usage) - core concepts and patterns
+- [Configuration](https://imapflow.com/docs/guides/configuration) - connection options and settings
+- [Fetching Messages](https://imapflow.com/docs/guides/fetching-messages) - reading email data
+- [Searching](https://imapflow.com/docs/guides/searching) - finding messages with search queries
+- [Mailbox Management](https://imapflow.com/docs/guides/mailbox-management) - creating, renaming, and deleting mailboxes
+- [API Reference](https://imapflow.com/docs/api/imapflow-client) - complete method and event documentation
 
-## Documentation
-
-[API reference](https://imapflow.com/module-imapflow-ImapFlow.html).
+> [!NOTE]
+> If you are looking for a complete email integration solution, ImapFlow was built for [EmailEngine](https://emailengine.app/), a self-hosted email gateway that provides REST API access to IMAP and SMTP accounts.
 
 ## License
 
-© 2020-2024 Postal Systems OÜ
+Copyright (c) 2020-2025 Postal Systems OU
 
-Licensed under **MIT-license**
+Licensed under the MIT license.

package/eslint.config.js

@@ -1,38 +1,40 @@
 'use strict';
 
-const { FlatCompat } = require('@eslint/eslintrc');
 const js = require('@eslint/js');
-
-const compat = new FlatCompat({
-    baseDirectory: __dirname,
-    recommendedConfig: js.configs.recommended
-});
+const globals = require('globals');
+const prettierConfig = require('eslint-config-prettier/flat');
+const nodemailerConfig = require('eslint-config-nodemailer');
 
 module.exports = [
     {
         ignores: ['node_modules/**', 'examples/**', 'docs/**']
     },
-    ...compat.extends('nodemailer', 'prettier'),
+    js.configs.recommended,
     {
         languageOptions: {
-            ecmaVersion: 2020,
+            ecmaVersion: 2022,
             sourceType: 'script',
-            globals: {
-                BigInt: 'readonly'
-            },
-            parser: require('@babel/eslint-parser'),
             parserOptions: {
-                requireConfigFile: false
+                ecmaFeatures: {
+                    globalReturn: true
+                }
+            },
+            globals: {
+                ...globals.node,
+                ...globals.es2021,
+                it: 'readonly',
+                describe: 'readonly',
+                beforeEach: 'readonly',
+                afterEach: 'readonly'
             }
         },
-        plugins: {
-            '@babel': require('@babel/eslint-plugin')
-        },
         rules: {
+            ...nodemailerConfig.rules,
             'no-await-in-loop': 0,
             'require-atomic-updates': 0
         }
     },
+    prettierConfig,
     {
         files: ['eslint.config.js', '.prettierrc.js', '.ncurc.js'],
         rules: {

package/lib/charsets.js

@@ -1,5 +1,8 @@
 'use strict';
 
+// Subset of the IANA Character Sets registry (https://www.iana.org/assignments/character-sets/).
+// Used to validate and resolve charset names found in MIME Content-Type parameters.
+// This list covers the most commonly encountered charsets in email messages.
 const CHARACTER_SETS = [
     'US-ASCII',
     'ISO-8859-1',
@@ -262,6 +265,14 @@ const CHARACTER_SETS = [
 
 const CHARSET_MAP = new Map();
 
+// Build a lookup map with normalized keys for fuzzy charset resolution.
+// Normalization strategy:
+// 1. Strip all underscores, hyphens, and spaces, then lowercase (e.g., "ISO-8859-1" -> "iso88591")
+// 2. Create additional aliases for common alternative prefixes:
+//    - "windows" -> "win" (e.g., "windows1252" also matches as "win1252")
+//    - "usascii" -> "ascii" (common shorthand)
+//    - "iso8859" -> "latin" (e.g., "iso88591" also matches as "latin1")
+// This handles the many variant spellings found in real-world email headers.
 CHARACTER_SETS.forEach(entry => {
     let key = entry.replace(/[_-\s]/g, '').toLowerCase();
     let modifiedKey = key
@@ -274,6 +285,10 @@ CHARACTER_SETS.forEach(entry => {
     }
 });
 
+// Resolves a charset name to its canonical IANA form using case-insensitive,
+// symbol-stripping normalization. For example, "WIN-1252", "windows_1252",
+// and "WINDOWS-1252" all resolve to "windows-1252".
+// Returns null if the charset is not recognized.
 module.exports.resolveCharset = charset => {
     let key = charset.replace(/[_-\s]/g, '').toLowerCase();
     if (CHARSET_MAP.has(key)) {

package/lib/commands/append.js

@@ -2,7 +2,17 @@
 
 const { formatFlag, canUseFlag, formatDateTime, normalizePath, encodePath, comparePaths, enhanceCommandError } = require('../tools.js');
 
-// Appends a message to a mailbox
+/**
+ * Appends a message to a mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} destination - Destination mailbox path
+ * @param {Buffer|string} content - Message content (RFC 822 format)
+ * @param {string|string[]} [flags] - Message flags to set on the appended message
+ * @param {Date|string} [idate] - Internal date to set for the message
+ * @returns {Promise<{destination: string, path?: string, uid?: number, uidValidity?: BigInt, seq?: number}|undefined>} Append result with UID info if available, or undefined if preconditions not met
+ * @throws {Error} If the APPEND command fails or message exceeds APPENDLIMIT
+ */
 module.exports = async (connection, destination, content, flags, idate) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !destination) {
         // nothing to do here
@@ -13,6 +23,8 @@ module.exports = async (connection, destination, content, flags, idate) => {
         content = Buffer.from(content);
     }
 
+    // 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) {
@@ -24,28 +36,36 @@ module.exports = async (connection, destination, content, flags, idate) => {
 
     destination = normalizePath(connection, destination);
 
+    // If appending to the currently selected mailbox, we can listen for the
+    // untagged EXISTS response to capture the new message's sequence number.
     let expectExists = comparePaths(connection, connection.mailbox.path, destination);
 
+    // Validate and format flags. Only flags allowed by the mailbox's permanentFlags are included.
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => flag && formatFlag(flag.toString()))
         .filter(flag => flag && canUseFlag(connection.mailbox, flag));
 
+    // APPEND command format: APPEND <mailbox> [<flags>] [<date-time>] <literal>
     let attributes = [{ type: 'ATOM', value: encodePath(connection, destination) }];
 
+    // Internal date: the date the server should record for this message.
+    // Must be quoted (STRING type) per the IMAP date-time grammar.
     idate = idate ? formatDateTime(idate) : false;
 
+    // Flags and date are optional; flags must come before date if both are present
     if (flags.length || idate) {
         attributes.push(flags.map(flag => ({ type: 'ATOM', value: flag })));
     }
 
     if (idate) {
-        attributes.push({ type: 'STRING', value: idate }); // force quotes as required by date-time
+        attributes.push({ type: 'STRING', value: idate });
     }
 
+    // BINARY extension (RFC 3516): if the message content contains NUL bytes,
+    // use literal8 syntax (~{size}\r\n) instead of regular literal ({size}\r\n).
+    // Regular literals cannot contain NUL bytes per the IMAP grammar.
     let isLiteral8 = false;
     if (connection.capabilities.has('BINARY') && !connection.disableBinary) {
-        // Value is literal8 if it contains NULL bytes. The server must support the BINARY extension
-        // and if it does not then send the value as a regular literal and hope for the best
         isLiteral8 = content.indexOf(Buffer.from([0])) >= 0;
     }
 
@@ -56,72 +76,58 @@ module.exports = async (connection, destination, content, flags, idate) => {
         map.path = connection.mailbox.path;
     }
 
+    // Handler for untagged EXISTS: captures the new message count which gives
+    // us the sequence number of the appended message (it's the latest message).
+    const handleExistsUpdate = untagged => {
+        map.seq = Number(untagged.command);
+
+        // Update the connection's mailbox state and emit 'exists' event if the
+        // count changed (notifies listeners about the new message).
+        if (expectExists) {
+            let prevCount = connection.mailbox.exists;
+            if (map.seq !== prevCount) {
+                connection.mailbox.exists = map.seq;
+                connection.emit('exists', {
+                    path: connection.mailbox.path,
+                    count: map.seq,
+                    prevCount
+                });
+            }
+        }
+    };
+
     let response;
     try {
         response = await connection.exec('APPEND', attributes, {
-            untagged: expectExists
-                ? {
-                      EXISTS: async untagged => {
-                          map.seq = Number(untagged.command);
-
-                          if (expectExists) {
-                              let prevCount = connection.mailbox.exists;
-                              if (map.seq !== prevCount) {
-                                  connection.mailbox.exists = map.seq;
-                                  connection.emit('exists', {
-                                      path: connection.mailbox.path,
-                                      count: map.seq,
-                                      prevCount
-                                  });
-                              }
-                          }
-                      }
-                  }
-                : false
+            // Only listen for EXISTS if we're appending to the currently selected mailbox
+            untagged: expectExists ? { EXISTS: handleExistsUpdate } : false
         });
 
+        // UIDPLUS (RFC 4315): the server may include APPENDUID response code in
+        // the tagged OK. Format: [APPENDUID <uidValidity> <uid>]
         let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
         if (section && section.length) {
             let responseCode = section[0] && typeof section[0].value === 'string' ? section[0].value : '';
-            switch (responseCode.toUpperCase()) {
-                case 'APPENDUID':
-                    {
-                        let uidValidity = section[1] && typeof section[1].value === 'string' && !isNaN(section[1].value) ? BigInt(section[1].value) : false;
-                        let uid = section[2] && typeof section[2].value === 'string' && !isNaN(section[2].value) ? Number(section[2].value) : false;
-                        if (uidValidity) {
-                            map.uidValidity = uidValidity;
-                        }
-                        if (uid) {
-                            map.uid = uid;
-                        }
-                    }
-                    break;
+            if (responseCode.toUpperCase() === 'APPENDUID') {
+                let uidValidity = section[1] && typeof section[1].value === 'string' && !isNaN(section[1].value) ? BigInt(section[1].value) : false;
+                let uid = section[2] && typeof section[2].value === 'string' && !isNaN(section[2].value) ? Number(section[2].value) : false;
+                if (uidValidity) {
+                    map.uidValidity = uidValidity;
+                }
+                if (uid) {
+                    map.uid = uid;
+                }
             }
         }
 
         response.next();
 
+        // If we didn't get an EXISTS during APPEND (some servers don't send it
+        // until the next command), issue a NOOP to flush pending notifications.
         if (expectExists && !map.seq) {
-            // try to use NOOP to get the new sequence number
             try {
                 response = await connection.exec('NOOP', false, {
-                    untagged: {
-                        EXISTS: async untagged => {
-                            map.seq = Number(untagged.command);
-
-                            if (expectExists) {
-                                let prevCount = connection.mailbox.exists;
-                                if (map.seq !== prevCount) {
-                                    connection.mailbox.exists = map.seq;
-                                    connection.emit('exists', {
-                                        path: connection.mailbox.path,
-                                        count: map.seq,
-                                        prevCount
-                                    });
-                                }
-                            }
-                        }
-                    },
+                    untagged: { EXISTS: handleExistsUpdate },
                     comment: 'Sequence not found from APPEND output'
                 });
                 response.next();
@@ -130,6 +136,8 @@ module.exports = async (connection, destination, content, flags, idate) => {
             }
         }
 
+        // If we have a sequence number but no UID (server doesn't support UIDPLUS),
+        // look up the UID via SEARCH to provide a consistent result to the caller.
         if (map.seq && !map.uid) {
             let list = await connection.search({ seq: map.seq }, { uid: true });
             if (list && list.length) {