@buenojs/bueno 0.8.6 → 0.8.8

package/dist/jobs/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Background Jobs / Task Queue
+ *
+ * Type definitions for the job queue system.
+ * Supports Redis (production) and in-memory (development) drivers.
+ */
+export type JobStatus = "pending" | "processing" | "completed" | "failed" | "delayed";
+/**
+ * Represents a background job
+ */
+export interface Job<T = unknown> {
+    /** Unique job identifier */
+    id: string;
+    /** Job name/type (e.g., "email.welcome", "image.resize") */
+    name: string;
+    /** Job payload data */
+    data: T;
+    /** Current status of the job */
+    status: JobStatus;
+    /** Number of times this job has been attempted */
+    attempts: number;
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Error message if job failed */
+    error?: string;
+    /** Stack trace if job failed */
+    stackTrace?: string;
+    /** When the job was created (ISO 8601) */
+    createdAt: string;
+    /** When the job was last updated (ISO 8601) */
+    updatedAt: string;
+    /** When the job should start (ISO 8601, for delayed jobs) */
+    scheduledFor?: string;
+    /** When job processing started (ISO 8601) */
+    startedAt?: string;
+    /** When job processing completed (ISO 8601) */
+    completedAt?: string;
+    /** How long the job took to complete in milliseconds */
+    duration?: number;
+    /** Job priority (higher = process sooner) */
+    priority?: number;
+    /** Custom metadata attached to the job */
+    metadata?: Record<string, unknown>;
+    /** Worker that claimed this job */
+    workerId?: string;
+    /** When the job claim expires (for dead letter handling) */
+    claimExpiresAt?: string;
+}
+export interface JobQueueConfig {
+    /** Driver type: 'redis' for production, 'memory' for development */
+    driver?: "redis" | "memory";
+    /** Redis connection URL (required if driver is 'redis') */
+    url?: string;
+    /** Key prefix for all jobs (default: 'jobs:') */
+    keyPrefix?: string;
+    /** Maximum number of jobs to process concurrently (default: 10) */
+    concurrency?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay in seconds for exponential backoff (default: 1) */
+    retryDelay?: number;
+    /** Number of jobs to claim in a single poll (default: 10) */
+    batchSize?: number;
+    /** Polling interval in milliseconds (default: 1000) */
+    pollInterval?: number;
+    /** Job timeout in milliseconds (default: 300000 / 5 minutes) */
+    jobTimeout?: number;
+    /** Enable metrics collection (default: true) */
+    enableMetrics?: boolean;
+}
+export interface QueueOptions {
+    /** Schedule job for later execution (ISO 8601 or Date) */
+    delay?: number | Date;
+    /** Job priority (default: 0) */
+    priority?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Override default job timeout in milliseconds */
+    timeout?: number;
+    /** Maximum retries for this specific job */
+    maxRetries?: number;
+}
+/**
+ * Async handler function for processing jobs
+ */
+export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
+/**
+ * Metrics for job queue observability
+ */
+export interface QueueMetrics {
+    /** Total jobs enqueued */
+    enqueued: number;
+    /** Jobs successfully completed */
+    processed: number;
+    /** Jobs that failed (exceeded max retries) */
+    failed: number;
+    /** Jobs currently in pending state */
+    pending: number;
+    /** Jobs currently being processed */
+    processing: number;
+    /** Average job processing time in milliseconds */
+    avgLatency: number;
+    /** Total processing time in milliseconds */
+    totalLatency: number;
+    /** Number of job retries that occurred */
+    retried: number;
+    /** Success rate (0.0 to 1.0) */
+    successRate: number;
+    /** Average number of attempts per job */
+    avgAttempts: number;
+}
+export type JobEventType = "enqueued" | "started" | "completed" | "failed" | "retried";
+export interface JobEvent<T = unknown> {
+    type: JobEventType;
+    job: Job<T>;
+    timestamp: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface JobClaimHandle {
+    /** Whether the claim was successfully acquired */
+    acquired: boolean;
+    /** Release the claim (job goes back to pending) */
+    release: () => Promise<boolean>;
+    /** Extend the claim TTL for long-running jobs */
+    extend: (ttl?: number) => Promise<boolean>;
+    /** Check if claim is still valid */
+    isValid: () => Promise<boolean>;
+    /** Get remaining TTL in milliseconds */
+    getRemainingTTL: () => Promise<number>;
+    /** The claim key */
+    key: string;
+    /** The claim value (unique identifier) */
+    value: string;
+}
+/**
+ * Interface that both Redis and Memory drivers must implement
+ */
+export interface JobQueueDriver {
+    /**
+     * Initialize the driver (e.g., connect to Redis)
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the driver
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Enqueue a new job
+     */
+    enqueue<T = unknown>(name: string, data: T, options?: QueueOptions): Promise<string>;
+    /**
+     * Claim a batch of pending jobs for processing
+     */
+    claim(count: number, timeout: number): Promise<Job[]>;
+    /**
+     * Mark a job as completed
+     */
+    complete(jobId: string): Promise<void>;
+    /**
+     * Mark a job as failed
+     */
+    fail(jobId: string, error: string, stackTrace?: string): Promise<void>;
+    /**
+     * Schedule a job for retry
+     */
+    scheduleRetry(jobId: string, delayMs: number, error: string): Promise<void>;
+    /**
+     * Get a job by ID
+     */
+    getJob(jobId: string): Promise<Job | null>;
+    /**
+     * Get queue metrics
+     */
+    getMetrics(): Promise<QueueMetrics>;
+    /**
+     * Clear all jobs from the queue (use with caution!)
+     */
+    clear(): Promise<void>;
+}
+export interface HandlerRegistryEntry {
+    pattern: string;
+    handler: JobHandler<unknown>;
+    specificity: number;
+}
+export interface JobConfigValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"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"}

package/dist/jobs/worker.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Job Worker
+ *
+ * Production-grade worker for processing background jobs.
+ * Designed to run in a separate process/worker.
+ * Supports graceful shutdown and exponential backoff polling.
+ */
+import type { JobEvent, JobEventType, JobHandler, JobQueueConfig } from "./types";
+export declare class JobWorker {
+    private driver;
+    private handlers;
+    private handlerRegistry;
+    private eventListeners;
+    private isRunning;
+    private pollInterval;
+    private concurrency;
+    private jobTimeout;
+    private maxBackoffDelay;
+    private currentBackoff;
+    private inFlightJobs;
+    private shutdownTimeout;
+    constructor(config?: JobQueueConfig);
+    /**
+     * Initialize the worker (connect to backend)
+     */
+    init(): Promise<void>;
+    /**
+     * Register a handler for a job type
+     * Supports wildcards: "email.*" matches "email.welcome", "email.reset", etc.
+     */
+    handle(pattern: string, handler: JobHandler<unknown>): void;
+    /**
+     * Remove a handler
+     */
+    unhandle(pattern: string): void;
+    /**
+     * Listen for worker events
+     */
+    on(eventType: JobEventType, listener: (event: JobEvent) => void): void;
+    /**
+     * Stop listening for events
+     */
+    off(eventType: JobEventType, listener: (event: JobEvent) => void): void;
+    /**
+     * Emit a worker event
+     */
+    private _emitEvent;
+    /**
+     * Find the best matching handler for a job
+     */
+    private findHandler;
+    /**
+     * Check if a pattern matches a job name (supports wildcards)
+     */
+    private _patternMatches;
+    /**
+     * Start the worker (blocks until stopped)
+     */
+    start(): Promise<void>;
+    /**
+     * Main polling loop
+     */
+    private _pollLoop;
+    /**
+     * Process a single job
+     */
+    private _processJob;
+    /**
+     * Stop the worker gracefully
+     * Waits for in-flight jobs to complete before shutdown
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the number of jobs currently being processed
+     */
+    getInFlightCount(): number;
+    /**
+     * Get queue metrics
+     */
+    getMetrics(): Promise<import("./types").QueueMetrics>;
+    /**
+     * Check if worker is running
+     */
+    isActive(): boolean;
+}
+/**
+ * Create and start a worker from config
+ * Useful for CLI commands like: bueno queue:worker
+ */
+export declare function startWorker(config?: JobQueueConfig): Promise<void>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/jobs/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/jobs/worker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAGX,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,cAAc,EAEd,MAAM,SAAS,CAAC;AAIjB,qBAAa,SAAS;IACrB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,cAAc,CACX;IACX,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,eAAe,CAAS;gBAEpB,MAAM,GAAE,cAAmB;IAkBvC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI;IAkB3D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ/B;;OAEG;IACH,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAOtE;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAIvE;;OAEG;IACH,OAAO,CAAC,UAAU;IAmBlB;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;OAEG;YACW,SAAS;IAiDvB;;OAEG;YACW,WAAW;IAyDzB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B3B;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACG,UAAU;IAIhB;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGnB;AAID;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBxE"}

package/dist/lock/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Distributed Locking
+ *
+ * Redis-based distributed locks with in-memory fallback.
+ * Uses Bun 1.3+ native Redis client for production.
+ *
+ * Implementation based on Redis SET NX PX pattern with Lua scripts
+ * for safe lock release and extension.
+ */
+export interface LockConfig {
+    driver?: "redis" | "memory";
+    url?: string;
+    keyPrefix?: string;
+    defaultTTL?: number;
+    retryCount?: number;
+    retryDelay?: number;
+    autoExtend?: boolean;
+}
+export interface LockOptions {
+    ttl?: number;
+    retryCount?: number;
+    retryDelay?: number;
+}
+export interface Lock {
+    key: string;
+    value: string;
+    acquired: boolean;
+    acquiredAt: number;
+    ttl: number;
+    expiresAt: number;
+}
+export interface LockHandle {
+    /** Whether the lock was successfully acquired */
+    acquired: boolean;
+    /** Release the lock */
+    release: () => Promise<boolean>;
+    /** Extend the lock TTL */
+    extend: (ttl?: number) => Promise<boolean>;
+    /** Check if lock is still held */
+    isValid: () => Promise<boolean>;
+    /** Get remaining TTL in milliseconds */
+    getRemainingTTL: () => Promise<number>;
+    /** The lock key */
+    key: string;
+    /** The lock value (unique identifier) */
+    value: string;
+}
+export declare class DistributedLock {
+    private driver;
+    private driverType;
+    private keyPrefix;
+    private defaultTTL;
+    private defaultRetryCount;
+    private defaultRetryDelay;
+    private _isConnected;
+    constructor(config?: LockConfig);
+    /**
+     * Connect to the lock backend (Redis only)
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the lock backend
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the driver type
+     */
+    getDriverType(): "redis" | "memory";
+    /**
+     * Generate a unique lock value
+     */
+    private generateLockValue;
+    /**
+     * Try to acquire a lock without retry
+     */
+    private tryAcquire;
+    /**
+     * Acquire a lock
+     * Returns a LockHandle that can be used to release or extend the lock
+     */
+    acquire(key: string, options?: LockOptions): Promise<LockHandle>;
+    /**
+     * Acquire a lock and execute a function
+     * Automatically releases the lock when done
+     */
+    withLock<T>(key: string, fn: (lock: LockHandle) => Promise<T>, options?: LockOptions): Promise<T>;
+    /**
+     * Acquire a lock with automatic extension for long-running operations
+     */
+    withAutoExtend<T>(key: string, fn: (lock: LockHandle) => Promise<T>, options?: LockOptions): Promise<T>;
+    /**
+     * Try to acquire a lock without waiting
+     * Returns immediately whether the lock was acquired
+     */
+    tryLock(key: string, options?: LockOptions): Promise<LockHandle>;
+    /**
+     * Check if a lock exists (anyone holds it)
+     */
+    isLocked(key: string): Promise<boolean>;
+    /**
+     * Force release a lock (dangerous - use with caution)
+     * This will release the lock regardless of ownership
+     */
+    forceRelease(key: string): Promise<void>;
+    private sleep;
+}
+export declare class LockAcquireError extends Error {
+    constructor(message: string);
+}
+export declare class LockTimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Create a distributed lock instance
+ */
+export declare function createDistributedLock(config?: LockConfig): DistributedLock;
+/**
+ * Create a Redis-based distributed lock
+ */
+export declare function createRedisLock(url: string, options?: Omit<LockConfig, "driver" | "url">): DistributedLock;
+/**
+ * Create an in-memory lock (for development/testing)
+ */
+export declare function createMemoryLock(): DistributedLock;
+/**
+ * Get the default lock instance
+ */
+export declare function getDefaultLock(): DistributedLock;
+/**
+ * Set the default lock instance
+ */
+export declare function setDefaultLock(lock: DistributedLock): void;
+/**
+ * Acquire a lock using the default instance
+ */
+export declare function lock<T>(key: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lock/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lock/index.ts"],"names":[],"mappings":"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"}

package/dist/logger/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Structured Logging System
+ *
+ * Provides structured logging with JSON output, log levels,
+ * context-aware logging, and performance metrics.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    context?: Record<string, unknown>;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    duration?: number;
+    [key: string]: unknown;
+}
+export interface LoggerConfig {
+    level?: LogLevel;
+    pretty?: boolean;
+    timestamp?: boolean;
+    context?: Record<string, unknown>;
+    output?: "console" | "stdout" | ((entry: LogEntry) => void);
+}
+export interface LoggerContext {
+    requestId?: string;
+    userId?: string;
+    method?: string;
+    path?: string;
+    [key: string]: unknown;
+}
+export declare class Logger {
+    private level;
+    private pretty;
+    private timestamp;
+    private context;
+    private output;
+    constructor(config?: LoggerConfig);
+    /**
+     * Check if a log level should be logged
+     */
+    private shouldLog;
+    /**
+     * Serialize log entry to JSON
+     */
+    private serialize;
+    /**
+     * Pretty print log entry
+     */
+    private prettyPrint;
+    /**
+     * Create a log entry
+     */
+    private createEntry;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: Error | unknown, context?: Record<string, unknown>): void;
+    /**
+     * Log a fatal message
+     */
+    fatal(message: string, error?: Error | unknown, context?: Record<string, unknown>): void;
+    /**
+     * Create a child logger with additional context
+     */
+    child(context: Record<string, unknown>): Logger;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Add context to the logger
+     */
+    addContext(context: Record<string, unknown>): void;
+    /**
+     * Time a function
+     */
+    time<T>(label: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Create a timer
+     */
+    startTimer(label: string): () => number;
+}
+export interface RequestLogContext {
+    requestId?: string;
+    method: string;
+    path: string;
+    query?: string;
+    ip?: string;
+    userAgent?: string;
+    userId?: string;
+}
+export interface ResponseLogContext extends RequestLogContext {
+    statusCode: number;
+    duration: number;
+    contentLength?: number;
+}
+/**
+ * Create a request logger middleware
+ */
+export declare function createRequestLogger(logger: Logger): (ctx: unknown, next: () => Promise<unknown>) => Promise<unknown>;
+export declare class PerformanceLogger {
+    private logger;
+    private metrics;
+    constructor(logger: Logger);
+    /**
+     * Record a metric
+     */
+    record(name: string, value: number): void;
+    /**
+     * Get metric statistics
+     */
+    stats(name: string): {
+        count: number;
+        min: number;
+        max: number;
+        avg: number;
+        p99: number;
+    } | null;
+    /**
+     * Log all metrics
+     */
+    logMetrics(): void;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+/**
+ * Get the default logger instance
+ */
+export declare function getLogger(): Logger;
+/**
+ * Set the default logger instance
+ */
+export declare function setLogger(logger: Logger): void;
+/**
+ * Create a new logger
+ */
+export declare function createLogger(config?: LoggerConfig): Logger;
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"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"}