@codefast/di 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,169 @@
 # @codefast/di
 
+## 0.10.0
+
+### Minor Changes
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`3621384`](https://github.com/codefastlabs/codefast/commit/36213842e7e64284dfb0c5b0d651368debf20a13) Thanks [@thevuong](https://github.com/thevuong)! - `BindingIdentifier` is a branded number, minted from a process-wide counter, instead of a branded string. The id stays
+  opaque — obtained from `.id()`, handed back to `unbind(id)`, reported by `inspect()` and the dependency graph — and a
+  plain bind no longer allocates a string for it. Code that treated the id as a string (interpolating, parsing or storing
+  it as text) must treat it as a number.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`67c7eb4`](https://github.com/codefastlabs/codefast/commit/67c7eb4a63cee26c8b3d4954965a5fdacbfe3533) Thanks [@thevuong](https://github.com/thevuong)! - The fluent chain `bind()` returns is now the binding it registers: one object is every builder step, the registry's
+  record and what the resolver reads, so a plain bind is one allocation instead of three and a copy of every field. Two
+  names on the `Binding` shapes change to make room for the builder's methods — `id` is `identifier`, and the hook fields
+  are `activationHook` / `deactivationHook` — and a chain registers exactly once: a second `to*()` throws
+  `ChainAlreadyRegisteredError` instead of minting a second binding.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`7f4efc2`](https://github.com/codefastlabs/codefast/commit/7f4efc2faf96ffdd4279241c9bc83aba53bc64af) Thanks [@thevuong](https://github.com/thevuong)! - `resolveAll`, `resolveAllAsync` and the value an `injectAll()` dependency delivers are `ReadonlyArray`s, and a
+  root-level, options-less `resolveAll` hands out the engine's own list — the same array on every call while no registry
+  in the chain has changed — instead of a copy per read. That list is kept while every member is a hook-free constant or a
+  hook-free singleton whose instance is cached, so a collection of singleton handlers is one lookup per read. Callers that
+  mutated the returned array spread it first; a constructor parameter typed `Array<T>` for an `injectAll` dependency
+  becomes `ReadonlyArray<T>`.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`6980f8e`](https://github.com/codefastlabs/codefast/commit/6980f8ee5b804b17946ac959a9581f207e7ad008) Thanks [@thevuong](https://github.com/thevuong)! - `many()` marks a binding as a collection member: several members of one token coexist on the default slot, `resolveAll`
+  returns every member, a single `resolve` never selects one, and membership replaces slot last-wins. A member keeps the
+  default slot (`ManyBindingSlotError` otherwise) and may carry `when()` predicates. It is the intended form of a strategy
+  set, where a predicate that always passes used to stand in — and it is what lets a root-level collection of constants be
+  served from its memo without evaluating anything. `BindingSnapshot` gains `isMany`.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`a56390f`](https://github.com/codefastlabs/codefast/commit/a56390f79bb62e6e33ecb79cbd158ad1349d7bee) Thanks [@thevuong](https://github.com/thevuong)! - A root-level `resolveAll` with no options memoizes its candidate list until any registry in the chain changes, and its
+  value list while every member is a hook-free constant with no activation hook anywhere in the chain. The contract
+  already required `when()` predicates to be pure; the engine now relies on it there, evaluating a predicate once per
+  container state for that read instead of on every call. Reads carrying options, or made from inside a factory, are
+  unchanged.
+
+### Patch Changes
+
+- [#863](https://github.com/codefastlabs/codefast/pull/863) [`ccc5ed1`](https://github.com/codefastlabs/codefast/commit/ccc5ed193f15d9edc7c3e6475a6bfda22e2c6319) Thanks [@thevuong](https://github.com/thevuong)! - Rewrite `benchmarks/di/RESULTS.md` as a single machine-derived snapshot on `@codefast/di` 0.9.0 (full profile,
+  GC-exposed, interleaved) instead of an accreted dated ledger, weighting wins and losses equally so the page shows where
+  the engine is slower. The snapshot records that `@codefast/di` loses the aggregate to ditox (0.79× median) and the
+  geomean to injection-js (0.56×), and breaks down each loss as a real deficit or a by-design work difference — the
+  `resolve-all-strategies` collapse (0.03× at N=100) is the rivals returning a memoized collection where `@codefast/di`
+  re-gathers per op.
+
+  Assert the A/B method in `BENCH_GUIDE.md`: because `run.ts` rebuilds `packages/di/dist` from `src` unconditionally
+  before spawning, swapping the source is the one method, and swapping `dist` directly is a demoted escape hatch that must
+  use the child entries. Repoint the `packages/di/ARCHITECTURE.md` tag-chain-walk-memo reference from `RESULTS.md` to the
+  package `CHANGELOG.md`, where that A/B now lives.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`85adfd0`](https://github.com/codefastlabs/codefast/commit/85adfd004920f99ec8552745b7726e03e971cbb2) Thanks [@thevuong](https://github.com/thevuong)! - Construct an accessor-injected class without the two per-instantiation allocations it used to pay: the ambient
+  resolution handed to its accessors is built once per resolver for the lent root stack, and the construction itself runs
+  inside the ambient scope directly instead of through a wrapping closure.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`d541dee`](https://github.com/codefastlabs/codefast/commit/d541dee97719a3151dd4daa9675846cb11aac82b) Thanks [@thevuong](https://github.com/thevuong)! - Compile an accessor-injected class as a plan root instead of declining the plan: its constructor parameters compile as
+  usual and construction runs through the host, which puts the class's frame on the resolution path and the container
+  ambient before constructing, so an accessor that cycles back is still reported as a `CircularDependencyError`. Below a
+  plan's root such a class stays an escape.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`793f5d0`](https://github.com/codefastlabs/codefast/commit/793f5d0a13092144b2ca83ec23142e68011cd5ca) Thanks [@thevuong](https://github.com/thevuong)! - Route every member of a `resolveAllAsync` collection that is a transient factory with no activation and no request
+  options through the same non-`async` lane a single `resolveAsync` already takes, so a fan-out costs one factory promise
+  per member instead of an async state machine on top of each.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`7a00e30`](https://github.com/codefastlabs/codefast/commit/7a00e306de98a829385e3238095333f094a843f7) Thanks [@thevuong](https://github.com/thevuong)! - Build collections in linear time. A token's binding list now appends in place and is replaced only on removal or
+  displacement, with every selection walk reading its starting length first, so a predicate that binds mid-walk is still
+  invisible to that walk; and a bare `when()` rewrites the binding's predicate in place — moving a lone binding into a
+  record — instead of re-registering it, whenever the chain owns the registry's last write and has nothing parked. A
+  hundred `when()` bindings on one token no longer copy the list a hundred times.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`3613886`](https://github.com/codefastlabs/codefast/commit/36138863480e0fa48ca522ad56fa1ee98a528307) Thanks [@thevuong](https://github.com/thevuong)! - Defer every per-container allocation a resolve can happen without. The resolver builds its plan compiler and plan maps
+  on the first plan request, the lookup cache allocates its memo maps only once a second distinct token or tag appears in
+  one cache generation, the activation-need memo is allocated by the first answer its early returns cannot give, and the
+  registry allocates its record map on the first bind. A per-request child that is created, asked one parent-owned token
+  and disposed now allocates none of them; the registry's fast-default map stays eager so the first read of every
+  synchronous resolve is still a bare `Map.get`.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`b823fc8`](https://github.com/codefastlabs/codefast/commit/b823fc89c09fb200d0d9262f16f34f32cd27a63e) Thanks [@thevuong](https://github.com/thevuong)! - Price the two lanes the full pass showed paying for the rewrite: a request for an unbound or record-less token reads the
+  record map alone once its lone-map probe has missed, instead of probing the lone map again, and a root container's
+  chain-summed versions are read as its own version instead of through the epoch memo, so a `resolveAll` over a root no
+  longer pays a compare and a stamp per candidate.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`5fbc3de`](https://github.com/codefastlabs/codefast/commit/5fbc3dea835987f8eb857529a5a6b1293ac523b6) Thanks [@thevuong](https://github.com/thevuong)! - A request carrying a name and one tag is answered from a memoized lookup of the exact two-criterion slot, in either
+  declaration order, instead of a scan of the token's bindings; a predicate on that binding still runs, and a name no
+  binding has declared is a miss at once.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`b46c0cd`](https://github.com/codefastlabs/codefast/commit/b46c0cd9473a662f294231796c4be2a206c83033) Thanks [@thevuong](https://github.com/thevuong)! - `resolveOptional` with no options answers a lone default binding in its own registry on the lane a plain `resolve`
+  takes, and a root that keeps no records answers a miss without the selection walk; a generated `toResolved` plan checks
+  its factory's result for a promise inline instead of through a call.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`0506f04`](https://github.com/codefastlabs/codefast/commit/0506f046e9f797086708c186f14f96f13026a8bd) Thanks [@thevuong](https://github.com/thevuong)! - A compiled instantiation plan that keeps running — sync or async — is generated as a function of its own through the
+  `Function` constructor and takes the closure's place, so its call sites carry feedback for one plan only instead of for
+  every plan the process has compiled; below the threshold a plan stays a closure, so a cold container or a per-request
+  child never compiles one. A runtime whose Content Security Policy refuses the constructor keeps every plan a closure and
+  behaves identically. `RESOLUTION_DIAGNOSTICS` reports `generatedPlanCount`.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`e3e9257`](https://github.com/codefastlabs/codefast/commit/e3e92571dc64f8eb48006b3310d4334ea61cc149) Thanks [@thevuong](https://github.com/thevuong)! - Keep the common token — one default-slot binding, no predicate — in the registry's fast-default map alone, and give a
+  record (binding list plus tagged indexes) only to a token that carries a second binding, a tagged slot or a predicate,
+  moving it back when the record shrinks to the default slot. A plain bind is now one map write and one binding object;
+  `getFastDefault()` is unchanged, a bare `Map.get` on that map, and `has()`/`hasOwn()` without criteria answer from a
+  registry presence probe instead of materialising the token's list. `RESOLUTION_DIAGNOSTICS` reports the record map under
+  `registry.records`.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`414d495`](https://github.com/codefastlabs/codefast/commit/414d495c6db58106e64ba5f74880e12bd85c2459) Thanks [@thevuong](https://github.com/thevuong)! - The binding registry keeps one record per token — its list and its two tagged indexes — in a single map, and builds the
+  binding-id index only on the first id-keyed operation. A bind into a fresh token is one record and one map write where
+  it was three map writes; `getFastDefault()` keeps its own map so the warm resolve lane still answers from one bare
+  `Map.get`. Measured paired and alternating against the previous layout: the bind path runs at roughly 1.6× on the
+  128-binding registration row and the warm resolve rows hold at parity.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`3db3447`](https://github.com/codefastlabs/codefast/commit/3db3447bfe87b4aaf5f48113cc91b19537eefeb0) Thanks [@thevuong](https://github.com/thevuong)! - Register a binding into a token's record in constant time. Last-wins displacement asked the record's list who occupied
+  the incoming binding's slot, walking every binding already on the token; the default slot now has its own index entry
+  beside the two tagged ones, so an add finds and displaces exactly its occupant without the walk. A token that grows a
+  large collection member by member — the fan-out cold path — was quadratic to build and is now linear: per-bind cost
+  stays flat instead of climbing with the collection size, and the `resolve-all-cold` rows move from a loss to a win
+  against the decorator-free rivals. The slot index is dropped in the same step a binding leaves its slot — `many()`
+  turning it into a member, a predicate making it predicate-only — so a later add never displaces a binding that has
+  already moved on.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`8bb19e3`](https://github.com/codefastlabs/codefast/commit/8bb19e3ab11c4176f307765321e431cfa94d37bb) Thanks [@thevuong](https://github.com/thevuong)! - Answer a request the slot indexes decline with an allocation-free first pass over the token's candidates: one slot match
+  with no predicate is returned outright and no match is a clean miss, without building a constraint context, a display
+  name or a candidate array. A second match, or a predicate on a match, still goes through full selection, so specificity
+  and ambiguity are decided exactly as before.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`5e57752`](https://github.com/codefastlabs/codefast/commit/5e57752b2fcad8a1c44e5bff61d5f91f7cdb27da) Thanks [@thevuong](https://github.com/thevuong)! - A container's class-metadata caches are keyed by the metadata reader and shared by every container that reads through
+  it, so a child inheriting its parent's reader resolves a class the parent already met without reading its metadata
+  again; the activation-need cache is built by the first interpreted resolve that asks for it instead of with the
+  container.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`bee69af`](https://github.com/codefastlabs/codefast/commit/bee69af3688a67234ecd113159ca7e767e14699a) Thanks [@thevuong](https://github.com/thevuong)! - Memoize the lookup cache's chain-summed registry version against a process-wide state epoch that every registry mutation
+  and activation-hook registration advances, and let a root container read both chain sums as its own version. A resolve
+  from a deep child no longer walks its whole ancestor chain on every lookup while nothing has changed; the first read
+  after any change re-sums exactly as before. The activation sum stays a walk: the memo that would serve it costs fields
+  on the resolver that the warm transient class lane pays for.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`f78726e`](https://github.com/codefastlabs/codefast/commit/f78726e00b9c388ceb03f7fad116593d7b752a94) Thanks [@thevuong](https://github.com/thevuong)! - A request carrying one criterion that the token's tagged index does not hold is answered as a miss for that container
+  without scanning its bindings, and walks to the parent directly.
+
+- [#866](https://github.com/codefastlabs/codefast/pull/866) [`5536e62`](https://github.com/codefastlabs/codefast/commit/5536e6208ab58955fb551866c3b9703e7f2c55e0) Thanks [@thevuong](https://github.com/thevuong)! - Allocate the deactivation-pair list only when an unbind, rebind or teardown actually owes a deactivation; the hot-swap
+  shape, a binding nothing ever cached, hands back a shared empty list instead.
+
+## 0.9.0
+
+### Minor Changes
+
+- [#847](https://github.com/codefastlabs/codefast/pull/847) [`d0b794c`](https://github.com/codefastlabs/codefast/commit/d0b794c047344c4040b5641202c259d72a0ea48c) Thanks [@thevuong](https://github.com/thevuong)! - `Token` gains a second type parameter, `Names extends string = string`, declaring the slot names its bindings may use:
+  `token<Logger, "console" | "file">("Logger")`. `whenNamed`, and `name` in `ResolveOptions` and `InjectOptions`, narrow
+  to it, so a misspelt name is a compile error and the IDE completes the declared names at every bind and request site.
+  `Names` is a covariant phantom that defaults to `string`, so existing tokens, class keys and internal `Token<unknown>`
+  lanes are unchanged; a new `SlotNamesOf<Key>` type reads the set back.
+
+  **Breaking:** `whenParentNamed` and `whenAnyAncestorNamed` now take the parent token first —
+  `whenParentNamed(Database, "primary")` — and match only when that frame resolves that token at that slot. A slot name is
+  a label on one token's bindings, so the token is part of the question and is what types the name; a label shared across
+  tokens is what a tag key is for. `validate()` checks the name on that token's bindings and `UnreachableConstraintError`
+  carries the new `requiredTokenName`. The reserved criterion handed to a `…Tagged` helper
+  (`whenParentTagged(slotName.of("x"))`) is now validated too, as it is the same bare string.
+
+  Display names follow one rule everywhere the package speaks — spelled like the TS symbol they stand for, under the
+  owner's namespace: `token<Logger>("app:Logger")`, `Module.create("app:Infra", …)`, `tag("app:cacheTier")`. The package's
+  own `MetadataReaderToken` now prints as `di:MetadataReader`, beside the reserved `di:name` key. SPEC gains a normative
+  "Display names" section stating the rule and its enforcement.
+
+### Patch Changes
+
+- [#827](https://github.com/codefastlabs/codefast/pull/827) [`0984174`](https://github.com/codefastlabs/codefast/commit/0984174df148a7cffcd09b837bdde1922f38f24e) Thanks [@thevuong](https://github.com/thevuong)! - `package.json` now carries `homepage` and `bugs`, so npm links the package README and the issue tracker the way the
+  other `@codefast/*` packages already do.
+
 ## 0.8.1
 
 ### Patch Changes

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 CodeFast Labs
+Copyright (c) 2024 Codefast Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -48,7 +48,7 @@ interface Logger {
   info(message: string): void;
 }
 
-const LoggerToken = token<Logger>("Logger");
+const LoggerToken = token<Logger>("app:Logger");
 
 @injectable([LoggerToken])
 class CheckoutService {
@@ -86,7 +86,7 @@ and resolve against. Tokens compare by reference, so declare each one once and r
 ```ts
 import { token } from "@codefast/di";
 
-const DbToken = token<Database>("Database");
+const DbToken = token<Database>("app:Database");
 ```
 
 A class constructor works as a key too: `container.bind(UserService).toSelf()`, then `container.resolve(UserService)`.
@@ -170,6 +170,15 @@ container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
 container.resolve(LoggerToken, { name: "file" }); // → fileLogger
 ```
 
+Declare the names on the token and they become checked, completable literals at every bind and request site:
+
+```ts
+const LoggerToken = token<Logger, "console" | "file">("app:Logger");
+
+container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
+container.resolve(LoggerToken, { name: "file" }); // { name: "fiel" } is a compile error
+```
+
 **Tagged — for typed, collision-proof keys.** A criterion is a `[key, value]` pair. Declare the key once with
 `tag<Value>(name)`, then mint a criterion with `key.of(value)`. The bind site and the resolve site share the same typed
 key: a key declared `tag<"s3" | "gcs">` refuses any other value, so the two sites can't drift apart.
@@ -177,7 +186,7 @@ key: a key declared `tag<"s3" | "gcs">` refuses any other value, so the two site
 ```ts
 import { tag } from "@codefast/di";
 
-const Provider = tag<"s3" | "gcs">("provider");
+const Provider = tag<"s3" | "gcs">("app:provider");
 
 container.bind(StorageToken).to(S3Storage).whenTagged(Provider.of("s3"));
 container.resolve(StorageToken, { tag: Provider.of("s3") }); // → S3Storage
@@ -202,18 +211,18 @@ container.resolve(StorageToken, { tag: Provider.of("s3") }); // → S3Storage
 resolving — pass a predicate to `.when(ctx => boolean)`. It runs at resolve time, after slot matching. These ready-made
 predicates ship from the root entry:
 
-| Predicate                            | Matches when                                           |
-| ------------------------------------ | ------------------------------------------------------ |
-| `whenParentIs(token)`                | the direct parent resolves `token`                     |
-| `whenNoParentIs(token)`              | there is no parent, or it resolves a different token   |
-| `whenAnyAncestorIs(token)`           | some ancestor resolves `token`                         |
-| `whenNoAncestorIs(token)`            | no ancestor resolves `token`                           |
-| `whenParentNamed(name)`              | the parent's slot carries that name                    |
-| `whenAnyAncestorNamed(name)`         | some ancestor's slot carries that name                 |
-| `whenParentTagged(criterion)`        | the parent's slot carries that criterion               |
-| `whenAnyAncestorTagged(criterion)`   | some ancestor's slot carries that criterion            |
-| `whenParentTaggedAll(criteria)`      | the parent's slot carries all criteria in the array    |
-| `whenAnyAncestorTaggedAll(criteria)` | some ancestor's slot carries all criteria in the array |
+| Predicate                            | Matches when                                            |
+| ------------------------------------ | ------------------------------------------------------- |
+| `whenParentIs(token)`                | the direct parent resolves `token`                      |
+| `whenNoParentIs(token)`              | there is no parent, or it resolves a different token    |
+| `whenAnyAncestorIs(token)`           | some ancestor resolves `token`                          |
+| `whenNoAncestorIs(token)`            | no ancestor resolves `token`                            |
+| `whenParentNamed(token, name)`       | the parent resolves `token` at the slot named `name`    |
+| `whenAnyAncestorNamed(token, name)`  | some ancestor resolves `token` at the slot named `name` |
+| `whenParentTagged(criterion)`        | the parent's slot carries that criterion                |
+| `whenAnyAncestorTagged(criterion)`   | some ancestor's slot carries that criterion             |
+| `whenParentTaggedAll(criteria)`      | the parent's slot carries all criteria in the array     |
+| `whenAnyAncestorTaggedAll(criteria)` | some ancestor's slot carries all criteria in the array  |
 
 For the exact matching and most-specific-wins rules, see [`SPEC.md` → Slots and last-wins](./SPEC.md#slot-matching).
 
@@ -358,11 +367,11 @@ A module is a reusable, stateless bundle of related bindings. Group them once, t
 ```ts
 import { Container, Module } from "@codefast/di";
 
-const InfrastructureModule = Module.create("Infra", (api) => {
+const InfrastructureModule = Module.create("app:Infra", (api) => {
   api.bind(LoggerToken).toConstantValue(console);
 });
 
-const AppModule = Module.create("App", (api) => {
+const AppModule = Module.create("app:Root", (api) => {
   api.import(InfrastructureModule);
   api.bind(UserRepository).toSelf().singleton();
 });
@@ -407,9 +416,9 @@ metadata under `decorators/*` and `metadata/*`. Introspection ships at flat spec
 
 ## Benchmarks
 
-A first-party benchmark suite lives in the monorepo, at [`benchmarks/di-inversify`](../../benchmarks/di-inversify). It
-runs the same workloads through `@codefast/di`, InversifyJS, Awilix, and tsyringe, and its `RESULTS.md` ledger records
-the numbers alongside the method that produced them. Run it yourself rather than taking any figure on faith.
+A first-party benchmark suite lives in the monorepo, at [`benchmarks/di`](../../benchmarks/di). It runs the same
+workloads through `@codefast/di`, InversifyJS, Awilix, and tsyringe, and its `RESULTS.md` ledger records the numbers
+alongside the method that produced them. Run it yourself rather than taking any figure on faith.
 
 ## Documentation
 

package/dist/ambient/active-container.d.ts

@@ -1,5 +1,6 @@
 /** The container an `@inject` accessor initializer resolves from when it has no other handle. */
 import type { Container } from "#/container/container";
+import type { ConstructorInvocation } from "#/core/constructor-type";
 import type { Token } from "#/core/token";
 import type { Constructor, ResolveOptions } from "#/core/types";
 /**
@@ -31,6 +32,18 @@ export declare function runWithAmbientResolution<Result>(container: Container, r
  *
  * @since 0.3.16-canary.0
  */
+/**
+ * Constructs `target` with `container` and `resolution` ambient for the duration of its constructor.
+ *
+ * @remarks The construction is written out rather than wrapped in a closure: an accessor-injected
+ * class pays this on every instantiation, and the closure was one of two allocations it paid for.
+ *
+ * @since 0.10.0
+ */
+export declare function constructWithAmbientResolution(container: Container, resolution: AmbientResolution, target: ConstructorInvocation, deps: ReadonlyArray<unknown>): unknown;
+/**
+ * @since 0.10.0
+ */
 export declare function getActiveContainer(): Container | undefined;
 /**
  * The path-continuing resolution for the construction in flight, when the engine installed one.

package/dist/ambient/active-container.js

@@ -31,6 +31,30 @@ export function runWithAmbientResolution(container, resolution, fn) {
  *
  * @since 0.3.16-canary.0
  */
+/**
+ * Constructs `target` with `container` and `resolution` ambient for the duration of its constructor.
+ *
+ * @remarks The construction is written out rather than wrapped in a closure: an accessor-injected
+ * class pays this on every instantiation, and the closure was one of two allocations it paid for.
+ *
+ * @since 0.10.0
+ */
+export function constructWithAmbientResolution(container, resolution, target, deps) {
+    const previousContainer = activeContainer;
+    const previousResolution = activeResolution;
+    activeContainer = container;
+    activeResolution = resolution;
+    try {
+        return new target(...deps);
+    }
+    finally {
+        activeContainer = previousContainer;
+        activeResolution = previousResolution;
+    }
+}
+/**
+ * @since 0.10.0
+ */
 export function getActiveContainer() {
     return activeContainer;
 }

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

@@ -1,15 +1,17 @@
 /**
- * The fluent chain `bind()` returns: it registers the binding and refines it in place.
+ * The fluent chain `bind()` returns, which is also the binding it registers.
  *
- * @remarks One object plays every role in the chain; the return type of each step is what pins the
- * order, so no runtime check has to.
+ * @remarks One object plays every role: each builder step, the record the registry stores, and the
+ * binding the resolver reads. The binding fields are declared first and in a fixed order, so every
+ * binding in the process shares one hidden class; the return type of each step is what pins the
+ * chain's order, so no runtime check has to.
  */
-import type { AliasBindingBuilder, BindingBuilder, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#/core/binding";
+import type { AliasBindingBuilder, BindingBuilder, BindingSlot, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#/core/binding";
 import type { BindingRegistry } from "#/core/registry";
 import type { BindingTag } from "#/core/tag";
 import type { Token } from "#/core/token";
-import type { ActivationHandler, BindingConstraint, BindingIdentifier, Constructor, DeactivationHandler, ResolutionContext } from "#/core/types";
-import type { InjectableDependency, ResolvedDependencyValue } from "#/injection/descriptor";
+import type { ActivationHandler, BindingConstraint, BindingIdentifier, BindingKind, BindingScope, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame } from "#/core/types";
+import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/injection/descriptor";
 import type { ScopeManager } from "#/lifecycle/scope-manager";
 /**
  * Where a chain registers, and on whose behalf.
@@ -25,30 +27,50 @@ export interface BindingRegistration {
     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.
+ * The one builder behind `bind()` and every `to*()` return type — and the binding it registers.
+ *
+ * @remarks The binding fields come first, in the order every binding shares, and the chain's own
+ * bookkeeping follows as private fields; `to*()` fills the fields in place and hands this object to
+ * the registry, so a plain bind is one allocation. Refinements write the registered object: a scope
+ * or hook in place, a slot or predicate through the registry so its indexes follow.
  *
  * @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> {
+export declare class BindingChain<Value, Names extends string = string> implements AliasBindingBuilder<Names>, BindingBuilder<Value, Names>, BindToBuilder<Value, Names>, ConstantBindingBuilder<Value, Names>, 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>;
+    kind: BindingKind;
+    readonly identifier: BindingIdentifier;
+    inFlight: boolean;
+    frame: ResolutionFrame | undefined;
+    instance: unknown;
+    readonly token: Token<Value, Names> | Constructor<Value>;
+    slot: BindingSlot;
+    predicate: BindingConstraint | undefined;
+    isMany: boolean;
+    scope: BindingScope;
+    target: unknown;
+    factory: unknown;
+    deps: ReadonlyArray<InjectionDescriptor> | undefined;
+    value: unknown;
+    activationHook: ActivationHandler<Value> | undefined;
+    deactivationHook: DeactivationHandler<Value> | undefined;
+    constructor(token: Token<Value, Names> | Constructor<Value>, registration: BindingRegistration);
+    to(type: Constructor<Value>): BindingBuilder<Value, Names>;
+    toSelf(): BindingBuilder<Value, Names>;
+    toConstantValue(value: Value): ConstantBindingBuilder<Value, Names>;
+    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value, Names>;
+    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value, Names>;
     toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
         [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
-    }) => Value, deps: Deps): BindingBuilder<Value>;
+    }) => Value, deps: Deps): BindingBuilder<Value, Names>;
     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;
+    }) => Promise<Value>, deps: Deps): BindingBuilder<Value, Names>;
+    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder<Names>;
     when(predicate: BindingConstraint): this;
-    whenNamed(name: string): this;
+    whenNamed(name: Names): this;
     whenTagged(criterion: BindingTag): this;
+    many(): this;
     whenDefault(): this;
     singleton(): SingletonBindingBuilder<Value>;
     transient(): TransientBindingBuilder<Value>;