qwerk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,744 @@
+/**
+* Job status
+*/
+type JobStatus = "waiting" | "active" | "completed" | "failed" | "delayed" | "stalled";
+/**
+* Logger interface - implement this to use your own logger
+*/
+interface Logger {
+	debug(message: string, ...args: unknown[]): void;
+	info(message: string, ...args: unknown[]): void;
+	warn(message: string, ...args: unknown[]): void;
+	error(message: string, ...args: unknown[]): void;
+}
+/**
+* Default console logger
+*/
+declare const consoleLogger: Logger;
+/**
+* Silent logger (no output)
+*/
+declare const silentLogger: Logger;
+/**
+* Represents a job in the queue
+*/
+interface Job<
+	T = unknown,
+	R = unknown
+> {
+	readonly id: string;
+	readonly name: string;
+	readonly data: T;
+	readonly attempts: number;
+	readonly maxAttempts: number;
+	readonly createdAt: number;
+	readonly scheduledAt: number;
+	readonly backoff: BackoffOptions;
+	/** When the job started processing (set by pop) */
+	readonly startedAt?: number;
+	/** Job priority (lower = higher priority, default: 0) */
+	readonly priority: number;
+	/** Job timeout in ms (default: 30000) */
+	readonly timeout: number;
+	/** Repeat configuration for recurring jobs */
+	readonly repeat?: RepeatOptions;
+	/** Current progress (0-100) */
+	readonly progress?: number;
+	/** Job result (set after completion) */
+	readonly result?: R;
+}
+/**
+* Options for creating a new job
+*/
+interface JobOptions {
+	/** Maximum retry attempts (default: 3) */
+	maxAttempts?: number;
+	/** Delay before first execution in ms (default: 0) */
+	delay?: number;
+	/** Backoff strategy for retries */
+	backoff?: BackoffOptions;
+	/** Job priority - lower number = higher priority (default: 0) */
+	priority?: number;
+	/** Job timeout in ms - job fails if handler exceeds this (default: 30000) */
+	timeout?: number;
+	/** Unique job ID - if provided, prevents duplicate jobs with same ID */
+	jobId?: string;
+	/** Repeat configuration for recurring jobs */
+	repeat?: RepeatOptions;
+}
+/**
+* Configuration for repeatable/recurring jobs
+*/
+interface RepeatOptions {
+	/** Cron expression (e.g., "0 * * * *" for every hour) */
+	cron?: string;
+	/** Fixed interval in ms between job completions */
+	every?: number;
+	/** Maximum number of times to repeat (undefined = infinite) */
+	limit?: number;
+	/** Number of times this job has been repeated */
+	count?: number;
+	/** Unique key for this repeatable job (auto-generated if not provided) */
+	key?: string;
+}
+/**
+* Backoff configuration for retries
+*/
+interface BackoffOptions {
+	type: "exponential" | "linear" | "fixed";
+	/** Base delay in ms (default: 1000) */
+	delay: number;
+	/** Maximum delay in ms (default: 30000) */
+	maxDelay?: number;
+}
+/**
+* Context passed to job handlers for progress updates and signals
+*/
+interface JobContext {
+	/** Update job progress (0-100) */
+	updateProgress(progress: number): Promise<void>;
+	/** AbortSignal for cancellation */
+	signal: AbortSignal;
+}
+/**
+* Backend interface - implement this for custom storage
+*/
+interface Backend {
+	/**
+	* Add a job to the queue
+	* @returns false if job with same ID already exists (deduplication)
+	*/
+	push(job: Job): Promise<boolean>;
+	/**
+	* Add multiple jobs to the queue (bulk operation)
+	* @returns number of jobs successfully added
+	*/
+	pushBulk(jobs: Job[]): Promise<number>;
+	/**
+	* Get the next job ready for processing (atomic)
+	* Moves job to "active" state with visibility timeout
+	*/
+	pop(visibilityTimeout: number): Promise<Job | null>;
+	/**
+	* Acknowledge successful job completion
+	* Removes job from active set and stores result
+	*/
+	ack(jobId: string, result?: unknown): Promise<void>;
+	/**
+	* Negative acknowledge - reschedule job for retry
+	*/
+	nack(job: Job, nextAttemptAt: number): Promise<void>;
+	/**
+	* Move a job to the dead letter queue
+	*/
+	fail(job: Job, error: Error): Promise<void>;
+	/**
+	* Get stalled jobs (exceeded visibility timeout)
+	* These should be moved back to waiting or failed
+	*/
+	getStalled(): Promise<Job[]>;
+	/**
+	* Update job progress (0-100)
+	*/
+	updateProgress(jobId: string, progress: number): Promise<void>;
+	/**
+	* Get a completed job with its result
+	*/
+	getCompleted(jobId: string): Promise<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	} | null>;
+	/**
+	* Get completed jobs count
+	*/
+	completedCount(): Promise<number>;
+	/**
+	* Get recent completed jobs
+	*/
+	getCompletedJobs(limit?: number): Promise<Array<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	}>>;
+	/**
+	* Subscribe to job notifications (for real-time processing)
+	*/
+	subscribe(callback: () => void): void;
+	/**
+	* Unsubscribe from notifications
+	*/
+	unsubscribe(): void;
+	/**
+	* Get queue size (pending jobs)
+	*/
+	size(): Promise<number>;
+	/**
+	* Get count of active (processing) jobs
+	*/
+	activeCount(): Promise<number>;
+	/**
+	* Get count of failed jobs in DLQ
+	*/
+	failedCount(): Promise<number>;
+	/**
+	* Get failed jobs from DLQ
+	*/
+	getFailed(limit?: number): Promise<Array<{
+		job: Job;
+		error: string;
+		failedAt: number;
+	}>>;
+	/**
+	* Retry a failed job (move from DLQ back to queue)
+	*/
+	retryFailed(jobId: string): Promise<boolean>;
+	/**
+	* Remove a job by ID (from any state)
+	*/
+	remove(jobId: string): Promise<boolean>;
+	/**
+	* Clear all jobs (waiting, active, failed)
+	*/
+	clear(): Promise<void>;
+	/**
+	* Close/cleanup resources
+	*/
+	close?(): Promise<void>;
+}
+/**
+* Queue events
+*/
+interface QueueEvents<
+	T = unknown,
+	R = unknown
+> {
+	/** Job completed successfully */
+	completed: (job: Job<T, R>, result: R | undefined) => void;
+	/** Job failed after all retries (moved to DLQ) */
+	failed: (job: Job<T, R>, error: Error) => void;
+	/** Job failed, will retry */
+	retry: (job: Job<T, R>, error: Error) => void;
+	/** Job exceeded visibility timeout, will be reprocessed */
+	stalled: (job: Job<T, R>) => void;
+	/** Job timed out during processing */
+	timeout: (job: Job<T, R>) => void;
+	/** Job started processing */
+	active: (job: Job<T, R>) => void;
+	/** Job was added to the queue */
+	added: (job: Job<T, R>) => void;
+	/** Rate limit hit - job delayed */
+	rateLimited: (job: Job<T, R>) => void;
+	/** Job progress updated */
+	progress: (job: Job<T, R>, progress: number) => void;
+}
+/**
+* Rate limiter configuration
+*/
+interface RateLimitOptions {
+	/** Maximum number of jobs to process per interval */
+	max: number;
+	/** Time window in ms (default: 1000 = 1 second) */
+	duration?: number;
+}
+/**
+* Queue options
+*/
+interface QueueOptions {
+	/** Polling interval in ms when no jobs (default: 1000) */
+	pollInterval?: number;
+	/** Concurrency limit (default: 1) */
+	concurrency?: number;
+	/** Visibility timeout in ms - how long a job can be processing before considered stalled (default: 30000) */
+	visibilityTimeout?: number;
+	/** How often to check for stalled jobs in ms (default: 5000) */
+	stalledInterval?: number;
+	/** Rate limiting configuration */
+	rateLimit?: RateLimitOptions;
+	/** Custom logger (default: consoleLogger) */
+	logger?: Logger;
+	/** Maximum job payload size in bytes (default: unlimited) */
+	maxPayloadSize?: number;
+	/** Maximum queue size - rejects new jobs when exceeded (default: unlimited) */
+	maxQueueSize?: number;
+}
+/**
+* Queue metrics snapshot
+*/
+interface QueueMetrics {
+	/** Number of jobs waiting to be processed */
+	waiting: number;
+	/** Number of jobs currently being processed */
+	active: number;
+	/** Number of failed jobs in DLQ */
+	failed: number;
+	/** Total jobs completed since start */
+	completed: number;
+	/** Total jobs that failed (moved to DLQ) since start */
+	totalFailed: number;
+	/** Total job processing time in ms */
+	totalProcessingTime: number;
+	/** Average job processing time in ms */
+	avgProcessingTime: number;
+	/** Jobs processed per second (recent) */
+	throughput: number;
+}
+type EventCallback = (...args: unknown[]) => void;
+/**
+* Events emitted by a JobHandle
+*/
+interface JobHandleEvents<
+	TData,
+	TResult
+> {
+	completed: (job: Job<TData, TResult>, result: TResult | undefined) => void;
+	failed: (job: Job<TData, TResult>, error: Error) => void;
+	retry: (job: Job<TData, TResult>, error: Error) => void;
+	stalled: (job: Job<TData, TResult>) => void;
+	timeout: (job: Job<TData, TResult>) => void;
+	active: (job: Job<TData, TResult>) => void;
+	added: (job: Job<TData, TResult>) => void;
+	progress: (job: Job<TData, TResult>, progress: number) => void;
+}
+/**
+* Options for defining a job type
+*/
+interface JobDefineOptions {
+	maxAttempts?: number;
+	timeout?: number;
+	backoff?: BackoffOptions;
+	priority?: number;
+}
+/**
+* Options when adding a job instance (overrides defaults)
+*/
+interface JobAddOptions {
+	delay?: number;
+	priority?: number;
+	jobId?: string;
+	maxAttempts?: number;
+	timeout?: number;
+	backoff?: BackoffOptions;
+	repeat?: RepeatOptions;
+}
+/**
+* Handler function for processing jobs
+*/
+type JobHandleHandler<
+	TData,
+	TResult
+> = (data: TData, ctx: JobContext) => Promise<TResult | void> | TResult | void;
+/**
+* Interface for queue operations needed by JobHandle
+*/
+interface JobHandleQueue {
+	addJob(name: string, data: unknown, options: JobOptions): Promise<Job | null>;
+	addJobBulk(jobs: Array<{
+		name: string;
+		data: unknown;
+		options?: JobOptions;
+	}>): Promise<Job[]>;
+	processJob(name: string, handler: (job: Job, ctx: JobContext) => Promise<unknown>): void;
+	subscribeToEvent(event: string, name: string, callback: EventCallback): void;
+	unsubscribeFromEvent(event: string, name: string, callback: EventCallback): void;
+}
+/**
+* A typed handle for a specific job type.
+* Provides type-safe methods for adding and processing jobs.
+*/
+declare class JobHandle<
+	TData = unknown,
+	TResult = void
+> {
+	private readonly queue;
+	readonly name: string;
+	private readonly defaults;
+	private events;
+	private onceEvents;
+	private handler;
+	constructor(queue: JobHandleQueue, name: string, defaults?: JobDefineOptions);
+	/**
+	* Register a handler for this job type
+	*/
+	process(handler: JobHandleHandler<TData, TResult>): this;
+	/**
+	* Add a job to the queue
+	*/
+	add(data: TData, options?: JobAddOptions): Promise<Job<TData, TResult> | null>;
+	/**
+	* Add multiple jobs to the queue
+	*/
+	addBulk(items: Array<{
+		data: TData;
+		options?: JobAddOptions;
+	}>): Promise<Job<TData, TResult>[]>;
+	/**
+	* Subscribe to events for this job type
+	*/
+	on<K extends keyof JobHandleEvents<TData, TResult>>(event: K, callback: JobHandleEvents<TData, TResult>[K]): this;
+	/**
+	* Subscribe to a single occurrence of an event
+	*/
+	once<K extends keyof JobHandleEvents<TData, TResult>>(event: K, callback: JobHandleEvents<TData, TResult>[K]): this;
+	/**
+	* Unsubscribe from events
+	*/
+	off<K extends keyof JobHandleEvents<TData, TResult>>(event: K, callback: JobHandleEvents<TData, TResult>[K]): this;
+}
+type EventCallback2 = (...args: unknown[]) => void;
+/**
+* Type-safe job queue with pluggable backends
+*/
+declare class Queue implements JobHandleQueue {
+	private backend;
+	private handlers;
+	private events;
+	private onceEvents;
+	private jobEvents;
+	private running;
+	private processing;
+	private pollInterval;
+	private concurrency;
+	private visibilityTimeout;
+	private stalledInterval;
+	private pollTimer;
+	private stalledTimer;
+	private activeJobs;
+	private shuttingDown;
+	private shutdownResolve;
+	private rateLimit;
+	private rateLimitTokens;
+	private rateLimitLastRefill;
+	private logger;
+	private maxPayloadSize;
+	private maxQueueSize;
+	private metricsData;
+	constructor(backend: Backend, options?: QueueOptions);
+	/**
+	* Add a job to the queue (internal)
+	* @internal
+	*/
+	private add;
+	/**
+	* Add multiple jobs to the queue (internal)
+	* @internal
+	*/
+	private addBulk;
+	/**
+	* Define a new job type and return a typed handle for it.
+	* The handle provides type-safe methods for adding and processing jobs.
+	*
+	* @example
+	* const sendEmail = queue.define<{ to: string; subject: string }>("send-email", {
+	*   maxAttempts: 5,
+	*   timeout: 60_000,
+	* });
+	*
+	* sendEmail.process(async (data, ctx) => {
+	*   await mail(data.to, data.subject);
+	* });
+	*
+	* await sendEmail.add({ to: "test@example.com", subject: "Hello" });
+	*/
+	define<
+		TData,
+		TResult = void
+	>(name: string, defaults?: JobDefineOptions): JobHandle<TData, TResult>;
+	/** @internal */
+	addJob(name: string, data: unknown, options: JobOptions): Promise<Job | null>;
+	/** @internal */
+	addJobBulk(jobs: Array<{
+		name: string;
+		data: unknown;
+		options?: JobOptions;
+	}>): Promise<Job[]>;
+	/** @internal */
+	processJob(name: string, handler: (job: Job, ctx: JobContext) => Promise<unknown>): void;
+	/** @internal */
+	subscribeToEvent(event: string, name: string, callback: EventCallback2): void;
+	/** @internal */
+	unsubscribeFromEvent(event: string, name: string, callback: EventCallback2): void;
+	/**
+	* Start processing jobs
+	*/
+	start(): void;
+	/**
+	* Stop processing jobs gracefully
+	* @param timeout Max time to wait for in-flight jobs (default: 30000ms)
+	* @returns Promise that resolves when all jobs complete or timeout
+	*/
+	stop(timeout?: number): Promise<void>;
+	/**
+	* Pause processing (finish current jobs but don't pick up new ones)
+	*/
+	pause(): void;
+	/**
+	* Resume processing after pause
+	*/
+	resume(): void;
+	/**
+	* Wait for all current jobs to complete
+	*/
+	drain(): Promise<void>;
+	/**
+	* Subscribe to queue events
+	*/
+	on<K extends keyof QueueEvents>(event: K, callback: QueueEvents[K]): this;
+	/**
+	* Subscribe to a single occurrence of an event
+	*/
+	once<K extends keyof QueueEvents>(event: K, callback: QueueEvents[K]): this;
+	/**
+	* Unsubscribe from queue events
+	*/
+	off<K extends keyof QueueEvents>(event: K, callback: QueueEvents[K]): this;
+	/**
+	* Get current queue size (waiting jobs)
+	*/
+	size(): Promise<number>;
+	/**
+	* Get count of active (processing) jobs
+	*/
+	activeCount(): Promise<number>;
+	/**
+	* Get count of failed jobs
+	*/
+	failedCount(): Promise<number>;
+	/**
+	* Get failed jobs
+	*/
+	getFailed(limit?: number): Promise<Array<{
+		job: Job;
+		error: string;
+		failedAt: number;
+	}>>;
+	/**
+	* Get a completed job with its result
+	*/
+	getCompleted(jobId: string): Promise<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	} | null>;
+	/**
+	* Get count of completed jobs (with stored results)
+	*/
+	completedCount(): Promise<number>;
+	/**
+	* Get recent completed jobs with results
+	*/
+	getCompletedJobs(limit?: number): Promise<Array<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	}>>;
+	/**
+	* Retry a failed job
+	*/
+	retryFailed(jobId: string): Promise<boolean>;
+	/**
+	* Remove a job by ID
+	*/
+	remove(jobId: string): Promise<boolean>;
+	/**
+	* Clear all jobs
+	*/
+	clear(): Promise<void>;
+	/**
+	* Close the queue and backend
+	*/
+	close(): Promise<void>;
+	/**
+	* Get queue metrics
+	*/
+	getMetrics(): Promise<QueueMetrics>;
+	private startStalledChecker;
+	private checkStalled;
+	private checkRateLimit;
+	private tick;
+	private executeJob;
+	private scheduleNextRepeat;
+	private emit;
+}
+/**
+* In-memory backend - single process, no persistence
+* Good for development, testing, or simple use cases
+* Uses a min-heap for O(log n) job retrieval by priority
+*/
+declare class MemoryBackend implements Backend {
+	/** Waiting jobs heap (sorted by priority, then scheduledAt) */
+	private waitingHeap;
+	/** Waiting jobs map for O(1) lookup by ID */
+	private waiting;
+	/** Active jobs being processed */
+	private active;
+	/** Failed jobs (dead letter queue) */
+	private failed;
+	/** Completed jobs with results */
+	private completed;
+	/** All job IDs for deduplication */
+	private allIds;
+	/** Job progress */
+	private progress;
+	private listener;
+	push(job: Job): Promise<boolean>;
+	pushBulk(jobs: Job[]): Promise<number>;
+	pop(visibilityTimeout: number): Promise<Job | null>;
+	ack(jobId: string, result?: unknown): Promise<void>;
+	nack(job: Job, nextAttemptAt: number): Promise<void>;
+	fail(job: Job, error: Error): Promise<void>;
+	getStalled(): Promise<Job[]>;
+	updateProgress(jobId: string, progress: number): Promise<void>;
+	getCompleted(jobId: string): Promise<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	} | null>;
+	completedCount(): Promise<number>;
+	getCompletedJobs(limit?: number): Promise<Array<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	}>>;
+	subscribe(callback: () => void): void;
+	unsubscribe(): void;
+	size(): Promise<number>;
+	activeCount(): Promise<number>;
+	failedCount(): Promise<number>;
+	getFailed(limit?: number): Promise<Array<{
+		job: Job;
+		error: string;
+		failedAt: number;
+	}>>;
+	retryFailed(jobId: string): Promise<boolean>;
+	remove(jobId: string): Promise<boolean>;
+	clear(): Promise<void>;
+	close(): Promise<void>;
+	private notify;
+}
+/**
+* BroadcastChannel backend - cross-tab/worker communication
+*
+* Uses BroadcastChannel API for real-time sync between:
+* - Browser tabs (same origin)
+* - Web Workers
+* - Bun/Node worker threads
+*
+* Uses distributed claim protocol to prevent duplicate job processing.
+*/
+declare class BroadcastBackend implements Backend {
+	private waiting;
+	private active;
+	private failed;
+	private completed;
+	private allIds;
+	private progress;
+	private channel;
+	private listener;
+	private isLeader;
+	private leaderTimeout;
+	private instanceId;
+	private pendingClaims;
+	constructor(channelName?: string);
+	private electLeader;
+	private handleMessage;
+	push(job: Job): Promise<boolean>;
+	pushBulk(jobs: Job[]): Promise<number>;
+	pop(visibilityTimeout: number): Promise<Job | null>;
+	private tryClaim;
+	ack(jobId: string, result?: unknown): Promise<void>;
+	nack(job: Job, nextAttemptAt: number): Promise<void>;
+	fail(job: Job, error: Error): Promise<void>;
+	getStalled(): Promise<Job[]>;
+	updateProgress(jobId: string, progress: number): Promise<void>;
+	getCompleted(jobId: string): Promise<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	} | null>;
+	completedCount(): Promise<number>;
+	getCompletedJobs(limit?: number): Promise<Array<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	}>>;
+	subscribe(callback: () => void): void;
+	unsubscribe(): void;
+	size(): Promise<number>;
+	activeCount(): Promise<number>;
+	failedCount(): Promise<number>;
+	getFailed(limit?: number): Promise<Array<{
+		job: Job;
+		error: string;
+		failedAt: number;
+	}>>;
+	retryFailed(jobId: string): Promise<boolean>;
+	remove(jobId: string): Promise<boolean>;
+	clear(): Promise<void>;
+	close(): Promise<void>;
+	private notify;
+}
+type RedisClient = InstanceType<typeof Bun.RedisClient>;
+/**
+* Redis backend options
+*/
+interface RedisBackendOptions {
+	/** Key prefix for all queue data (default: "qwerk") */
+	prefix?: string;
+	/** Separate client for pub/sub subscriptions (optional, will create one if not provided) */
+	subscriber?: RedisClient;
+}
+/**
+* Redis backend - distributed, persistent job queue
+*
+* Uses atomic Lua scripts for safe concurrent access.
+* Requires Bun's built-in Redis client.
+*/
+declare class RedisBackend implements Backend {
+	private client;
+	private subscriber;
+	private prefix;
+	private listener;
+	private ownsSubscriber;
+	private url;
+	constructor(url: string, options?: RedisBackendOptions);
+	private key;
+	/**
+	* Execute a Lua script via EVAL command
+	*/
+	private evalScript;
+	push(job: Job): Promise<boolean>;
+	pushBulk(jobs: Job[]): Promise<number>;
+	pop(visibilityTimeout: number): Promise<Job | null>;
+	ack(jobId: string, result?: unknown): Promise<void>;
+	nack(job: Job, nextAttemptAt: number): Promise<void>;
+	fail(job: Job, error: Error): Promise<void>;
+	getStalled(): Promise<Job[]>;
+	updateProgress(jobId: string, progress: number): Promise<void>;
+	getCompleted(jobId: string): Promise<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	} | null>;
+	completedCount(): Promise<number>;
+	getCompletedJobs(limit?: number): Promise<Array<{
+		job: Job;
+		result: unknown;
+		completedAt: number;
+	}>>;
+	subscribe(callback: () => void): void;
+	unsubscribe(): void;
+	size(): Promise<number>;
+	activeCount(): Promise<number>;
+	failedCount(): Promise<number>;
+	getFailed(limit?: number): Promise<Array<{
+		job: Job;
+		error: string;
+		failedAt: number;
+	}>>;
+	retryFailed(jobId: string): Promise<boolean>;
+	remove(jobId: string): Promise<boolean>;
+	clear(): Promise<void>;
+	close(): Promise<void>;
+}
+export { silentLogger, consoleLogger, RepeatOptions, RedisBackendOptions, RedisBackend, RateLimitOptions, QueueOptions, QueueMetrics, QueueEvents, Queue, MemoryBackend, Logger, JobStatus, JobOptions, JobHandleHandler, JobHandleEvents, JobHandle, JobDefineOptions, JobContext, JobAddOptions, Job, BroadcastBackend, BackoffOptions, Backend };