imapflow 1.7.7 → 2.0.0

package/dist/esm/types.js

@@ -0,0 +1,4 @@
+// Public data shapes of the ImapFlow API. Every optional property is declared with an
+// explicit `| undefined` so that a consumer compiling with exactOptionalPropertyTypes
+// can still pass a value that may be undefined.
+export {};

package/package.json

@@ -1,17 +1,56 @@
 {
     "name": "imapflow",
-    "version": "1.7.7",
+    "version": "2.0.0",
     "description": "IMAP Client for Node",
-    "main": "lib/imap-flow.js",
-    "types": "lib/imap-flow.d.ts",
+    "type": "module",
+    "main": "./dist/cjs/imap-flow.js",
+    "types": "./dist/cjs/imap-flow.d.ts",
+    "typesVersions": {
+        "*": {
+            "lib/*": [
+                "dist/cjs/*.d.ts"
+            ]
+        }
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/esm/imap-flow.js",
+            "require": "./dist/cjs/imap-flow.js"
+        },
+        "./lib/*.js": {
+            "import": "./dist/esm/*.js",
+            "require": "./dist/cjs/*.js"
+        },
+        "./lib/*": {
+            "import": "./dist/esm/*.js",
+            "require": "./dist/cjs/*.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "SECURITY.txt"
+    ],
     "scripts": {
-        "test": "grunt",
-        "coverage": "c8 --reporter=text --reporter=html npx nodeunit test/*-test.js",
+        "build": "node scripts/build.js",
+        "typecheck": "node scripts/build.js --generate-only && tsc -p tsconfig.json",
+        "pretest": "npm run build",
+        "test": "node --import tsx --test --test-force-exit --test-concurrency=1 $(find test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*')",
+        "pretest:coverage": "npm run build",
+        "test:coverage": "c8 node --import tsx --test --test-force-exit --test-concurrency=1 $(find test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*')",
+        "pretest:bun": "npm run build",
+        "test:bun": "bun test --timeout 60000 $(find ./test -name '*-test.ts' -not -path '*/integration/*' -not -path '*/cloudflare/*')",
+        "pretest:workers": "npm run build",
+        "test:workers": "node --import tsx --test test/cloudflare/cloudflare-test.ts",
         "test:rev2": "bash test/integration/run-rev2-tests.sh",
-        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
-        "format": "prettier --write \"**/*.{js,json,md,yml,yaml}\" --ignore-path .prettierignore",
-        "format:check": "prettier --check \"**/*.{js,json,md,yml,yaml}\" --ignore-path .prettierignore",
-        "lint": "eslint ."
+        "format": "prettier --write \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
+        "format:check": "prettier --check \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
+        "lint": "eslint . && npm run typecheck",
+        "lint:fix": "eslint . --fix",
+        "prepare": "npm run build",
+        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
     },
     "repository": {
         "type": "git",
@@ -29,19 +68,17 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@eslint/js": "10.0.1",
-        "@types/node": "26.4.0",
+        "@types/node": "20.19.43",
         "c8": "12.0.0",
-        "eslint": "10.9.1",
-        "eslint-config-nodemailer": "1.2.0",
+        "eslint": "10.10.0",
         "eslint-config-prettier": "10.1.8",
-        "grunt": "1.6.3",
-        "grunt-cli": "1.5.0",
-        "grunt-contrib-nodeunit": "5.0.0",
-        "grunt-eslint": "26.0.0",
+        "globals": "17.12.0",
         "prettier": "3.9.6",
-        "proxyquire": "^2.1.3",
-        "typescript": "7.0.2"
+        "tsx": "4.23.13",
+        "types-node-legacy": "npm:@types/node@20.0.0",
+        "typescript": "6.0.3",
+        "typescript-eslint": "8.69.0",
+        "wrangler": "4.129.0"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.16",
@@ -51,6 +88,9 @@
         "libmime": "5.4.3",
         "libqp": "2.1.1",
         "pino": "10.3.1",
-        "socks": "2.8.9"
+        "socks": "2.8.10"
+    },
+    "engines": {
+        "node": ">=20.0.0"
     }
 }

package/.gitattributes

@@ -1 +0,0 @@
-*.js text eol=lf

package/.github/CODE_OF_CONDUCT.md

@@ -1,76 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-- Using welcoming and inclusive language
-- Being respectful of differing viewpoints and experiences
-- Gracefully accepting constructive criticism
-- Focusing on what is best for the community
-- Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-- The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
-- Trolling, insulting/derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at andris@postalsys.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq

package/.github/FUNDING.yml

@@ -1,4 +0,0 @@
-# These are supported funding model platforms
-
-github: [andris9] # enable once enrolled
-custom: ['https://www.paypal.me/nodemailer']

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,40 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
----
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
-
-**Desktop (please complete the following information):**
-
-- OS: [e.g. iOS]
-- Browser [e.g. chrome, safari]
-- Version [e.g. 22]
-
-**Smartphone (please complete the following information):**
-
-- Device: [e.g. iPhone6]
-- OS: [e.g. iOS8.1]
-- Browser [e.g. stock browser, safari]
-- Version [e.g. 22]
-
-**Additional context**
-Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,19 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.

package/.github/contributing.md

@@ -1,17 +0,0 @@
-# Contributing
-
-## Legal
-
-(agreement below borrowed from [Sidekiq Legal](https://github.com/mperham/sidekiq/blob/master/.github/contributing.md))
-
-By submitting a Pull Request, you disavow any rights or claims to any changes
-submitted to the ImapFlow project and assign the copyright of
-those changes to Postal Systems OÜ.
-
-If you cannot or do not want to reassign those rights (your employment
-contract for your employer may not allow this), you should not submit a PR.
-Open an issue and someone else can do the work.
-
-This is a legal way of saying "If you submit a PR to us, that code becomes ours".
-99.9% of the time that's what you intend anyways; we hope it doesn't scare you
-away from contributing.

package/.github/workflows/release.yaml

@@ -1,36 +0,0 @@
-on:
-    push:
-        branches:
-            - master
-
-permissions:
-    contents: write
-    pull-requests: write
-    issues: write
-    id-token: write
-
-name: release
-jobs:
-    release-please:
-        runs-on: ubuntu-latest
-        outputs:
-            release_created: ${{ steps.release.outputs.release_created }}
-        steps:
-            - uses: googleapis/release-please-action@v4
-              id: release
-
-    publish:
-        needs: release-please
-        if: ${{ needs.release-please.outputs.release_created }}
-        runs-on: ubuntu-latest
-        permissions:
-            contents: read
-            id-token: write
-        steps:
-            - uses: actions/checkout@v6
-            - uses: actions/setup-node@v6
-              with:
-                  node-version: 24
-                  registry-url: 'https://registry.npmjs.org'
-            - run: npm ci
-            - run: npm publish --provenance --access public

package/.github/workflows/stale.yml

@@ -1,29 +0,0 @@
-name: 'Close stale issues and PRs'
-on:
-    schedule:
-        - cron: '30 1 * * *'
-
-permissions:
-    contents: read
-    issues: write
-    pull-requests: write
-
-jobs:
-    stale:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/stale@v10
-              with:
-                  stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.'
-                  stale-pr-message: 'This PR is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 10 days.'
-                  close-issue-message: 'This issue was closed because it has been stalled for 15 days with no activity.'
-                  close-pr-message: 'This PR was closed because it has been stalled for 20 days with no activity.'
-                  days-before-issue-stale: 30
-                  days-before-pr-stale: 45
-                  days-before-issue-close: 15
-                  days-before-pr-close: 20
-                  stale-issue-label: 'no-issue-activity'
-                  exempt-issue-labels: 'pending,work-in-progress'
-                  stale-pr-label: 'no-pr-activity'
-                  exempt-pr-labels: 'awaiting-approval,work-in-progress'
-                  repo-token: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/test.yml

@@ -1,51 +0,0 @@
-name: Run tests
-
-on:
-    push:
-    pull_request:
-
-permissions:
-    contents: read
-
-concurrency:
-    group: ${{ github.workflow }}-${{ github.ref }}
-    cancel-in-progress: true
-
-jobs:
-    test:
-        name: Test (Node ${{ matrix.node }})
-        timeout-minutes: 10
-        strategy:
-            matrix:
-                node: [22.x, 24.x]
-                os: [ubuntu-latest]
-        runs-on: ${{ matrix.os }}
-        steps:
-            - uses: actions/checkout@v6
-            - name: Use Node.js ${{ matrix.node }}
-              uses: actions/setup-node@v6
-              with:
-                  node-version: ${{ matrix.node }}
-                  cache: npm
-            - run: npm install
-            - run: npm test
-
-    test-rev2:
-        # Live IMAP4rev2 integration tests against a real Dovecot 2.4 server in
-        # Docker on linux/amd64 (ubuntu runners are amd64 with Docker preinstalled).
-        # This is the only place the suite runs on amd64 - Apple Silicon dev
-        # machines cannot run the amd64 image under Rosetta.
-        name: Live IMAP4rev2 tests (Dovecot, linux/amd64)
-        timeout-minutes: 15
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v6
-            - name: Use Node.js 24.x
-              uses: actions/setup-node@v6
-              with:
-                  node-version: 24.x
-                  cache: npm
-            - run: npm install
-            - run: npm run test:rev2
-              env:
-                  IMAPFLOW_DOVECOT_PLATFORM: linux/amd64

package/.ncurc.js

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

package/.prettierignore

@@ -1,4 +0,0 @@
-node_modules
-package-lock.json
-CHANGELOG.md
-docs/

package/.prettierrc.js

@@ -1,8 +0,0 @@
-module.exports = {
-    printWidth: 160,
-    tabWidth: 4,
-    singleQuote: true,
-    endOfLine: 'lf',
-    trailingComma: 'none',
-    arrowParens: 'avoid'
-};

package/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-    ".": "1.7.7"
-}

package/CLAUDE.md

@@ -1,104 +0,0 @@
-# Claude Development Guidelines
-
-## Project Overview
-
-ImapFlow is a modern, promise-based IMAP client library for Node.js. It opens
-TLS/cleartext connections to IMAP servers, authenticates, and parses untrusted
-protocol responses from those servers into a friendly API. It is published to
-npm as `imapflow` and ships TypeScript type definitions.
-
-## Project Structure
-
-- `lib/imap-flow.js` - Main `ImapFlow` client class (connection lifecycle, command dispatch, public API)
-- `lib/imap-flow.d.ts` - TypeScript type definitions (published as `types`)
-- `lib/imap-commands.js` - Registry wiring individual command implementations
-- `lib/commands/` - Per-command implementations (login, fetch, search, append, etc.)
-- `lib/handler/` - IMAP response stream parser and command compiler (tokenizer, literals, line handling)
-- `lib/search-compiler.js` - Translates the search query object into IMAP SEARCH terms
-- `lib/charsets.js`, `lib/jp-decoder.js` - Charset/encoding helpers
-- `lib/special-use.js` - SPECIAL-USE mailbox detection
-- `lib/proxy-connection.js` - SOCKS/HTTP proxy connection support
-- `lib/limited-passthrough.js`, `lib/tools.js`, `lib/logger.js` - Internal utilities
-- `test/` - Unit tests (`*-test.js`), run with nodeunit via Grunt
-- `examples/` - Standalone usage examples (not production code)
-
-## Technology Stack
-
-- **Runtime**: Node.js (CI tests on 22.x and 24.x)
-- **Module system**: CommonJS (see Packaging Constraints below)
-- **Testing**: Grunt + grunt-contrib-nodeunit, ESLint via grunt-eslint
-- **Lint/format**: ESLint (`eslint.config.js`, flat config) + Prettier
-- **Key dependencies**: `@zone-eu/mailsplit`, `libmime`, `libqp`, `libbase64`, `iconv-lite`, `encoding-japanese`, `pino`, `socks`
-
-## Development Commands
-
-```
-npm test           # Run full suite via Grunt (ESLint + nodeunit tests)
-npm run coverage   # Run tests under c8 coverage (text + html reports)
-npm run lint       # Lint with ESLint
-npm run format     # Format with Prettier (js, json, md, yml, yaml)
-npm run update     # Refresh deps: remove node_modules + lockfile, ncu -u, npm install
-npm run test:rev2  # Live IMAP4rev2 tests against Dovecot in Docker (see test/integration/)
-```
-
-## Testing
-
-- Tests live in `test/` and are named `*-test.js`; the Grunt nodeunit glob only matches that pattern, so helpers/fixtures are never run as tests. Exception: `test/integration/` is excluded from the glob - those tests need Docker and run only via `npm run test:rev2`.
-- `npm test` runs `grunt`, which runs ESLint first, then the nodeunit suite. Keep the suite green and lint-clean before committing.
-- New tests go in `test/` as `*-test.js`. The parser, command compiler, and search compiler are the most security-sensitive areas - add hostile/malformed-input cases there.
-- `npm run test:rev2` starts a Dovecot 2.4 container (real IMAP4rev2 server) and runs `test/integration/rev2-live-test.js` against it - use it to verify rev2-facing changes end to end, mocks alone are not enough.
-
-## Packaging Constraints (IMPORTANT)
-
-EmailEngine (see "Relationship to EmailEngine" below) bundles ImapFlow and all
-of its transitive dependencies into a single self-contained executable using
-[`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg). `pkg` works by snapshotting a
-CommonJS `require()` graph, so it **cannot bundle pure-ESM packages**.
-
-Therefore ImapFlow itself and every dependency it pulls in must stay
-CommonJS-compatible:
-
-- ImapFlow source stays CommonJS (`require`/`module.exports`). Do not convert the library to ESM.
-- Do not add a dependency that is pure ESM (`"type": "module"` with only an `import`/ESM entry and no CommonJS export). It must be `require()`-able.
-- When `npm run update` or a new dependency would pull in a pure-ESM package (a common outcome of major-version bumps), pin to the last CommonJS-compatible version instead, or find a CommonJS alternative. Verify with a quick `require()` of the package after updating.
-- After every `npm run update`, run this check to confirm all production dependencies are still CommonJS (it must print `CJS OK` for every dependency and report no pure-ESM packages), then run `npm test`:
-
-    ```
-    node -e "Object.keys(require('./package.json').dependencies).forEach(d => { require(d); console.log('CJS OK:', d); })"
-    node -e "const fs=require('fs');const bad=Object.keys(require('./package.json').dependencies).filter(d=>JSON.parse(fs.readFileSync(require.resolve(d+'/package.json'),'utf8')).type==='module');console.log(bad.length?'PURE-ESM DEPS FOUND: '+bad.join(', '):'No pure-ESM production dependencies')"
-    ```
-
-- Keep dynamic `require()` paths static enough for `pkg` to detect; avoid building module paths at runtime in ways the bundler can't trace.
-
-## Code Style Rules
-
-- Never use emojis in code or documentation, only printable ASCII characters.
-- Use a single hyphen-minus (`-`) as a dash in user-facing strings and docs. Never use double hyphens (`--`), em dashes, or en dashes.
-- When composing git commit messages, do not include Claude as a co-contributor.
-- Use Conventional Commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, ...). Versioning and the changelog are driven by these prefixes via release-please.
-- For commits that do not change published runtime behavior (docs, comments, CI/workflow tweaks, formatting), append `[skip ci]` to the commit message to avoid triggering the GitHub Actions workflows. Exception: do not add `[skip ci]` to commits using a `fix:` or `feat:` prefix - those must run so the release action is triggered.
-- After making code changes:
-    1. Run `npm run format` and `npm run lint`
-    2. Run `npm test` and keep it green
-    3. For non-trivial changes, run `/simplify` to review changed code and `/security-review` to check for security issues before committing
-- After pushing, check the GitHub Actions runs for the push (e.g. `gh run list --branch master`) and report their status. If a run fails for a strange or unrelated reason (for example a checkout step reporting "account suspended", HTTP 403, or other auth/infrastructure errors that have nothing to do with the change), check <https://www.githubstatus.com/> for an active GitHub incident before assuming the failure is caused by the change.
-
-## Relationship to EmailEngine
-
-ImapFlow is developed and maintained primarily as the IMAP client used by
-[EmailEngine](https://github.com/postalsys/emailengine). The local development
-copy of EmailEngine lives at `../emailengine` relative to this project root. When
-EmailEngine hits a bug or unhandled promise rejection that originates in
-ImapFlow, the fix belongs here in the ImapFlow source rather than as a
-workaround in EmailEngine. Because EmailEngine packages this library with
-`@yao-pkg/pkg`, never make a change here that breaks CommonJS packaging (see
-Packaging Constraints).
-
-## Security
-
-Security policy and private reporting channels are documented in
-[`SECURITY.md`](SECURITY.md) / [`SECURITY.txt`](SECURITY.txt).
-
-## Release Process
-
-Changelog and version numbers are managed automatically by the release-please GitHub Action. Do not check for or suggest CHANGELOG entries or version bumps during code reviews.

package/Gruntfile.js

@@ -1,23 +0,0 @@
-'use strict';
-
-module.exports = function (grunt) {
-    // Project configuration.
-    grunt.initConfig({
-        eslint: {
-            all: ['lib/**/*.js', 'test/**/*.js', 'Gruntfile.js']
-        },
-
-        nodeunit: {
-            // test/integration is excluded: those tests need a live Docker server
-            // and run via `npm run test:rev2` instead
-            all: ['test/**/*-test.js', '!test/integration/**']
-        }
-    });
-
-    // Load the plugin(s)
-    grunt.loadNpmTasks('grunt-eslint');
-    grunt.loadNpmTasks('grunt-contrib-nodeunit');
-
-    // Tasks
-    grunt.registerTask('default', ['eslint', 'nodeunit']);
-};

package/eslint.config.js

@@ -1,45 +0,0 @@
-'use strict';
-
-const js = require('@eslint/js');
-const globals = require('globals');
-const prettierConfig = require('eslint-config-prettier/flat');
-const nodemailerConfig = require('eslint-config-nodemailer');
-
-module.exports = [
-    {
-        ignores: ['node_modules/**', 'examples/**', 'docs/**']
-    },
-    js.configs.recommended,
-    {
-        languageOptions: {
-            ecmaVersion: 2022,
-            sourceType: 'script',
-            parserOptions: {
-                ecmaFeatures: {
-                    globalReturn: true
-                }
-            },
-            globals: {
-                ...globals.node,
-                ...globals.es2021,
-                it: 'readonly',
-                describe: 'readonly',
-                beforeEach: 'readonly',
-                afterEach: 'readonly'
-            }
-        },
-        rules: {
-            ...nodemailerConfig.rules,
-            'no-await-in-loop': 0,
-            'require-atomic-updates': 0
-        }
-    },
-    prettierConfig,
-    {
-        files: ['eslint.config.js', '.prettierrc.js', '.ncurc.js'],
-        rules: {
-            'global-require': 0,
-            strict: 0
-        }
-    }
-];