@boringnode/queue 0.3.1 → 0.3.2

package/build/chunk-RO6VVBGK.js

@@ -0,0 +1,1550 @@
+import {
+  DEFAULT_PRIORITY,
+  E_ADAPTER_INIT_ERROR,
+  E_CONFIGURATION_ERROR,
+  E_INVALID_CRON_EXPRESSION,
+  E_INVALID_SCHEDULE_CONFIG,
+  E_JOB_NOT_FOUND,
+  E_QUEUE_NOT_INITIALIZED,
+  parse
+} from "./chunk-3BIR4IQD.js";
+
+// src/drivers/fake_adapter.ts
+import assert from "assert/strict";
+import { randomUUID as randomUUID3 } from "crypto";
+import { isDeepStrictEqual } from "util";
+import { CronExpressionParser as CronExpressionParser2 } from "cron-parser";
+
+// src/debug.ts
+import { debuglog } from "util";
+var debug_default = debuglog("boringnode:queue");
+
+// src/job_dispatcher.ts
+import { randomUUID } from "crypto";
+
+// src/locator.ts
+import { glob } from "fs/promises";
+import { resolve } from "path";
+var LocatorSingleton = class {
+  #registry = /* @__PURE__ */ new Map();
+  /**
+   * Register a job class with a given name.
+   *
+   * @param name - The job name (usually the class name)
+   * @param JobClass - The job class constructor
+   *
+   * @example
+   * ```typescript
+   * Locator.register('SendEmailJob', SendEmailJob)
+   * ```
+   */
+  register(name, JobClass) {
+    debug_default("registering job: %s", name);
+    this.#registry.set(name, JobClass);
+  }
+  /**
+   * Auto-register job classes from files matching glob patterns.
+   *
+   * Each file should have a default export that is a Job class.
+   * The class name is used as the registration name.
+   *
+   * @param patterns - Glob patterns to match job files
+   * @returns Number of jobs successfully registered
+   *
+   * @example
+   * ```typescript
+   * const count = await Locator.registerFromGlob([
+   *   './jobs/**\/*.js',
+   *   './app/jobs/**\/*.ts'
+   * ])
+   * console.log(`Registered ${count} jobs`)
+   * ```
+   */
+  async registerFromGlob(patterns) {
+    let registered = 0;
+    for (const pattern of patterns) {
+      debug_default("registering jobs from glob pattern: %s", pattern);
+      for await (const file of glob(pattern)) {
+        debug_default("found job file: %s", file);
+        try {
+          const absolutePath = resolve(file);
+          const module = await import(`file://${absolutePath}`);
+          const JobClass = module.default;
+          if (JobClass && typeof JobClass === "function") {
+            const jobName = JobClass.options?.name || JobClass.name;
+            this.register(jobName, JobClass);
+            registered++;
+          }
+        } catch (error) {
+          console.warn(`Failed to load job from ${file}:`, error);
+        }
+      }
+    }
+    return registered;
+  }
+  /**
+   * Get a job class by name.
+   *
+   * @param name - The job name to look up
+   * @returns The job class, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const JobClass = Locator.get('SendEmailJob')
+   * if (JobClass) {
+   *   const instance = new JobClass(payload)
+   * }
+   * ```
+   */
+  get(name) {
+    return this.#registry.get(name);
+  }
+  /**
+   * Get a job class by name, throwing if not found.
+   *
+   * @param name - The job name to look up
+   * @returns The job class
+   * @throws {E_JOB_NOT_FOUND} If the job is not registered
+   *
+   * @example
+   * ```typescript
+   * const JobClass = Locator.getOrThrow('SendEmailJob')
+   * const instance = new JobClass(payload)
+   * ```
+   */
+  getOrThrow(name) {
+    const JobClass = this.get(name);
+    if (!JobClass) {
+      throw new E_JOB_NOT_FOUND([name]);
+    }
+    return JobClass;
+  }
+  /**
+   * Remove all registered jobs.
+   *
+   * Primarily useful for testing.
+   */
+  clear() {
+    this.#registry.clear();
+  }
+};
+var Locator = new LocatorSingleton();
+
+// src/logger.ts
+var ConsoleLogger = class _ConsoleLogger {
+  #prefix;
+  constructor(prefix = "queue") {
+    this.#prefix = prefix;
+  }
+  #format(level, msgOrObj, msg) {
+    const prefix = `[${this.#prefix}] ${level}:`;
+    if (typeof msgOrObj === "object") {
+      return [`${prefix} ${msg}`, msgOrObj];
+    }
+    return [`${prefix} ${msgOrObj}`];
+  }
+  trace(msgOrObj, msg) {
+    const [message, obj] = this.#format("TRACE", msgOrObj, msg);
+    if (obj) {
+      return console.log(message, obj);
+    }
+    console.log(message);
+  }
+  debug(msgOrObj, msg) {
+    const [message, obj] = this.#format("DEBUG", msgOrObj, msg);
+    if (obj) {
+      return console.log(message, obj);
+    }
+    console.log(message);
+  }
+  info(msgOrObj, msg) {
+    const [message, obj] = this.#format("INFO", msgOrObj, msg);
+    if (obj) {
+      return console.log(message, obj);
+    }
+    console.log(message);
+  }
+  warn(msgOrObj, msg) {
+    const [message, obj] = this.#format("WARN", msgOrObj, msg);
+    if (obj) {
+      return console.warn(message, obj);
+    }
+    console.warn(message);
+  }
+  error(msgOrObj, msg) {
+    const [message, obj] = this.#format("ERROR", msgOrObj, msg);
+    if (obj) {
+      return console.error(message, obj);
+    }
+    console.error(message);
+  }
+  child(obj) {
+    const childPrefix = obj.pkg ? String(obj.pkg) : this.#prefix;
+    return new _ConsoleLogger(childPrefix);
+  }
+};
+var consoleLogger = new ConsoleLogger();
+
+// src/queue_manager.ts
+var QueueManagerSingleton = class {
+  #initialized = false;
+  #defaultAdapter;
+  #adapters = {};
+  #adapterInstances = /* @__PURE__ */ new Map();
+  #globalRetryConfig;
+  #globalJobOptions;
+  #queueConfigs = /* @__PURE__ */ new Map();
+  #logger = consoleLogger;
+  #jobFactory;
+  #fakeState;
+  /**
+   * Initialize the queue system with the given configuration.
+   *
+   * This must be called before using the queue system. It:
+   * - Validates the configuration
+   * - Registers adapters
+   * - Auto-discovers and registers job classes from `locations`
+   *
+   * @param config - The queue configuration
+   * @returns This instance for chaining
+   * @throws {E_CONFIGURATION_ERROR} If the configuration is invalid
+   *
+   * @example
+   * ```typescript
+   * await QueueManager.init({
+   *   default: 'redis',
+   *   adapters: {
+   *     redis: redis(),
+   *     postgres: knex(pgConfig),
+   *   },
+   *   locations: ['./jobs/**\/*.js'],
+   * })
+   * ```
+   */
+  async init(config) {
+    debug_default("initializing queue manager with config: %O", config);
+    this.#validateConfig(config);
+    this.#adapterInstances.clear();
+    this.#defaultAdapter = config.default;
+    this.#adapters = config.adapters;
+    this.#globalRetryConfig = config.retry;
+    this.#globalJobOptions = config.defaultJobOptions;
+    this.#logger = config.logger ?? consoleLogger;
+    this.#jobFactory = config.jobFactory;
+    if (config.queues) {
+      for (const [queue, queueConfig] of Object.entries(config.queues)) {
+        this.#queueConfigs.set(queue, queueConfig);
+      }
+    }
+    if (config.locations && config.locations.length > 0) {
+      const registered = await Locator.registerFromGlob(config.locations);
+      if (registered === 0) {
+        this.#logger.warn(
+          `No jobs found for locations: ${config.locations.join(", ")}. Verify your glob patterns match your job files.`
+        );
+      }
+    }
+    this.#initialized = true;
+    return this;
+  }
+  /**
+   * Get an adapter instance by name.
+   *
+   * Adapter instances are cached and reused. If no name is provided,
+   * the default adapter is returned.
+   *
+   * @param adapter - Adapter name (optional, defaults to the default adapter)
+   * @returns The adapter instance
+   * @throws {E_QUEUE_NOT_INITIALIZED} If `init()` hasn't been called
+   * @throws {E_CONFIGURATION_ERROR} If the adapter is not registered
+   * @throws {E_ADAPTER_INIT_ERROR} If the adapter factory throws
+   *
+   * @example
+   * ```typescript
+   * // Get default adapter
+   * const adapter = QueueManager.use()
+   *
+   * // Get specific adapter
+   * const redisAdapter = QueueManager.use('redis')
+   * ```
+   */
+  use(adapter) {
+    if (!this.#initialized) {
+      throw new E_QUEUE_NOT_INITIALIZED();
+    }
+    if (!adapter) {
+      adapter = this.#defaultAdapter;
+    }
+    const cached = this.#adapterInstances.get(adapter);
+    if (cached) {
+      return cached;
+    }
+    const adapterFactory = this.#adapters[adapter];
+    if (!adapterFactory) {
+      throw new E_CONFIGURATION_ERROR([`Adapter "${adapter}" is not registered`]);
+    }
+    debug_default('using adapter "%s"', adapter);
+    try {
+      const instance = adapterFactory();
+      this.#adapterInstances.set(adapter, instance);
+      return instance;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new E_ADAPTER_INIT_ERROR([adapter, message]);
+    }
+  }
+  /**
+   * Replace all adapters with a fake adapter for testing.
+   *
+   * The fake adapter records pushed jobs and exposes assertion helpers.
+   * Call `restore()` to return to the previous configuration.
+   *
+   * @returns The fake adapter instance for assertions
+   * @throws {E_QUEUE_NOT_INITIALIZED} If `init()` hasn't been called
+   *
+   * @example
+   * ```typescript
+   * const fake = QueueManager.fake()
+   *
+   * await SendEmailJob.dispatch({ to: 'user@example.com' })
+   *
+   * fake.assertPushed(SendEmailJob)
+   * QueueManager.restore()
+   * ```
+   */
+  fake() {
+    if (!this.#initialized) {
+      throw new E_QUEUE_NOT_INITIALIZED();
+    }
+    if (this.#fakeState) {
+      return this.#fakeState.fakeAdapter;
+    }
+    const fakeAdapter = new FakeAdapter();
+    this.#fakeState = {
+      defaultAdapter: this.#defaultAdapter,
+      adapters: this.#adapters,
+      adapterInstances: this.#adapterInstances,
+      globalRetryConfig: this.#globalRetryConfig,
+      globalJobOptions: this.#globalJobOptions,
+      queueConfigs: this.#queueConfigs,
+      logger: this.#logger,
+      jobFactory: this.#jobFactory,
+      fakeAdapter
+    };
+    const fakeFactory = () => fakeAdapter;
+    const nextAdapters = {};
+    for (const name of Object.keys(this.#fakeState.adapters)) {
+      nextAdapters[name] = fakeFactory;
+    }
+    this.#adapters = nextAdapters;
+    this.#adapterInstances = /* @__PURE__ */ new Map();
+    return fakeAdapter;
+  }
+  /**
+   * Restore adapters after calling `fake()`.
+   */
+  restore() {
+    if (!this.#fakeState) {
+      return;
+    }
+    void this.#fakeState.fakeAdapter.destroy();
+    for (const adapter of this.#adapterInstances.values()) {
+      void adapter.destroy();
+    }
+    const state = this.#fakeState;
+    this.#fakeState = void 0;
+    this.#defaultAdapter = state.defaultAdapter;
+    this.#adapters = state.adapters;
+    this.#adapterInstances = state.adapterInstances;
+    this.#globalRetryConfig = state.globalRetryConfig;
+    this.#globalJobOptions = state.globalJobOptions;
+    this.#queueConfigs = state.queueConfigs;
+    this.#logger = state.logger;
+    this.#jobFactory = state.jobFactory;
+  }
+  /**
+   * Get the merged retry configuration for a job.
+   *
+   * Configuration is merged with priority: job > queue > global.
+   * This allows specific jobs or queues to override global defaults.
+   *
+   * @param queue - The queue name
+   * @param jobRetryConfig - Optional job-level retry config
+   * @returns The merged retry configuration
+   *
+   * @example
+   * ```typescript
+   * // Global: maxRetries=3, Queue: maxRetries=5, Job: maxRetries=1
+   * // Result: maxRetries=1 (job wins)
+   * const config = QueueManager.getMergedRetryConfig('emails', { maxRetries: 1 })
+   * ```
+   */
+  getMergedRetryConfig(queue, jobRetryConfig) {
+    const queueConfig = this.#queueConfigs.get(queue);
+    const queueRetryConfig = queueConfig?.retry || {};
+    let maxRetries = jobRetryConfig?.maxRetries ?? queueRetryConfig.maxRetries ?? this.#globalRetryConfig?.maxRetries ?? 0;
+    let backoff = jobRetryConfig?.backoff || queueRetryConfig.backoff || this.#globalRetryConfig?.backoff;
+    return { maxRetries, backoff };
+  }
+  /**
+   * Get the configured job factory for custom instantiation.
+   *
+   * @returns The job factory function, or undefined if not configured
+   */
+  getJobFactory() {
+    return this.#jobFactory;
+  }
+  /**
+   * Get the merged job options for a job (priority: job > queue > global).
+   */
+  getMergedJobOptions(queue, jobOptions) {
+    const queueConfig = this.#queueConfigs.get(queue);
+    const queueJobOptions = queueConfig?.defaultJobOptions;
+    return {
+      removeOnComplete: jobOptions?.removeOnComplete ?? queueJobOptions?.removeOnComplete ?? this.#globalJobOptions?.removeOnComplete,
+      removeOnFail: jobOptions?.removeOnFail ?? queueJobOptions?.removeOnFail ?? this.#globalJobOptions?.removeOnFail
+    };
+  }
+  #validateConfig(config) {
+    if (!config.adapters || Object.keys(config.adapters).length === 0) {
+      throw new E_CONFIGURATION_ERROR(["At least one adapter must be configured"]);
+    }
+    if (!config.default) {
+      throw new E_CONFIGURATION_ERROR(["Default adapter must be specified"]);
+    }
+    if (!config.adapters[config.default]) {
+      throw new E_CONFIGURATION_ERROR([
+        `Default adapter "${config.default}" not found in adapters configuration`
+      ]);
+    }
+    for (const [name, factory] of Object.entries(config.adapters)) {
+      if (typeof factory !== "function") {
+        throw new E_CONFIGURATION_ERROR([`Adapter "${name}" must be a factory function`]);
+      }
+    }
+  }
+  /**
+   * Clean up all adapter instances and reset state.
+   *
+   * Call this when shutting down the application or when
+   * you need to reinitialize with a new configuration.
+   *
+   * @example
+   * ```typescript
+   * // On application shutdown
+   * await QueueManager.destroy()
+   * ```
+   */
+  async destroy() {
+    for (const [name, adapter] of this.#adapterInstances) {
+      debug_default('destroying adapter "%s"', name);
+      await adapter.destroy();
+    }
+    if (this.#fakeState) {
+      await this.#fakeState.fakeAdapter.destroy();
+      for (const [name, adapter] of this.#fakeState.adapterInstances) {
+        debug_default('destroying adapter "%s"', name);
+        await adapter.destroy();
+      }
+    }
+    this.#adapterInstances.clear();
+    this.#initialized = false;
+    this.#fakeState = void 0;
+  }
+};
+var QueueManager = new QueueManagerSingleton();
+
+// src/job_dispatcher.ts
+var JobDispatcher = class {
+  #name;
+  #payload;
+  #queue = "default";
+  #adapter;
+  #delay;
+  #priority;
+  #groupId;
+  /**
+   * Create a new job dispatcher.
+   *
+   * @param name - The job class name (used to locate the class at runtime)
+   * @param payload - The data to pass to the job
+   */
+  constructor(name, payload) {
+    this.#name = name;
+    this.#payload = payload;
+  }
+  /**
+   * Set the target queue for this job.
+   *
+   * @param queue - Queue name (default: 'default')
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await SendEmailJob.dispatch(payload).toQueue('emails')
+   * ```
+   */
+  toQueue(queue) {
+    this.#queue = queue;
+    return this;
+  }
+  /**
+   * Delay the job execution.
+   *
+   * The job will be stored in a delayed state and moved to pending
+   * after the delay expires.
+   *
+   * @param delay - Delay as milliseconds or duration string ('5s', '1h', '7d')
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // Send reminder in 24 hours
+   * await ReminderJob.dispatch(payload).in('24h')
+   *
+   * // Process in 5 minutes
+   * await CleanupJob.dispatch(payload).in('5m')
+   * ```
+   */
+  in(delay) {
+    this.#delay = delay;
+    return this;
+  }
+  /**
+   * Set the job priority.
+   *
+   * Lower numbers = higher priority. Jobs with lower priority values
+   * are processed before jobs with higher values.
+   *
+   * @param priority - Priority level (1-10, default: 5)
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // High priority job
+   * await UrgentJob.dispatch(payload).priority(1)
+   *
+   * // Low priority job
+   * await BackgroundJob.dispatch(payload).priority(10)
+   * ```
+   */
+  priority(priority) {
+    this.#priority = priority;
+    return this;
+  }
+  /**
+   * Assign this job to a group.
+   *
+   * Jobs with the same groupId can be filtered and displayed together
+   * in monitoring UIs. Useful for batch operations like newsletters
+   * or bulk exports.
+   *
+   * @param groupId - Group identifier
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // Group newsletter jobs together
+   * await SendEmailJob.dispatch({ to: 'user@example.com' })
+   *   .group('newsletter-jan-2025')
+   *   .run()
+   * ```
+   */
+  group(groupId) {
+    this.#groupId = groupId;
+    return this;
+  }
+  /**
+   * Use a specific adapter for this job.
+   *
+   * @param adapter - Adapter name or factory function
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * // Use named adapter
+   * await Job.dispatch(payload).with('redis')
+   *
+   * // Use custom adapter instance
+   * await Job.dispatch(payload).with(() => new CustomAdapter())
+   * ```
+   */
+  with(adapter) {
+    this.#adapter = adapter;
+    return this;
+  }
+  /**
+   * Dispatch the job to the queue.
+   *
+   * @returns A DispatchResult containing the jobId
+   *
+   * @example
+   * ```typescript
+   * const { jobId } = await SendEmailJob.dispatch(payload).run()
+   * console.log(`Dispatched job: ${jobId}`)
+   * ```
+   */
+  async run() {
+    const id = randomUUID();
+    debug_default("dispatching job %s with id %s using payload %s", this.#name, id, this.#payload);
+    const adapter = this.#getAdapterInstance();
+    const payload = {
+      id,
+      name: this.#name,
+      payload: this.#payload,
+      attempts: 0,
+      priority: this.#priority,
+      groupId: this.#groupId
+    };
+    if (this.#delay) {
+      const parsedDelay = parse(this.#delay);
+      await adapter.pushLaterOn(this.#queue, payload, parsedDelay);
+    } else {
+      await adapter.pushOn(this.#queue, payload);
+    }
+    return {
+      jobId: id
+    };
+  }
+  /**
+   * Thenable implementation for auto-dispatch when awaited.
+   *
+   * Allows `await Job.dispatch(payload)` without explicit `.run()`.
+   *
+   * @param onFulfilled - Success callback
+   * @param onRejected - Error callback
+   * @returns Promise resolving to the DispatchResult
+   */
+  then(onFulfilled, onRejected) {
+    return this.run().then(onFulfilled, onRejected);
+  }
+  #getAdapterInstance() {
+    if (!this.#adapter) {
+      return QueueManager.use();
+    }
+    if (typeof this.#adapter === "string") {
+      return QueueManager.use(this.#adapter);
+    }
+    return this.#adapter();
+  }
+};
+
+// src/job_batch_dispatcher.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var JobBatchDispatcher = class {
+  #name;
+  #payloads;
+  #queue = "default";
+  #adapter;
+  #priority;
+  #groupId;
+  /**
+   * Create a new batch job dispatcher.
+   *
+   * @param name - The job class name (used to locate the class at runtime)
+   * @param payloads - Array of data to pass to each job
+   */
+  constructor(name, payloads) {
+    this.#name = name;
+    this.#payloads = payloads;
+  }
+  /**
+   * Set the target queue for all jobs.
+   *
+   * @param queue - Queue name (default: 'default')
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await SendEmailJob.dispatchMany(payloads).toQueue('emails')
+   * ```
+   */
+  toQueue(queue) {
+    this.#queue = queue;
+    return this;
+  }
+  /**
+   * Set the priority for all jobs.
+   *
+   * Lower numbers = higher priority. Jobs with lower priority values
+   * are processed before jobs with higher values.
+   *
+   * @param priority - Priority level (1-10, default: 5)
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await UrgentJob.dispatchMany(payloads).priority(1)
+   * ```
+   */
+  priority(priority) {
+    this.#priority = priority;
+    return this;
+  }
+  /**
+   * Assign all jobs to a group.
+   *
+   * Jobs with the same groupId can be filtered and displayed together
+   * in monitoring UIs. Useful for batch operations like newsletters
+   * or bulk exports.
+   *
+   * @param groupId - Group identifier
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await SendEmailJob.dispatchMany(recipients)
+   *   .group('newsletter-jan-2025')
+   *   .run()
+   * ```
+   */
+  group(groupId) {
+    this.#groupId = groupId;
+    return this;
+  }
+  /**
+   * Use a specific adapter for these jobs.
+   *
+   * @param adapter - Adapter name or factory function
+   * @returns This dispatcher for chaining
+   *
+   * @example
+   * ```typescript
+   * await Job.dispatchMany(payloads).with('redis')
+   * ```
+   */
+  with(adapter) {
+    this.#adapter = adapter;
+    return this;
+  }
+  /**
+   * Dispatch all jobs to the queue.
+   *
+   * @returns A DispatchManyResult containing all jobIds
+   *
+   * @example
+   * ```typescript
+   * const { jobIds } = await SendEmailJob.dispatchMany(payloads).run()
+   * console.log(`Dispatched ${jobIds.length} jobs`)
+   * ```
+   */
+  async run() {
+    debug_default("dispatching %d jobs of type %s", this.#payloads.length, this.#name);
+    const adapter = this.#getAdapterInstance();
+    const jobs = this.#payloads.map((payload) => ({
+      id: randomUUID2(),
+      name: this.#name,
+      payload,
+      attempts: 0,
+      priority: this.#priority,
+      groupId: this.#groupId
+    }));
+    await adapter.pushManyOn(this.#queue, jobs);
+    return {
+      jobIds: jobs.map((job) => job.id)
+    };
+  }
+  /**
+   * Thenable implementation for auto-dispatch when awaited.
+   *
+   * Allows `await Job.dispatchMany(payloads)` without explicit `.run()`.
+   *
+   * @param onFulfilled - Success callback
+   * @param onRejected - Error callback
+   * @returns Promise resolving to the DispatchManyResult
+   */
+  then(onFulfilled, onRejected) {
+    return this.run().then(onFulfilled, onRejected);
+  }
+  #getAdapterInstance() {
+    if (!this.#adapter) {
+      return QueueManager.use();
+    }
+    if (typeof this.#adapter === "string") {
+      return QueueManager.use(this.#adapter);
+    }
+    return this.#adapter();
+  }
+};
+
+// src/schedule_builder.ts
+import { CronExpressionParser } from "cron-parser";
+var ScheduleBuilder = class {
+  #name;
+  #payload;
+  #id;
+  #cronExpression;
+  #everyMs;
+  #timezone = "UTC";
+  #from;
+  #to;
+  #limit;
+  constructor(name, payload) {
+    this.#name = name;
+    this.#payload = payload;
+  }
+  /**
+   * 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) {
+    this.#id = scheduleId;
+    return this;
+  }
+  /**
+   * Set a cron expression for the schedule.
+   * Mutually exclusive with `every()`.
+   */
+  cron(expression) {
+    this.#cronExpression = expression;
+    return this;
+  }
+  /**
+   * Set a repeating interval for the schedule.
+   * Mutually exclusive with `cron()`.
+   */
+  every(interval) {
+    this.#everyMs = parse(interval);
+    return this;
+  }
+  /**
+   * Set the timezone for cron evaluation.
+   * @default 'UTC'
+   */
+  timezone(tz) {
+    this.#timezone = tz;
+    return this;
+  }
+  /**
+   * Set the start boundary for the schedule.
+   * No jobs will be dispatched before this date.
+   */
+  from(date) {
+    this.#from = date;
+    return this;
+  }
+  /**
+   * Set the end boundary for the schedule.
+   * No jobs will be dispatched after this date.
+   */
+  to(date) {
+    this.#to = date;
+    return this;
+  }
+  /**
+   * Set both start and end boundaries for the schedule.
+   * Shorthand for `.from(start).to(end)`.
+   */
+  between(from, to) {
+    return this.from(from).to(to);
+  }
+  /**
+   * Set the maximum number of runs for this schedule.
+   */
+  limit(maxRuns) {
+    this.#limit = maxRuns;
+    return this;
+  }
+  /**
+   * Create the schedule and return the schedule ID.
+   */
+  async run() {
+    if (!this.#cronExpression && !this.#everyMs) {
+      throw new E_INVALID_SCHEDULE_CONFIG([
+        "Schedule must have either a cron expression or an interval"
+      ]);
+    }
+    if (this.#cronExpression && this.#everyMs) {
+      throw new E_INVALID_SCHEDULE_CONFIG([
+        "Schedule cannot have both a cron expression and an interval"
+      ]);
+    }
+    if (this.#cronExpression) {
+      try {
+        CronExpressionParser.parse(this.#cronExpression, { tz: this.#timezone });
+      } catch (error) {
+        throw new E_INVALID_CRON_EXPRESSION([this.#cronExpression, error.message]);
+      }
+    }
+    const config = {
+      id: this.#id ?? this.#name,
+      name: this.#name,
+      payload: this.#payload,
+      cronExpression: this.#cronExpression,
+      everyMs: this.#everyMs,
+      timezone: this.#timezone,
+      from: this.#from,
+      to: this.#to,
+      limit: this.#limit
+    };
+    const adapter = QueueManager.use();
+    const scheduleId = await adapter.createSchedule(config);
+    const nextRunAt = this.#calculateNextRunAt();
+    await adapter.updateSchedule(scheduleId, { nextRunAt });
+    return { scheduleId };
+  }
+  /**
+   * Calculate the next run time based on cron or interval.
+   */
+  #calculateNextRunAt() {
+    const now = /* @__PURE__ */ new Date();
+    let nextRun;
+    if (this.#cronExpression) {
+      const cron = CronExpressionParser.parse(this.#cronExpression, {
+        currentDate: now,
+        tz: this.#timezone
+      });
+      nextRun = cron.next().toDate();
+    } else {
+      nextRun = new Date(now.getTime() + this.#everyMs);
+    }
+    if (this.#from && nextRun < this.#from) {
+      if (this.#cronExpression) {
+        const cron = CronExpressionParser.parse(this.#cronExpression, {
+          currentDate: this.#from,
+          tz: this.#timezone
+        });
+        nextRun = cron.next().toDate();
+      } else {
+        nextRun = this.#from;
+      }
+    }
+    return nextRun;
+  }
+  /**
+   * Implement PromiseLike to allow `await builder.every('5m')` syntax.
+   */
+  then(onfulfilled, onrejected) {
+    return this.run().then(onfulfilled, onrejected);
+  }
+};
+
+// src/job.ts
+var Job = class {
+  #payload;
+  #context;
+  #signal;
+  /**
+   * 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 = {};
+  /**
+   * 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() {
+    return this.#payload;
+  }
+  /**
+   * Context information for the current job execution.
+   *
+   * Provides metadata such as job ID, current attempt number,
+   * queue name, priority, and timing information.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   if (this.context.attempt > 1) {
+   *     console.log(`Retry attempt ${this.context.attempt}`)
+   *   }
+   *   console.log(`Processing job ${this.context.jobId} on queue ${this.context.queue}`)
+   * }
+   * ```
+   */
+  get context() {
+    return this.#context;
+  }
+  /**
+   * 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() {
+    return this.#signal;
+  }
+  /**
+   * 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
+   * @param signal - Optional abort signal for timeout handling
+   *
+   * @internal
+   */
+  $hydrate(payload, context, signal) {
+    this.#payload = payload;
+    this.#context = Object.freeze(context);
+    this.#signal = signal;
+  }
+  /**
+   * 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(payload) {
+    const options = this.options || {};
+    const jobName = options.name || this.name;
+    const dispatcher = new JobDispatcher(jobName, payload);
+    if (options.queue) {
+      dispatcher.toQueue(options.queue);
+    }
+    if (options.adapter) {
+      dispatcher.with(options.adapter);
+    }
+    if (options.priority !== void 0) {
+      dispatcher.priority(options.priority);
+    }
+    return dispatcher;
+  }
+  /**
+   * Dispatch multiple jobs to the queue in a single batch.
+   *
+   * Returns a JobBatchDispatcher for fluent configuration before dispatching.
+   * The jobs are not actually dispatched until `.run()` is called or the
+   * dispatcher is awaited.
+   *
+   * This is more efficient than calling `dispatch()` multiple times as it
+   * uses batched operations (e.g., Redis pipeline, SQL batch insert).
+   *
+   * @param payloads - Array of data to pass to each job
+   * @returns A JobBatchDispatcher for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * // Batch dispatch for newsletter
+   * const { jobIds } = await SendEmailJob.dispatchMany([
+   *   { to: 'user1@example.com', subject: 'Newsletter' },
+   *   { to: 'user2@example.com', subject: 'Newsletter' },
+   * ])
+   *   .group('newsletter-jan-2025')
+   *   .toQueue('emails')
+   *   .run()
+   *
+   * console.log(`Dispatched ${jobIds.length} jobs`)
+   * ```
+   */
+  static dispatchMany(payloads) {
+    const options = this.options || {};
+    const jobName = options.name || this.name;
+    const dispatcher = new JobBatchDispatcher(jobName, payloads);
+    if (options.queue) {
+      dispatcher.toQueue(options.queue);
+    }
+    if (options.adapter) {
+      dispatcher.with(options.adapter);
+    }
+    if (options.priority !== void 0) {
+      dispatcher.priority(options.priority);
+    }
+    return dispatcher;
+  }
+  /**
+   * 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(payload) {
+    const options = this.options || {};
+    const jobName = options.name || this.name;
+    return new ScheduleBuilder(jobName, payload);
+  }
+};
+
+// src/drivers/fake_adapter.ts
+function fake() {
+  return () => new FakeAdapter();
+}
+var FakeAdapter = class {
+  #queues = /* @__PURE__ */ new Map();
+  #activeJobs = /* @__PURE__ */ new Map();
+  #delayedJobs = /* @__PURE__ */ new Map();
+  #completedJobs = /* @__PURE__ */ new Map();
+  #failedJobs = /* @__PURE__ */ new Map();
+  #pendingTimeouts = /* @__PURE__ */ new Set();
+  #schedules = /* @__PURE__ */ new Map();
+  #pushedJobs = [];
+  setWorkerId(_workerId) {
+  }
+  getPushedJobs() {
+    return [...this.#pushedJobs];
+  }
+  getPushedJobsOn(queue) {
+    return this.#pushedJobs.filter((record) => record.queue === queue);
+  }
+  findPushed(matcher, query) {
+    return this.#pushedJobs.find((record) => this.#matchesRecord(record, matcher, query));
+  }
+  clearPushedJobs() {
+    this.#pushedJobs = [];
+  }
+  clear() {
+    for (const timeout of this.#pendingTimeouts) {
+      clearTimeout(timeout);
+    }
+    this.#pendingTimeouts.clear();
+    this.#queues.clear();
+    this.#activeJobs.clear();
+    this.#delayedJobs.clear();
+    this.#completedJobs.clear();
+    this.#failedJobs.clear();
+    this.#schedules.clear();
+    this.#pushedJobs = [];
+  }
+  assertPushed(matcher, query) {
+    const record = this.findPushed(matcher, query);
+    assert.ok(record, this.#formatFailure("Expected job to be pushed", matcher, query));
+  }
+  assertNotPushed(matcher, query) {
+    const record = this.findPushed(matcher, query);
+    assert.ok(!record, this.#formatFailure("Expected job to not be pushed", matcher, query));
+  }
+  assertPushedCount(count, options) {
+    const actual = options?.queue ? this.#pushedJobs.filter((record) => record.queue === options.queue).length : this.#pushedJobs.length;
+    const suffix = options?.queue ? ` on "${options.queue}"` : "";
+    assert.equal(actual, count, `Expected ${count} pushed job(s)${suffix}, got ${actual}`);
+  }
+  assertNothingPushed() {
+    assert.equal(
+      this.#pushedJobs.length,
+      0,
+      `Expected no jobs to be pushed, got ${this.#pushedJobs.length}`
+    );
+  }
+  async size() {
+    return this.sizeOf("default");
+  }
+  async sizeOf(queue) {
+    const jobs = this.#queues.get(queue) || [];
+    return jobs.length;
+  }
+  async push(jobData) {
+    return this.pushOn("default", jobData);
+  }
+  async pushOn(queue, jobData) {
+    this.#recordPush(queue, jobData);
+    this.#enqueue(queue, jobData);
+  }
+  async pushLater(jobData, delay) {
+    return this.pushLaterOn("default", jobData, delay);
+  }
+  pushLaterOn(queue, jobData, delay) {
+    this.#recordPush(queue, jobData, delay);
+    this.#schedulePush(queue, jobData, delay);
+    return Promise.resolve();
+  }
+  async pushMany(jobs) {
+    return this.pushManyOn("default", jobs);
+  }
+  async pushManyOn(queue, jobs) {
+    for (const job of jobs) {
+      await this.pushOn(queue, job);
+    }
+  }
+  async pop() {
+    return this.popFrom("default");
+  }
+  async popFrom(queue) {
+    const jobs = this.#queues.get(queue);
+    if (!jobs || jobs.length === 0) {
+      return null;
+    }
+    let bestIndex = 0;
+    let bestPriority = jobs[0].priority ?? DEFAULT_PRIORITY;
+    for (let i = 1; i < jobs.length; i++) {
+      const priority = jobs[i].priority ?? DEFAULT_PRIORITY;
+      if (priority < bestPriority) {
+        bestPriority = priority;
+        bestIndex = i;
+      }
+    }
+    const [job] = jobs.splice(bestIndex, 1);
+    if (!job) {
+      return null;
+    }
+    const acquiredAt = Date.now();
+    this.#activeJobs.set(job.id, { job, acquiredAt, queue });
+    return { ...job, acquiredAt };
+  }
+  async completeJob(jobId, queue, removeOnComplete) {
+    const active = this.#activeJobs.get(jobId);
+    if (!active) return;
+    this.#activeJobs.delete(jobId);
+    if (removeOnComplete === void 0 || removeOnComplete === true) {
+      return;
+    }
+    this.#storeHistory(queue, "completed", active.job, removeOnComplete);
+  }
+  async failJob(jobId, queue, error, removeOnFail) {
+    const active = this.#activeJobs.get(jobId);
+    if (!active) return;
+    this.#activeJobs.delete(jobId);
+    if (removeOnFail === void 0 || removeOnFail === true) {
+      return;
+    }
+    this.#storeHistory(queue, "failed", active.job, removeOnFail, error);
+  }
+  async retryJob(jobId, queue, retryAt) {
+    const active = this.#activeJobs.get(jobId);
+    if (!active) return;
+    this.#activeJobs.delete(jobId);
+    const updatedJob = {
+      ...active.job,
+      attempts: (active.job.attempts || 0) + 1
+    };
+    if (retryAt) {
+      const delay = retryAt.getTime() - Date.now();
+      if (delay > 0) {
+        this.#schedulePush(queue, updatedJob, delay);
+        return;
+      }
+    }
+    this.#enqueue(queue, updatedJob);
+  }
+  async recoverStalledJobs(queue, stalledThreshold, maxStalledCount) {
+    const now = Date.now();
+    let recovered = 0;
+    for (const [jobId, active] of this.#activeJobs.entries()) {
+      if (active.queue !== queue) {
+        continue;
+      }
+      const isStalled = now - active.acquiredAt > stalledThreshold;
+      if (!isStalled) {
+        continue;
+      }
+      const currentStalledCount = active.job.stalledCount ?? 0;
+      if (currentStalledCount >= maxStalledCount) {
+        this.#activeJobs.delete(jobId);
+        continue;
+      }
+      this.#activeJobs.delete(jobId);
+      const updatedJob = {
+        ...active.job,
+        stalledCount: currentStalledCount + 1
+      };
+      this.#enqueue(active.queue, updatedJob);
+      recovered++;
+    }
+    return recovered;
+  }
+  async getJob(jobId, queue) {
+    const active = this.#activeJobs.get(jobId);
+    if (active && active.queue === queue) {
+      return { status: "active", data: active.job };
+    }
+    const pendingJobs = this.#queues.get(queue);
+    const pending = pendingJobs?.find((job) => job.id === jobId);
+    if (pending) {
+      return { status: "pending", data: pending };
+    }
+    const delayed = this.#delayedJobs.get(queue)?.get(jobId);
+    if (delayed) {
+      return { status: "delayed", data: delayed.job };
+    }
+    const completed = this.#findHistory(this.#completedJobs, queue, jobId);
+    if (completed) {
+      return completed;
+    }
+    const failed = this.#findHistory(this.#failedJobs, queue, jobId);
+    if (failed) {
+      return failed;
+    }
+    return null;
+  }
+  destroy() {
+    for (const timeout of this.#pendingTimeouts) {
+      clearTimeout(timeout);
+    }
+    this.#pendingTimeouts.clear();
+    return Promise.resolve();
+  }
+  async createSchedule(config) {
+    const id = config.id ?? randomUUID3();
+    const now = /* @__PURE__ */ new Date();
+    const schedule = {
+      id,
+      name: config.name,
+      payload: config.payload,
+      cronExpression: config.cronExpression ?? null,
+      everyMs: config.everyMs ?? null,
+      timezone: config.timezone,
+      from: config.from ?? null,
+      to: config.to ?? null,
+      limit: config.limit ?? null,
+      runCount: 0,
+      nextRunAt: null,
+      // Will be calculated by the caller
+      lastRunAt: null,
+      status: "active",
+      createdAt: now
+    };
+    this.#schedules.set(id, schedule);
+    return id;
+  }
+  async getSchedule(id) {
+    return this.#schedules.get(id) ?? null;
+  }
+  async listSchedules(options) {
+    const schedules = Array.from(this.#schedules.values());
+    if (options?.status) {
+      return schedules.filter((s) => s.status === options.status);
+    }
+    return schedules;
+  }
+  async updateSchedule(id, updates) {
+    const schedule = this.#schedules.get(id);
+    if (!schedule) return;
+    if (updates.status !== void 0) schedule.status = updates.status;
+    if (updates.nextRunAt !== void 0) schedule.nextRunAt = updates.nextRunAt;
+    if (updates.lastRunAt !== void 0) schedule.lastRunAt = updates.lastRunAt;
+    if (updates.runCount !== void 0) schedule.runCount = updates.runCount;
+  }
+  async deleteSchedule(id) {
+    this.#schedules.delete(id);
+  }
+  async claimDueSchedule() {
+    const now = /* @__PURE__ */ new Date();
+    const schedule = Array.from(this.#schedules.values()).find((s) => {
+      if (s.status !== "active") return false;
+      if (s.nextRunAt === null || s.nextRunAt > now) return false;
+      if (s.limit !== null && s.runCount >= s.limit) return false;
+      if (s.to !== null && now > s.to) return false;
+      return true;
+    });
+    if (!schedule) return null;
+    let nextRunAt = null;
+    if (schedule.everyMs) {
+      nextRunAt = new Date(now.getTime() + schedule.everyMs);
+    } else if (schedule.cronExpression) {
+      const cron = CronExpressionParser2.parse(schedule.cronExpression, {
+        currentDate: now,
+        tz: schedule.timezone || "UTC"
+      });
+      nextRunAt = cron.next().toDate();
+    }
+    const newRunCount = schedule.runCount + 1;
+    if (schedule.limit !== null && newRunCount >= schedule.limit) {
+      nextRunAt = null;
+    }
+    if (nextRunAt && schedule.to !== null && nextRunAt > schedule.to) {
+      nextRunAt = null;
+    }
+    const claimedSchedule = { ...schedule };
+    schedule.nextRunAt = nextRunAt;
+    schedule.lastRunAt = now;
+    schedule.runCount = newRunCount;
+    return claimedSchedule;
+  }
+  #recordPush(queue, jobData, delay) {
+    this.#pushedJobs.push({
+      queue,
+      job: jobData,
+      delay,
+      pushedAt: Date.now()
+    });
+  }
+  #enqueue(queue, jobData) {
+    if (!this.#queues.has(queue)) {
+      this.#queues.set(queue, []);
+    }
+    this.#queues.get(queue).push(jobData);
+  }
+  #schedulePush(queue, jobData, delay) {
+    if (!this.#delayedJobs.has(queue)) {
+      this.#delayedJobs.set(queue, /* @__PURE__ */ new Map());
+    }
+    const executeAt = Date.now() + delay;
+    this.#delayedJobs.get(queue).set(jobData.id, { job: jobData, executeAt, delay });
+    const timeout = setTimeout(() => {
+      this.#pendingTimeouts.delete(timeout);
+      this.#delayedJobs.get(queue)?.delete(jobData.id);
+      this.#enqueue(queue, jobData);
+    }, delay);
+    this.#pendingTimeouts.add(timeout);
+  }
+  #storeHistory(queue, status, job, retention, error) {
+    const record = {
+      status,
+      data: job,
+      finishedAt: Date.now(),
+      error: error?.message
+    };
+    const store = status === "completed" ? this.#completedJobs : this.#failedJobs;
+    if (!store.has(queue)) {
+      store.set(queue, []);
+    }
+    const records = store.get(queue);
+    records.push(record);
+    if (retention && retention !== true) {
+      this.#applyRetention(records, retention);
+    }
+  }
+  #applyRetention(records, retention) {
+    if (retention === false || retention === true) {
+      return;
+    }
+    if (retention.age !== void 0) {
+      const maxAgeMs = parse(retention.age);
+      if (maxAgeMs > 0) {
+        const cutoff = Date.now() - maxAgeMs;
+        const filtered = records.filter((record) => (record.finishedAt ?? 0) >= cutoff);
+        records.splice(0, records.length, ...filtered);
+      }
+    }
+    if (retention.count !== void 0 && retention.count > 0 && records.length > retention.count) {
+      records.splice(0, records.length - retention.count);
+    }
+  }
+  #findHistory(store, queue, jobId) {
+    const records = store.get(queue);
+    if (!records) return null;
+    return records.find((record) => record.data.id === jobId) ?? null;
+  }
+  #matchesRecord(record, matcher, query) {
+    if (query?.queue && record.queue !== query.queue) {
+      return false;
+    }
+    const matchesJob = typeof matcher === "string" ? record.job.name === matcher : this.#isJobClass(matcher) ? record.job.name === this.#getJobClassName(matcher) : matcher(record.job);
+    if (!matchesJob) {
+      return false;
+    }
+    if (query?.payload !== void 0) {
+      const payloadMatcher = query.payload;
+      const matchesPayload = typeof payloadMatcher === "function" ? payloadMatcher(record.job.payload) : isDeepStrictEqual(record.job.payload, payloadMatcher);
+      if (!matchesPayload) {
+        return false;
+      }
+    }
+    if (query?.delay !== void 0) {
+      const delayMatcher = query.delay;
+      const matchesDelay = typeof delayMatcher === "function" ? delayMatcher(record.delay) : record.delay === delayMatcher;
+      if (!matchesDelay) {
+        return false;
+      }
+    }
+    return true;
+  }
+  #formatFailure(prefix, matcher, query) {
+    const parts = [prefix];
+    const matcherName = this.#getMatcherName(matcher);
+    if (matcherName) {
+      parts.push(`for "${matcherName}"`);
+    }
+    if (query?.queue) {
+      parts.push(`on "${query.queue}"`);
+    }
+    if (query?.payload !== void 0) {
+      parts.push("with matching payload");
+    }
+    if (query?.delay !== void 0) {
+      parts.push("with matching delay");
+    }
+    const suffix = this.#pushedJobs.length ? `Pushed jobs: ${this.#pushedJobs.map((record) => record.job.name).join(", ")}` : "Pushed jobs: none";
+    return `${parts.join(" ")}. ${suffix}.`;
+  }
+  #getMatcherName(matcher) {
+    if (typeof matcher === "string") {
+      return matcher;
+    }
+    if (this.#isJobClass(matcher)) {
+      return this.#getJobClassName(matcher);
+    }
+    return void 0;
+  }
+  #isJobClass(matcher) {
+    return typeof matcher === "function" && matcher.prototype instanceof Job;
+  }
+  #getJobClassName(JobClass) {
+    return JobClass.options?.name || JobClass.name;
+  }
+};
+
+export {
+  debug_default,
+  Locator,
+  fake,
+  FakeAdapter,
+  QueueManager,
+  JobDispatcher,
+  JobBatchDispatcher,
+  ScheduleBuilder,
+  Job
+};
+//# sourceMappingURL=chunk-RO6VVBGK.js.map