feature

Events and snapshots

Before a definition can fire, you must declare each event id and its payload fields — that schema is what Collect stores and studies filter on.

events.declare is required for anything you ctx.emit. Optional snapshots.declare is for intermediate state you want to record without creating a Collect event.

events.declare

events.declare({
  id: string;
  intent: string;
  payload: Record<string, {
    type: "string" | "number" | "boolean" | "object" | "array";
    description: string;
  }>;
  oncePer?: { keys: string[]; windowBars?: number };
  paint?: "none" | "pin" | "highlight_event_bar" | "highlight_price"
        | "highlight_event_bar_and_price" | /* deprecated: marker|highlight|both */;
}): void

Example

events.declare({
  id: "london_session_classified",
  intent: "Classify London→NY continuation regime",
  payload: {
    regime: { type: "string", description: "Regime label" },
    atr: { type: "number", description: "ATR at classify time" },
  },
  oncePer: { keys: ["sessionKey"], windowBars: 390 },
  paint: "pin",
});

oncePer

Built-in dedupe. Prefer this over hand-rolled throttles with module state.

Reserved payload keys

Do not declare _displayLabel or _displaySubtitle in payload. Those are written by the runtime from emit label / subtitle. See Emit and labels.

snapshots.declare

snapshots.declare({
  id: "pre_london",
  /* fields per SnapshotDecl contract */
});

Emit with ctx.snapshot(snapshotId, payload) from onBar.

Lint

Emitting an undeclared event id fails
events/emit-missing-label when label is missing (warn; runtime drops)

← Previous Next →