@frontmcp/di 0.0.1 → 0.7.1

package/registry/indexed.registry.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Base class for registries with indexed lookups.
+ *
+ * Provides:
+ * - O(1) lookups by qualified ID, name, owner
+ * - Child registry adoption with live subscriptions
+ * - Lineage management for tracking ownership
+ * - Change event emission for subscribers
+ *
+ * Extended by ToolRegistry, ResourceRegistry, PromptRegistry, AgentRegistry.
+ */
+import type { Token } from '../interfaces/base.interface.js';
+import { RegistryAbstract, type RegistryKind } from './registry.base.js';
+import type { IndexedEntry, EntryLineage, EntryOwnerRef, ChangeEvent, ChangeKind, SubscribeOptions, RegistryEmitter } from './indexed.types.js';
+/**
+ * Abstract base class for registries with indexed lookups.
+ *
+ * @typeParam TInstance - Type of registry entry instances
+ * @typeParam TRecord - Type of registry records
+ * @typeParam TIndexed - Type of indexed entries (extends IndexedEntry)
+ * @typeParam TMetadata - Type of initialization metadata
+ * @typeParam TProviders - Type of parent provider registry
+ */
+export declare abstract class IndexedRegistry<TInstance, TRecord, TIndexed extends IndexedEntry<TInstance>, TMetadata, TProviders = unknown> extends RegistryAbstract<TInstance, TRecord, TMetadata, TProviders> {
+    /** Entries created by this registry */
+    protected localRows: TIndexed[];
+    /** Entries adopted from child registries */
+    protected adopted: Map<IndexedRegistry<TInstance, TRecord, TIndexed, any, any>, TIndexed[]>;
+    /** Set of child registries */
+    protected children: Set<IndexedRegistry<TInstance, TRecord, TIndexed, any, any>>;
+    /** Unsubscribe functions for child subscriptions */
+    protected childSubscriptions: Map<IndexedRegistry<TInstance, TRecord, TIndexed, any, any>, () => void>;
+    /** O(1) lookup by qualified ID */
+    protected byQualifiedId: Map<string, TIndexed>;
+    /** O(1) lookup by base name (array for conflicts) */
+    protected byName: Map<string, TIndexed[]>;
+    /** O(1) lookup by owner key */
+    protected byOwner: Map<string, TIndexed[]>;
+    /** O(1) lookup by owner:name composite */
+    protected byOwnerAndName: Map<string, TIndexed>;
+    /** Version counter for change tracking */
+    protected version: number;
+    /** Event emitter for change notifications */
+    protected emitter: RegistryEmitter<ChangeEvent<TIndexed>>;
+    /**
+     * Create an event emitter for this registry.
+     * Override to use custom emitter implementation.
+     */
+    protected createEmitter(): RegistryEmitter<ChangeEvent<TIndexed>>;
+    protected constructor(name: RegistryKind, providers: TProviders, metadata: TMetadata, auto?: boolean);
+    /**
+     * Build additional indexes from rows.
+     * Called during reindex to populate custom indexes.
+     *
+     * @param rows - All indexed entries (local + adopted)
+     */
+    protected abstract buildIndexes(rows: TIndexed[]): void;
+    /**
+     * Create an indexed entry from a record.
+     * Called during initialization to wrap records.
+     *
+     * @param token - Entry token
+     * @param record - Entry record
+     * @param instance - Instantiated entry
+     * @returns Indexed entry wrapper
+     */
+    protected abstract makeRow(token: Token, record: TRecord, instance: TInstance): TIndexed;
+    /**
+     * Adopt entries from a child registry.
+     *
+     * @param child - Child registry to adopt from
+     * @param childOwner - Owner reference for lineage
+     */
+    adoptFromChild(child: IndexedRegistry<TInstance, TRecord, TIndexed, any, any>, childOwner: EntryOwnerRef): void;
+    /**
+     * Remove a child registry.
+     */
+    removeChild(child: IndexedRegistry<TInstance, TRecord, TIndexed, any, any>): void;
+    /**
+     * Relineage an entry with a new prefix.
+     * Creates a new indexed entry with updated lineage.
+     */
+    protected relineage(row: TIndexed, prepend: EntryLineage): TIndexed;
+    /**
+     * Remove adjacent duplicate segments from lineage.
+     */
+    protected dedupLineage(lineage: EntryLineage): EntryLineage;
+    /**
+     * Generate owner key from lineage.
+     */
+    protected ownerKeyOf(lineage: EntryLineage): string;
+    /**
+     * Generate qualified name from base name and lineage.
+     */
+    protected qualifiedNameOf(baseName: string, lineage: EntryLineage): string;
+    /**
+     * Rebuild all indexes from local and adopted entries.
+     */
+    protected reindex(): void;
+    /**
+     * Subscribe to change events.
+     */
+    subscribe(opts: SubscribeOptions<TInstance>, callback: (event: ChangeEvent<TIndexed>) => void): () => void;
+    /**
+     * Emit a change event.
+     */
+    protected bump(kind: ChangeKind): void;
+    /**
+     * Find by base name (returns first match).
+     */
+    findByName(name: string): TInstance | undefined;
+    /**
+     * Find all by base name.
+     */
+    findAllByName(name: string): TInstance[];
+    /**
+     * Find by qualified ID.
+     */
+    findByQualifiedId(qualifiedId: string): TInstance | undefined;
+    /**
+     * List all indexed entries by owner.
+     */
+    listByOwner(ownerKey: string): TIndexed[];
+    /**
+     * List all indexed entries.
+     */
+    listAllIndexed(): TIndexed[];
+    /**
+     * List all instances.
+     */
+    listAllInstances(): TInstance[];
+    /**
+     * Check if registry has any entries.
+     */
+    hasAny(): boolean;
+    /**
+     * Dispose of this registry and clean up subscriptions.
+     */
+    dispose(): void;
+}

package/registry/indexed.types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Types for indexed registries with fast lookups.
+ */
+import type { Token } from '../interfaces/base.interface.js';
+/**
+ * Entry lineage segment describing the owner path.
+ */
+export interface LineageSegment {
+    /** Type of owner (e.g., 'app', 'plugin', 'scope') */
+    type: string;
+    /** Identifier for this segment */
+    id: string;
+    /** Optional name for display purposes */
+    name?: string;
+}
+/**
+ * Complete lineage path from root to entry.
+ */
+export type EntryLineage = LineageSegment[];
+/**
+ * Reference to an entry owner for adoption tracking.
+ */
+export interface EntryOwnerRef {
+    /** Lineage path to the owner */
+    lineage: EntryLineage;
+    /** String key representation of the owner */
+    ownerKey: string;
+}
+/**
+ * Base indexed entry interface.
+ * Extended by specific registries with additional fields.
+ */
+export interface IndexedEntry<T> {
+    /** Token for this entry */
+    token: Token;
+    /** Instantiated entry */
+    instance: T;
+    /** Base name without qualification */
+    baseName: string;
+    /** Full lineage path */
+    lineage: EntryLineage;
+    /** String key for owner lookup */
+    ownerKey: string;
+    /** Fully qualified name including owner path */
+    qualifiedName: string;
+    /** Fully qualified ID for unique lookup */
+    qualifiedId: string;
+}
+/**
+ * Change event kinds.
+ */
+export type ChangeKind = 'reset' | 'add' | 'remove' | 'update';
+/**
+ * Change event scope.
+ */
+export type ChangeScope = 'local' | 'global';
+/**
+ * Base change event for indexed registries.
+ */
+export interface ChangeEvent<TIndexed> {
+    /** Type of change */
+    kind: ChangeKind;
+    /** Scope of the change */
+    changeScope: ChangeScope;
+    /** Version counter after change */
+    version: number;
+    /** Current snapshot of all entries */
+    snapshot: TIndexed[];
+}
+/**
+ * Subscription options for change events.
+ */
+export interface SubscribeOptions<T> {
+    /** Emit immediately with current state */
+    immediate?: boolean;
+    /** Filter function for entries */
+    filter?: (instance: T) => boolean;
+}
+/**
+ * Event emitter interface for change notifications.
+ */
+export interface RegistryEmitter<TEvent> {
+    /** Emit an event to all subscribers */
+    emit(event: TEvent): void;
+    /** Subscribe to events, returns unsubscribe function */
+    on(handler: (event: TEvent) => void): () => void;
+}

package/registry/registry.base.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Base abstract class for all registries.
+ *
+ * Provides the core structure for managing tokens, definitions, and
+ * dependency graphs. Subclasses implement specific initialization logic.
+ */
+import type { Token } from '../interfaces/base.interface.js';
+/**
+ * Result of the buildMap phase containing registry structures.
+ */
+export type RegistryBuildMapResult<Record> = {
+    /** All tokens that are provided (graph nodes) */
+    tokens: Set<Token>;
+    /** Record definition by token */
+    defs: Map<Token, Record>;
+    /** Dependency graph by token */
+    graph: Map<Token, Set<Token>>;
+};
+/**
+ * Registry kind identifier for categorizing registries.
+ */
+export type RegistryKind = string;
+/**
+ * Abstract base class for registries.
+ *
+ * @typeParam Interface - The interface type for registry entries
+ * @typeParam Record - The record type stored in the registry
+ * @typeParam MetadataType - The metadata type for initialization
+ * @typeParam ProviderRegistryType - Optional parent provider registry type
+ */
+export declare abstract class RegistryAbstract<Interface, Record, MetadataType, ProviderRegistryType = unknown> {
+    /** Default timeout for async operations in milliseconds */
+    protected asyncTimeoutMs: number;
+    /** Promise that resolves when the registry is fully initialized */
+    ready: Promise<void>;
+    /** Reference to parent provider registry for dependency resolution */
+    protected providers: ProviderRegistryType;
+    /** Metadata used for initialization */
+    protected list: MetadataType;
+    /** All tokens that are provided (graph nodes) */
+    protected tokens: Set<Token>;
+    /** Record definition by token */
+    protected defs: Map<Token, Record>;
+    /** Dependency graph by token */
+    protected graph: Map<Token, Set<Token>>;
+    /** Instantiated entries by token */
+    protected readonly instances: Map<Token<Interface>, Interface>;
+    /**
+     * Create a new registry.
+     *
+     * @param name - Registry kind name for identification
+     * @param providers - Parent provider registry
+     * @param metadata - Initialization metadata
+     * @param auto - Whether to automatically build and initialize
+     */
+    protected constructor(name: RegistryKind, providers: ProviderRegistryType, metadata: MetadataType, auto?: boolean);
+    /**
+     * Build the initial token/record/graph maps from metadata.
+     * Called during construction.
+     *
+     * @param list - Initialization metadata
+     * @returns Registry structures
+     */
+    protected abstract buildMap(list: MetadataType): RegistryBuildMapResult<Record>;
+    /**
+     * Build the dependency graph.
+     * Called after buildMap to establish dependencies.
+     */
+    protected abstract buildGraph(): void;
+    /**
+     * Initialize the registry by instantiating entries.
+     * Called after buildGraph.
+     *
+     * @returns Promise that resolves when initialization is complete
+     */
+    protected abstract initialize(): Promise<void>;
+    /**
+     * Check if the registry has any entries.
+     */
+    hasAny(): boolean;
+    /**
+     * Get all instances as a readonly map.
+     */
+    getAllInstances(): ReadonlyMap<Token<Interface>, Interface>;
+}

package/registry/simple.registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Simple registry base class without indexed lookups.
+ *
+ * Used for registries that don't need adoption or complex indexing:
+ * - AppRegistry
+ * - AuthRegistry
+ * - FlowRegistry
+ */
+import { RegistryAbstract, type RegistryKind } from './registry.base.js';
+/**
+ * Simple registry without indexed lookups or adoption.
+ *
+ * @typeParam TInstance - Type of registry entry instances
+ * @typeParam TRecord - Type of registry records
+ * @typeParam TMetadata - Type of initialization metadata
+ * @typeParam TProviders - Type of parent provider registry
+ */
+export declare abstract class SimpleRegistry<TInstance, TRecord, TMetadata, TProviders = unknown> extends RegistryAbstract<TInstance, TRecord, TMetadata, TProviders> {
+    protected constructor(name: RegistryKind, providers: TProviders, metadata: TMetadata, auto?: boolean);
+    /**
+     * Get all entries as an array.
+     */
+    getAll(): TInstance[];
+    /**
+     * Get entry count.
+     */
+    count(): number;
+}

package/tokens/di.constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DI-related metadata keys and constants.
+ *
+ * These symbols are used with reflect-metadata for storing and retrieving
+ * dependency injection metadata on classes.
+ */
+/**
+ * Metadata key for design:paramtypes (TypeScript's emitted constructor parameter types).
+ * Used by reflect-metadata to store constructor parameter type information.
+ */
+export declare const DESIGN_PARAMTYPES = "design:paramtypes";
+/**
+ * Metadata key indicating a class uses async initialization via static `with()` method.
+ * When this metadata is present, the DI container will call the static `with()` method
+ * instead of the constructor for instantiation.
+ */
+export declare const META_ASYNC_WITH: unique symbol;
+/**
+ * Metadata key for storing the token array used by @AsyncWith decorator.
+ * Contains a function that returns the dependency tokens for the static `with()` method.
+ */
+export declare const META_ASYNC_WITH_TOKENS: unique symbol;

package/tokens/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Token system for dependency injection.
+ *
+ * This module provides:
+ * - Token factory for creating type-safe DI tokens
+ * - DI-related metadata constants
+ */
+export { createTokenFactory, DiTokens, type TokenFactory, type TokenFactoryOptions } from './token.factory.js';
+export { DESIGN_PARAMTYPES, META_ASYNC_WITH, META_ASYNC_WITH_TOKENS } from './di.constants.js';

package/tokens/token.factory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Token factory for creating type-safe DI tokens with configurable prefix.
+ *
+ * @example
+ * ```typescript
+ * // Create a factory with custom prefix
+ * const tokens = createTokenFactory({ prefix: 'MyApp' });
+ *
+ * // Create typed tokens
+ * const serviceToken = tokens.type('UserService');
+ * // => Symbol('MyApp:type:UserService')
+ *
+ * const metaToken = tokens.meta('config');
+ * // => Symbol('MyApp:meta:config')
+ * ```
+ */
+export interface TokenFactoryOptions {
+    /**
+     * Prefix for generated token symbols.
+     * @default 'DI'
+     */
+    prefix?: string;
+}
+export interface TokenFactory {
+    /**
+     * Create a type token for a service/provider.
+     * @param name - The name of the type
+     * @returns A unique symbol for the type
+     */
+    type: (name: string) => symbol;
+    /**
+     * Create a metadata token for storing/retrieving metadata.
+     * @param name - The name of the metadata key
+     * @returns A unique symbol for the metadata key
+     */
+    meta: (name: string) => symbol;
+}
+/**
+ * Create a token factory with the given options.
+ *
+ * @param options - Factory configuration
+ * @returns A token factory instance
+ *
+ * @example
+ * ```typescript
+ * const tokens = createTokenFactory({ prefix: 'FrontMcp' });
+ * const userToken = tokens.type('UserService');
+ * ```
+ */
+export declare function createTokenFactory(options?: TokenFactoryOptions): TokenFactory;
+/**
+ * Default token factory instance with 'DI' prefix.
+ * Use this for standalone DI usage without custom branding.
+ */
+export declare const DiTokens: TokenFactory;

package/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Utility functions for dependency injection.
+ */
+export { getMetadata, setMetadata, hasAsyncWith } from './metadata.utils.js';
+export { tokenName, isClass, isPromise, getAsyncWithTokens, readWithParamTypes, depsOfClass, depsOfFunc, } from './token.utils.js';
+export { createProviderNormalizer, providerDiscoveryDeps, providerInvocationTokens, type ProviderTokens, type ProviderNormalizerOptions, } from './provider.utils.js';

package/utils/metadata.utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Metadata utilities for dependency injection.
+ *
+ * These utilities work with reflect-metadata to store and retrieve
+ * DI-related metadata on classes.
+ */
+import 'reflect-metadata';
+import type { Type } from '../interfaces/base.interface.js';
+/**
+ * Get metadata value from a target.
+ *
+ * @param key - The metadata key
+ * @param target - The target object or class
+ * @param propertyKey - Optional property key for method/property metadata
+ * @returns The metadata value or undefined
+ */
+export declare function getMetadata<T = any>(key: any, target: any, propertyKey?: string | symbol): T | undefined;
+/**
+ * Set metadata value on a target.
+ *
+ * @param key - The metadata key
+ * @param value - The metadata value
+ * @param target - The target object or class
+ * @param propertyKey - Optional property key for method/property metadata
+ */
+export declare function setMetadata(key: any, value: any, target: any, propertyKey?: string | symbol): void;
+/**
+ * Check if a class uses async initialization via static `with()` method.
+ *
+ * Classes decorated with @AsyncWith will have this metadata set and
+ * should be instantiated using their static `with()` method instead
+ * of the constructor.
+ *
+ * @param klass - The class to check
+ * @returns True if the class uses async initialization
+ */
+export declare function hasAsyncWith(klass: Type<any>): boolean;

package/utils/provider.utils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Provider normalization and dependency discovery utilities.
+ *
+ * These utilities convert user-facing provider definitions to internal
+ * ProviderRecord format and discover dependencies.
+ */
+import type { Token, Type } from '../interfaces/base.interface.js';
+import type { ProviderType } from '../interfaces/provider.interface.js';
+import { type ProviderRecord } from '../records/provider.record.js';
+/**
+ * Token set for reading provider metadata from classes.
+ * Each key maps to a metadata symbol used with reflect-metadata.
+ */
+export interface ProviderTokens {
+    /** Token indicating this is a provider class */
+    type: symbol;
+    /** Token for provider name */
+    name: symbol;
+    /** Token for provider scope */
+    scope: symbol;
+    /** Token for provider description */
+    description?: symbol;
+    /** Token for provider id */
+    id?: symbol;
+}
+/**
+ * Options for creating a provider normalizer.
+ */
+export interface ProviderNormalizerOptions {
+    /**
+     * Metadata tokens for reading provider information from decorated classes.
+     */
+    tokens: ProviderTokens;
+}
+/**
+ * Create a provider normalizer function with the given metadata tokens.
+ *
+ * The normalizer converts user-facing provider definitions to internal
+ * ProviderRecord format. By injecting tokens, this works with any
+ * decorator system (FrontMCP, custom, etc.).
+ *
+ * @param options - Normalizer configuration with metadata tokens
+ * @returns A normalizer function
+ *
+ * @example
+ * ```typescript
+ * import { createProviderNormalizer } from '@frontmcp/di';
+ *
+ * const normalizeProvider = createProviderNormalizer({
+ *   tokens: {
+ *     type: Symbol('provider:type'),
+ *     name: Symbol('provider:name'),
+ *     scope: Symbol('provider:scope'),
+ *   }
+ * });
+ *
+ * const record = normalizeProvider(MyService);
+ * ```
+ */
+export declare function createProviderNormalizer(options: ProviderNormalizerOptions): (item: ProviderType) => ProviderRecord;
+/**
+ * Discover dependencies for a provider record during the discovery phase.
+ *
+ * @param rec - The provider record
+ * @param localTokens - Set of locally registered tokens
+ * @param depsOfClassFn - Function to discover class dependencies
+ * @returns Array of dependency tokens
+ */
+export declare function providerDiscoveryDeps(rec: ProviderRecord, localTokens: Set<Token>, depsOfClassFn: (klass: Type, phase: 'discovery' | 'invocation') => Type[]): Token[];
+/**
+ * Get invocation tokens for a provider record.
+ *
+ * These are the tokens that need to be resolved when instantiating the provider.
+ *
+ * @param rec - The provider record
+ * @param depsOfClassFn - Function to discover class dependencies
+ * @returns Array of dependency tokens
+ */
+export declare function providerInvocationTokens(rec: ProviderRecord, depsOfClassFn: (klass: Type, phase: 'discovery' | 'invocation') => Type[]): Token[];

package/utils/token.utils.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Token utilities for dependency injection.
+ *
+ * These utilities help with token resolution, type checking, and
+ * dependency discovery from class metadata.
+ */
+import type { Token, Type } from '../interfaces/base.interface.js';
+/**
+ * Get a human-readable name for a token.
+ *
+ * @param t - The token to get the name for
+ * @returns A string representation of the token
+ */
+export declare const tokenName: (t: Token) => string;
+/**
+ * Check if a value is a class constructor.
+ *
+ * @param x - The value to check
+ * @returns True if x is a class constructor
+ */
+export declare const isClass: (x: any) => x is Type;
+/**
+ * Check if a value is a Promise.
+ *
+ * @param v - The value to check
+ * @returns True if v is a Promise
+ */
+export declare const isPromise: (v: any) => v is Promise<any>;
+/**
+ * Get async-with dependency tokens from a class.
+ *
+ * If a class is decorated with @AsyncWith, this returns the token array
+ * that should be resolved and passed to the static `with()` method.
+ *
+ * @param klass - The class to get tokens from
+ * @returns Array of dependency tokens, or null if not decorated
+ */
+export declare function getAsyncWithTokens(klass: Type<any>): Type<any>[] | null;
+/**
+ * Read parameter types for static with(...) method.
+ *
+ * This function is TDZ-friendly and will use the @AsyncWith token array
+ * if available, falling back to design:paramtypes metadata.
+ *
+ * @param klass - The class to read parameter types from
+ * @param forWhat - Whether this is for 'discovery' or 'invocation' phase
+ * @returns Array of dependency types
+ * @throws If parameter types cannot be determined
+ */
+export declare function readWithParamTypes(klass: Type, forWhat: 'discovery' | 'invocation'): Type[];
+/**
+ * Discover dependencies for a CLASS token or concrete Type.
+ *
+ * For classes with @AsyncWith, reads from the static `with()` method.
+ * Otherwise, reads constructor parameter types.
+ *
+ * @param klass - The class to discover dependencies for
+ * @param phase - Whether this is 'discovery' or 'invocation' phase
+ * @returns Array of dependency types
+ * @throws If dependencies cannot be determined (TDZ issues, missing metadata)
+ */
+export declare function depsOfClass(klass: Type, phase: 'discovery' | 'invocation'): Type[];
+/**
+ * Discover dependencies for a function token.
+ *
+ * Reads design:paramtypes metadata, skipping the first parameter
+ * (which is typically the input argument, not a dependency).
+ *
+ * @param fn - The function to discover dependencies for
+ * @param phase - Whether this is 'discovery' or 'invocation' phase
+ * @returns Array of dependency types
+ * @throws If dependencies cannot be determined
+ */
+export declare function depsOfFunc(fn: (...args: any[]) => any | Promise<any>, phase: 'discovery' | 'invocation'): Type[];