better-cf 0.2.2 → 2.0.0

package/dist/index.js

@@ -62,7 +62,7 @@ async function consumeQueueDefinition(definition, batch, env, executionCtx) {
   await consumeMulti(definition.jobs, definition.shared, batch, env, executionCtx);
 }
 async function consumeSingle(config, batch, env, executionCtx) {
-  if ("processBatch" in config && config.processBatch) {
+  if ("batchHandler" in config && config.batchHandler) {
     let ackOrRetryHandled = false;
     const batchCtx = {
       env,
@@ -81,14 +81,20 @@ async function consumeSingle(config, batch, env, executionCtx) {
         }
       }
     };
-    const typedMessages = batch.messages.map((msg) => ({
-      data: msg.body,
-      id: msg.id,
-      timestamp: msg.timestamp,
-      attempts: msg.attempts
-    }));
     try {
-      await config.processBatch(batchCtx, typedMessages);
+      const typedMessages = batch.messages.map((msg) => {
+        const parsed = config.args.safeParse(msg.body);
+        if (!parsed.success) {
+          throw new Error(`Queue batch validation failed for ${msg.id}: ${parsed.error.message}`);
+        }
+        return {
+          data: parsed.data,
+          id: msg.id,
+          timestamp: msg.timestamp,
+          attempts: msg.attempts
+        };
+      });
+      await config.batchHandler(batchCtx, typedMessages);
       if (!ackOrRetryHandled) {
         batch.ackAll();
       }
@@ -113,11 +119,11 @@ async function consumeSingle(config, batch, env, executionCtx) {
       }
     };
     try {
-      const parsed = config.message.safeParse(message.body);
+      const parsed = config.args.safeParse(message.body);
       if (!parsed.success) {
-        throw new Error(`Queue message validation failed: ${parsed.error.message}`);
+        throw new Error(`Queue args validation failed: ${parsed.error.message}`);
       }
-      await config.process(queueCtx, parsed.data);
+      await config.handler(queueCtx, parsed.data);
       message.ack();
     } catch (error) {
       await callFailureHandler(
@@ -152,11 +158,11 @@ async function consumeMulti(jobs, shared, batch, env, executionCtx) {
       }
     };
     try {
-      const parsed = job.message.safeParse(envelope.data);
+      const parsed = job.args.safeParse(envelope.data);
       if (!parsed.success) {
         throw new Error(`Queue job validation failed for ${jobName}: ${parsed.error.message}`);
       }
-      await job.process(queueCtx, parsed.data);
+      await job.handler(queueCtx, parsed.data);
       message.ack();
     } catch (error) {
       await callFailureHandler(
@@ -170,13 +176,13 @@ async function consumeMulti(jobs, shared, batch, env, executionCtx) {
     }
   }
 }
-async function callFailureHandler(handler, context, message, rawError) {
+async function callFailureHandler(handler, context, args, rawError) {
   if (!handler) {
     return;
   }
   const error = rawError instanceof Error ? rawError : new Error(String(rawError));
   try {
-    await handler(context, message, error);
+    await handler(context, args, error);
   } catch {
   }
 }
@@ -192,135 +198,150 @@ var RESERVED_MULTI_JOB_KEYS = /* @__PURE__ */ new Set([
   "deliveryDelay",
   "visibilityTimeout",
   "batch",
-  "consumer"
+  "consumer",
+  "args",
+  "handler",
+  "batchHandler",
+  "onFailure",
+  "message",
+  "process",
+  "processBatch"
 ]);
 
 // src/queue/define-queue.ts
+var LEGACY_SCHEMA_KEY = "message";
+var LEGACY_SINGLE_HANDLER_KEYS = ["process", "processBatch"];
 function defineQueueFactory() {
-  function defineQueue(config) {
-    const definition = toQueueDefinition(config);
-    let bindingName = null;
-    const sendBase = async (ctx, body, options) => {
-      if (!bindingName) {
-        throw new Error(
-          "Queue binding not initialized. Run through better-cf dev/generate/deploy generated entry."
-        );
-      }
-      const binding = ctx.env[bindingName];
-      if (!binding || typeof binding.send !== "function") {
-        throw new Error(`Queue binding ${bindingName} not found in env.`);
-      }
-      await binding.send(body, toCloudflareSendOptions(options));
-    };
-    const sendBatchBase = async (ctx, messages) => {
-      if (!bindingName) {
-        throw new Error(
-          "Queue binding not initialized. Run through better-cf dev/generate/deploy generated entry."
-        );
-      }
-      const binding = ctx.env[bindingName];
-      if (!binding || typeof binding.sendBatch !== "function") {
-        throw new Error(`Queue binding ${bindingName} not found in env.`);
+  return function defineQueue(config) {
+    assertNoLegacySingleQueueKeys(config);
+    const definition = toSingleQueueDefinition(config);
+    return createQueueHandle(definition);
+  };
+}
+function defineQueuesFactory() {
+  return function defineQueues(config) {
+    assertNoLegacyMultiQueueKeys(config);
+    const definition = toMultiQueueDefinition(config);
+    return createQueueHandle(definition);
+  };
+}
+function createQueueHandle(definition) {
+  let bindingName = null;
+  const sendBase = async (ctx, body, options) => {
+    if (!bindingName) {
+      throw new Error("Queue binding not initialized. Run through better-cf dev/generate/deploy generated entry.");
+    }
+    const binding = ctx.env[bindingName];
+    if (!binding || typeof binding.send !== "function") {
+      throw new Error(`Queue binding ${bindingName} not found in env.`);
+    }
+    await binding.send(body, toCloudflareSendOptions(options));
+  };
+  const sendBatchBase = async (ctx, messages) => {
+    if (!bindingName) {
+      throw new Error("Queue binding not initialized. Run through better-cf dev/generate/deploy generated entry.");
+    }
+    const binding = ctx.env[bindingName];
+    if (!binding || typeof binding.sendBatch !== "function") {
+      throw new Error(`Queue binding ${bindingName} not found in env.`);
+    }
+    const payload = messages.map((item) => ({
+      body: item.body,
+      ...toCloudflareSendOptions(item.options)
+    }));
+    await binding.sendBatch(payload);
+  };
+  const baseHandle = {
+    async send(ctx, data, options) {
+      if (definition.kind === "single") {
+        await sendBase(ctx, data, options);
+        return;
       }
-      const payload = messages.map((item) => ({
-        body: item.body,
-        ...toCloudflareSendOptions(item.options)
-      }));
-      await binding.sendBatch(payload);
-    };
-    const baseHandle = {
-      async send(ctx, data, options) {
-        if (definition.kind === "single") {
-          await sendBase(ctx, data, options);
-          return;
-        }
-        await sendBase(ctx, { _job: "__default", data }, options);
-      },
-      async sendBatch(ctx, messages, options) {
-        if (definition.kind === "single") {
-          await sendBatchBase(
-            ctx,
-            messages.map((message) => ({
-              body: message.data,
-              options: mergeSendOptions(message, options)
-            }))
-          );
-          return;
-        }
+      await sendBase(ctx, { _job: "__default", data }, options);
+    },
+    async sendBatch(ctx, messages, options) {
+      if (definition.kind === "single") {
         await sendBatchBase(
           ctx,
           messages.map((message) => ({
-            body: { _job: "__default", data: message.data },
+            body: message.data,
             options: mergeSendOptions(message, options)
           }))
         );
+        return;
       }
-    };
-    if (definition.kind === "multi") {
-      for (const jobName of Object.keys(definition.jobs)) {
-        baseHandle[jobName] = {
-          async send(ctx, data, options) {
-            await sendBase(ctx, { _job: jobName, data }, options);
-          },
-          async sendBatch(ctx, messages, options) {
-            await sendBatchBase(
-              ctx,
-              messages.map((message) => ({
-                body: { _job: jobName, data: message.data },
-                options: mergeSendOptions(message, options)
-              }))
-            );
-          }
-        };
-      }
+      await sendBatchBase(
+        ctx,
+        messages.map((message) => ({
+          body: { _job: "__default", data: message.data },
+          options: mergeSendOptions(message, options)
+        }))
+      );
     }
-    Object.defineProperty(baseHandle, kQueueInternals, {
-      enumerable: false,
-      configurable: false,
-      writable: false,
-      value: {
-        setBinding(name) {
-          bindingName = name;
-        },
-        getBinding() {
-          return bindingName;
-        },
-        getDefinition() {
-          return definition;
+  };
+  if (definition.kind === "multi") {
+    for (const jobName of Object.keys(definition.jobs)) {
+      baseHandle[jobName] = {
+        async send(ctx, data, options) {
+          await sendBase(ctx, { _job: jobName, data }, options);
         },
-        consume(batch, env, executionCtx) {
-          return consumeQueueDefinition(definition, batch, env, executionCtx);
+        async sendBatch(ctx, messages, options) {
+          await sendBatchBase(
+            ctx,
+            messages.map((message) => ({
+              body: { _job: jobName, data: message.data },
+              options: mergeSendOptions(message, options)
+            }))
+          );
         }
-      }
-    });
-    return baseHandle;
-  }
-  return defineQueue;
-}
-function toQueueDefinition(config) {
-  if (isSingleQueue(config)) {
-    if (isPullQueue(config)) {
-      if ("process" in config || "processBatch" in config) {
-        throw new Error('Queue config with consumer.type="http_pull" cannot define process/processBatch.');
-      }
-      return {
-        kind: "single",
-        mode: "pull",
-        config
       };
     }
-    if (hasProcess(config) && hasProcessBatch(config)) {
-      throw new Error("Queue config cannot define both process and processBatch.");
+  }
+  Object.defineProperty(baseHandle, kQueueInternals, {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: {
+      setBinding(name) {
+        bindingName = name;
+      },
+      getBinding() {
+        return bindingName;
+      },
+      getDefinition() {
+        return definition;
+      },
+      consume(batch, env, executionCtx) {
+        return consumeQueueDefinition(definition, batch, env, executionCtx);
+      }
     }
-    if (!hasProcess(config) && !hasProcessBatch(config)) {
-      throw new Error("Queue config must define one of process or processBatch in worker consumer mode.");
+  });
+  return baseHandle;
+}
+function toSingleQueueDefinition(config) {
+  if (isPullQueue(config)) {
+    if ("handler" in config || "batchHandler" in config) {
+      throw new Error('Queue config with consumer.type="http_pull" cannot define handler/batchHandler.');
     }
     return {
       kind: "single",
-      mode: "push",
+      mode: "pull",
       config
     };
   }
+  if (hasHandler(config) && hasBatchHandler(config)) {
+    throw new Error("Queue config cannot define both handler and batchHandler.");
+  }
+  if (!hasHandler(config) && !hasBatchHandler(config)) {
+    throw new Error("Queue config must define one of handler or batchHandler in worker consumer mode.");
+  }
+  return {
+    kind: "single",
+    mode: "push",
+    config
+  };
+}
+function toMultiQueueDefinition(config) {
   const shared = {
     retry: config.retry,
     retryDelay: config.retryDelay,
@@ -334,6 +355,14 @@ function toQueueDefinition(config) {
     if (RESERVED_MULTI_JOB_KEYS.has(key)) {
       continue;
     }
+    if (hasLegacyKeys(value)) {
+      throw new Error(
+        `Multi-job queue "${key}" uses legacy keys. Rename message->args and process/processBatch->handler/batchHandler.`
+      );
+    }
+    if (isPlainObject(value) && "batchHandler" in value) {
+      throw new Error(`Multi-job queue "${key}" cannot define batchHandler. Use handler per job.`);
+    }
     if (isJobConfig(value)) {
       jobs[key] = value;
     }
@@ -347,23 +376,56 @@ function toQueueDefinition(config) {
     shared
   };
 }
-function isSingleQueue(config) {
-  return "message" in config;
-}
 function isPullQueue(config) {
   return "consumer" in config && Boolean(config.consumer && config.consumer.type === "http_pull");
 }
-function hasProcess(config) {
-  return "process" in config && typeof config.process === "function";
+function hasHandler(config) {
+  return "handler" in config && typeof config.handler === "function";
 }
-function hasProcessBatch(config) {
-  return "processBatch" in config && typeof config.processBatch === "function";
+function hasBatchHandler(config) {
+  return "batchHandler" in config && typeof config.batchHandler === "function";
 }
 function isJobConfig(value) {
   if (!isPlainObject(value)) {
     return false;
   }
-  return "message" in value && "process" in value;
+  return "args" in value && "handler" in value;
+}
+function assertNoLegacySingleQueueKeys(config) {
+  if (!isPlainObject(config)) {
+    return;
+  }
+  const legacyKeys = [LEGACY_SCHEMA_KEY, ...LEGACY_SINGLE_HANDLER_KEYS].filter((key) => key in config);
+  if (legacyKeys.length === 0) {
+    return;
+  }
+  throw new Error(
+    `Queue config uses legacy keys (${legacyKeys.join(", ")}). Rename message->args, process->handler, processBatch->batchHandler.`
+  );
+}
+function assertNoLegacyMultiQueueKeys(config) {
+  const topLevelLegacyKeys = [LEGACY_SCHEMA_KEY, ...LEGACY_SINGLE_HANDLER_KEYS].filter((key) => key in config);
+  if (topLevelLegacyKeys.length > 0) {
+    throw new Error(
+      `Multi-job queue config uses legacy keys (${topLevelLegacyKeys.join(", ")}). Use defineQueues({ job: { args, handler } }).`
+    );
+  }
+  for (const [jobName, value] of Object.entries(config)) {
+    if (RESERVED_MULTI_JOB_KEYS.has(jobName) || !isPlainObject(value)) {
+      continue;
+    }
+    if (hasLegacyKeys(value)) {
+      throw new Error(
+        `Multi-job queue "${jobName}" uses legacy keys. Rename message->args and process/processBatch->handler/batchHandler.`
+      );
+    }
+  }
+}
+function hasLegacyKeys(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return LEGACY_SCHEMA_KEY in value || LEGACY_SINGLE_HANDLER_KEYS.some((key) => key in value);
 }
 
 // src/queue/define-worker.ts
@@ -390,8 +452,11 @@ function defineWorkerFactory() {
 
 // src/queue/create-sdk.ts
 function createSDK() {
+  const defineQueue = defineQueueFactory();
+  const defineQueues = defineQueuesFactory();
   return {
-    defineQueue: defineQueueFactory(),
+    defineQueue,
+    defineQueues,
     defineWorker: defineWorkerFactory()
   };
 }