hooks-lib/scripts/internal/envelope.js

// scripts/internal/envelope.js
//
// HOOK_CONTRACT.md §2 (envelope shape) + §8 (sync vs async dispatch).
//
// buildEnvelope(rawHookName, args): produces a {ts, hook, args} object
//   or null if the raw hook is not in our registered set.
//
// dispatchEnvelope(envelope): routes the envelope to subscribers via
//   the subscribers module. For sync-mode hooks, this is inline. For
//   async-mode hooks, this is deferred to a microtask.
//
// This is the only module that touches the envelope shape. All other
// modules consume envelopes through subscribers.subscribe.

import { getEntryForRawName, getEntryForEnvelope } from "./registered-hooks.js";
import { ARG_SHAPES, maybeSynthesize } from "./anti-corruption.js";
import { dispatch } from "./subscribers.js";

const MODULE_ID = "foundry-hooks-lib";

/**
 * Build an envelope for a Foundry hook fire.
 *
 * Returns:
 *   - { envelope, synthesized?: true } for the primary envelope
 *   - or null if the raw hook is not registered
 *
 * For hooks that synthesize additional envelopes (combatInactive from
 * updateCombat), the synthesized envelope(s) are also returned in the
 * `synthesized` array on the result.
 */
export function buildEnvelope(rawHookName, args) {
  const entry = getEntryForRawName(rawHookName);
  if (!entry) return null;
  const normalize = ARG_SHAPES[entry.envelope];
  const normalizedArgs = normalize ? normalize(args ?? []) : (args ?? []);
  const ts = Date.now();
  const primary = { ts, hook: entry.envelope, args: normalizedArgs };
  // Anti-corruption: hooks with synthesized envelopes may produce
  // additional envelopes from a single Foundry fire.
  const synth = maybeSynthesize(rawHookName, args);
  return { envelope: primary, synthesized: synth };
}

/**
 * Dispatch an envelope. Called by the Foundry hook wrappers
 * registered in main.js.
 *
 * For sync-mode hooks, dispatches inline. For async-mode hooks,
 * schedules dispatch on a microtask. The wrapper returns immediately
 * in both cases (microtask dispatch returns synchronously to Foundry).
 *
 * Returns immediately in both modes — never awaited by callers.
 */
export function dispatchEnvelope(envelope, mode) {
  if (mode === "sync") {
    dispatch(envelope);
  } else {
    // Async dispatch via microtask. We schedule a single microtask
    // per envelope; the dispatch itself runs synchronously inside
    // the microtask.
    Promise.resolve().then(() => dispatch(envelope));
  }
}

/**
 * Dispatch a batch of envelopes. Used when a single Foundry fire
 * produces multiple envelopes (e.g. updateCombat produces both
 * updateCombat and combatInactive). Each envelope is dispatched
 * according to its own mode.
 */
export function dispatchEnvelopes(envelopes) {
  for (const env of envelopes) {
    const entry = getEntryForEnvelope(env.hook);
    if (!entry) continue;
    dispatchEnvelope(env, entry.mode);
  }
}

export { MODULE_ID };