@lunora/queue 0.0.0 → 1.0.0-alpha.10

package/dist/index.mjs

@@ -0,0 +1,6 @@
+export { createQueueCaptureSink, shouldCaptureQueue } from './packem_shared/createQueueCaptureSink-B8WE0eHf.mjs';
+export { createQueueContext } from './packem_shared/createQueueContext-D0XCdCsd.mjs';
+export { default as createQueues } from './packem_shared/createQueues-14-vSICK.mjs';
+export { defineQueue, isQueueDefinition, queueBindingName, queueDefaultName } from './packem_shared/defineQueue-D40gREfg.mjs';
+export { dispatchQueueBatch } from './packem_shared/dispatchQueueBatch-DSEWhEy8.mjs';
+export { createQueueRunContext } from './packem_shared/createQueueRunContext-C8jboCk6.mjs';

package/dist/packem_shared/createQueueCaptureSink-B8WE0eHf.mjs

@@ -0,0 +1,64 @@
+import { LunoraError } from '@lunora/errors';
+
+const RECORD_QUEUE_MESSAGE_OP = "__lunora_admin__:recordQueueMessage";
+const DEFAULT_ROOT_SHARD = "__root__";
+const DEV_ENVIRONMENT_PATTERN = /^(?:dev(?:elopment)?|local(?:host)?|test)$/iu;
+const ENVIRONMENT_VARS = ["CF_ENV", "ENVIRONMENT", "NODE_ENV", "WORKER_ENV"];
+const CAPTURE_FETCH_TIMEOUT_MS = 5e3;
+const shouldCaptureQueue = (env) => {
+  const flag = env["LUNORA_QUEUE_CAPTURE"];
+  if (typeof flag === "string") {
+    return flag === "1" || flag.toLowerCase() === "true";
+  }
+  return ENVIRONMENT_VARS.some((key) => {
+    const value = env[key];
+    return typeof value === "string" && DEV_ENVIRONMENT_PATTERN.test(value);
+  });
+};
+const createQueueCaptureSink = (env, options = {}) => {
+  const rootShard = options.rootShard ?? DEFAULT_ROOT_SHARD;
+  return async (messages) => {
+    if (messages.length === 0) {
+      return;
+    }
+    const binding = env["SHARD"];
+    const adminToken = typeof env["LUNORA_ADMIN_TOKEN"] === "string" ? env["LUNORA_ADMIN_TOKEN"] : void 0;
+    if (binding === void 0 || adminToken === void 0) {
+      return;
+    }
+    let namespace = binding;
+    if (options.jurisdiction !== void 0) {
+      if (typeof binding.jurisdiction !== "function") {
+        throw new TypeError(
+          `@lunora/queue: Durable Object namespace does not support jurisdiction("${options.jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`
+        );
+      }
+      namespace = binding.jurisdiction(options.jurisdiction);
+    }
+    const stub = namespace.get(namespace.idFromName(rootShard));
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, CAPTURE_FETCH_TIMEOUT_MS);
+    try {
+      const response = await stub.fetch("https://shard.internal/rpc", {
+        body: JSON.stringify({ args: { messages }, functionPath: RECORD_QUEUE_MESSAGE_OP }),
+        headers: { authorization: `Bearer ${adminToken}`, "content-type": "application/json" },
+        method: "POST",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new LunoraError(
+          "INTERNAL",
+          `@lunora/queue: capture write to the root shard failed (${String(response.status)} ${response.statusText})${detail === "" ? "" : `: ${detail}`}`
+        );
+      }
+      await response.body?.cancel();
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+};
+
+export { createQueueCaptureSink, shouldCaptureQueue };

package/dist/packem_shared/createQueueContext-D0XCdCsd.mjs

@@ -0,0 +1,14 @@
+import createQueues from './createQueues-14-vSICK.mjs';
+
+const createQueueContext = (env, specs) => {
+  const bindings = {};
+  for (const spec of specs) {
+    const binding = env[spec.binding];
+    if (binding && typeof binding.send === "function" && typeof binding.sendBatch === "function") {
+      bindings[spec.exportName] = binding;
+    }
+  }
+  return createQueues({ bindings });
+};
+
+export { createQueueContext };

package/dist/packem_shared/createQueueRunContext-C8jboCk6.mjs

@@ -0,0 +1,94 @@
+import { LunoraError } from '@lunora/errors';
+
+const createDispatchLogger = (prefix) => {
+  return {
+    debug: (message, ...rest) => {
+      console.debug(prefix, message, ...rest);
+    },
+    error: (message, ...rest) => {
+      console.error(prefix, message, ...rest);
+    },
+    info: (message, ...rest) => {
+      console.info(prefix, message, ...rest);
+    },
+    warn: (message, ...rest) => {
+      console.warn(prefix, message, ...rest);
+    }
+  };
+};
+
+const SCHEDULER_DISPATCH_PATH = "/_lunora/scheduler/dispatch";
+const trimTrailingSlashes = (value) => {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+  return value.slice(0, end);
+};
+const toDispatchError = (label, status, rawBody) => {
+  try {
+    const parsed = JSON.parse(rawBody);
+    const errorBody = parsed?.error;
+    if (typeof errorBody === "object" && errorBody !== null && typeof errorBody.code === "string") {
+      const { code, data, message } = errorBody;
+      return new LunoraError(code, typeof message === "string" ? message : void 0, { data, status });
+    }
+  } catch {
+  }
+  return new LunoraError("INTERNAL", `${label}: function dispatch failed (${String(status)}): ${rawBody}`, { status });
+};
+const createDispatchRunner = (options) => {
+  const { label } = options;
+  const globalFetch = globalThis.fetch;
+  const fetchImpl = options.fetchImpl ?? (typeof globalFetch === "function" ? globalFetch.bind(globalThis) : void 0);
+  return async (function_, args, runOptions = {}) => {
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError(`${label}: no fetch implementation available — pass fetchImpl or run on a platform with global fetch`);
+    }
+    const origin = options.env.LUNORA_ORIGIN_URL;
+    if (typeof origin !== "string" || origin.length === 0) {
+      throw new LunoraError("INTERNAL", `${label}: \`LUNORA_ORIGIN_URL\` must be set on the Worker env so a handler can call back into Lunora functions`);
+    }
+    const token = options.env.LUNORA_ADMIN_TOKEN;
+    if (typeof token !== "string" || token.length === 0) {
+      throw new LunoraError("INTERNAL", `${label}: \`LUNORA_ADMIN_TOKEN\` must be set on the Worker env to authenticate function dispatch`);
+    }
+    const url = `${trimTrailingSlashes(origin)}${SCHEDULER_DISPATCH_PATH}`;
+    const headers = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+    if (options.identity?.userId !== void 0) {
+      headers["x-lunora-userid"] = options.identity.userId;
+    }
+    if (options.identity?.claims !== void 0) {
+      headers["x-lunora-identity"] = JSON.stringify(options.identity.claims);
+    }
+    const response = await fetchImpl(url, {
+      body: JSON.stringify({ args: args ?? {}, functionPath: function_.__lunoraRef, shardKey: runOptions.shardKey }),
+      headers,
+      method: "POST"
+    });
+    if (!response.ok) {
+      throw toDispatchError(label, response.status, await response.text());
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new LunoraError("INTERNAL", `${label}: function dispatch returned a non-JSON body (${String(response.status)}): ${text}`, {
+        status: response.status
+      });
+    }
+  };
+};
+
+const createQueueRunContext = (options) => {
+  return {
+    env: options.env,
+    log: createDispatchLogger(`[queue:${options.exportName}]`),
+    run: createDispatchRunner({ env: options.env, fetchImpl: options.fetchImpl, label: "@lunora/queue" })
+  };
+};
+
+export { createQueueRunContext };

package/dist/packem_shared/createQueues-14-vSICK.mjs

@@ -0,0 +1,33 @@
+const producerFor = (binding) => {
+  return {
+    send: async (body, options) => {
+      await binding.send(body, options);
+    },
+    sendBatch: async (messages, options) => {
+      await binding.sendBatch(messages, options);
+    }
+  };
+};
+const createQueues = (options) => {
+  const bindings = options.bindings ?? {};
+  const producers = /* @__PURE__ */ Object.create(null);
+  for (const [exportName, binding] of Object.entries(bindings)) {
+    producers[exportName] = producerFor(binding);
+  }
+  const known = Object.keys(producers);
+  const missing = (name) => {
+    const suffix = known.length === 0 ? "no queues are declared" : `known queues: ${known.join(", ")}`;
+    const error = () => Promise.reject(new Error(`@lunora/queue: no queue named "${name}" (${suffix})`));
+    return { send: error, sendBatch: error };
+  };
+  return /* @__PURE__ */ new Proxy(producers, {
+    get(target, property) {
+      if (typeof property !== "string") {
+        return void 0;
+      }
+      return Object.hasOwn(target, property) ? target[property] : missing(property);
+    }
+  });
+};
+
+export { createQueues as default };

package/dist/packem_shared/defineQueue-D40gREfg.mjs

@@ -0,0 +1,18 @@
+const queueBindingName = (exportName) => `QUEUE_${exportName.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g, "_").toUpperCase()}`;
+const queueDefaultName = (exportName) => exportName.replaceAll(/(?<=[a-z0-9])(?=[A-Z])/g, "-").toLowerCase();
+const defineQueue = (config) => {
+  const mode = config.mode ?? "push";
+  if (mode !== "push" && mode !== "pull") {
+    throw new TypeError(`defineQueue: \`mode\` must be "push" or "pull" (got ${JSON.stringify(config.mode)})`);
+  }
+  if (mode === "push" && typeof config.handler !== "function") {
+    throw new TypeError('defineQueue: `handler` must be a function for a push consumer (omit it only when `mode: "pull"`)');
+  }
+  if (config.name !== void 0 && (typeof config.name !== "string" || config.name.length === 0)) {
+    throw new TypeError("defineQueue: `name` must be a non-empty string when provided");
+  }
+  return { ...config, isLunoraQueue: true, mode };
+};
+const isQueueDefinition = (value) => typeof value === "object" && value !== null && value.isLunoraQueue === true;
+
+export { defineQueue, isQueueDefinition, queueBindingName, queueDefaultName };

package/dist/packem_shared/dispatchQueueBatch-DSEWhEy8.mjs

@@ -0,0 +1,132 @@
+import { LunoraError } from '@lunora/errors';
+import { createQueueRunContext } from './createQueueRunContext-C8jboCk6.mjs';
+
+const DEFAULT_MAX_RETRIES = 3;
+const timestampToMs = (value) => {
+  if (value instanceof Date) {
+    return value.getTime();
+  }
+  const asNumber = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(asNumber) ? asNumber : 0;
+};
+const instrumentBatch = (batch) => {
+  const dispositions = /* @__PURE__ */ new Map();
+  const originals = batch.messages;
+  const wrappedMessages = originals.map((message) => {
+    return {
+      ack: () => {
+        dispositions.set(message, "ack");
+        message.ack();
+      },
+      get attempts() {
+        return message.attempts;
+      },
+      get body() {
+        return message.body;
+      },
+      get id() {
+        return message.id;
+      },
+      retry: (options) => {
+        dispositions.set(message, "retry");
+        message.retry(options);
+      },
+      get timestamp() {
+        return message.timestamp;
+      }
+    };
+  });
+  const fillUndecided = (outcome) => {
+    for (const message of originals) {
+      if (!dispositions.has(message)) {
+        dispositions.set(message, outcome);
+      }
+    }
+  };
+  const wrappedBatch = {
+    ackAll: () => {
+      fillUndecided("ack");
+      batch.ackAll();
+    },
+    messages: wrappedMessages,
+    queue: batch.queue,
+    retryAll: (options) => {
+      fillUndecided("retry");
+      batch.retryAll(options);
+    }
+  };
+  return { dispositions, originals, wrappedBatch };
+};
+const describeThrownError = (handlerError) => {
+  if (handlerError instanceof Error) {
+    return handlerError.message;
+  }
+  if (typeof handlerError === "string") {
+    return handlerError;
+  }
+  if (handlerError !== null && typeof handlerError === "object") {
+    try {
+      return JSON.stringify(handlerError);
+    } catch {
+      return "[unserializable thrown value]";
+    }
+  }
+  return String(handlerError);
+};
+const buildCaptureRecords = (harness, entry, queue, threw, handlerError) => {
+  const errorMessage = threw ? describeThrownError(handlerError) : void 0;
+  const maxRetries = typeof entry.definition.maxRetries === "number" ? entry.definition.maxRetries : DEFAULT_MAX_RETRIES;
+  return harness.originals.map((message) => {
+    const decided = harness.dispositions.get(message);
+    const outcome = decided ?? (threw ? "error" : "ack");
+    const attempts = typeof message.attempts === "number" ? message.attempts : 1;
+    return {
+      attempts,
+      body: message.body,
+      deadLettered: outcome !== "ack" && attempts > maxRetries,
+      error: outcome === "error" ? errorMessage : void 0,
+      exportName: entry.exportName,
+      messageId: message.id,
+      outcome,
+      queue,
+      timestamp: timestampToMs(message.timestamp)
+    };
+  });
+};
+const dispatchQueueBatch = async (batch, registry, options) => {
+  const entry = Object.hasOwn(registry, batch.queue) ? registry[batch.queue] : void 0;
+  if (entry === void 0) {
+    const known = Object.keys(registry);
+    const suffix = known.length === 0 ? "no push queues are declared" : `known push queues: ${known.join(", ")}`;
+    throw new LunoraError("INTERNAL", `@lunora/queue: received a batch for queue "${batch.queue}" but no push handler is registered (${suffix})`);
+  }
+  const { handler } = entry.definition;
+  if (typeof handler !== "function") {
+    throw new TypeError(`@lunora/queue: queue "${batch.queue}" (${entry.exportName}) has no push handler — it is declared as a pull consumer`);
+  }
+  const context = createQueueRunContext({ env: options.env, exportName: entry.exportName, fetchImpl: options.fetchImpl });
+  if (options.capture === void 0) {
+    await handler(context, batch);
+    return;
+  }
+  const harness = instrumentBatch(batch);
+  let threw = false;
+  let handlerError;
+  try {
+    await handler(context, harness.wrappedBatch);
+  } catch (error) {
+    threw = true;
+    handlerError = error;
+  }
+  try {
+    const records = buildCaptureRecords(harness, entry, batch.queue, threw, handlerError);
+    await options.capture(records);
+  } catch (captureError) {
+    console.warn("@lunora/queue: capture sink failed (delivery unaffected):", captureError);
+  }
+  if (threw) {
+    throw handlerError;
+  }
+};
+
+export { dispatchQueueBatch };

package/package.json

@@ -1,19 +1,52 @@
 {
   "name": "@lunora/queue",
-  "version": "0.0.0",
-  "description": "Placeholder to reserve the npm name. Real releases are published from CI — install the latest version.",
+  "version": "1.0.0-alpha.10",
+  "description": "Cloudflare Queues for Lunora: defineQueue producers + consumers, the ctx.queues surface, and the generated queue() worker handler",
+  "keywords": [
+    "background-jobs",
+    "cloudflare",
+    "lunora",
+    "messaging",
+    "queues",
+    "workers"
+  ],
+  "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
   "license": "FSL-1.1-Apache-2.0",
   "author": {
     "name": "Daniel Bannert",
     "email": "d.bannert@anolilab.de"
   },
-  "homepage": "https://lunora.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/anolilab/lunora.git",
     "directory": "packages/queue"
   },
+  "files": [
+    "./dist",
+    "README.md",
+    "LICENSE.md",
+    "__assets__"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@lunora/errors": "1.0.0-alpha.8"
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
   }
-}
+}