@zerotal/flow 1.0.0

package/src/events.ts

@@ -0,0 +1,118 @@
+// ── Type-safe real-time events ─────────────────────────────────────────────────
+//
+// `dispatch` / `dispatchTo` / `dispatchSelf` and `@on` are string-keyed at runtime, but their
+// payloads can be type-checked end-to-end by declaring a contract — an app-augmentable interface
+// that maps each event name to its payload type. No codegen: augment `FlowEvents` once and every
+// dispatch site is checked, from server actions and client expressions alike.
+//
+//   // app/flow-events.d.ts
+//   declare module "@zerotal/flow" {
+//     interface FlowEvents {
+//       "post-created": { id: number; title: string };
+//       "cart-cleared": void;   // no payload
+//     }
+//   }
+//
+// Unknown event names still work (a `string` fallback overload keeps `echo:…` broadcasts and
+// gradual adoption compiling), they're just untyped. Payloads are object shapes or `void`.
+
+/**
+ * The realtime event contract: maps each event name to its payload type. Empty by default; apps
+ * augment it via TypeScript module augmentation so every dispatch site and `@on` handler is
+ * type-checked end-to-end, with no codegen. `keyof FlowEvents` drives dispatch/`@on`
+ * autocomplete.
+ *
+ * @remarks
+ * Payloads are object shapes or `void` (for events with no payload). Unknown event names still
+ * compile (a `string` fallback keeps `echo:…` broadcasts and gradual adoption working); they are
+ * simply untyped.
+ *
+ * @example
+ * ```ts
+ * // app/flow-events.d.ts
+ * declare module "@zerotal/flow" {
+ *   interface FlowEvents {
+ *     "post-created": { id: number; title: string };
+ *     "cart-cleared": void; // no payload
+ *   }
+ * }
+ * ```
+ *
+ * @category Realtime
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface FlowEvents {}
+
+/**
+ * A known event name — a key of the augmented {@link FlowEvents} contract.
+ *
+ * @category Realtime
+ */
+export type EventName = keyof FlowEvents;
+
+/**
+ * The payload type for a known event `K`, resolved from the {@link FlowEvents} contract. Use it
+ * to type an `@on` handler's parameter, e.g. `EventPayload<"post-created">`.
+ *
+ * @category Realtime
+ */
+export type EventPayload<K extends EventName> = FlowEvents[K];
+
+/**
+ * The trailing argument(s) of a dispatch call for payload `P`: none when `P` is `void`
+ * (`dispatch("cart-cleared")`), otherwise a single typed payload.
+ */
+export type EventArgs<P> = [P] extends [void] ? [] : [payload: P];
+
+/** An event name loosened to accept any string (autocomplete for known names, `echo:…` too). */
+export type LooseEventName = EventName | (string & {});
+
+// ── Optional runtime shape guards ──────────────────────────────────────────────
+// The types cover dispatch sites at compile time; a guard adds a runtime check for payloads that
+// arrive from an untrusted source (a client-originated dispatch) or to catch a refactor that the
+// types missed. Opt in per event; a failed guard throws from dispatch().
+
+type Guard = (payload: unknown) => boolean;
+const _guards = new Map<string, Guard>();
+
+/**
+ * Registers a runtime guard for a known event's payload.
+ *
+ * @remarks
+ * The compile-time {@link FlowEvents} contract covers dispatch sites at build time; this adds a
+ * runtime check for payloads arriving from an untrusted source (a client-originated dispatch) or
+ * to catch a refactor the types missed. Opt in per event. When a guard is set, `dispatch` (and
+ * its variants) throw a `TypeError` if the payload doesn't satisfy it — surfacing a malformed
+ * payload loudly instead of letting it flow to listeners. Registering the same event again
+ * replaces its guard.
+ *
+ * @param name - The known event name to guard (a key of {@link FlowEvents}).
+ * @param guard - A type-guard predicate that narrows an `unknown` payload to the event's type.
+ *
+ * @example
+ * ```ts
+ * registerFlowEvent("post-created", (p): p is { id: number } =>
+ *   typeof (p as { id?: unknown })?.id === "number");
+ * ```
+ *
+ * @category Realtime
+ */
+export function registerFlowEvent<K extends EventName>(
+  name: K,
+  guard: (payload: unknown) => payload is FlowEvents[K],
+): void {
+  _guards.set(name as string, guard as Guard);
+}
+
+/** @internal Validate a dispatched payload against its registered guard; throws on mismatch. */
+export function _validateEventPayload(name: string, payload: unknown): void {
+  const guard = _guards.get(name);
+  if (guard && !guard(payload)) {
+    throw new TypeError(`[Flow] dispatch("${name}") payload failed its registered guard.`);
+  }
+}
+
+/** @internal Test hook — clear all registered guards. */
+export function _resetEventGuards(): void {
+  _guards.clear();
+}

package/src/frameworkEvents.ts

@@ -0,0 +1,40 @@
+/**
+ * Flow's realtime **framework** events, emitted on core's {@link FrameworkEvents}
+ * bus (distinct from the app-facing `FlowEvents` realtime contract in
+ * `./events.ts`). Observability packages subscribe to them by kind (their class name).
+ */
+
+/**
+ * Emitted when a Flow (reactive SSR) WebSocket connection opens.
+ * @category Realtime
+ */
+export class WebSocketConnected {
+  constructor(readonly url: string) {}
+}
+
+/**
+ * Emitted when a Flow WebSocket connection closes.
+ * @category Realtime
+ */
+export class WebSocketDisconnected {
+  constructor(readonly url: string) {}
+}
+
+/**
+ * Emitted after a Flow component action round-trips over the WebSocket. Carries
+ * the same rich context an HTTP request does: `ip`, and the request-scoped `ctx`
+ * (an HttpContext with `user` set by re-run middleware, and the SQL queries that
+ * ran during the action correlated to it).
+ *
+ * @category Realtime
+ */
+export class FlowActionHandled {
+  constructor(
+    readonly component: string,
+    readonly action: string,
+    readonly durationMs: number,
+    readonly ok: boolean,
+    readonly ip: string | null,
+    readonly ctx: object | undefined,
+  ) {}
+}