@nicnocquee/dataqueue 1.38.0 → 1.39.0-beta.20260322125514

package/dist/index.d.cts

@@ -41,6 +41,29 @@ interface JobGroup {
     /** Optional tier label reserved for future tier-based concurrency controls. */
     tier?: string;
 }
+/**
+ * Declares prerequisites for a job. Both dimensions use logical AND.
+ *
+ * - `jobIds`: The job will not run until every listed job is `completed`. If any
+ *   prerequisite becomes `failed` or `cancelled`, pending dependents are cancelled (transitively).
+ * - `tags`: Active barrier — the job will not run while another job (not self) is
+ *   `pending`, `processing`, or `waiting` whose `tags` are a superset of every tag listed here
+ *   (Postgres `tags @> depends_on_tags`). If any such job becomes `failed` or `cancelled`,
+ *   pending jobs that list these tags are cancelled (transitively).
+ *
+ * **`addJobs` batch references:** In a batch insert, a negative job id means a 0-based index
+ * into the same batch array: use {@link batchDepRef} (e.g. `batchDepRef(0)` for the first job).
+ * Single `addJob` calls must use positive database ids only.
+ */
+interface JobDependsOn {
+    /** Prerequisite job ids (must all reach `completed`). */
+    jobIds?: number[];
+    /**
+     * Tag drain: wait until no active job (pending/processing/waiting) has all of these tags.
+     * Requires matching jobs to succeed (dependents are cancelled if a matching job fails or is cancelled).
+     */
+    tags?: string[];
+}
 interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
     jobType: T;
     payload: PayloadMap[T];
@@ -148,6 +171,10 @@ interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
      * globally limited by `group.id` across all workers/instances.
      */
     group?: JobGroup;
+    /**
+     * Optional prerequisites (job ids and/or tag drain). See {@link JobDependsOn}.
+     */
+    dependsOn?: JobDependsOn;
 }
 /**
  * Options for editing a pending job.
@@ -297,6 +324,14 @@ interface JobRecord<PayloadMap, T extends JobType<PayloadMap>> {
      * Group tier for this job, if provided at enqueue time.
      */
     groupTier?: string | null;
+    /**
+     * Prerequisite job ids persisted at enqueue time, if any.
+     */
+    dependsOnJobIds?: number[] | null;
+    /**
+     * Tag drain prerequisites persisted at enqueue time, if any.
+     */
+    dependsOnTags?: string[] | null;
 }
 /**
  * Envelope payload stored in dead-letter jobs.
@@ -1211,6 +1246,54 @@ interface JobQueue<PayloadMap> {
     getRedisClient: () => unknown;
 }
 
+/**
+ * Returns a negative placeholder id for `addJobs` batch ordering: `-(index + 1)`.
+ * Resolves to the id of the job at `batchIndex` in the same batch after inserts.
+ *
+ * @param batchIndex - Zero-based index into the `addJobs` array.
+ */
+declare function batchDepRef(batchIndex: number): number;
+/**
+ * Normalizes optional `dependsOn`: empty arrays become undefined, ids de-duplicated.
+ *
+ * @param dep - Raw dependency options from the caller.
+ */
+declare function normalizeDependsOn(dep?: JobDependsOn): {
+    jobIds: number[] | undefined;
+    tags: string[] | undefined;
+};
+/**
+ * Resolves batch-relative negative ids to real job ids after partial batch inserts.
+ *
+ * @param jobIds - May contain negative placeholders from {@link batchDepRef}.
+ * @param insertedIds - Ids inserted so far, index-aligned with the batch array prefix.
+ */
+declare function resolveDependsOnJobIdsForBatch(jobIds: number[], insertedIds: number[]): number[];
+/**
+ * Returns true if `holderTags` contains every tag in `requiredTags` (set inclusion).
+ *
+ * @param holderTags - Tags on job X.
+ * @param requiredTags - `depends_on_tags` on dependent D.
+ */
+declare function tagsAreSuperset(holderTags: string[] | null | undefined, requiredTags: string[] | null | undefined): boolean;
+/**
+ * Throws if inserting a job with `dependsOnJobIds` would create a cycle.
+ * Uses: jobs reachable downstream from `newJobId` must not include any prerequisite id
+ * (equivalently: a prerequisite must not lie in the downstream closure of `newJobId`).
+ *
+ * @param client - DB client (transaction).
+ * @param newJobId - Id of the row just inserted.
+ * @param dependsOnJobIds - Resolved positive prerequisite ids.
+ */
+/**
+ * Ensures every id in `jobIds` exists in `job_queue`.
+ *
+ * @param client - Database client.
+ * @param jobIds - Resolved positive job ids.
+ */
+declare function validatePrerequisiteJobIdsExist(client: DatabaseClient, jobIds: number[]): Promise<void>;
+declare function assertNoDependencyCycle(client: DatabaseClient, newJobId: number, dependsOnJobIds: number[]): Promise<void>;
+
 /**
  * Filter options used by getJobs, cancelAllUpcomingJobs, editAllPendingJobs
  */
@@ -1440,7 +1523,7 @@ declare class PostgresBackend implements QueueBackend {
      *   client (e.g., inside a transaction) so the job is part of the caller's
      *   transaction. The event INSERT also uses the same client.
      */
-    addJob<PayloadMap, T extends JobType<PayloadMap>>({ jobType, payload, maxAttempts, priority, runAt, timeoutMs, forceKillOnTimeout, tags, idempotencyKey, retryDelay, retryBackoff, retryDelayMax, deadLetterJobType, group, }: JobOptions<PayloadMap, T>, options?: AddJobOptions): Promise<number>;
+    addJob<PayloadMap, T extends JobType<PayloadMap>>({ jobType, payload, maxAttempts, priority, runAt, timeoutMs, forceKillOnTimeout, tags, idempotencyKey, retryDelay, retryBackoff, retryDelayMax, deadLetterJobType, group, dependsOn, }: JobOptions<PayloadMap, T>, options?: AddJobOptions): Promise<number>;
     /**
      * Insert multiple jobs in a single database round-trip.
      *
@@ -1455,6 +1538,14 @@ declare class PostgresBackend implements QueueBackend {
     getJobsByTags<PayloadMap, T extends JobType<PayloadMap>>(tags: string[], mode?: TagQueryMode, limit?: number, offset?: number): Promise<JobRecord<PayloadMap, T>[]>;
     getNextBatch<PayloadMap, T extends JobType<PayloadMap>>(workerId: string, batchSize?: number, jobType?: string | string[], groupConcurrency?: number): Promise<JobRecord<PayloadMap, T>[]>;
     completeJob(jobId: number, output?: unknown): Promise<void>;
+    /**
+     * Cancel pending/waiting jobs that depend on any seed job (by job id or tag superset), transitively.
+     *
+     * @param client - Database client (must be inside an open transaction when used from fail/cancel).
+     * @param initialSeeds - Job ids that just failed or were cancelled.
+     * @param rootJobId - Original job id for event metadata.
+     */
+    private propagateDependencyCancellations;
     failJob(jobId: number, error: Error, failureReason?: FailureReason): Promise<void>;
     prolongJob(jobId: number): Promise<void>;
     updateProgress(jobId: number, progress: number): Promise<void>;
@@ -1648,4 +1739,4 @@ declare function validateCronExpression(cronExpression: string, CronImpl?: typeo
  */
 declare const initJobQueue: <PayloadMap = any>(config: JobQueueConfig) => JobQueue<PayloadMap>;
 
-export { type AddJobOptions, type CreateTokenOptions, type CronScheduleInput, type CronScheduleOptions, type CronScheduleRecord, type CronScheduleStatus, type DatabaseClient, type DatabaseSSLConfig, type DeadLetterPayloadEnvelope, type EditCronScheduleOptions, type EditJobOptions, FailureReason, type JobContext, type JobEvent, JobEventType, type JobGroup, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobQueueConfigLegacy, type JobRecord, type JobStatus, type JobType, type OnTimeoutCallback, PostgresBackend, type PostgresJobQueueConfig, type Processor, type ProcessorOptions, type QueueBackend, type QueueEmitFn, type QueueEventMap, type QueueEventName, type RedisJobQueueConfig, type RedisTLSConfig, type Supervisor, type SupervisorOptions, type SupervisorRunResult, type TagQueryMode, type WaitDuration, WaitSignal, type WaitToken, type WaitTokenResult, type WaitpointRecord, type WaitpointStatus, getNextCronOccurrence, initJobQueue, testHandlerSerialization, validateCronExpression, validateHandlerSerializable };
+export { type AddJobOptions, type CreateTokenOptions, type CronScheduleInput, type CronScheduleOptions, type CronScheduleRecord, type CronScheduleStatus, type DatabaseClient, type DatabaseSSLConfig, type DeadLetterPayloadEnvelope, type EditCronScheduleOptions, type EditJobOptions, FailureReason, type JobContext, type JobDependsOn, type JobEvent, JobEventType, type JobGroup, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobQueueConfigLegacy, type JobRecord, type JobStatus, type JobType, type OnTimeoutCallback, PostgresBackend, type PostgresJobQueueConfig, type Processor, type ProcessorOptions, type QueueBackend, type QueueEmitFn, type QueueEventMap, type QueueEventName, type RedisJobQueueConfig, type RedisTLSConfig, type Supervisor, type SupervisorOptions, type SupervisorRunResult, type TagQueryMode, type WaitDuration, WaitSignal, type WaitToken, type WaitTokenResult, type WaitpointRecord, type WaitpointStatus, assertNoDependencyCycle, batchDepRef, getNextCronOccurrence, initJobQueue, normalizeDependsOn, resolveDependsOnJobIdsForBatch, tagsAreSuperset, testHandlerSerialization, validateCronExpression, validateHandlerSerializable, validatePrerequisiteJobIdsExist };

package/dist/index.d.ts

@@ -41,6 +41,29 @@ interface JobGroup {
     /** Optional tier label reserved for future tier-based concurrency controls. */
     tier?: string;
 }
+/**
+ * Declares prerequisites for a job. Both dimensions use logical AND.
+ *
+ * - `jobIds`: The job will not run until every listed job is `completed`. If any
+ *   prerequisite becomes `failed` or `cancelled`, pending dependents are cancelled (transitively).
+ * - `tags`: Active barrier — the job will not run while another job (not self) is
+ *   `pending`, `processing`, or `waiting` whose `tags` are a superset of every tag listed here
+ *   (Postgres `tags @> depends_on_tags`). If any such job becomes `failed` or `cancelled`,
+ *   pending jobs that list these tags are cancelled (transitively).
+ *
+ * **`addJobs` batch references:** In a batch insert, a negative job id means a 0-based index
+ * into the same batch array: use {@link batchDepRef} (e.g. `batchDepRef(0)` for the first job).
+ * Single `addJob` calls must use positive database ids only.
+ */
+interface JobDependsOn {
+    /** Prerequisite job ids (must all reach `completed`). */
+    jobIds?: number[];
+    /**
+     * Tag drain: wait until no active job (pending/processing/waiting) has all of these tags.
+     * Requires matching jobs to succeed (dependents are cancelled if a matching job fails or is cancelled).
+     */
+    tags?: string[];
+}
 interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
     jobType: T;
     payload: PayloadMap[T];
@@ -148,6 +171,10 @@ interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
      * globally limited by `group.id` across all workers/instances.
      */
     group?: JobGroup;
+    /**
+     * Optional prerequisites (job ids and/or tag drain). See {@link JobDependsOn}.
+     */
+    dependsOn?: JobDependsOn;
 }
 /**
  * Options for editing a pending job.
@@ -297,6 +324,14 @@ interface JobRecord<PayloadMap, T extends JobType<PayloadMap>> {
      * Group tier for this job, if provided at enqueue time.
      */
     groupTier?: string | null;
+    /**
+     * Prerequisite job ids persisted at enqueue time, if any.
+     */
+    dependsOnJobIds?: number[] | null;
+    /**
+     * Tag drain prerequisites persisted at enqueue time, if any.
+     */
+    dependsOnTags?: string[] | null;
 }
 /**
  * Envelope payload stored in dead-letter jobs.
@@ -1211,6 +1246,54 @@ interface JobQueue<PayloadMap> {
     getRedisClient: () => unknown;
 }
 
+/**
+ * Returns a negative placeholder id for `addJobs` batch ordering: `-(index + 1)`.
+ * Resolves to the id of the job at `batchIndex` in the same batch after inserts.
+ *
+ * @param batchIndex - Zero-based index into the `addJobs` array.
+ */
+declare function batchDepRef(batchIndex: number): number;
+/**
+ * Normalizes optional `dependsOn`: empty arrays become undefined, ids de-duplicated.
+ *
+ * @param dep - Raw dependency options from the caller.
+ */
+declare function normalizeDependsOn(dep?: JobDependsOn): {
+    jobIds: number[] | undefined;
+    tags: string[] | undefined;
+};
+/**
+ * Resolves batch-relative negative ids to real job ids after partial batch inserts.
+ *
+ * @param jobIds - May contain negative placeholders from {@link batchDepRef}.
+ * @param insertedIds - Ids inserted so far, index-aligned with the batch array prefix.
+ */
+declare function resolveDependsOnJobIdsForBatch(jobIds: number[], insertedIds: number[]): number[];
+/**
+ * Returns true if `holderTags` contains every tag in `requiredTags` (set inclusion).
+ *
+ * @param holderTags - Tags on job X.
+ * @param requiredTags - `depends_on_tags` on dependent D.
+ */
+declare function tagsAreSuperset(holderTags: string[] | null | undefined, requiredTags: string[] | null | undefined): boolean;
+/**
+ * Throws if inserting a job with `dependsOnJobIds` would create a cycle.
+ * Uses: jobs reachable downstream from `newJobId` must not include any prerequisite id
+ * (equivalently: a prerequisite must not lie in the downstream closure of `newJobId`).
+ *
+ * @param client - DB client (transaction).
+ * @param newJobId - Id of the row just inserted.
+ * @param dependsOnJobIds - Resolved positive prerequisite ids.
+ */
+/**
+ * Ensures every id in `jobIds` exists in `job_queue`.
+ *
+ * @param client - Database client.
+ * @param jobIds - Resolved positive job ids.
+ */
+declare function validatePrerequisiteJobIdsExist(client: DatabaseClient, jobIds: number[]): Promise<void>;
+declare function assertNoDependencyCycle(client: DatabaseClient, newJobId: number, dependsOnJobIds: number[]): Promise<void>;
+
 /**
  * Filter options used by getJobs, cancelAllUpcomingJobs, editAllPendingJobs
  */
@@ -1440,7 +1523,7 @@ declare class PostgresBackend implements QueueBackend {
      *   client (e.g., inside a transaction) so the job is part of the caller's
      *   transaction. The event INSERT also uses the same client.
      */
-    addJob<PayloadMap, T extends JobType<PayloadMap>>({ jobType, payload, maxAttempts, priority, runAt, timeoutMs, forceKillOnTimeout, tags, idempotencyKey, retryDelay, retryBackoff, retryDelayMax, deadLetterJobType, group, }: JobOptions<PayloadMap, T>, options?: AddJobOptions): Promise<number>;
+    addJob<PayloadMap, T extends JobType<PayloadMap>>({ jobType, payload, maxAttempts, priority, runAt, timeoutMs, forceKillOnTimeout, tags, idempotencyKey, retryDelay, retryBackoff, retryDelayMax, deadLetterJobType, group, dependsOn, }: JobOptions<PayloadMap, T>, options?: AddJobOptions): Promise<number>;
     /**
      * Insert multiple jobs in a single database round-trip.
      *
@@ -1455,6 +1538,14 @@ declare class PostgresBackend implements QueueBackend {
     getJobsByTags<PayloadMap, T extends JobType<PayloadMap>>(tags: string[], mode?: TagQueryMode, limit?: number, offset?: number): Promise<JobRecord<PayloadMap, T>[]>;
     getNextBatch<PayloadMap, T extends JobType<PayloadMap>>(workerId: string, batchSize?: number, jobType?: string | string[], groupConcurrency?: number): Promise<JobRecord<PayloadMap, T>[]>;
     completeJob(jobId: number, output?: unknown): Promise<void>;
+    /**
+     * Cancel pending/waiting jobs that depend on any seed job (by job id or tag superset), transitively.
+     *
+     * @param client - Database client (must be inside an open transaction when used from fail/cancel).
+     * @param initialSeeds - Job ids that just failed or were cancelled.
+     * @param rootJobId - Original job id for event metadata.
+     */
+    private propagateDependencyCancellations;
     failJob(jobId: number, error: Error, failureReason?: FailureReason): Promise<void>;
     prolongJob(jobId: number): Promise<void>;
     updateProgress(jobId: number, progress: number): Promise<void>;
@@ -1648,4 +1739,4 @@ declare function validateCronExpression(cronExpression: string, CronImpl?: typeo
  */
 declare const initJobQueue: <PayloadMap = any>(config: JobQueueConfig) => JobQueue<PayloadMap>;
 
-export { type AddJobOptions, type CreateTokenOptions, type CronScheduleInput, type CronScheduleOptions, type CronScheduleRecord, type CronScheduleStatus, type DatabaseClient, type DatabaseSSLConfig, type DeadLetterPayloadEnvelope, type EditCronScheduleOptions, type EditJobOptions, FailureReason, type JobContext, type JobEvent, JobEventType, type JobGroup, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobQueueConfigLegacy, type JobRecord, type JobStatus, type JobType, type OnTimeoutCallback, PostgresBackend, type PostgresJobQueueConfig, type Processor, type ProcessorOptions, type QueueBackend, type QueueEmitFn, type QueueEventMap, type QueueEventName, type RedisJobQueueConfig, type RedisTLSConfig, type Supervisor, type SupervisorOptions, type SupervisorRunResult, type TagQueryMode, type WaitDuration, WaitSignal, type WaitToken, type WaitTokenResult, type WaitpointRecord, type WaitpointStatus, getNextCronOccurrence, initJobQueue, testHandlerSerialization, validateCronExpression, validateHandlerSerializable };
+export { type AddJobOptions, type CreateTokenOptions, type CronScheduleInput, type CronScheduleOptions, type CronScheduleRecord, type CronScheduleStatus, type DatabaseClient, type DatabaseSSLConfig, type DeadLetterPayloadEnvelope, type EditCronScheduleOptions, type EditJobOptions, FailureReason, type JobContext, type JobDependsOn, type JobEvent, JobEventType, type JobGroup, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobQueueConfigLegacy, type JobRecord, type JobStatus, type JobType, type OnTimeoutCallback, PostgresBackend, type PostgresJobQueueConfig, type Processor, type ProcessorOptions, type QueueBackend, type QueueEmitFn, type QueueEventMap, type QueueEventName, type RedisJobQueueConfig, type RedisTLSConfig, type Supervisor, type SupervisorOptions, type SupervisorRunResult, type TagQueryMode, type WaitDuration, WaitSignal, type WaitToken, type WaitTokenResult, type WaitpointRecord, type WaitpointStatus, assertNoDependencyCycle, batchDepRef, getNextCronOccurrence, initJobQueue, normalizeDependsOn, resolveDependsOnJobIdsForBatch, tagsAreSuperset, testHandlerSerialization, validateCronExpression, validateHandlerSerializable, validatePrerequisiteJobIdsExist };