@zerotal/flow 1.0.0

package/src/synths/index.ts

@@ -0,0 +1,148 @@
+// ── Synthesizer registry ──────────────────────────────────────────────────────
+//
+// Each synthesizer knows how to:
+//   - match a JS value at dehydration time
+//   - convert it to a JSON-safe primitive + metadata object
+//   - reconstruct the original value from that primitive + metadata
+//
+// Pattern lifted directly from Livewire v3's synthesizer system.
+
+/**
+ * A synthesizer ("synth") teaches flow how to send a non-JSON type across the
+ * wire: it matches a live value, dehydrates it to a JSON-safe primitive plus
+ * metadata for the snapshot, and hydrates it back on the other side.
+ *
+ * @remarks
+ * This is the extension point behind first-class support for `Date`, `Carbon`,
+ * ORM models, collections, and {@link TemporaryUploadedFile}. During
+ * serialization the registry tries each synth's {@link match} in order; the first
+ * match's {@link dehydrate} produces the stored data and its {@link key} is
+ * written to `meta.s`. On the way back, {@link key} selects the synth whose
+ * {@link hydrate} reconstructs the value. `hydrate` may be async (e.g. a model
+ * synth re-fetches by id). The pattern is lifted from Livewire v3's synthesizers.
+ *
+ * @typeParam T - The live value type this synth handles.
+ */
+export interface Synth<T = unknown> {
+  /** Short tag stored as `meta.s` in the snapshot, e.g. `'cbn'`, `'mdl'`. */
+  key: string;
+  /** Type guard: whether this synth handles `value` (checked in registration order). */
+  match(value: unknown): value is T;
+  /** Serialize `value` to a JSON-safe form; may mutate `meta` to stash extra fields for hydrate. */
+  dehydrate(value: T, meta: Record<string, unknown>): unknown;
+  /** Reconstruct the live value from serialized `data` and its `meta` (may be async). */
+  hydrate(data: unknown, meta: Record<string, unknown>): T | Promise<T>;
+}
+
+const _synths: Synth[] = [];
+
+/**
+ * Register a synthesizer so its type can cross the wire in snapshots. Newly
+ * registered synths are tried first, so a later registration can override an
+ * earlier (built-in) match.
+ *
+ * @param synth - The {@link Synth} to add to the registry.
+ *
+ * @example
+ * ```ts
+ * class Money { constructor(public cents: number, public currency: string) {} }
+ *
+ * registerSynth({
+ *   key: "money",
+ *   match: (v): v is Money => v instanceof Money,
+ *   dehydrate: (v, meta) => { meta.cur = v.currency; return v.cents; },
+ *   hydrate: (data, meta) => new Money(data as number, meta.cur as string),
+ * });
+ * ```
+ */
+export function registerSynth(synth: Synth): void {
+  _synths.unshift(synth); // user-registered synths take priority
+}
+
+/** The registered synths, in match order (most-recently-registered first). */
+export function getSynths(): readonly Synth[] {
+  return _synths;
+}
+
+/**
+ * Serialize a single value through the synth registry, recursing into plain
+ * arrays and objects (each element/property stored as its own `[data, meta]`
+ * tuple so per-element synth metadata is preserved).
+ *
+ * @param value - The value to serialize.
+ * @returns A `[data, meta]` tuple; `meta.s` names the synth that matched, if any.
+ */
+export function serializeValue(value: unknown): [data: unknown, meta: Record<string, unknown>] {
+  const meta: Record<string, unknown> = {};
+
+  for (const synth of _synths) {
+    if (synth.match(value)) {
+      const data = synth.dehydrate(value as never, meta);
+      meta["s"] = synth.key;
+      return [data, meta];
+    }
+  }
+
+  // Recursive: plain arrays and objects.
+  // Store full [data, meta] tuples per element so per-element synth metadata
+  // (e.g. { s: 'mdl', class: 'Post' } for ORM models, Date, etc.) is preserved.
+  if (Array.isArray(value)) {
+    return [value.map((v) => serializeValue(v)), meta];
+  }
+  if (typeof value === "object" && value !== null) {
+    const obj: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      obj[k] = serializeValue(v);
+    }
+    return [obj, meta];
+  }
+
+  return [value, meta];
+}
+
+/**
+ * Deserialize a `[data, meta]` tuple produced by {@link serializeValue} back into
+ * a live value, recursing into plain arrays and objects.
+ *
+ * @param data - The serialized data.
+ * @param meta - Its metadata; `meta.s`, when present, selects the synth to hydrate with.
+ * @returns The reconstructed value.
+ * @throws Error if `meta.s` names a synth key that isn't registered.
+ */
+export async function deserializeValue(
+  data: unknown,
+  meta: Record<string, unknown>,
+): Promise<unknown> {
+  const synthKey = meta["s"] as string | undefined;
+  if (synthKey) {
+    const synth = _synths.find((s) => s.key === synthKey);
+    if (!synth) throw new Error(`[Flow] Unknown synth key: "${synthKey}"`);
+    return synth.hydrate(data, meta);
+  }
+
+  // Recursive: plain arrays/objects (no synth key).
+  // Each element/value is a [data, meta] tuple stored by serializeValue.
+  if (Array.isArray(data)) {
+    return Promise.all(
+      data.map((item) =>
+        Array.isArray(item) && item.length === 2
+          ? deserializeValue(item[0], item[1] as Record<string, unknown>)
+          : deserializeValue(item, {}),
+      ),
+    );
+  }
+  if (typeof data === "object" && data !== null) {
+    const result: Record<string, unknown> = {};
+    await Promise.all(
+      Object.entries(data as Record<string, unknown>).map(async ([k, v]) => {
+        result[k] =
+          Array.isArray(v) && v.length === 2
+            ? await deserializeValue(v[0], v[1] as Record<string, unknown>)
+            : await deserializeValue(v, {});
+      }),
+    );
+    return result;
+  }
+
+  return data;
+}

package/src/testing.ts

@@ -0,0 +1,361 @@
+/**
+ * `@zerotal/flow/testing` — in-process test helpers for Flow components.
+ *
+ * Runs the full server-side Flow request pipeline in-process for Bun's test runner:
+ * no WebSocket connection is opened — actions are dispatched directly against a mounted
+ * page instance, driving its real lifecycle hooks (boot/mount/hydrate/update). The entry
+ * point is {@link FlowTest.mount}, which returns a chainable {@link FlowTest} exposing
+ * state-driving actions (`set`/`update`/`call`) and fluent assertions (`assertSee`,
+ * `assertRedirectedTo`, `assertHasErrors`, `assertFlashed`, …). `hydrate` is re-exported
+ * for advanced snapshot-level tests.
+ *
+ * @example
+ * ```ts
+ * import { FlowTest } from '@zerotal/flow/testing';
+ *
+ * const t = await FlowTest.mount(LoginPage);
+ * await t.set('email', 'test@example.com');
+ * await t.set('password', 'secret');
+ * await t.call('login');
+ * t.assertRedirectedTo('/dashboard');
+ * ```
+ *
+ * @example
+ * ```ts
+ * const t = await FlowTest.mount(CreatePostPage);
+ * await t.call('save');
+ * t.assertHasErrors('title');
+ * t.assertSee('The title field is required.');
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { Component } from "./Component.ts";
+import type { FlowEffects } from "./Component.ts";
+import { _renderFlowPage } from "./jsx-runtime.ts";
+import { dehydrate, hydrate } from "./dehydrate.ts";
+import { ValidationError } from "./validation.ts";
+import type { Snapshot } from "./types.ts";
+
+type PageClass<T extends Component> = new () => T;
+
+/**
+ * A fluent test harness around a single mounted Flow page/component. Obtain one with
+ * {@link FlowTest.mount}, drive state with `set`/`update`/`call`, then chain assertions
+ * against the rendered HTML, redirects, validation errors, flashes, and dispatched events.
+ * Every action and assertion returns `this` (or a Promise of it) for chaining.
+ *
+ * @typeParam T - The Component subclass under test.
+ */
+export class FlowTest<T extends Component> {
+  private _page: T;
+  private _html: string = "";
+  private _effects: FlowEffects | null = null;
+  private _snapshot: Snapshot | null = null;
+  private _name: string;
+
+  private constructor(page: T, name: string) {
+    this._page = page;
+    this._name = name;
+  }
+
+  // ── Factory ────────────────────────────────────────────────────────────────
+
+  /**
+   * Mount a page: instantiate it, seed optional props, run its initial-request lifecycle
+   * (`onBoot()` then `onMount()`), render once, and return the harness for chaining.
+   *
+   * @param PageClass - The Component subclass to mount.
+   * @param props - Optional initial property values assigned before `onMount()` runs.
+   * @returns A resolved {@link FlowTest} wrapping the mounted page.
+   * @category Lifecycle
+   *
+   * @example
+   * ```ts
+   * const t = await FlowTest.mount(DashboardPage);
+   * ```
+   */
+  static async mount<T extends Component>(
+    PageClass: PageClass<T>,
+    props: Partial<T> = {},
+  ): Promise<FlowTest<T>> {
+    const page = new PageClass();
+    page._flowId = `test-${PageClass.name.toLowerCase()}`;
+    page._flowPath = "/test";
+
+    Object.assign(page, props);
+    // Initial request lifecycle: boot() runs on every request, then mount() once.
+    await page.onBoot();
+    await page.onMount();
+
+    const t = new FlowTest<T>(page, PageClass.name);
+    await t._render();
+    return t;
+  }
+
+  // ── Actions ────────────────────────────────────────────────────────────────
+
+  /**
+   * Set a property value directly (state seeding), then return for chaining.
+   * Does NOT fire the updating/updated hooks — use `update()` to simulate a
+   * client-driven property change.
+   * @category Actions
+   */
+  async set(prop: keyof T, value: unknown): Promise<this> {
+    (this._page as Record<string, unknown>)[prop as string] = value;
+    return this;
+  }
+
+  /**
+   * Simulate a client-driven property update (as a `value`/`checked` input or
+   * `$flow.$set` would produce): routes through the allowlist and fires the
+   * `onUpdating()` / `onUpdated()` hooks (and their per-property variants), then
+   * re-renders.
+   * @category Actions
+   */
+  async update(prop: keyof T, value: unknown): Promise<this> {
+    await this._page._applyClientUpdate(prop as string, value);
+    await this._render();
+    return this;
+  }
+
+  /**
+   * Call an action method and re-render. Simulates a subsequent (WebSocket) request:
+   * runs `onBoot()` + `onHydrate()`, invokes the method, then `onUpdate()` and re-render.
+   * If the action throws ValidationError, the errors are stored and the page re-renders
+   * with the error bag populated; any other thrown error is routed to `onError()`.
+   *
+   * @param method - Name of the method to invoke on the page.
+   * @param args - Arguments forwarded to the method.
+   * @throws If `method` is not a function on the page instance.
+   * @category Actions
+   */
+  async call(method: string, ...args: unknown[]): Promise<this> {
+    const fn = (this._page as Record<string, unknown>)[method];
+    if (typeof fn !== "function") {
+      throw new Error(`[FlowTest] Method "${method}" not found on ${this._name}`);
+    }
+
+    // Each call simulates a subsequent (WebSocket) request: boot() then hydrate().
+    await this._page.onBoot();
+    await this._page.onHydrate();
+
+    try {
+      await (fn as (...a: unknown[]) => unknown).apply(this._page, args);
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        // Errors already stored on page._errors
+      } else {
+        try {
+          await this._page.onError(error instanceof Error ? error : new Error(String(error)));
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    await this._page.onUpdate();
+    this._effects = this._page._drainEffects();
+    await this._render();
+    return this;
+  }
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+
+  private async _render(): Promise<void> {
+    const compId = this._page._flowId;
+
+    if (!this._effects) {
+      this._html = await _renderFlowPage(this._page, () => this._page.render()).catch(() => "");
+    } else {
+      if (!this._effects.redirectUrl) {
+        this._html = await _renderFlowPage(this._page, () => this._page.render()).catch(() => "");
+      }
+    }
+
+    // dehydrate() hook runs at the end of the request, before serialisation.
+    await this._page.onDehydrate();
+    this._snapshot = dehydrate(this._page, {
+      id: compId,
+      name: this._name,
+      path: this._page._flowPath,
+    });
+  }
+
+  // ── HTML assertions ────────────────────────────────────────────────────────
+
+  /**
+   * Assert the rendered HTML contains the given string.
+   * @category Assertions
+   */
+  assertSee(text: string): this {
+    if (!this._html.includes(text)) {
+      throw new Error(
+        `[FlowTest] Expected to see "${text}" but it was not found in:\n${this._html}`,
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Assert the rendered HTML does NOT contain the given string.
+   * @category Assertions
+   */
+  assertDontSee(text: string): this {
+    if (this._html.includes(text)) {
+      throw new Error(`[FlowTest] Expected NOT to see "${text}" but it was found in the HTML.`);
+    }
+    return this;
+  }
+
+  // ── Redirect assertions ────────────────────────────────────────────────────
+
+  /**
+   * Assert the last action redirected to the given URL.
+   * @category Assertions
+   */
+  assertRedirectedTo(url: string): this {
+    const actual = this._effects?.redirectUrl;
+    if (actual !== url) {
+      throw new Error(`[FlowTest] Expected redirect to "${url}" but got: ${actual ?? "(none)"}`);
+    }
+    return this;
+  }
+
+  /**
+   * Assert the last action did NOT redirect.
+   * @category Assertions
+   */
+  assertNotRedirected(): this {
+    if (this._effects?.redirectUrl) {
+      throw new Error(`[FlowTest] Expected no redirect but got: ${this._effects.redirectUrl}`);
+    }
+    return this;
+  }
+
+  // ── Validation assertions ──────────────────────────────────────────────────
+
+  /**
+   * Assert that a validation error exists for the given field, optionally that one of
+   * its messages contains `message`.
+   * @category Assertions
+   */
+  assertHasErrors(field: string, message?: string): this {
+    const errors = this._page._errors;
+    if (!errors[field] || errors[field]!.length === 0) {
+      throw new Error(`[FlowTest] Expected validation error for "${field}" but none found.`);
+    }
+    if (message && !errors[field]!.some((m) => m.includes(message))) {
+      throw new Error(
+        `[FlowTest] Expected error for "${field}" to contain "${message}" but got: ${errors[field]!.join(", ")}`,
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Assert no validation errors exist.
+   * @category Assertions
+   */
+  assertNoErrors(): this {
+    const count = Object.keys(this._page._errors).length;
+    if (count > 0) {
+      const summary = Object.entries(this._page._errors)
+        .map(([f, msgs]) => `  ${f}: ${msgs.join(", ")}`)
+        .join("\n");
+      throw new Error(`[FlowTest] Expected no validation errors but found:\n${summary}`);
+    }
+    return this;
+  }
+
+  // ── Flash assertions ───────────────────────────────────────────────────────
+
+  /**
+   * The full flash payloads emitted by the last action (title/position/duration/…).
+   * @category Assertions
+   */
+  flashes(): FlowEffects["flashes"] {
+    return this._effects?.flashes ?? [];
+  }
+
+  /**
+   * Assert a flash notification was emitted, optionally filtered by `level` and/or a
+   * substring of its `message`.
+   * @category Assertions
+   */
+  assertFlashed(level?: string, message?: string): this {
+    const flashes = this._effects?.flashes ?? [];
+    const match = flashes.find(
+      (f) => (!level || f.level === level) && (!message || f.message.includes(message)),
+    );
+    if (!match) {
+      const desc = [level, message].filter(Boolean).join("/");
+      throw new Error(
+        `[FlowTest] Expected flash "${desc}" but flashes were: ${JSON.stringify(flashes)}`,
+      );
+    }
+    return this;
+  }
+
+  // ── Event assertions ───────────────────────────────────────────────────────
+
+  /**
+   * Assert a cross-component event was dispatched by the last action.
+   * @category Assertions
+   */
+  assertDispatched(eventName: string): this {
+    const events = this._effects?.events ?? [];
+    if (!events.some((e) => e.name === eventName)) {
+      throw new Error(
+        `[FlowTest] Expected event "${eventName}" to be dispatched but it wasn't. Events: ${events.map((e) => e.name).join(", ") || "(none)"}`,
+      );
+    }
+    return this;
+  }
+
+  // ── State accessors ────────────────────────────────────────────────────────
+
+  /**
+   * Get the rendered HTML.
+   * @category State
+   */
+  html(): string {
+    return this._html;
+  }
+
+  /**
+   * Get the last drained effects (flashes, events, redirect, downloads).
+   * @category State
+   */
+  effects(): FlowEffects | null {
+    return this._effects;
+  }
+
+  /**
+   * Get the current page state snapshot.
+   * @category State
+   */
+  snapshot(): Snapshot | null {
+    return this._snapshot;
+  }
+
+  /**
+   * Get the current page instance (for direct property inspection).
+   * @category State
+   */
+  page(): T {
+    return this._page;
+  }
+
+  /**
+   * Get current validation errors.
+   * @category State
+   */
+  errors(): Record<string, string[]> {
+    return this._page._errors;
+  }
+}
+
+// ── Re-export hydrate for advanced use ────────────────────────────────────────
+export { hydrate } from "./dehydrate.ts";