@codefast/di 0.11.0 → 0.12.0

package/dist/resolution/select/{binding-select.d.ts → candidates.d.ts}

@@ -9,6 +9,36 @@ import type { ConstraintContext, ResolveOptions } from "#core/types";
  * @since 0.3.16-canary.0
  */
 export declare function selectBinding(bindings: ReadonlyArray<Binding>, options: ResolveOptions | undefined, ctx: ConstraintContext, tokenDisplayName: string): Binding | undefined;
+/**
+ * The rule that settles a request's eligible candidates, in the order selection applies them.
+ *
+ * @remarks `sole-candidate`: one candidate is eligible. `sole-predicate`: the only candidate carrying a `when()`
+ * predicate beats those without. `most-criteria`: the slot declaring more criteria than every other wins.
+ * `ambiguous`: a tie, which `resolve` reports as `AmbiguousBindingError`.
+ *
+ * @since 0.12.0
+ */
+export type CandidateRule = "sole-candidate" | "sole-predicate" | "most-criteria" | "ambiguous";
+/**
+ * The candidate a non-empty eligible list settles on, or `undefined` for a tie — the one decision `resolve` and
+ * `explain()` share.
+ *
+ * @remarks Most specific wins, predicate before criterion count: a lone predicate-carrying candidate
+ * is a deliberate specialization of the default, and a slot declaring more of what the request
+ * carries is the more specific match, so an over-specified request resolves instead of tying.
+ *
+ * @since 0.12.0
+ */
+export declare function chooseCandidate(candidates: ReadonlyArray<Binding>): Binding | undefined;
+/**
+ * The rule behind what {@link chooseCandidate} returned for the same list, read off its answer.
+ *
+ * @remarks Kept beside the decision and derived from it, so the order lives in one function and resolve
+ * pays nothing for the label.
+ *
+ * @since 0.12.0
+ */
+export declare function candidateRuleOf(candidates: ReadonlyArray<Binding>, chosen: Binding | undefined): CandidateRule;
 /**
  * Selects all candidates matching options + predicates.
  *

package/dist/resolution/select/{binding-select.js → candidates.js}

@@ -1,5 +1,5 @@
 import { coversTagKeys, NO_TAG_KEYS, slotName, slotNameCriterionOf } from "#core/tag";
-import { AmbiguousBindingError } from "#errors/errors";
+import { AmbiguousBindingError } from "#errors";
 /**
  * The single candidate a request selects from a list, by slot match then predicate.
  *
@@ -15,9 +15,26 @@ export function selectBinding(bindings, options, ctx, tokenDisplayName) {
     if (candidates.length === 1) {
         return candidates[0];
     }
-    // Most specific wins, predicate before tag count: a lone predicate-carrying candidate beats
-    // predicate-less ones, a predicate being a deliberate specialization of the default. This order is
-    // what keeps every resolution that already succeeds deciding the same way.
+    const chosen = chooseCandidate(candidates);
+    if (chosen !== undefined) {
+        return chosen;
+    }
+    throw new AmbiguousBindingError(tokenDisplayName, candidates.map((c) => c.identifier));
+}
+/**
+ * The candidate a non-empty eligible list settles on, or `undefined` for a tie — the one decision `resolve` and
+ * `explain()` share.
+ *
+ * @remarks Most specific wins, predicate before criterion count: a lone predicate-carrying candidate
+ * is a deliberate specialization of the default, and a slot declaring more of what the request
+ * carries is the more specific match, so an over-specified request resolves instead of tying.
+ *
+ * @since 0.12.0
+ */
+export function chooseCandidate(candidates) {
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
     let predicatedCandidate;
     for (const candidate of candidates) {
         if (candidate.predicate !== undefined) {
@@ -31,13 +48,37 @@ export function selectBinding(bindings, options, ctx, tokenDisplayName) {
     if (predicatedCandidate !== undefined) {
         return predicatedCandidate;
     }
-    // Reached only where the throw was: a slot declaring more of what the request carries is the more
-    // specific match, so an over-specified request resolves instead of being ambiguous.
-    const mostSpecific = mostSpecificByCriterionCount(candidates);
-    if (mostSpecific !== undefined) {
-        return mostSpecific;
+    return mostSpecificByCriterionCount(candidates);
+}
+/**
+ * The rule behind what {@link chooseCandidate} returned for the same list, read off its answer.
+ *
+ * @remarks Kept beside the decision and derived from it, so the order lives in one function and resolve
+ * pays nothing for the label.
+ *
+ * @since 0.12.0
+ */
+export function candidateRuleOf(candidates, chosen) {
+    if (chosen === undefined) {
+        return "ambiguous";
     }
-    throw new AmbiguousBindingError(tokenDisplayName, candidates.map((c) => c.identifier));
+    if (candidates.length === 1) {
+        return "sole-candidate";
+    }
+    return solePredicatedCandidate(candidates) === chosen ? "sole-predicate" : "most-criteria";
+}
+/** The one candidate carrying a predicate, or `undefined` when none or several do. */
+function solePredicatedCandidate(candidates) {
+    let predicatedCandidate;
+    for (const candidate of candidates) {
+        if (candidate.predicate !== undefined) {
+            if (predicatedCandidate !== undefined) {
+                return undefined;
+            }
+            predicatedCandidate = candidate;
+        }
+    }
+    return predicatedCandidate;
 }
 /** The lone candidate declaring more criteria than every other, or `undefined` when that is a tie. */
 function mostSpecificByCriterionCount(candidates) {

package/dist/resolution/select/constraints.js

@@ -1,7 +1,7 @@
 import { requiringAncestorSlotName, requiringAncestorSlotNames } from "#core/constraint-requirement";
 import { coversTagKeys, slotName, tagKeyMaskOf } from "#core/tag";
 import { tokenName } from "#core/token";
-import { EmptyTagCriteriaError } from "#errors/errors";
+import { EmptyTagCriteriaError } from "#errors";
 /**
  * Matches when the direct parent frame resolves the given token.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/di",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Lightweight dependency injection primitives for Codefast",
   "keywords": [
     "codefast",
@@ -42,13 +42,13 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./ambient/active-container": {
-      "types": "./dist/ambient/active-container.d.ts",
-      "import": "./dist/ambient/active-container.js"
+    "./ambient-container": {
+      "types": "./dist/ambient-container.d.ts",
+      "import": "./dist/ambient-container.js"
     },
-    "./container/binding-builders": {
-      "types": "./dist/container/binding-builders.d.ts",
-      "import": "./dist/container/binding-builders.js"
+    "./container/binding-chain": {
+      "types": "./dist/container/binding-chain.d.ts",
+      "import": "./dist/container/binding-chain.js"
     },
     "./container/container": {
       "types": "./dist/container/container.d.ts",
@@ -58,14 +58,14 @@
       "types": "./dist/core/binding.d.ts",
       "import": "./dist/core/binding.js"
     },
+    "./core/binding-builders": {
+      "types": "./dist/core/binding-builders.d.ts",
+      "import": "./dist/core/binding-builders.js"
+    },
     "./core/binding-declaration": {
       "types": "./dist/core/binding-declaration.d.ts",
       "import": "./dist/core/binding-declaration.js"
     },
-    "./core/binding-scope": {
-      "types": "./dist/core/binding-scope.d.ts",
-      "import": "./dist/core/binding-scope.js"
-    },
     "./core/constraint-requirement": {
       "types": "./dist/core/constraint-requirement.d.ts",
       "import": "./dist/core/constraint-requirement.js"
@@ -102,10 +102,6 @@
       "types": "./dist/core/types.d.ts",
       "import": "./dist/core/types.js"
     },
-    "./decorators/decorator-metadata": {
-      "types": "./dist/decorators/decorator-metadata.d.ts",
-      "import": "./dist/decorators/decorator-metadata.js"
-    },
     "./decorators/inject": {
       "types": "./dist/decorators/inject.d.ts",
       "import": "./dist/decorators/inject.js"
@@ -114,77 +110,89 @@
       "types": "./dist/decorators/injectable.d.ts",
       "import": "./dist/decorators/injectable.js"
     },
-    "./decorators/lifecycle-decorators": {
-      "types": "./dist/decorators/lifecycle-decorators.d.ts",
-      "import": "./dist/decorators/lifecycle-decorators.js"
+    "./decorators/lifecycle": {
+      "types": "./dist/decorators/lifecycle.d.ts",
+      "import": "./dist/decorators/lifecycle.js"
     },
-    "./errors/diagnostics": {
-      "types": "./dist/errors/diagnostics.d.ts",
-      "import": "./dist/errors/diagnostics.js"
+    "./decorators/metadata-record": {
+      "types": "./dist/decorators/metadata-record.d.ts",
+      "import": "./dist/decorators/metadata-record.js"
     },
-    "./errors/errors": {
-      "types": "./dist/errors/errors.d.ts",
-      "import": "./dist/errors/errors.js"
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./injection/dependency-slot": {
+      "types": "./dist/injection/dependency-slot.d.ts",
+      "import": "./dist/injection/dependency-slot.js"
     },
     "./injection/descriptor": {
       "types": "./dist/injection/descriptor.d.ts",
       "import": "./dist/injection/descriptor.js"
     },
-    "./injection/resolve-options": {
-      "types": "./dist/injection/resolve-options.d.ts",
-      "import": "./dist/injection/resolve-options.js"
-    },
-    "./dependency-graph": {
+    "./introspection/dependency-graph": {
       "types": "./dist/introspection/dependency-graph.d.ts",
       "import": "./dist/introspection/dependency-graph.js"
     },
-    "./graph-adapters/cytoscape": {
+    "./introspection/diagnostics": {
+      "types": "./dist/introspection/diagnostics.d.ts",
+      "import": "./dist/introspection/diagnostics.js"
+    },
+    "./introspection/explanation": {
+      "types": "./dist/introspection/explanation.d.ts",
+      "import": "./dist/introspection/explanation.js"
+    },
+    "./introspection/graph-adapters/cytoscape": {
       "types": "./dist/introspection/graph-adapters/cytoscape.d.ts",
       "import": "./dist/introspection/graph-adapters/cytoscape.js"
     },
-    "./graph-adapters/dot": {
+    "./introspection/graph-adapters/dot": {
       "types": "./dist/introspection/graph-adapters/dot.d.ts",
       "import": "./dist/introspection/graph-adapters/dot.js"
     },
-    "./graph-adapters/mermaid": {
+    "./introspection/graph-adapters/mermaid": {
       "types": "./dist/introspection/graph-adapters/mermaid.d.ts",
       "import": "./dist/introspection/graph-adapters/mermaid.js"
     },
-    "./graph-adapters/reactflow": {
+    "./introspection/graph-adapters/reactflow": {
       "types": "./dist/introspection/graph-adapters/reactflow.d.ts",
       "import": "./dist/introspection/graph-adapters/reactflow.js"
     },
-    "./inspector": {
+    "./introspection/inspector": {
       "types": "./dist/introspection/inspector.d.ts",
       "import": "./dist/introspection/inspector.js"
     },
-    "./lifecycle/lifecycle-manager": {
-      "types": "./dist/lifecycle/lifecycle-manager.d.ts",
-      "import": "./dist/lifecycle/lifecycle-manager.js"
+    "./lifecycle/hooks": {
+      "types": "./dist/lifecycle/hooks.d.ts",
+      "import": "./dist/lifecycle/hooks.js"
+    },
+    "./lifecycle/scopes": {
+      "types": "./dist/lifecycle/scopes.d.ts",
+      "import": "./dist/lifecycle/scopes.js"
     },
-    "./lifecycle/scope-manager": {
-      "types": "./dist/lifecycle/scope-manager.d.ts",
-      "import": "./dist/lifecycle/scope-manager.js"
+    "./metadata/keys": {
+      "types": "./dist/metadata/keys.d.ts",
+      "import": "./dist/metadata/keys.js"
     },
-    "./metadata/metadata-keys": {
-      "types": "./dist/metadata/metadata-keys.d.ts",
-      "import": "./dist/metadata/metadata-keys.js"
+    "./metadata/reader-token": {
+      "types": "./dist/metadata/reader-token.d.ts",
+      "import": "./dist/metadata/reader-token.js"
     },
-    "./metadata/metadata-reader-token": {
-      "types": "./dist/metadata/metadata-reader-token.d.ts",
-      "import": "./dist/metadata/metadata-reader-token.js"
+    "./metadata/symbol-reader": {
+      "types": "./dist/metadata/symbol-reader.d.ts",
+      "import": "./dist/metadata/symbol-reader.js"
     },
-    "./metadata/metadata-types": {
-      "types": "./dist/metadata/metadata-types.d.ts",
-      "import": "./dist/metadata/metadata-types.js"
+    "./metadata/types": {
+      "types": "./dist/metadata/types.d.ts",
+      "import": "./dist/metadata/types.js"
     },
-    "./metadata/symbol-metadata-reader": {
-      "types": "./dist/metadata/symbol-metadata-reader.d.ts",
-      "import": "./dist/metadata/symbol-metadata-reader.js"
+    "./metadata/verify": {
+      "types": "./dist/metadata/verify.d.ts",
+      "import": "./dist/metadata/verify.js"
     },
-    "./metadata/verifying-metadata-reader": {
-      "types": "./dist/metadata/verifying-metadata-reader.d.ts",
-      "import": "./dist/metadata/verifying-metadata-reader.js"
+    "./metadata/verifying-reader": {
+      "types": "./dist/metadata/verifying-reader.d.ts",
+      "import": "./dist/metadata/verifying-reader.js"
     },
     "./resolution/async-fan-out": {
       "types": "./dist/resolution/async-fan-out.d.ts",
@@ -194,37 +202,37 @@
       "types": "./dist/resolution/cache/activation-need.d.ts",
       "import": "./dist/resolution/cache/activation-need.js"
     },
-    "./resolution/cache/binding-lookup-cache": {
-      "types": "./dist/resolution/cache/binding-lookup-cache.d.ts",
-      "import": "./dist/resolution/cache/binding-lookup-cache.js"
-    },
     "./resolution/cache/class-introspector": {
       "types": "./dist/resolution/cache/class-introspector.d.ts",
       "import": "./dist/resolution/cache/class-introspector.js"
     },
+    "./resolution/cache/lookup": {
+      "types": "./dist/resolution/cache/lookup.d.ts",
+      "import": "./dist/resolution/cache/lookup.js"
+    },
     "./resolution/context": {
       "types": "./dist/resolution/context.d.ts",
       "import": "./dist/resolution/context.js"
     },
-    "./resolution/path/resolution-path": {
-      "types": "./dist/resolution/path/resolution-path.d.ts",
-      "import": "./dist/resolution/path/resolution-path.js"
+    "./resolution/path": {
+      "types": "./dist/resolution/path.d.ts",
+      "import": "./dist/resolution/path.js"
     },
-    "./resolution/plan/instantiation-plan": {
-      "types": "./dist/resolution/plan/instantiation-plan.d.ts",
-      "import": "./dist/resolution/plan/instantiation-plan.js"
+    "./resolution/plan/codegen": {
+      "types": "./dist/resolution/plan/codegen.d.ts",
+      "import": "./dist/resolution/plan/codegen.js"
     },
-    "./resolution/plan/plan-codegen": {
-      "types": "./dist/resolution/plan/plan-codegen.d.ts",
-      "import": "./dist/resolution/plan/plan-codegen.js"
+    "./resolution/plan/compiler": {
+      "types": "./dist/resolution/plan/compiler.d.ts",
+      "import": "./dist/resolution/plan/compiler.js"
     },
     "./resolution/resolver": {
       "types": "./dist/resolution/resolver.d.ts",
       "import": "./dist/resolution/resolver.js"
     },
-    "./resolution/select/binding-select": {
-      "types": "./dist/resolution/select/binding-select.d.ts",
-      "import": "./dist/resolution/select/binding-select.js"
+    "./resolution/select/candidates": {
+      "types": "./dist/resolution/select/candidates.d.ts",
+      "import": "./dist/resolution/select/candidates.js"
     },
     "./resolution/select/constraints": {
       "types": "./dist/resolution/select/constraints.d.ts",

package/dist/core/binding-scope.d.ts

@@ -1,12 +0,0 @@
-import type { Binding } from "#core/binding";
-import type { BindingScope } from "#core/types";
-/**
- * The scope a binding resolves under.
- *
- * @remarks Every kind declares one — an alias declares `transient`, since it defers scoping to the
- * binding it points at — so this is a field read, kept as a named function because it is the
- * vocabulary validation and introspection speak.
- *
- * @since 0.3.16-canary.0
- */
-export declare function effectiveBindingScope(binding: Binding): BindingScope;

package/dist/core/binding-scope.js

@@ -1,12 +0,0 @@
-/**
- * The scope a binding resolves under.
- *
- * @remarks Every kind declares one — an alias declares `transient`, since it defers scoping to the
- * binding it points at — so this is a field read, kept as a named function because it is the
- * vocabulary validation and introspection speak.
- *
- * @since 0.3.16-canary.0
- */
-export function effectiveBindingScope(binding) {
-    return binding.scope;
-}