@postalsys/email-text-tools 2.4.24 → 2.4.26

package/.github/workflows/release.yaml

@@ -28,10 +28,11 @@ jobs:
             contents: read
             id-token: write
         steps:
-            - uses: actions/checkout@v6
-            - uses: actions/setup-node@v6
+            - uses: actions/checkout@v7
+            - uses: actions/setup-node@v7
               with:
                   node-version: 24
+                  package-manager-cache: false
                   registry-url: 'https://registry.npmjs.org'
             - run: npm ci
             - run: npm publish --provenance --access public

package/.github/workflows/test.yaml

@@ -15,17 +15,21 @@ jobs:
     test:
         strategy:
             matrix:
-                node: [22.x, 24.x]
+                node: [20.x, 22.x, 24.x, latest]
                 os: [ubuntu-latest]
         runs-on: ${{ matrix.os }}
         timeout-minutes: 10
         steps:
-            - uses: actions/checkout@v6
+            - uses: actions/checkout@v7
             - name: Use Node.js ${{ matrix.node }}
-              uses: actions/setup-node@v6
+              uses: actions/setup-node@v7
               with:
                   node-version: ${{ matrix.node }}
                   cache: npm
-            - run: npm install
+            - run: npm ci
             - run: npm run lint
+            - run: npm run format:check
             - run: npm test
+            - name: CommonJS dependency graph (require(esm) disabled)
+              if: matrix.node != '20.x'
+              run: npm run test:cjs

package/.ncurc.js

@@ -1,3 +1,5 @@
+'use strict';
+
 module.exports = {
     upgrade: true,
     reject: [
@@ -17,6 +19,10 @@ module.exports = {
         // 2.0.0 is ESM-only (exports only src/he.mjs) and requires Node >=22, so require('he') throws
         // and pkg cannot bundle it. 1.2.0 is the last CommonJS release; EmailEngine and mailparser
         // hold it there too, and a different copy here would be a second he in their trees
-        'he'
+        'he',
+        // @asamuzakjp/css-color >=4.1.2 pulls in @csstools/* which are pure ESM, so require(jsdom) fails
+        // without require(esm) (jsdom -> cssstyle -> @asamuzakjp/css-color). Held at 4.1.1 through
+        // package.json "overrides"; overrides do not propagate to consumers, EmailEngine carries its own.
+        '@asamuzakjp/css-color'
     ]
 };

package/.prettierrc.js

@@ -1,3 +1,5 @@
+'use strict';
+
 module.exports = {
     printWidth: 160,
     tabWidth: 4,

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "2.4.24"
+    ".": "2.4.26"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.4.26](https://github.com/postalsys/email-text-tools/compare/v2.4.25...v2.4.26) (2026-10-19)
+
+
+### Bug Fixes
+
+* bump email-content to 0.1.17 and node-html-parser to 9.0.5 ([e95e4a8](https://github.com/postalsys/email-text-tools/commit/e95e4a840a5d343004c022ccaeaf4caec1d4e142))
+
+## [2.4.25](https://github.com/postalsys/email-text-tools/compare/v2.4.24...v2.4.25) (2026-10-18)
+
+
+### Bug Fixes
+
+* bump @postalsys/email-content to 0.1.16 ([2c31e98](https://github.com/postalsys/email-text-tools/commit/2c31e98d087937e677c1a2f7d6f066d18148d788))
+
 ## [2.4.24](https://github.com/postalsys/email-text-tools/compare/v2.4.23...v2.4.24) (2026-10-18)
 
 

package/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm test                  # run the full suite (node --test test/*.test.js)
+npm run test:cjs          # the suite with require(esm) disabled (CommonJS graph guard)
+npm run test:coverage     # with experimental coverage
+npm run test:watch        # watch mode
+npm run lint              # eslint .
+npm run lint:fix          # eslint . --fix
+npm run format            # prettier --write .
+npm run format:check      # prettier --check .
+npm run update            # rm -rf node_modules package-lock.json && ncu -u && npm install
+```
+
+Run a single test file or a single test by name (uses Node's built-in test runner):
+
+```bash
+node --test test/mime-html.test.js
+node --test --test-name-pattern="should process HTML in worker thread"
+```
+
+Benchmarks are not wired into npm scripts; run them directly, e.g. `node benchmark/benchmark.js` (see `benchmark/` and `docs/PERFORMANCE.md`).
+
+## Critical constraints
+
+- **CommonJS only, Node 20 minimum.** See Platform constraints below. All source uses `require`/`module.exports` with a global `'use strict'` (ESLint enforces `sourceType: 'commonjs'`). The constraint is about the module format, not the syntax level: ESLint parses `ecmaVersion: 2022`, which every supported Node (>=20) and pkg target runs natively. The `require('juice').default || require('juice')` idiom at the require sites is a deliberate CJS-interop fallback, not dead code.
+- **Releases are automated via release-please.** Version in `package.json` and `CHANGELOG.md` are owned by the bot, do not bump them by hand. Conventional Commits drive it (`fix:` -> patch, `feat:` -> minor); `fix:`/`feat:` commits land directly on `main` and release-please opens the release PR. See Conventions below for the full commit rules.
+- **ESLint uses the shared flat config** (`eslint.config.js`, ESLint 10). It is the CommonJS template shared across the Postal Systems / Nodemailer packages (eslint:recommended plus the retired eslint-config-nodemailer rules, eslint-config-prettier last); keep it identical to the other repos except for the "Repo-specific" block at the end, where each override carries a one-line reason. The only override here turns `no-await-in-loop` off for `benchmark/`, which awaits sequentially on purpose. CI (`.github/workflows/test.yaml`) runs lint, `format:check` and the tests on Node 20, 22 and 24, plus `npm run test:cjs` on 22 and 24.
+
+## Platform constraints
+
+- **Node.js 20 is the minimum supported version** (`engines.node` is `>=20.0.0`). Runtime code, tests and tooling must work on Node 20, 22 and 24.
+- **Everything that reaches runtime must be genuinely CommonJS-loadable.** EmailEngine consumes this library and ships as a single-file binary built with [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg), which snapshots a CommonJS module graph and cannot load ES modules. `require()` of this package and of every runtime dependency must work with `--no-experimental-require-module`: Node 22+ (and 20.19) enable require(esm) by default, which hides an ESM-only dependency until the pkg binary fails. A CommonJS entry that only wraps a dynamic `import()` of ESM code does not count.
+- **How to check:** `npm run test:cjs` runs the whole suite under `NODE_OPTIONS=--no-experimental-require-module`; CI runs it on Node 22 and 24.
+- **Pins:** never add or upgrade to an ESM-only dependency. Hold the last CommonJS major in `.ncurc.js` (`reject` or `target`) with a one-line reason; `npm run update` honors it. Currently rejected: `nanoid`, `jsdom` (27.0.1 pulls an ESM-only parse5), `juice` (12+ is pure ESM and needs Node >=22.12), `linkify-it` (6.0.0 changed exports and stopped linkifying bare domains), `he` (2.0.0 is ESM-only), `@asamuzakjp/css-color`.
+- **The jsdom chain:** jsdom -> cssstyle -> `@asamuzakjp/css-color` >=4.1.2 pulls in `@csstools/*` v4, which are pure ESM. `package.json` `"overrides"` holds `@asamuzakjp/css-color` at 4.1.1 so this repo's own tests and CI exercise the CommonJS graph. Overrides do not propagate to consumers: an app installing this package resolves css-color itself, and EmailEngine carries its own identical override and `.ncurc.js` reject.
+
+## Conventions
+
+These mirror the conventions used across Postal Systems projects (see `../emailengine`).
+
+**Git commits**
+
+- Use Conventional Commits: `fix:` (patch release), `feat:` (minor release), and `chore:`/`build:`/`ci:`/`docs:`/`refactor:`/`style:`/`test:` for changes that should not trigger a release. release-please derives the version and changelog from these prefixes.
+- Do **not** list Claude or any AI assistant as a co-author / co-contributor in commit messages or PR descriptions (no `Co-Authored-By` trailer).
+- Append `[skip ci]` to commits that do not change runtime behavior (docs, comments, CI/workflow tweaks, formatting) to avoid spending CI minutes. Exception: never add `[skip ci]` to a `fix:` or `feat:` commit, those must run so the release workflow triggers.
+
+**Code & docs style**
+
+- No emojis anywhere in code or documentation, printable ASCII only.
+- Use a single hyphen-minus (`-`) as a dash in user-facing strings and docs. Never use double hyphens (`--`), em dashes, or en dashes.
+
+**Before committing code changes**
+
+1. `npm run format` and `npm run lint`
+2. `npm test`
+3. For non-trivial changes, consider `/simplify` (quality cleanup) and `/security-review`. This library sanitizes untrusted HTML, so anything touching the `mimeHtml` pipeline is security-sensitive.
+
+**After pushing**
+
+- Check the workflow runs for the push (`gh run list --branch <branch>`) and report their status. If a run fails for an unrelated/infrastructure reason (checkout reporting "account suspended", HTTP 403, other auth errors), check <https://www.githubstatus.com/> for an active GitHub incident before assuming the change caused it.
+
+## Architecture
+
+A small CommonJS library exposing five text-transformation functions for email content, all re-exported from `index.js` (`mimeHtml` through a lazy getter, so jsdom only loads on first use):
+
+| Export       | File                  | Purpose                                                     |
+| ------------ | --------------------- | ----------------------------------------------------------- |
+| `textToHtml` | `lib/text-to-html.js` | plain text -> HTML (linkified, quote-aware)                 |
+| `htmlToText` | `lib/html-to-text.js` | HTML -> plain text                                          |
+| `inlineHtml` | `lib/inline-html.js`  | build reply/forward HTML body with quoted original          |
+| `inlineText` | `lib/inline-text.js`  | build reply/forward plain-text body with quoted original    |
+| `mimeHtml`   | `lib/mime-html.js`    | sanitize + inline-CSS arbitrary email HTML for safe display |
+
+`lib/html-guard.js` holds what `mimeHtml` and `inlineHtml` share before they parse anything: the nesting-depth estimate (`exceedsNestingDepth`, `MAX_NESTING_DEPTH`) and the plain-text fallback projection (`fallbackText`). It does not load jsdom, so `inline-html.js` can require it eagerly.
+
+### `mimeHtml`: the core, and where the complexity lives
+
+Pipeline (same for sync and async): **DOMPurify sanitize (whole document)** -> **pre-filter problematic CSS** -> **juice (inline `<style>` into element `style=` attributes)** -> **DOMPurify sanitize again (return DOM body)** -> strip forbidden style properties / size constraints, force `target="_blank"` on links, wrap in a styled `<div>`. When the input has only `text` (no `html`), it is first run through `textToHtml` and given a default `<style>` block (`INLINE_STYLE_BLOCK`).
+
+The non-obvious part is **juice hang protection**. Certain modern CSS selectors (`:is()`, `:where()`, `:has()`, `:not(... : ...)`) can make `juice` hang. Two layers defend against this:
+
+1. A linear pre-filter (`filterCss()`, split on `}`, never a regex: the old regex backtracked catastrophically) strips rules using those selectors from head `<style>` tags before juice runs, after capping style text at 256 KB. Input nested deeper than `MAX_NESTING_DEPTH` is not parsed (jsdom tree building is quadratic in depth) and, like any pipeline error, renders the escaped-text `fallbackHtml()`.
+2. The async path additionally runs juice inside a **worker thread with a timeout** as a safety net for unknown edge cases. On timeout/failure it falls back to returning the HTML without inlined CSS (unless `fallbackOnError: false`).
+
+`mimeHtml` exposes three forms. Note the default is sync for backward compatibility, but only the async form is fully hang-protected:
+
+- `mimeHtml(message)` / `mimeHtml.sync(message)`: synchronous, runs juice in-process (can still hang on unknown selectors).
+- `mimeHtml.async(message, options)`: async, juice in a worker pool with timeout. Options: `timeout`, `useWorkerPool`, `fallbackOnError`, `minWorkers`/`maxWorkers`/`idleTimeout`.
+- `mimeHtml.closeWorkerPool()` / `mimeHtml.getWorkerPoolStats()`: manage the lazily-created global worker pool.
+
+`lib/worker-pool.js` (`WorkerPool`) manages a min/max pool of `lib/juice-worker.js` workers with task queueing, per-task timeouts, worker replacement on error/timeout, and idle-worker reaping. `lib/juice-worker.js` is a tiny worker entry that just runs `juice(html)` and posts the result back.
+
+### Other modules
+
+- `text-to-html.js` parses plain text into a nested tree of `text`/`quote` nodes (by `>` prefixes) so multi-level email quotes become nested `<blockquote class="ee-block-N">`. Linkification uses `linkify-it` + full `tlds` list (plus `.onion` and a `git:` alias).
+- `inline-html.js` / `inline-text.js` produce Apple-Mail-style reply/forward bodies, formatting From/Subject/Date/To/Cc/Bcc headers and quoting the original (HTML via `<blockquote>`, text via `> ` prefixes). Dates use `Intl.DateTimeFormat` via `lib/format-date.js`, honoring `options.locale` (unsupported -> 'en') and `options.tz` (unknown -> UTC).
+
+### Testing notes
+
+Tests use Node's built-in `node:test` runner. Suites that exercise `mimeHtml.async` or `WorkerPool` **must call `await mimeHtml.closeWorkerPool()` (or close the pool) in an `after()` hook**, otherwise live workers keep the process alive and the run hangs.

package/benchmark/benchmark.js

@@ -281,22 +281,14 @@ class Benchmark {
             };
 
             // Test sync version
-            results.tests.push(
-                await this.runTest(
-                    'Sync',
-                    () => {
-                        return Promise.resolve(mimeHtml.sync({ html: testCase.html }));
-                    },
-                    100
-                )
-            );
+            results.tests.push(await this.runTest('Sync', () => Promise.resolve(mimeHtml.sync({ html: testCase.html })), 100));
 
             // Test async version with pool
             results.tests.push(
                 await this.runTest(
                     'Async (with pool)',
-                    async () => {
-                        return await mimeHtml.async(
+                    async () =>
+                        await mimeHtml.async(
                             { html: testCase.html },
                             {
                                 useWorkerPool: true,
@@ -304,8 +296,7 @@ class Benchmark {
                                 minWorkers: 2,
                                 maxWorkers: 4
                             }
-                        );
-                    },
+                        ),
                     100
                 )
             );
@@ -314,15 +305,14 @@ class Benchmark {
             results.tests.push(
                 await this.runTest(
                     'Async (no pool)',
-                    async () => {
-                        return await mimeHtml.async(
+                    async () =>
+                        await mimeHtml.async(
                             { html: testCase.html },
                             {
                                 useWorkerPool: false,
                                 timeout: 5000
                             }
-                        );
-                    },
+                        ),
                     100
                 )
             );

package/benchmark/concurrency-benchmark.js

@@ -142,10 +142,10 @@ async function concurrencyBenchmark() {
     console.log('-'.repeat(40));
 
     const asyncResults = results.filter(r => r.method === 'Async (pool)');
-    const maxThroughput = Math.max(...asyncResults.map(r => parseInt(r.reqPerSec)));
+    const maxThroughput = Math.max(...asyncResults.map(r => parseInt(r.reqPerSec, 10)));
 
     asyncResults.forEach(r => {
-        const barLength = Math.round((parseInt(r.reqPerSec) / maxThroughput) * 30);
+        const barLength = Math.round((parseInt(r.reqPerSec, 10) / maxThroughput) * 30);
         const bar = '█'.repeat(barLength);
         console.log(`  ${String(r.concurrency).padStart(2)}: ${bar} ${r.reqPerSec} req/s`);
     });

package/benchmark/real-world-benchmark.js

@@ -117,15 +117,7 @@ class RealWorldBenchmark {
         // Test 1: Sync version
         console.log('Test 1: Sync Version');
         console.log('-'.repeat(40));
-        results.push(
-            await this.runTest(
-                'Sync',
-                () => {
-                    return Promise.resolve(mimeHtml.sync({ html: realWorldHtml }));
-                },
-                50
-            )
-        );
+        results.push(await this.runTest('Sync', () => Promise.resolve(mimeHtml.sync({ html: realWorldHtml })), 50));
 
         // Test 2: Async with worker pool
         console.log('\nTest 2: Async with Worker Pool');
@@ -133,8 +125,8 @@ class RealWorldBenchmark {
         results.push(
             await this.runTest(
                 'Async (pool)',
-                async () => {
-                    return await mimeHtml.async(
+                async () =>
+                    await mimeHtml.async(
                         { html: realWorldHtml },
                         {
                             useWorkerPool: true,
@@ -143,8 +135,7 @@ class RealWorldBenchmark {
                             maxWorkers: 4,
                             logErrors: false
                         }
-                    );
-                },
+                    ),
                 50
             )
         );
@@ -155,16 +146,15 @@ class RealWorldBenchmark {
         results.push(
             await this.runTest(
                 'Async (no pool)',
-                async () => {
-                    return await mimeHtml.async(
+                async () =>
+                    await mimeHtml.async(
                         { html: realWorldHtml },
                         {
                             useWorkerPool: false,
                             timeout: 5000,
                             logErrors: false
                         }
-                    );
-                },
+                    ),
                 10
             )
         );

package/eslint.config.js

@@ -1,52 +1,71 @@
+'use strict';
+
+// Shared lint baseline for the Postal Systems / Nodemailer packages: eslint:recommended
+// plus the rules of the retired eslint-config-nodemailer, with formatting left to Prettier.
+// Keep this file identical across repos except for the "Repo-specific" block at the end.
+
 const js = require('@eslint/js');
 const prettier = require('eslint-config-prettier');
+const globals = require('globals');
 
 module.exports = [
+    {
+        ignores: ['node_modules/**', 'coverage/**', 'dist/**']
+    },
     js.configs.recommended,
-    prettier,
     {
-        files: ['**/*.js'],
+        files: ['**/*.js', '**/*.cjs'],
         languageOptions: {
-            ecmaVersion: 2018,
-            sourceType: 'script',
-            globals: {
-                BigInt: true,
-                Buffer: 'readonly',
-                console: 'readonly',
-                global: 'readonly',
-                process: 'readonly',
-                require: 'readonly',
-                module: 'readonly',
-                exports: 'writable',
-                __dirname: 'readonly',
-                __filename: 'readonly',
-                setTimeout: 'readonly',
-                clearTimeout: 'readonly',
-                setInterval: 'readonly',
-                clearInterval: 'readonly',
-                setImmediate: 'readonly',
-                clearImmediate: 'readonly'
-            }
+            ecmaVersion: 2022,
+            sourceType: 'commonjs',
+            globals: { ...globals.node }
         },
         rules: {
-            'no-await-in-loop': 'off',
-            'require-atomic-updates': 'off',
-            'no-unused-vars': [
-                'error',
-                {
-                    argsIgnorePattern: '^_',
-                    varsIgnorePattern: '^_',
-                    caughtErrorsIgnorePattern: '^_'
-                }
-            ],
-            'no-console': 'off',
-            'no-constant-condition': ['error', { checkLoops: false }],
-            'no-empty': ['error', { allowEmptyCatch: true }],
-            'no-useless-escape': 'warn',
+            'no-await-in-loop': 'error',
+            'no-div-regex': 'error',
+            strict: ['error', 'global'],
+            eqeqeq: 'error',
+            'dot-notation': 'error',
+            curly: 'error',
+            'no-unused-expressions': ['error', { allowShortCircuit: true }],
+            'no-unused-vars': ['error', { varsIgnorePattern: '^_', argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+            'handle-callback-err': 'error',
+            'no-new': 'error',
+            'new-cap': 'error',
+            'no-eval': 'error',
+            'no-invalid-this': 'error',
+            radix: ['error', 'always'],
+            'no-use-before-define': ['error', 'nofunc'],
+            'callback-return': ['error', ['callback', 'cb', 'done']],
+            'no-redeclare': 'error',
+            'block-scoped-var': 'error',
+            'no-sequences': 'error',
+            'no-throw-literal': 'error',
+            'no-useless-call': 'error',
+            'no-useless-concat': 'error',
+            'no-void': 'error',
+            yoda: 'error',
+            'no-var': 'error',
+            'no-bitwise': 'error',
+            'no-lonely-if': 'error',
+            'arrow-body-style': ['error', 'as-needed'],
+            'prefer-arrow-callback': 'error',
+            'object-shorthand': 'error',
+            'prefer-spread': 'error',
             'no-prototype-builtins': 'off'
         }
     },
     {
-        ignores: ['node_modules/**', 'coverage/**', '.git/**', '*.log', 'test-*.js', 'dist/**', 'build/**']
-    }
+        files: ['test/**'],
+        languageOptions: {
+            globals: { ...globals.node, ...globals.mocha }
+        }
+    },
+    // Repo-specific: overrides go here, each with a one-line reason
+    {
+        // Benchmarks time each iteration sequentially on purpose (9 violations, all in benchmark/)
+        files: ['benchmark/**'],
+        rules: { 'no-await-in-loop': 'off' }
+    },
+    prettier
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@postalsys/email-text-tools",
-    "version": "2.4.24",
+    "version": "2.4.26",
     "description": "Email text tools",
     "main": "index.js",
     "scripts": {
@@ -11,7 +11,8 @@
         "lint:fix": "eslint . --fix",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
+        "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
+        "test:cjs": "NODE_OPTIONS=--no-experimental-require-module npm test"
     },
     "repository": {
         "type": "git",
@@ -31,17 +32,21 @@
         "@eslint/js": "10.0.1",
         "eslint": "10.13.0",
         "eslint-config-prettier": "10.1.8",
+        "globals": "17.13.0",
         "prettier": "3.9.10"
     },
     "dependencies": {
-        "@postalsys/email-content": "0.1.15",
+        "@postalsys/email-content": "0.1.17",
         "dompurify": "3.4.17",
         "he": "1.2.0",
         "html-to-text": "10.0.1",
         "jsdom": "27.0.0",
         "juice": "11.1.1",
         "linkify-it": "5.0.2",
-        "node-html-parser": "9.0.4",
+        "node-html-parser": "9.0.5",
         "tlds": "1.261.0"
+    },
+    "overrides": {
+        "@asamuzakjp/css-color": "4.1.1"
     }
 }

package/.eslintrc

@@ -1,15 +0,0 @@
-{
-    "rules": {
-        "indent": 0,
-        "no-await-in-loop": 0,
-        "require-atomic-updates": 0
-    },
-    "globals": {
-        "BigInt": true
-    },
-    "extends": ["nodemailer", "prettier"],
-    "parserOptions": {
-        "ecmaVersion": 2018,
-        "sourceType": "script"
-    }
-}