@dotpress/events 0.0.0-stage → 2.0.0-alpha.1

package/dist/index.js

@@ -0,0 +1,701 @@
+import {
+  checkLogger,
+  silentLogger
+} from "./chunk-E4NMMZMY.js";
+import {
+  EventEmitError,
+  EventPayloadError,
+  EventsError,
+  PartialSendError
+} from "./chunk-NCQ4ZTNB.js";
+
+// src/define.ts
+var NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var checkName = (prefix, kind, name) => {
+  if (typeof name !== "string" || !NAME.test(name)) {
+    throw new TypeError(
+      `${prefix}: ${kind} must have 1 to 128 letters, digits, ".", "_", ":" or "-", starting with a letter or a digit.`
+    );
+  }
+};
+var checkTransport = (prefix, transport) => {
+  if (transport !== void 0 && (typeof transport !== "string" || transport === "")) {
+    throw new TypeError(`${prefix}: transport must be a non-empty string.`);
+  }
+};
+var checkKeys = (prefix, options, allowed) => {
+  if (!isRecord(options)) throw new TypeError(`${prefix}: expected an object.`);
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`${prefix}: unknown option "${key}".`);
+    }
+  }
+  return options;
+};
+var events = /* @__PURE__ */ new WeakSet();
+var loaders = /* @__PURE__ */ new WeakMap();
+var isEvent = (value) => (
+  // WeakSet.has() returns false for other values.
+  events.has(value)
+);
+var loaderOf = (listener) => loaders.get(listener);
+var defineEvent = (options) => {
+  const name = options?.name;
+  const prefix = typeof name === "string" ? `Invalid event "${name}"` : "Invalid event";
+  const values = checkKeys(
+    prefix,
+    options,
+    /* @__PURE__ */ new Set(["name", "schema", "transport"])
+  );
+  checkName(prefix, "name", name);
+  if (typeof values.schema?.safeParseAsync !== "function") {
+    throw new TypeError(`${prefix}: schema must be a Zod schema.`);
+  }
+  checkTransport(prefix, values.transport);
+  const event = Object.freeze({
+    name,
+    schema: values.schema,
+    transport: values.transport
+  });
+  events.add(event);
+  return event;
+};
+var defineListener = (event, options) => {
+  const name = options?.name;
+  const prefix = typeof name === "string" ? `Invalid listener "${name}"` : "Invalid listener";
+  if (!isEvent(event)) {
+    throw new TypeError(
+      `${prefix}: expected an event created by defineEvent().`
+    );
+  }
+  const values = checkKeys(
+    prefix,
+    options,
+    /* @__PURE__ */ new Set(["name", "transport", "handle", "load"])
+  );
+  checkName(prefix, "name", name);
+  checkTransport(prefix, values.transport);
+  const { handle, load } = values;
+  if (handle === void 0 === (load === void 0)) {
+    throw new TypeError(`${prefix}: set exactly one of handle and load.`);
+  }
+  if (typeof (handle ?? load) !== "function") {
+    throw new TypeError(
+      `${prefix}: ${handle === void 0 ? "load" : "handle"} must be a function.`
+    );
+  }
+  const listener = Object.freeze({
+    name,
+    event,
+    transport: values.transport
+  });
+  let loading;
+  loaders.set(
+    listener,
+    handle === void 0 ? () => (loading ??= load().then((module) => {
+      const loaded = module?.default;
+      if (typeof loaded !== "function") {
+        throw new TypeError(
+          `Listener "${name}": load() must resolve to a module whose default export is the handler.`
+        );
+      }
+      return loaded;
+    })).catch((error) => {
+      loading = void 0;
+      throw error;
+    }) : () => Promise.resolve(handle)
+  );
+  return listener;
+};
+
+// src/envelope.ts
+var hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+var messageId = async (emissionId, listener) => {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(`${emissionId}
+${listener}`)
+  );
+  const bytes = new Uint8Array(digest.slice(0, 16));
+  bytes[6] = bytes[6] & 15 | 128;
+  bytes[8] = bytes[8] & 63 | 128;
+  const value = hex(bytes);
+  return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+};
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var STRING_FIELDS = [
+  "id",
+  "emissionId",
+  "event",
+  "listener",
+  "emittedAt"
+];
+var parseEnvelope = (message) => {
+  let value = message;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return { problem: "the message is not JSON" };
+    }
+  }
+  if (!isRecord2(value)) return { problem: "the message is not an object" };
+  if (value.v !== 1) {
+    return {
+      problem: `unsupported envelope version ${JSON.stringify(value.v)}`
+    };
+  }
+  for (const field of STRING_FIELDS) {
+    if (typeof value[field] !== "string" || value[field] === "") {
+      return { problem: `the envelope has no ${field}` };
+    }
+  }
+  if (!("payload" in value)) return { problem: "the envelope has no payload" };
+  const { metadata } = value;
+  if (!isRecord2(metadata) || !Object.values(metadata).every((item) => typeof item === "string")) {
+    return { problem: "the metadata of the envelope is not a string map" };
+  }
+  return { envelope: value };
+};
+
+// src/transport.ts
+var isTransport = (value) => typeof value?.send === "function" && typeof value.kind === "string";
+
+// src/worker.ts
+var OPTIONS = /* @__PURE__ */ new Set(["listeners", "logger", "onFailure", "maxAttempts"]);
+var listenersByName = (label, listeners) => {
+  if (!Array.isArray(listeners)) {
+    throw new TypeError(`${label}: listeners must be a list.`);
+  }
+  const byName = /* @__PURE__ */ new Map();
+  for (const listener of listeners) {
+    if (!loaderOf(listener)) {
+      throw new TypeError(
+        `${label}: listeners must be created by defineListener().`
+      );
+    }
+    const { name } = listener;
+    if (byName.has(name)) {
+      throw new TypeError(`${label}: two listeners are named "${name}".`);
+    }
+    byName.set(name, listener);
+  }
+  return byName;
+};
+var describe = (error) => error instanceof Error ? error.message : String(error);
+var createWorker = (options) => {
+  const label = "createWorker()";
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(`${label}: expected an object of options.`);
+  }
+  for (const key of Object.keys(options)) {
+    if (!OPTIONS.has(key)) {
+      throw new TypeError(`${label}: unknown option "${key}".`);
+    }
+  }
+  const listeners = listenersByName(label, options.listeners);
+  const logger = options.logger === void 0 ? silentLogger : checkLogger(label, options.logger);
+  const { onFailure, maxAttempts } = options;
+  if (onFailure !== void 0 && typeof onFailure !== "function") {
+    throw new TypeError(`${label}: onFailure must be a function.`);
+  }
+  if (maxAttempts !== void 0 && (!Number.isInteger(maxAttempts) || maxAttempts < 1)) {
+    throw new TypeError(`${label}: maxAttempts must be a positive integer.`);
+  }
+  const fail = async (error, info) => {
+    const fields = {
+      event: info.envelope?.event,
+      listener: info.envelope?.listener,
+      messageId: info.envelope?.id,
+      attempt: info.attempt,
+      reason: info.reason,
+      error: describe(error)
+    };
+    if (info.final) {
+      logger.error(fields, "Event listener failed, the message is not retried");
+    } else {
+      logger.warn(fields, "Event listener failed, the message is retried");
+    }
+    if (onFailure) {
+      try {
+        await onFailure(error, info);
+      } catch (hookError) {
+        logger.error(
+          { ...fields, hookError: describe(hookError) },
+          "onFailure hook failed"
+        );
+      }
+    }
+    return info.reason === "listener-error" ? { status: "retry", error } : { status: "dead", reason: info.reason, error };
+  };
+  const handle = async (message, handleOptions = {}) => {
+    const attempt = handleOptions.attempt ?? 1;
+    const parsed = parseEnvelope(message);
+    if ("problem" in parsed) {
+      return fail(new Error(`Invalid message: ${parsed.problem}.`), {
+        envelope: void 0,
+        reason: "invalid-envelope",
+        attempt,
+        final: true
+      });
+    }
+    const { envelope } = parsed;
+    const dead = (reason, text) => fail(new Error(text), { envelope, reason, attempt, final: true });
+    const listener = listeners.get(envelope.listener);
+    if (!listener) {
+      return dead(
+        "unknown-listener",
+        `Unknown listener "${envelope.listener}": this worker runs ${[...listeners.keys()].join(", ") || "no listener"}.`
+      );
+    }
+    if (listener.event.name !== envelope.event) {
+      return dead(
+        "invalid-envelope",
+        `Listener "${listener.name}" listens to "${listener.event.name}", not "${envelope.event}".`
+      );
+    }
+    let result;
+    try {
+      result = await listener.event.schema.safeParseAsync(envelope.payload);
+    } catch (error) {
+      return fail(error, {
+        envelope,
+        reason: "listener-error",
+        attempt,
+        final: maxAttempts !== void 0 && attempt >= maxAttempts
+      });
+    }
+    if (!result.success) {
+      const issues = result.error.issues.map(
+        ({ path, message: text }) => path.length > 0 ? `${path.map(String).join(".")}: ${text}` : text
+      ).join("; ");
+      return dead(
+        "invalid-payload",
+        `Invalid payload for event "${envelope.event}": ${issues}`
+      );
+    }
+    const context = {
+      payload: result.data,
+      event: envelope.event,
+      listener: envelope.listener,
+      id: envelope.id,
+      emissionId: envelope.emissionId,
+      attempt,
+      emittedAt: new Date(envelope.emittedAt),
+      metadata: envelope.metadata,
+      logger
+    };
+    try {
+      const handler = await loaderOf(listener)();
+      await handler(context);
+    } catch (error) {
+      return fail(error, {
+        envelope,
+        reason: "listener-error",
+        attempt,
+        final: maxAttempts !== void 0 && attempt >= maxAttempts
+      });
+    }
+    logger.debug?.(
+      {
+        event: envelope.event,
+        listener: envelope.listener,
+        messageId: envelope.id,
+        attempt
+      },
+      "Event listener succeeded"
+    );
+    return { status: "success" };
+  };
+  return Object.freeze({
+    listeners: Object.freeze([...listeners.keys()]),
+    handle
+  });
+};
+
+// src/bus.ts
+var OPTIONS2 = /* @__PURE__ */ new Set([
+  "listeners",
+  "logger",
+  "onFailure",
+  "transport",
+  "transports"
+]);
+var METADATA_KEY = /^[A-Za-z0-9._-]{1,128}$/;
+var LINE_BREAK = /[\r\n]/;
+var checkMetadata = (label, metadata) => {
+  if (metadata === void 0) return {};
+  if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+    throw new TypeError(`${label}: metadata must be an object.`);
+  }
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!METADATA_KEY.test(key)) {
+      throw new TypeError(
+        `${label}: metadata keys must have 1 to 128 letters, digits, ".", "_" or "-": ${JSON.stringify(key)}.`
+      );
+    }
+    if (typeof value !== "string" || LINE_BREAK.test(value)) {
+      throw new TypeError(
+        `${label}: metadata.${key} must be a string on one line.`
+      );
+    }
+  }
+  return metadata;
+};
+var routeOf = (listener) => listener.transport ?? listener.event.transport ?? "default";
+var checkEmission = async (event, payload, emitOptions, contextMetadata) => {
+  if (!isEvent(event)) {
+    throw new TypeError("emit(): expected an event created by defineEvent().");
+  }
+  const emitLabel = `emit("${event.name}")`;
+  const { delay, metadata } = emitOptions ?? {};
+  if (delay !== void 0 && (!Number.isInteger(delay) || delay < 0)) {
+    throw new TypeError(
+      `${emitLabel}: delay must be a non-negative integer (seconds).`
+    );
+  }
+  const checked = {
+    ...contextMetadata,
+    ...checkMetadata(emitLabel, metadata)
+  };
+  let json;
+  try {
+    json = JSON.parse(JSON.stringify(payload) ?? "null");
+  } catch (error) {
+    throw new EventPayloadError(event.name, [
+      {
+        path: [],
+        message: `the payload cannot be serialized as JSON (${error instanceof Error ? error.message : String(error)})`
+      }
+    ]);
+  }
+  const result = await event.schema.safeParseAsync(json);
+  if (!result.success) {
+    throw new EventPayloadError(
+      event.name,
+      result.error.issues.map(({ path, message }) => ({
+        path: path.map((key) => typeof key === "symbol" ? String(key) : key),
+        message
+      }))
+    );
+  }
+  return { event, json, delay, metadata: checked };
+};
+var createEventBus = (options) => {
+  const label = "createEventBus()";
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(`${label}: expected an object of options.`);
+  }
+  for (const key of Object.keys(options)) {
+    if (!OPTIONS2.has(key)) {
+      throw new TypeError(`${label}: unknown option "${key}".`);
+    }
+  }
+  const listeners = listenersByName(label, options.listeners);
+  const logger = options.logger === void 0 ? silentLogger : checkLogger(label, options.logger);
+  const { onFailure } = options;
+  if (onFailure !== void 0 && typeof onFailure !== "function") {
+    throw new TypeError(`${label}: onFailure must be a function.`);
+  }
+  if (options.transport === void 0 === (options.transports === void 0)) {
+    throw new TypeError(
+      `${label}: set exactly one of transport and transports.`
+    );
+  }
+  const transports = new Map(
+    options.transport === void 0 ? Object.entries(options.transports ?? {}).filter(
+      ([, transport]) => transport !== void 0
+    ) : [["default", options.transport]]
+  );
+  if (options.transports !== void 0 && (typeof options.transports !== "object" || options.transports === null)) {
+    throw new TypeError(`${label}: transports must be an object.`);
+  }
+  for (const [name, transport] of transports) {
+    if (!isTransport(transport)) {
+      throw new TypeError(
+        `${label}: the "${name}" transport must have a kind and a send() method.`
+      );
+    }
+  }
+  const routed = /* @__PURE__ */ new Map();
+  for (const listener of listeners.values()) {
+    const route = routeOf(listener);
+    if (!transports.has(route)) {
+      throw new TypeError(
+        `${label}: listener "${listener.name}" (event "${listener.event.name}") uses the "${route}" transport, which is not configured.`
+      );
+    }
+    routed.set(route, [...routed.get(route) ?? [], listener]);
+  }
+  for (const [name, transport] of transports) {
+    transport.bind?.(
+      createWorker({
+        listeners: routed.get(name) ?? [],
+        logger,
+        onFailure,
+        maxAttempts: transport.maxAttempts
+      })
+    );
+  }
+  const listenersOf = (event) => [...listeners.values()].filter((listener) => listener.event.name === event);
+  const create = (context) => {
+    const emit = async (event, payload, emitOptions = {}) => {
+      const { json, delay, metadata } = await checkEmission(
+        event,
+        payload,
+        emitOptions,
+        context.metadata
+      );
+      const emissionId = crypto.randomUUID();
+      const targets = listenersOf(event.name);
+      if (targets.length === 0) {
+        context.logger.debug?.(
+          { event: event.name, emissionId },
+          "Event emitted without listeners"
+        );
+        return { emissionId, messages: [] };
+      }
+      const base = {
+        v: 1,
+        emissionId,
+        event: event.name,
+        payload: json,
+        emittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        metadata
+      };
+      const messages = [];
+      for (const listener of targets) {
+        const id = await messageId(emissionId, listener.name);
+        messages.push({
+          ref: { id, listener: listener.name, transport: routeOf(listener) },
+          envelope: { ...base, id, listener: listener.name }
+        });
+      }
+      const groups = /* @__PURE__ */ new Map();
+      for (const message of messages) {
+        const { transport } = message.ref;
+        groups.set(transport, [...groups.get(transport) ?? [], message]);
+      }
+      const sent = [];
+      const failed = [];
+      await Promise.all(
+        [...groups].map(async ([name, group]) => {
+          try {
+            await transports.get(name).send(
+              group.map(({ envelope }) => envelope),
+              { delay }
+            );
+            for (const { ref } of group) sent.push(ref);
+          } catch (error) {
+            const partial = error instanceof PartialSendError ? new Map(error.failed.map((item) => [item.id, item.error])) : void 0;
+            for (const { ref } of group) {
+              if (partial && !partial.has(ref.id)) sent.push(ref);
+              else failed.push({ ...ref, error: partial?.get(ref.id) ?? error });
+            }
+          }
+        })
+      );
+      const order = (refs) => refs.sort(
+        (a, b) => targets.findIndex(({ name }) => name === a.listener) - targets.findIndex(({ name }) => name === b.listener)
+      );
+      if (failed.length > 0) {
+        throw new EventEmitError(event.name, order(sent), order(failed));
+      }
+      context.logger.info(
+        { event: event.name, emissionId, messages: sent.length },
+        "Event emitted"
+      );
+      return {
+        emissionId,
+        messages: order(messages.map(({ ref }) => ref))
+      };
+    };
+    return Object.freeze({
+      emit,
+      withContext: ({ logger: other, metadata } = {}) => create({
+        logger: other === void 0 ? context.logger : checkLogger("withContext()", other),
+        metadata: {
+          ...context.metadata,
+          ...checkMetadata("withContext()", metadata)
+        }
+      })
+    });
+  };
+  return create({ logger, metadata: {} });
+};
+
+// src/fake.ts
+var createFakeEventBus = () => {
+  const emitted = [];
+  const create = (metadata) => {
+    const emit = async (event, payload, options) => {
+      const checked = await checkEmission(event, payload, options, metadata);
+      const emissionId = crypto.randomUUID();
+      emitted.push(
+        Object.freeze({
+          emissionId,
+          event: checked.event.name,
+          payload: checked.json,
+          delay: checked.delay,
+          metadata: Object.freeze(checked.metadata),
+          emittedAt: /* @__PURE__ */ new Date()
+        })
+      );
+      return { emissionId, messages: [] };
+    };
+    return Object.freeze({
+      emit,
+      withContext: ({ logger, metadata: added } = {}) => {
+        if (logger !== void 0) checkLogger("withContext()", logger);
+        return create({
+          ...metadata,
+          ...checkMetadata("withContext()", added)
+        });
+      }
+    });
+  };
+  const root = create({});
+  return Object.freeze({
+    ...root,
+    emitted,
+    clear: () => {
+      emitted.length = 0;
+    }
+  });
+};
+
+// src/start-worker.ts
+var startWorker = (worker, source, options = {}) => {
+  const label = "startWorker()";
+  if (typeof worker?.handle !== "function") {
+    throw new TypeError(
+      `${label}: expected a worker created by createWorker().`
+    );
+  }
+  if (typeof source?.consume !== "function") {
+    throw new TypeError(`${label}: expected a source with a consume() method.`);
+  }
+  const logger = options.logger === void 0 ? silentLogger : checkLogger(label, options.logger);
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  options.signal?.addEventListener("abort", stop, { once: true });
+  if (options.signal?.aborted) stop();
+  logger.info(
+    { source: source.kind, listeners: worker.listeners },
+    "Event worker started"
+  );
+  const done = source.consume(worker, { signal: controller.signal, logger }).finally(() => {
+    options.signal?.removeEventListener("abort", stop);
+    logger.info({ source: source.kind }, "Event worker stopped");
+  });
+  return {
+    stop: () => {
+      stop();
+      return done;
+    },
+    done
+  };
+};
+
+// src/transports/memory.ts
+var createMemoryTransport = (options = {}) => {
+  const label = "createMemoryTransport()";
+  const {
+    maxAttempts = 3,
+    retryDelay = (attempt) => 100 * 2 ** (attempt - 1)
+  } = options ?? {};
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new TypeError(`${label}: maxAttempts must be a positive integer.`);
+  }
+  if (typeof retryDelay !== "function") {
+    throw new TypeError(`${label}: retryDelay must be a function.`);
+  }
+  const sent = [];
+  let worker;
+  let pending = 0;
+  const idle = [];
+  const settle = () => {
+    pending -= 1;
+    if (pending === 0) {
+      for (const resolve of idle.splice(0)) resolve();
+    }
+  };
+  const schedule = (json, attempt, delayMs) => {
+    pending += 1;
+    setTimeout(() => {
+      void (async () => {
+        const result = await worker.handle(json, { attempt });
+        if (result.status === "retry" && attempt < maxAttempts) {
+          schedule(json, attempt + 1, retryDelay(attempt));
+        }
+        settle();
+      })();
+    }, delayMs);
+  };
+  return {
+    kind: "memory",
+    maxAttempts,
+    sent,
+    bind: (bound) => {
+      worker = bound;
+    },
+    send: async (envelopes, { delay }) => {
+      if (!worker) {
+        throw new Error("The memory transport is not used by an event bus.");
+      }
+      for (const envelope of envelopes) {
+        const json = JSON.stringify(envelope);
+        sent.push(JSON.parse(json));
+        schedule(json, 1, (delay ?? 0) * 1e3);
+      }
+    },
+    drain: () => pending === 0 ? Promise.resolve() : new Promise((resolve) => {
+      idle.push(resolve);
+    }),
+    clear: () => {
+      sent.length = 0;
+    }
+  };
+};
+
+// src/transports/sync.ts
+var createSyncTransport = () => {
+  let worker;
+  return {
+    kind: "sync",
+    maxAttempts: 1,
+    bind: (bound) => {
+      worker = bound;
+    },
+    send: async (envelopes) => {
+      if (!worker) {
+        throw new Error("The sync transport is not used by an event bus.");
+      }
+      const failed = [];
+      for (const envelope of envelopes) {
+        const result = await worker.handle(envelope, { attempt: 1 });
+        if (result.status !== "success") {
+          failed.push({ id: envelope.id, error: result.error });
+        }
+      }
+      if (failed.length > 0) throw new PartialSendError(failed);
+    }
+  };
+};
+export {
+  EventEmitError,
+  EventPayloadError,
+  EventsError,
+  PartialSendError,
+  createEventBus,
+  createFakeEventBus,
+  createMemoryTransport,
+  createSyncTransport,
+  createWorker,
+  defineEvent,
+  defineListener,
+  parseEnvelope,
+  startWorker
+};
+//# sourceMappingURL=index.js.map