@xoong/data 0.0.0-stage → 0.0.35

package/src/format.js

@@ -0,0 +1,55 @@
+// @ts-check
+/**
+ * Display formats for interpolation: `{publishedAt | datetime}`, `{total | number}`, `{createdAt | relative}`.
+ * They use Intl (the platform), the page language (`<html lang>`, else the browser's), and never throw on bad input: a value that
+ * cannot be formatted is shown as it is. Add your own with `setFormat('money', (v) => ...)`.
+ */
+
+/** @type {(() => string) | null} */
+let localeSource = null;
+/** The i18n package says which language is active; without it the page language (`<html lang>`) or the browser's is used. */
+export function setLocaleSource(fn) { localeSource = fn; }
+export function locale() {
+  return localeSource?.() || globalThis.document?.documentElement?.lang || globalThis.navigator?.language || 'en';
+}
+const asDate = (v) => { const d = new Date(v); return Number.isNaN(d.getTime()) ? null : d; };
+
+const UNITS = /** @type {[Intl.RelativeTimeFormatUnit, number][]} */ ([['year', 31536000], ['month', 2592000], ['week', 604800], ['day', 86400], ['hour', 3600], ['minute', 60], ['second', 1]]);
+
+/** @type {Map<string, (value: any, locale?: string) => string>} */
+const formats = new Map([
+  ['date', (v, loc = locale()) => { const d = asDate(v); return d ? new Intl.DateTimeFormat(loc, { dateStyle: 'medium' }).format(d) : String(v); }],
+  ['datetime', (v, loc = locale()) => { const d = asDate(v); return d ? new Intl.DateTimeFormat(loc, { dateStyle: 'medium', timeStyle: 'short' }).format(d) : String(v); }],
+  ['time', (v, loc = locale()) => { const d = asDate(v); return d ? new Intl.DateTimeFormat(loc, { timeStyle: 'short' }).format(d) : String(v); }],
+  ['relative', (v, loc = locale()) => {
+    const d = asDate(v);
+    if (!d) return String(v);
+    const seconds = Math.round((d.getTime() - Date.now()) / 1000);
+    const [unit, size] = UNITS.find(([, s]) => Math.abs(seconds) >= s) ?? ['second', 1];
+    return new Intl.RelativeTimeFormat(loc, { numeric: 'auto' }).format(Math.round(seconds / size), unit);
+  }],
+  ['number', (v, loc = locale()) => (Number.isFinite(Number(v)) && v !== '' ? new Intl.NumberFormat(loc).format(Number(v)) : String(v))],
+  ['json', (v) => JSON.stringify(v)],
+  // content in several languages: { en: 'Hello', vi: 'Xin chào' } -> the active language, then its base language, then English, then whatever is filled
+  ['localized', (v) => {
+    if (v === null || typeof v !== 'object') return String(v);
+    const loc = locale();
+    const pick = v[loc] ?? v[loc.split('-')[0]] ?? v.en ?? Object.values(v).find((x) => x !== '' && x != null);
+    return pick == null ? '' : String(pick);
+  }],
+]);
+const warned = new Set();
+
+/** Register or replace a format. @param {string} name @param {(value: any, locale?: string) => string} fn */
+export function setFormat(name, fn) { formats.set(name, fn); }
+
+/** Format a value; nothing (null, undefined) is an empty string; an unknown format name is reported once and shows the plain value. */
+export function format(name, value, loc) {
+  if (value === undefined || value === null) return '';
+  const fn = formats.get(name);
+  if (!fn) {
+    if (!warned.has(name)) { warned.add(name); console.error(`xoong: unknown format "${name}" in {path | ${name}} (known: ${[...formats.keys()].join(', ')})`); }
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+  }
+  try { return fn(value, loc); } catch { return String(value); }
+}

package/src/index.d.ts

@@ -0,0 +1,83 @@
+// Types for @xoong/data. The runtime is plain JavaScript; this file adds the typed client.
+// Use it with the file `xoong sync` generates:
+//
+//   import type { Operations } from './.xoong/api.d.ts';
+//   const client = createClient<Operations>({ api, baseUrl: '/api' });
+//   const page = await client.load('listUsers', { limit: 10 });   // page: UserPage
+//   await client.mutate('createUser', {}, { name: 'Ada' });       // body is checked
+
+/** Shape of one entry of the generated `Operations` interface. */
+export interface OperationType { method: string; path: string; params: any; body: any; response: any }
+
+/** Arguments after the operation name: params may be left out when the operation has none that are required. */
+type ParamsArg<O extends OperationType> = {} extends O['params'] ? [params?: O['params']] : [params: O['params']];
+type Id<Ops> = keyof Ops & string;
+
+type Signal<T> = { readonly value: T; peek(): T };
+
+export class XoongError extends Error {
+  status: number;
+  title?: string;
+  detail?: string;
+  code?: string;
+  retryAfterS?: number;
+  problem?: any;
+  operation?: string;
+  /** Per-field messages when the server reports them (`{ email: 'is not valid' }`). */
+  fields: Record<string, string>;
+}
+
+export interface ClientOptions {
+  /** Contents of .xoong/operations.json */
+  api: { operations: Record<string, any>; entities?: Record<string, any> };
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  headers?: () => Record<string, string> | Promise<Record<string, string>>;
+  credentials?: RequestCredentials;
+  staleTime?: number;
+  gcTime?: number;
+  evictEntities?: boolean;
+  retry?: number;
+  retryDelay?: number;
+  invalidate?: Record<string, string[]>;
+  onError?: (e: XoongError) => void;
+  onUnauthorized?: (e: XoongError) => void;
+  streamUrl?: string;
+}
+
+export interface SseEvent { event: string; data: string; json?: unknown; id?: string }
+
+export interface TypedQuery<O extends OperationType> {
+  readonly data: Signal<O['response'] | undefined>;
+  readonly status: Signal<'idle' | 'loading' | 'success' | 'error'>;
+  readonly error: Signal<XoongError | null>;
+  retain(): void;
+  release(): void;
+  invalidate(): void;
+  fetch(): Promise<O['response']>;
+}
+
+/**
+ * `Ops` is the generated `Operations` interface. Without it every operation name is a string and nothing is checked.
+ */
+export interface Client<Ops extends Record<keyof Ops, OperationType> = any> {
+  store: unknown;
+  op(ref: string): any;
+  query<K extends Id<Ops>>(op: K, ...params: ParamsArg<Ops[K]>): TypedQuery<Ops[K]>;
+  load<K extends Id<Ops>>(op: K, ...params: ParamsArg<Ops[K]>): Promise<Ops[K]['response']>;
+  /** Put data the server already has into the cache as if the GET had run (no request until it is stale). */
+  seed<K extends Id<Ops>>(op: K, params: Ops[K] extends { params: infer P } ? P : never, data: Ops[K]['response']): Ops[K]['response'];
+  mutate<K extends Id<Ops>>(op: K, params: Ops[K]['params'], ...body: [Ops[K]['body']] extends [never] ? [] : [body: Ops[K]['body']]): Promise<Ops[K]['response']>;
+  stream<K extends Id<Ops>>(op: K, params: Ops[K]['params'], body?: Ops[K]['body'], options?: { signal?: AbortSignal }): AsyncGenerator<SseEvent>;
+  invalidateAll(): void;
+  readonly pending: number;
+  readonly size: number;
+}
+
+export function createClient<Ops extends Record<keyof Ops, OperationType> = any>(options: ClientOptions): Client<Ops>;
+export function configure<Ops extends Record<keyof Ops, OperationType> = any>(options: ClientOptions): Client<Ops>;
+export function getClient<Ops extends Record<keyof Ops, OperationType> = any>(): Client<Ops>;
+export function derived<T>(fn: (ctx: { all(name: string): any[]; get(name: string, id: string | number): any }) => T, client?: Client<any>): Signal<T>;
+export function connectStream(options: { client: Client<any>; url: string; EventSource?: typeof EventSource; onStatus?: (s: 'open' | 'error' | 'closed') => void; onError?: (e: Error) => void }): { close(): void };
+export function createStore(entityDefs?: Record<string, any>): unknown;
+export function isRef(v: unknown): v is { $ref: string };

package/src/index.js

@@ -0,0 +1,5 @@
+export { createClient, XoongError } from './client.js';
+export { configure, getClient } from './default.js';
+export { derived } from './derived.js';
+export { createStore, isRef } from './store.js';
+export { connectStream } from './stream.js';

package/src/invalidate.js

@@ -0,0 +1,29 @@
+// @ts-check
+/**
+ * Default invalidation rule, derived from REST path structure.
+ *
+ * A mutation on `/users/42/disable` invalidates cached queries whose concrete
+ * path is a segment-prefix of it or that it is a segment-prefix of:
+ *   GET /users            (prefix of the mutation)        -> invalidated
+ *   GET /users/42         (prefix of the mutation)        -> invalidated
+ *   GET /users/42/posts   (neither is a prefix)           -> kept
+ *   GET /users/43         (differs at a segment)          -> kept
+ */
+const segments = (p) => p.split('/').filter(Boolean);
+
+/** @param {string} a concrete path @param {string} b concrete path */
+export function pathsOverlap(a, b) {
+  const x = segments(a), y = segments(b);
+  const n = Math.min(x.length, y.length);
+  for (let i = 0; i < n; i++) if (x[i] !== y[i]) return false;
+  return true;
+}
+
+/** Fill `{param}` placeholders and encode values. Throws naming a missing param. */
+export function fillPath(template, params = {}, opId = template) {
+  return template.replace(/\{([^}]+)\}/g, (_, name) => {
+    const v = params[name];
+    if (v === undefined || v === null) throw new Error(`xoong: operation "${opId}" needs path parameter "${name}"`);
+    return encodeURIComponent(String(v));
+  });
+}

package/src/options.js

@@ -0,0 +1,62 @@
+// @ts-check
+/**
+ * Options from the API for a combobox or a tag input, declared in markup:
+ *
+ *   <xo-combobox name="categoryIds" multiple options-op="listCategories" option-value="id" option-label="name.en"></xo-combobox>
+ *
+ * `options-op` is a GET operation (an operationId or "/path"); `p-<name>` attributes are its parameters, as on <xo-view>. The list is the
+ * response itself, or its `items` (or `data`) member. `option-value` and `option-label` are paths in each item ("id", "name.en"); they
+ * default to `value` and `label`, then to `id` and `name`. The data comes from the shared cache, so a mutation that touches the list
+ * (a category added elsewhere on the page) refreshes the options by itself. Importing `@xoong/data/view` turns this on.
+ */
+import { effect } from '@xoong/core/signals';
+import { getClient } from './default.js';
+
+const camel = (/** @type {string} */ s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const pick = (/** @type {any} */ item, /** @type {string[]} */ paths) => {
+  for (const path of paths) {
+    let v = item;
+    for (const step of path.split('.')) v = v?.[step];
+    if (v != null && typeof v !== 'object') return String(v);
+  }
+  return '';
+};
+const stops = new WeakMap();
+
+/** @param {any} el */
+function start(el) {
+  if (stops.has(el)) return;
+  const ref = el.getAttribute('options-op');
+  if (!ref) return;
+  /** @type {Record<string, string>} */ const params = {};
+  for (const a of el.attributes) if (a.name.startsWith('p-')) params[camel(a.name.slice(2))] = a.value;
+  const valueAt = el.getAttribute('option-value');
+  const labelAt = el.getAttribute('option-label');
+  let query;
+  try { query = getClient().query(ref.startsWith('/') ? `GET ${ref}` : ref, params); } catch (e) { console.error(e); return; }
+  query.retain();
+  const stop = effect(() => {
+    const data = query.data.value;
+    const list = Array.isArray(data) ? data : (data?.items ?? data?.data ?? []);
+    el.options = (Array.isArray(list) ? list : []).map((item) => (typeof item === 'object' && item
+      ? { value: pick(item, [valueAt ?? 'value', 'id']), label: pick(item, [labelAt ?? 'label', 'name', 'title', valueAt ?? 'id']) }
+      : String(item)));
+  });
+  stops.set(el, () => { stop(); query.release(); });
+}
+
+const scan = (/** @type {ParentNode} */ root) => { for (const el of root.querySelectorAll?.('[options-op]') ?? []) start(el); };
+const clean = (/** @type {Node} */ node) => { for (const el of [node, ...((/** @type {any} */ (node)).querySelectorAll?.('[options-op]') ?? [])]) { stops.get(el)?.(); stops.delete(el); } };
+
+if (typeof document !== 'undefined' && typeof MutationObserver !== 'undefined') {
+  const watch = () => {
+    scan(document);
+    new MutationObserver((records) => {
+      for (const r of records) {
+        for (const n of r.removedNodes) if (n.nodeType === 1 && !(/** @type {Element} */ (n)).isConnected) clean(n);
+        for (const n of r.addedNodes) if (n.nodeType === 1) { if (/** @type {Element} */ (n).hasAttribute('options-op')) start(n); scan(/** @type {Element} */ (n)); }
+      }
+    }).observe(document.documentElement, { childList: true, subtree: true });
+  };
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', watch, { once: true }); else queueMicrotask(watch);
+}

package/src/pointer.js

@@ -0,0 +1,28 @@
+// @ts-check
+/** RFC 6901 JSON Pointer helpers (copy-on-write set). */
+
+/** @param {string} p */
+export function parsePointer(p) {
+  if (p === '' ) return [];
+  if (!p.startsWith('/')) throw new Error(`xoong: invalid JSON pointer "${p}" (must start with "/")`);
+  return p.slice(1).split('/').map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+
+const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Return a copy of `obj` with `value` set at `pointer`. Never mutates `obj`.
+ * @param {any} obj @param {string} pointer @param {any} value
+ */
+export function setPointer(obj, pointer, value) {
+  const parts = parsePointer(pointer);
+  if (parts.length === 0) return value;
+  for (const part of parts) if (FORBIDDEN.has(part)) throw new Error(`xoong: forbidden pointer segment "${part}"`);
+  const walk = (node, i) => {
+    const key = parts[i];
+    const base = Array.isArray(node) ? [...node] : { ...(node && typeof node === 'object' ? node : {}) };
+    base[key] = i === parts.length - 1 ? value : walk(base[key], i + 1);
+    return base;
+  };
+  return walk(obj, 0);
+}

package/src/store.js

@@ -0,0 +1,285 @@
+// @ts-check
+import { signal, batch } from '@xoong/core/signals';
+import { setPointer } from './pointer.js';
+
+/** A reference to a stored entity: { $ref: "User#42" } */
+export const isRef = (v) => !!v && typeof v === 'object' && typeof v.$ref === 'string';
+export const refKey = (name, id) => `${name}#${id}`;
+const shallowEqual = (a, b) => {
+  const ka = Object.keys(a), kb = Object.keys(b);
+  return ka.length === kb.length && ka.every((k) => Object.is(a[k], b[k]));
+};
+
+/**
+ * Normalized entity store. Every entity is one signal, so a change made by a
+ * mutation, a refetch or a stream event is seen by every screen reading it.
+ *
+ * @param {Record<string, { id: string, props?: Record<string, any> }>} [entityDefs]
+ */
+export function createStore(entityDefs = {}) {
+  /**
+   * One signal per entity key, kept even after deletion (value undefined) so that
+   * readers stay subscribed and see an entity that is deleted and later re-created.
+   * @type {Map<string, import('@xoong/core/signals').Signal<any>>}
+   */
+  const entities = new Map();
+  /** @type {Map<string, Set<string>>} entity name -> ids that currently exist */
+  const ids = new Map();
+  /** @type {Map<string, import('@xoong/core/signals').Signal<number>>} */
+  const indexTick = new Map();
+  /** Last applied stream version per entity; deletes keep theirs so late events cannot resurrect. */
+  const versions = new Map();
+
+  const tick = (name) => {
+    let s = indexTick.get(name);
+    if (!s) indexTick.set(name, (s = signal(0)));
+    return s;
+  };
+  const bump = (name) => { const s = tick(name); s.value = s.peek() + 1; };
+  const slot = (key) => {
+    let s = entities.get(key);
+    if (!s) entities.set(key, (s = signal(undefined)));
+    return s;
+  };
+  const exists = (key) => entities.get(key)?.peek() !== undefined;
+
+  const store = {
+    defs: entityDefs,
+
+    /** Insert or merge an entity record (already normalized: nested entities are refs). */
+    upsert(name, id, record, { replace = false } = {}) {
+      const key = refKey(name, id);
+      const sig = slot(key);
+      const current = sig.peek();
+      if (current !== undefined) {
+        const next = replace ? { ...record } : { ...current, ...record };
+        if (!shallowEqual(current, next)) sig.value = next;
+      } else {
+        batch(() => {
+          sig.value = { ...record };
+          if (!ids.has(name)) ids.set(name, new Set());
+          ids.get(name).add(String(id));
+          bump(name);
+        });
+      }
+      return { $ref: key };
+    },
+
+    /** Remove an entity. References to it resolve to undefined afterwards. */
+    remove(name, id) {
+      const key = refKey(name, id);
+      if (!exists(key)) return;
+      batch(() => {
+        ids.get(name)?.delete(String(id));
+        entities.get(key).value = undefined; // notify readers; the slot stays for re-creation
+        bump(name);
+      });
+    },
+
+    /** Tracked read of one entity record (nested entities remain refs). Tracks even when absent. */
+    read(key) {
+      return slot(key).value;
+    },
+
+    /**
+     * Tracked existence check. Subscribes to adds/removes of that entity type
+     * only (not to field changes), so lists can drop deleted rows cheaply.
+     */
+    has(ref) {
+      const name = ref.$ref.slice(0, ref.$ref.indexOf('#'));
+      tick(name).value;
+      return exists(ref.$ref);
+    },
+
+    /** Resolve a ref to its record (tracked); other values pass through. */
+    deref(v) {
+      return isRef(v) ? store.read(v.$ref) : v;
+    },
+
+    /** Tracked list of all loaded entity refs of a type. */
+    refs(name) {
+      tick(name).value; // subscribe to adds/removes
+      return [...(ids.get(name) ?? [])].map((id) => ({ $ref: refKey(name, id) }));
+    },
+
+    /** Deeply resolve refs into plain objects (tracked). Cycles are cut. */
+    denormalize(v, seen = new Set()) {
+      if (isRef(v)) {
+        if (seen.has(v.$ref)) return v;
+        const rec = store.read(v.$ref);
+        if (rec === undefined) return undefined;
+        const next = new Set(seen).add(v.$ref);
+        return store.denormalize(rec, next);
+      }
+      if (Array.isArray(v)) {
+        // References to deleted entities drop out of lists instead of leaving holes.
+        return v.map((x) => store.denormalize(x, seen)).filter((x, i) => !(x === undefined && isRef(v[i])));
+      }
+      if (v && typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v)) {
+          Object.defineProperty(out, k, { value: store.denormalize(v[k], seen), enumerable: true, writable: true, configurable: true });
+        }
+        return out;
+      }
+      return v;
+    },
+
+    /**
+     * Apply one stream event. Returns true if applied, false if dropped
+     * (stale version, unknown entity, malformed).
+     * Events: {type:'patch'|'upsert'|'delete', entity, id, path?, value?, version?}
+     */
+    applyEvent(ev) {
+      if (!ev || typeof ev !== 'object' || typeof ev.entity !== 'string' || ev.id == null) return false;
+      const key = refKey(ev.entity, ev.id);
+      if (typeof ev.version === 'number') {
+        const seen = versions.get(key);
+        if (seen !== undefined && ev.version <= seen) return false;
+      }
+      let applied = false;
+      if (ev.type === 'delete') {
+        if (exists(key)) { store.remove(ev.entity, ev.id); applied = true; }
+      } else if (ev.type === 'upsert') {
+        if (ev.value && typeof ev.value === 'object') {
+          store.upsert(ev.entity, ev.id, normalizeRecord(store, ev.entity, ev.value));
+          applied = true;
+        }
+      } else if (ev.type === 'patch') {
+        const sig = entities.get(key);
+        if (sig && exists(key) && typeof ev.path === 'string') {
+          const next = setPointer(sig.peek(), ev.path, ev.value);
+          if (!shallowEqual(sig.peek(), next)) sig.value = next;
+          applied = true;
+        }
+      }
+      if (applied && typeof ev.version === 'number') versions.set(key, ev.version);
+      return applied;
+    },
+
+    /**
+     * Apply a provisional change to an existing entity (an optimistic update). Returns an undo function that puts back only
+     * the fields that still hold the provisional value, so a newer change from the server or another screen is not erased.
+     * Does nothing (returns a no-op) when the entity is not loaded.
+     * @param {string} key "Name#id"
+     * @param {Record<string, any>} patch
+     */
+    optimistic(key, patch) {
+      const sig = entities.get(key);
+      const prev = sig?.peek();
+      if (prev === undefined) return () => {};
+      const next = { ...prev, ...patch };
+      if (!shallowEqual(prev, next)) sig.value = next;
+      return () => {
+        const now = sig.peek();
+        if (now === undefined) return;
+        const back = { ...now };
+        for (const k of Object.keys(patch)) if (Object.is(now[k], patch[k])) { if (k in prev) back[k] = prev[k]; else delete back[k]; }
+        if (!shallowEqual(now, back)) sig.value = back;
+      };
+    },
+
+    /** Forget stream versions (the server may have restarted its counters). Call after a resync or reconnect. */
+    resetVersions() { versions.clear(); },
+
+    /**
+     * Drop every entity that cannot be reached from `roots` (normalized query results), following nested refs.
+     * Readers of a dropped entity see it as deleted. Returns how many were dropped.
+     * @param {any[]} roots
+     */
+    sweep(roots) {
+      const keep = new Set();
+      const visit = (v) => {
+        if (isRef(v)) {
+          if (keep.has(v.$ref)) return;
+          keep.add(v.$ref);
+          visit(entities.get(v.$ref)?.peek());
+        } else if (Array.isArray(v)) v.forEach(visit);
+        else if (v && typeof v === 'object') Object.values(v).forEach(visit);
+      };
+      roots.forEach(visit);
+      let dropped = 0;
+      batch(() => {
+        const names = new Set();
+        for (const [key, sig] of entities) {
+          if (keep.has(key) || sig.peek() === undefined) continue;
+          const name = key.slice(0, key.indexOf('#'));
+          ids.get(name)?.delete(key.slice(name.length + 1));
+          sig.value = undefined; versions.delete(key); names.add(name); dropped++;
+        }
+        for (const name of names) bump(name);
+      });
+      return dropped;
+    },
+
+    clear() {
+      batch(() => {
+        for (const sig of entities.values()) sig.value = undefined;
+        ids.clear(); versions.clear();
+        for (const name of indexTick.keys()) bump(name);
+      });
+    },
+  };
+  return store;
+}
+
+/**
+ * Identity of a record: one property, or several for a composite id (each part percent-encoded, joined with "/", so
+ * ["a/b","c"] and ["a","b/c"] stay different). undefined when a part is missing. Stream events address it the same way.
+ */
+export function idOf(idDef, value) {
+  if (!Array.isArray(idDef)) return value[idDef] ?? undefined;
+  const parts = idDef.map((k) => value[k]);
+  return parts.some((p) => p === undefined || p === null) ? undefined : parts.map((p) => encodeURIComponent(String(p))).join('/');
+}
+
+/** Normalize a plain entity object into a record whose nested entities are refs. */
+export function normalizeRecord(store, name, value, touched) {
+  const def = store.defs[name];
+  const record = { ...value };
+  if (def?.props) {
+    for (const [k, desc] of Object.entries(def.props)) {
+      if (k in record) record[k] = normalize(store, desc, record[k], touched);
+    }
+  }
+  return record;
+}
+
+/**
+ * Walk `value` using a schema descriptor, storing entities and returning the
+ * normalized tree. `touched` (optional Set) collects the keys of every entity written. Descriptors: {t:'entity',name} | {t:'array',items} | {t:'object',props} | {t:'union',key,map,default?}
+ */
+export function normalize(store, desc, value, touched) {
+  if (!desc || value == null) return value;
+  switch (desc.t) {
+    case 'entity': {
+      if (typeof value !== 'object') return value;
+      const def = store.defs[desc.name];
+      const id = def ? idOf(def.id, value) : undefined;
+      if (id === undefined) return value; // no identity: keep inline
+      const ref = store.upsert(desc.name, id, normalizeRecord(store, desc.name, value, touched), { replace: desc.replace });
+      touched?.add(ref.$ref);
+      return ref;
+    }
+    case 'array':
+      return Array.isArray(value) ? value.map((x) => normalize(store, desc.items, x, touched)) : value;
+    case 'object': {
+      if (typeof value !== 'object' || Array.isArray(value)) return value;
+      const out = { ...value };
+      for (const [k, d] of Object.entries(desc.props ?? {})) if (k in out) out[k] = normalize(store, d, out[k], touched);
+      return out;
+    }
+    case 'union': {
+      // Pick the member by its tag property; anything else (a plain id string, an unknown tag) stays as received.
+      if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+      if (desc.has) { // no tag: the member is recognised by a property only it has
+        const hit = desc.has.find(([prop]) => prop in value);
+        return hit ? normalize(store, hit[1], value, touched) : value;
+      }
+      const member = (value[desc.key] !== undefined ? desc.map[value[desc.key]] : undefined) ?? desc.default;
+      return member ? normalize(store, member, value, touched) : value;
+    }
+    default:
+      return value;
+  }
+}

package/src/stream.js

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * Connect to a stream of entity events (SSE) and apply them to the client's store.
+ * Event JSON: {type:'patch'|'upsert'|'delete', entity, id, path?, value?, version?}
+ * or {type:'resync'} to invalidate every cached query.
+ *
+ * Reconnection and Last-Event-ID replay are handled by EventSource itself.
+ *
+ * @param {{ client: ReturnType<import('./client.js').createClient>, url: string,
+ *           EventSource?: typeof EventSource, onStatus?: (s:'open'|'error'|'closed') => void,
+ *           onError?: (e: Error) => void }} opts
+ */
+export function connectStream({ client, url, EventSource = globalThis.EventSource, onStatus, onError }) {
+  if (!EventSource) throw new Error('xoong: EventSource is not available in this environment');
+  const source = new EventSource(url, { withCredentials: true });
+  let reconnected = false;
+  source.onopen = () => {
+    onStatus?.('open');
+    // After an interruption we may have missed events: refetch what is on screen.
+    if (reconnected) { client.store.resetVersions(); client.invalidateAll(); }
+  };
+  source.onerror = () => { reconnected = true; onStatus?.('error'); };
+  source.onmessage = (msg) => {
+    let ev;
+    try { ev = JSON.parse(msg.data); } catch (e) { onError?.(/** @type {Error} */ (e)); return; }
+    if (ev?.type === 'resync') { client.store.resetVersions(); client.invalidateAll(); }
+    else client.store.applyEvent(ev);
+  };
+  return { close() { source.close(); onStatus?.('closed'); } };
+}

package/src/url-state.js

@@ -0,0 +1,32 @@
+// @ts-check
+/**
+ * Where `<xo-view url-params="status,q,sort,offset">` keeps its parameters: the query string of the page. Without a router the
+ * History API is used directly; a router (in @xoong/ui) replaces this with its own, which also keeps its history positions.
+ */
+
+/**
+ * @typedef {{
+ *   read(): URLSearchParams,
+ *   write(params: URLSearchParams, mode: 'push' | 'replace'): void,
+ *   subscribe(fn: () => void): () => void,
+ * }} UrlSync
+ */
+
+/** @type {UrlSync} */
+const history = {
+  read: () => new URLSearchParams(globalThis.location?.search),
+  write(params, mode) {
+    const loc = globalThis.location;
+    if (!loc) return;
+    const query = params.toString();
+    const url = loc.pathname + (query ? `?${query}` : '') + loc.hash;
+    if (url === loc.pathname + loc.search + loc.hash) return;
+    globalThis.history[mode === 'push' ? 'pushState' : 'replaceState'](globalThis.history.state, '', url);
+  },
+  subscribe(fn) { globalThis.addEventListener('popstate', fn); return () => globalThis.removeEventListener('popstate', fn); },
+};
+
+let current = history;
+/** The router registers itself here. @param {UrlSync | null} sync */
+export function setUrlSync(sync) { current = sync ?? history; }
+export const urlSync = () => current;