@stacksjs/bun-router 0.0.2

package/dist/config.d.ts

@@ -0,0 +1,274 @@
+import type { RouterConfig } from './types';
+export declare function getConfig(): Promise<RouterConfig>;
+/**
+ * Default configuration for the router
+ */
+export declare const defaultConfig: {
+  // General settings
+  verbose: false;
+  // Route paths
+  routesPath: 'routes';
+  apiRoutesPath: 'routes/api.ts';
+  webRoutesPath: 'routes/web.ts';
+  // URL prefixes
+  apiPrefix: '/api';
+  webPrefix: '';
+  // Default middleware configuration
+  defaultMiddleware: {
+  api: readonly ['security', 'helmet', 'cors', 'rate_limit', 'json_body', 'request_id'];
+  web: readonly ['security', 'helmet', 'ddos_protection', 'session', 'csrf']
+};
+  // Documentation settings
+  docs: {
+  output: 'api-reference.md';
+  groupBy: 'path';
+  includeExamples: true;
+  title: 'API Reference';
+  description: 'API documentation for the application.';
+  version: '1.0.0';
+  baseUrl: 'http://localhost:3000';
+  contact: {
+  name: 'API Support';
+  email: 'support@example.com';
+  url: 'https://example.com/support'
+};
+  security: {
+  bearer: {
+  type: 'http';
+  scheme: 'bearer';
+  bearerFormat: 'JWT'
+}
+}
+};
+  // Server settings
+  server: {
+  port: 3000;
+  hostname: 'localhost';
+  development: unknown;
+  cors: {
+  enabled: true;
+  origin: '*';
+  methods: readonly ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+  allowedHeaders: readonly ['Content-Type', 'Authorization'];
+  exposedHeaders: readonly ['X-Request-Id'];
+  credentials: false;
+  maxAge: 86400
+};
+  rateLimit: {
+  enabled: true;
+  max: 100;
+  timeWindow: 60000;
+  // 1 minute
+      message: 'Too many requests, please try again later'
+};
+  compression: {
+  enabled: true;
+  level: 6;
+  threshold: 1024
+};
+  static: {
+  enabled: true;
+  dir: 'public';
+  maxAge: 86400
+};
+  performance: {
+  cache: {
+  enabled: false;
+  type: 'memory';
+  ttl: 3600
+};
+  prefetch: {
+  enabled: false;
+  paths: Array<never>;
+  maxConcurrent: 5
+};
+  optimization: {
+  minify: false;
+  compress: false;
+  treeshake: false;
+  lazyLoad: false;
+  chunkSize: 50000
+};
+  monitoring: {
+  enabled: false;
+  metrics: {
+  responseTime: true;
+  memoryUsage: true;
+  cpuUsage: true;
+  errorRate: true;
+  requestRate: true;
+  cacheStats: true
+};
+  tracing: {
+  enabled: false;
+  sampleRate: 0.1;
+  // @ts-expect-error - Extended tracing config supports exporters array
+          exporters: readonly ['console'];
+  propagation: readonly ['w3c']
+};
+  logging: {
+  level: 'info';
+  format: 'json';
+  destination: 'console'
+}
+}
+};
+  security: {
+  schemes: {};
+  rateLimit: {
+  enabled: true;
+  max: 100;
+  timeWindow: 60000
+};
+  cors: {
+  enabled: true;
+  origin: '*';
+  methods: readonly ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
+};
+  csrf: {
+  enabled: true;
+  secret: 'csrf-secret';
+  cookie: {
+  name: 'csrf-token';
+  options: {
+  httpOnly: true;
+  secure: true;
+  sameSite: 'strict'
+}
+}
+};
+  helmet: {
+  enabled: true;
+  contentSecurityPolicy: {
+  directives: {
+  'default-src': readonly ['\'self\''];
+  'script-src': readonly ['\'self\'', '\'unsafe-inline\''];
+  'style-src': readonly ['\'self\'', '\'unsafe-inline\''];
+  'img-src': readonly ['\'self\'', 'data:', 'https:'];
+  'font-src': readonly ['\'self\''];
+  'connect-src': readonly ['\'self\''];
+  'media-src': readonly ['\'self\''];
+  'object-src': readonly ['\'none\''];
+  'child-src': readonly ['\'self\''];
+  'worker-src': readonly ['\'self\''];
+  'frame-ancestors': readonly ['\'none\''];
+  'form-action': readonly ['\'self\''];
+  'base-uri': readonly ['\'self\''];
+  'manifest-src': readonly ['\'self\'']
+}
+};
+  xssFilter: true;
+  noSniff: true;
+  frameOptions: 'DENY';
+  hidePoweredBy: true;
+  hsts: {
+  maxAge: 31536000;
+  includeSubDomains: true;
+  preload: true
+};
+  referrerPolicy: 'strict-origin-when-cross-origin'
+};
+  ddos: {
+  enabled: true;
+  maxRequestsPerSecond: 10;
+  maxRequestsPerMinute: 100;
+  maxRequestsPerHour: 1000;
+  burstLimit: 20;
+  windowSize: 60000;
+  blockDuration: 300000;
+  whitelistedIPs: Array<never>;
+  blacklistedIPs: Array<never>;
+  trustProxy: true;
+  store: 'memory'
+};
+  inputValidation: {
+  enabled: true;
+  sanitizeByDefault: true;
+  strictMode: false;
+  allowUnknownFields: true;
+  maxDepth: 10
+};
+  attackPrevention: {
+  enabled: true;
+  sqlInjection: true;
+  xss: true;
+  pathTraversal: true;
+  commandInjection: true;
+  ldapInjection: true;
+  xxe: true;
+  customPatterns: Array<never>
+};
+  requestFiltering: {
+  enabled: true;
+  blockSuspiciousPatterns: true;
+  maxRequestsPerMinute: 1000;
+  blockUserAgents: readonly ['sqlmap', 'nikto', 'nessus', 'openvas', 'nmap', 'masscan', 'zap', 'w3af'];
+  allowedMethods: readonly ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+  requireUserAgent: false;
+  maxBodySize: 10485760;
+  // 10MB
+        maxUrlLength: 2048;
+  maxHeaderSize: 8192;
+  allowedContentTypes: readonly ['application/json', 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain', 'text/html', 'application/xml', 'text/xml']
+};
+  ipFiltering: {
+  enabled: false;
+  whitelist: Array<never>;
+  blacklist: Array<never>;
+  blockPrivateIPs: false;
+  blockCloudProviders: false;
+  geoBlocking: {
+  enabled: false;
+  allowedCountries: Array<never>;
+  blockedCountries: Array<never>
+}
+};
+  responseSecurity: {
+  enabled: true;
+  removeServerHeaders: true;
+  addSecurityHeaders: true;
+  sanitizeErrors: true;
+  preventInfoDisclosure: true
+};
+  auth: {
+  jwt: {
+  secret: 'jwt-secret';
+  expiresIn: '1h';
+  algorithm: 'HS256'
+};
+  session: {
+  enabled: false;
+  secret: 'session-secret';
+  name: 'session';
+  resave: false;
+  rolling: true;
+  saveUninitialized: false;
+  cookie: {
+  maxAge: 86400000;
+  secure: true;
+  httpOnly: true;
+  sameSite: 'strict'
+}
+}
+}
+};
+  cluster: {
+  enabled: false;
+  workers: 'auto';
+  sticky: true
+};
+  gracefulShutdown: {
+  enabled: true;
+  timeout: 30000;
+  signals: readonly ['SIGTERM', 'SIGINT'];
+  forceTimeout: 10000
+};
+  middleware: {
+  order: Array<never>;
+  global: Array<never>
+};
+  hooks: {}
+}
+};
+// For backwards compatibility - synchronous access with default fallback
+export declare const config: RouterConfig;

package/dist/container/container.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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;
+// Dependency injection decorators
+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 interface BindingMetadata {
+  scope: BindingScope
+  tags?: string[]
+  when?: (context: ResolutionContext) => boolean
+  factory?: (...args: any[]) => any
+  dependencies?: Token[]
+  lazy?: boolean
+  decorators?: ((...args: any[]) => any)[]
+}
+export declare interface Binding<T = any> {
+  token: Token
+  implementation?: new (...args: any[]) => T
+  instance?: T
+  factory?: (...args: any[]) => T
+  value?: T
+  metadata: BindingMetadata
+}
+export declare interface ResolutionContext {
+  container: Container
+  token: Token
+  parent?: ResolutionContext
+  environment?: string
+  requestId?: string
+  depth: number
+  resolving: Set<Token>
+}
+export declare interface ContainerOptions {
+  autoRegister?: boolean
+  strictMode?: boolean
+  maxDepth?: number
+  enableDecorators?: boolean
+  enableInterception?: boolean
+  defaultScope?: BindingScope
+}
+// Decorator metadata
+export declare interface InjectableMetadata {
+  token?: string | symbol
+  scope?: BindingScope
+  tags?: string[]
+}
+export declare interface InjectMetadata {
+  token: Token
+  optional?: boolean
+  tags?: string[]
+  when?: (context: ResolutionContext) => boolean
+}
+// Container binding types
+export type BindingScope = 'singleton' | 'transient' | 'scoped' | 'request'
+// Token can be a string, symbol, function, constructor, or generic Function
+// eslint-disable-next-line ts/no-unsafe-function-type
+export type Token = string | symbol | ((...args: any[]) => any) | (new (...args: any[]) => any) | Function
+/**
+ * Main IoC Container implementation
+ */
+export declare class Container {
+  private bindings: any;
+  private instances: any;
+  private scopedInstances: any;
+  private interceptors: any;
+  private parent?: Container;
+  private children: any;
+  private options: Required<ContainerOptions>;
+  constructor(options?: ContainerOptions);
+  bind<T>(token: Token): BindingBuilder<T>;
+  register<T>(binding: Binding<T>): this;
+  singleton<T>(token: Token, implementation: new (...args: any[]) => T): Container;
+  transient<T>(token: Token, implementation: new (...args: any[]) => T): Container;
+  value<T>(token: Token, value: T): Container;
+  factory<T>(token: Token, factory: (...args: any[]) => T): Container;
+  resolve<T>(token: Token, context?: Partial<ResolutionContext>): T;
+  resolveAll<T>(token: Token): T[];
+  resolveTagged<T>(tag: string): T[];
+  getTaggedBindings<T>(tag: string): Binding<T>[];
+  addInterceptor<T>(token: Token, interceptor: (service: T) => T): void;
+  registerController(controller: new (...args: any[]) => any): void;
+  getController<T>(controller: new (...args: any[]) => T): T;
+  isBound(token: Token): boolean;
+  unbind(token: Token): this;
+  createChild(options?: ContainerOptions): Container;
+  createScope(scopeId: string): Container;
+  getBindings(): Map<Token, Binding>;
+  clear(): this;
+  intercept<T>(token: string | symbol | ((...args: any[]) => any), interceptor: (instance: T, context: ResolutionContext) => T): this;
+  private resolveInternal<T>(token: Token, context: ResolutionContext): T;
+  protected createInstance<T>(binding: Binding<T>, context: ResolutionContext): T;
+  private createNewInstance<T>(binding: Binding<T>, context: ResolutionContext): T;
+  private createInstanceFromConstructor<T>(constructor: new (...args: any[]) => T, context: ResolutionContext): T;
+  private getConstructorDependencies(constructor: ((...args: any[]) => any) | (new (...args: any[]) => any)): Token[];
+  private parseConstructorDependencies(constructor: ((...args: any[]) => any) | (new (...args: any[]) => any)): string[];
+  private resolveDependencies(dependencies: Token[], context: ResolutionContext): any[];
+  private autoRegisterAndResolve<T>(constructor: new (...args: any[]) => T, context: ResolutionContext): T;
+  private applyDecorators(instance: any, constructor: ((...args: any[]) => any) | (new (...args: any[]) => any)): void;
+  private hasTag(binding: Binding, tag: string): boolean;
+  private tokenToString(token: Token): string;
+  private generateRequestId(): string;
+}
+/**
+ * Fluent binding builder
+ */
+export declare class BindingBuilder<T> {
+  private binding: Partial<Binding<T>>;
+  private container: Container;
+  constructor(container: Container, token: Token);
+  to(implementation: new (...args: any[]) => T): this;
+  toValue(value: T): this;
+  toFactory(factory: (...args: any[]) => T): this;
+  toInstance(instance: T): this;
+  inSingletonScope(): this;
+  inTransientScope(): this;
+  inScopedScope(): this;
+  inRequestScope(): this;
+  withTags(tags: string[]): this;
+  when(condition: (context: ResolutionContext) => boolean): this;
+  lazy(): this;
+  build(): Container;
+}
+// Extend Reflect with metadata methods
+declare namespace 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 { Container as DIContainer };

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

@@ -0,0 +1,112 @@
+import { Container } from './container';
+import type { Binding, ResolutionContext, Token } from './container';
+// Contextual binding interfaces
+export declare interface ContextualBinding<T = any> extends Binding<T> {
+  conditions: BindingCondition[]
+  priority: number
+  fallback?: Binding<T>
+}
+export declare interface BindingCondition {
+  type: 'environment' | 'custom' | 'tag' | 'parent' | 'request'
+  predicate: (context: ResolutionContext) => boolean
+  description?: string
+}
+export declare interface EnvironmentConfig {
+  name: string
+  variables: Record<string, any>
+  services: Record<string, any>
+  features: string[]
+}
+export declare 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: any;
+  private currentEnvironment: string;
+  private variables: any;
+  constructor(defaultEnvironment?: string);
+  register(config: EnvironmentConfig): this;
+  setEnvironment(name: string): this;
+  getCurrentEnvironment(): string;
+  getEnvironment(name?: string): EnvironmentConfig | undefined;
+  is(environments: string[]): boolean;
+  get(key: string, defaultValue?: any): any;
+  set(key: string, value: any): this;
+  hasFeature(feature: string): boolean;
+  private loadEnvironmentVariables(): void;
+}
+/**
+ * Contextual binding builder implementation
+ */
+export declare class DefaultContextualBindingBuilder<T> implements ContextualBindingBuilder<T> {
+  private binding: Partial<ContextualBinding<T>>;
+  private container: ContextualContainer;
+  constructor(container: ContextualContainer, token: Token);
+  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>;
+  to(implementation: new (...args: any[]) => T): this;
+  toValue(value: T): this;
+  toFactory(factory: (...args: any[]) => T): this;
+  inSingletonScope(): this;
+  inTransientScope(): this;
+  build(): Container;
+}
+/**
+ * Enhanced container with contextual binding support
+ */
+export declare class ContextualContainer extends Container {
+  private contextualBindings: any;
+  private environmentManager: EnvironmentManager;
+  constructor(options?: any);
+  bindContextual<T>(token: Token): ContextualBindingBuilder<T>;
+  registerContextualBinding<T>(binding: ContextualBinding<T>): this;
+  getEnvironmentManager(): EnvironmentManager;
+  forDevelopment<T>(token: Token): ContextualBindingBuilder<T>;
+  forProduction<T>(token: Token): ContextualBindingBuilder<T>;
+  forTesting<T>(token: Token): ContextualBindingBuilder<T>;
+  forStaging<T>(token: Token): ContextualBindingBuilder<T>;
+  resolve<T>(token: Token, context?: Partial<ResolutionContext>): T;
+  private findContextualBinding(token: Token, context: ResolutionContext): ContextualBinding | undefined;
+  private evaluateConditions(conditions: BindingCondition[], context: ResolutionContext): boolean;
+  private createInstanceFromContextualBinding<T>(binding: ContextualBinding<T>, context: ResolutionContext): T;
+  private generateContextualRequestId(): string;
+}
+/**
+ * Pre-configured environment setups
+ */
+export declare class EnvironmentPresets {
+  static development(): EnvironmentConfig;
+  static production(): EnvironmentConfig;
+  static testing(): EnvironmentConfig;
+  static staging(): EnvironmentConfig;
+}
+/**
+ * Contextual binding conditions factory
+ */
+export declare class BindingConditions {
+  static environment(environments: string[]): BindingCondition;
+  static feature(featureName: string): BindingCondition;
+  static envVar(key: string, value: any): BindingCondition;
+  static requestPattern(pattern: RegExp): BindingCondition;
+  static timeRange(startHour: number, endHour: number): BindingCondition;
+  static custom(predicate: (context: ResolutionContext) => boolean, description?: string): BindingCondition;
+}
+export { ContextualContainer as DIContainer };

package/dist/container/decorators.d.ts

@@ -0,0 +1,114 @@
+import { Container } from './container';
+import type { ResolutionContext } from './container';
+/**
+ * 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 keys with explicit types
+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 a default instance
+export declare const decoratorContainer: DecoratorContainer;
+// Decorator metadata interfaces
+export declare interface InjectableMetadata {
+  token?: string | symbol
+  scope?: 'singleton' | 'transient' | 'scoped' | 'request'
+  tags?: string[]
+}
+export declare interface InjectMetadata {
+  token: string | symbol | Function
+  optional?: boolean
+  tags?: string[]
+  when?: (context: ResolutionContext) => boolean
+}
+export declare interface ControllerMetadata {
+  prefix?: string
+  middleware?: Function[]
+  tags?: string[]
+}
+export declare interface RouteMetadata {
+  method: string
+  path: string
+  middleware?: Function[]
+  tags?: string[]
+}
+export declare interface ParamMetadata {
+  type: 'param' | 'query' | 'body' | 'header' | 'cookie'
+  key?: string
+  token?: string | symbol | Function
+  optional?: boolean
+  transform?: (value: any) => any
+  validate?: (value: any) => boolean
+}
+/**
+ * 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 {
+  registerController(controllerClass: Function): void;
+  resolve<T>(token: string | symbol | Function, context?: ResolutionContext): T;
+}