@di-framework/di-framework 0.0.0-prerelease-0

package/dist/container.js

@@ -0,0 +1,408 @@
+/**
+ * Dependency Injection Container
+ *
+ * Manages service registration, dependency resolution, and instance lifecycle.
+ * Supports singleton pattern and automatic dependency injection via decorators.
+ * Works with SWC and TypeScript's native decorator support.
+ */
+const INJECTABLE_METADATA_KEY = "di:injectable";
+const INJECT_METADATA_KEY = "di:inject";
+const DESIGN_PARAM_TYPES_KEY = "design:paramtypes";
+export const TELEMETRY_METADATA_KEY = "di:telemetry";
+export const TELEMETRY_LISTENER_METADATA_KEY = "di:telemetry-listener";
+/**
+ * Simple metadata storage that doesn't require reflect-metadata
+ * Works with SWC's native decorator support
+ */
+const metadataStore = new Map();
+function defineMetadata(key, value, target) {
+    if (!metadataStore.has(target)) {
+        metadataStore.set(target, new Map());
+    }
+    metadataStore.get(target).set(key, value);
+}
+function getMetadata(key, target) {
+    return metadataStore.get(target)?.get(key);
+}
+function hasMetadata(key, target) {
+    return metadataStore.has(target) && metadataStore.get(target).has(key);
+}
+function getOwnMetadata(key, target) {
+    return getMetadata(key, target);
+}
+export class Container {
+    services = new Map();
+    resolutionStack = new Set();
+    listeners = new Map();
+    /**
+     * Register a service class as injectable
+     */
+    register(serviceClass, options = { singleton: true }) {
+        const name = serviceClass.name;
+        this.services.set(name, {
+            type: serviceClass,
+            singleton: options.singleton ?? true,
+        });
+        this.services.set(serviceClass, {
+            type: serviceClass,
+            singleton: options.singleton ?? true,
+        });
+        this.emit("registered", {
+            key: serviceClass,
+            singleton: options.singleton ?? true,
+            kind: "class",
+        });
+        return this;
+    }
+    /**
+     * Register a service using a factory function
+     */
+    registerFactory(name, factory, options = { singleton: true }) {
+        this.services.set(name, {
+            type: factory,
+            singleton: options.singleton ?? true,
+        });
+        this.emit("registered", {
+            key: name,
+            singleton: options.singleton ?? true,
+            kind: "factory",
+        });
+        return this;
+    }
+    /**
+     * Get or create a service instance
+     */
+    resolve(serviceClass) {
+        const key = typeof serviceClass === "string" ? serviceClass : serviceClass;
+        const keyStr = typeof serviceClass === "string" ? serviceClass : serviceClass.name;
+        // Check for circular dependencies
+        if (this.resolutionStack.has(key)) {
+            throw new Error(`Circular dependency detected while resolving ${keyStr}. Stack: ${Array.from(this.resolutionStack).join(" -> ")} -> ${keyStr}`);
+        }
+        const definition = this.services.get(key);
+        if (!definition) {
+            throw new Error(`Service '${keyStr}' is not registered in the DI container`);
+        }
+        const wasCached = definition.singleton && !!definition.instance;
+        // Return cached singleton
+        if (definition.singleton && definition.instance) {
+            this.emit("resolved", {
+                key,
+                instance: definition.instance,
+                singleton: true,
+                fromCache: true,
+            });
+            return definition.instance;
+        }
+        // Resolve dependencies
+        this.resolutionStack.add(key);
+        try {
+            const instance = this.instantiate(definition.type);
+            // Cache singleton
+            if (definition.singleton) {
+                definition.instance = instance;
+            }
+            this.emit("resolved", {
+                key,
+                instance,
+                singleton: definition.singleton,
+                fromCache: wasCached,
+            });
+            return instance;
+        }
+        finally {
+            this.resolutionStack.delete(key);
+        }
+    }
+    /**
+     * Construct a new instance without registering it in the container.
+     * Supports constructor overrides for primitives/config (constructor pattern).
+     * Always returns a fresh instance (no caching).
+     */
+    construct(serviceClass, overrides = {}) {
+        const keyStr = serviceClass.name;
+        if (this.resolutionStack.has(serviceClass)) {
+            throw new Error(`Circular dependency detected while constructing ${keyStr}. Stack: ${Array.from(this.resolutionStack).join(" -> ")} -> ${keyStr}`);
+        }
+        this.resolutionStack.add(serviceClass);
+        try {
+            const instance = this.instantiate(serviceClass, overrides);
+            this.emit("constructed", { key: serviceClass, instance, overrides });
+            return instance;
+        }
+        finally {
+            this.resolutionStack.delete(serviceClass);
+        }
+    }
+    /**
+     * Check if a service is registered
+     */
+    has(serviceClass) {
+        return this.services.has(serviceClass);
+    }
+    /**
+     * Clear all registered services
+     */
+    clear() {
+        const count = this.services.size;
+        this.services.clear();
+        this.emit("cleared", { count });
+    }
+    /**
+     * Get all registered service names
+     */
+    getServiceNames() {
+        const names = new Set();
+        this.services.forEach((_, key) => {
+            if (typeof key === "string") {
+                names.add(key);
+            }
+        });
+        return Array.from(names);
+    }
+    /**
+     * Fork the container (prototype pattern): clone registrations into a new container.
+     * Optionally carry over existing singleton instances.
+     */
+    fork(options = {}) {
+        const clone = new Container();
+        this.services.forEach((def, key) => {
+            clone.services.set(key, {
+                ...def,
+                instance: options.carrySingletons ? def.instance : undefined,
+            });
+        });
+        return clone;
+    }
+    /**
+     * Subscribe to container lifecycle events (observer pattern).
+     * Returns an unsubscribe function.
+     */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+        return () => this.off(event, listener);
+    }
+    /**
+     * Remove a previously registered listener
+     */
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    emit(event, payload) {
+        const listeners = this.listeners.get(event);
+        if (!listeners || listeners.size === 0)
+            return;
+        listeners.forEach((listener) => {
+            try {
+                listener(payload);
+            }
+            catch (err) {
+                console.error(`[Container] listener for '${event}' threw`, err);
+            }
+        });
+    }
+    /**
+     * Private method to instantiate a service
+     */
+    instantiate(type, overrides = {}) {
+        if (typeof type !== "function") {
+            throw new Error("Service type must be a constructor or factory function");
+        }
+        // If it's a factory function (not a class), just call it
+        if (!this.isClass(type)) {
+            return type();
+        }
+        // Get constructor parameter types from metadata
+        const paramTypes = getMetadata(DESIGN_PARAM_TYPES_KEY, type) || [];
+        const paramNames = this.getConstructorParamNames(type);
+        // Resolve dependencies
+        const dependencies = [];
+        const injectMetadata = getOwnMetadata(INJECT_METADATA_KEY, type) || {};
+        const paramCount = Math.max(paramTypes.length, paramNames.length);
+        for (let i = 0; i < paramCount; i++) {
+            if (Object.prototype.hasOwnProperty.call(overrides, i)) {
+                dependencies.push(overrides[i]);
+                continue;
+            }
+            const paramType = paramTypes[i];
+            const paramName = paramNames[i];
+            // Prefer explicit @Component() decorator when present
+            const paramInjectTarget = injectMetadata[`param_${i}`];
+            if (paramInjectTarget) {
+                // Use explicit injection target (can be class or string token)
+                dependencies.push(this.resolve(paramInjectTarget));
+            }
+            else if (paramType && paramType !== Object) {
+                // Try to resolve by type when metadata is available
+                if (this.has(paramType)) {
+                    dependencies.push(this.resolve(paramType));
+                }
+                else if (this.has(paramType.name)) {
+                    dependencies.push(this.resolve(paramType.name));
+                }
+                else {
+                    throw new Error(`Cannot resolve dependency of type ${paramType.name} for parameter '${paramName}' in ${type.name}`);
+                }
+            }
+            else {
+                // No information available for this parameter; leave undefined (constructor may provide default)
+            }
+        }
+        // Create instance
+        const instance = new type(...dependencies);
+        // Apply Telemetry and TelemetryListener
+        this.applyTelemetry(instance, type);
+        // Call @Component() decorators on properties
+        // Check both the instance and the constructor prototype for metadata
+        const injectProperties = getMetadata(INJECT_METADATA_KEY, type) || {};
+        const protoInjectProperties = getMetadata(INJECT_METADATA_KEY, type.prototype) ||
+            {};
+        const allInjectProperties = {
+            ...injectProperties,
+            ...protoInjectProperties,
+        };
+        Object.entries(allInjectProperties).forEach(([propName, targetType]) => {
+            if (!propName.startsWith("param_") && targetType) {
+                try {
+                    instance[propName] = this.resolve(targetType);
+                }
+                catch (error) {
+                    console.warn(`Failed to inject property '${propName}' on ${type.name}:`, error);
+                }
+            }
+        });
+        return instance;
+    }
+    /**
+     * Apply telemetry tracking and listeners to an instance
+     */
+    applyTelemetry(instance, constructor) {
+        const className = constructor.name;
+        // Handle @TelemetryListener
+        const listenerMethods = getMetadata(TELEMETRY_LISTENER_METADATA_KEY, constructor.prototype) || [];
+        listenerMethods.forEach((methodName) => {
+            const method = instance[methodName];
+            if (typeof method === "function") {
+                this.on("telemetry", (payload) => {
+                    try {
+                        method.call(instance, payload);
+                    }
+                    catch (err) {
+                        console.error(`[Container] TelemetryListener '${className}.${methodName}' threw`, err);
+                    }
+                });
+            }
+        });
+        // Handle @Telemetry
+        const telemetryMethods = getMetadata(TELEMETRY_METADATA_KEY, constructor.prototype) || {};
+        Object.entries(telemetryMethods).forEach(([methodName, options]) => {
+            const originalMethod = instance[methodName];
+            if (typeof originalMethod === "function") {
+                const self = this;
+                instance[methodName] = function (...args) {
+                    const startTime = Date.now();
+                    const emit = (result, error) => {
+                        const payload = {
+                            className,
+                            methodName,
+                            args,
+                            startTime,
+                            endTime: Date.now(),
+                            result,
+                            error,
+                        };
+                        if (options.logging) {
+                            const duration = payload.endTime - payload.startTime;
+                            const status = error
+                                ? `ERROR: ${error.message || error}`
+                                : "SUCCESS";
+                            console.log(`[Telemetry] ${className}.${methodName} - ${status} (${duration}ms)`);
+                        }
+                        self.emit("telemetry", payload);
+                    };
+                    try {
+                        const result = originalMethod.apply(this, args);
+                        if (result instanceof Promise) {
+                            return result
+                                .then((val) => {
+                                emit(val);
+                                return val;
+                            })
+                                .catch((err) => {
+                                emit(undefined, err);
+                                throw err;
+                            });
+                        }
+                        emit(result);
+                        return result;
+                    }
+                    catch (err) {
+                        emit(undefined, err);
+                        throw err;
+                    }
+                };
+            }
+        });
+    }
+    /**
+     * Check if a function is a class constructor
+     */
+    isClass(func) {
+        return (typeof func === "function" &&
+            func.prototype &&
+            func.prototype.constructor === func);
+    }
+    /**
+     * Extract parameter names from constructor
+     */
+    getConstructorParamNames(target) {
+        const funcStr = target.toString();
+        const match = funcStr.match(/constructor\s*\(([^)]*)\)/);
+        if (!match || !match[1])
+            return [];
+        const paramsStr = match[1];
+        return paramsStr
+            .split(",")
+            .map((param) => {
+            const trimmed = param.trim();
+            const withoutDefault = trimmed.split("=")[0] || "";
+            const withoutType = withoutDefault.split(":")[0] || "";
+            return withoutType.trim();
+        })
+            .filter((param) => param);
+    }
+    /**
+     * Extract parameter types from TypeScript compiled code
+     * Looks for type annotations in the compiled constructor signature
+     */
+    extractParamTypesFromSource(target) {
+        const funcStr = target.toString();
+        // Try to extract types from decorated constructor
+        // In compiled TypeScript with emitDecoratorMetadata, types appear in decorator calls
+        const decoratorMatch = funcStr.match(/__decorate\(\[\s*(?:\w+\s*\([^)]*\),?\s*)*__param\((\d+),\s*(\w+)\([^)]*\)\)/g);
+        if (decoratorMatch) {
+            // Found decorator-based metadata
+            return [];
+        }
+        // Return empty array - will fall back to type annotations or @Component decorators
+        return [];
+    }
+}
+/**
+ * Global DI container instance
+ */
+export const container = new Container();
+/**
+ * Get the global DI container
+ */
+export function useContainer() {
+    return container;
+}
+/**
+ * Export metadata functions for use in decorators
+ * These provide a simple, reflect-metadata-free way to store and access metadata
+ */
+export { defineMetadata, getMetadata, hasMetadata, getOwnMetadata };

package/dist/decorators.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Dependency Injection Decorators
+ *
+ * @Container - Marks a class as injectable
+ * @Component - Marks dependencies for injection (constructor parameters or properties)
+ *
+ * Works with SWC and TypeScript's native decorator support.
+ * No external dependencies required (no reflect-metadata needed).
+ */
+import { Container as DIContainer } from "./container";
+/**
+ * Options for the @Telemetry decorator
+ */
+export interface TelemetryOptions {
+    /**
+     * Whether to log the telemetry event to the console.
+     * Defaults to false.
+     */
+    logging?: boolean;
+}
+/**
+ * Marks a method for telemetry tracking.
+ * When called, it will emit a 'telemetry' event on the container.
+ * Compatible with async and sync methods.
+ *
+ * @param options Configuration options for telemetry
+ */
+export declare function Telemetry(options?: TelemetryOptions): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Marks a method as a listener for telemetry events.
+ * The method will be automatically registered to the container's 'telemetry' event.
+ */
+export declare function TelemetryListener(): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Marks a class as injectable and registers it with the DI container
+ *
+ * @param options Configuration options for the injectable service
+ *
+ * @example
+ * @Container()
+ * class UserService {
+ *   getUser(id: string) { ... }
+ * }
+ *
+ * @example With options
+ * @Container({ singleton: false })
+ * class RequestScopedService {
+ *   // New instance created for each resolution
+ * }
+ */
+export declare function Container(options?: {
+    singleton?: boolean;
+    container?: DIContainer;
+}): <T extends {
+    new (...args: any[]): {};
+}>(constructor: T) => T;
+/**
+ * Marks a constructor parameter or property for dependency injection
+ *
+ * Can be used on:
+ * - Constructor parameters
+ * - Class properties
+ *
+ * @param target The class to inject dependencies into. Can be a class constructor or a string identifier.
+ *
+ * @example Constructor parameter injection
+ * @Container()
+ * class UserController {
+ *   constructor(@Component(UserService) userService: UserService) {}
+ * }
+ *
+ * @example Property injection
+ * @Container()
+ * class UserService {
+ *   @Component(DatabaseConnection)
+ *   private db: DatabaseConnection;
+ * }
+ *
+ * @example With string identifier
+ * @Container()
+ * class PaymentService {
+ *   constructor(@Component('apiKey') apiKey: string) {}
+ * }
+ */
+export declare function Component(target: any): (targetClass: Object | any, propertyKey?: string | symbol, parameterIndex?: number) => void;
+/**
+ * Check if a class is marked as injectable
+ */
+export declare function isInjectable(target: any): boolean;
+/**
+ * Get the container instance used by decorators
+ */
+export declare function getInjectionContainer(): DIContainer;

package/dist/decorators.js

@@ -0,0 +1,128 @@
+/**
+ * Dependency Injection Decorators
+ *
+ * @Container - Marks a class as injectable
+ * @Component - Marks dependencies for injection (constructor parameters or properties)
+ *
+ * Works with SWC and TypeScript's native decorator support.
+ * No external dependencies required (no reflect-metadata needed).
+ */
+import { useContainer, Container as DIContainer, defineMetadata, getOwnMetadata, getMetadata, TELEMETRY_METADATA_KEY, TELEMETRY_LISTENER_METADATA_KEY, } from "./container";
+const INJECTABLE_METADATA_KEY = "di:injectable";
+const INJECT_METADATA_KEY = "di:inject";
+/**
+ * Marks a method for telemetry tracking.
+ * When called, it will emit a 'telemetry' event on the container.
+ * Compatible with async and sync methods.
+ *
+ * @param options Configuration options for telemetry
+ */
+export function Telemetry(options = {}) {
+    return function (target, propertyKey, descriptor) {
+        const methods = getOwnMetadata(TELEMETRY_METADATA_KEY, target) || {};
+        methods[propertyKey] = options;
+        defineMetadata(TELEMETRY_METADATA_KEY, methods, target);
+    };
+}
+/**
+ * Marks a method as a listener for telemetry events.
+ * The method will be automatically registered to the container's 'telemetry' event.
+ */
+export function TelemetryListener() {
+    return function (target, propertyKey, descriptor) {
+        const listeners = getOwnMetadata(TELEMETRY_LISTENER_METADATA_KEY, target) || [];
+        listeners.push(propertyKey);
+        defineMetadata(TELEMETRY_LISTENER_METADATA_KEY, listeners, target);
+    };
+}
+/**
+ * Marks a class as injectable and registers it with the DI container
+ *
+ * @param options Configuration options for the injectable service
+ *
+ * @example
+ * @Container()
+ * class UserService {
+ *   getUser(id: string) { ... }
+ * }
+ *
+ * @example With options
+ * @Container({ singleton: false })
+ * class RequestScopedService {
+ *   // New instance created for each resolution
+ * }
+ */
+export function Container(options = {}) {
+    return function (constructor) {
+        const container = options.container ?? useContainer();
+        const singleton = options.singleton ?? true;
+        // Mark as injectable using our metadata store
+        defineMetadata(INJECTABLE_METADATA_KEY, true, constructor);
+        // Register with container
+        container.register(constructor, { singleton });
+        return constructor;
+    };
+}
+/**
+ * Marks a constructor parameter or property for dependency injection
+ *
+ * Can be used on:
+ * - Constructor parameters
+ * - Class properties
+ *
+ * @param target The class to inject dependencies into. Can be a class constructor or a string identifier.
+ *
+ * @example Constructor parameter injection
+ * @Container()
+ * class UserController {
+ *   constructor(@Component(UserService) userService: UserService) {}
+ * }
+ *
+ * @example Property injection
+ * @Container()
+ * class UserService {
+ *   @Component(DatabaseConnection)
+ *   private db: DatabaseConnection;
+ * }
+ *
+ * @example With string identifier
+ * @Container()
+ * class PaymentService {
+ *   constructor(@Component('apiKey') apiKey: string) {}
+ * }
+ */
+export function Component(target) {
+    return function (targetClass, propertyKey, parameterIndex) {
+        // Property injection
+        if (propertyKey && parameterIndex === undefined) {
+            // Store on both the class and its prototype to ensure it's accessible
+            const metadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass) || {};
+            metadata[propertyKey] = target;
+            defineMetadata(INJECT_METADATA_KEY, metadata, targetClass);
+            // Also store on the constructor if we have it
+            if (targetClass.constructor && targetClass.constructor !== Object) {
+                const constructorMetadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass.constructor) || {};
+                constructorMetadata[propertyKey] = target;
+                defineMetadata(INJECT_METADATA_KEY, constructorMetadata, targetClass.constructor);
+            }
+        }
+        // Constructor parameter injection
+        else if (parameterIndex !== undefined) {
+            const metadata = getOwnMetadata(INJECT_METADATA_KEY, targetClass) || {};
+            metadata[`param_${parameterIndex}`] = target;
+            defineMetadata(INJECT_METADATA_KEY, metadata, targetClass);
+        }
+    };
+}
+/**
+ * Check if a class is marked as injectable
+ */
+export function isInjectable(target) {
+    return getMetadata(INJECTABLE_METADATA_KEY, target) === true;
+}
+/**
+ * Get the container instance used by decorators
+ */
+export function getInjectionContainer() {
+    return useContainer();
+}