Repository navigation
Conversation
- run the spec/**/*.test.ts regression files again (lost in #280) - drop inline 'type' import modifiers so the typings parse on TypeScript < 4.5 - import 'util' instead of 'node:util' (Node < 14.18 compatibility) - use registered symbols (Symbol.for) so duplicate package copies interoperate - add a 'configure' context symbol (runtime support follows) - remove the unused src/api/Constants.ts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Replace the node/recorder model with an explicit SubstituteState per substitute (root or cached auto-substitute): append-only received-call records indexed by member, configured substitutions kept apart from them, an optional mimicked instance, and a cache of auto-substitutes keyed by (kind, member, arguments). Thin proxies translate operations onto it: real use, setup chains, assertion chains and a configure view. Existing specs updated where a fix-spec decision changes behaviour: - RecordedArguments.spec: argument matching is one-directional (D3) - received.spec (#18): a bare add(Arg.all()) is a setup, not a call (D3) - issues/178: received(3).subSection fails both ways, so it throws synchronously; an ambiguous case keeps the deferred report (D9) - clearReceivedCalls.spec: asserts behaviour instead of the removed recorder internals Recorder.spec and RecordsSet.spec are removed with the classes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Add one regression test per audit finding (named with its id) under spec/regression/fixes/, plus tests for the decisions that add or change behaviour (D2 auto-substitute caching, D5 configure, D9 deferral, D11 string assertion forms, D12 mimick, D13, D14, D16-D19) and for two copies of the package interoperating (G:RG-8). Engine changes found while testing: - every proxy target carries the printer, because util.inspect inspects the target of a proxy instead of calling its traps - only the call-site frame is captured per call, which halves the cost of a call (D19) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
After sub[mimick](instance), reading a member that the instance does not have now returns undefined, as on the instance itself. The substitute keeps an auto-substitute only where it needs one: the string received/didNotReceive forms, members with configured calls, and members configured through nested setups. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… spec output - Add an "exports" map with a generated native ES module entry (dist/index.mjs + dist/index.d.mts, written by packaging/build-esm.js), so `import Substitute from '@fluffy-spoon/substitute'` is the Substitute class under native ESM and TypeScript node16/nodenext/bundler. CommonJS, "main"/"types", package.json and deep imports of dist/ files keep working. - Build before packing (prepack), so npm pack / npm publish always ship a fresh dist/ (G:PK-3). - Compile the specs into dist-spec/ (npm run build:spec), so npm test never leaves dist/ in an unpublishable state (G:PK-3). - Sync package-lock.json to 2.0.1 (G:PK-4). - engines.node stays >=10: the packed build was smoke-tested on Node 10.0.0 to 26 (CommonJS) and 12.17.0+ (ESM); Node 8 lacks util.isDeepStrictEqual (G:PK-2). - publishConfig pins the npm registry; packaging/dist-tag.js computes the npm dist-tag for a release; better keywords; volta pin moves to Node 24. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…:test check - The pretest script (npm run install:local) packs the repository root like npm publish does and installs the tarball with --no-save; the runners import '@fluffy-spoon/substitute' instead of ../../../src (G:CI-2). - Strip NODE_TEST_* from the environment of the nested runners. A nested `node --test` inherited NODE_TEST_CONTEXT and exited 0 although its test failed, so the node:test check failed on Node 20.11+ (G:CI-2). - Accept the runners' reports for a synchronous failure as well as for an assertion thrown on process.nextTick, and match the exception name and message separately (ava and node:test print them apart). - Update the runners (ava 6.4, jest 30, mocha 12, vitest 5, tsx, ts-jest, TypeScript 5.9) so the checks run on Node 22, 24 and 26; mocha 10 failed to start on Node 26. This also removes the critical/high audit findings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…rs; fix publishing - Node CI: run on push and pull_request (and as a reusable workflow) on Node 22, 24 and 26 instead of 18/20/21, and run `npm run test:types --if-present`. - New compatibility job: the compatibility checks against the packed package (G:CI-2). - New minimum-node job: packs the package and smoke-tests it on MINIMUM_NODE_VERSION (10.0.0, = engines.node) and on 12.17.0 for the ES module entry (G:PK-2). - Publish: trigger on `published` releases, run the full CI workflow first, check that the release tag matches package.json, publish stable versions as `latest` and prereleases as `beta`, with provenance. - Remove the GitHub Packages job. GitHub Packages only accepts packages whose scope is the repository owner (@ffMathy), so it could never host @fluffy-spoon/substitute and failed every release (G:CI-1). - CodeQL: action v4, drop the obsolete HEAD^2 checkout, explicit permissions. Dependabot also watches compatibility-checks/. The bug report template asks for the module system and the test runner. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
packaging/package.test.js runs with `npm test`. It packs the repository like npm publish does (starting from a stale dist/), installs the tarball into a fresh consumer project and checks: - G:PK-3: the tarball has the entry points and no spec/stale output; the spec build goes to dist-spec/. - DOCS:ESM: the default import works under native ESM and in TypeScript (node10, node16, nodenext, bundler); require, deep imports and package.json still work. - G:PK-4: package-lock.json version = package.json version. - G:PK-2: engines.node = the version the minimum-node CI job tests. - G:CI-1 / CI:dist-tag: publishing only targets npm, tag logic. - G:CI-2: nested node --test runs report failures; CI runs the compatibility checks against the packed build. - CI:matrix: supported LTS lines and the type tests. CONTRIBUTING.md (linked from the README, previously a 404) documents install, build, test, test:types, the compatibility checks, CI and the release process. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- One rule for the setup methods (T:TY-2, G:RG-4): `.returns` / `.throws` / `.mimicks` / `.resolves` / `.rejects` are offered unless the value they are accessed on (property type or return type) has a member with that name; the symbol forms are always offered. Checks are non-distributive for the method types, so union return types keep a single `mimicks` (T:TY-1). - D11: `sub.received` / `sub.didNotReceive` are only offered when T has no public or private member named received, didNotReceive, returns, throws, resolves, rejects or mimicks; the symbol forms are always available, including on SubstituteOf<T> for a generic T (T:TY-3, G:RG-3, T:TY-14). - D12: `mimick` is symbol-only (`sub[mimick](instance)`) (T:TY-5). - D5: `sub[configure]()` returns a view whose members only expose the setup API. - Overloads: up to 8 overloads in one bivariant inference step (T:TY-11), zero-parameter overloads anywhere (T:TY-10), `(...args: unknown[])` (T:TY-13), positional signatures before the Arg.all() ones. - Optional members (T:TY-7), index signatures next to named members (T:TY-8), members returning `never` (T:TY-12), `then` typed `never` and `toJSON` without setup API (T:TY-16, D20). - Export SubstituteException from the index through a public interface, so the typings do not reach the internals or @types/node (G:RG-9). - overlap.spec.ts: use the string received/didNotReceive forms through `any`, since D11 no longer offers them in the typings for these types. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- spec-types/: fixtures type-checked by `npm run test:types` (strict, and spec-types/loose without strict), one file per finding; must-fail lines use `@ts-expect-error`. `npm test` runs them first. - spec-types/min-ts: `npm run test:types:min-ts` builds dist/ and type-checks a consumer of the built typings (resolved through package.json, without @types/node) with an old TypeScript installed by npx (default 3.6, the measured minimum; other versions as arguments). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
With the D9 engine change, the old scenario fails synchronously. Three calls followed by a property-style received(2) can only be reported on process.nextTick, so the runners are still checked for that path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Editors then show the documentation of received, didNotReceive, configure, mimick and the setup methods on hover. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
sub[returns](1) (and [throws], [resolves], [rejects], [mimicks]) on a root substitute, or on its configure() view, used to read a member keyed by the symbol and return an auto-substitute, so nothing was configured. It now throws a SubstituteException usage error that points to member/call setups and to sub[configure]() for a substitute returned by a configured call. The string names stay ordinary members (D11). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
A failing assertion on a member with hundreds of received calls produced a message with one or two lines per call. The listing now stops after 50 entries with "› … and N more", using the listing's own marker. The counts in the expectation line still cover every call. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The colour decision now follows Node's own policy more closely:
FORCE_COLOR still wins ('0'/'false' off, anything else on); otherwise a
non-empty NO_COLOR or NODE_DISABLE_COLORS, or TERM=dumb, turn colours off;
otherwise stdout must be a TTY. The decision is a pure function,
shouldUseColors(env, stdoutIsTTY), so it is tested without a real TTY.
The existing A:RT-14 test now also clears NODE_DISABLE_COLORS and TERM, so
its TTY case does not depend on the environment the tests run in.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Two hints, after the listing of received calls: - When a method assertion finds too few calls and the member was also read without being invoked: "@Substitute.m was read N time(s) without being called; reading a method does not count as calling it." The same hint is given when a member that was read and invoked fails a property-style check with a count above its calls. - When didNotReceive().m(...) fails on a member that was only read, for example passed as a callback (the A:RT-3 residual forced by D9): the hint explains that the assertion is decided when the member is read and that sub[clearReceivedCalls]() after the arrange step resets the reads. SubstituteException's mismatch description gains optional `explanation` (continues the expectation line) and `hints` (lines after the listing). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… method Amended D9: a property-style assertion such as `sub.received(2).m` on a member that has only ever been invoked is reported on process.nextTick when it is not invoked. Its message said "Expected to receive 2 property reads matching m, but received none." and nothing else. It now continues with "m was never read as a property; it was called 1 time as a method. To assert calls, invoke it: sub.received(2).m(...)", with the path of nested substitutes (sub.logger.received(2).info(...)). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…utated arguments
Resolving a call compared it against every literal substitution of the
member, and configuring one compared it against all earlier ones, so 8000
literal setups plus 8000 calls took about 4.6 s. All-literal substitutions
are now indexed per member by a stable fingerprint of their arguments:
primitives by value, functions, substitutes and symbols by identity, and an
object only as "an object", so the key never goes stale when an argument
object is mutated after the setup (literal arguments are compared as they
are when the call is made, D15). The deep-equal confirmation and the D4
precedence (most specific class, then most recent) are unchanged. The same
workload now takes about 0.17 s. Literal setups with object arguments still
compare against the setups with the same primitives in the same places.
The auto-substitute cache looked entries up by a structural fingerprint
only, which goes stale when an argument object is mutated: after
api.get(request).body.returns('ok') and request.headers = {...},
api.get(request).body was a new auto-substitute (D2). Entries are now also
found by the identity of the argument objects.
The ratio test 'the cost of a call does not grow' now takes the best of
three runs and compares 2000 with 32000 calls against a bound of 48x
(linear is about 16x, quadratic about 256x), so CPU load does not fail it.
New: 8000 literal setups plus 8000 matching calls in under 1 s (best of
three, directly and through configure()) and a growth check for them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Every example now compiles under strict TypeScript and does what the text says (the old snippets mostly failed to compile or crashed at runtime). - Fix the malformed badge HTML and the requirements: Node.js 10 for CommonJS, 12.17 for the ES module entry point, TypeScript 3.6. - Document importing (CommonJS, ES module default and named imports), sequences that repeat their last value, promises on properties, mimicks, the Arg.any type strings, Arg.all() for the rest of the arguments, the .not matchers, match order and precedence, configure(), partial mocks with [mimick](), auto-substitutes and nested members, received(count) validation, property checks, what counts as a call, clearReceivedCalls, SubstituteException, the assertions reported on process.nextTick, the name-conflict rules for TypeScript and JavaScript, the symbol API, special members, typing limitations and test runners. - Replace the Substitute.disableFor section, which described an API that no longer exists. - Link the migration guide, the changelog and CONTRIBUTING.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Covers npm latest moving from 1.208.0 to 2.x, the Node.js and TypeScript minimums, the removed APIs (Substitute.disableFor, clearSubstitute and ClearType, the string mimick(instance)) with their replacements, the symbol API and the name-conflict rules, and the behaviour changes: sequences repeating their last value, cached auto-substitutes and nested checks that really check, matcher calls being setups, match order, configure(), what counts as a call, checks never running setups, received(count) validation, matchers and messages. Also the ES module default import, the exports map and the moved deep import paths. Each section says which old versions it applies to; the "after" examples are checked like the README's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Keep a Changelog format. The 2.0.1 entry summarises the fixes, changes, additions and removals since 2.0.0-beta.4 in user terms; the beta entries are reconstructed from the git history. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
`npm run test:docs` builds the package, then spec-docs/check.js extracts every typescript and js code block from README.md, MIGRATION.md and CHANGELOG.md, type-checks the TypeScript ones under strict against the built package (resolved through package.json and its exports map, like an installed copy) and runs each block in its own Node.js process. Examples state what they do in comments that the check enforces: `// prints <output>` must print exactly that, and `// throws <Name>` must throw. Any other output, exception, uncaught exception or unhandled rejection fails the check. HTML comment directives share setup code between blocks (name=/uses=), mark ES modules, compile-only and skipped blocks, an expected uncaught exception, and an error message text that must match. Relative links and #anchors are checked too. spec-docs/self-test.js runs the check on fixtures/broken.md, whose blocks and links are broken on purpose, and fails unless each problem is reported. The whole run takes about 10 seconds. CI runs it in the test job. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tion (D10, D11) A call of the string `received` / `didNotReceive` with an Arg matcher among its arguments was always taken as a setup (D3) of a member with that name, so `sub.received(Arg.any()).add(1)` silently configured something and the "assertion" passed, and `sub.didNotReceive(Arg.any()).value = 1` threw "Property assignments cannot be configured". By D11 such a call followed by a member access or an assignment is the assertion API: received() now reports the invalid count (D10) and didNotReceive() asserts, ignoring its arguments as it does without matchers. Followed by a substitution method, and inside a configure() view, it is still a setup of the user's member. Found by porting engine A's D11 test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tion A failed `sub.received(1).isEnabled = false` listed the assignments under "All property or method calls to @Substitute.isEnabled received so far:". The listing of an assignment assertion only contains assignments, so it is now headed "All property assignments to ... received so far:". The other headings are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… setups Code under test that reads a member called returns (or throws, resolves, rejects, mimicks) on an unconfigured call result gets the setup method, so calling it reconfigures the substitute. Configuring the value first avoids that. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…objects is searched" (E9) An argument looks at 32,768 items and keys in all at most (not 4,096), so that an array of 1,000 objects with a few keys each is still searched completely, as the README says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…peScript version (T40, R4TD-2, R4V-1) The direct setups compile with TypeScript 4.8 and newer. With older versions the typings cannot avoid two limitations, now pinned and documented in the fixture header from cross-version harness runs (3.6 to 5.9 and 7.0): - 3.6 to 4.7: calls of optional methods and of `fn | undefined` members are not callable with a constrained type parameter (`sub.reset().returns()`); - 3.6 to 3.8: properties whose type includes null/undefined have no setup API, with a constrained type parameter and in an interface instantiated with any type parameter (`maybe?: T`, `orNull: T | null`). The configure view and the checks work on every version; the min-ts consumer now checks those workarounds with TypeScript 3.6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…neric code (T41, R4TD-3)
With `T extends { [key: string]: number; port: number }`, `sub.timeout.returns(5)`
and `sub[configure]().timeout.returns(5)` took no value: the setup API was computed
from `T[string]`, and TypeScript never lets a value be written to `T[string]` of a
type parameter. For keys that exist only through a string index signature, the
member is now computed by a conditional type over the members type, which
TypeScript resolves with the constraint when the member is used, so the setups
take the index signature's type (also for union-typed index signatures). Concrete
types are unchanged.
Checking a set of such a key (`sub.received().timeout = 5`) still does not compile
on any TypeScript version (TS2339: a write through an index signature of a generic
type); the fixture pins it with the workaround `(sub.received() as Settings).timeout = 5`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… exports (PK4-2) With vitest's server.deps.inline and deps.interopDefault: false, the default import of dist/index.js is an object with only some of the exports, and the namespace holds every named export plus that object as its default. The wrapper required default === Substitute and threw "could not read the exports" although the namespace was complete. The generated dist/index.mjs now accepts a view when every named export has the type it has at build time, ignoring the view's default, and exports the named export Substitute (the default export found at build time) as its default. The packaging test simulates the new shape and a namespace with undefined values; the compatibility checks run the inlined vitest exports test with deps.interopDefault: false too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…agerly (GenericKind comment) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…/ (PK4-4) packaging/package.test.js deleted dist/, wrote a stale dist/spec/Stale.spec.js and packed the working tree, so an interrupted npm test left no dist/ at all, although CONTRIBUTING says npm test never writes into dist/. The checks now copy the working tree (uncommitted changes included; without dist/, dist-spec/, .git, other dot-directories and node_modules/, which is linked instead) to a temporary directory, put the stale dist/ there and pack that copy. A new test compares a snapshot of the working tree's dist/ before and after packing. CONTRIBUTING describes the temporary copy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…d import (PK4-1) ES module code bundled into CommonJS output while the package stays external (Rollup format 'cjs', esbuild format 'cjs' with packages external, webpack with a commonjs external, a Vite SSR build with CommonJS output) require()s the package at run time, and its default import is module.exports, the exports object, not the Substitute class. compatibility-checks/test/bundlers.ts now bundles bundlers/named-entry.mjs (named import only) with each of them and checks that it works, checks Rollup's output.interop: 'auto' workaround for the default import, and checks that the caveat itself still holds, so the README and MIGRATION wording is updated when the tools change. A packaging test makes sure these checks stay in place. CONTRIBUTING describes them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…on return types (T39) The T39 call results took the position of the overload in the 8-slot expansion as a type argument. Identical overloads in several positions then gave distinct signature types, so their intersection no longer collapsed. For a rest parameter typed as a union of tuples (`log(...args: [string] | [string, number])`) every position is a union, and the combinations multiplied: type-checking such a substitute took minutes, and TypeScript 5.4 ran out of memory. The union of the variants' return types is now keyed by the overload's parameter list (as TypeScript matches signatures of a union of function types), so identical positions give identical types again. The T39 fixture now includes such a member, so a regression makes `npm run test:types` hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
E8 (R4-ADV-1): a method reference invoked by the code under test is a call made where it is invoked, decided by frames, not by this === proxy. E9 (R4-ADV-2): bounded cost per call for wide and shared arguments. E10 (R4-ADV-4): error-like objects hash as Node.js compares them. E11: one call-site capture per recorded operation; hot path back to round-3 speed. E12 (R4-ADV-3): compatibility checks pin each runner's behaviour around a deferred report. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
T39 (R4TD-1): members typed as a union of function types get the setup API again, with the union of the variants' return types. T40 (R4TD-2, R4V-1): optional and nullable members in generic code are pinned per TypeScript version, with the configure-view workaround. T41 (R4TD-3): keys that exist only through a constraint's string index signature can be configured in generic code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
P31 (PK4-2): the ES module entry decides completeness by the named exports, so vitest with deps.interopDefault: false works. P32 (PK4-4): the packaging checks pack a temporary copy of the repository and never write into the working tree's dist/. P33 (PK4-1): a compatibility case for CommonJS output with the package external and the named import. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes - Importing (PK4-1, PK4-3, PK4-2, P33): prefer the named import; document CommonJS output with the package external (Rollup/Vite 5-7 cjs for any source; esbuild, webpack, Rolldown, Vite 8 for .mjs/type:module sources; Rollup output.interop: 'auto') and ts-node's ESM loader; qualify "Bundlers give the same exports"; vitest deps.interopDefault: false is checked. - Which calls lead to a setup (E8): method references invoked with the substitute as `this` (Reflect.apply, fn.call, wrappers) are kept; builtins (Reflect.apply/call/apply/bind have no frame, Array.map does). Checked example. Stack-chain rule without the wrong version (R4TD-4). - How arguments are compared (E10): error-like objects with the Error tag, [object Object]-tagged errors, Node 24+ order dependence. Checked example. - Matchers inside objects (E9): shared containers searched once, 32,768 items and keys per argument, objects once wider than 1,024 keys remembered. - Assertions that fail later / Test runners (R4-ADV-3, E12): exact mocha (stops the run) and ava (ends the file's worker) behaviour, plus jest, vitest and node:test; drop "without crashing". - Typing limitations, "In TypeScript" and MIGRATION "TypeScript" (R4V-1, R4TD-2, R4TD-3, T39-T41): TS < 4.8 optional/nullable members in generic code, union constraints, index-signature set checks, rest parameters typed as tuple unions; T41 index-signature setups; T39 union return types. Checked examples. - Performance (E9, E11): re-measured on Node 22 against the build; 4,096 cap, identity-first lookup, remaining slow shapes (unreadable arguments, matcher setups inside objects about 9 s, which 6cb1c22 and ec64181 share). - CHANGELOG: T39 fix relative to 2.0.0-beta.4, T41, E8, E9, E12, PK4-2, CommonJS-output and ts-node note. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The R3-ADV-3 (E4) check compiled its TypeScript fixture into a new directory under os.tmpdir() and never removed it, so every npm test run left a substitute-source-map-* directory behind. withSourceMapProject now removes the directory in a finally block, also when the check fails, and a PK5-1 test pins that. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… Error.stackTraceLimit (R5V-3, E15) captureStack lowered Error.stackTraceLimit to 1 for every capture with a plain assignment, which throws in strict code when the property is read-only (also after Object.freeze(Error)) or an accessor without a setter, so every substitute operation failed with a TypeError. The assignment is now tried once per limit value: when it fails, or an accessor ignores it, the capture uses the current limit (more frames, same result) and the attempt is not repeated while the limit stays the same, so no exception is thrown on every operation. Nothing is restored when nothing was changed, and a limit that did not exist is deleted again instead of being left behind as an own property set to undefined. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…formatter is installed (R5-ADV-2, E16)
Since round 5 the frame of a record was read by a temporary
Error.prepareStackTrace that threw after looking at the call sites, so
that V8 kept the stack unformatted for its text. A debugger set to pause
on caught exceptions stopped there twice for every step of a chain (40
times in a six-line test).
When Error.prepareStackTrace holds a function (Node.js's own from 20.20
on, or an installed one such as source-map-support's), the temporary
formatter now returns a DeferredStack with the call sites instead of
throwing. The text is made from those call sites when a message needs it,
by the formatter in place then (or the one seen when the frame was read),
called as V8 calls it, so source maps and custom formatters still apply.
Without a formatter (Node.js before 20.20 with none installed) the
throwing read stays. The R5-ADV-2 test counts debugger pauses with
Debugger.setPauseOnExceptions('all'): none now.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…a wide object's keys once (R5V-1, R5-ADV-1, R5TD-2, E13) Round 5 hashed objects, Maps and Sets with more than 4,096 entries by their size alone, so distinct wide values of the same size all shared a bucket and every call was compared with every earlier one (5,000-key objects x 200 calls: 21 s), and it listed the keys of a wide object on every call even when the same object was passed again. - The shallow hash of a container with more than 256 entries is remembered by identity across calls (WeakMap). Mutating an argument after it was passed is not supported (amended D15/D35). - Every key and value of a wide object or Map counts again up to 65,536 entries; above that every key and an order-independent sample of about 256 values chosen by key hash. Large Sets count every member. Maps and Sets are iterated with their intrinsic forEach. - Families: listing the keys of a wide object costs most (10 ms for 70,000 keys). The first wide object (at least 1,025 string keys) that matches no family starts one, a fixed list of 1,025 of its keys (at most 16 families). An object whose own enumerable keys include all of a family's is hashed by those keys' values without listing its keys. Families are only added, so the family of an object never changes and equal objects always hash alike. A family hash leaves out the other keys, so when a bucket holds several candidates the lookups compare their refined hashes (computed without families) before live deep equality. The search for nested matchers skips family members too, as they have more keys than it searches. The E3 property test gets wide objects, Maps and Sets on both sides of 256, 1,025 and 65,536 entries (shared and copied, in shuffled order) and also checks the refined hashes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…E14) Every argument list with a value that cannot be read (a throwing getter, a revoked proxy) got the same FALLBACK_HASH, so each such call was compared with every earlier one, running the throwing getter each time: 4,000 calls took about 65 s. Such a value is now hashed by its identity, where it is found (nested values too), and remembered, so it is read only once. It is deep strictly equal to nothing but itself (Node.js throws when it compares it, which counts as no match), so results are the same as before: the same value, and a copy of a container that holds the same value, still match; another value does not, and is no longer compared at all. FALLBACK_HASH is left for an argument list that cannot be hashed at all. The round-3 and round-4 hashing tests asserted that such values hash to FALLBACK_HASH; they now assert the identity hash instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…s keys once per operation (R5V-1, R5-ADV-1, E13) The objects among the entries of a wide container (more than 256 keys or entries) all counted as one constant, so distinct Sets of objects, Maps with object keys and tables of records with the same keys still shared a hash, and each call was compared with every earlier one (100 calls with 5,000 records: 3.3 to 4.4 s, as at ec64181; 6cb1c22: 0.13 to 0.65 s). Each such entry is now hashed with a budget of four objects of its own (the fields of a record and one level below). Inside an entry a wide container counts as a constant, so that the remembered hash of a wide container does not depend on where it is found and the hash never goes from one wide container into the next (cycles end there). Sets with more than 65,536 members, and the object-keyed entries of such Maps, stay shallow. Also: - the search for nested matchers notes the keys of a wide object it lists, and the hash that follows in the same operation takes them, so a new wide object is listed once instead of twice (10 calls with distinct 65,536-key objects once every family is taken: 240 -> 150 ms); - families are looked up only for an object that has the first key of a recently matched family, or whose listed keys are enough for one, so small objects no longer pay for 16 families; the family an object belongs to is still decided over every family, in order; - objects with Object.prototype or a null prototype skip the checks for other kinds of objects; - one memo per wide container instead of three maps. The cliff test now runs both while families are free and once all are taken, a new test covers tables of records, and the E3 property test generator gets tables of records, Maps with object keys, Sets of records, tables of tables, cycles through wide containers, objects without a prototype and arguments objects, with a property test of its own for wide values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ed Error.stackTraceLimit without a failed assignment (R5-ADV-2, R5V-3, E16, E15) E16 kept a record's call sites in a wrapper with an array (about 100 bytes more per record whose frame is read: 1,645 instead of 1,236 bytes for app.a.b.c.d(i) on Node.js 22). The temporary formatter now returns the call site itself when there is one frame (as usual), and the wrapper only for several (E15); the text is still made by the formatter in place when it is needed, or by the one in place when call sites were last kept. A chain step now costs 1,357 bytes (Node.js 24: 1,343 against 1,174), and the text is identical to V8's own formatting on Node.js 18 to 26 with Node.js's formatter, source-map-support, a custom formatter and --enable-source-maps. E15 found out that Error.stackTraceLimit cannot be lowered by assigning it and catching the TypeError, once per value: a debugger set to pause on caught exceptions stopped there once. The property's descriptor is now looked at first (once per value of the limit). The R5-ADV-2 debugger test also covers a read-only, a getter-only and a frozen limit, and a new test checks that a capture whose frame was read formats exactly as one that was not, with several formatters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… differ (R5TD-1, T42)
A concrete union whose variants declare a same-named method with different
parameter lists (an extra optional parameter, other parameter types, other
required counts, overloads in one variant, a generic method) had no setup API
on calls of that method: SubstituteOf<T> intersects the member with each
variant's own function type, and TypeScript paired the substitute's signatures
with the variant's plain ones when calling the resulting union.
For a concrete union the member now carries one intersection of every
variant's signatures (identical in every variant, so they pair up with each
other); a member that is not a union, and generic code, keep the per-variant
expansion (T33). The call result takes the return types of the variants whose
overloads the call can reach: the overload with the same parameter list, or
else every overload whose argument counts overlap and whose parameter list
accepts the other's (or is accepted by it). A variant returning `any` makes the
result take anything, whichever signature the call resolves to.
The positional signatures are ordered by required argument count, most first:
TypeScript 5.3 and older pair a signature with the first signature of the other
variant that requires no more arguments, so `get()` before `get(key)` made
`get('k').returns()` take only what both return.
spec-types/R5TD-1.T42.union-variant-parameter-lists.ts covers the hunter's
cases (ClientV1|ClientV2, LogA|LogB, ReaderA|ReaderB and t39a.ts) with their
must-reject lines.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
spec-types/min-ts/consumer.ts (TypeScript 3.6 in CI) gets the union cases whose parameter lists differ, including a zero-argument overload before a one-argument one and methods that require different numbers of arguments, which TypeScript 5.3 and older paired wrongly before the signatures were ordered. spec-types/limitations.ts pins what stays imprecise for such unions: argument values are not considered (overlapping parameter types do not count), and a call that an earlier overload with optional parameters also accepts resolves to the later overload with more required parameters. Both are configured through the variant's type. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… (E13) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…every call (R5TD-2, E13) The search for nested matchers (D27) remembered only objects too wide to be searched (more than 1,024 keys). A table with 257 to 1,024 keys that every call passes was searched again on every call: 10,000 calls with one shared 1,000-key table took 860 ms (300 keys: 234 ms), while wider tables took 42 ms. A container with more than 256 items or keys that was searched in full (no bound left anything inside it out) and holds no matcher is now remembered as well, like its hash; 10,000 such calls take about 55 to 80 ms whatever the size of the table. A matcher put into such a container after it was passed is not seen: mutating an argument after it was passed is not supported (amended D15/D35). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…when its search leaves nested objects out (R5TD-2, E13) A table of 257 to 1,024 records whose records hold nested objects (users that share a role object) was searched for nested matchers on every call, as the budget of the search left the nested objects out, so the table could not be remembered as searched: 10,000 calls with one shared table of 600 such records took 1.6 to 1.8 s (also at ec64181 and 45facfb). Such a wide container is now searched once more without budgets, looking at everything a search could reach from it (each container once, 32 levels, 32,768 items at most); when that finds no matcher it is remembered as searched (72 ms for the 10,000 calls), otherwise it is not tried again and keeps the bounded search of every call (a matcher beyond the bounds is not recognised, as before). Within one search, a shared container that was searched in full no longer counts as left out where it is met again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…s (E13) Most of the time of this shape is Node.js's own deep equality, which confirms each copy (about 200 of its 250 ms). Under the full suite with other processes running it once took 1,069 ms on Node.js 24. As the round-4 performance tests do, it now takes the best of three runs, each with objects of its own; the limit stays 1 s. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The combined signatures of a concrete union member had one signature per
variant and overload, because each carried its variant's return type and its
parameter names (since TypeScript 4.0 a named tuple is told apart by the
declarations of its names). Calling the union then paired up all of them:
`u.self('x')` on a union of 20 variants with `self(x: string): this` took
10-16 s to check on TypeScript 4.0-4.5, and 60 variants about 5 s on 5.9.
The union signatures now take the parameter list without names (lists of up
to 6 parameters without a rest parameter) and compute their call result from
the parameter list and the whole member type only, so the same parameter list
in several variants is one signature. When every overload of every variant
returns the same type (or one returns `any`), that type is the call result
without looking at the parameters; this also lets `.returns()` take a type
parameter in generic code (`(() => T) | (() => string)` in a `Picker<T>`).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
E13 (R5V-1, R5-ADV-1, R5TD-2): distinct wide objects, Maps and Sets no longer share a hash. Wide containers hash every key and value up to 65,536 entries and an order-independent sample above that; the hash of a wide container is memoized by identity across calls, and a wide container searched in full without a matcher is not searched again. E14 (R5V-2): a value that cannot be read is matched by identity and read only once. E15 (R5V-3): a read-only, getter-only, frozen or deleted Error.stackTraceLimit no longer breaks the library and is left as it was. E16 (R5-ADV-2): when Error.prepareStackTrace holds a function, the first frame is read without throwing, and the text is produced lazily by that formatter. E17 (PK5-1): the source-map test removes its temporary directory. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
T42 (R5TD-1): a concrete union whose variants declare a same-named method with different parameter lists (an extra optional parameter, other parameter types or required-argument counts, overloads, a generic method in one variant) has the full setup API on calls of that method again. Setups accept the return types of the variants whose overloads the call can reach. The residual limits are pinned in spec-types/limitations.ts and in the TypeScript 3.6 consumer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes - Performance (R5V-1, R5TD-2, E13, E14): wide objects, Maps and Sets hash every key and value (records with a budget of 4 objects), a sample of the values above 65,536 entries, families of 1,025 keys for objects with the keys of an earlier one, and a hash remembered across calls. Every number re-measured on Node.js 22 against the build (best of 3): hot path, shared and distinct wide shapes, records, the 200 literal setups with copies (0.2 s of 0.25 s is isDeepStrictEqual), colliding strings and symbols, unreadable values (about 50 to 70 ms for 4,000), matcher setups (0.8 s / 7.5 s) and memory (1,350 bytes per chain call). - How arguments are compared (E13, E14): unreadable values are equal only to themselves; a wide container keeps the hash of its first use, so a copy does not match a setup made after it changed, and a matcher put into it later is not recognised. Checked examples. - Matchers inside objects (E13): containers with more than 256 items or keys without a matcher are searched only the first time. - Error.stackTraceLimit (R5V-3, E15): read-only, accessor, missing and frozen limits work and are left as they were; accessors give no "called at" lines. Checked example with Object.freeze(Error). - "called at" text (E16): the formatter in place when the message is made, or the last one seen for reads in a chain. - Debuggers (R5-ADV-2, E16): no stops when Error.prepareStackTrace is a function (Node.js 20.20+, source-map-support, jest 29, vitest forks and threads); 40 stops for a 6-line test otherwise (Node.js 18, deleted formatter, vm contexts: jest 30, vitest vm pools), with the skipFiles hint. - Typing limitations, MIGRATION "TypeScript" and CHANGELOG (R5TD-1, T42): methods whose parameter lists differ between union variants have the setup API; exact rule, the two pinned limitations with casts, and unnamed parameters in editor hints. Checked example. - CHANGELOG: entries framed against 2.0.0-beta.4 (union methods with differing parameter lists, debugger stops as a change, tables passed with every call, stackTraceLimit shapes). - CONTRIBUTING: what a test run leaves in the temporary directory. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR fixes the problems found in an audit of the unreleased 2.0.1 on
master, before it is published. It covers the runtime engine, the typings, packaging/CI and the docs.CHANGELOG.mdlists every user-visible change, andMIGRATION.mdexplains how to upgrade from 1.x and from the betas.The work went through several rounds. Each round fixed the open findings, then re-ran every earlier repro and started fresh adversarial reviews on Node.js 22, 24 and 26. The last review round is still running. Any further fix will come as a new commit here, so the PR stays a draft until then.
What changed
Engine (
src/internals/, rewritten around per-substitute state)Arg.all()), and among setups of the same kind the most recent one wins..call/.apply/.bindorReflect.applyis recorded.app.logger.received().info('hi')) work. Root setups no longer leak into them.sub[configure](),sub[mimick](instance),sub[clearReceivedCalls](), matchers nested inside objects and arrays,Arg.all()after leading arguments, and an exportedSubstituteException.Error.stackTraceLimit = 0, with a read-only or frozenError, with customError.prepareStackTraceformatters (stack-chain, source-map-support), and with fake timers that fakequeueMicrotaskandnextTick.Symbol.iterator,Symbol.hasInstance,then,util.promisify.custom,util.inspect.customand jest's asymmetric-matcher check behave sensibly instead of answering with a substitute.Typings
<T extends Calc>(sub: SubstituteOf<T>));Arg.any('undefined');.mimicks()on union and boolean returns;.not.npm run test:types, plus a TypeScript 3.6 minimum check in CI. The remaining limitations on old TypeScript versions are documented with workarounds in the README's "Typing limitations".Packaging and CI
exportsmap and an ES module entry that shares one copy of the library with CommonJS, so the default import works under native ESM. It is checked with Node and with Rollup/Vite/webpack/esbuild/Rolldown bundles.prepackbuild,enginesverified down to Node 10, and the CI matrix on Node 22/24/26 plus minimum-Node and TypeScript 3.6 jobs.latest/betadist-tag and provenance, and runs after CI. The GitHub Packages job, which could not publish the@fluffy-spoonscope, is removed.Docs
npm run test:docs, 81 blocks).MIGRATION.md,CHANGELOG.md(closes Update documentation #234) andCONTRIBUTING.md.Verification at
74b8588npm testpasses 277 tests on Node 22, 24 and 26.test:types, the TypeScript 3.6 check andtest:docspass.Worth a look before merging
Error.prepareStackTraceis not a function: Node < 20.20 without a formatter, jest 30, and vitestvm*pools. The README gives theskipFilesworkaround.@rollup/plugin-commonjswith the package external, and bundles that emit CommonJS, need the named import or a documented setting. The README and MIGRATION spell this out.Before publishing
NPM_PUBLISH_TOKENmust be a valid granular npm token, or trusted publishing must be configured for the package.v2.0.1GitHub release makes 2.x the npmlatest. Until now,latestis 1.208.0.🤖 Generated with Claude Code
https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt