v3.0.0: add settle/map/mapSettled and AbortSignal support

[Acro]

Expands the API to 3.0.0 while keeping the v2 surface: the default export and the parallel(jobs, limit) call shape are unchanged; everything new is additive. Follows up on #2 (merged).

New named exports

Function	Purpose
settle(jobs, limit?, options?)	Concurrency-limited Promise.allSettled — resolves to per-job { status, value | reason } in input order; never rejects because of a failing job
map(items, mapper, limit?, options?)	Map over data with (item, index) => value | Promise<value> instead of pre-built thunks; fail-fast, results in input order
mapSettled(items, mapper, limit?, options?)	Settle-all variant of map

parallel remains the default export and is also re-exported by name. Both CJS and ESM are first-class — an exports map routes each module system to the right entry, so import parallel from 'await-parallel-limit' works in bare Node ESM.

New options argument (3rd positional, { signal })

AbortSignal support across all four variants:

• An already-aborted signal rejects immediately, before any job starts.
• Aborting mid-run — including synchronously from inside a job during worker startup — rejects with the signal's reason (or a default AbortError for minimal signals without reason support) and stops scheduling new jobs.
• In-flight jobs run to completion (JS can't force-cancel them); their results are discarded and a late straggler rejection is absorbed rather than surfacing as an unhandled rejection.
• The abort listener is removed on completion and on abort — verified by listener add/remove counting in tests.

Hardened by two review passes + verification + bulletproofing

Review pass 1 fixed fail-fast semantics (a rejection now stops new jobs from starting) and made map/mapSettled reject on non-array input instead of throwing synchronously.

Review pass 2 (8-angle deep review, every finding independently verified) surfaced 10 findings, all fixed — highlights: a critical sync-abort hole (a job aborting the signal synchronously made all variants fulfill with a holey array — fixed via post-attach re-check + one unified stopped flag); sparse-array holes now reach the mapper as undefined; workers invoke the mapper/thunk directly (100k-item map: ~185ms → ~13ms, no O(N) thunk array); abort machinery simplified; engines raised to >=16.14; stub-signal tests pin the fallback AbortError and listener add/remove symmetry.

End-to-end verification at the package boundary (packed tarball → fresh consumer): full behavioral battery plus the typings floor pinned at TS ≥ 3.4 (verified with TS 3.4.5 and latest). Recipe persisted in .claude/skills/verify/SKILL.md.

Bulletproofing pass:

• Fixed an Infinity regression vs published 2.1.0 (v2 treated Infinity as unbounded; validation had silently degraded it to 5).
• Input-length snapshot — mutating the input array mid-run can't change the result set.
• Seeded differential fuzzer (test/fuzz.cjs): randomized variants/sizes/limits/failures/aborts vs a per-job reference model — 2,000 scenarios green under --unhandled-rejections=strict (500 per CI run).
• Exact-type regression tests (test/types.test.ts) — tuple inference and settle narrowing are now build-gated.
• CI: exact engines floor ('16.14') through 24.x; fuzz job; package-boundary job (tarball → consumer → smoke + TS 3.4.5/latest gates).
• README rewritten around explicit Guarantees.

Agent-friendly packaging

• ESM exports map + static wrapper (esm/index.mjs re-exports the CJS build — one implementation, no dual-package hazard). The previously documented bare-Node-ESM default-import trap is fixed, not just documented. Types route per condition (esm/index.d.mts / dist/index.d.ts); legacy TS resolvers use main/types, so the TS 3.4 floor holds (gated in CI, including a node16-resolution check).
• llms.txt ships in the npm tarball — complete API, semantics, recipes, and gotchas (thunks-not-promises, settle rejection rules, abort scope) in one context-window-sized file at node_modules/await-parallel-limit/llms.txt.
• AGENTS.md + CLAUDE.md — build/test/fuzz commands, architecture map, and frozen invariants for agents working on the repo.
• @example JSDoc on all four functions — flows into dist/index.d.ts for hover docs and d.ts-reading agents.
• Richer npm metadata — sharper description and expanded keywords (promise-pool, p-limit, allsettled, rate-limit, abortsignal, …).
• ESM boundary smoke (test/boundary/smoke.mjs) runs in CI beside the CJS smoke: asserts the default import is the function and drives the full surface.
• Provenance publish workflow (.github/workflows/publish.yml) — release-triggered npm publish --provenance via OIDC, guarded by a tag↔version check and the full gate (unit + type suite, 500 fuzz scenarios, CJS+ESM tarball smokes) before anything ships. Requires an NPM_TOKEN automation-token secret.

Internals

• One worker-pool core for all variants: sustained concurrency (sliding pool, not batches), index-ordered result writes, direct invoke(items[i], i) dispatch.
• AbortSignalLike and SettledResult are declared locally, so the package compiles without DOM/es2020 libs and stays zero-dependency.

Backward compatibility

• parallel(tasks, 30) (the exact @paperbits/core call shape) verified against published 2.1.0 head-to-head: happy path identical; error path rejects with the same error at the same point; Infinity parity restored.
• One deliberate divergence, disclosed in the README: after a fail-fast rejection, remaining not-yet-started jobs are abandoned instead of continuing in the background.
• Tuple return-type inference for as const job arrays preserved and regression-locked by test/types.test.ts.
• As a major bump, Paperbits' ^2.1.0 range will not auto-adopt 3.0.0 — they opt in by widening their range.

Testing

• npm test → 32/32 unit tests + exact-type gate, under --unhandled-rejections=strict.
• npm run fuzz → seeded differential fuzzing; 2,000 scenarios validated locally, 500 per CI run.
• CI package-boundary job → CJS + ESM tarball smoke tests + TS 3.4.5/latest/node16 typings gates.
• Release path re-runs the full gate before npm publish --provenance.
• Benchmarks: 100k-item map ~13–17ms. Tarball: 8 files (dist, esm, llms.txt, README, LICENSE, package.json).

🤖 Generated with Claude Code