docs: add JSDoc documentation to public APIs

Author: RomainLanz

src/contracts/adapter.ts

@@ -1,31 +1,64 @@
 import type { JobData } from '../types/main.js'
 
+/**
+ * A job that has been acquired by a worker for processing.
+ * Extends JobData with the timestamp when the job was acquired.
+ */
 export interface AcquiredJob extends JobData {
+  /** Timestamp (in ms) when the job was acquired by the worker */
   acquiredAt: number
 }
 
+/**
+ * Adapter interface for queue storage backends.
+ *
+ * Implementations handle job persistence, atomic operations, and
+ * concurrency control. Built-in adapters: Redis, Knex (PostgreSQL/SQLite).
+ *
+ * @example
+ * ```typescript
+ * import { redis } from '@boringnode/queue'
+ *
+ * const config = {
+ *   default: 'redis',
+ *   adapters: {
+ *     redis: redis({ host: 'localhost', port: 6379 })
+ *   }
+ * }
+ * ```
+ */
 export interface Adapter {
   /**
    * Set the worker ID for this adapter instance.
    * Required before calling pop methods when consuming jobs.
+   *
+   * @param workerId - Unique identifier for the worker
    */
   setWorkerId(workerId: string): void
 
   /**
    * Pop the next available job from the default queue.
-   * The driver handles locking internally.
+   * Atomically moves the job from pending to active state.
+   *
+   * @returns The acquired job, or null if queue is empty
    */
   pop(): Promise<AcquiredJob | null>
 
   /**
    * Pop the next available job from a specific queue.
-   * The driver handles locking internally.
+   * Atomically moves the job from pending to active state.
+   *
+   * @param queue - The queue name to pop from
+   * @returns The acquired job, or null if queue is empty
    */
   popFrom(queue: string): Promise<AcquiredJob | null>
 
   /**
    * Recover stalled jobs that have been active for too long.
-   * Jobs that exceed maxStalledCount will be failed permanently.
+   * A stalled job is one where the worker stopped responding (e.g., crash).
+   *
+   * Jobs within maxStalledCount are moved back to pending.
+   * Jobs exceeding maxStalledCount are failed permanently.
    *
    * @param queue - The queue to check for stalled jobs
    * @param stalledThreshold - Duration in ms after which a job is considered stalled
@@ -39,26 +72,81 @@ export interface Adapter {
   ): Promise<number>
 
   /**
-   * Mark a job as completed and remove it from active set.
+   * Mark a job as completed and remove it from the queue.
+   *
+   * @param jobId - The job ID to complete
+   * @param queue - The queue the job belongs to
    */
   completeJob(jobId: string, queue: string): Promise<void>
 
   /**
-   * Mark a job as failed permanently.
+   * Mark a job as failed permanently and remove it from the queue.
+   *
+   * @param jobId - The job ID to fail
+   * @param queue - The queue the job belongs to
+   * @param error - Optional error that caused the failure
    */
   failJob(jobId: string, queue: string, error?: Error): Promise<void>
 
   /**
-   * Retry a job - move back to pending queue with incremented attempts.
+   * Retry a job by moving it back to pending with incremented attempts.
+   *
+   * @param jobId - The job ID to retry
+   * @param queue - The queue the job belongs to
+   * @param retryAt - Optional future date to delay the retry
    */
   retryJob(jobId: string, queue: string, retryAt?: Date): Promise<void>
 
+  /**
+   * Push a job to the default queue for immediate processing.
+   *
+   * @param jobData - The job data to push
+   */
   push(jobData: JobData): Promise<void>
+
+  /**
+   * Push a job to a specific queue for immediate processing.
+   *
+   * @param queue - The queue name to push to
+   * @param jobData - The job data to push
+   */
   pushOn(queue: string, jobData: JobData): Promise<void>
+
+  /**
+   * Push a job to the default queue with a delay.
+   *
+   * @param jobData - The job data to push
+   * @param delay - Delay in milliseconds before the job becomes available
+   */
   pushLater(jobData: JobData, delay: number): Promise<void>
+
+  /**
+   * Push a job to a specific queue with a delay.
+   *
+   * @param queue - The queue name to push to
+   * @param jobData - The job data to push
+   * @param delay - Delay in milliseconds before the job becomes available
+   */
   pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<void>
 
+  /**
+   * Get the number of pending jobs in the default queue.
+   *
+   * @returns The number of pending jobs
+   */
   size(): Promise<number>
+
+  /**
+   * Get the number of pending jobs in a specific queue.
+   *
+   * @param queue - The queue name to check
+   * @returns The number of pending jobs
+   */
   sizeOf(queue: string): Promise<number>
+
+  /**
+   * Clean up resources (close connections, etc.).
+   * Called when the worker stops or the adapter is no longer needed.
+   */
   destroy(): Promise<void>
 }

src/job.ts

@@ -1,19 +1,83 @@
 import { JobDispatcher } from './job_dispatcher.js'
 import type { JobOptions } from './types/main.js'
 
+/**
+ * Abstract base class for all queue jobs.
+ *
+ * Extend this class to create your own jobs. Each job must implement
+ * the `execute()` method which contains the job's business logic.
+ *
+ * @typeParam Payload - The type of data this job receives
+ *
+ * @example
+ * ```typescript
+ * import { Job } from '@boringnode/queue'
+ *
+ * interface SendEmailPayload {
+ *   to: string
+ *   subject: string
+ *   body: string
+ * }
+ *
+ * export default class SendEmailJob extends Job<SendEmailPayload> {
+ *   static options = {
+ *     queue: 'emails',
+ *     maxRetries: 3,
+ *   }
+ *
+ *   async execute() {
+ *     await sendEmail(this.payload.to, this.payload.subject, this.payload.body)
+ *   }
+ *
+ *   async failed(error: Error) {
+ *     console.error(`Failed to send email to ${this.payload.to}:`, error)
+ *   }
+ * }
+ * ```
+ */
 export abstract class Job<Payload = any> {
   readonly #payload: Payload
 
+  /** Static options for this job class (queue, retries, timeout, etc.) */
   static options: JobOptions = {}
 
+  /** The payload data passed to this job instance */
   get payload(): Payload {
     return this.#payload
   }
 
+  /**
+   * Create a new job instance.
+   *
+   * @param payload - The data to be processed by this job
+   */
   constructor(payload: Payload) {
     this.#payload = payload
   }
 
+  /**
+   * Dispatch this job to the queue.
+   *
+   * Returns a JobDispatcher for fluent configuration before dispatching.
+   * The job is not actually dispatched until `.run()` is called or the
+   * dispatcher is awaited.
+   *
+   * @param payload - The data to pass to the job
+   * @returns A JobDispatcher for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * // Simple dispatch
+   * await SendEmailJob.dispatch({ to: 'user@example.com', subject: 'Hello' })
+   *
+   * // With options
+   * await SendEmailJob.dispatch({ to: 'user@example.com' })
+   *   .toQueue('high-priority')
+   *   .priority(1)
+   *   .in('5m')
+   *   .run()
+   * ```
+   */
   static dispatch<T extends Job>(
     this: new (payload: any) => T,
     payload: T extends Job<infer P> ? P : never
@@ -38,7 +102,45 @@ export abstract class Job<Payload = any> {
     return dispatcher
   }
 
+  /**
+   * Execute the job's business logic.
+   *
+   * This method is called by the worker when processing the job.
+   * Implement your job's logic here.
+   *
+   * @param signal - Optional AbortSignal for timeout handling.
+   *                 Check `signal.aborted` for long-running operations.
+   * @throws Any error thrown will trigger retry logic (if configured)
+   *
+   * @example
+   * ```typescript
+   * async execute(signal?: AbortSignal) {
+   *   for (const item of this.payload.items) {
+   *     if (signal?.aborted) {
+   *       throw new Error('Job timed out')
+   *     }
+   *     await processItem(item)
+   *   }
+   * }
+   * ```
+   */
   abstract execute(signal?: AbortSignal): Promise<void>
 
+  /**
+   * Called when the job has permanently failed (after all retries exhausted).
+   *
+   * Use this hook for cleanup, logging, or notifications.
+   * This is optional - implement only if you need failure handling.
+   *
+   * @param error - The error that caused the final failure
+   *
+   * @example
+   * ```typescript
+   * async failed(error: Error) {
+   *   await notifyAdmin(`Job failed: ${error.message}`)
+   *   await cleanup(this.payload)
+   * }
+   * ```
+   */
   failed?(error: Error): Promise<void>
 }