@trigger.dev/sdk 4.6.4 → 4.7.0

package/dist/esm/v3/shared.js

@@ -2,31 +2,106 @@ import { SpanKind } from "@opentelemetry/api";
 import { accessoryAttributes, apiClientManager, ApiError, conditionallyExportPacket, conditionallyImportPacket, convertToolParametersToSchema, createErrorFromCauses, createErrorTaskError, defaultRetryOptions, flattenIdempotencyKey, generateFriendlyId, getIdempotencyKeyOptions, getSchemaParseFn, lifecycleHooks, makeIdempotencyKey, packetRequiresOffloading, parsePacket, RateLimitError, resourceCatalog, runtime, SemanticInternalAttributes, stringifyIO, SubtaskUnwrapError, taskContext, TaskRunPromise, } from "@trigger.dev/core/v3";
 import { resolveTriggerExternalDeploymentId, scopedEnvVar } from "./externalDeploymentId.js";
 import { tracer } from "./tracer.js";
+import { triggerConcurrencyBody, validateConcurrencyLimitName } from "./concurrency-shared.js";
 export { SubtaskUnwrapError, TaskRunPromise };
+/** A task's `queue` is a queue object or a string reference to a queue defined elsewhere. */
+function normalizeTaskQueue(queue) {
+    if (!queue) {
+        return {};
+    }
+    return { queue: typeof queue === "string" ? { name: queue } : queue };
+}
+/**
+ * Validates and normalizes the task `concurrency` option into its manifest shape:
+ * at most one inline limit (caps this task) plus up to two named limits (shared).
+ */
+function normalizeTaskConcurrency(taskId, concurrency) {
+    if (!concurrency) {
+        return undefined;
+    }
+    const items = Array.isArray(concurrency) ? concurrency : [concurrency];
+    const inline = [];
+    const limits = [];
+    for (const item of items) {
+        if (typeof item === "string") {
+            limits.push(item);
+        }
+        else if (item &&
+            typeof item === "object" &&
+            "name" in item &&
+            typeof item.name === "string") {
+            validateConcurrencyLimitName(item.name);
+            resourceCatalog.registerConcurrencyLimitMetadata(item);
+            limits.push(item.name);
+        }
+        else if (item && typeof item === "object") {
+            inline.push({ perKey: item.perKey, total: item.total });
+        }
+    }
+    if (inline.length > 1) {
+        throw new Error(`Task "${taskId}": concurrency accepts at most one inline limit. Give shared limits a name with concurrencyLimit().`);
+    }
+    if (limits.length > 2) {
+        throw new Error(`Task "${taskId}": concurrency accepts at most two named limits.`);
+    }
+    return {
+        inline: inline[0],
+        limits: limits.length > 0 ? limits : undefined,
+    };
+}
+/** Builds the queue field of a trigger request body. */
+function triggerQueueBody(queue, fallbackQueueName) {
+    const name = queue ?? fallbackQueueName;
+    return { queue: name ? { name } : undefined };
+}
 export function queue(options) {
     resourceCatalog.registerQueueMetadata(options);
     // @ts-expect-error
     options[Symbol.for("trigger.dev/queue")] = true;
     return options;
 }
+/**
+ * Declares a named, shareable concurrency limit. Tasks hold it via their `concurrency`
+ * option; every task holding the same limit draws from the same pools.
+ *
+ * @example
+ *
+ * ```ts
+ * export const openaiLimit = concurrencyLimit({ name: "openai", total: 25 });
+ *
+ * export const generateSummary = task({
+ *   id: "generate-summary",
+ *   concurrency: [{ total: 5 }, openaiLimit],
+ *   run: async (payload) => {},
+ * });
+ * ```
+ */
+export function concurrencyLimit(options) {
+    validateConcurrencyLimitName(options.name);
+    resourceCatalog.registerConcurrencyLimitMetadata(options);
+    // @ts-expect-error
+    options[Symbol.for("trigger.dev/concurrencyLimit")] = true;
+    return options;
+}
 export function createTask(params) {
+    const normalizedQueue = normalizeTaskQueue(params.queue);
     const task = {
         id: params.id,
         description: params.description,
         jsonSchema: params.jsonSchema,
         trigger: async (payload, options) => {
             return await trigger_internal("trigger()", params.id, payload, undefined, {
-                queue: params.queue?.name,
+                queue: normalizedQueue.queue?.name,
                 ...options,
             });
         },
         batchTrigger: async (items, options) => {
-            return await batchTrigger_internal("batchTrigger()", params.id, items, options, undefined, undefined, params.queue?.name);
+            return await batchTrigger_internal("batchTrigger()", params.id, items, options, undefined, undefined, normalizedQueue.queue?.name);
         },
         triggerAndWait: (payload, options, requestOptions) => {
             return new TaskRunPromise((resolve, reject) => {
                 triggerAndWait_internal("triggerAndWait()", params.id, payload, undefined, {
-                    queue: params.queue?.name,
+                    queue: normalizedQueue.queue?.name,
                     ...options,
                 }, requestOptions)
                     .then((result) => {
@@ -40,7 +115,7 @@ export function createTask(params) {
         triggerAndSubscribe: (payload, options) => {
             return new TaskRunPromise((resolve, reject) => {
                 triggerAndSubscribe_internal("triggerAndSubscribe()", params.id, payload, undefined, {
-                    queue: params.queue?.name,
+                    queue: normalizedQueue.queue?.name,
                     ...options,
                 })
                     .then((result) => {
@@ -52,14 +127,15 @@ export function createTask(params) {
             }, params.id);
         },
         batchTriggerAndWait: async (items, options) => {
-            return await batchTriggerAndWait_internal("batchTriggerAndWait()", params.id, items, undefined, options, undefined, params.queue?.name);
+            return await batchTriggerAndWait_internal("batchTriggerAndWait()", params.id, items, undefined, options, undefined, normalizedQueue.queue?.name);
         },
     };
     registerTaskLifecycleHooks(params.id, params);
     resourceCatalog.registerTaskMetadata({
         id: params.id,
         description: params.description,
-        queue: params.queue,
+        queue: normalizedQueue.queue,
+        concurrency: normalizeTaskConcurrency(params.id, params.concurrency),
         retry: params.retry ? { ...defaultRetryOptions, ...params.retry } : undefined,
         machine: typeof params.machine === "string" ? { preset: params.machine } : params.machine,
         triggerSource: params.triggerSource,
@@ -71,8 +147,14 @@ export function createTask(params) {
             run: params.run,
         },
     });
-    const queue = params.queue;
-    if (queue && typeof queue.name === "string") {
+    const queue = normalizedQueue.queue;
+    /**
+     * A string queue name (bare or as a tuple's first element) is a REFERENCE to a
+     * queue defined elsewhere; registering it would create an empty definition that
+     * can shadow the real one depending on module evaluation order.
+     */
+    const homeIsReference = typeof params.queue === "string";
+    if (queue && typeof queue.name === "string" && !homeIsReference) {
         resourceCatalog.registerQueueMetadata({
             name: queue.name,
             concurrencyLimit: queue.concurrencyLimit,
@@ -105,23 +187,24 @@ export function createSchemaTask(params) {
     const parsePayload = params.schema
         ? getSchemaParseFn(params.schema)
         : undefined;
+    const normalizedQueue = normalizeTaskQueue(params.queue);
     const task = {
         id: params.id,
         description: params.description,
         schema: params.schema,
         trigger: async (payload, options, requestOptions) => {
             return await trigger_internal("trigger()", params.id, payload, parsePayload, {
-                queue: params.queue?.name,
+                queue: normalizedQueue.queue?.name,
                 ...options,
             }, requestOptions);
         },
         batchTrigger: async (items, options, requestOptions) => {
-            return await batchTrigger_internal("batchTrigger()", params.id, items, options, parsePayload, requestOptions, params.queue?.name);
+            return await batchTrigger_internal("batchTrigger()", params.id, items, options, parsePayload, requestOptions, normalizedQueue.queue?.name);
         },
         triggerAndWait: (payload, options) => {
             return new TaskRunPromise((resolve, reject) => {
                 triggerAndWait_internal("triggerAndWait()", params.id, payload, parsePayload, {
-                    queue: params.queue?.name,
+                    queue: normalizedQueue.queue?.name,
                     ...options,
                 })
                     .then((result) => {
@@ -135,7 +218,7 @@ export function createSchemaTask(params) {
         triggerAndSubscribe: (payload, options) => {
             return new TaskRunPromise((resolve, reject) => {
                 triggerAndSubscribe_internal("triggerAndSubscribe()", params.id, payload, parsePayload, {
-                    queue: params.queue?.name,
+                    queue: normalizedQueue.queue?.name,
                     ...options,
                 })
                     .then((result) => {
@@ -147,14 +230,15 @@ export function createSchemaTask(params) {
             }, params.id);
         },
         batchTriggerAndWait: async (items, options) => {
-            return await batchTriggerAndWait_internal("batchTriggerAndWait()", params.id, items, parsePayload, options, undefined, params.queue?.name);
+            return await batchTriggerAndWait_internal("batchTriggerAndWait()", params.id, items, parsePayload, options, undefined, normalizedQueue.queue?.name);
         },
     };
     registerTaskLifecycleHooks(params.id, params);
     resourceCatalog.registerTaskMetadata({
         id: params.id,
         description: params.description,
-        queue: params.queue,
+        queue: normalizedQueue.queue,
+        concurrency: normalizeTaskConcurrency(params.id, params.concurrency),
         retry: params.retry ? { ...defaultRetryOptions, ...params.retry } : undefined,
         machine: typeof params.machine === "string" ? { preset: params.machine } : params.machine,
         triggerSource: params.triggerSource,
@@ -167,8 +251,14 @@ export function createSchemaTask(params) {
         },
         schema: params.schema,
     });
-    const queue = params.queue;
-    if (queue && typeof queue.name === "string") {
+    const queue = normalizedQueue.queue;
+    /**
+     * A string queue name (bare or as a tuple's first element) is a REFERENCE to a
+     * queue defined elsewhere; registering it would create an empty definition that
+     * can shadow the real one depending on module evaluation order.
+     */
+    const homeIsReference = typeof params.queue === "string";
+    if (queue && typeof queue.name === "string" && !homeIsReference) {
         resourceCatalog.registerQueueMetadata({
             name: queue.name,
             concurrencyLimit: queue.concurrencyLimit,
@@ -307,7 +397,8 @@ export async function batchTriggerById(...args) {
                 task: item.id,
                 payload: payloadPacket.data,
                 options: {
-                    queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                    ...triggerQueueBody(item.options?.queue),
+                    ...triggerConcurrencyBody(item.options?.concurrency),
                     concurrencyKey: item.options?.concurrencyKey,
                     test: taskContext.ctx?.run.isTest,
                     payloadType: payloadPacket.dataType,
@@ -403,7 +494,8 @@ export async function batchTriggerByIdAndWait(...args) {
                 payload: payloadPacket.data,
                 options: {
                     lockToVersion: taskContext.worker?.version,
-                    queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                    ...triggerQueueBody(item.options?.queue),
+                    ...triggerConcurrencyBody(item.options?.concurrency),
                     concurrencyKey: item.options?.concurrencyKey,
                     test: taskContext.ctx?.run.isTest,
                     payloadType: payloadPacket.dataType,
@@ -500,7 +592,8 @@ export async function batchTriggerTasks(...args) {
                 task: item.task.id,
                 payload: payloadPacket.data,
                 options: {
-                    queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                    ...triggerQueueBody(item.options?.queue),
+                    ...triggerConcurrencyBody(item.options?.concurrency),
                     concurrencyKey: item.options?.concurrencyKey,
                     test: taskContext.ctx?.run.isTest,
                     payloadType: payloadPacket.dataType,
@@ -597,7 +690,8 @@ export async function batchTriggerAndWaitTasks(...args) {
                 payload: payloadPacket.data,
                 options: {
                     lockToVersion: taskContext.worker?.version,
-                    queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                    ...triggerQueueBody(item.options?.queue),
+                    ...triggerConcurrencyBody(item.options?.concurrency),
                     concurrencyKey: item.options?.concurrencyKey,
                     test: taskContext.ctx?.run.isTest,
                     payloadType: payloadPacket.dataType,
@@ -955,7 +1049,8 @@ async function* transformBatchItemsStream(items, options) {
             task: item.id,
             payload: payloadPacket.data,
             options: {
-                queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                ...triggerQueueBody(item.options?.queue),
+                ...triggerConcurrencyBody(item.options?.concurrency),
                 concurrencyKey: item.options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: payloadPacket.dataType,
@@ -998,7 +1093,8 @@ async function* transformBatchItemsStreamForWait(items, options) {
             payload: payloadPacket.data,
             options: {
                 lockToVersion: taskContext.worker?.version,
-                queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                ...triggerQueueBody(item.options?.queue),
+                ...triggerConcurrencyBody(item.options?.concurrency),
                 concurrencyKey: item.options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: payloadPacket.dataType,
@@ -1037,7 +1133,8 @@ async function* transformBatchByTaskItemsStream(items, options) {
             task: item.task.id,
             payload: payloadPacket.data,
             options: {
-                queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                ...triggerQueueBody(item.options?.queue),
+                ...triggerConcurrencyBody(item.options?.concurrency),
                 concurrencyKey: item.options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: payloadPacket.dataType,
@@ -1079,7 +1176,8 @@ async function* transformBatchByTaskItemsStreamForWait(items, options) {
             payload: payloadPacket.data,
             options: {
                 lockToVersion: taskContext.worker?.version,
-                queue: item.options?.queue ? { name: item.options.queue } : undefined,
+                ...triggerQueueBody(item.options?.queue),
+                ...triggerConcurrencyBody(item.options?.concurrency),
                 concurrencyKey: item.options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: payloadPacket.dataType,
@@ -1115,11 +1213,8 @@ async function* transformSingleTaskBatchItemsStream(taskIdentifier, items, parse
             task: taskIdentifier,
             payload: payloadPacket.data,
             options: {
-                queue: item.options?.queue
-                    ? { name: item.options.queue }
-                    : queue
-                        ? { name: queue }
-                        : undefined,
+                ...triggerQueueBody(item.options?.queue, queue),
+                ...triggerConcurrencyBody(item.options?.concurrency),
                 concurrencyKey: item.options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: payloadPacket.dataType,
@@ -1164,11 +1259,8 @@ async function* transformSingleTaskBatchItemsStreamForWait(taskIdentifier, items
             payload: payloadPacket.data,
             options: {
                 lockToVersion: taskContext.worker?.version,
-                queue: item.options?.queue
-                    ? { name: item.options.queue }
-                    : queue
-                        ? { name: queue }
-                        : undefined,
+                ...triggerQueueBody(item.options?.queue, queue),
+                ...triggerConcurrencyBody(item.options?.concurrency),
                 concurrencyKey: item.options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: payloadPacket.dataType,
@@ -1201,7 +1293,8 @@ async function trigger_internal(name, id, payload, parsePayload, options, reques
     const handle = await apiClient.triggerTask(id, {
         payload: triggerPayloadPacket.data,
         options: {
-            queue: options?.queue ? { name: options.queue } : undefined,
+            ...triggerQueueBody(options?.queue),
+            ...triggerConcurrencyBody(options?.concurrency),
             concurrencyKey: options?.concurrencyKey,
             test: taskContext.ctx?.run.isTest,
             payloadType: triggerPayloadPacket.dataType,
@@ -1261,11 +1354,8 @@ async function batchTrigger_internal(name, taskIdentifier, items, options, parse
                 task: taskIdentifier,
                 payload: payloadPacket.data,
                 options: {
-                    queue: item.options?.queue
-                        ? { name: item.options.queue }
-                        : queue
-                            ? { name: queue }
-                            : undefined,
+                    ...triggerQueueBody(item.options?.queue, queue),
+                    ...triggerConcurrencyBody(item.options?.concurrency),
                     concurrencyKey: item.options?.concurrencyKey,
                     test: taskContext.ctx?.run.isTest,
                     payloadType: payloadPacket.dataType,
@@ -1386,7 +1476,8 @@ async function triggerAndWait_internal(name, id, payload, parsePayload, options,
             payload: triggerPayloadPacket.data,
             options: {
                 lockToVersion: taskContext.worker?.version, // Lock to current version because we're waiting for it to finish
-                queue: options?.queue ? { name: options.queue } : undefined,
+                ...triggerQueueBody(options?.queue),
+                ...triggerConcurrencyBody(options?.concurrency),
                 concurrencyKey: options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: triggerPayloadPacket.dataType,
@@ -1447,7 +1538,8 @@ async function triggerAndSubscribe_internal(name, id, payload, parsePayload, opt
             payload: triggerPayloadPacket.data,
             options: {
                 lockToVersion: taskContext.worker?.version,
-                queue: options?.queue ? { name: options.queue } : undefined,
+                ...triggerQueueBody(options?.queue),
+                ...triggerConcurrencyBody(options?.concurrency),
                 concurrencyKey: options?.concurrencyKey,
                 test: taskContext.ctx?.run.isTest,
                 payloadType: triggerPayloadPacket.dataType,
@@ -1582,11 +1674,8 @@ async function batchTriggerAndWait_internal(name, id, items, parsePayload, optio
                 payload: payloadPacket.data,
                 options: {
                     lockToVersion: taskContext.worker?.version,
-                    queue: item.options?.queue
-                        ? { name: item.options.queue }
-                        : queue
-                            ? { name: queue }
-                            : undefined,
+                    ...triggerQueueBody(item.options?.queue, queue),
+                    ...triggerConcurrencyBody(item.options?.concurrency),
                     concurrencyKey: item.options?.concurrencyKey,
                     test: taskContext.ctx?.run.isTest,
                     payloadType: payloadPacket.dataType,