@boringnode/queue 0.0.1-alpha.4 → 0.2.0

package/build/{index-C3_tlebh.d.ts → index-C0Xg6F4E.d.ts}

@@ -185,23 +185,134 @@ interface Logger {
     child(obj: LogObject): Logger;
 }
 
+/**
+ * Duration can be specified as milliseconds (number) or as a human-readable string.
+ *
+ * Supported string formats: '1s', '5m', '2h', '1d', etc.
+ *
+ * @example
+ * ```typescript
+ * const timeout: Duration = '30s'   // 30 seconds
+ * const delay: Duration = 5000      // 5000 milliseconds
+ * const interval: Duration = '5m'   // 5 minutes
+ * ```
+ */
 type Duration = number | string;
+/**
+ * Result returned when dispatching a job.
+ *
+ * @example
+ * ```typescript
+ * const { jobId } = await SendEmailJob.dispatch(payload)
+ * console.log(`Dispatched job: ${jobId}`)
+ * ```
+ */
+interface DispatchResult {
+    /** Unique identifier for this specific job instance */
+    jobId: string;
+}
+/**
+ * Internal representation of a job in the queue.
+ *
+ * This is used by adapters to store and retrieve job data.
+ * Not typically used directly by application code.
+ */
 interface JobData {
+    /**
+     * Unique identifier for this job.
+     */
     id: string;
+    /**
+     * Job class name.
+     */
     name: string;
+    /**
+     * Serialized job payload.
+     */
     payload: any;
+    /**
+     * Number of execution attempts so far.
+     */
     attempts: number;
+    /**
+     * Job priority (lower = higher priority).
+     *
+     * @default 0
+     */
     priority?: number;
+    /**
+     * When to retry this job next (for failed jobs).
+     */
     nextRetryAt?: Date;
+    /**
+     * Number of times this job was recovered from stalled state.
+     */
     stalledCount?: number;
 }
+/**
+ * Static options for a Job class.
+ *
+ * Define these as a static property on your Job class to configure
+ * default behavior for all instances.
+ *
+ * @example
+ * ```typescript
+ * class SendEmailJob extends Job<EmailPayload> {
+ *   static options: JobOptions = {
+ *     name: 'SendEmailJob',
+ *     queue: 'emails',
+ *     maxRetries: 3,
+ *     timeout: '30s',
+ *   }
+ * }
+ * ```
+ */
 interface JobOptions {
+    /**
+     * Unique name for this job class.
+     *
+     * Used to identify the job when dispatching and processing.
+     *
+     * @default constructor.name
+     */
+    name?: string;
+    /**
+     * Queue name for this job.
+     *
+     * @default 'default'
+     */
     queue?: string;
+    /**
+     * Adapter name or factory to use for this job.
+     */
     adapter?: string | (() => Adapter);
+    /**
+     * Maximum retry attempts before permanent failure.
+     *
+     * @default 3
+     */
     maxRetries?: number;
+    /**
+     * Job priority (lower = higher priority).
+     *
+     * @default 0
+     */
     priority?: number;
+    /**
+     * Retry configuration (backoff strategy, delays, etc.).
+     */
     retry?: RetryConfig;
+    /**
+     * Maximum execution time before timeout.
+     *
+     * @default undefined (no timeout)
+     */
     timeout?: Duration;
+    /**
+     * Whether to mark job as failed on timeout.
+     *
+     * @default true
+     */
     failOnTimeout?: boolean;
 }
 /**
@@ -236,34 +347,39 @@ interface JobContext {
     /** Number of times this job has been recovered from stalled state */
     stalledCount: number;
 }
-type JobClass<T extends Job = Job> = (new (payload: any, context: JobContext) => T) & {
+/**
+ * Type representing a Job class constructor.
+ *
+ * The constructor accepts any arguments for dependency injection.
+ * Payload and context are provided separately via `$hydrate()`.
+ */
+type JobClass<T extends Job = Job> = (new (...args: any[]) => T) & {
     options?: JobOptions;
 };
 /**
  * Factory function for custom job instantiation.
  *
  * Use this to integrate with IoC containers for dependency injection.
- * The factory receives the job class, payload, and context, and must return
- * a job instance (or a Promise that resolves to one).
+ * The factory receives only the job class and should return an instance
+ * with all dependencies injected. The worker will call `$hydrate()` separately
+ * to provide payload, context, and signal.
  *
  * @param JobClass - The job class to instantiate
- * @param payload - The payload data for the job
- * @param context - The job execution context (jobId, attempt, queue, etc.)
  * @returns The job instance, or a Promise resolving to the instance
  *
  * @example
  * ```typescript
  * // With AdonisJS IoC container
- * const worker = new Worker({
- *   worker: {
- *     jobFactory: async (JobClass, payload, context) => {
- *       return app.container.make(JobClass, [payload, context])
- *     }
+ * await QueueManager.init({
+ *   default: 'redis',
+ *   adapters: { redis: redis() },
+ *   jobFactory: async (JobClass) => {
+ *     return app.container.make(JobClass)
  *   }
  * })
  * ```
  */
-type JobFactory = (JobClass: JobClass, payload: any, context: JobContext) => Job | Promise<Job>;
+type JobFactory = (JobClass: JobClass) => Job | Promise<Job>;
 interface RetryConfig {
     maxRetries?: number;
     backoff?: () => BackoffStrategy$1;
@@ -345,6 +461,82 @@ type WorkerCycle = {
     suggestedDelay: Duration;
 };
 type AdapterFactory<T extends Adapter = Adapter> = () => T;
+/**
+ * Status of a schedule.
+ */
+type ScheduleStatus = 'active' | 'paused';
+/**
+ * Configuration for creating a schedule.
+ * Used by ScheduleBuilder to collect schedule options before creation.
+ */
+interface ScheduleConfig {
+    /** Optional ID for the schedule (UUID if not set). Used for upsert. */
+    id?: string;
+    /** Job class name */
+    name: string;
+    /** Job payload */
+    payload: any;
+    /** Cron expression (mutually exclusive with everyMs) */
+    cronExpression?: string;
+    /** Interval in milliseconds (mutually exclusive with cronExpression) */
+    everyMs?: number;
+    /** IANA timezone for cron evaluation */
+    timezone: string;
+    /** Start boundary - no jobs dispatched before this */
+    from?: Date;
+    /** End boundary - no jobs dispatched after this */
+    to?: Date;
+    /** Maximum number of runs (null = unlimited) */
+    limit?: number;
+}
+/**
+ * Persisted schedule data.
+ * Represents a schedule stored in the adapter.
+ */
+interface ScheduleData {
+    /** Unique identifier */
+    id: string;
+    /** Job class name */
+    name: string;
+    /** Job payload */
+    payload: any;
+    /** Cron expression (null if using interval) */
+    cronExpression: string | null;
+    /** Interval in milliseconds (null if using cron) */
+    everyMs: number | null;
+    /** IANA timezone */
+    timezone: string;
+    /** Start boundary - no jobs dispatched before this */
+    from: Date | null;
+    /** End boundary - no jobs dispatched after this */
+    to: Date | null;
+    /** Maximum number of runs */
+    limit: number | null;
+    /** Number of times this schedule has run */
+    runCount: number;
+    /** Next scheduled run time */
+    nextRunAt: Date | null;
+    /** Last run time */
+    lastRunAt: Date | null;
+    /** Current status */
+    status: ScheduleStatus;
+    /** When the schedule was created */
+    createdAt: Date;
+}
+/**
+ * Result returned when creating a schedule.
+ */
+interface ScheduleResult {
+    /** Unique identifier for the schedule */
+    scheduleId: string;
+}
+/**
+ * Options for listing schedules.
+ */
+interface ScheduleListOptions {
+    /** Filter by status */
+    status?: ScheduleStatus;
+}
 interface QueueManagerConfig {
     default: string;
     adapters: Record<string, AdapterFactory>;
@@ -357,15 +549,17 @@ interface QueueManagerConfig {
      * Custom factory function for job instantiation.
      *
      * Use this to integrate with IoC containers for dependency injection.
-     * When provided, this factory is called instead of `new JobClass(payload, context)`.
+     * When provided, this factory is called instead of `new JobClass()`.
+     * The worker will call `$hydrate()` on the returned instance to provide
+     * payload, context, and signal.
      *
      * @example
      * ```typescript
      * await QueueManager.init({
      *   default: 'redis',
      *   adapters: { redis: redis() },
-     *   jobFactory: async (JobClass, payload, context) => {
-     *     return app.container.make(JobClass, [payload, context])
+     *   jobFactory: async (JobClass) => {
+     *     return app.container.make(JobClass)
      *   }
      * })
      * ```
@@ -504,6 +698,57 @@ interface Adapter {
      * Called when the worker stops or the adapter is no longer needed.
      */
     destroy(): Promise<void>;
+    /**
+     * Create or update a schedule.
+     *
+     * If a schedule with the given id exists, it will be updated (upsert).
+     * Otherwise, a new schedule is created.
+     *
+     * @param config - The schedule configuration
+     * @returns The schedule ID
+     */
+    createSchedule(config: ScheduleConfig): Promise<string>;
+    /**
+     * Get a schedule by ID.
+     *
+     * @param id - The schedule ID
+     * @returns The schedule data, or null if not found
+     */
+    getSchedule(id: string): Promise<ScheduleData | null>;
+    /**
+     * List all schedules matching the given options.
+     *
+     * @param options - Optional filters for listing
+     * @returns Array of schedule data
+     */
+    listSchedules(options?: ScheduleListOptions): Promise<ScheduleData[]>;
+    /**
+     * Update a schedule's status or run metadata.
+     *
+     * @param id - The schedule ID
+     * @param updates - The fields to update
+     */
+    updateSchedule(id: string, updates: Partial<Pick<ScheduleData, 'status' | 'nextRunAt' | 'lastRunAt' | 'runCount'>>): Promise<void>;
+    /**
+     * Delete a schedule permanently.
+     *
+     * @param id - The schedule ID to delete
+     */
+    deleteSchedule(id: string): Promise<void>;
+    /**
+     * Atomically claim a due schedule for execution.
+     *
+     * This method:
+     * 1. Finds ONE schedule where nextRunAt <= now AND status = 'active'
+     * 2. Calculates and updates its nextRunAt to the next occurrence
+     * 3. Increments runCount and sets lastRunAt
+     * 4. Returns the schedule data for job dispatching
+     *
+     * The atomic nature prevents multiple workers from claiming the same schedule.
+     *
+     * @returns The claimed schedule, or null if no schedules are due
+     */
+    claimDueSchedule(): Promise<ScheduleData | null>;
 }
 
 /**
@@ -616,15 +861,15 @@ declare class JobDispatcher<T> {
     /**
      * Dispatch the job to the queue.
      *
-     * @returns The unique job ID
+     * @returns A DispatchResult containing the jobId
      *
      * @example
      * ```typescript
-     * const jobId = await SendEmailJob.dispatch(payload).run()
+     * const { jobId } = await SendEmailJob.dispatch(payload).run()
      * console.log(`Dispatched job: ${jobId}`)
      * ```
      */
-    run(): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+    run(): Promise<DispatchResult>;
     /**
      * Thenable implementation for auto-dispatch when awaited.
      *
@@ -632,9 +877,80 @@ declare class JobDispatcher<T> {
      *
      * @param onFulfilled - Success callback
      * @param onRejected - Error callback
-     * @returns Promise resolving to the job ID
+     * @returns Promise resolving to the DispatchResult
+     */
+    then(onFulfilled?: (value: DispatchResult) => any, onRejected?: (reason: any) => any): Promise<any>;
+}
+
+/**
+ * Fluent builder for creating job schedules.
+ *
+ * @example
+ * ```typescript
+ * // Create with cron
+ * const { scheduleId } = await new ScheduleBuilder('CleanupJob', { days: 30 })
+ *   .id('cleanup-daily')
+ *   .cron('0 0 * * *')
+ *   .timezone('Europe/Paris')
+ *   .run()
+ *
+ * // Create with interval
+ * const { scheduleId } = await new ScheduleBuilder('SyncJob', {})
+ *   .every('5m')
+ *   .run()
+ * ```
+ */
+declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
+    #private;
+    constructor(name: string, payload: any);
+    /**
+     * Set a custom schedule ID.
+     * If not specified, defaults to the job name.
+     * If a schedule with this ID exists, it will be updated (upsert).
+     */
+    id(scheduleId: string): this;
+    /**
+     * Set a cron expression for the schedule.
+     * Mutually exclusive with `every()`.
+     */
+    cron(expression: string): this;
+    /**
+     * Set a repeating interval for the schedule.
+     * Mutually exclusive with `cron()`.
+     */
+    every(interval: Duration): this;
+    /**
+     * Set the timezone for cron evaluation.
+     * @default 'UTC'
+     */
+    timezone(tz: string): this;
+    /**
+     * Set the start boundary for the schedule.
+     * No jobs will be dispatched before this date.
+     */
+    from(date: Date): this;
+    /**
+     * Set the end boundary for the schedule.
+     * No jobs will be dispatched after this date.
+     */
+    to(date: Date): this;
+    /**
+     * Set both start and end boundaries for the schedule.
+     * Shorthand for `.from(start).to(end)`.
+     */
+    between(from: Date, to: Date): this;
+    /**
+     * Set the maximum number of runs for this schedule.
+     */
+    limit(maxRuns: number): this;
+    /**
+     * Create the schedule and return the schedule ID.
+     */
+    run(): Promise<ScheduleResult>;
+    /**
+     * Implement PromiseLike to allow `await builder.every('5m')` syntax.
      */
-    then(onFulfilled?: (value: string) => any, onRejected?: (reason: any) => any): Promise<any>;
+    then<TResult1 = ScheduleResult, TResult2 = never>(onfulfilled?: ((value: ScheduleResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
 
 /**
@@ -643,12 +959,14 @@ declare class JobDispatcher<T> {
  * Extend this class to create your own jobs. Each job must implement
  * the `execute()` method which contains the job's business logic.
  *
+ * The constructor is reserved for dependency injection. Payload and context
+ * are provided separately via the `$hydrate()` method (called by the worker).
+ *
  * @typeParam Payload - The type of data this job receives
  *
  * @example
  * ```typescript
  * import { Job } from '@boringnode/queue'
- * import type { JobContext } from '@boringnode/queue'
  *
  * interface SendEmailPayload {
  *   to: string
@@ -662,13 +980,14 @@ declare class JobDispatcher<T> {
  *     maxRetries: 3,
  *   }
  *
- *   constructor(payload: SendEmailPayload, context: JobContext) {
- *     super(payload, context)
+ *   // Constructor is for dependency injection only
+ *   constructor(private mailer: MailerService) {
+ *     super()
  *   }
  *
  *   async execute() {
  *     console.log(`Attempt ${this.context.attempt} for job ${this.context.jobId}`)
- *     await sendEmail(this.payload.to, this.payload.subject, this.payload.body)
+ *     await this.mailer.send(this.payload.to, this.payload.subject, this.payload.body)
  *   }
  *
  *   async failed(error: Error) {
@@ -679,9 +998,38 @@ declare class JobDispatcher<T> {
  */
 declare abstract class Job<Payload = any> {
     #private;
-    /** Static options for this job class (queue, retries, timeout, etc.) */
+    /**
+     * Static options for this job class.
+     *
+     * Override this property in subclasses to configure job behavior
+     * such as queue name, retry policy, timeout, and more.
+     *
+     * @example
+     * ```typescript
+     * class SendEmailJob extends Job<SendEmailPayload> {
+     *   static options = {
+     *     queue: 'emails',
+     *     maxRetries: 3,
+     *     timeout: '30s',
+     *   }
+     * }
+     * ```
+     */
     static options: JobOptions;
-    /** The payload data passed to this job instance */
+    /**
+     * The payload data passed to this job instance.
+     *
+     * Contains the data provided when the job was dispatched.
+     * Available after the job has been hydrated by the worker.
+     *
+     * @example
+     * ```typescript
+     * async execute() {
+     *   const { to, subject, body } = this.payload
+     *   await sendEmail(to, subject, body)
+     * }
+     * ```
+     */
     get payload(): Payload;
     /**
      * Context information for the current job execution.
@@ -701,12 +1049,36 @@ declare abstract class Job<Payload = any> {
      */
     get context(): JobContext;
     /**
-     * Create a new job instance.
+     * The abort signal for timeout handling.
+     *
+     * Check `signal.aborted` in long-running operations to handle timeouts gracefully.
+     *
+     * @example
+     * ```typescript
+     * async execute() {
+     *   for (const item of this.payload.items) {
+     *     if (this.signal?.aborted) {
+     *       throw new Error('Job timed out')
+     *     }
+     *     await processItem(item)
+     *   }
+     * }
+     * ```
+     */
+    get signal(): AbortSignal | undefined;
+    /**
+     * Hydrate the job with payload, context, and optional abort signal.
+     *
+     * This method is called by the worker after instantiation to provide
+     * the job's runtime data. It should not be called directly by user code.
      *
      * @param payload - The data to be processed by this job
-     * @param context - The job execution context (provided by the worker)
+     * @param context - The job execution context
+     * @param signal - Optional abort signal for timeout handling
+     *
+     * @internal
      */
-    constructor(payload: Payload, context: JobContext);
+    $hydrate(payload: Payload, context: JobContext, signal?: AbortSignal): void;
     /**
      * Dispatch this job to the queue.
      *
@@ -730,22 +1102,48 @@ declare abstract class Job<Payload = any> {
      *   .run()
      * ```
      */
-    static dispatch<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
+    static dispatch<T extends Job>(this: new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
+    /**
+     * Create a schedule for this job.
+     *
+     * Returns a ScheduleBuilder for fluent configuration before creating the schedule.
+     * The schedule is not actually created until `.run()` is called or the
+     * builder is awaited.
+     *
+     * @param payload - The data to pass to the job on each run
+     * @returns A ScheduleBuilder for fluent configuration
+     *
+     * @example
+     * ```typescript
+     * // Cron schedule
+     * await CleanupJob.schedule({ days: 30 })
+     *   .id('cleanup-daily')
+     *   .cron('0 0 * * *')
+     *   .timezone('Europe/Paris')
+     *   .run()
+     *
+     * // Interval schedule
+     * await SyncJob.schedule({ source: 'api' })
+     *   .every('5m')
+     *   .run()
+     * ```
+     */
+    static schedule<T extends Job>(this: new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder;
     /**
      * 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.
+     * For timeout handling, use `this.signal` which is available after hydration.
+     *
      * @throws Any error thrown will trigger retry logic (if configured)
      *
      * @example
      * ```typescript
-     * async execute(signal?: AbortSignal) {
+     * async execute() {
      *   for (const item of this.payload.items) {
-     *     if (signal?.aborted) {
+     *     if (this.signal?.aborted) {
      *       throw new Error('Job timed out')
      *     }
      *     await processItem(item)
@@ -753,7 +1151,7 @@ declare abstract class Job<Payload = any> {
      * }
      * ```
      */
-    abstract execute(signal?: AbortSignal): Promise<void>;
+    abstract execute(): Promise<void>;
     /**
      * Called when the job has permanently failed (after all retries exhausted).
      *
@@ -773,4 +1171,4 @@ declare abstract class Job<Payload = any> {
     failed?(error: Error): Promise<void>;
 }
 
-export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type WorkerCycle as W, type AcquiredJob as a, type JobFactory as b, Job as c, type JobClass as d, customBackoff as e, exponentialBackoff as f, fixedBackoff as g, type JobOptions as h, type JobContext as i, type BackoffConfig as j, type QueueConfig as k, linearBackoff as l, type WorkerConfig as m, type AdapterFactory as n };
+export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type AcquiredJob as a, type ScheduleData as b, type ScheduleListOptions as c, type JobFactory as d, Job as e, type JobClass as f, type ScheduleStatus as g, ScheduleBuilder as h, customBackoff as i, exponentialBackoff as j, fixedBackoff as k, linearBackoff as l, type DispatchResult as m, type JobOptions as n, type JobContext as o, type BackoffConfig as p, type QueueConfig as q, type WorkerConfig as r, type AdapterFactory as s, type ScheduleResult as t };