@codefast/di 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @codefast/di
 
+## 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();
 });

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

@@ -31,23 +31,23 @@ export interface BindingRegistration {
  *
  * @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>;
+    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;
     whenDefault(): this;
     singleton(): SingletonBindingBuilder<Value>;

package/dist/container/container.d.ts

@@ -13,12 +13,12 @@ import type { MetadataReader } from "#/metadata/metadata-types";
  */
 export interface Container {
     readonly isDisposed: boolean;
-    bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+    bind<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>): BindToBuilder<Value, Names>;
     unbind(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): void;
     unbindAsync(tokenOrId: Token<unknown> | Constructor | BindingIdentifier): Promise<void>;
     unbindAll(): void;
     unbindAllAsync(): Promise<void>;
-    rebind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+    rebind<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>): BindToBuilder<Value, Names>;
     load(...modules: Array<SyncModule>): void;
     loadAsync(...modules: Array<SyncModule | AsyncModule>): Promise<void>;
     unload(...modules: Array<SyncModule>): void;
@@ -26,20 +26,20 @@ export interface Container {
     loadAutoRegistered(registry: AutoRegisterRegistry): number;
     onActivation<Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void;
     onDeactivation<Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void;
-    resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
-    resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
-    resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
-    resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+    resolve<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Value;
+    resolveAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Value>;
+    resolveOptional<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Value | undefined;
+    resolveOptionalAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Value | undefined>;
+    resolveAll<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Array<Value>;
+    resolveAllAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Array<Value>>;
     createChild(): Container;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
     [Symbol.dispose](): never;
     initializeAsync(): Promise<void>;
     validate(): void;
-    has(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean;
-    hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean;
+    has<Names extends string = string>(token: Token<unknown, Names> | Constructor, options?: NoInfer<ResolveOptions<Names>>): boolean;
+    hasOwn<Names extends string = string>(token: Token<unknown, Names> | Constructor, options?: NoInfer<ResolveOptions<Names>>): boolean;
     lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
     inspect(): ContainerSnapshot;
     generateDependencyGraph(options?: GraphOptions): ContainerGraphJson;

package/dist/container/container.js

@@ -2,7 +2,7 @@ import { BindingChain } from "#/container/binding-builders";
 import { NO_INSTANCE } from "#/core/binding";
 import { effectiveBindingScope } from "#/core/binding-scope";
 import { constraintRequirementsOf } from "#/core/constraint-requirement";
-import { getOrInsert } from "#/core/map-upsert";
+import { getOrInsert, getOrInsertComputed } from "#/core/map-upsert";
 import { isSyncModule, MODULE_SETUP } from "#/core/module";
 import { BindingRegistry } from "#/core/registry";
 import { tokenName } from "#/core/token";
@@ -18,6 +18,20 @@ import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
 import { verifyingMetadataReader } from "#/metadata/verifying-metadata-reader";
 import { ROOT_BRANCH } from "#/resolution/path/resolution-path";
 import { DependencyResolver } from "#/resolution/resolver";
+/** Whether a requirement's name is declared — on its token when it names one, on any token otherwise. */
+function isSlotNameDeclared(declared, requirement) {
+    if (requirement.tokenName !== undefined) {
+        return declared.get(requirement.tokenName)?.has(requirement.name) ?? false;
+    }
+    for (const names of declared.values()) {
+        if (names.has(requirement.name)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Hoisted so the slot-name index's `getOrInsertComputed` allocates only on a miss, no closure per call. */
+const newSlotNameSet = () => new Set();
 // A Record rather than an if-chain, so a new `BindingScope` is a compile error here instead of
 // silently landing in whichever branch happened to be last.
 const APPLY_BINDING_SCOPE = {
@@ -552,18 +566,19 @@ class DefaultContainer {
             }
             declaredSlotNames ??= this.#slotNamesInChain();
             for (const requirement of requirements) {
-                if (!declaredSlotNames.has(requirement.name)) {
-                    throw new UnreachableConstraintError(tokenName(binding.token), requirement.name, requirement.helperName);
+                if (!isSlotNameDeclared(declaredSlotNames, requirement)) {
+                    throw new UnreachableConstraintError(tokenName(binding.token), requirement);
                 }
             }
         }
     }
-    /** Every slot name declared anywhere a resolve through this container could reach. */
+    /** Every slot name declared anywhere a resolve through this container could reach, by declaring token. */
     #slotNamesInChain() {
-        const names = this.#parent === undefined ? new Set() : this.#parent.#slotNamesInChain();
+        const names = this.#parent === undefined ? new Map() : this.#parent.#slotNamesInChain();
         for (const binding of this.#registry.allBindings()) {
-            if (binding.slot.name !== undefined) {
-                names.add(binding.slot.name);
+            const name = binding.slot.name;
+            if (name !== undefined) {
+                getOrInsertComputed(names, tokenName(binding.token), newSlotNameSet).add(name);
             }
         }
         return names;

package/dist/core/binding.d.ts

@@ -248,11 +248,16 @@ export declare function clearBindingFrame<Value>(binding: Binding<Value>): void;
  *
  * @since 0.3.16-canary.0
  */
-export interface SlotConstrainedBuilder {
+export interface SlotConstrainedBuilder<Names extends string = string> {
+    /** Narrows the binding to requests the predicate accepts, evaluated on every resolve. */
     when(predicate: BindingConstraint): this;
-    whenNamed(name: string): this;
+    /** Declares the binding's slot name, one of the names the token declares. */
+    whenNamed(name: Names): this;
+    /** Declares one criterion of the binding's slot, replacing any earlier criterion of the same key. */
     whenTagged(criterion: BindingTag): this;
+    /** Keeps the binding on the default slot, the one an unconstrained request selects. */
     whenDefault(): this;
+    /** The identifier this binding is registered under. */
     id(): BindingIdentifier;
 }
 /**
@@ -260,26 +265,26 @@ export interface SlotConstrainedBuilder {
  *
  * @since 0.3.16-canary.0
  */
-export interface BindToBuilder<Value> {
-    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>;
+export interface BindToBuilder<Value, Names extends string = string> {
+    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>;
 }
 /**
  * The scope-selection step of the fluent chain.
  *
  * @since 0.3.16-canary.0
  */
-export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
+export interface BindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
     singleton(): SingletonBindingBuilder<Value>;
     transient(): TransientBindingBuilder<Value>;
     scoped(): ScopedBindingBuilder<Value>;
@@ -289,7 +294,7 @@ export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
  *
  * @since 0.3.16-canary.0
  */
-export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
+export interface ConstantBindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
     onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
     onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
 }
@@ -298,7 +303,7 @@ export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
  *
  * @since 0.3.16-canary.0
  */
-export interface AliasBindingBuilder extends SlotConstrainedBuilder {
+export interface AliasBindingBuilder<Names extends string = string> extends SlotConstrainedBuilder<Names> {
 }
 /**
  * The fluent chain after `singleton()`, where both lifecycle hooks stay available.

package/dist/core/constraint-requirement.d.ts

@@ -12,23 +12,38 @@ export declare const CONSTRAINT_REQUIREMENT: unique symbol;
 /**
  * The slot name a constraint waits for on an ancestor.
  *
- * @remarks Only names are described. A tag criterion is interned, so a typo cannot produce one that
- * looks valid, while a name is a bare string that nothing checks.
+ * @remarks Only names are described, however spelled: a tag criterion of any other key is minted from
+ * a typed key, so a typo cannot produce one that looks valid, while a name is a bare string that
+ * nothing checks — through `whenNamed`'s reserved key included.
  *
  * @since 0.6.0
  */
 export interface ConstraintRequirement {
     readonly requires: "ancestorSlotName";
+    /** The token whose slot must carry the name, or `undefined` when the spelling named no token. */
+    readonly tokenName: string | undefined;
     readonly name: string;
     /** The helper that built the predicate, so a report can name what the caller wrote. */
     readonly helperName: string;
 }
 /**
- * Records what a predicate waits for. Called once, where the predicate is built.
+ * What a helper records about one waited-for slot name, before the discriminant is stamped on.
+ *
+ * @since 0.9.0
+ */
+export type SlotNameRequirement = Omit<ConstraintRequirement, "requires">;
+/**
+ * Records the one slot name a predicate waits for. Called once, where the predicate is built.
  *
  * @since 0.6.0
  */
-export declare function requiringAncestorSlotName(predicate: BindingConstraint, name: string, helperName: string): BindingConstraint;
+export declare function requiringAncestorSlotName(predicate: BindingConstraint, requirement: SlotNameRequirement): BindingConstraint;
+/**
+ * Records every slot name a predicate waits for — one per reserved criterion in a `…TaggedAll` list.
+ *
+ * @since 0.9.0
+ */
+export declare function requiringAncestorSlotNames(predicate: BindingConstraint, requirements: ReadonlyArray<SlotNameRequirement>): BindingConstraint;
 /**
  * The requirement a predicate carries, if it was built by a helper that records one.
  *

package/dist/core/constraint-requirement.js

@@ -8,13 +8,27 @@
  */
 export const CONSTRAINT_REQUIREMENT = Symbol("di:constraint-requirement");
 /**
- * Records what a predicate waits for. Called once, where the predicate is built.
+ * Records the one slot name a predicate waits for. Called once, where the predicate is built.
  *
  * @since 0.6.0
  */
-export function requiringAncestorSlotName(predicate, name, helperName) {
-    const requirement = { requires: "ancestorSlotName", name, helperName };
-    Object.defineProperty(predicate, CONSTRAINT_REQUIREMENT, { value: requirement, enumerable: false });
+export function requiringAncestorSlotName(predicate, requirement) {
+    return requiringAncestorSlotNames(predicate, [requirement]);
+}
+/**
+ * Records every slot name a predicate waits for — one per reserved criterion in a `…TaggedAll` list.
+ *
+ * @since 0.9.0
+ */
+export function requiringAncestorSlotNames(predicate, requirements) {
+    return attachRequirements(predicate, requirements.map((requirement) => ({ requires: "ancestorSlotName", ...requirement })));
+}
+/** One non-enumerable write per predicate: a second define on the same key would throw. */
+function attachRequirements(predicate, requirements) {
+    Object.defineProperty(predicate, CONSTRAINT_REQUIREMENT, {
+        value: requirements.length === 1 ? requirements[0] : requirements,
+        enumerable: false,
+    });
     return predicate;
 }
 /**
@@ -53,9 +67,5 @@ export function mergingConstraintRequirements(composite, left, right) {
     if (merged.length === 0) {
         return composite;
     }
-    Object.defineProperty(composite, CONSTRAINT_REQUIREMENT, {
-        value: merged.length === 1 ? merged[0] : merged,
-        enumerable: false,
-    });
-    return composite;
+    return attachRequirements(composite, merged);
 }

package/dist/core/tag.d.ts

@@ -59,12 +59,12 @@ export interface TagKey<Value = unknown> {
 /**
  * Declares a tag key, whose `of()` builds the criteria a `whenTagged` and a resolve both take.
  *
- * @remarks The value type is checked at both ends: a key declared `tag<Region>("region")` refuses a
+ * @remarks The value type is checked at both ends: a key declared `tag<Region>("di:region")` refuses a
  * value that is not a `Region`, so a bind site and a resolve site cannot drift apart silently.
  *
  * @example
  * ```ts
- * const Region = tag<"eu" | "us">("region");
+ * const Region = tag<"eu" | "us">("di:region");
  * container.bind(Storage).to(S3).whenTagged(Region.of("eu"));
  * container.resolve(Storage, { tag: Region.of("eu") });
  * ```

package/dist/core/tag.js

@@ -27,12 +27,12 @@ function internKeyFor(value) {
 /**
  * Declares a tag key, whose `of()` builds the criteria a `whenTagged` and a resolve both take.
  *
- * @remarks The value type is checked at both ends: a key declared `tag<Region>("region")` refuses a
+ * @remarks The value type is checked at both ends: a key declared `tag<Region>("di:region")` refuses a
  * value that is not a `Region`, so a bind site and a resolve site cannot drift apart silently.
  *
  * @example
  * ```ts
- * const Region = tag<"eu" | "us">("region");
+ * const Region = tag<"eu" | "us">("di:region");
  * container.bind(Storage).to(S3).whenTagged(Region.of("eu"));
  * container.resolve(Storage, { tag: Region.of("eu") });
  * ```

package/dist/core/token.d.ts

@@ -1,20 +1,40 @@
 import type { Constructor } from "#/core/constructor-type";
 declare const TOKEN_BRAND: unique symbol;
+declare const TOKEN_NAMES_BRAND: unique symbol;
 /**
- * A branded identifier carrying the value type its bindings resolve to.
+ * A branded identifier carrying the value type its bindings resolve to, and the slot names they may declare.
+ *
+ * @remarks `Names` exists at the type level only: `whenNamed`, and `name` in `ResolveOptions` and
+ * `InjectOptions`, narrow to it, so a bind site and a request site cannot drift apart silently. It
+ * is covariant, so a token declaring names is still a `Token<unknown>` wherever the engine erases
+ * the value type; the default `string` leaves a token that declares none unconstrained.
+ *
+ * @example
+ * ```ts
+ * const Logger = token<Logger, "console" | "file">("di:Logger");
+ * container.bind(Logger).to(FileLogger).whenNamed("file");
+ * container.resolve(Logger, { name: "file" });
+ * ```
  *
  * @since 0.3.16-canary.0
  */
-export interface Token<out Value> {
+export interface Token<out Value, out Names extends string = string> {
     readonly name: string;
     readonly [TOKEN_BRAND]: Value;
+    readonly [TOKEN_NAMES_BRAND]?: Names;
 }
 /**
- * Creates a named `Token` for the given value type.
+ * The slot names a dependency key declares — `string` for a class, or a token that declares none.
+ *
+ * @since 0.9.0
+ */
+export type SlotNamesOf<Key> = Key extends Token<unknown, infer Names extends string> ? Names : string;
+/**
+ * Creates a named `Token` for the given value type, optionally declaring the slot names its bindings may use.
  *
  * @since 0.3.16-canary.0
  */
-export declare function token<Value>(name: string): Token<Value>;
+export declare function token<Value, Names extends string = string>(name: string): Token<Value, Names>;
 /**
  * Returns the display name of a token or class used as a dependency key.
  *

package/dist/core/token.js

@@ -1,5 +1,5 @@
 /**
- * Creates a named `Token` for the given value type.
+ * Creates a named `Token` for the given value type, optionally declaring the slot names its bindings may use.
  *
  * @since 0.3.16-canary.0
  */

package/dist/core/types.d.ts

@@ -47,8 +47,14 @@ export type DeactivationHandler<Value> = (instance: Value) => void | Promise<voi
  *
  * @since 0.3.16-canary.0
  */
-export interface ResolveOptions {
-    name?: string | undefined;
+export interface ResolveOptions<Names extends string = string> {
+    /**
+     * The slot name a binding declared with `whenNamed`.
+     *
+     * @remarks Narrowed to the names the token declares, so a request cannot ask for a name no
+     * binding could carry; a token declaring none takes any string.
+     */
+    name?: Names | undefined;
     /**
      * Single-tag shorthand, equivalent to listing the one pair in `tags`.
      *

package/dist/decorators/inject.d.ts

@@ -8,5 +8,5 @@ type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget
  *
  * @since 0.3.16-canary.0
  */
-export declare function inject<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
+export declare function inject<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
 export {};

package/dist/decorators/inject.js

@@ -30,6 +30,8 @@ export function inject(token, options) {
     // Derived from the descriptor, not from `options`: the descriptor is where the tag shorthand has
     // already been folded. Built once here rather than per constructed instance.
     const resolveOptions = injectionSlotToResolveOptions(descriptor);
+    // The names are checked above; the container lane only needs the value type.
+    const resolveKey = token;
     const decoratorFn = (_target, context) => {
         if (context.static) {
             throw new StaticMemberDecoratorError("inject", String(context.name));
@@ -50,8 +52,8 @@ export function inject(token, options) {
             const ambient = getAmbientResolution();
             if (ambient !== undefined) {
                 const value = descriptor.optional
-                    ? ambient.resolveOptional(token, resolveOptions)
-                    : ambient.resolve(token, resolveOptions);
+                    ? ambient.resolveOptional(resolveKey, resolveOptions)
+                    : ambient.resolve(resolveKey, resolveOptions);
                 context.access.set(this, value);
                 return;
             }
@@ -60,8 +62,8 @@ export function inject(token, options) {
                 throw new MissingContainerContextError(classNameOf(this), context.name);
             }
             const value = descriptor.optional
-                ? container.resolveOptional(token, resolveOptions)
-                : container.resolve(token, resolveOptions);
+                ? container.resolveOptional(resolveKey, resolveOptions)
+                : container.resolve(resolveKey, resolveOptions);
             context.access.set(this, value);
         });
         return {};

package/dist/errors/errors.d.ts

@@ -1,3 +1,4 @@
+import type { ConstraintRequirement } from "#/core/constraint-requirement";
 import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/core/types";
 /**
  * Base class for every error the library throws, each carrying a machine-readable `code`.
@@ -132,8 +133,10 @@ export declare class UnreachableConstraintError extends DiError {
     readonly code = "UNREACHABLE_CONSTRAINT";
     readonly tokenName: string;
     readonly requiredName: string;
+    /** The token the name was required on, or `undefined` when the constraint named no token. */
+    readonly requiredTokenName: string | undefined;
     readonly helperName: string;
-    constructor(tokenName: string, requiredName: string, helperName: string);
+    constructor(tokenName: string, requirement: ConstraintRequirement);
 }
 /**
  * A container-level lifecycle hook whose token nothing is bound to, so it can never run.

package/dist/errors/errors.js

@@ -191,11 +191,17 @@ export class UnreachableConstraintError extends DiError {
     code = "UNREACHABLE_CONSTRAINT";
     tokenName;
     requiredName;
+    /** The token the name was required on, or `undefined` when the constraint named no token. */
+    requiredTokenName;
     helperName;
-    constructor(tokenName, requiredName, helperName) {
-        super(`The binding for '${tokenName}' is constrained by ${helperName}('${requiredName}'), but no binding in this container or its ancestors declares the slot name '${requiredName}', so the constraint can never hold. Name the slot with .whenNamed('${requiredName}') on the binding it should match, or correct the name here.`);
+    constructor(tokenName, requirement) {
+        const { name, helperName, tokenName: requiredTokenName } = requirement;
+        const scope = requiredTokenName === undefined ? "no binding" : `no binding for '${requiredTokenName}'`;
+        const target = requiredTokenName === undefined ? "the binding it should match" : `a '${requiredTokenName}' binding`;
+        super(`The binding for '${tokenName}' is constrained by ${helperName} waiting on the slot name '${name}', but ${scope} in this container or its ancestors declares it, so the constraint can never hold. Name the slot with .whenNamed('${name}') on ${target}, or correct the name here.`);
         this.tokenName = tokenName;
-        this.requiredName = requiredName;
+        this.requiredName = name;
+        this.requiredTokenName = requiredTokenName;
         this.helperName = helperName;
     }
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { ActivationHandler, BindingConstraint, BindingIdentifier, BindingKind, BindingScope, BindingTag, ConstraintContext, Constructor, DependencyKey, DeactivationHandler, ResolutionFrame, ResolveOptions, ResolutionContext, TokenValue, } from "#/core/types";
 export { token, tokenName } from "#/core/token";
-export type { Token } from "#/core/token";
+export type { SlotNamesOf, Token } from "#/core/token";
 export { coversTagKeys, NO_TAG_KEYS, slotName, tag, tagKeyMaskOf } from "#/core/tag";
 export type { TagKey, TagKeyMask } from "#/core/tag";
 export type { AliasBindingBuilder, BindToBuilder, BindingBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, SlotConstrainedBuilder, TransientBindingBuilder, } from "#/core/binding";

package/dist/injection/descriptor.d.ts

@@ -7,8 +7,14 @@ import type { DependencySlot } from "#/injection/resolve-options";
  *
  * @since 0.3.16-canary.0
  */
-export interface InjectOptions {
-    name?: string | undefined;
+export interface InjectOptions<Names extends string = string> {
+    /**
+     * The slot name a binding declared with `whenNamed`.
+     *
+     * @remarks Narrowed to the names the token declares, so a dependency cannot ask for a name no
+     * binding could carry; a token declaring none takes any string.
+     */
+    name?: Names | undefined;
     /**
      * Single-tag shorthand, equivalent to listing the one pair in `tags`.
      *
@@ -74,17 +80,17 @@ export declare function normalizeToDescriptor(dependency: InjectableDependency):
  *
  * @since 0.6.0
  */
-export declare function buildInjectionDescriptor<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value>;
+export declare function buildInjectionDescriptor<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Value>;
 /**
  * Creates a descriptor that resolves to `undefined` instead of throwing when no binding matches.
  *
  * @since 0.3.16-canary.0
  */
-export declare function optional<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value | undefined>;
+export declare function optional<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Value | undefined>;
 /**
  * Creates a descriptor that resolves every matching binding for the token into an array.
  *
  * @since 0.3.16-canary.0
  */
-export declare function injectAll<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Array<Value>>;
+export declare function injectAll<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<InjectOptions<Names>>): InjectionDescriptor<Array<Value>>;
 export {};

package/dist/metadata/metadata-reader-token.js

@@ -4,4 +4,4 @@ import { token } from "#/core/token";
  *
  * @since 0.3.16-canary.0
  */
-export const MetadataReaderToken = token("MetadataReader");
+export const MetadataReaderToken = token("di:MetadataReader");

package/dist/resolution/select/constraints.d.ts

@@ -26,17 +26,20 @@ export declare function whenAnyAncestorIs(token: Token<unknown> | Constructor):
  */
 export declare function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingConstraint;
 /**
- * Matches when the direct parent slot carries the given name.
+ * Matches when the direct parent resolves the given token at the slot carrying the given name.
+ *
+ * @remarks A slot name is a label on one token's bindings, so the token is part of the question — and
+ * what types `name` to the names that token declares.
  *
  * @since 0.3.16-canary.0
  */
-export declare function whenParentNamed(name: string): BindingConstraint;
+export declare function whenParentNamed<Names extends string>(token: Token<unknown, Names> | Constructor, name: NoInfer<Names>): BindingConstraint;
 /**
- * Matches when at least one ancestor slot carries the given name.
+ * Matches when at least one ancestor resolves the given token at the slot carrying the given name.
  *
  * @since 0.3.16-canary.0
  */
-export declare function whenAnyAncestorNamed(name: string): BindingConstraint;
+export declare function whenAnyAncestorNamed<Names extends string>(token: Token<unknown, Names> | Constructor, name: NoInfer<Names>): BindingConstraint;
 /**
  * Matches when the direct parent slot carries the given tag pair.
  *

package/dist/resolution/select/constraints.js

@@ -1,5 +1,5 @@
-import { requiringAncestorSlotName } from "#/core/constraint-requirement";
-import { coversTagKeys, tagKeyMaskOf } from "#/core/tag";
+import { requiringAncestorSlotName, requiringAncestorSlotNames } from "#/core/constraint-requirement";
+import { coversTagKeys, slotName, tagKeyMaskOf } from "#/core/tag";
 import { tokenName } from "#/core/token";
 import { EmptyTagCriteriaError } from "#/errors/errors";
 /**
@@ -39,20 +39,27 @@ export function whenNoAncestorIs(token) {
     return (constraintContext) => constraintContext.ancestors.every((ancestorFrame) => ancestorFrame.tokenName !== tokenDisplayName);
 }
 /**
- * Matches when the direct parent slot carries the given name.
+ * Matches when the direct parent resolves the given token at the slot carrying the given name.
+ *
+ * @remarks A slot name is a label on one token's bindings, so the token is part of the question — and
+ * what types `name` to the names that token declares.
  *
  * @since 0.3.16-canary.0
  */
-export function whenParentNamed(name) {
-    return requiringAncestorSlotName((constraintContext) => constraintContext.parent !== undefined && constraintContext.parent.slot.name === name, name, "whenParentNamed");
+export function whenParentNamed(token, name) {
+    const parentTokenName = tokenName(token);
+    return requiringAncestorSlotName((constraintContext) => constraintContext.parent !== undefined &&
+        constraintContext.parent.tokenName === parentTokenName &&
+        constraintContext.parent.slot.name === name, { tokenName: parentTokenName, name, helperName: "whenParentNamed" });
 }
 /**
- * Matches when at least one ancestor slot carries the given name.
+ * Matches when at least one ancestor resolves the given token at the slot carrying the given name.
  *
  * @since 0.3.16-canary.0
  */
-export function whenAnyAncestorNamed(name) {
-    return requiringAncestorSlotName((constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.name === name), name, "whenAnyAncestorNamed");
+export function whenAnyAncestorNamed(token, name) {
+    const ancestorTokenName = tokenName(token);
+    return requiringAncestorSlotName((constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.tokenName === ancestorTokenName && ancestorFrame.slot.name === name), { tokenName: ancestorTokenName, name, helperName: "whenAnyAncestorNamed" });
 }
 /**
  * Matches when the direct parent slot carries the given tag pair.
@@ -60,7 +67,7 @@ export function whenAnyAncestorNamed(name) {
  * @since 0.3.16-canary.0
  */
 export function whenParentTagged(criterion) {
-    return (constraintContext) => constraintContext.parent !== undefined && constraintContext.parent.slot.tags.includes(criterion);
+    return requiringReservedNamesAmong((constraintContext) => constraintContext.parent !== undefined && constraintContext.parent.slot.tags.includes(criterion), [criterion], "whenParentTagged");
 }
 /**
  * Matches when at least one ancestor slot carries the given tag pair.
@@ -68,7 +75,7 @@ export function whenParentTagged(criterion) {
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorTagged(criterion) {
-    return (constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.tags.includes(criterion));
+    return requiringReservedNamesAmong((constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.tags.includes(criterion)), [criterion], "whenAnyAncestorTagged");
 }
 /**
  * Matches when the direct parent slot carries **all** of the given tag pairs.
@@ -80,13 +87,13 @@ export function whenAnyAncestorTagged(criterion) {
 export function whenParentTaggedAll(tags) {
     assertHasCriteria(tags, "whenParentTaggedAll");
     const wanted = tagKeyMaskOf(tags);
-    return (constraintContext) => {
+    return requiringReservedNamesAmong((constraintContext) => {
         const { parent } = constraintContext;
         if (parent === undefined || !coversTagKeys(parent.slot.keyMask, wanted)) {
             return false;
         }
         return tags.every((criterion) => parent.slot.tags.includes(criterion));
-    };
+    }, tags, "whenParentTaggedAll");
 }
 /**
  * Matches when at least one ancestor slot carries **all** of the given tag pairs.
@@ -98,7 +105,21 @@ export function whenParentTaggedAll(tags) {
 export function whenAnyAncestorTaggedAll(tags) {
     assertHasCriteria(tags, "whenAnyAncestorTaggedAll");
     const wanted = tagKeyMaskOf(tags);
-    return (constraintContext) => constraintContext.ancestors.some((frame) => coversTagKeys(frame.slot.keyMask, wanted) && tags.every((criterion) => frame.slot.tags.includes(criterion)));
+    return requiringReservedNamesAmong((constraintContext) => constraintContext.ancestors.some((frame) => coversTagKeys(frame.slot.keyMask, wanted) && tags.every((criterion) => frame.slot.tags.includes(criterion))), tags, "whenAnyAncestorTaggedAll");
+}
+/**
+ * Records a requirement for every reserved-key criterion in a list, so a name spelled through the tag
+ * lane is validated exactly as one spelled through `whenNamed`.
+ */
+function requiringReservedNamesAmong(predicate, tags, helperName) {
+    let requirements;
+    for (const criterion of tags) {
+        if (criterion.key === slotName) {
+            requirements ??= [];
+            requirements.push({ tokenName: undefined, name: criterion.value, helperName });
+        }
+    }
+    return requirements === undefined ? predicate : requiringAncestorSlotNames(predicate, requirements);
 }
 /**
  * Refuses a criteria list with nothing in it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/di",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Lightweight dependency injection primitives for Codefast",
   "keywords": [
     "codefast",
@@ -9,8 +9,12 @@
     "inversion-of-control",
     "typescript"
   ],
+  "homepage": "https://github.com/codefastlabs/codefast/tree/main/packages/di#readme",
+  "bugs": {
+    "url": "https://github.com/codefastlabs/codefast/issues"
+  },
   "license": "MIT",
-  "author": "Vuong Phan <mr.thevuong@gmail.com>",
+  "author": "Vuong Phan <mr.thevuong@gmail.com> (https://github.com/thevuong)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/codefastlabs/codefast.git",
@@ -28,20 +32,6 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "imports": {
-    "#/tests/*": [
-      "./tests/*",
-      "./tests/*.ts",
-      "./tests/*.tsx",
-      "./tests/*/index.ts",
-      "./tests/*/index.tsx"
-    ],
-    "#/examples/*": [
-      "./examples/*",
-      "./examples/*.ts",
-      "./examples/*.tsx",
-      "./examples/*/index.ts",
-      "./examples/*/index.tsx"
-    ],
     "#/*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
@@ -225,31 +215,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@babel/core": "^8.0.1",
-    "@babel/plugin-proposal-decorators": "8.0.2",
-    "@rolldown/plugin-babel": "^0.2.3",
-    "@types/node": "^26.4.1",
-    "@vitest/coverage-v8": "^5.0.0",
-    "tsx": "^4.23.13",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
-    "@codefast/typescript-config": "0.9.0"
-  },
   "engines": {
     "node": ">=24.0.0"
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "check-types": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "examples": "node examples/run.mjs",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "vitest run tests/e2e",
-    "test:integration": "vitest run tests/integration",
-    "test:type": "vitest run tests/types",
-    "test:unit": "vitest run tests/unit",
-    "test:watch": "vitest"
   }
 }