hooks-lib/scripts/internal/subscribers.js

// scripts/internal/subscribers.js
//
// HOOK_CONTRACT.md §3: subscribe primitives + §3.5 error containment.
//
// subscribe(hookName, fn) — single hook, single handler
// subscribeMany(map) — atomic batch
// subscribeAll(fn) — every hook, one handler
// unsubscribeAll() — purge everything
//
// Error containment (§3.5): throwing consumer callbacks are caught,
// logged via console.error with the [foundry-hooks-lib] prefix and the
// hook name, and the dispatch chain continues to the next callback.
// Errors never propagate to Foundry's hook chain.
//
// Multiple subscriptions for the same hook stack in registration
// order.

import { REGISTERED_HOOKS } from "./registered-hooks.js";

const MODULE_ID = "foundry-hooks-lib";

// Per-envelope callback list. Order = registration order.
const _callbacks = new Map(); // hookName (envelope) -> [fn, fn, ...]
const _allCallbacks = [];     // subscribeAll subscribers, in order

function assertRegistered(hookName) {
  if (!REGISTERED_HOOKS.includes(hookName)) {
    throw new TypeError(
      `subscribe("${hookName}"): hook not in REGISTERED_HOOKS. ` +
      `Available hooks: ${REGISTERED_HOOKS.length}. Use listActiveAdapters() + adapter factory to add system-specific derived events.`
    );
  }
}

export function subscribe(hookName, fn) {
  if (typeof fn !== "function") {
    throw new TypeError(`subscribe(hookName, fn): fn must be a function`);
  }
  assertRegistered(hookName);
  if (!_callbacks.has(hookName)) {
    _callbacks.set(hookName, []);
  }
  _callbacks.get(hookName).push(fn);
  return () => {
    const list = _callbacks.get(hookName);
    if (!list) return;
    const idx = list.indexOf(fn);
    if (idx >= 0) list.splice(idx, 1);
  };
}

export function subscribeMany(map) {
  if (!map || typeof map !== "object") {
    throw new TypeError(`subscribeMany(map): map must be an object`);
  }
  const entries = Object.entries(map);
  // Atomicity: validate all names first. If any fails, throw WITHOUT
  // registering any. (We don't register until all checks pass.)
  for (const [name, fn] of entries) {
    if (typeof fn !== "function") {
      throw new TypeError(
        `subscribeMany: handler for "${name}" must be a function`
      );
    }
    assertRegistered(name);
  }
  // All validated — register all.
  const unsubs = entries.map(([name, fn]) => subscribe(name, fn));
  return () => {
    for (const u of unsubs) u();
  };
}

export function subscribeAll(fn) {
  if (typeof fn !== "function") {
    throw new TypeError(`subscribeAll(fn): fn must be a function`);
  }
  _allCallbacks.push(fn);
  return () => {
    const idx = _allCallbacks.indexOf(fn);
    if (idx >= 0) _allCallbacks.splice(idx, 1);
  };
}

export function unsubscribeAll() {
  _callbacks.clear();
  _allCallbacks.length = 0;
}

// Internal: dispatch an envelope to all matching callbacks + all
// subscribeAll subscribers. Called by the envelope dispatcher.
//
// For sync-mode hooks, this runs inline. For async-mode hooks, the
// envelope dispatcher wraps this in a microtask.
//
// Returns true if any callback threw (for diagnostics). Never re-throws.
export function dispatch(envelope) {
  let threwAny = false;
  // Targeted callbacks.
  const list = _callbacks.get(envelope.hook);
  if (list) {
    for (const fn of list) {
      try {
        fn(envelope);
      } catch (e) {
        threwAny = true;
        console.error(
          `[${MODULE_ID}] consumer callback for "${envelope.hook}" threw:`,
          e
        );
      }
    }
  }
  // Wildcard subscribers (subscribeAll). These also receive every
  // envelope; consumers dispatch on envelope.hook themselves.
  for (const fn of _allCallbacks) {
    try {
      fn(envelope);
    } catch (e) {
      threwAny = true;
      console.error(
        `[${MODULE_ID}] subscribeAll callback for "${envelope.hook}" threw:`,
        e
      );
    }
  }
  return threwAny;
}

// Internal: list envelope names that have at least one callback.
// Used by tests for verification.
export function listSubscribedHooks() {
  return [..._callbacks.keys()];
}

export function hasCallbacksFor(envelopeName) {
  const list = _callbacks.get(envelopeName);
  return !!list && list.length > 0;
}