@codefast/di 0.5.0-canary.6 → 0.5.0-canary.8

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # @codefast/di
 
+## 0.5.0-canary.8
+
+### Minor Changes
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`0093b99`](https://github.com/codefastlabs/codefast/commit/0093b99ed711ad037b0e98e7343dee89786d328b) Thanks [@thevuong](https://github.com/thevuong)! - Build a container's rarely-used collaborators on first use instead of in its constructor: the inspector, the module ref/binding tables, the scope's in-flight and scoped caches, the registry's named and tagged slot indexes, and the class introspector's metadata caches. A container that only binds and resolves — the common case, and every per-request child container — no longer allocates eleven `Map`s it never reads.
+
+  A fresh `Container.create()` retains 2.7 KB instead of 4.8 KB (**43% lighter**), and `parent.createChild()` the same, measured by retention against a forced collection. Every deferred collaborator behaves identically whether or not something touched it first, which `tests/unit/container/deferred-subsystems.test.ts` pins by exercising each one as the first thing a fresh container does.
+
+  It is a throughput win too, on the paths that actually build containers: `Container.create()` is **1.80×** faster (230 ns → 127 ns) and a per-request child container plus a resolve through it — `createChild()` + resolve, the shape a web app runs once per request — is **1.31×** faster. Measured by an interleaved A/B with both builds loaded into one process, 13 trials in alternating order, against a control scenario that resolves from a pre-built container and so cannot benefit; the control sat at 0.997–1.009, and median and best-of agreed on both figures.
+
+  **Breaking:** `ScopeManager.getAllScoped()` is removed from the `./resolution/scope` subpath. Deferring the scoped cache raised the question of what a bulk reader returns when the cache was never allocated, and this reader had no callers anywhere in the package — so it is gone rather than carrying an empty-map fallback for nobody. `getAllSingletons()` is unaffected; its cache is still eager.
+
+  What it does **not** do is close the `realistic-graph-cold-resolve` loss against tsyringe, and the arithmetic says why: 103 ns off container construction is 2.5% of that row's 4.06 µs iteration, so the row moves ~1.5% — measured, and inside the noise floor. That row's gap is GC-attributable (the two libraries are at mutator parity; di only loses once a forced collection is in the loop), so a 13.7% allocation cut was never going to carry it.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`de80bad`](https://github.com/codefastlabs/codefast/commit/de80bad63f14afda1bd64a6d247852b24aac8e16) Thanks [@thevuong](https://github.com/thevuong)! - Publish an intentional export surface: 13 subpaths instead of 36. The engine's collaborators — `resolution/*`, `registry`, `container/*`, `binding`, `constructor-type`, and the `metadata` internals — are no longer entry points. They carry the invariants documented in ARCHITECTURE.md, and publishing them meant every internal refactor was technically a breaking change. Everything a consumer needs stays reachable from the root export, which already re-exports the builder interfaces, `Constructor`, `MetadataReader`, `effectiveBindingScope`, and the resolve-options helpers.
+
+  **This also repairs a silent break.** The surface was generated from `dist/`, so reorganising `src/` into `container/`, `resolution/` and `introspection/` renamed twelve already-published entry points — `./inspector` → `./introspection/inspector`, `./dependency-graph` → `./introspection/dependency-graph`, `./graph-adapters/*` → `./introspection/graph-adapters/*`, `./container` → `./container/container`, and the whole flat `./resolver`/`./scope`/`./lifecycle`/`./environment`/`./constraints`/`./binding-select`/`./binding-scope`/`./resolve-options` set — with no changeset saying so. The consumer-facing ones (`./inspector`, `./dependency-graph`, `./graph-adapters/*`) are back at the specifiers they shipped under; `examples/tanstack-start` imports two of them and would have broken on its next upgrade.
+
+  **Breaking:** the internal subpaths listed above are gone. Import from the package root instead.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`4ba70d1`](https://github.com/codefastlabs/codefast/commit/4ba70d1724e19580ee93ee392e413c23e669f310) Thanks [@thevuong](https://github.com/thevuong)! - Keep a singleton's instance on its binding instead of in a per-container table. A binding belongs to exactly one container, so its singleton slot is per-binding — which turns every cached-singleton read from a keyed `Map` lookup into a field read, on the most common resolve shape there is. The scope manager keeps only a lazily-created list of the bindings that have materialized, so disposal and `inspect()` can still enumerate them, and the singleton `Map` is gone entirely.
+
+  In the suite, `realistic-graph-resolve-root` — a transient controller over eight cached singletons — went from 10.66M to **12.19M** hz/op, and the `realistic` group geomean from 2.24× to **2.54×** of InversifyJS. That row carries a 2.9% IQR, so it is one of the numbers here worth reading precisely. `singleton-class-1-dep` and cold container build both moved up as well, on rows whose IQR is too wide to attribute confidently.
+
+  An interleaved A/B against the previous build, both in one process with a control that cannot benefit, put the same row between 1.09× and 1.40× across four runs — never slower, median and best-of agreeing inside each run, but with a spread that depends on what else the process had run. The suite's figure is the one to cite; the A/B established the direction. A trap worth recording: the control first read 0.88×, which was an artifact of timing an 11 ns call one at a time — batched the way the harness does it, the same control reads 1.02× with a 4% spread.
+
+  **Breaking:** `ScopeManager`'s singleton API takes a `Binding` rather than a `BindingIdentifier`, and `hasSingleton`/`getSingleton`/`peekSingleton`/`setSingleton(id, …)`/`getAllSingletons` are replaced by `setSingleton(binding, …)`, `deleteSingleton(binding)` and `cachedSingletons()`. The `SINGLETON_MISS` sentinel is gone; `NO_INSTANCE` on the binding replaces it. None of this is a published entry point any more, so it is internal — but a fork reaching into `./resolution/scope` would notice. `InstantiationPlanDependencyEntry` also drops its `ownerScope` field, which a compiled thunk no longer needs.
+
+### Patch Changes
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`d27b76f`](https://github.com/codefastlabs/codefast/commit/d27b76fb14200ae5226ec2a05b77d44ab91b016c) Thanks [@thevuong](https://github.com/thevuong)! - Thread an async chain's resolution context through the call and pool it, instead of parking chain identity on the resolver. `ctx.resolveAsync()` now hands the callee the context it used, so an inner level reuses it when the owner matches — which removes the resolver's path-identity heuristic, its shared settle callback and its active-level counter, and makes two concurrent chains correct by construction rather than by a fallback branch.
+
+  The contexts are pooled, and that is load-bearing rather than an allocation micro-optimization: a per-chain context survives its chain's microtask hops, so under a collecting profile a freshly allocated one is promoted out of the nursery and then collected the expensive way. An ablation that allocated per chain cost **2.5×** on `dynamic-async-chain-8` under a forced GC every 100 samples, which is the reason for the shape.
+
+  It does **not** close that row. An earlier draft of this changeset claimed it went from 0.98× to 1.18× of InversifyJS; that figure came from a probe running both library builds in one process, which this harness's README warns is worth ~30% on async chains, and from a 3-trial suite run on a loaded machine. At 5 trials on a quiet machine the row is **0.87×** with a 0.6% / 0.3% IQR — among the tightest numbers in the suite. The mechanism above is real; the win over inversify was not.
+
+  A competing hypothesis was tested and rejected: a forced full GC costs the two libraries the same (1.35 ms / 9.76 MB live for di, 1.41 ms / 9.89 MB for inversify), so the cost was never the collection but what di re-established afterwards.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`864d213`](https://github.com/codefastlabs/codefast/commit/864d213a4253346dae5799ebba06fc2726e933d2) Thanks [@thevuong](https://github.com/thevuong)! - Fold the fluent chain's registry committer into the chain itself. `bind()` now allocates a `BindingEntry` that carries only the `to*()` calls, and `to*()` a `BindingChain` that commits to the registry directly — one object per bind less than the entry/chain/committer trio, and one `Map` lookup less per binding registered by a module.
+
+  The two classes now share a `BindingRegistration` describing where the chain registers, built once per container rather than once per `bind()`. Threading that instead of a loose `(registry, moduleBindingIds, moduleRef)` triple makes the module invariant type-enforced — the id list is present exactly when the chain belongs to a module load — which removes both non-null assertions from the commit path, and drops the constructors from 4 and 5 positional parameters to 2 and 3.
+
+  `BindingCommitter` is gone and `BindingEntry`'s constructor now takes `(token, registration)`. Neither is a published entry point any more, so this is internal.
+
+  This is a simplification, **not** a throughput win: removing only the committer measured no change above noise. The chain stays two objects because `tests/unit/container/bind-to-builder-order.test.ts` requires `bind()`'s result to lack `when*()` at runtime — that is the test's own guarantee, stricter than SPEC §2.4, which only claims compiler enforcement. The measured ceiling for removing every builder object is ~19% on `realistic-graph-cold-resolve` under a forced GC — recorded in ARCHITECTURE so the lead is not re-tried blind.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`d27b76f`](https://github.com/codefastlabs/codefast/commit/d27b76fb14200ae5226ec2a05b77d44ab91b016c) Thanks [@thevuong](https://github.com/thevuong)! - Compile instantiation plans around dependencies the compiler cannot see through, instead of refusing to compile the graph at all. A factory, a scoped binding, an activation hook, a class past the depth limit, or a multi/optional/named parameter now compiles to an _escape_ — a re-entry into the runtime resolver seeded with exactly the ancestors the interpreted path would have pushed at that point, dispatched through exactly the resolve the interpreter would have called. Cycle detection, constraint contexts and error paths are therefore identical to never having compiled, and only the opaque dependency pays the runtime price while its siblings and ancestors stay compiled.
+
+  Previously a single `toDynamic` dependency anywhere in a class graph dropped the whole graph to the interpreted path — a 13.9× cliff on a shape applications write constantly (a factory-provided config injected into a class tree). That graph is now ~2× faster, and the first-materialization path of a singleton dependency inside a plan gained cycle detection it did not have.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`d27b76f`](https://github.com/codefastlabs/codefast/commit/d27b76fb14200ae5226ec2a05b77d44ab91b016c) Thanks [@thevuong](https://github.com/thevuong)! - Split the resolver's self-contained caches into named collaborators — `BindingLookupCache` (the chain-versioned options-less lookup memo), `ClassIntrospector` (per-class metadata, `@postConstruct` discovery, accessor injection, instantiation) and `ActivationNeedCache` (per-binding activation need, versioned on the lifecycle manager). The engine class keeps the sync and async pipelines, which genuinely need the same private state on every hop, and `ARCHITECTURE.md` now records the layering, the invariants each hot path depends on, and the rule that separates a legitimate threshold (choosing an implementation) from the kind that was removed (choosing a semantics).
+
+  New subpaths `@codefast/di/resolution/{activation-need,binding-lookup-cache,class-introspector}`; `@codefast/di/resolution/class-plan` is now `@codefast/di/resolution/instantiation-plan`, correcting an export map that had been stale since the module was renamed.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`a720c62`](https://github.com/codefastlabs/codefast/commit/a720c6297d041ffd2d0bba2e6146af894007a367) Thanks [@thevuong](https://github.com/thevuong)! - Collapse the fluent binding chain into one object. A single `BindingChain` is now the `BindToBuilder` that `bind()` returns and the kind-specific builder that `to*()` returns, so a `bind()` allocates one builder instead of two.
+
+  The `to*()`-before-`when*()` ordering stays enforced, as a type-level guarantee — which is what SPEC §2.4 actually claims. `bind()` is typed `BindToBuilder`, so a refinement before `to*()` does not compile; `tests/types/container-api.test.ts` pins that. For a caller without types, or one who casts past them, every refinement now throws the new **`ChainNotRegisteredError`** naming the token and pointing at `to*()`, rather than silently doing nothing. `whenDefault()` asserts registration for that reason alone, since it otherwise has nothing to do.
+
+  The previous revision kept two objects because a unit test asserted the refinement methods were _absent from the object_ `bind()` returns — a stricter reading than the spec, and one that pinned an implementation detail. That test now asserts the contract instead: every refinement throws before `to*()`, nothing is registered when it does, and the chain still works normally afterwards.
+
+  This is an API simplification, **not** a throughput win: going from four builder objects per bind to three measured no change above noise, and a fluent API cannot go below one, so the ~19% ceiling recorded in ARCHITECTURE for removing all of them is unreachable rather than pending.
+
+- [#646](https://github.com/codefastlabs/codefast/pull/646) [`1241f82`](https://github.com/codefastlabs/codefast/commit/1241f82bdb40613667c781111f2ce20409ddfd89) Thanks [@thevuong](https://github.com/thevuong)! - Register a fluent binding chain once instead of once per refinement. `bind(T).toDynamic(f).singleton()` used to insert a binding, remove it, and insert a replacement — two registry mutations, two version bumps, and a full index churn per binding. The chain now registers on its `to*()` call and refines that same registered object in place; only `when*()` re-slots, and it re-registers under the chain's original id, so `id()` stays valid for the whole chain instead of the intermediate ids being dead. Binding construction also funnels through a single `createBinding()` literal, which is what guarantees the one V8 hidden class the resolver's hot property reads depend on — so the registry stores what it is handed rather than re-copying it.
+
+  Cold container build (build, bind 10 nodes, resolve the root) went from the suite's only loss to a win against every competitor: 0.76× → 3.0× of InversifyJS, 0.43× → 1.9× of Awilix, 0.22× → 1.07× of tsyringe.
+
+  The builder's `CommitFn` type is replaced by a `BindingCommitter` interface (`commit` plus `refine`, the latter for in-place refinements the registry indexes do not care about), and `createBinding` / `refinableFields` are new exports from `@codefast/di/binding`.
+
+## 0.5.0-canary.7
+
+### Minor Changes
+
+- [`ad11507`](https://github.com/codefastlabs/codefast/commit/ad115077e23eaed845abd1f093f32d57f2445a36) Thanks [@thevuong](https://github.com/thevuong)! - Reorganize the source tree into subsystem folders — `container/` (container + the extracted fluent binding builders), `resolution/` (resolver, scope, lifecycle, environment, selection/constraints, and the extracted cycle-guard module), and `introspection/` (inspector, dependency graph, and the graph adapters). The root entry keeps exporting everything and now also exports the graph adapters (`toDotGraph`, `toCytoscapeGraph`, `toReactFlowGraph` and their types), so `import { toReactFlowGraph } from "@codefast/di"` is the preferred path.
+
+  Breaking (0.x minor): the `@codefast/di/graph-adapters/*` subpaths are removed — import the adapters from the root entry or from `@codefast/di/introspection/graph-adapters/*`. Deep subpaths of other moved modules follow the new folders (e.g. `@codefast/di/resolver` → `@codefast/di/resolution/resolver`).
+
+- [`6a25788`](https://github.com/codefastlabs/codefast/commit/6a25788320c73074c3ae0bb06cf7a70b7800c953) Thanks [@thevuong](https://github.com/thevuong)! - Resolver performance overhaul — the head-to-head benchmark vs InversifyJS 8 now shows 38/38 comparable scenarios won (median 1.82×, isolated mode), up from 7 losing rows. Four techniques, no public-API changes:
+
+  - **Chain-versioned lookup memo** — `BindingRegistry` gains a monotonic mutation version; resolvers memoize options-less `token → {binding, owner}` lookups across the parent chain with alias hops folded to the terminal binding. Resolving a root binding from a depth-2 child (or through `toAlias`) is now as fast as resolving it locally.
+  - **Compiled resolution plans** — a transient class binding whose dependency subgraph is pure static (class/constant/cached-singleton deps, no activation hooks or `postConstruct`) compiles once into a nested-constructor closure, cycle-checked at compile time. Anything dynamic keeps the runtime cycle guard, so error semantics are unchanged.
+  - **Uniform binding hidden class** — `Registry.add` rebuilds every binding with one fixed field superset so mixed binding kinds no longer turn the resolver's hot property reads megamorphic (~30% throughput loss in processes exercising several kinds).
+  - **Leaner async transient path** — cleanup runs as a FIFO side listener on the factory promise instead of a derived-promise chain (one less promise and one less microtask hop per level), and activated transient dynamic bindings get a dedicated lane that fetches container hooks once. Behavior note: an unawaited _failing_ `resolveAsync` no longer surfaces as an `unhandledRejection`; await (or `.catch`) the returned promise.
+
+- [#643](https://github.com/codefastlabs/codefast/pull/643) [`14c3a98`](https://github.com/codefastlabs/codefast/commit/14c3a98a98ae6221df447a94afe14b2e4a147c90) Thanks [@thevuong](https://github.com/thevuong)! - `container.validate()` now reports a captive dependency when a singleton depends on a **transient or scoped `toDynamic` / `toDynamicAsync` binding**. Previously any dynamic terminal was classified opaque and its declared scope went unchecked, so the most common form of the bug — a singleton capturing one instance of something bound transient — passed validation silently.
+
+  A factory's _body_ remains opaque: `validate()` still does not descend into it, so whatever the factory resolves internally is not reported. Only the declared scope of the dependency edge is judged, which is the part the container actually knows.
+
+  **Breaking:** a container that wires a singleton to a transient or scoped dynamic binding now throws `ScopeViolationError` from `validate()` where it previously passed. Either widen the dependency's scope, or inject a factory instead of the value if a fresh instance per use is intended.
+
+### Patch Changes
+
+- [`2def688`](https://github.com/codefastlabs/codefast/commit/2def688e305eebe7e14af4ae163beec13582aad5) Thanks [@thevuong](https://github.com/thevuong)! - Fix a crash on cyclic aliases: `bind(a).toAlias(b)` + `bind(b).toAlias(a)` previously recursed until `RangeError: Maximum call stack size exceeded` on both `resolve` and `resolveAsync`. Alias following is now an iterative loop with exact revisit detection — a genuine cycle throws `CircularDependencyError` naming the alias chain, and legitimately long alias chains resolve with no arbitrary hop cap.
+
+  Also splits the magic `32` that served two unrelated roles: the transient-dynamic fast lanes keep their own `DEEP_LANE_THRESHOLD = 32` (a shared-context/pool design point), while the cycle-scan Set attachment moves to a measured `RESOLUTION_SET_THRESHOLD = 128` — benchmarking showed `Array.includes` beats the Set's has/add/delete churn up to at least depth 96, so mid-depth graphs now skip the Set entirely.
+
+- [`19199af`](https://github.com/codefastlabs/codefast/commit/19199af174d8971081d1849a36fd9df05c8541ae) Thanks [@thevuong](https://github.com/thevuong)! - Fix binding-registration order sensitivity: the fluent builder chain commits eagerly, so `bind(x).toDynamic(f).when(p)` (or `.whenNamed(...)` / `.whenTagged(...)`) momentarily registered a default-slot binding whose last-wins commit silently displaced an existing default binding of the same token — and the displaced binding was never restored once the chain narrowed to a predicate or a named/tagged slot. Registering a default binding before a constrained one on the same token therefore lost the default. The commit chain now remembers what an intermediate commit displaced and restores it when the chain settles on a non-conflicting shape; a chain that genuinely ends on the same default slot still replaces the previous default (last-wins unchanged).
+
+  Binding selection also gains a most-specific-wins rule: when both a default binding and exactly one predicate-carrying binding match, the predicate wins (it is a deliberate specialization) instead of throwing `AmbiguousBindingError` — so "default plus `when(...)` override" now works as naturally intended. Two matching predicates remain ambiguous and still throw.
+
+- [#643](https://github.com/codefastlabs/codefast/pull/643) [`14c3a98`](https://github.com/codefastlabs/codefast/commit/14c3a98a98ae6221df447a94afe14b2e4a147c90) Thanks [@thevuong](https://github.com/thevuong)! - Unify sync transient-dynamic cycle detection on a per-binding `inFlight` flag, replacing the shallow lane's `O(depth)` `resolutionPath.includes()` scan and the deep lane's `Map` of generation marks. Sync resolution runs on a single call stack, so a binding marked on factory-enter and cleared on factory-exit is exactly path membership — detection becomes an `O(1)` field read with no hashing, no string scan, and no side table to allocate or grow. The async lane keeps its own per-path check, since async chains can interleave.
+
+  Transient-dynamic chains that previously lost now win across the whole depth range (a 32-deep chain went from ~0.55× to ~1.8× of InversifyJS), deep chains widen their lead, and cold container builds get cheaper because there is no per-resolver cycle-tracking structure to allocate. It also fixes a latent correctness bug: because the deep lane now clears a binding's mark when its factory returns, a deep (past-threshold) transient dependency resolved twice via separate sub-branches (a diamond, not a cycle) no longer throws a false `CircularDependencyError`.
+
+- [`f9aeeb0`](https://github.com/codefastlabs/codefast/commit/f9aeeb04a271877e47a7fbbfc6d62ae0fe1ad955) Thanks [@thevuong](https://github.com/thevuong)! - Extend the compiled-plan and memoization coverage: `toResolved(...)` transient bindings with pure-static explicit deps now compile into factory-call plans (same refusal rules and sync-only check as class plans), and name-only resolves gain a chain-versioned memo that fast-paths constants and cached singletons — predicates, aliases, and anything context-dependent keep the full selection path. Measured: `named-constant-get` ~21M → ~30M hz/op, `to-resolved-3-deps` ~39M → ~52M hz/op.
+
+- [#643](https://github.com/codefastlabs/codefast/pull/643) [`14c3a98`](https://github.com/codefastlabs/codefast/commit/14c3a98a98ae6221df447a94afe14b2e4a147c90) Thanks [@thevuong](https://github.com/thevuong)! - Collapse the async transient-dynamic resolver into a single lane and retune the cycle-set threshold.
+
+  The async lane used to split at depth 32 into a fast path (linear path scan, shared context, no stack frames) and a slow path (forced Set, fresh context per level, stack frames, extra microtask hop) — so context identity, `ctx.graph` contents, and promise shape all changed silently at that depth. Both are now one lane whose cycle guard goes through `enterResolutionPath`, the only mechanism that stays correct when chains interleave (`Promise.all`) and which adapts on its own: a linear scan while the path is short, an attached Set past `RESOLUTION_SET_THRESHOLD`. `DEEP_LANE_THRESHOLD` is gone from the package entirely.
+
+  `RESOLUTION_SET_THRESHOLD` drops from 128 to 32 on fresh measurements — at 128 an async chain costs 1275 / 3641 / 9645 / 26082 ns at depth 16 / 32 / 64 / 128 versus 1202 / 3285 / 7735 / 16837 at 32, so the old value was the worse choice at every depth measured.
+
+- [#643](https://github.com/codefastlabs/codefast/pull/643) [`14c3a98`](https://github.com/codefastlabs/codefast/commit/14c3a98a98ae6221df447a94afe14b2e4a147c90) Thanks [@thevuong](https://github.com/thevuong)! - Collapse the sync transient-dynamic resolver into a single lane and memoize each binding's resolution frame on the binding itself.
+
+  The separate deep lane existed to escape an `O(depth)` `resolutionPath.includes()` cycle scan past ~32 levels. With cycle detection now an `O(1)` `binding.inFlight` mark there is nothing to escape, so the depth split, its shared-context bookkeeping, its reentrancy fallback, and the per-resolver frame `Map` are all gone — the smaller function also inlines better. Frames derive only from immutable binding fields, so caching one per binding replaces a `Map` lookup per hop and a `Map` insert per binding per container.
+
+  Faster at every chain depth measured (8 → 512), e.g. a 32-deep transient chain improved ~39% and cold container build ~62%, which turns the cold-build result against Awilix from a loss into a win in the default benchmark profile.
+
+- [#643](https://github.com/codefastlabs/codefast/pull/643) [`14c3a98`](https://github.com/codefastlabs/codefast/commit/14c3a98a98ae6221df447a94afe14b2e4a147c90) Thanks [@thevuong](https://github.com/thevuong)! - `toResolved()` and `toResolvedAsync()` now accept injection descriptors — `inject()`, `optional()` and `injectAll()` — in their dependency list, matching what `@injectable([...])` already allowed and what the builder already did at runtime (it normalizes every entry through `normalizeToDescriptor`). Previously the public signature only admitted bare tokens and constructors, so an optional or multi dependency needed a cast even though resolution handled it correctly.
+
+  Factory arguments are typed from the descriptor: a bare token gives `Value`, `optional(token)` gives `Value | undefined`, and `injectAll(token)` gives `Array<Value>`. Widening only — existing bare-token call sites are unaffected.
+
+- [#643](https://github.com/codefastlabs/codefast/pull/643) [`14c3a98`](https://github.com/codefastlabs/codefast/commit/14c3a98a98ae6221df447a94afe14b2e4a147c90) Thanks [@thevuong](https://github.com/thevuong)! - `unbind(token)` now drops the token's bindings in a single registry pass instead of removing them one id at a time. The previous path re-scanned and re-indexed the token's binding list once per binding — quadratic in the number of slots bound to that token — and bumped the registry version once per removal, invalidating resolver lookup caches repeatedly. Behaviour is unchanged, including deactivation of cached singletons.
+
 ## 0.5.0-canary.6
 
 ### Minor Changes

package/README.md

@@ -12,7 +12,7 @@ Lightweight, type-safe dependency injection for modern TypeScript — built on T
 - **Modules.** Bundle bindings into reusable units; load, unload, and compose them across containers.
 - **Async-aware.** Async factories, deduped async singleton construction, and `await using` disposal.
 
-> Currently published as `1.0.0-canary.x` pre-releases on the way to a stable 1.0.
+> Currently published as `0.x` canary pre-releases on the way to a stable 1.0 — breaking changes on 0.x ship as minor versions.
 
 ## Requirements
 
@@ -128,7 +128,7 @@ container.resolve(LoggerToken, { name: "file" });
 container.resolve(StorageToken, { tag: ["provider", "s3"] });
 ```
 
-For graph-aware selection, pass a predicate to `.when(...)` — helpers like `whenParentIs`, `whenAnyAncestorNamed`, and `whenParentTagged` ship in `@codefast/di/constraints`.
+For graph-aware selection, pass a predicate to `.when(...)` — helpers like `whenParentIs`, `whenAnyAncestorNamed`, and `whenParentTagged` ship from the root entry (`import { whenParentIs } from "@codefast/di"`).
 
 ## Decorators
 
@@ -236,11 +236,22 @@ Every error extends `DiError` and carries a stable `code` — `TokenNotBoundErro
 
 ## Subpath exports
 
-The root entry re-exports the full public API. Every internal area is also published as a tree-shakeable subpath — `@codefast/di/container`, `@codefast/di/token`, `@codefast/di/module`, `@codefast/di/constraints`, `@codefast/di/errors`, and graph adapters under `@codefast/di/graph-adapters/*` (DOT, Cytoscape, React Flow) for visualizing `container.generateDependencyGraph()` output.
+The root entry re-exports the full public API — prefer it (`import { Container, token, toReactFlowGraph } from "@codefast/di"`). Every module is also published as a tree-shakeable subpath mirroring the source layout:
+
+- **Model** at the top level — `@codefast/di/token`, `/types`, `/binding`, `/registry`, `/errors`, `/module`
+- **Runtime** under `/container/*` and `/resolution/*` — e.g. `@codefast/di/resolution/constraints`
+- **Introspection** under `/introspection/*` — the inspector, `dependency-graph`, and the graph adapters (`@codefast/di/introspection/graph-adapters/{dot,cytoscape,reactflow}`) for visualizing `container.generateDependencyGraph()` output
+- **Decorators & metadata** under `/decorators/*` and `/metadata/*`
 
 ## Benchmarks
 
-A head-to-head benchmark suite against InversifyJS 8 lives in the monorepo: [benchmarks/di-inversify](https://github.com/codefastlabs/codefast/tree/main/benchmarks/di-inversify). Each library runs in its canonical decorator mode, in isolated subprocesses, reported as per-trial medians with interquartile range — designed so the results are re-runnable rather than taken on faith. On the production-shaped scenarios measured there, `@codefast/di` resolves faster than InversifyJS; run `pnpm bench` in that package to reproduce the numbers on your machine.
+A head-to-head benchmark suite lives in the monorepo: [benchmarks/di-inversify](https://github.com/codefastlabs/codefast/tree/main/benchmarks/di-inversify). It compares `@codefast/di` against **InversifyJS 8** on the full scenario set, plus **Awilix** and **tsyringe** on a shared core subset. Each library runs in its canonical mode, in isolated subprocesses, reported as per-trial medians with interquartile range — designed so the results are re-runnable rather than taken on faith.
+
+Against InversifyJS — the only one of the three that covers a comparable feature surface — `@codefast/di` currently wins **all 43 comparable scenarios** in both profiles, at a median of 1.86×–2.21× and a geometric mean of 2.38×–2.76×. Against the two deliberately leaner containers it wins the shared core subset as well, with one exception: cold container build against tsyringe under the forced-GC profile. See [RESULTS.md](https://github.com/codefastlabs/codefast/blob/main/benchmarks/di-inversify/RESULTS.md) for the full tables, the caveats, and the losses that earlier revisions reported — or run `pnpm bench` in that package to reproduce them on your machine.
+
+## Contributing
+
+Changing this package's source? [CONTRIBUTING.md](https://github.com/codefastlabs/codefast/blob/main/packages/di/CONTRIBUTING.md) is the full workflow — build, exports mirror, tests, the mandatory perf-guard for resolver changes, and the release gate.
 
 ## License
 

package/dist/binding.d.ts

@@ -1,6 +1,6 @@
-import type { InjectionDescriptor } from "#/decorators/inject";
+import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/decorators/inject";
 import type { Token } from "#/token";
-import type { ActivationHandler, BindingIdentifier, BindingScope, BindingTag, Constructor, DeactivationHandler, DependencyKey, ResolutionContext, TokenValue, ConstraintContext } from "#/types";
+import type { ActivationHandler, BindingIdentifier, BindingScope, BindingTag, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame, ConstraintContext } from "#/types";
 /**
  * @since 0.3.16-canary.0
  */
@@ -12,6 +12,12 @@ export interface BindingSlot {
  * @since 0.3.16-canary.0
  */
 export declare function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolean;
+/**
+ * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
+ *
+ * @since 0.5.0-canary.8
+ */
+export declare const NO_INSTANCE: unique symbol;
 /**
  * @since 0.3.16-canary.0
  */
@@ -25,9 +31,31 @@ export declare const DEFAULT_BINDING_SLOT: {
 export declare function bindingSlotToString(slot: BindingSlot): string;
 interface BindingBase<Value> {
     readonly id: BindingIdentifier;
+    /**
+     * True while this binding's factory is on the sync resolution stack — the sync lane's cycle check.
+     *
+     * @remarks Resolver-owned bookkeeping; callers never set it. See `ARCHITECTURE.md` for why the
+     * sync and async lanes detect cycles differently.
+     */
+    inFlight?: boolean | undefined;
+    /**
+     * Memoized resolution frame for this binding. Its contents derive only from immutable binding
+     * fields, so it is computed once on first resolve and reused instead of a per-resolver Map
+     * lookup on every hop.
+     *
+     * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
+     */
+    frame?: ResolutionFrame | undefined;
+    /**
+     * Cached singleton instance, or {@link NO_INSTANCE}.
+     *
+     * @remarks A binding belongs to exactly one container, so its singleton slot is per-binding —
+     * a field read replaces a keyed lookup on the hottest resolve shape there is.
+     */
+    instance?: unknown;
     readonly token: Token<Value> | Constructor<Value>;
     readonly slot: BindingSlot;
-    readonly predicate?: (ctx: ConstraintContext) => boolean;
+    readonly predicate?: ((ctx: ConstraintContext) => boolean) | undefined;
 }
 type BindingBaseKeys = keyof BindingBase<unknown>;
 /**
@@ -37,8 +65,8 @@ export interface ClassBinding<Value> extends BindingBase<Value> {
     readonly kind: "class";
     readonly target: Constructor<Value>;
     readonly scope: BindingScope;
-    readonly onActivation?: ActivationHandler<Value>;
-    readonly onDeactivation?: DeactivationHandler<Value>;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 /**
  * @since 0.3.16-canary.0
@@ -47,8 +75,8 @@ export interface DynamicBinding<Value> extends BindingBase<Value> {
     readonly kind: "dynamic";
     readonly factory: (ctx: ResolutionContext) => Value;
     readonly scope: BindingScope;
-    readonly onActivation?: ActivationHandler<Value>;
-    readonly onDeactivation?: DeactivationHandler<Value>;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 /**
  * @since 0.3.16-canary.0
@@ -57,8 +85,8 @@ export interface DynamicAsyncBinding<Value> extends BindingBase<Value> {
     readonly kind: "dynamic-async";
     readonly factory: (ctx: ResolutionContext) => Promise<Value>;
     readonly scope: BindingScope;
-    readonly onActivation?: ActivationHandler<Value>;
-    readonly onDeactivation?: DeactivationHandler<Value>;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 /**
  * @since 0.3.16-canary.0
@@ -68,8 +96,8 @@ export interface ResolvedBinding<Value> extends BindingBase<Value> {
     readonly factory: (...args: Array<unknown>) => Value;
     readonly deps: ReadonlyArray<InjectionDescriptor>;
     readonly scope: BindingScope;
-    readonly onActivation?: ActivationHandler<Value>;
-    readonly onDeactivation?: DeactivationHandler<Value>;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 /**
  * @since 0.3.16-canary.0
@@ -79,8 +107,8 @@ export interface ResolvedAsyncBinding<Value> extends BindingBase<Value> {
     readonly factory: (...args: Array<unknown>) => Promise<Value>;
     readonly deps: ReadonlyArray<InjectionDescriptor>;
     readonly scope: BindingScope;
-    readonly onActivation?: ActivationHandler<Value>;
-    readonly onDeactivation?: DeactivationHandler<Value>;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 /**
  * @since 0.3.16-canary.0
@@ -89,8 +117,8 @@ export interface ConstantBinding<Value> extends BindingBase<Value> {
     readonly kind: "constant";
     readonly value: Value;
     readonly scope: "singleton";
-    readonly onActivation?: ActivationHandler<Value>;
-    readonly onDeactivation?: DeactivationHandler<Value>;
+    readonly onActivation?: ActivationHandler<Value> | undefined;
+    readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 /**
  * @since 0.3.16-canary.0
@@ -113,6 +141,37 @@ export type PartialBinding<Value> = Omit<ClassBinding<Value>, BindingBaseKeys> |
  * @since 0.3.16-canary.0
  */
 export declare function generateBindingId(): BindingIdentifier;
+/**
+ * The single construction site for bindings — one literal, one V8 hidden class.
+ *
+ * @see `ARCHITECTURE.md` — why the field order and the single site are load-bearing.
+ *
+ * @param source - the kind-specific payload, or an existing binding to re-slot
+ * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
+ *
+ * @since 0.5.0-canary.8
+ */
+export declare function createBinding<Value>(source: PartialBinding<Value> | Binding<Value>, token: Token<Value> | Constructor<Value>, slot: BindingSlot, predicate: ((ctx: ConstraintContext) => boolean) | undefined, id?: BindingIdentifier): Binding<Value>;
+/**
+ * Writable view of the only fields a fluent chain may refine after registration.
+ *
+ * @remarks No registry index is keyed on these, so a builder that owns the registered object
+ * can write them directly instead of re-registering. `token`, `slot`, `predicate` and `id`
+ * are excluded on purpose — changing those means re-indexing.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface RefinableBindingFields<Value> {
+    onActivation: ActivationHandler<Value> | undefined;
+    onDeactivation: DeactivationHandler<Value> | undefined;
+    scope: BindingScope;
+}
+/**
+ * Narrows a registered binding to the fields a fluent chain may still refine.
+ *
+ * @since 0.5.0-canary.8
+ */
+export declare function refinableFields<Value>(binding: Binding<Value>): RefinableBindingFields<Value>;
 /**
  * Common slot-constraint + id methods shared by all concrete binding builders.
  *
@@ -134,11 +193,11 @@ export interface BindToBuilder<Value> {
     toConstantValue(value: Value): ConstantBindingBuilder<Value>;
     toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
     toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
-    toResolved<const Deps extends ReadonlyArray<DependencyKey>>(factory: (...args: {
-        [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]>;
+    toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
+        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
     }) => Value, deps: Deps): BindingBuilder<Value>;
-    toResolvedAsync<const Deps extends ReadonlyArray<DependencyKey>>(factory: (...args: {
-        [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]>;
+    toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
+        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
     }) => Promise<Value>, deps: Deps): BindingBuilder<Value>;
     toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
 }

package/dist/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"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"}

package/dist/binding.js

@@ -15,6 +15,12 @@ export function bindingSlotEquals(left, right) {
     }
     return true;
 }
+/**
+ * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const NO_INSTANCE = Symbol("di:no-instance");
 /**
  * @since 0.3.16-canary.0
  */
@@ -36,11 +42,49 @@ export function bindingSlotToString(slot) {
     return parts.join(",");
 }
 // ── ID generation ─────────────────────────────────────────────────────────────
-let _idCounter = 0;
+let bindingIdCounter = 0;
 /**
  * @since 0.3.16-canary.0
  */
 export function generateBindingId() {
-    return String(++_idCounter);
+    return String(++bindingIdCounter);
+}
+/**
+ * The single construction site for bindings — one literal, one V8 hidden class.
+ *
+ * @see `ARCHITECTURE.md` — why the field order and the single site are load-bearing.
+ *
+ * @param source - the kind-specific payload, or an existing binding to re-slot
+ * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
+ *
+ * @since 0.5.0-canary.8
+ */
+export function createBinding(source, token, slot, predicate, id = generateBindingId()) {
+    const fields = source;
+    return {
+        kind: fields.kind,
+        id,
+        inFlight: false,
+        frame: undefined,
+        instance: source.instance ?? NO_INSTANCE,
+        token,
+        slot,
+        predicate,
+        scope: fields.scope,
+        target: fields.target,
+        factory: fields.factory,
+        deps: fields.deps,
+        value: fields.value,
+        onActivation: fields.onActivation,
+        onDeactivation: fields.onDeactivation,
+    };
+}
+/**
+ * Narrows a registered binding to the fields a fluent chain may still refine.
+ *
+ * @since 0.5.0-canary.8
+ */
+export function refinableFields(binding) {
+    return binding;
 }
 //# sourceMappingURL=binding.js.map

package/dist/binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAyBA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAE,KAAkB;IACrE,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,QAAQ,KAAK,MAAM,IAAI,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;YACzG,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAwB,CAAC;AAExF;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAqHD,iFAAiF;AAEjF,IAAI,UAAU,GAAG,CAAC,CAAC;AACnB;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,EAAE,UAAU,CAAsB,CAAC;AACnD,CAAC"}
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"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"}

package/dist/constructor-type.d.ts

@@ -1,9 +1,8 @@
 /**
- * A class (newable) that produces `Value`. Rest parameters are `never[]` so
- * real classes with typed constructors remain assignable under
- * `strictFunctionTypes` (unlike `unknown[]`, which is not assignable from
- * narrower parameter types). Runtime construction still uses the real shape;
- * this alias is the DI “class token” surface only.
+ * A class token: newable, producing `Value`.
+ *
+ * @remarks Rest parameters are `never[]` so classes with typed constructors stay assignable under
+ * `strictFunctionTypes`. Construction uses the real shape; this alias is the token surface only.
  *
  * @since 0.3.16-canary.0
  */

package/dist/constructor-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constructor-type.d.ts","sourceRoot":"","sources":["../src/constructor-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC"}
+{"version":3,"file":"constructor-type.d.ts","sourceRoot":"","sources":["../src/constructor-type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC"}

package/dist/container/binding-builders.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The fluent chain `bind()` returns: it registers the binding and refines it in place.
+ *
+ * @see `ARCHITECTURE.md` — why one object plays every role, and what pins the ordering.
+ */
+import type { AliasBindingBuilder, BindingBuilder, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#/binding";
+import type { InjectableDependency, ResolvedDependencyValue } from "#/decorators/inject";
+import type { BindingRegistry } from "#/registry";
+import type { Token } from "#/token";
+import type { ActivationHandler, BindingIdentifier, ConstraintContext, Constructor, DeactivationHandler, ResolutionContext } from "#/types";
+/**
+ * Where a chain registers, and on whose behalf.
+ *
+ * @remarks Built once per container and shared by every chain it creates. `moduleBindingIds` is
+ * present exactly when the chain belongs to a module load.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface BindingRegistration {
+    readonly registry: BindingRegistry;
+    readonly moduleBindingIds: Array<BindingIdentifier> | undefined;
+}
+/**
+ * The one builder behind `bind()` and every `to*()` return type. Each interface exposes only the
+ * calls that are legal at that point in the chain; the runtime object is shared because every
+ * refinement is the same operation — narrow the registered binding, keep its id.
+ *
+ * @since 0.5.0-canary.8
+ */
+export declare class BindingChain<Value> implements AliasBindingBuilder, BindingBuilder<Value>, BindToBuilder<Value>, ConstantBindingBuilder<Value>, ScopedBindingBuilder<Value>, SingletonBindingBuilder<Value>, SingletonLifecycleBuilder<Value>, TransientBindingBuilder<Value> {
+    #private;
+    constructor(token: Token<Value> | Constructor<Value>, registration: BindingRegistration);
+    to(type: Constructor<Value>): BindingBuilder<Value>;
+    toSelf(): BindingBuilder<Value>;
+    toConstantValue(value: Value): ConstantBindingBuilder<Value>;
+    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
+    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
+    toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
+        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
+    }) => Value, deps: Deps): BindingBuilder<Value>;
+    toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
+        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
+    }) => Promise<Value>, deps: Deps): BindingBuilder<Value>;
+    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
+    when(predicate: (ctx: ConstraintContext) => boolean): this;
+    whenNamed(name: string): this;
+    whenTagged(tag: string, value: unknown): this;
+    whenDefault(): this;
+    singleton(): SingletonBindingBuilder<Value>;
+    transient(): TransientBindingBuilder<Value>;
+    scoped(): ScopedBindingBuilder<Value>;
+    onActivation(fn: ActivationHandler<Value>): this;
+    onDeactivation(fn: DeactivationHandler<Value>): this;
+    id(): BindingIdentifier;
+}
+//# sourceMappingURL=binding-builders.d.ts.map

package/dist/container/binding-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-builders.d.ts","sourceRoot":"","sources":["../../src/container/binding-builders.ts"],"names":[],"mappings":"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"}