@stacksjs/bun-router 0.0.5 → 0.0.7

package/dist/container/container.d.ts

@@ -0,0 +1,273 @@
+/**
+ * IoC Container for Dependency Resolution
+ *
+ * Comprehensive dependency injection container with automatic resolution,
+ * lifecycle management, and contextual binding support
+ */
+declare global {
+    namespace Reflect {
+        function getMetadata(_metadataKey: any, _target: any, _propertyKey?: string | symbol): any;
+        function defineMetadata(_metadataKey: any, _metadataValue: any, _target: any, _propertyKey?: string | symbol): void;
+    }
+}
+export type BindingScope = 'singleton' | 'transient' | 'scoped' | 'request';
+export type Token = string | symbol | ((...args: any[]) => any) | (new (...args: any[]) => any) | Function;
+export interface BindingMetadata {
+    scope: BindingScope;
+    tags?: string[];
+    when?: (context: ResolutionContext) => boolean;
+    factory?: (..._args: any[]) => any;
+    dependencies?: Token[];
+    lazy?: boolean;
+    decorators?: ((..._args: any[]) => any)[];
+}
+export interface Binding<T = any> {
+    token: Token;
+    implementation?: new (...args: any[]) => T;
+    instance?: T;
+    factory?: (...args: any[]) => T;
+    value?: T;
+    metadata: BindingMetadata;
+}
+export interface ResolutionContext {
+    container: Container;
+    token: Token;
+    parent?: ResolutionContext;
+    environment?: string;
+    requestId?: string;
+    depth: number;
+    resolving: Set<Token>;
+}
+export interface ContainerOptions {
+    autoRegister?: boolean;
+    strictMode?: boolean;
+    maxDepth?: number;
+    enableDecorators?: boolean;
+    enableInterception?: boolean;
+    defaultScope?: BindingScope;
+}
+export declare const INJECTABLE_METADATA_KEY: unique symbol;
+export declare const INJECT_METADATA_KEY: unique symbol;
+export declare const OPTIONAL_METADATA_KEY: unique symbol;
+export declare const TAGGED_METADATA_KEY: unique symbol;
+export interface InjectableMetadata {
+    token?: string | symbol;
+    scope?: BindingScope;
+    tags?: string[];
+}
+export interface InjectMetadata {
+    token: Token;
+    optional?: boolean;
+    tags?: string[];
+    when?: (context: ResolutionContext) => boolean;
+}
+/**
+ * Main IoC Container implementation
+ */
+export declare class Container {
+    private bindings;
+    private instances;
+    private scopedInstances;
+    private interceptors;
+    private parent?;
+    private children;
+    private options;
+    constructor(options?: ContainerOptions);
+    /**
+     * Bind a token to an implementation
+     */
+    bind<T>(token: Token): BindingBuilder<T>;
+    /**
+     * Register a binding
+     */
+    register<T>(binding: Binding<T>): this;
+    /**
+     * Bind a singleton
+     */
+    singleton<T>(token: Token, implementation: new (...args: any[]) => T): Container;
+    /**
+     * Bind a transient
+     */
+    transient<T>(token: Token, implementation: new (...args: any[]) => T): Container;
+    /**
+     * Bind a value
+     */
+    value<T>(token: Token, value: T): Container;
+    /**
+     * Bind a factory
+     */
+    factory<T>(token: Token, factory: (...args: any[]) => T): Container;
+    /**
+     * Resolve a dependency
+     */
+    resolve<T>(token: Token, context?: Partial<ResolutionContext>): T;
+    /**
+     * Resolve all instances of a token (useful for arrays of services)
+     */
+    resolveAll<T>(token: Token): T[];
+    /**
+     * Resolve with tags
+     */
+    resolveTagged<T>(tag: string): T[];
+    /**
+     * Get all bindings with a specific tag
+     */
+    getTaggedBindings<T>(tag: string): Binding<T>[];
+    /**
+     * Add interceptor for a service
+     */
+    addInterceptor<T>(token: Token, interceptor: (service: T) => T): void;
+    /**
+     * Register controller (basic implementation for compatibility)
+     */
+    registerController(controller: new (...args: any[]) => any): void;
+    /**
+     * Get controller instance
+     */
+    getController<T>(controller: new (...args: any[]) => T): T;
+    /**
+     * Check if a token is bound
+     */
+    isBound(token: Token): boolean;
+    /**
+     * Unbind a token
+     */
+    unbind(token: Token): this;
+    /**
+     * Create a child container
+     */
+    createChild(options?: ContainerOptions): Container;
+    /**
+     * Create a scoped container
+     */
+    createScope(scopeId: string): Container;
+    /**
+     * Get all bindings
+     */
+    getBindings(): Map<Token, Binding>;
+    /**
+     * Clear all bindings and instances
+     */
+    clear(): this;
+    /**
+     * Add interceptor
+     */
+    intercept<T>(token: string | symbol | ((..._args: any[]) => any), interceptor: (instance: T, context: ResolutionContext) => T): this;
+    /**
+     * Internal resolution logic
+     */
+    private resolveInternal;
+    /**
+     * Create instance from binding
+     */
+    protected createInstance<T>(binding: Binding<T>, context: ResolutionContext): T;
+    /**
+     * Create new instance from binding
+     */
+    private createNewInstance;
+    /**
+     * Create instance from constructor
+     */
+    private createInstanceFromConstructor;
+    /**
+     * Get constructor dependencies using reflection
+     */
+    private getConstructorDependencies;
+    /**
+     * Parse constructor dependencies from function string
+     */
+    private parseConstructorDependencies;
+    /**
+     * Resolve array of dependencies
+     */
+    private resolveDependencies;
+    /**
+     * Auto-register and resolve
+     */
+    private autoRegisterAndResolve;
+    /**
+     * Apply decorators to instance
+     */
+    private applyDecorators;
+    /**
+     * Check if binding has tag
+     */
+    private hasTag;
+    /**
+     * Convert token to string for error messages
+     */
+    private tokenToString;
+    /**
+     * Generate unique request ID
+     */
+    private generateRequestId;
+}
+/**
+ * Fluent binding builder
+ */
+export declare class BindingBuilder<T> {
+    private container;
+    private binding;
+    constructor(container: Container, token: Token);
+    /**
+     * Bind to implementation
+     */
+    to(implementation: new (...args: any[]) => T): this;
+    /**
+     * Bind to value
+     */
+    toValue(value: T): this;
+    /**
+     * Bind to factory
+     */
+    toFactory(factory: (...args: any[]) => T): this;
+    /**
+     * Bind to existing instance
+     */
+    toInstance(instance: T): this;
+    /**
+     * Set singleton scope
+     */
+    inSingletonScope(): this;
+    /**
+     * Set transient scope
+     */
+    inTransientScope(): this;
+    /**
+     * Set scoped scope
+     */
+    inScopedScope(): this;
+    /**
+     * Set request scope
+     */
+    inRequestScope(): this;
+    /**
+     * Add tags
+     */
+    withTags(...tags: string[]): this;
+    /**
+     * Add contextual condition
+     */
+    when(condition: (context: ResolutionContext) => boolean): this;
+    /**
+     * Set as lazy
+     */
+    lazy(): this;
+    /**
+     * Build and register binding
+     */
+    build(): Container;
+}
+/**
+ * Get or create global container
+ */
+export declare function getContainer(): Container;
+/**
+ * Set global container
+ */
+export declare function setContainer(container: Container): void;
+/**
+ * Create new container
+ */
+export declare function createContainer(options?: ContainerOptions): Container;
+export { Container as DIContainer };

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

@@ -0,0 +1,240 @@
+/**
+ * Contextual Binding for Different Environments
+ *
+ * Advanced contextual binding system supporting environment-specific configurations,
+ * conditional service resolution, and dynamic binding based on runtime context
+ */
+import type { Binding, ResolutionContext, Token } from './container';
+import { Container } from './container';
+export interface ContextualBinding<T = any> extends Binding<T> {
+    conditions: BindingCondition[];
+    priority: number;
+    fallback?: Binding<T>;
+}
+export interface BindingCondition {
+    type: 'environment' | 'custom' | 'tag' | 'parent' | 'request';
+    predicate: (context: ResolutionContext) => boolean;
+    description?: string;
+}
+export interface EnvironmentConfig {
+    name: string;
+    variables: Record<string, any>;
+    services: Record<string, any>;
+    features: string[];
+}
+export interface ContextualBindingBuilder<T> {
+    to: (implementation: new (...args: any[]) => T) => ContextualBindingBuilder<T>;
+    toValue: (value: T) => ContextualBindingBuilder<T>;
+    toFactory: (factory: (...args: any[]) => T) => ContextualBindingBuilder<T>;
+    when: (condition: BindingCondition) => ContextualBindingBuilder<T>;
+    whenEnvironment: (...environments: string[]) => ContextualBindingBuilder<T>;
+    whenTag: (tag: string) => ContextualBindingBuilder<T>;
+    whenParent: (parentToken: string | symbol | ((..._args: any[]) => any)) => ContextualBindingBuilder<T>;
+    whenRequest: (predicate: (context: ResolutionContext) => boolean) => ContextualBindingBuilder<T>;
+    withPriority: (priority: number) => ContextualBindingBuilder<T>;
+    withFallback: (fallback: Binding<T>) => ContextualBindingBuilder<T>;
+    build: () => Container;
+}
+/**
+ * Environment manager for handling different deployment contexts
+ */
+export declare class EnvironmentManager {
+    private environments;
+    private currentEnvironment;
+    private variables;
+    constructor(defaultEnvironment?: string);
+    /**
+     * Register an environment configuration
+     */
+    register(config: EnvironmentConfig): this;
+    /**
+     * Set current environment
+     */
+    setEnvironment(name: string): this;
+    /**
+     * Get current environment
+     */
+    getCurrentEnvironment(): string;
+    /**
+     * Get environment configuration
+     */
+    getEnvironment(name?: string): EnvironmentConfig | undefined;
+    /**
+     * Check if environment is active
+     */
+    is(...environments: string[]): boolean;
+    /**
+     * Get environment variable
+     */
+    get(key: string, defaultValue?: any): any;
+    /**
+     * Set environment variable
+     */
+    set(key: string, value: any): this;
+    /**
+     * Check if feature is enabled
+     */
+    hasFeature(feature: string): boolean;
+    /**
+     * Load environment variables
+     */
+    private loadEnvironmentVariables;
+}
+/**
+ * Contextual binding builder implementation
+ */
+export declare class DefaultContextualBindingBuilder<T> implements ContextualBindingBuilder<T> {
+    private container;
+    private binding;
+    constructor(container: ContextualContainer, token: Token);
+    /**
+     * Add custom condition
+     */
+    when(condition: BindingCondition): ContextualBindingBuilder<T>;
+    /**
+     * Add environment condition
+     */
+    whenEnvironment(...environments: string[]): ContextualBindingBuilder<T>;
+    /**
+     * Add tag condition
+     */
+    whenTag(tag: string): ContextualBindingBuilder<T>;
+    /**
+     * Add parent condition
+     */
+    whenParent(parentToken: string | symbol | ((..._args: any[]) => any)): ContextualBindingBuilder<T>;
+    /**
+     * Add request condition
+     */
+    whenRequest(predicate: (context: ResolutionContext) => boolean): ContextualBindingBuilder<T>;
+    /**
+     * Set priority
+     */
+    withPriority(priority: number): ContextualBindingBuilder<T>;
+    /**
+     * Set fallback binding
+     */
+    withFallback(fallback: Binding<T>): ContextualBindingBuilder<T>;
+    /**
+     * Set implementation
+     */
+    to(implementation: new (...args: any[]) => T): this;
+    /**
+     * Set value
+     */
+    toValue(value: T): this;
+    /**
+     * Set factory
+     */
+    toFactory(factory: (...args: any[]) => T): this;
+    /**
+     * Set singleton scope
+     */
+    inSingletonScope(): this;
+    /**
+     * Set transient scope
+     */
+    inTransientScope(): this;
+    /**
+     * Build and register binding
+     */
+    build(): Container;
+}
+/**
+ * Enhanced container with contextual binding support
+ */
+export declare class ContextualContainer extends Container {
+    private contextualBindings;
+    private environmentManager;
+    constructor(options?: any);
+    /**
+     * Create contextual binding
+     */
+    bindContextual<T>(token: Token): ContextualBindingBuilder<T>;
+    /**
+     * Register contextual binding
+     */
+    registerContextualBinding<T>(binding: ContextualBinding<T>): this;
+    /**
+     * Get environment manager
+     */
+    getEnvironmentManager(): EnvironmentManager;
+    /**
+     * Environment-specific binding helpers
+     */
+    forDevelopment<T>(token: Token): ContextualBindingBuilder<T>;
+    forProduction<T>(token: Token): ContextualBindingBuilder<T>;
+    forTesting<T>(token: Token): ContextualBindingBuilder<T>;
+    forStaging<T>(token: Token): ContextualBindingBuilder<T>;
+    /**
+     * Override resolve to handle contextual bindings
+     */
+    resolve<T>(token: Token, context?: Partial<ResolutionContext>): T;
+    /**
+     * Find matching contextual binding
+     */
+    private findContextualBinding;
+    /**
+     * Evaluate binding conditions
+     */
+    private evaluateConditions;
+    /**
+     * Create instance from contextual binding
+     */
+    private createInstanceFromContextualBinding;
+    /**
+     * Generate unique request ID
+     */
+    private generateContextualRequestId;
+}
+/**
+ * Pre-configured environment setups
+ */
+export declare class EnvironmentPresets {
+    /**
+     * Development environment
+     */
+    static development(): EnvironmentConfig;
+    /**
+     * Production environment
+     */
+    static production(): EnvironmentConfig;
+    /**
+     * Testing environment
+     */
+    static testing(): EnvironmentConfig;
+    /**
+     * Staging environment
+     */
+    static staging(): EnvironmentConfig;
+}
+/**
+ * Contextual binding conditions factory
+ */
+export declare class BindingConditions {
+    /**
+     * Environment condition
+     */
+    static environment(...environments: string[]): BindingCondition;
+    /**
+     * Feature flag condition
+     */
+    static feature(featureName: string): BindingCondition;
+    /**
+     * Environment variable condition
+     */
+    static envVar(key: string, value: any): BindingCondition;
+    /**
+     * Request ID pattern condition
+     */
+    static requestPattern(pattern: RegExp): BindingCondition;
+    /**
+     * Time-based condition
+     */
+    static timeRange(startHour: number, endHour: number): BindingCondition;
+    /**
+     * Custom predicate condition
+     */
+    static custom(predicate: (context: ResolutionContext) => boolean, description?: string): BindingCondition;
+}
+export { ContextualContainer as DIContainer };

package/dist/container/decorators.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Modern Dependency Injection Decorators
+ */
+import type { ResolutionContext } from './container';
+import { Container } from './container';
+export declare const INJECTABLE_METADATA_KEY: unique symbol;
+export declare const INJECT_METADATA_KEY: unique symbol;
+export declare const OPTIONAL_METADATA_KEY: unique symbol;
+export declare const TAGGED_METADATA_KEY: unique symbol;
+export declare const CONTROLLER_METADATA_KEY: unique symbol;
+export declare const ROUTE_METADATA_KEY: unique symbol;
+export declare const MIDDLEWARE_METADATA_KEY: unique symbol;
+export declare const PARAM_METADATA_KEY: unique symbol;
+export interface InjectableMetadata {
+    token?: string | symbol;
+    scope?: 'singleton' | 'transient' | 'scoped' | 'request';
+    tags?: string[];
+}
+export interface InjectMetadata {
+    token: string | symbol | Function;
+    optional?: boolean;
+    tags?: string[];
+    when?: (context: ResolutionContext) => boolean;
+}
+export interface ControllerMetadata {
+    prefix?: string;
+    middleware?: Function[];
+    tags?: string[];
+}
+export interface RouteMetadata {
+    method: string;
+    path: string;
+    middleware?: Function[];
+    tags?: string[];
+}
+export interface ParamMetadata {
+    type: 'param' | 'query' | 'body' | 'header' | 'cookie';
+    key?: string;
+    token?: string | symbol | Function;
+    optional?: boolean;
+    transform?: (value: any) => any;
+    validate?: (value: any) => boolean;
+}
+/**
+ * Injectable decorator - marks a class as injectable
+ */
+export declare function Injectable(metadata?: InjectableMetadata): ClassDecorator;
+/**
+ * Inject decorator - specifies dependency injection for constructor parameters
+ */
+export declare function Inject(token: string | symbol | Function, options?: {
+    optional?: boolean;
+    tags?: string[];
+    when?: (context: ResolutionContext) => boolean;
+}): ParameterDecorator;
+/**
+ * Optional decorator - marks a dependency as optional
+ */
+export declare function Optional(): ParameterDecorator;
+/**
+ * Tagged decorator - injects services with specific tags
+ */
+export declare function Tagged(tag: string): ParameterDecorator;
+/**
+ * Controller decorator - marks a class as a controller
+ */
+export declare function Controller(prefix?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): ClassDecorator;
+/**
+ * HTTP method decorators
+ */
+export declare function Get(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+export declare function Post(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+export declare function Put(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+export declare function Delete(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+export declare function Patch(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+export declare function Options(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+export declare function Head(path?: string, options?: {
+    middleware?: Function[];
+    tags?: string[];
+}): MethodDecorator;
+/**
+ * UseMiddleware decorator - applies middleware to a class or method
+ */
+export declare function UseMiddleware(...middleware: Function[]): ClassDecorator & MethodDecorator;
+/**
+ * Parameter decorators for route handlers
+ */
+export declare function Param(key?: string): ParameterDecorator;
+export declare function Query(key?: string): ParameterDecorator;
+export declare function Body(): ParameterDecorator;
+export declare function Header(key?: string): ParameterDecorator;
+export declare function Cookie(key?: string): ParameterDecorator;
+export declare function InjectParam(token: string | symbol | Function): ParameterDecorator;
+/**
+ * Metadata reader utility class
+ */
+export declare class MetadataReader {
+    static getInjectableMetadata(target: Function): InjectableMetadata | undefined;
+    static getInjectMetadata(target: Function): InjectMetadata[];
+    static getOptionalMetadata(target: Function): boolean[];
+    static getTaggedMetadata(target: Function): string[];
+    static getControllerMetadata(target: Function): ControllerMetadata | undefined;
+    static getAllRoutes(target: Function): any[];
+    static getMiddlewareMetadata(target: Function, propertyKey?: string | symbol): Function[];
+    static getParamMetadata(target: Function, propertyKey: string | symbol): ParamMetadata[];
+}
+/**
+ * Modern Decorator Container
+ */
+export declare class DecoratorContainer extends Container {
+    /**
+     * Register a controller with automatic route discovery
+     */
+    registerController(controllerClass: Function): void;
+    /**
+     * Enhanced resolve method that handles decorator metadata
+     */
+    resolve<T>(token: string | symbol | Function, context?: ResolutionContext): T;
+}
+export declare const decoratorContainer: DecoratorContainer;