@stacksjs/bun-router 0.0.4 → 0.0.6

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;

package/dist/container/service-provider.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Service Providers for Bootstrapping
+ *
+ * Service provider system for registering services, managing lifecycle,
+ * and bootstrapping application components with dependency injection
+ */
+import type { BindingBuilder, Container, ResolutionContext } from './container';
+export interface ServiceProvider {
+    /**
+     * Register services in the container
+     */
+    register: (container: Container) => void | Promise<void>;
+    /**
+     * Boot services after all providers are registered
+     */
+    boot?: (container: Container) => void | Promise<void>;
+    /**
+     * Shutdown services gracefully
+     */
+    shutdown?: (container: Container) => void | Promise<void>;
+    /**
+     * Provider metadata
+     */
+    readonly name: string;
+    readonly version?: string;
+    readonly dependencies?: readonly string[];
+    readonly environment?: string[];
+    readonly priority?: number;
+}
+export interface DeferredServiceProvider extends ServiceProvider {
+    /**
+     * Services that should trigger loading of this provider
+     */
+    provides: () => (string | symbol | Function)[];
+    /**
+     * Check if provider should be loaded
+     */
+    isDeferred: () => boolean;
+}
+export interface ConditionalServiceProvider extends ServiceProvider {
+    /**
+     * Check if provider should be loaded based on environment
+     */
+    shouldLoad: (container: Container) => boolean | Promise<boolean>;
+}
+export interface ServiceProviderManager {
+    register: (provider: ServiceProvider) => this;
+    boot: () => Promise<void>;
+    shutdown: () => Promise<void>;
+    getProvider: (name: string) => ServiceProvider | undefined;
+    getProviders: () => ServiceProvider[];
+}
+/**
+ * Base service provider implementation
+ */
+export declare abstract class BaseServiceProvider implements ServiceProvider {
+    abstract readonly name: string;
+    readonly version?: string;
+    readonly dependencies?: readonly string[];
+    readonly environment?: string[];
+    readonly priority: number;
+    abstract register(container: Container): void | Promise<void>;
+    boot?(_container: Container): void | Promise<void>;
+    shutdown?(_container: Container): void | Promise<void>;
+    /**
+     * Helper method to bind singleton
+     */
+    protected singleton<T>(container: Container, token: string | symbol | Function, implementation: new (...args: any[]) => T): void;
+    /**
+     * Helper method to bind transient
+     */
+    protected transient<T>(container: Container, token: string | symbol | Function, implementation: new (...args: any[]) => T): void;
+    /**
+     * Helper method to bind value
+     */
+    protected value<T>(container: Container, token: string | symbol | Function, value: T): void;
+    /**
+     * Helper method to bind factory
+     */
+    protected factory<T>(container: Container, token: string | symbol | Function, factory: (...args: any[]) => T): void;
+    /**
+     * Helper method for conditional binding
+     */
+    protected when(container: Container, condition: (context: ResolutionContext) => boolean): {
+        bind: <T>(token: string | symbol | Function) => BindingBuilder<T>;
+    };
+    /**
+     * Helper method for environment-specific binding
+     */
+    protected forEnvironment(container: Container, ...environments: string[]): {
+        bind: <T>(token: string | symbol | Function) => BindingBuilder<T>;
+    };
+}
+/**
+ * Deferred service provider base class
+ */
+export declare abstract class BaseDeferredServiceProvider extends BaseServiceProvider implements DeferredServiceProvider {
+    abstract provides(): (string | symbol | Function)[];
+    isDeferred(): boolean;
+}
+/**
+ * Service provider manager implementation
+ */
+export declare class DefaultServiceProviderManager implements ServiceProviderManager {
+    private providers;
+    private deferredProviders;
+    private loadedProviders;
+    private bootedProviders;
+    private container;
+    constructor(container: Container);
+    /**
+     * Register a service provider
+     */
+    register(provider: ServiceProvider): this;
+    /**
+     * Boot all registered providers
+     */
+    boot(): Promise<void>;
+    /**
+     * Shutdown all providers
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get provider by name
+     */
+    getProvider(name: string): ServiceProvider | undefined;
+    /**
+     * Get all providers
+     */
+    getProviders(): ServiceProvider[];
+    /**
+     * Load deferred provider when needed
+     */
+    loadDeferredProvider(token: string | symbol | Function): Promise<void>;
+    /**
+     * Internal registration logic
+     */
+    private doRegister;
+    /**
+     * Load a provider
+     */
+    private loadProvider;
+    /**
+     * Boot a provider
+     */
+    private bootProvider;
+    /**
+     * Validate provider dependencies
+     */
+    private validateDependencies;
+    /**
+     * Check if provider is deferred
+     */
+    private isDeferredProvider;
+    /**
+     * Check if provider is conditional
+     */
+    private isConditionalProvider;
+}
+/**
+ * Common service providers
+ */
+/**
+ * Configuration service provider
+ */
+export declare class ConfigServiceProvider extends BaseServiceProvider {
+    readonly name = "config";
+    readonly priority = 100;
+    register(container: Container): void;
+}
+/**
+ * Logging service provider
+ */
+export declare class LoggingServiceProvider extends BaseServiceProvider {
+    readonly name = "logging";
+    readonly priority = 90;
+    register(container: Container): void;
+}
+/**
+ * Database service provider
+ */
+export declare class DatabaseServiceProvider extends BaseServiceProvider {
+    readonly name = "database";
+    readonly dependencies: readonly ["config", "logging"];
+    register(container: Container): void;
+    boot(container: Container): Promise<void>;
+    shutdown(container: Container): Promise<void>;
+}
+/**
+ * Cache service provider
+ */
+export declare class CacheServiceProvider extends BaseServiceProvider {
+    readonly name = "cache";
+    readonly dependencies: readonly ["config"];
+    register(container: Container): void;
+}
+/**
+ * Authentication service provider
+ */
+export declare class AuthServiceProvider extends BaseServiceProvider {
+    readonly name = "auth";
+    readonly dependencies: readonly ["config", "database"];
+    register(container: Container): void;
+}
+/**
+ * Validation service provider
+ */
+export declare class ValidationServiceProvider extends BaseServiceProvider {
+    readonly name = "validation";
+    register(container: Container): void;
+}
+/**
+ * Event service provider (deferred)
+ */
+export declare class EventServiceProvider extends BaseDeferredServiceProvider {
+    readonly name = "events";
+    provides(): (string | symbol | Function)[];
+    register(container: Container): void;
+}
+declare class ConfigService {
+    get(key: string, defaultValue?: any): any;
+}
+declare class Logger {
+    private config;
+    constructor(config: any);
+    log(message: string): void;
+}
+declare class ConsoleLogger extends Logger {
+    constructor();
+}
+declare class FileLogger extends Logger {
+    private filePath;
+    constructor(filePath: string);
+}
+declare class DatabaseConnection {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+}
+declare class UserRepository {
+    private db;
+    constructor(db: DatabaseConnection);
+}
+declare class PostRepository {
+    private db;
+    constructor(db: DatabaseConnection);
+}
+declare class CacheManager {
+    private store;
+    constructor(store: any);
+}
+declare class MemoryCache {
+    private cache;
+}
+declare class RedisCache {
+    private config;
+    constructor(config: any);
+}
+declare class AuthService {
+    private jwt;
+    private userRepo;
+    constructor(jwt: JwtService, userRepo: UserRepository);
+}
+declare class JwtService {
+    private config;
+    constructor(config: ConfigService);
+}
+declare class AuthGuard {
+    private auth;
+    constructor(auth: AuthService);
+}
+declare class Validator {
+    validate(_data: any, _rules: any): boolean;
+}
+declare class ValidationPipe {
+    private validator;
+    constructor(validator: Validator);
+}
+declare class EventBus {
+    emit(_event: string, _data: any): void;
+}
+declare class EventDispatcher {
+    private bus;
+    constructor(bus: EventBus);
+}
+export { AuthGuard, AuthService, CacheManager, ConfigService, ConsoleLogger, DatabaseConnection, EventBus, EventDispatcher, FileLogger, JwtService, Logger, MemoryCache, PostRepository, RedisCache, UserRepository, ValidationPipe, Validator, };