fix: resolution bugs, typed tokens, faster resolve

[ivandotv]

Fixes a set of resolution bugs, adds typed tokens and a few container APIs, and cuts per-resolve allocations. Ships with three changesets (one major, one minor, one patch).

Fixes

• A SINGLETON/REQUEST binding whose class or factory produced undefined returned an internal sentinel symbol on the first resolve, then injected that symbol into every dependent afterwards.
• validate / validateSafe silently gave up: reaching a bind key that an earlier binding already listed as a dependency aborted the whole check, so validate did not throw and validateSafe returned undefined. Missing dependencies are now reported regardless of bind order, and optional ones are not reported at all.
• Resolving a parent-owned SINGLETON started a fresh request context. That split REQUEST scope into two instances within a single resolve call, ran postConstruct before the outer graph finished building, and hid circular references behind a stack overflow.
• setParent accepted a parent that formed a cycle, turning every lookup into infinite recursion. It now throws, and accepts undefined to detach.
• unbindAll ignored the lock when the container was empty.
• using container = new PumpIt() threw Container is locked at scope exit on a locked container. Throwing out of a disposal masks the original error behind a SuppressedError, so disposal now bypasses the lock. unbindAll still refuses a locked container.
• Circular reference errors report the full resolution path with bound class names instead of stringifying an internal wrapper function.

Features

• token<T>() — typed bind keys. resolve infers the result instead of being told, and bindings under the token are type checked. resolve also infers the instance type when a class is the key.
• tryResolve — returns undefined for an unbound key instead of throwing. A missing required dependency of a bound key still throws.
• getKeys — lists keys bound on the container, optionally walking the parent chain.
• replace bind option — rebind a key without unbinding first; the previous binding is unbound, disposing its cached singleton.
• Symbol.dispose support on resolved singletons (preferred over dispose), and on the container itself.
• Every thrown error is a PumpitError carrying a machine-readable code, exported as ERROR_CODE.

Performance

Bound values ~2.5x, cached singletons ~5x, a small transient graph ~2.4x — from allocating request-context maps lazily, parsing injection metadata once at bind time, and dropping the write-only transient cache plus the per-lookup wrapper object.

Breaking changes

• PumpitError is now the base class for every container error and its constructor takes an ErrorCode instead of ValidationError[]. Validation failures throw PumpitValidationError, which still carries result but whose message lists the unresolved keys instead of the literal string "Validation".
• validateSafe always returns a ValidationResult, never undefined.
• Injection metadata is read once at bind time, so registerInjections (or assigning inject / INJECT_KEY) must happen before bindClass / bindFactory. Later changes are no longer picked up.
• Optional dependencies are no longer reported by validate / validateSafe.
• resolve infers its return type for class and typed-token keys where it previously widened to unknown.

Tests

Adds container-api.test.ts, regressions.test.ts, and token.test.ts. The regression suite also pins behaviour nothing previously guarded — parent-owned singletons not reaching child-only deps, sibling sharing, throwing constructors/postConstruct leaving the container usable and retryable, replace scoping, and typed tokens as optional deps and through a child.

🤖 Generated with Claude Code