Compatibility Contract — @stackline/proxyquire

Versioned project notes for @stackline/proxyquire 1.0.5. Original attribution is retained in the linked repository.

Compatibility Contract

The 1.x line preserves the observable [email protected] CommonJS contract unless a narrow change is required to prevent loader corruption, unsafe key handling, or retention of temporary module records.

Preserved

• callable proxyquire(request, stubs) and equivalent .load(request, stubs);
• a fresh load of the CommonJS subject for each Proxyquire call;
• subjects resolved from the module that created the Proxyquire instance;
• stub keys matched as the subject or its dependencies pass them to require();
• call-through by default for properties omitted from object/function stubs;
• .noCallThru() and .callThru() instance controls;
• per-stub @noCallThru overrides;
• .noPreserveCache() and .preserveCache() controls;
• @global initialization-time and @runtimeGlobal runtime overrides;
• null stubs that produce a Node-shaped MODULE_NOT_FOUND error;
• function, array, primitive, and other non-plain-object stubs;
• errors thrown by the subject or dependency escaping synchronously and by identity;
• compatibility with any test or spy framework;
• .compat() remaining present and rejecting the removed 0.3 compatibility mode with the historical guidance;
• the enumerable callable-export method shape, including historical bound runtime methods used by advanced consumers;
• published CommonJS root, index, package metadata, and runtime deep imports.

Cache semantics

preserveCache() is enabled by default. Before loading, Proxyquire temporarily removes the subject's current cache entry. After loading, it restores exactly the entry that existed before the call, or restores absence when none existed. The newly proxyquired result is therefore not installed as a lasting cache replacement, and separate Proxyquire calls are not promised to return the same object identity.

noPreserveCache() leaves the subject and explicitly named, resolved stub modules absent from the cache after the call. It does not recursively evict unstubbed transitive dependencies. Global stubs temporarily bypass the broader CommonJS cache so the transitive request can be observed; module initialization may consequently run again.

Additive

• createProxyquire(from) anchors an independent instance to an ESM or native-TypeScript test module using an absolute filename or file: URL;
• .from(from) is an alias of createProxyquire(from);
• default and named ESM package entry points for configuring CommonJS loads;
• first-party declarations compatible with TypeScript 3.9 and current versions;
• explicit package exports and npm-alias installation.

Resolution boundary

The package uses an internal lexical CommonJS resolver and has no runtime, optional, or peer dependencies. It intentionally avoids native canonical resolution because canonical paths collapse distinct symlink and package-export alias requests. Differential tests keep those request identities independently stubbable, matching [email protected]. Resolution covers built-ins, relative and absolute files, configured extensions, directory indexes, package main, deep package requests, ancestor node_modules, and Node global module paths.

Intentional corrections

• An unanchored ESM use fails with guidance to call createProxyquire() instead of crashing while reading an undefined CommonJS parent.
• Temporary loads detach only the exact transient module records they added to the caller's children collection. Existing and unrelated children remain.
• Extension handlers are restored only when the Stackline wrapper is still the active handler; a later loader is never overwritten.
• @global and @runtimeGlobal state is scoped to the active load and restored safely across nested calls instead of leaking into later ordinary loads.
• Stub lookup and special-property checks use own keys and prototype-safe maps.

Outside the contract

• interception of native ESM static or dynamic imports;
• browser module mocking;
• recursive eviction of every transitive dependency;
• cross-process, worker, or VM-context mocking;
• asynchronous mocking or an experimental Node loader;
• sandboxing, code trust, or authorization boundaries.

Package reference