@holo-js/broadcast 0.1.3

package/dist/chunk-742LGR5P.mjs

@@ -0,0 +1,528 @@
+import {
+  formatChannelPattern,
+  isBroadcastDefinition,
+  normalizeBroadcastDefinition
+} from "./chunk-QW6MHEWS.mjs";
+
+// src/runtime.ts
+import { randomUUID } from "crypto";
+import { holoBroadcastDefaults } from "@holo-js/config";
+
+// src/registry.ts
+var registeredDrivers = /* @__PURE__ */ new Map();
+function normalizeDriverName(name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("[Holo Broadcast] Broadcast driver names must be non-empty strings.");
+  }
+  return normalized;
+}
+function registerBroadcastDriver(name, driver, options = {}) {
+  const normalizedName = normalizeDriverName(name);
+  if (typeof driver?.send !== "function") {
+    throw new Error("[Holo Broadcast] Broadcast drivers must define a send(...) function.");
+  }
+  if (registeredDrivers.has(normalizedName) && options.replace !== true) {
+    throw new Error(`[Holo Broadcast] Broadcast driver "${normalizedName}" is already registered.`);
+  }
+  registeredDrivers.set(normalizedName, driver);
+  return Object.freeze({
+    name: normalizedName,
+    driver
+  });
+}
+function getRegisteredBroadcastDriver(name) {
+  return registeredDrivers.get(normalizeDriverName(name));
+}
+function listRegisteredBroadcastDrivers() {
+  return Object.freeze(
+    [...registeredDrivers.entries()].map(([name, driver]) => Object.freeze({ name, driver }))
+  );
+}
+function resetBroadcastDriverRegistry() {
+  registeredDrivers.clear();
+}
+var broadcastRegistryInternals = {
+  normalizeDriverName
+};
+
+// src/runtime.ts
+var HOLO_BROADCAST_DELIVER_JOB = "holo.broadcast.deliver";
+function getRuntimeState() {
+  const runtime = globalThis;
+  runtime.__holoBroadcastRuntime__ ??= {};
+  return runtime.__holoBroadcastRuntime__;
+}
+function getRuntimeBindings() {
+  return getRuntimeState().bindings ?? {};
+}
+function dynamicImport(specifier) {
+  return import(specifier);
+}
+async function loadQueueModule() {
+  const load = getRuntimeState().loadQueueModule ?? (async () => await dynamicImport("@holo-js/queue"));
+  try {
+    return await load();
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+      throw new Error("[@holo-js/broadcast] Queued or delayed broadcasts require @holo-js/queue to be installed.");
+    }
+    throw error;
+  }
+}
+async function loadDbModule() {
+  const load = getRuntimeState().loadDbModule ?? (async () => await dynamicImport("@holo-js/db"));
+  try {
+    return await load();
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+      return null;
+    }
+    throw error;
+  }
+}
+function normalizeOptionalString(value, label) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[@holo-js/broadcast] ${label} must be a non-empty string when provided.`);
+  }
+  return normalized;
+}
+function normalizeRequiredString(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[@holo-js/broadcast] ${label} must be a non-empty string.`);
+  }
+  return normalized;
+}
+function normalizeDelayValue(value, label) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`[@holo-js/broadcast] ${label} must be a finite number greater than or equal to 0.`);
+    }
+    return value;
+  }
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error(`[@holo-js/broadcast] ${label} dates must be valid Date instances.`);
+  }
+  return value;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function normalizeJsonValue(value, path) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`)));
+  }
+  if (!isRecord(value)) {
+    throw new Error(`[@holo-js/broadcast] ${path} must be JSON-serializable.`);
+  }
+  return Object.freeze(Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [key, normalizeJsonValue(entry, `${path}.${key}`)])
+  ));
+}
+function normalizePayload(payload) {
+  if (!isRecord(payload)) {
+    throw new Error("[@holo-js/broadcast] Broadcast payload must be a plain object.");
+  }
+  return normalizeJsonValue(payload, "Broadcast payload");
+}
+function normalizeRawChannels(channels) {
+  if (!Array.isArray(channels) || channels.length === 0) {
+    throw new Error("[@holo-js/broadcast] Raw broadcasts must target at least one channel.");
+  }
+  const normalized = channels.map((channel) => normalizeRequiredString(channel, "Broadcast channel"));
+  return Object.freeze(normalized);
+}
+function resolveBroadcastDefinition(definition) {
+  return isBroadcastDefinition(definition) ? definition : normalizeBroadcastDefinition(definition);
+}
+function resolveBroadcastConnection(selectedConnection) {
+  const config = getRuntimeBindings().config ?? holoBroadcastDefaults;
+  const connectionName = normalizeOptionalString(selectedConnection, "Broadcast connection") ?? config.default;
+  const connection = config.connections[connectionName];
+  if (!connection) {
+    throw new Error(`[@holo-js/broadcast] Broadcast connection "${connectionName}" is not configured.`);
+  }
+  return Object.freeze({
+    name: connection.name,
+    driver: connection.driver,
+    ..."options" in connection ? { options: connection.options } : {}
+  });
+}
+function normalizeRawBroadcastInput(input, selectedConnection) {
+  const connection = resolveBroadcastConnection(selectedConnection ?? input.connection);
+  const event = normalizeRequiredString(input.event, "Broadcast event");
+  const socketId = normalizeOptionalString(input.socketId, "Broadcast socket id");
+  return Object.freeze({
+    connection: connection.name,
+    event,
+    channels: normalizeRawChannels(input.channels),
+    payload: normalizePayload(input.payload),
+    ...typeof socketId === "undefined" ? {} : { socketId }
+  });
+}
+function createRawInputFromDefinition(definition, selectedConnection) {
+  if (typeof definition.name !== "string" || !definition.name.trim()) {
+    throw new Error("[@holo-js/broadcast] Broadcast definitions must resolve a public event name before dispatch.");
+  }
+  return normalizeRawBroadcastInput({
+    connection: selectedConnection,
+    event: definition.name,
+    channels: definition.channels.map((channel) => {
+      const resolved = formatChannelPattern(
+        channel.pattern,
+        channel.params
+      );
+      if (channel.type === "private") {
+        return `private-${resolved}`;
+      }
+      if (channel.type === "presence") {
+        return `presence-${resolved}`;
+      }
+      return resolved;
+    }),
+    payload: definition.payload
+  });
+}
+function resolveQueuePlan(definition, options) {
+  const queueDefaults = definition?.queue;
+  const queued = queueDefaults?.queued === true || typeof options.connection !== "undefined" || typeof options.queue !== "undefined" || typeof options.delay !== "undefined" || typeof definition?.delay !== "undefined";
+  return Object.freeze({
+    queued,
+    connection: options.connection ?? queueDefaults?.connection,
+    queue: options.queue ?? queueDefaults?.queue,
+    delay: options.delay ?? definition?.delay,
+    afterCommit: options.afterCommit ?? queueDefaults?.afterCommit ?? false
+  });
+}
+function normalizeDispatchOptions(options) {
+  return Object.freeze({
+    broadcaster: options.broadcaster,
+    connection: options.connection,
+    queue: options.queue,
+    delay: options.delay,
+    afterCommit: options.afterCommit
+  });
+}
+function createExecutionContext(messageId, driver, queued, deferred = false) {
+  return Object.freeze({
+    connection: driver.connection.name,
+    driver: driver.driver,
+    queued,
+    delayed: deferred,
+    messageId
+  });
+}
+function createBaseResult(context, channels) {
+  return Object.freeze({
+    connection: context.connection,
+    driver: context.driver,
+    queued: context.queued,
+    publishedChannels: Object.freeze([...channels]),
+    messageId: context.messageId
+  });
+}
+function normalizeDriverResult(result, context, channels) {
+  const publishedChannels = Array.isArray(result.publishedChannels) ? Object.freeze(result.publishedChannels.map((channel) => normalizeRequiredString(channel, "Published channel"))) : Object.freeze([...channels]);
+  const provider = result.provider && isRecord(result.provider) ? Object.freeze({ ...result.provider }) : void 0;
+  return Object.freeze({
+    connection: normalizeOptionalString(result.connection, "Broadcast result connection") ?? context.connection,
+    driver: normalizeOptionalString(result.driver, "Broadcast result driver") ?? context.driver,
+    queued: typeof result.queued === "boolean" ? result.queued : context.queued,
+    publishedChannels,
+    messageId: normalizeOptionalString(result.messageId, "Broadcast result messageId") ?? context.messageId,
+    ...provider ? { provider } : {}
+  });
+}
+function createTransportDriver(driverName) {
+  return {
+    async send(input, context) {
+      const publish = getRuntimeBindings().publish;
+      if (!publish) {
+        throw new Error(`[@holo-js/broadcast] The "${driverName}" driver requires a publish runtime binding.`);
+      }
+      return await publish(input, context);
+    }
+  };
+}
+var builtInDrivers = Object.freeze({
+  holo: createTransportDriver("holo"),
+  pusher: createTransportDriver("pusher"),
+  ably: createTransportDriver("ably"),
+  log: {
+    send(input, context) {
+      console.warn("[@holo-js/broadcast]", {
+        connection: context.connection,
+        driver: context.driver,
+        event: input.event,
+        channels: input.channels,
+        hasSocketId: typeof input.socketId === "string"
+      });
+      return createBaseResult({ ...context, messageId: randomUUID() }, input.channels);
+    }
+  },
+  null: {
+    send(input, context) {
+      return createBaseResult({ ...context, messageId: randomUUID() }, input.channels);
+    }
+  }
+});
+function resolveDriver(connectionName) {
+  const connection = resolveBroadcastConnection(connectionName);
+  const implementation = getRegisteredBroadcastDriver(connection.driver) ?? builtInDrivers[connection.driver];
+  if (!implementation) {
+    throw new Error(`[@holo-js/broadcast] Broadcast driver "${connection.driver}" is not registered.`);
+  }
+  return Object.freeze({
+    connection,
+    driver: connection.driver,
+    implementation
+  });
+}
+async function runQueuedBroadcastDelivery(payload) {
+  const driver = resolveDriver(payload.context.connection);
+  const context = createExecutionContext(payload.messageId, driver, true);
+  return await deliverResolvedRawBroadcast(payload.raw, driver, context);
+}
+async function ensureBroadcastQueueJobRegistered(queueModule) {
+  const state = getRuntimeState();
+  if (queueModule?.getRegisteredQueueJob(HOLO_BROADCAST_DELIVER_JOB)) {
+    return queueModule;
+  }
+  if (state.queueJobRegistration) {
+    return await state.queueJobRegistration;
+  }
+  const registration = (async () => {
+    const resolvedQueueModule = queueModule ?? await loadQueueModule();
+    if (!resolvedQueueModule.getRegisteredQueueJob(HOLO_BROADCAST_DELIVER_JOB)) {
+      resolvedQueueModule.registerQueueJob(
+        resolvedQueueModule.defineJob({
+          async handle(payload) {
+            return await runQueuedBroadcastDelivery(payload);
+          }
+        }),
+        { name: HOLO_BROADCAST_DELIVER_JOB }
+      );
+    }
+    return resolvedQueueModule;
+  })();
+  state.queueJobRegistration = registration;
+  try {
+    return await registration;
+  } finally {
+    if (state.queueJobRegistration === registration) {
+      state.queueJobRegistration = void 0;
+    }
+  }
+}
+function createQueuedPayload(input, context) {
+  return Object.freeze({
+    messageId: context.messageId,
+    raw: input,
+    context: Object.freeze({
+      connection: context.connection,
+      driver: context.driver
+    })
+  });
+}
+async function dispatchQueuedBroadcast(input, context, plan) {
+  const queueModule = await ensureBroadcastQueueJobRegistered();
+  let pending = queueModule.dispatch(
+    HOLO_BROADCAST_DELIVER_JOB,
+    createQueuedPayload(input, context)
+  );
+  if (typeof plan.connection !== "undefined") {
+    pending = pending.onConnection(plan.connection);
+  }
+  if (typeof plan.queue !== "undefined") {
+    pending = pending.onQueue(plan.queue);
+  }
+  if (typeof plan.delay !== "undefined") {
+    pending = pending.delay(plan.delay);
+  }
+  await pending.dispatch();
+  return createBaseResult(context, input.channels);
+}
+async function deferDispatchUntilCommit(context, channels, callback) {
+  const dbModule = await loadDbModule();
+  const active = dbModule?.connectionAsyncContext.getActive()?.connection;
+  if (!active || active.getScope().kind === "root") {
+    return null;
+  }
+  active.afterCommit(async () => {
+    await callback();
+  });
+  return createBaseResult(context, channels);
+}
+async function deliverResolvedRawBroadcast(input, driver, context) {
+  const frozenInput = Object.freeze({
+    connection: input.connection,
+    event: input.event,
+    channels: Object.freeze([...input.channels]),
+    payload: input.payload,
+    ...typeof input.socketId === "undefined" ? {} : { socketId: input.socketId }
+  });
+  const result = await driver.implementation.send(frozenInput, context);
+  return normalizeDriverResult(result, context, frozenInput.channels);
+}
+async function executeResolvedRawBroadcast(input, definition, options) {
+  const driver = resolveDriver(input.connection);
+  const plan = resolveQueuePlan(definition, options);
+  const context = createExecutionContext(randomUUID(), driver, plan.queued);
+  if (plan.afterCommit) {
+    const deferred = await deferDispatchUntilCommit(
+      createExecutionContext(context.messageId, driver, plan.queued, true),
+      input.channels,
+      async () => {
+        if (plan.queued) {
+          return await dispatchQueuedBroadcast(
+            input,
+            createExecutionContext(context.messageId, driver, true),
+            plan
+          );
+        }
+        return await deliverResolvedRawBroadcast(
+          input,
+          driver,
+          createExecutionContext(context.messageId, driver, false)
+        );
+      }
+    );
+    if (deferred) {
+      return deferred;
+    }
+  }
+  if (plan.queued) {
+    return await dispatchQueuedBroadcast(
+      input,
+      createExecutionContext(context.messageId, driver, true),
+      plan
+    );
+  }
+  return await deliverResolvedRawBroadcast(
+    input,
+    driver,
+    createExecutionContext(context.messageId, driver, false)
+  );
+}
+var PendingDispatch = class {
+  constructor(executor, options = {}) {
+    this.executor = executor;
+    this.options = options;
+  }
+  #promise;
+  using(name) {
+    this.options.broadcaster = normalizeRequiredString(name, "Broadcast connection");
+    return this;
+  }
+  onConnection(name) {
+    this.options.connection = normalizeRequiredString(name, "Broadcast queue connection");
+    return this;
+  }
+  onQueue(name) {
+    this.options.queue = normalizeRequiredString(name, "Broadcast queue name");
+    return this;
+  }
+  delay(value) {
+    this.options.delay = normalizeDelayValue(value, "Broadcast delay");
+    return this;
+  }
+  afterCommit() {
+    this.options.afterCommit = true;
+    return this;
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.execute().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.execute().finally(onfinally ?? void 0);
+  }
+  execute() {
+    if (!this.#promise) {
+      this.#promise = this.executor(normalizeDispatchOptions(this.options));
+    }
+    return this.#promise;
+  }
+};
+function configureBroadcastRuntime(bindings) {
+  getRuntimeState().bindings = bindings;
+}
+function getBroadcastRuntimeBindings() {
+  return getRuntimeBindings();
+}
+function resetBroadcastRuntime() {
+  const state = getRuntimeState();
+  state.bindings = void 0;
+  state.loadQueueModule = void 0;
+  state.loadDbModule = void 0;
+  state.queueJobRegistration = void 0;
+}
+function broadcast(definition) {
+  return new PendingDispatch(async (options) => {
+    const resolvedDefinition = resolveBroadcastDefinition(definition);
+    const raw = createRawInputFromDefinition(resolvedDefinition, options.broadcaster);
+    const input = Object.freeze({
+      broadcast: resolvedDefinition,
+      raw,
+      options
+    });
+    void input;
+    return await executeResolvedRawBroadcast(raw, resolvedDefinition, options);
+  });
+}
+function broadcastRaw(input) {
+  return new PendingDispatch(async (options) => {
+    const resolvedInput = normalizeRawBroadcastInput(input, options.broadcaster);
+    return await executeResolvedRawBroadcast(resolvedInput, null, options);
+  });
+}
+function getBroadcastRuntime() {
+  return Object.freeze({
+    broadcast,
+    broadcastRaw
+  });
+}
+var broadcastRuntimeInternals = {
+  createRawInputFromDefinition,
+  ensureBroadcastQueueJobRegistered,
+  normalizeDelayValue,
+  normalizeRawBroadcastInput,
+  resolveBroadcastConnection,
+  resolveDriver,
+  resolveQueuePlan,
+  resetBroadcastRuntime,
+  async runQueuedBroadcastDelivery(payload) {
+    return await runQueuedBroadcastDelivery(payload);
+  },
+  setLoadDbModuleForTesting(loader) {
+    getRuntimeState().loadDbModule = loader;
+  },
+  setLoadQueueModuleForTesting(loader) {
+    getRuntimeState().loadQueueModule = loader;
+  }
+};
+
+export {
+  registerBroadcastDriver,
+  getRegisteredBroadcastDriver,
+  listRegisteredBroadcastDrivers,
+  resetBroadcastDriverRegistry,
+  broadcastRegistryInternals,
+  configureBroadcastRuntime,
+  getBroadcastRuntimeBindings,
+  resetBroadcastRuntime,
+  broadcast,
+  broadcastRaw,
+  getBroadcastRuntime,
+  broadcastRuntimeInternals
+};