@zerotal/flow 1.0.0

package/src/shared.ts

@@ -0,0 +1,226 @@
+// ── @shared support (server side) ─────────────────────────────────────────────
+//
+// `@shared` props are convergent, server-authoritative state bound to a broadcast
+// channel. A per-channel room store holds the canonical value; before every action the
+// prop is refilled from the store (read-latest), and after an action that changed it the
+// new value is written back and broadcast to the channel so other subscribers converge.
+//
+// Broadcasting is an OPTIONAL peer: flow does not depend on it. We resolve `Broadcast`
+// through a variable-specifier dynamic import (not type-checked, so no hard dependency)
+// and no-op gracefully when it isn't installed — the store still works in-process, so a
+// single-tab app converges within its own round-trips even without broadcasting.
+
+import type { Component } from "./Component.ts";
+import { getSharedProps, resolveSharedChannel } from "./decorators.ts";
+
+/**
+ * The wire event name the server broadcasts (and the client subscribes to) when
+ * one or more `@shared` props on a channel change, prompting subscribers to
+ * re-read the room store and converge.
+ */
+export const SHARED_EVENT = "flow:shared";
+
+// ── Room store ────────────────────────────────────────────────────────────────
+// Keyed by `channel::prop`. The default is an in-process Map (single-process apps and
+// the showcase). Multi-instance deployments swap in a Redis-backed store via
+// `setSharedStore()` — the same convergence logic then fans out across processes.
+
+/**
+ * Pluggable backing store for `@shared` room state — the canonical, per-channel
+ * value that all subscribers converge on.
+ *
+ * @remarks
+ * Keys are of the form `channel::prop`. Stored values are already deep-cloned by
+ * the caller, so the store may hold references without aliasing component state.
+ * The default is an in-process {@link MemorySharedStore}; swap a distributed
+ * implementation (e.g. Redis-backed) via {@link setSharedStore} to converge
+ * across processes. Implement all three methods synchronously.
+ */
+export interface SharedStore {
+  /** Read the current value for a `channel::prop` key, or `undefined` if unset. */
+  get(key: string): unknown | undefined;
+  /** Write the canonical value for a `channel::prop` key. */
+  set(key: string, value: unknown): void;
+  /** Whether a value has been stored for a `channel::prop` key. */
+  has(key: string): boolean;
+}
+
+class MemorySharedStore implements SharedStore {
+  private _map = new Map<string, unknown>();
+  get(key: string): unknown | undefined {
+    return this._map.get(key);
+  }
+  set(key: string, value: unknown): void {
+    this._map.set(key, value);
+  }
+  has(key: string): boolean {
+    return this._map.has(key);
+  }
+}
+
+let _store: SharedStore = new MemorySharedStore();
+
+/**
+ * Replace the process-wide backing store for `@shared` room state. Call this once
+ * at boot to move convergence off the default in-process map onto a distributed
+ * backend so it fans out across server instances.
+ *
+ * @param store - The store implementation to install.
+ *
+ * @example
+ * ```ts
+ * // boot: converge @shared state across all app instances via Redis.
+ * setSharedStore(new RedisSharedStore(redis));
+ * ```
+ */
+export function setSharedStore(store: SharedStore): void {
+  _store = store;
+}
+
+/**
+ * Get the active `@shared` room store (the in-process default, or whatever was
+ * installed via {@link setSharedStore}). Rarely needed in app code — `@shared`
+ * props read/write it automatically — but useful for tests or admin tooling that
+ * inspects room state directly.
+ *
+ * @returns The current {@link SharedStore}.
+ *
+ * @example
+ * ```tsx
+ * // A collaborative counter: every subscriber to `room.lobby` converges on `count`.
+ * class Counter extends Component {
+ *   @shared("room.lobby") count = 0;
+ *   @expose increment() { this.count++; } // written back + broadcast on commit
+ * }
+ * ```
+ */
+export function getSharedStore(): SharedStore {
+  return _store;
+}
+
+/** @internal Test hook — clear the default in-memory store between tests. */
+export function _resetSharedStore(): void {
+  _store = new MemorySharedStore();
+}
+
+function _key(channel: string, prop: string): string {
+  return `${channel}::${prop}`;
+}
+
+/** Deep-clone a value so the store and the component never alias the same reference. */
+function _clone<T>(value: T): T {
+  try {
+    return structuredClone(value);
+  } catch {
+    // Functions / class instances with methods aren't structured-cloneable — fall back to
+    // a JSON round-trip (the same shape the delta encoder already assumes for @shared props).
+    return JSON.parse(JSON.stringify(value)) as T;
+  }
+}
+
+// ── Broadcasting (optional peer) ───────────────────────────────────────────────
+
+interface BroadcastBuilder {
+  as(event: string): BroadcastBuilder;
+  with(data: unknown): BroadcastBuilder;
+  toOthers(): BroadcastBuilder;
+  send(): void;
+}
+interface BroadcastFacade {
+  presence(channel: string): BroadcastBuilder;
+}
+
+let _broadcast: BroadcastFacade | null | undefined;
+
+async function _resolveBroadcast(): Promise<BroadcastFacade | null> {
+  if (_broadcast !== undefined) return _broadcast;
+  try {
+    const spec = "@zerotal/broadcasting";
+    const mod = (await import(spec)) as { Broadcast?: BroadcastFacade };
+    _broadcast = mod.Broadcast ?? null;
+  } catch {
+    _broadcast = null; // broadcasting not installed → in-process convergence only
+  }
+  return _broadcast;
+}
+
+// ── Populate / snapshot / commit ────────────────────────────────────────────────
+
+/**
+ * Refill every `@shared` prop on `page` from the room store (server-authoritative
+ * read-latest). If a channel has no stored value yet, seed the store with the prop's
+ * current default so the first writer converges against a known baseline. Called before
+ * every action and on the initial GET; a no-op when the component has no `@shared` props.
+ */
+export function populateShared(page: Component): void {
+  const props = getSharedProps(page);
+  if (props.size === 0) return;
+  const store = _store;
+  const bag = page as unknown as Record<string, unknown>;
+  for (const [prop, channel] of props) {
+    const key = _key(resolveSharedChannel(channel, page), prop);
+    if (store.has(key)) {
+      bag[prop] = _clone(store.get(key));
+    } else {
+      store.set(key, _clone(bag[prop])); // seed with the current default
+    }
+  }
+}
+
+/**
+ * Capture the current `@shared` prop values (as stable JSON) so a later
+ * {@link commitShared} can detect which ones an action changed.
+ */
+export function snapshotSharedValues(page: Component): Map<string, string> {
+  const props = getSharedProps(page);
+  const before = new Map<string, string>();
+  if (props.size === 0) return before;
+  const bag = page as unknown as Record<string, unknown>;
+  for (const prop of props.keys()) before.set(prop, JSON.stringify(bag[prop]));
+  return before;
+}
+
+/**
+ * Write back every `@shared` prop whose value changed since `before`, then broadcast the
+ * change to its channel so other subscribers re-read and converge. Returns the names of
+ * the props that changed. No broadcast is sent when broadcasting isn't installed (the
+ * store is still updated, so same-process round-trips converge).
+ */
+export async function commitShared(
+  page: Component,
+  before: Map<string, string>,
+): Promise<string[]> {
+  const props = getSharedProps(page);
+  if (props.size === 0) return [];
+  const store = _store;
+  const bag = page as unknown as Record<string, unknown>;
+
+  // Group changed props by channel so one channel broadcasts a single event.
+  const changedByChannel = new Map<string, string[]>();
+  const changed: string[] = [];
+  for (const [prop, channel] of props) {
+    const now = JSON.stringify(bag[prop]);
+    if (now === before.get(prop)) continue;
+    const name = resolveSharedChannel(channel, page);
+    store.set(_key(name, prop), _clone(bag[prop]));
+    changed.push(prop);
+    (changedByChannel.get(name) ?? changedByChannel.set(name, []).get(name)!).push(prop);
+  }
+  if (changed.length === 0) return [];
+
+  const Broadcast = await _resolveBroadcast();
+  if (Broadcast) {
+    for (const [channel, propsForChannel] of changedByChannel) {
+      try {
+        Broadcast.presence(channel)
+          .as(SHARED_EVENT)
+          .with({ props: propsForChannel })
+          .toOthers()
+          .send();
+      } catch {
+        /* broadcasting misconfigured — the store is still authoritative for new GETs */
+      }
+    }
+  }
+  return changed;
+}

package/src/store.ts

@@ -0,0 +1,116 @@
+// ── Global client store — a single Alpine store named "flow" ────────────────────
+//
+// App-wide, client-only UI state the SERVER never needs to see: theme, sidebar open/closed,
+// a command-palette's visibility, an unsaved-changes flag. It IS an Alpine store — Alpine
+// already gives us a global, reactive, dependency-tracked store, so we don't reinvent it.
+// Everything lives under one store, `flow`, and `$flow.$store` returns it:
+//
+//   <button onClick={() => ($flow.store.ui.dark = !$flow.store.ui.dark)}>Toggle</button>
+//   <div class={$flow.store.ui.dark ? "dark" : ""}>…</div>
+//   <span>{$flow.store.cart.count} items</span>
+//
+// Reads compile to Alpine bindings (x-text / :class / x-show) and re-render with no round-trip;
+// writes mutate the reactive store directly. Declare the shape with defineStore().
+//
+// Division of labour:
+//   • $flow.store — live cross-component UI state the server never sees.
+//   • @session    — a preference that must survive a refresh (persisted server-side).
+//   • @expose     — state one component owns and the server may reconcile.
+//
+// Dependency-free (no @zerotal/core import) so it's safe in the browser runtime bundle.
+
+/**
+ * The shape of the global client store (`$flow.store`). Declare your namespaces by augmenting
+ * this interface, which makes every `$flow.store.*` access fully typed:
+ *
+ * ```ts
+ * // resources/js/env.d.ts — augment the /store subpath, where the interface is declared.
+ * declare module "@zerotal/flow/store" {
+ *   interface FlowStore {
+ *     ui: { dark: boolean; sidebar: boolean };
+ *     cart: { count: number };
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface FlowStore {}
+
+/** The one Alpine store name that backs `$flow.store`. */
+const STORE_NAME = "flow";
+
+/** The slice of Alpine we use (register/read a named store). */
+interface AlpineStores {
+  store(name: string): Record<string, unknown> | undefined;
+  store(name: string, value: Record<string, unknown>): void;
+}
+
+type GlobalWithAlpine = typeof globalThis & {
+  Alpine?: AlpineStores;
+  __flowStoreInit?: Array<Record<string, unknown>>;
+};
+
+function _g(): GlobalWithAlpine {
+  return globalThis as GlobalWithAlpine;
+}
+
+/** Recursively fill defaults into `target` WITHOUT overwriting values already present. */
+function _mergeDefaults(target: Record<string, unknown>, src: Record<string, unknown>): void {
+  for (const [k, v] of Object.entries(src)) {
+    const cur = target[k];
+    if (
+      v &&
+      typeof v === "object" &&
+      !Array.isArray(v) &&
+      cur &&
+      typeof cur === "object" &&
+      !Array.isArray(cur)
+    ) {
+      _mergeDefaults(cur as Record<string, unknown>, v as Record<string, unknown>);
+    } else if (!(k in target)) {
+      target[k] = v;
+    }
+  }
+}
+
+/** Merge `initial` (defaults only) into the reactive "flow" Alpine store, registering it if new. */
+function _seed(A: AlpineStores, initial: Record<string, unknown>): void {
+  if (!A.store(STORE_NAME)) A.store(STORE_NAME, {});
+  _mergeDefaults(A.store(STORE_NAME)!, initial); // mutating the reactive store keeps bindings live
+}
+
+/**
+ * Declare (or extend) the client store's initial shape — call once at app start:
+ *
+ * ```ts
+ * // resources/js/app.ts — import from the browser-safe /store subpath, not the package barrel.
+ * import { defineStore } from "@zerotal/flow/store";
+ * defineStore({ ui: { dark: false, sidebar: true }, cart: { count: 0 } });
+ * ```
+ *
+ * Existing values are preserved (defaults only). Safe to call before OR after the Flow runtime
+ * boots — a call made before Alpine exists is queued and applied when the store is registered.
+ */
+export function defineStore(initial: Record<string, unknown>): void {
+  const g = _g();
+  if (g.Alpine?.store) _seed(g.Alpine, initial);
+  else (g.__flowStoreInit ??= []).push(initial);
+}
+
+/**
+ * @internal Register the "flow" Alpine store and apply any defineStore() calls queued before
+ * Alpine existed. Called once by the client entry, before `Alpine.start()`. Idempotent.
+ */
+export function initClientStore(alpine: AlpineStores): Record<string, unknown> {
+  if (!alpine.store(STORE_NAME)) alpine.store(STORE_NAME, {});
+  const g = _g();
+  for (const partial of g.__flowStoreInit ?? []) _seed(alpine, partial);
+  g.__flowStoreInit = [];
+  return alpine.store(STORE_NAME)!;
+}
+
+/** @internal The reactive "flow" store object (Alpine-owned), or `{}` before Alpine is ready. */
+export function clientStore(): Record<string, unknown> {
+  const A = _g().Alpine;
+  return (A?.store && A.store(STORE_NAME)) || {};
+}

package/src/synths/CarbonIntervalSynth.ts

@@ -0,0 +1,22 @@
+// Synth (key "cbi") for CarbonInterval durations: serializes to an ISO 8601
+// duration string (e.g. "P1DT2H30M") and hydrates back to a CarbonInterval.
+// Registered as a side effect of importing this module.
+import { CarbonInterval } from "@zerotal/core/carbon";
+import { registerSynth } from "./index.ts";
+
+registerSynth({
+  key: "cbi",
+
+  match(value): value is CarbonInterval {
+    return value instanceof CarbonInterval;
+  },
+
+  dehydrate(value: CarbonInterval, _meta) {
+    // Serialise as ISO 8601 duration string: "P1DT2H30M"
+    return value.toISO();
+  },
+
+  hydrate(data, _meta) {
+    return CarbonInterval.fromISO(data as string);
+  },
+});

package/src/synths/CarbonSynth.ts

@@ -0,0 +1,20 @@
+// Synth (key "cbn") for Carbon datetimes: serializes to an ISO 8601 string and
+// hydrates back to a Carbon. Registered as a side effect of importing this module.
+import { Carbon } from "@zerotal/core/carbon";
+import { registerSynth } from "./index.ts";
+
+registerSynth({
+  key: "cbn",
+
+  match(value): value is Carbon {
+    return value instanceof Carbon;
+  },
+
+  dehydrate(value: Carbon, _meta) {
+    return value.toISOString();
+  },
+
+  hydrate(data, _meta) {
+    return new Carbon(data as string);
+  },
+});

package/src/synths/CollectionSynth.ts

@@ -0,0 +1,62 @@
+// Synth (key "col") for arrays of ORM models: dehydrates a non-empty array of
+// registered models to their ids (tagged with the model class name) and hydrates
+// it back with a single `whereIn("id", ids)` query. Registered as a side effect
+// of importing this module. Matches only when the array's first element is a
+// registered model, so plain arrays fall through to the recursive serializer.
+import type { BaseModel } from "@zerotal/orm";
+import { registerSynth } from "./index.ts";
+import { _modelRegistry, _modelClassToName } from "./ModelSynth.ts";
+
+function isModelOf(value: unknown, ctor: typeof BaseModel): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as object).constructor === ctor &&
+    typeof (value as Record<string, unknown>)["id"] !== "undefined"
+  );
+}
+
+registerSynth({
+  key: "col",
+
+  match(value): value is BaseModel[] {
+    if (!Array.isArray(value) || value.length === 0) return false;
+    const first = value[0] as unknown;
+    if (typeof first !== "object" || first === null) return false;
+    // Key off the constructor, not constructor.name, so the match survives
+    // minification (same hardening as ModelSynth).
+    const ctor = (first as object).constructor as typeof BaseModel;
+    if (!_modelClassToName.has(ctor)) return false;
+    // Only claim a homogeneous array. A mixed array would be dehydrated under a
+    // single class tag and silently lose the odd-one-out on hydrate, so let it
+    // fall through to the recursive serializer, which handles each model via
+    // ModelSynth.
+    return value.every((m) => isModelOf(m, ctor));
+  },
+
+  dehydrate(value: BaseModel[], meta) {
+    const ctor = (value[0] as object).constructor as typeof BaseModel;
+    meta["class"] = _modelClassToName.get(ctor)!;
+    return value.map((m) => (m as unknown as Record<string, unknown>)["id"]);
+  },
+
+  async hydrate(data, meta) {
+    const cls = meta["class"] as string | undefined;
+    if (!cls) throw new Error("[Flow] CollectionSynth: missing class in meta");
+    const Model = _modelRegistry.get(cls);
+    if (!Model) {
+      throw new Error(
+        `[Flow] Model "${cls}" is not registered. ` +
+          `Add it to your Component's static models property.`,
+      );
+    }
+    const ids = data as unknown[];
+    return (
+      Model as unknown as {
+        whereIn(col: string, vals: unknown[]): { get(): Promise<BaseModel[]> };
+      }
+    )
+      .whereIn("id", ids)
+      .get();
+  },
+});

package/src/synths/DateSynth.ts

@@ -0,0 +1,24 @@
+// Synth (key "dt") for plain JS Dates: serializes to an ISO string and hydrates
+// back to a Date. Because Carbon extends Date, this synth deliberately excludes
+// Carbon instances so they route to CarbonSynth instead. Registered as a side
+// effect of importing this module.
+import { Carbon } from "@zerotal/core/carbon";
+import { registerSynth } from "./index.ts";
+
+registerSynth({
+  key: "dt",
+
+  match(value): value is Date {
+    // Plain Date — Carbon is a subclass of Date so check it first via CarbonSynth;
+    // this synth only fires for non-Carbon Dates.
+    return value instanceof Date && !(value instanceof Carbon);
+  },
+
+  dehydrate(value: Date, _meta) {
+    return value.toISOString();
+  },
+
+  hydrate(data, _meta) {
+    return new Date(data as string);
+  },
+});

package/src/synths/ModelSynth.ts

@@ -0,0 +1,78 @@
+import type { BaseModel } from "@zerotal/orm";
+import { registerSynth } from "./index.ts";
+
+// Models register themselves here when their class is imported.
+// Populated via registerFlowModel() called in the Component's static `models` map.
+export const _modelRegistry = new Map<string, typeof BaseModel>();
+
+// Reverse map: class constructor → stable developer-assigned name.
+// Using this instead of constructor.name prevents breakage under minification,
+// where `Post` might be mangled to `n`. Exported so CollectionSynth shares the
+// same minification-safe lookup.
+export const _modelClassToName = new Map<typeof BaseModel, string>();
+
+/**
+ * Register an ORM model class under a stable name so the model synth can send it
+ * across the wire: a model prop is dehydrated to its `id` (tagged with this name)
+ * and hydrated back by re-fetching via `findOrFail`.
+ *
+ * @remarks
+ * Registering by an explicit name (rather than `constructor.name`) keeps snapshots
+ * valid under minification, where the class name may be mangled. You normally don't
+ * call this directly — declare models in a component's `static models` map and the
+ * framework registers them when the page is registered.
+ *
+ * @param name - Stable, developer-assigned name recorded in the snapshot's `meta.class`.
+ * @param ModelClass - The `BaseModel` subclass to associate with `name`.
+ *
+ * @example
+ * ```tsx
+ * class ShowPost extends Component {
+ *   static models = { Post }; // auto-calls registerFlowModel("Post", Post)
+ *   @locked post!: Post;      // survives the round-trip as a rehydrated model
+ * }
+ *
+ * // Or register manually (e.g. outside a page's static models):
+ * registerFlowModel("Post", Post);
+ * ```
+ */
+export function registerFlowModel(name: string, ModelClass: typeof BaseModel): void {
+  _modelRegistry.set(name, ModelClass);
+  _modelClassToName.set(ModelClass, name);
+}
+
+registerSynth({
+  key: "mdl",
+
+  match(value): value is BaseModel {
+    // Lazy check: duck-type for BaseModel (avoids circular import of BaseModel class)
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      typeof (value as Record<string, unknown>)["id"] !== "undefined" &&
+      typeof (value as Record<string, unknown>)["constructor"] === "function" &&
+      _modelClassToName.has((value as object).constructor as typeof BaseModel)
+    );
+  },
+
+  dehydrate(value: BaseModel, meta) {
+    // Use the stable registered name rather than constructor.name, which is
+    // mangled in minified production builds.
+    meta["class"] = _modelClassToName.get((value as object).constructor as typeof BaseModel)!;
+    return (value as unknown as Record<string, unknown>)["id"];
+  },
+
+  async hydrate(data, meta) {
+    const cls = meta["class"] as string | undefined;
+    if (!cls) throw new Error("[Flow] ModelSynth: missing class in meta");
+    const Model = _modelRegistry.get(cls);
+    if (!Model) {
+      throw new Error(
+        `[Flow] Model "${cls}" is not registered. ` +
+          `Add it to your Component's static models property.`,
+      );
+    }
+    // BaseModel.findOrFail is a static method
+    return (Model as unknown as { findOrFail(id: unknown): Promise<BaseModel> }).findOrFail(data);
+  },
+});

package/src/synths/TemporaryUploadedFileSynth.ts

@@ -0,0 +1,19 @@
+import { registerSynth } from "./index.ts";
+import { TemporaryUploadedFile, type TufData } from "../uploads/TemporaryUploadedFile.ts";
+
+// Synth (key "tuf") that lets a TemporaryUploadedFile property round-trip through
+// the (HMAC-signed) snapshot: dehydrates to its plain TufData ref and hydrates via
+// fromTrustedRef (no per-ref signature check, since the whole snapshot is signed).
+// Registered as a side effect of importing this module.
+registerSynth({
+  key: "tuf",
+  match(value): value is TemporaryUploadedFile {
+    return value instanceof TemporaryUploadedFile;
+  },
+  dehydrate(value: TemporaryUploadedFile) {
+    return value.toRef();
+  },
+  hydrate(data) {
+    return TemporaryUploadedFile.fromTrustedRef(data as TufData);
+  },
+});