@stacksjs/bun-router 0.0.5 → 0.0.7

package/dist/observability/metrics.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Observability & Monitoring - Custom Metrics Collection with Prometheus Format
+ *
+ * Enterprise-grade metrics collection and Prometheus-compatible exposition
+ */
+import type { EnhancedRequest } from '../types';
+export interface MetricConfig {
+    prefix?: string;
+    labels?: Record<string, string>;
+    enableDefaultMetrics?: boolean;
+    collectInterval?: number;
+    maxHistogramBuckets?: number;
+    maxSummaryAge?: number;
+}
+export interface MetricLabels {
+    [key: string]: string;
+}
+export interface HistogramBucket {
+    le: number;
+    count: number;
+}
+export interface SummaryQuantile {
+    quantile: number;
+    value: number;
+}
+/**
+ * Base metric interface
+ */
+export declare abstract class Metric {
+    readonly name: string;
+    readonly help: string;
+    readonly type: string;
+    readonly labels: MetricLabels;
+    constructor(name: string, help: string, type: string, labels?: MetricLabels);
+    abstract getValue(): number | string;
+    abstract reset(): void;
+    abstract toPrometheusString(): string;
+}
+/**
+ * Counter metric - monotonically increasing value
+ */
+export declare class Counter extends Metric {
+    private value;
+    private labeledCounters;
+    constructor(name: string, help: string, labels?: MetricLabels);
+    inc(value?: number, labels?: MetricLabels): void;
+    getValue(): number;
+    reset(): void;
+    private getLabelKey;
+    toPrometheusString(): string;
+}
+/**
+ * Gauge metric - can go up and down
+ */
+export declare class Gauge extends Metric {
+    private value;
+    private labeledGauges;
+    constructor(name: string, help: string, labels?: MetricLabels);
+    set(value: number, labels?: MetricLabels): void;
+    inc(value?: number, labels?: MetricLabels): void;
+    dec(value?: number, labels?: MetricLabels): void;
+    getValue(): number;
+    reset(): void;
+    private getLabelKey;
+    toPrometheusString(): string;
+}
+/**
+ * Histogram metric - tracks distribution of values
+ */
+export declare class Histogram extends Metric {
+    private buckets;
+    private sum;
+    private count;
+    private readonly bucketBounds;
+    constructor(name: string, help: string, buckets?: number[], labels?: MetricLabels);
+    observe(value: number, _labels?: MetricLabels): void;
+    getValue(): number;
+    getCount(): number;
+    getSum(): number;
+    getBuckets(): HistogramBucket[];
+    reset(): void;
+    toPrometheusString(): string;
+}
+/**
+ * Summary metric - tracks quantiles over sliding time window
+ */
+export declare class Summary extends Metric {
+    private observations;
+    private sum;
+    private count;
+    private readonly quantiles;
+    private readonly maxAge;
+    constructor(name: string, help: string, quantiles?: number[], maxAge?: number, // 10 minutes
+    labels?: MetricLabels);
+    observe(value: number, _labels?: MetricLabels): void;
+    getValue(): number;
+    getCount(): number;
+    getSum(): number;
+    getQuantiles(): SummaryQuantile[];
+    private cleanOldObservations;
+    reset(): void;
+    toPrometheusString(): string;
+}
+/**
+ * Metrics registry
+ */
+export declare class MetricsRegistry {
+    private metrics;
+    private config;
+    private defaultMetrics;
+    constructor(config?: MetricConfig);
+    /**
+     * Register a metric
+     */
+    register(metric: Metric): void;
+    /**
+     * Get a metric by name
+     */
+    get(name: string): Metric | undefined;
+    /**
+     * Create and register a counter
+     */
+    createCounter(name: string, help: string, labels?: MetricLabels): Counter;
+    /**
+     * Create and register a gauge
+     */
+    createGauge(name: string, help: string, labels?: MetricLabels): Gauge;
+    /**
+     * Create and register a histogram
+     */
+    createHistogram(name: string, help: string, buckets?: number[], labels?: MetricLabels): Histogram;
+    /**
+     * Create and register a summary
+     */
+    createSummary(name: string, help: string, quantiles?: number[], maxAge?: number, labels?: MetricLabels): Summary;
+    /**
+     * Register default system metrics
+     */
+    private registerDefaultMetrics;
+    /**
+     * Collect system metrics
+     */
+    private collectSystemMetrics;
+    /**
+     * Get all metrics in Prometheus format
+     */
+    toPrometheusString(): string;
+    /**
+     * Get metrics as JSON
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Get metric names
+     */
+    getMetricNames(): string[];
+    /**
+     * Remove a metric
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+/**
+ * Initialize global metrics registry
+ */
+export declare function initializeMetrics(config?: MetricConfig): MetricsRegistry;
+/**
+ * Get global metrics registry
+ */
+export declare function getMetricsRegistry(): MetricsRegistry | null;
+/**
+ * Metrics middleware factory
+ */
+export declare function createMetricsMiddleware(_config?: Partial<MetricConfig>): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Metrics endpoint handler
+ */
+export declare function createMetricsHandler(): (req: EnhancedRequest) => Promise<Response>;

package/dist/observability/tracing.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Observability & Monitoring - Distributed Tracing with OpenTelemetry
+ *
+ * Enterprise-grade distributed tracing for request correlation and performance monitoring
+ */
+import type { EnhancedRequest } from '../types';
+export interface TraceConfig {
+    serviceName: string;
+    serviceVersion?: string;
+    environment?: string;
+    endpoint?: string;
+    headers?: Record<string, string>;
+    sampleRate?: number;
+    enableConsoleExporter?: boolean;
+    enableJaegerExporter?: boolean;
+    enableOTLPExporter?: boolean;
+    jaegerEndpoint?: string;
+    otlpEndpoint?: string;
+    attributes?: Record<string, any>;
+}
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    flags: number;
+    baggage?: Record<string, string>;
+}
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    operationName: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    tags: Record<string, any>;
+    logs: Array<{
+        timestamp: number;
+        fields: Record<string, any>;
+    }>;
+    status: 'ok' | 'error' | 'timeout';
+    statusMessage?: string;
+}
+export interface TraceData {
+    traceId: string;
+    spans: Span[];
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    serviceName: string;
+    environment: string;
+}
+/**
+ * Distributed tracing implementation
+ */
+export declare class DistributedTracer {
+    private config;
+    private activeSpans;
+    private traces;
+    private spanCounter;
+    constructor(config: TraceConfig);
+    /**
+     * Generate trace ID
+     */
+    generateTraceId(): string;
+    /**
+     * Generate span ID
+     */
+    generateSpanId(): string;
+    /**
+     * Start a new trace
+     */
+    startTrace(operationName: string, parentContext?: SpanContext): Span;
+    /**
+     * Start a child span
+     */
+    startChildSpan(operationName: string, parentSpan: Span): Span;
+    /**
+     * Finish a span
+     */
+    finishSpan(span: Span): void;
+    /**
+     * Add tags to span
+     */
+    setSpanTags(span: Span, tags: Record<string, any>): void;
+    /**
+     * Add log to span
+     */
+    logToSpan(span: Span, fields: Record<string, any>): void;
+    /**
+     * Set span status
+     */
+    setSpanStatus(span: Span, status: 'ok' | 'error' | 'timeout', message?: string): void;
+    /**
+     * Extract trace context from headers
+     */
+    extractTraceContext(headers: Headers): SpanContext | null;
+    /**
+     * Inject trace context into headers
+     */
+    injectTraceContext(span: Span, headers: Record<string, string>): void;
+    /**
+     * Parse W3C traceparent header
+     */
+    private parseTraceParent;
+    /**
+     * Parse Jaeger trace header
+     */
+    private parseJaegerTrace;
+    /**
+     * Parse B3 trace headers
+     */
+    private parseB3Trace;
+    /**
+     * Check if span should be sampled
+     */
+    private shouldSample;
+    /**
+     * Export span to configured exporters
+     */
+    private exportSpan;
+    /**
+     * Export to console
+     */
+    private exportToConsole;
+    /**
+     * Export to Jaeger (simplified)
+     */
+    private exportToJaeger;
+    /**
+     * Export to OTLP endpoint
+     */
+    private exportToOTLP;
+    /**
+     * Convert hex string to bytes
+     */
+    private hexToBytes;
+    /**
+     * Get active spans
+     */
+    getActiveSpans(): Span[];
+    /**
+     * Get trace by ID
+     */
+    getTrace(traceId: string): TraceData | undefined;
+    /**
+     * Get all traces
+     */
+    getAllTraces(): TraceData[];
+    /**
+     * Clear old traces (cleanup)
+     */
+    cleanup(maxAge?: number): void;
+}
+/**
+ * Initialize global tracer
+ */
+export declare function initializeTracer(config: TraceConfig): DistributedTracer;
+/**
+ * Get global tracer
+ */
+export declare function getTracer(): DistributedTracer | null;
+/**
+ * Tracing middleware factory
+ */
+export declare function createTracingMiddleware(_config?: Partial<TraceConfig>): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Trace helper functions
+ */
+export declare const TraceHelpers: {
+    /**
+     * Start a span within a request context
+     */
+    startSpan: (req: EnhancedRequest, operationName: string) => Span | null;
+    /**
+     * Finish a span
+     */
+    finishSpan: (req: EnhancedRequest, span: Span) => void;
+    /**
+     * Add tags to current span
+     */
+    addTags: (req: EnhancedRequest, tags: Record<string, any>) => void;
+    /**
+     * Log to current span
+     */
+    log: (req: EnhancedRequest, fields: Record<string, any>) => void;
+};

package/dist/optimization/bun-utilities.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Bun Runtime Optimization Utilities
+ *
+ * Generic optimization utilities leveraging Bun's runtime capabilities
+ */
+import { Buffer } from 'node:buffer';
+export interface BunOptimizationConfig {
+    enableJIT?: boolean;
+    enableGC?: boolean;
+    memoryLimit?: number;
+    cpuLimit?: number;
+    enableProfiling?: boolean;
+    enableTracing?: boolean;
+}
+export interface PerformanceMetrics {
+    memoryUsage: {
+        rss: number;
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+        arrayBuffers: number;
+    };
+    cpuUsage: {
+        user: number;
+        system: number;
+    };
+    eventLoop: {
+        delay: number;
+        utilization: number;
+    };
+    gc: {
+        collections: number;
+        duration: number;
+        freed: number;
+    };
+    bunSpecific: {
+        jitCompilations: number;
+        nativeCallsOptimized: number;
+        fileSystemCacheHits: number;
+    };
+}
+/**
+ * Bun runtime optimizer
+ */
+export declare class BunOptimizer {
+    private config;
+    private metrics;
+    private gcObserver?;
+    private performanceObserver?;
+    constructor(config?: BunOptimizationConfig);
+    /**
+     * Initialize performance metrics
+     */
+    private initializeMetrics;
+    /**
+     * Setup Bun-specific optimizations
+     */
+    private setupOptimizations;
+    /**
+     * Enable JIT compilation optimizations
+     */
+    private enableJITOptimizations;
+    /**
+     * Warm up common code paths for JIT
+     */
+    private warmupCodePaths;
+    /**
+     * Enable native call optimizations
+     */
+    private enableNativeOptimizations;
+    /**
+     * Configure garbage collection
+     */
+    private configureGarbageCollection;
+    /**
+     * Set memory limits
+     */
+    private setMemoryLimits;
+    /**
+     * Setup performance monitoring
+     */
+    private setupMonitoring;
+    /**
+     * Get current performance metrics
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Optimize specific function
+     */
+    optimizeFunction<T extends (...args: any[]) => any>(fn: T, options?: {
+        memoize?: boolean;
+        warmup?: boolean;
+        profile?: boolean;
+    }): T;
+    /**
+     * Create optimized buffer operations
+     */
+    createBufferOptimizer(): {
+        /**
+         * Get buffer from pool or create new one
+         */
+        getBuffer: (size: number) => Buffer;
+        /**
+         * Return buffer to pool
+         */
+        returnBuffer: (buffer: Buffer) => void;
+        /**
+         * Clear buffer pools
+         */
+        clearPools: () => void;
+        /**
+         * Get pool statistics
+         */
+        getStats: () => Record<number, number>;
+    };
+    /**
+     * Create optimized JSON operations
+     */
+    createJSONOptimizer(): {
+        /**
+         * Optimized JSON parse with caching
+         */
+        parse: (text: string) => any;
+        /**
+         * Optimized JSON stringify with caching
+         */
+        stringify: (value: any) => string;
+        /**
+         * Clear JSON caches
+         */
+        clearCaches: () => void;
+        /**
+         * Get cache statistics
+         */
+        getStats: () => {
+            parseCache: number;
+            stringifyCache: number;
+        };
+    };
+    /**
+     * Create worker pool for CPU-intensive tasks
+     */
+    createWorkerPool(workerScript: string, poolSize?: number): {
+        /**
+         * Execute task in worker
+         */
+        execute: <T>(data: any) => Promise<T>;
+        /**
+         * Terminate all workers
+         */
+        terminate: () => void;
+        /**
+         * Get pool statistics
+         */
+        getStats: () => {
+            poolSize: number;
+            queueSize: number;
+            activeWorkers: number;
+        };
+    };
+    /**
+     * Generate performance report
+     */
+    generateReport(): string;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): void;
+}
+/**
+ * Bun optimization utilities
+ */
+export declare const BunUtils: {
+    /**
+     * Check if running in Bun runtime
+     */
+    isBun: () => boolean;
+    /**
+     * Get Bun version
+     */
+    getBunVersion: () => string;
+    /**
+     * Optimize async function with Bun-specific features
+     */
+    optimizeAsync: <T extends (...args: any[]) => Promise<any>>(fn: T) => T;
+    /**
+     * Create optimized stream processor
+     */
+    createStreamProcessor: () => {
+        /**
+         * Process readable stream with Bun optimizations
+         */
+        processStream: (stream: ReadableStream) => Promise<Uint8Array>;
+        /**
+         * Create optimized transform stream
+         */
+        createTransformStream: <T, U>(transformer: (chunk: T) => U | Promise<U>) => TransformStream<T, U>;
+    };
+};
+/**
+ * Bun optimization factory functions
+ */
+export declare const BunOptimizationFactory: {
+    /**
+     * Create development optimizer
+     */
+    createDevelopment: () => BunOptimizer;
+    /**
+     * Create production optimizer
+     */
+    createProduction: () => BunOptimizer;
+    /**
+     * Create testing optimizer
+     */
+    createTesting: () => BunOptimizer;
+};
+/**
+ * Initialize global Bun optimizer
+ */
+export declare function initializeBunOptimizer(config?: BunOptimizationConfig): BunOptimizer;
+/**
+ * Get global Bun optimizer
+ */
+export declare function getBunOptimizer(): BunOptimizer | null;

package/dist/query-builder-integration.d.ts

@@ -0,0 +1,36 @@
+import type { Model, QueryBuilderModelResolver } from './model-binding';
+/**
+ * Integration layer for bun-query-builder with model binding
+ */
+export declare class QueryBuilderIntegration {
+    private queryBuilder;
+    private resolvers;
+    constructor(queryBuilder: any);
+    /**
+     * Register a model resolver and inject the query builder
+     */
+    registerResolver<TModel extends Model>(name: string, resolver: QueryBuilderModelResolver<TModel>): void;
+    /**
+     * Get a registered resolver
+     */
+    getResolver<TModel extends Model>(name: string): QueryBuilderModelResolver<TModel> | undefined;
+    /**
+     * Resolve a model by name and ID
+     */
+    resolveModel<TModel extends Model>(name: string, id: string | number, keyName?: string, context?: Record<string, Model>): Promise<TModel | null>;
+    /**
+     * Resolve a model or throw an error
+     */
+    resolveModelOrFail<TModel extends Model>(name: string, id: string | number, keyName?: string, context?: Record<string, Model>): Promise<TModel>;
+}
+/**
+ * Create a query builder integration instance
+ */
+export declare function createQueryBuilderIntegration(queryBuilder: any): QueryBuilderIntegration;
+/**
+ * Helper to create a basic model resolver using the query builder
+ */
+export declare function createBasicResolver<TModel extends Model>(tableName: string, options?: {
+    keyName?: string;
+    transform?: (row: any) => TModel;
+}): QueryBuilderModelResolver<TModel>;

package/dist/request/context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Request Context
+ *
+ * AsyncLocalStorage-backed access to the current request. The Router wires
+ * `runWithRequest()` automatically around handler/middleware invocation and
+ * calls `setCurrentRequest()` once the request has been enhanced with route
+ * params. User code reaches the active request via `request()` or
+ * `getCurrentRequest()` without having to thread it through call stacks.
+ */
+import type { EnhancedRequest } from '../types';
+/**
+ * Run `fn` inside an AsyncLocalStorage scope where `request()` and
+ * `getCurrentRequest()` resolve to `initial`. The Router calls this around
+ * each request automatically.
+ */
+export declare function runWithRequest<T>(initial: EnhancedRequest | Request, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Update the request stored in the current context. The Router calls this
+ * after enhancing the request with matched route params, so subsequent
+ * `request()` calls see the enhanced object.
+ */
+export declare function setCurrentRequest(req: EnhancedRequest): void;
+/**
+ * Returns the active request, or `undefined` when called outside a request
+ * scope. Prefer `request()` when the request is required.
+ */
+export declare function getCurrentRequest(): EnhancedRequest | undefined;
+/**
+ * Returns the active request. Throws when called outside a request scope —
+ * typically that means it was called before the Router established context
+ * (e.g. during module initialization) or inside a fire-and-forget callback
+ * that escaped the AsyncLocalStorage frame.
+ */
+export declare function request(): EnhancedRequest;