station-broadcast 1.0.0

package/src/broadcast.ts

@@ -0,0 +1,293 @@
+import type { AnySignal, Signal } from "station-signal";
+import { isSignal, parseInterval, getTriggerAdapter } from "station-signal";
+import { getBroadcastAdapter } from "./config.js";
+import { BroadcastValidationError } from "./errors.js";
+import type { BroadcastRun, FailurePolicy } from "./types.js";
+import { BROADCAST_BRAND, topologicalSort } from "./util.js";
+
+/** A named node in the broadcast DAG. */
+export interface BroadcastNode {
+  readonly name: string;
+  readonly signalName: string;
+  /** Reference to the actual Signal object — used for input validation via signal.trigger(). */
+  readonly signal: AnySignal;
+  readonly dependsOn: readonly string[];
+  readonly timeout: number;
+  readonly maxAttempts: number;
+  readonly map?: (upstream: Record<string, unknown>) => unknown;
+  readonly when?: (upstream: Record<string, unknown>) => boolean;
+}
+
+export interface BroadcastDefinition {
+  readonly [BROADCAST_BRAND]: true;
+  readonly name: string;
+  readonly nodes: readonly BroadcastNode[];
+  readonly failurePolicy: FailurePolicy;
+  /** Max time (ms) the entire broadcast may run before being auto-failed. */
+  readonly timeout?: number;
+  readonly interval?: string;
+  readonly recurringInput?: unknown;
+  trigger(input: unknown): Promise<string>;
+}
+
+export interface ThenOptions {
+  /** Node label (defaults to signal name). */
+  as?: string;
+  /** Explicit upstream dependencies (defaults to all nodes in the previous tier). */
+  after?: string[];
+  /** Transform upstream outputs into this node's input. */
+  map?: (upstream: Record<string, unknown>) => unknown;
+  /** Conditional guard — skip this node if the predicate returns false. */
+  when?: (upstream: Record<string, unknown>) => boolean;
+}
+
+export class BroadcastChain<TInput> {
+  /** @internal */
+  readonly _name: string;
+  /** @internal */
+  readonly _nodes: BroadcastNode[];
+  /** @internal */
+  readonly _lastTier: string[];
+  /** @internal */
+  readonly _failurePolicy: FailurePolicy;
+  /** @internal */
+  readonly _timeout?: number;
+  /** @internal */
+  readonly _interval?: string;
+  /** @internal */
+  readonly _recurringInput?: unknown;
+
+  /** @internal */
+  constructor(opts: {
+    name: string;
+    nodes: BroadcastNode[];
+    lastTier: string[];
+    failurePolicy: FailurePolicy;
+    timeout?: number;
+    interval?: string;
+    recurringInput?: unknown;
+  }) {
+    this._name = opts.name;
+    this._nodes = opts.nodes;
+    this._lastTier = opts.lastTier;
+    this._failurePolicy = opts.failurePolicy;
+    this._timeout = opts.timeout;
+    this._interval = opts.interval;
+    this._recurringInput = opts.recurringInput;
+  }
+
+  /** @internal */
+  private _clone(overrides: Partial<ConstructorParameters<typeof BroadcastChain>[0]> = {}): BroadcastChain<TInput> {
+    return new BroadcastChain<TInput>({
+      name: this._name,
+      nodes: this._nodes,
+      lastTier: this._lastTier,
+      failurePolicy: this._failurePolicy,
+      timeout: this._timeout,
+      interval: this._interval,
+      recurringInput: this._recurringInput,
+      ...overrides,
+    });
+  }
+
+  /**
+   * Add one or more signals to the DAG.
+   *
+   * - `.then(signal)` — runs after the previous tier, pass-through data
+   * - `.then(signal, { as, after, map, when })` — single signal with options
+   * - `.then(signal1, signal2, ...)` — fan-out: all run in parallel after previous tier
+   */
+  then(...args: (AnySignal | ThenOptions)[]): BroadcastChain<TInput> {
+    const signals: AnySignal[] = [];
+    let options: ThenOptions | undefined;
+
+    for (const arg of args) {
+      if (isSignal(arg)) {
+        signals.push(arg);
+      } else if (typeof arg === "object" && arg !== null) {
+        options = arg as ThenOptions;
+      }
+    }
+
+    if (signals.length === 0) {
+      throw new BroadcastValidationError(
+        `then() requires at least one signal in broadcast "${this._name}".`,
+      );
+    }
+
+    // Single signal with options
+    if (signals.length === 1) {
+      const sig = signals[0];
+      const nodeName = options?.as ?? sig.name;
+      const deps = options?.after ? [...options.after] : [...this._lastTier];
+
+      const node: BroadcastNode = {
+        name: nodeName,
+        signalName: sig.name,
+        signal: sig,
+        dependsOn: deps,
+        timeout: sig.timeout,
+        maxAttempts: sig.maxAttempts,
+        map: options?.map,
+        when: options?.when,
+      };
+
+      return this._clone({ nodes: [...this._nodes, node], lastTier: [nodeName] });
+    }
+
+    // Fan-out with options is ambiguous — throw an error
+    if (options) {
+      throw new BroadcastValidationError(
+        `Options (as, after, map, when) cannot be used with fan-out (multiple signals) in broadcast "${this._name}". ` +
+        `Use separate .then() calls with options for each signal instead.`,
+      );
+    }
+
+    // Fan-out: multiple signals, all depend on the last tier
+    const newNodes: BroadcastNode[] = [];
+    const newTier: string[] = [];
+
+    for (const sig of signals) {
+      newNodes.push({
+        name: sig.name,
+        signalName: sig.name,
+        signal: sig,
+        dependsOn: [...this._lastTier],
+        timeout: sig.timeout,
+        maxAttempts: sig.maxAttempts,
+      });
+      newTier.push(sig.name);
+    }
+
+    return this._clone({ nodes: [...this._nodes, ...newNodes], lastTier: newTier });
+  }
+
+  /** Set a broadcast-level timeout (ms). Auto-fails the broadcast if exceeded. */
+  timeout(ms: number): BroadcastChain<TInput> {
+    return this._clone({ timeout: ms });
+  }
+
+  every(interval: string): BroadcastChain<TInput> {
+    parseInterval(interval);
+    return this._clone({ interval });
+  }
+
+  withInput(input: TInput): BroadcastChain<TInput> {
+    return this._clone({ recurringInput: input });
+  }
+
+  onFailure(policy: FailurePolicy): BroadcastChain<TInput> {
+    return this._clone({ failurePolicy: policy });
+  }
+
+  build(): BroadcastDefinition {
+    this.validate();
+
+    const name = this._name;
+    const nodes = [...this._nodes];
+    const failurePolicy = this._failurePolicy;
+    const timeout = this._timeout;
+    const interval = this._interval;
+    const recurringInput = this._recurringInput;
+
+    return {
+      [BROADCAST_BRAND]: true as const,
+      name,
+      nodes,
+      failurePolicy,
+      timeout,
+      interval,
+      recurringInput,
+      async trigger(input: unknown): Promise<string> {
+        // Remote trigger path
+        const triggerAdapter = getTriggerAdapter();
+        if (triggerAdapter?.triggerBroadcast) {
+          return triggerAdapter.triggerBroadcast(name, input);
+        }
+
+        // Local trigger path
+        const adapter = getBroadcastAdapter();
+        const id = adapter.generateId();
+        const run: BroadcastRun = {
+          id,
+          broadcastName: name,
+          input: JSON.stringify(input),
+          status: "pending",
+          failurePolicy,
+          timeout,
+          createdAt: new Date(),
+        };
+        await adapter.addBroadcastRun(run);
+        return id;
+      },
+    };
+  }
+
+  private validate(): void {
+    const names = new Set<string>();
+
+    // Check for duplicate node names
+    for (const node of this._nodes) {
+      if (names.has(node.name)) {
+        throw new BroadcastValidationError(
+          `Duplicate node name "${node.name}" in broadcast "${this._name}". ` +
+          `Use the "as" option to disambiguate.`,
+        );
+      }
+      names.add(node.name);
+    }
+
+    // Check for missing dependencies
+    for (const node of this._nodes) {
+      for (const dep of node.dependsOn) {
+        if (!names.has(dep)) {
+          throw new BroadcastValidationError(
+            `Node "${node.name}" depends on "${dep}", but no node named "${dep}" ` +
+            `exists in broadcast "${this._name}".`,
+          );
+        }
+      }
+    }
+
+    // Cycle detection via topological sort (throws BroadcastCycleError)
+    topologicalSort(this._name, this._nodes);
+  }
+}
+
+const VALID_NAME = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+export class BroadcastBuilder {
+  private _name: string;
+
+  constructor(name: string) {
+    if (!VALID_NAME.test(name)) {
+      throw new Error(
+        `Invalid broadcast name "${name}". Names must start with a letter and contain only letters, digits, hyphens, and underscores.`,
+      );
+    }
+    this._name = name;
+  }
+
+  /** Set the root signal — the entry point of the broadcast. Input type is inferred from the signal. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  input<T>(rootSignal: Signal<T, any>): BroadcastChain<T> {
+    const node: BroadcastNode = {
+      name: rootSignal.name,
+      signalName: rootSignal.name,
+      signal: rootSignal,
+      dependsOn: [],
+      timeout: rootSignal.timeout,
+      maxAttempts: rootSignal.maxAttempts,
+    };
+    return new BroadcastChain<T>({
+      name: this._name,
+      nodes: [node],
+      lastTier: [rootSignal.name],
+      failurePolicy: "fail-fast",
+    });
+  }
+}
+
+export function broadcast(name: string): BroadcastBuilder {
+  return new BroadcastBuilder(name);
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+import { BroadcastMemoryAdapter } from "./adapters/memory.js";
+import type { BroadcastQueueAdapter } from "./adapters/index.js";
+
+let _adapter: BroadcastQueueAdapter = new BroadcastMemoryAdapter();
+let _configured = false;
+let _warnedUnconfigured = false;
+
+export function configureBroadcast(options: { adapter: BroadcastQueueAdapter }): void {
+  if (_configured) {
+    console.warn(
+      "[station-broadcast] configureBroadcast() called multiple times. The previous adapter will be replaced.",
+    );
+  }
+  _adapter = options.adapter;
+  _configured = true;
+}
+
+export function getBroadcastAdapter(): BroadcastQueueAdapter {
+  if (!_configured && !_warnedUnconfigured) {
+    _warnedUnconfigured = true;
+    console.warn(
+      "[station-broadcast] No adapter configured — using default BroadcastMemoryAdapter. " +
+      "Call configureBroadcast({ adapter }) for persistent storage.",
+    );
+  }
+  return _adapter;
+}
+
+export function isBroadcastConfigured(): boolean {
+  return _configured;
+}

package/src/errors.ts

@@ -0,0 +1,19 @@
+export class BroadcastValidationError extends Error {
+  readonly code: string = "BROADCAST_VALIDATION_ERROR";
+  constructor(message: string) {
+    super(message);
+    this.name = "BroadcastValidationError";
+  }
+}
+
+export class BroadcastCycleError extends BroadcastValidationError {
+  override readonly code = "BROADCAST_CYCLE_ERROR";
+  readonly cycle: string[];
+  constructor(broadcastName: string, cycle: string[]) {
+    super(
+      `Broadcast "${broadcastName}" contains a cycle: ${cycle.join(" → ")}`,
+    );
+    this.name = "BroadcastCycleError";
+    this.cycle = cycle;
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export { broadcast, BroadcastBuilder, BroadcastChain, type BroadcastDefinition, type BroadcastNode, type ThenOptions } from "./broadcast.js";
+export { BroadcastRunner, type BroadcastRunnerOptions } from "./broadcast-runner.js";
+export { configureBroadcast, getBroadcastAdapter, isBroadcastConfigured } from "./config.js";
+
+export type {
+  BroadcastRun,
+  BroadcastRunStatus,
+  BroadcastRunPatch,
+  BroadcastNodeRun,
+  BroadcastNodeStatus,
+  BroadcastNodeRunPatch,
+  BroadcastNodeSkipReason,
+  FailurePolicy,
+} from "./types.js";
+
+export {
+  type BroadcastQueueAdapter,
+  BroadcastMemoryAdapter,
+} from "./adapters/index.js";
+
+export {
+  type BroadcastSubscriber,
+  ConsoleBroadcastSubscriber,
+} from "./subscribers/index.js";
+
+export {
+  BroadcastValidationError,
+  BroadcastCycleError,
+} from "./errors.js";
+
+export { isBroadcast, BROADCAST_BRAND } from "./util.js";

package/src/subscribers/console.ts

@@ -0,0 +1,66 @@
+import type { BroadcastRun, BroadcastNodeRun } from "../types.js";
+import type { BroadcastSubscriber } from "./index.js";
+
+export class ConsoleBroadcastSubscriber implements BroadcastSubscriber {
+  private prefix = "[station-broadcast]";
+
+  onBroadcastDiscovered(event: { broadcastName: string; filePath: string }): void {
+    console.log(
+      `${this.prefix} Discovered broadcast "${event.broadcastName}" at ${event.filePath}`,
+    );
+  }
+
+  onBroadcastQueued(event: { broadcastRun: BroadcastRun }): void {
+    console.log(
+      `${this.prefix} Queued "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id})`,
+    );
+  }
+
+  onBroadcastStarted(event: { broadcastRun: BroadcastRun }): void {
+    console.log(
+      `${this.prefix} Started "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id})`,
+    );
+  }
+
+  onBroadcastCompleted(event: { broadcastRun: BroadcastRun }): void {
+    console.log(
+      `${this.prefix} Completed "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id})`,
+    );
+  }
+
+  onBroadcastFailed(event: { broadcastRun: BroadcastRun; error: string }): void {
+    console.error(
+      `${this.prefix} Failed "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id}): ${event.error}`,
+    );
+  }
+
+  onBroadcastCancelled(event: { broadcastRun: BroadcastRun }): void {
+    console.log(
+      `${this.prefix} Cancelled "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id})`,
+    );
+  }
+
+  onNodeTriggered(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun }): void {
+    console.log(
+      `${this.prefix}   → Node "${event.nodeRun.nodeName}" triggered for "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id})`,
+    );
+  }
+
+  onNodeCompleted(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun }): void {
+    console.log(
+      `${this.prefix}   [ok] Node "${event.nodeRun.nodeName}" completed for "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id})`,
+    );
+  }
+
+  onNodeFailed(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun; error: string }): void {
+    console.error(
+      `${this.prefix}   [FAIL] Node "${event.nodeRun.nodeName}" failed for "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id}): ${event.error}`,
+    );
+  }
+
+  onNodeSkipped(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun; reason: string }): void {
+    console.log(
+      `${this.prefix}   [skip] Node "${event.nodeRun.nodeName}" skipped for "${event.broadcastRun.broadcastName}" (${event.broadcastRun.id}): ${event.reason}`,
+    );
+  }
+}

package/src/subscribers/index.ts

@@ -0,0 +1,35 @@
+import type { BroadcastRun, BroadcastNodeRun } from "../types.js";
+
+export interface BroadcastSubscriber {
+  /** Broadcast definition discovered during auto-discovery. */
+  onBroadcastDiscovered?(event: { broadcastName: string; filePath: string }): void;
+
+  /** Broadcast run created and queued. */
+  onBroadcastQueued?(event: { broadcastRun: BroadcastRun }): void;
+
+  /** Broadcast run started (first nodes being triggered). */
+  onBroadcastStarted?(event: { broadcastRun: BroadcastRun }): void;
+
+  /** All nodes completed successfully. */
+  onBroadcastCompleted?(event: { broadcastRun: BroadcastRun }): void;
+
+  /** Broadcast failed (at least one required node failed). */
+  onBroadcastFailed?(event: { broadcastRun: BroadcastRun; error: string }): void;
+
+  /** Broadcast cancelled. */
+  onBroadcastCancelled?(event: { broadcastRun: BroadcastRun }): void;
+
+  /** A node's signal was triggered. */
+  onNodeTriggered?(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun }): void;
+
+  /** A node's signal completed. */
+  onNodeCompleted?(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun }): void;
+
+  /** A node's signal failed. */
+  onNodeFailed?(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun; error: string }): void;
+
+  /** A node was skipped (guard returned false or upstream failed). */
+  onNodeSkipped?(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun; reason: string }): void;
+}
+
+export { ConsoleBroadcastSubscriber } from "./console.js";

package/src/types.ts

@@ -0,0 +1,47 @@
+export type FailurePolicy = "fail-fast" | "skip-downstream" | "continue";
+
+export type BroadcastRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+export type BroadcastNodeStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+
+export interface BroadcastRun {
+  id: string;
+  broadcastName: string;
+  /** JSON-serialized input provided when the broadcast was triggered. */
+  input: string;
+  status: BroadcastRunStatus;
+  failurePolicy: FailurePolicy;
+  /** Max time (ms) the entire broadcast may run before being auto-failed. */
+  timeout?: number;
+  /** Recurring interval (e.g. "5m"). */
+  interval?: string;
+  nextRunAt?: Date;
+  createdAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  error?: string;
+}
+
+export type BroadcastRunPatch = Partial<Omit<BroadcastRun, "id" | "broadcastName" | "createdAt">>;
+
+export type BroadcastNodeSkipReason = "guard" | "upstream-failed" | "cancelled";
+
+export interface BroadcastNodeRun {
+  id: string;
+  broadcastRunId: string;
+  nodeName: string;
+  signalName: string;
+  /** Links to the signal Run record created for this node. */
+  signalRunId?: string;
+  status: BroadcastNodeStatus;
+  /** Why this node was skipped (only set when status is "skipped"). */
+  skipReason?: BroadcastNodeSkipReason;
+  /** JSON-serialized input passed to the signal. */
+  input?: string;
+  /** JSON-serialized output from the completed signal. */
+  output?: string;
+  error?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+}
+
+export type BroadcastNodeRunPatch = Partial<Omit<BroadcastNodeRun, "id" | "broadcastRunId" | "nodeName" | "signalName">>;

package/src/util.ts

@@ -0,0 +1,49 @@
+import type { BroadcastDefinition, BroadcastNode } from "./broadcast.js";
+import { BroadcastCycleError } from "./errors.js";
+
+export const BROADCAST_BRAND = Symbol.for("station-broadcast");
+
+export function isBroadcast(value: unknown): value is BroadcastDefinition {
+  if (typeof value !== "object" || value === null) return false;
+  return (value as Record<symbol, unknown>)[BROADCAST_BRAND] === true;
+}
+
+/**
+ * Topological sort with cycle detection.
+ * Returns nodes in dependency order (roots first).
+ * Throws BroadcastCycleError if a cycle is found.
+ */
+export function topologicalSort(
+  broadcastName: string,
+  nodes: readonly BroadcastNode[],
+): BroadcastNode[] {
+  const nodeMap = new Map(nodes.map((n) => [n.name, n]));
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const sorted: BroadcastNode[] = [];
+
+  function visit(name: string, path: string[]): void {
+    if (visited.has(name)) return;
+    if (visiting.has(name)) {
+      const cycleStart = path.indexOf(name);
+      const cycle = [...path.slice(cycleStart), name];
+      throw new BroadcastCycleError(broadcastName, cycle);
+    }
+
+    visiting.add(name);
+    const node = nodeMap.get(name);
+    if (!node) return; // Guard: skip unknown nodes (validated elsewhere)
+    for (const dep of node.dependsOn) {
+      visit(dep, [...path, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+    sorted.push(node);
+  }
+
+  for (const node of nodes) {
+    visit(node.name, []);
+  }
+
+  return sorted;
+}