@codefast/di 0.7.0 → 0.7.1

package/src/injection/descriptor.ts

@@ -4,6 +4,8 @@ import type { BindingTag, Constructor, TokenValue } from "#/core/types";
 import type { DependencySlot } from "#/injection/resolve-options";
 
 /**
+ * Slot-selection options — a name and tags — a declared dependency narrows its binding with.
+ *
  * @since 0.3.16-canary.0
  */
 export interface InjectOptions {
@@ -31,6 +33,8 @@ export interface InjectionDescriptor<out Value = unknown> extends DependencySlot
 }
 
 /**
+ * A dependency as declared: a bare token, a class, or a full injection descriptor.
+ *
  * @since 0.3.16-canary.0
  */
 export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<Value> | InjectionDescriptor<Value>;
@@ -60,6 +64,8 @@ export type ResolvedDependencyValue<Dependency> = Dependency extends { readonly
 type DescribedValue<Dependency> = Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
 
 /**
+ * Returns whether the value is an `InjectionDescriptor`, dual-role `inject()` functions included.
+ *
  * @since 0.3.16-canary.0
  */
 export function isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
@@ -81,6 +87,8 @@ export function isInjectionDescriptor(value: unknown): value is InjectionDescrip
 }
 
 /**
+ * Normalises a declared dependency to a plain `InjectionDescriptor`.
+ *
  * @since 0.3.16-canary.0
  */
 export function normalizeToDescriptor(dependency: InjectableDependency): InjectionDescriptor {
@@ -172,6 +180,8 @@ export function buildInjectionDescriptor<Value>(
 }
 
 /**
+ * Creates a descriptor that resolves to `undefined` instead of throwing when no binding matches.
+ *
  * @since 0.3.16-canary.0
  */
 export function optional<Value>(
@@ -189,6 +199,8 @@ export function optional<Value>(
 }
 
 /**
+ * Creates a descriptor that resolves every matching binding for the token into an array.
+ *
  * @since 0.3.16-canary.0
  */
 export function injectAll<Value>(

package/src/introspection/dependency-graph.ts

@@ -43,6 +43,8 @@ export interface GraphEdge {
 }
 
 /**
+ * A container's dependency graph as plain JSON — nodes, edges, and whether the parent is included.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ContainerGraphJson {
@@ -52,6 +54,8 @@ export interface ContainerGraphJson {
 }
 
 /**
+ * Options controlling what a dependency graph includes.
+ *
  * @since 0.3.16-canary.0
  */
 export interface GraphOptions {
@@ -255,6 +259,8 @@ function addRegistryBindings(
 }
 
 /**
+ * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
+ *
  * @since 0.3.16-canary.0
  */
 export function buildDependencyGraph(

package/src/introspection/graph-adapters/cytoscape.ts

@@ -1,6 +1,8 @@
 import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
 
 /**
+ * A dependency-graph node in Cytoscape's element format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface CytoscapeNode {
@@ -15,6 +17,8 @@ export interface CytoscapeNode {
 }
 
 /**
+ * A dependency-graph edge in Cytoscape's element format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface CytoscapeEdge {
@@ -29,11 +33,15 @@ export interface CytoscapeEdge {
 }
 
 /**
+ * The flat node-and-edge list Cytoscape takes as its `elements` input.
+ *
  * @since 0.3.16-canary.0
  */
 export type CytoscapeElements = ReadonlyArray<CytoscapeNode | CytoscapeEdge>;
 
 /**
+ * Converts a container's dependency graph into Cytoscape's element list.
+ *
  * @since 0.3.16-canary.0
  */
 export function toCytoscapeGraph(graph: ContainerGraphJson): CytoscapeElements {

package/src/introspection/graph-adapters/dot.ts

@@ -7,6 +7,8 @@ function escapeDotString(value: string): string {
 }
 
 /**
+ * Renders a container's dependency graph as Graphviz DOT source.
+ *
  * @since 0.3.16-canary.0
  */
 export function toDotGraph(graph: ContainerGraphJson): string {

package/src/introspection/graph-adapters/reactflow.ts

@@ -1,6 +1,8 @@
 import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
 
 /**
+ * A dependency-graph node in React Flow's node format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ReactFlowNode {
@@ -16,6 +18,8 @@ export interface ReactFlowNode {
 }
 
 /**
+ * A dependency-graph edge in React Flow's edge format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ReactFlowEdge {
@@ -28,6 +32,8 @@ export interface ReactFlowEdge {
 }
 
 /**
+ * The nodes-and-edges pair a React Flow viewer renders.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ReactFlowGraph {
@@ -45,6 +51,8 @@ const GRID_CELL_WIDTH_PX = 200;
 const GRID_CELL_HEIGHT_PX = 100;
 
 /**
+ * Converts a container's dependency graph into React Flow nodes and edges on an initial grid.
+ *
  * @since 0.5.0-canary.7
  */
 export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {

package/src/introspection/inspector.ts

@@ -18,6 +18,8 @@ import { selectAllBindings } from "#/resolution/select/binding-select";
 // ── Public types ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * A read-only view of one binding: token, kind, scope, slot, and id.
+ *
  * @since 0.3.16-canary.0
  */
 export interface BindingSnapshot {
@@ -32,6 +34,8 @@ export interface BindingSnapshot {
 }
 
 /**
+ * A read-only view of one container's own bindings and state.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ContainerSnapshot {
@@ -44,6 +48,8 @@ export interface ContainerSnapshot {
 // ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The read-only introspection surface behind a container's `inspect()`.
+ *
  * @since 0.3.16-canary.0
  */
 export class Inspector {

package/src/lifecycle/lifecycle-manager.ts

@@ -13,6 +13,8 @@ import { AsyncActivationError, AsyncDeactivationError, InvalidMetadataError } fr
 import type { MetadataReader } from "#/metadata/metadata-types";
 
 /**
+ * One container's registry of container-level activation and deactivation hooks, keyed by token.
+ *
  * @since 0.3.16-canary.0
  */
 export class LifecycleManager {

package/src/lifecycle/scope-manager.ts

@@ -5,6 +5,8 @@ import type { BindingIdentifier } from "#/core/types";
 import { MissingScopeContextError } from "#/errors/errors";
 
 /**
+ * One container's instance caches — singletons, in-flight async creations, and the scoped cache.
+ *
  * @since 0.3.16-canary.0
  */
 export class ScopeManager {

package/src/metadata/metadata-keys.ts

@@ -1,12 +1,18 @@
 /**
+ * The metadata key `@injectable` writes a class's constructor dependencies under.
+ *
  * @since 0.3.16-canary.0
  */
 export const INJECTABLE_KEY: unique symbol = Symbol("di:injectable");
 /**
+ * The metadata key `@postConstruct` and `@preDestroy` record method names under.
+ *
  * @since 0.3.16-canary.0
  */
 export const LIFECYCLE_KEY: unique symbol = Symbol("di:lifecycle");
 /**
+ * The metadata key `@inject` accessors record their injection descriptors under.
+ *
  * @since 0.3.16-canary.0
  */
 export const INJECT_ACCESSOR_KEY: unique symbol = Symbol("di:inject-accessor");

package/src/metadata/metadata-reader-token.ts

@@ -3,6 +3,8 @@ import type { Token } from "#/core/token";
 import type { MetadataReader } from "#/metadata/metadata-types";
 
 /**
+ * The token a custom `MetadataReader` is bound to for a container to pick up.
+ *
  * @since 0.3.16-canary.0
  */
 export const MetadataReaderToken: Token<MetadataReader> = token<MetadataReader>("MetadataReader");

package/src/metadata/metadata-types.ts

@@ -15,6 +15,8 @@ export interface ParamMetadata extends DependencySlot {
 }
 
 /**
+ * A class's declared constructor dependencies, as a `MetadataReader` reports them.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ConstructorMetadata {
@@ -22,6 +24,8 @@ export interface ConstructorMetadata {
 }
 
 /**
+ * The `postConstruct` and `preDestroy` method names a class declares.
+ *
  * @since 0.3.16-canary.0
  */
 export interface LifecycleMetadata {
@@ -40,6 +44,8 @@ export interface MutableLifecycleMetadata {
 }
 
 /**
+ * The port a container reads class metadata through — constructor deps, lifecycle, and accessors.
+ *
  * @since 0.3.16-canary.0
  */
 export interface MetadataReader {

package/src/metadata/symbol-metadata-reader.ts

@@ -6,6 +6,8 @@ import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/m
 type AccessorEntry = { readonly key: string | symbol; readonly descriptor: InjectionDescriptor };
 
 /**
+ * The default `MetadataReader`, reading decorator metadata stored under `Symbol.metadata`.
+ *
  * @since 0.3.16-canary.0
  */
 export class SymbolMetadataReader implements MetadataReader {
@@ -117,6 +119,8 @@ function mergeUniqueNames(lists: Array<ReadonlyArray<string>>): Array<string> {
 }
 
 /**
+ * The shared reader a container falls back to when given no custom `MetadataReader`.
+ *
  * @since 0.3.16-canary.0
  */
 export const defaultMetadataReader: SymbolMetadataReader = new SymbolMetadataReader();

package/src/resolution/cache/activation-need.ts

@@ -11,6 +11,8 @@ import type { LifecycleManager } from "#/lifecycle/lifecycle-manager";
 import type { ClassIntrospector } from "#/resolution/cache/class-introspector";
 
 /**
+ * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
+ *
  * @since 0.5.0-canary.8
  */
 export class ActivationNeedCache {

package/src/resolution/cache/binding-lookup-cache.ts

@@ -39,6 +39,8 @@ const newNameToEntryMap = <Owner>(): Map<string, DefaultLookupEntry<Owner> | nul
 const newTagToEntryMap = <Owner>(): Map<BindingTag, DefaultLookupEntry<Owner> | null> => new Map();
 
 /**
+ * A version-stamped cache of binding lookups by token, name, and tag across the container chain.
+ *
  * @since 0.5.0-canary.9
  */
 export class BindingLookupCache<Owner> {

package/src/resolution/cache/class-introspector.ts

@@ -188,6 +188,8 @@ export function verifyAccessorMetadata(
 }
 
 /**
+ * A per-class cache of constructor metadata and the activation facts derived from it.
+ *
  * @since 0.5.0-canary.8
  */
 export class ClassIntrospector {

package/src/resolution/context.ts

@@ -16,6 +16,8 @@ import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
 // ── ResolutionContext implementation ─────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The engine surface a resolution context calls back into to resolve further dependencies.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolverCallbacks {
@@ -60,6 +62,8 @@ export interface ResolverCallbacks {
 }
 
 /**
+ * The `ResolutionContext` handed to factories and hooks, backed by the engine's callbacks.
+ *
  * @since 0.3.16-canary.0
  */
 export class DefaultResolutionContext implements ResolutionContext {
@@ -312,6 +316,8 @@ class DefaultConstraintContext implements ConstraintContext {
 }
 
 /**
+ * Creates the resolution-stack frame for one in-flight resolve.
+ *
  * @since 0.3.16-canary.0
  */
 export function buildResolutionFrame(

package/src/resolution/plan/instantiation-plan.ts

@@ -161,6 +161,8 @@ export interface InstantiationPlanHost {
 export type EscapeArity = "all" | "optional" | "single";
 
 /**
+ * The compiler that flattens a class or resolved binding's dependencies into an instantiation plan.
+ *
  * @since 0.3.16-canary.1
  */
 export class InstantiationPlanCompiler {

package/src/resolution/resolver.ts

@@ -71,6 +71,8 @@ const ROOT_CONSTRAINT_CONTEXT = {
 };
 
 /**
+ * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
+ *
  * @since 0.3.16-canary.0
  */
 export class DependencyResolver implements ResolverCallbacks {

package/src/resolution/select/constraints.ts

@@ -7,6 +7,8 @@ import type { BindingConstraint, Constructor } from "#/core/types";
 import { EmptyTagCriteriaError } from "#/errors/errors";
 
 /**
+ * Matches when the direct parent frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -16,6 +18,8 @@ export function whenParentIs(token: Token<unknown> | Constructor): BindingConstr
 }
 
 /**
+ * Matches when there is no direct parent frame, or it resolves a different token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenNoParentIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -25,6 +29,8 @@ export function whenNoParentIs(token: Token<unknown> | Constructor): BindingCons
 }
 
 /**
+ * Matches when at least one ancestor frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -34,6 +40,8 @@ export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingC
 }
 
 /**
+ * Matches when no ancestor frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -43,6 +51,8 @@ export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingCo
 }
 
 /**
+ * Matches when the direct parent slot carries the given name.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentNamed(name: string): BindingConstraint {
@@ -54,6 +64,8 @@ export function whenParentNamed(name: string): BindingConstraint {
 }
 
 /**
+ * Matches when at least one ancestor slot carries the given name.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorNamed(name: string): BindingConstraint {
@@ -65,6 +77,8 @@ export function whenAnyAncestorNamed(name: string): BindingConstraint {
 }
 
 /**
+ * Matches when the direct parent slot carries the given tag pair.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentTagged(criterion: BindingTag): BindingConstraint {
@@ -73,6 +87,8 @@ export function whenParentTagged(criterion: BindingTag): BindingConstraint {
 }
 
 /**
+ * Matches when at least one ancestor slot carries the given tag pair.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorTagged(criterion: BindingTag): BindingConstraint {