@nicnocquee/dataqueue 1.25.0 → 1.26.0-beta.20260223195940

package/src/backend.ts

@@ -6,6 +6,12 @@ import {
   FailureReason,
   TagQueryMode,
   JobType,
+  CronScheduleRecord,
+  CronScheduleStatus,
+  EditCronScheduleOptions,
+  WaitpointRecord,
+  CreateTokenOptions,
+  AddJobOptions,
 } from './types.js';
 
 /**
@@ -34,6 +40,31 @@ export interface JobUpdates {
   runAt?: Date | null;
   timeoutMs?: number | null;
   tags?: string[] | null;
+  retryDelay?: number | null;
+  retryBackoff?: boolean | null;
+  retryDelayMax?: number | null;
+}
+
+/**
+ * Input shape for creating a cron schedule in the backend.
+ * This is the backend-level version of CronScheduleOptions.
+ */
+export interface CronScheduleInput {
+  scheduleName: string;
+  cronExpression: string;
+  jobType: string;
+  payload: any;
+  maxAttempts: number;
+  priority: number;
+  timeoutMs: number | null;
+  forceKillOnTimeout: boolean;
+  tags: string[] | undefined;
+  timezone: string;
+  allowOverlap: boolean;
+  nextRunAt: Date | null;
+  retryDelay: number | null;
+  retryBackoff: boolean | null;
+  retryDelayMax: number | null;
 }
 
 /**
@@ -44,11 +75,34 @@ export interface JobUpdates {
 export interface QueueBackend {
   // ── Job CRUD ──────────────────────────────────────────────────────────
 
-  /** Add a job and return its numeric ID. */
+  /**
+   * Add a job and return its numeric ID.
+   *
+   * @param job - Job configuration.
+   * @param options - Optional. Pass `{ db }` to run the INSERT on an external
+   *   client (e.g., inside a transaction). PostgreSQL only.
+   */
   addJob<PayloadMap, T extends JobType<PayloadMap>>(
     job: JobOptions<PayloadMap, T>,
+    options?: AddJobOptions,
   ): Promise<number>;
 
+  /**
+   * Add multiple jobs in a single operation and return their IDs.
+   *
+   * IDs are returned in the same order as the input array.
+   * Each job may independently have an `idempotencyKey`; duplicates
+   * resolve to the existing job's ID without creating a new row.
+   *
+   * @param jobs - Array of job configurations.
+   * @param options - Optional. Pass `{ db }` to run the INSERTs on an external
+   *   client (e.g., inside a transaction). PostgreSQL only.
+   */
+  addJobs<PayloadMap, T extends JobType<PayloadMap>>(
+    jobs: JobOptions<PayloadMap, T>[],
+    options?: AddJobOptions,
+  ): Promise<number[]>;
+
   /** Get a single job by ID, or null if not found. */
   getJob<PayloadMap, T extends JobType<PayloadMap>>(
     id: number,
@@ -127,11 +181,11 @@ export interface QueueBackend {
     updates: JobUpdates,
   ): Promise<number>;
 
-  /** Delete completed jobs older than N days. Returns count deleted. */
-  cleanupOldJobs(daysToKeep?: number): Promise<number>;
+  /** Delete completed jobs older than N days. Deletes in batches for scale safety. Returns count deleted. */
+  cleanupOldJobs(daysToKeep?: number, batchSize?: number): Promise<number>;
 
-  /** Delete job events older than N days. Returns count deleted. */
-  cleanupOldJobEvents(daysToKeep?: number): Promise<number>;
+  /** Delete job events older than N days. Deletes in batches for scale safety. Returns count deleted. */
+  cleanupOldJobEvents(daysToKeep?: number, batchSize?: number): Promise<number>;
 
   /** Reclaim jobs stuck in 'processing' for too long. Returns count. */
   reclaimStuckJobs(maxProcessingTimeMinutes?: number): Promise<number>;
@@ -153,6 +207,117 @@ export interface QueueBackend {
   /** Get all events for a job, ordered by createdAt ASC. */
   getJobEvents(jobId: number): Promise<JobEvent[]>;
 
+  // ── Cron schedules ──────────────────────────────────────────────────
+
+  /** Create a cron schedule and return its ID. */
+  addCronSchedule(input: CronScheduleInput): Promise<number>;
+
+  /** Get a cron schedule by ID, or null if not found. */
+  getCronSchedule(id: number): Promise<CronScheduleRecord | null>;
+
+  /** Get a cron schedule by its unique name, or null if not found. */
+  getCronScheduleByName(name: string): Promise<CronScheduleRecord | null>;
+
+  /** List cron schedules, optionally filtered by status. */
+  listCronSchedules(status?: CronScheduleStatus): Promise<CronScheduleRecord[]>;
+
+  /** Delete a cron schedule by ID. */
+  removeCronSchedule(id: number): Promise<void>;
+
+  /** Pause a cron schedule. */
+  pauseCronSchedule(id: number): Promise<void>;
+
+  /** Resume a cron schedule. */
+  resumeCronSchedule(id: number): Promise<void>;
+
+  /** Edit a cron schedule. */
+  editCronSchedule(
+    id: number,
+    updates: EditCronScheduleOptions,
+    nextRunAt?: Date | null,
+  ): Promise<void>;
+
+  /**
+   * Atomically fetch all active cron schedules whose nextRunAt <= now.
+   * In PostgreSQL this uses FOR UPDATE SKIP LOCKED to prevent duplicate enqueuing.
+   */
+  getDueCronSchedules(): Promise<CronScheduleRecord[]>;
+
+  /**
+   * Update a cron schedule after a job has been enqueued.
+   * Sets lastEnqueuedAt, lastJobId, and advances nextRunAt.
+   */
+  updateCronScheduleAfterEnqueue(
+    id: number,
+    lastEnqueuedAt: Date,
+    lastJobId: number,
+    nextRunAt: Date | null,
+  ): Promise<void>;
+
+  // ── Wait / step-data support ────────────────────────────────────────
+
+  /**
+   * Transition a job from 'processing' to 'waiting' status.
+   * Persists step data so the handler can resume from where it left off.
+   *
+   * @param jobId - The job to pause.
+   * @param options - Wait configuration including optional waitUntil date, token ID, and step data.
+   */
+  waitJob(
+    jobId: number,
+    options: {
+      waitUntil?: Date;
+      waitTokenId?: string;
+      stepData: Record<string, any>;
+    },
+  ): Promise<void>;
+
+  /**
+   * Persist step data for a job. Called after each `ctx.run()` step completes
+   * to save intermediate progress. Best-effort: should not throw.
+   *
+   * @param jobId - The job to update.
+   * @param stepData - The step data to persist.
+   */
+  updateStepData(jobId: number, stepData: Record<string, any>): Promise<void>;
+
+  /**
+   * Create a waitpoint token that can pause a job until an external signal completes it.
+   *
+   * @param jobId - The job ID to associate with the token (null if created outside a handler).
+   * @param options - Optional timeout string (e.g. '10m', '1h') and tags.
+   * @returns The created waitpoint with its unique ID.
+   */
+  createWaitpoint(
+    jobId: number | null,
+    options?: CreateTokenOptions,
+  ): Promise<{ id: string }>;
+
+  /**
+   * Complete a waitpoint token, optionally providing output data.
+   * Moves the associated job from 'waiting' back to 'pending' so it gets picked up.
+   *
+   * @param tokenId - The waitpoint token ID to complete.
+   * @param data - Optional data to pass to the waiting handler.
+   */
+  completeWaitpoint(tokenId: string, data?: any): Promise<void>;
+
+  /**
+   * Retrieve a waitpoint token by its ID.
+   *
+   * @param tokenId - The waitpoint token ID to look up.
+   * @returns The waitpoint record, or null if not found.
+   */
+  getWaitpoint(tokenId: string): Promise<WaitpointRecord | null>;
+
+  /**
+   * Expire timed-out waitpoint tokens and move their associated jobs back to 'pending'.
+   * Should be called periodically (e.g., alongside reclaimStuckJobs).
+   *
+   * @returns The number of tokens that were expired.
+   */
+  expireTimedOutWaitpoints(): Promise<number>;
+
   // ── Internal helpers ──────────────────────────────────────────────────
 
   /** Set a pending reason for unpicked jobs of a given type. */