@ultimat3/core 20.2.1 → 22.0.0

package/src/client-paths.ts

@@ -0,0 +1,79 @@
+/**
+ * The ONE URL rule for the two HTTP primitives: an action's export name derives `POST
+ * /api/<resource>/<verb>`, a query's derives `GET /_x/query/<kebab>`. Tier 0 and pure string math,
+ * so `action`, `query` and `realtime` (all tier 3) derive the same URL with no sideways import and
+ * a browser bundle pays a few hundred bytes for it. Moved verbatim from both packages' `naming.ts`.
+ */
+
+/** Irregular plurals we actually hit in domain models. A `Map`: the key is a caller's word. */
+const IRREGULAR: ReadonlyMap<string, string> = new Map([
+  ['person', 'people'],
+  ['child', 'children'],
+  ['man', 'men'],
+  ['woman', 'women'],
+  ['datum', 'data'],
+  ['index', 'indexes'],
+  ['entry', 'entries'],
+]);
+
+/** Every read is served under one prefix, so a router can claim it in one rule. */
+export const QUERY_PATH_PREFIX = '/_x/query';
+
+export interface ActionRoute {
+  /** First camelCase word, kebab-cased. `publishPost` -> `publish`. */
+  readonly verb: string;
+  /** Remaining words, last one pluralized, kebab-cased. `publishPost` -> `posts`. */
+  readonly resource: string;
+  /** `/api/<resource>/<verb>`. */
+  readonly path: string;
+}
+
+/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
+export function splitWords(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[\s_-]+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.toLowerCase());
+}
+
+/**
+ * Naive-on-purpose English pluralizer. A word that already ends in `s` is left alone, so
+ * `publishPosts` and `publishPost` agree on the `posts` resource.
+ */
+export function pluralize(word: string): string {
+  const irregular = IRREGULAR.get(word);
+  if (irregular !== undefined) return irregular;
+  if (word.endsWith('s')) return word;
+  if (/(x|z|ch|sh)$/.test(word)) return `${word}es`;
+  if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
+  return `${word}s`;
+}
+
+/**
+ * `publishPost` -> `/api/posts/publish`, `updateUserProfile` -> `/api/user-profiles/update`,
+ * `checkout` -> `/api/checkouts/invoke` (single-word fallback).
+ */
+export function actionRoute(name: string): ActionRoute {
+  const words = splitWords(name);
+  const head = words[0] ?? 'invoke';
+  if (words.length < 2) {
+    const resource = pluralize(head);
+    return { verb: 'invoke', resource, path: `/api/${resource}/invoke` };
+  }
+  const nouns = words.slice(1);
+  const last = nouns[nouns.length - 1] ?? head;
+  const resource = [...nouns.slice(0, -1), pluralize(last)].join('-');
+  return { verb: head, resource, path: `/api/${resource}/${head}` };
+}
+
+/** The path an action is POSTed to — `actionRoute(name).path`. */
+export function actionPath(name: string): string {
+  return actionRoute(name).path;
+}
+
+/** `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. */
+export function queryPath(name: string): string {
+  return `${QUERY_PATH_PREFIX}/${splitWords(name).join('-')}`;
+}

package/src/client-problem.ts

@@ -0,0 +1,94 @@
+/**
+ * A browser request's failure, as the error it is: a non-2xx `problem+json` answer back into the
+ * `UltimateError` the server threw, and a dispatch that produced no usable answer into
+ * `X_CLIENT_TRANSPORT_FAILED`. The one decoder `clientTransport` owns, so every client surface
+ * reads a failure off the wire the same way.
+ */
+
+import { FRAMEWORK_CODE, problemOf, retryForStatus } from './client-wire';
+import { renderFixShellArg } from './error-render';
+import type { ErrorRetry } from './error-retry';
+import { UltimateError } from './errors';
+import { isJsonObject } from './json-object';
+
+/** An absolute HTTP(S) link, or nothing: a server's `docs` is data and may be `javascript:`. */
+const HTTP_URL = /^https?:\/\/[^\s]+$/;
+
+/**
+ * A non-2xx answer. A body naming a framework code IS the server's error, carried verbatim and
+ * marked `origin: 'remote'` — the code may be one this bundle never registered. Anything else is
+ * a proxy or a gateway answering instead of the app.
+ */
+export function problemError(status: number, text: string, url: string): UltimateError {
+  const body = problemOf(text);
+  const code = body['code'];
+  if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
+    return transportFailed(
+      'status',
+      `${url} answered HTTP ${status} without a problem+json body naming a framework code`,
+      retryForStatus('X_CLIENT_TRANSPORT_FAILED', status),
+      { url, status },
+    );
+  }
+  const docs = [body['docs'], body['type']].find(
+    (value): value is string => typeof value === 'string' && HTTP_URL.test(value),
+  );
+  return new UltimateError({
+    code,
+    cause: text1(body['cause']) ?? text1(body['detail']) ?? `${url} failed with HTTP ${status}`,
+    fix: text1(body['fix']) ?? `x errors explain ${renderFixShellArg(code, '<code>')} --json`,
+    retry: retryForStatus(code, status),
+    // The server's declared keys FIRST, so the three this decoder owns win a collision.
+    meta: { ...serverMeta(body['meta'], body['issues']), origin: 'remote', status, url },
+    ...(docs === undefined ? {} : { docs }),
+  });
+}
+
+/**
+ * WHICH way no usable answer came back, on `meta.failure` — what a caller branches on, since the
+ * code is the same for all three: `network` (no response at all — the one an offline outbox
+ * queues), `status` (a non-2xx no framework code explained) and `body` (a 2xx that is not JSON).
+ */
+export type TransportFailure = 'network' | 'status' | 'body';
+
+/**
+ * No usable answer: the network refused, the body stream broke, or a 2xx body was not JSON.
+ * `retry` is the caller's to state — a read is always safe to send again, an unkeyed write never.
+ */
+export function transportFailed(
+  failure: TransportFailure,
+  cause: string,
+  retry: ErrorRetry | undefined,
+  meta: Readonly<Record<string, unknown>>,
+  sourceError?: unknown,
+): UltimateError {
+  return new UltimateError({
+    code: 'X_CLIENT_TRANSPORT_FAILED',
+    cause,
+    fix: 'check the network and the gateway in front of the app with x doctor --json, then retry — a write with no idempotencyKey may already have landed',
+    ...(retry === undefined ? {} : { retry }),
+    meta: { ...meta, failure },
+    ...(sourceError === undefined ? {} : { sourceError }),
+  });
+}
+
+/**
+ * The document's `meta`, copied own key by own key: `JSON.parse` mints `__proto__` as a real own
+ * key, and assigned onto a plain object it would replace the prototype. `issues` rides along
+ * unparsed for the caller whose schema can read it.
+ */
+function serverMeta(meta: unknown, issues: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (isJsonObject(meta)) {
+    for (const [key, member] of Object.entries(meta)) {
+      if (key === '__proto__') continue;
+      Object.defineProperty(out, key, { value: member, writable: true, enumerable: true });
+    }
+  }
+  if (Array.isArray(issues)) out['issues'] = issues;
+  return out;
+}
+
+function text1(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/client-scope-error.ts

@@ -0,0 +1,18 @@
+/**
+ * The refusal a read in flight across `rescope()` rejects with — `X_CLIENT_SCOPE_CHANGED`. Its own
+ * module, imported only by the transport: `client-scope.ts` is what `pageClient()` and every
+ * `onRescope` subscriber reach, and constructing an `UltimateError` there put core's error registry
+ * into a store-only island that never makes a request.
+ */
+
+import { UltimateError } from './errors';
+
+/** Never a UI error: `isSuperseded(error)` answers true for it, and a caller renders nothing. */
+export function scopeChanged(subject: string, issued: number, current: number): UltimateError {
+  return new UltimateError({
+    code: 'X_CLIENT_SCOPE_CHANGED',
+    cause: `${subject} was issued for client scope epoch ${issued} and the page is now at ${current}, so its answer belongs to the previous principal`,
+    fix: 'discard this answer and read again — test it with isSuperseded(error) from @ultimat3/core and render nothing for it',
+    meta: { subject, issued, current },
+  });
+}

package/src/client-scope.ts

@@ -0,0 +1,59 @@
+/**
+ * The principal fence: which principal the page is acting for, and an epoch that moves exactly
+ * when that changes. A response, frame or persisted row from the previous principal must never
+ * land in the next one's store, so every client layer reads this one signal.
+ *
+ * Subscriber contract (`onRescope`): called SYNCHRONOUSLY, once per real change, in registration
+ * order, before `rescope()` returns — so by the time a sign-in action's caller continues, every
+ * read was aborted, the store wiped its non-persisted records, the socket dropped its channels
+ * and the persister switched scope. A throwing subscriber does not stop the others; the first
+ * throw is re-raised after all have run. The TRIGGER is not core's: the page bootstrap calls
+ * `rescope()` with the principal the server rendered, and sign-in / sign-out call it on success.
+ */
+
+import type { ScopeCell } from './record-sink';
+import { heldRecords, scopeCell } from './record-sink';
+
+export interface ClientScope {
+  /**
+   * An opaque principal id; `null` for a page rendered for an anonymous visitor; `undefined` for
+   * an UNSCOPED page — one rendered for nobody (a shared, cacheable document carries no scope
+   * meta). Nothing is persisted while unscoped (plan 101 slice 12): there is no principal to key
+   * the rows by, and guessing one is how one visitor's cache restores into another's.
+   */
+  readonly principal: string | null | undefined;
+  /** Bumped once per principal change. Work captured at another epoch is not this scope's. */
+  readonly epoch: number;
+}
+
+/** Move the page to `principal`. Same principal = no-op: no epoch bump, no notification. */
+export function rescope(principal: string | null): void {
+  const cell: ScopeCell = scopeCell();
+  const prev = cell.current;
+  if (prev.principal === principal) return;
+  const next: ClientScope = Object.freeze({ principal, epoch: prev.epoch + 1 });
+  cell.current = next;
+  // Held early records belong to the principal that just left; they never reach the next store.
+  heldRecords()?.clear();
+  let failure: { readonly error: unknown } | undefined;
+  // A snapshot: a subscriber that unsubscribes (or subscribes) mid-notify changes the NEXT round.
+  for (const listener of [...cell.listeners]) {
+    try {
+      listener(next, prev);
+    } catch (error) {
+      failure ??= { error };
+    }
+  }
+  if (failure !== undefined) throw failure.error;
+}
+
+/** Subscribe to principal changes. Returns the unsubscribe. */
+export function onRescope(fn: (next: ClientScope, prev: ClientScope) => void): () => void {
+  const listeners = scopeCell().listeners;
+  // Wrapped, so the same function registered twice is two subscriptions with two unsubscribes.
+  const entry = (next: ClientScope, prev: ClientScope): void => fn(next, prev);
+  listeners.add(entry);
+  return (): void => {
+    listeners.delete(entry);
+  };
+}

package/src/client-transport.ts

@@ -0,0 +1,86 @@
+/**
+ * The ONE browser HTTP function. Every client surface — `rpc()`, `queryClient()`, a signed upload,
+ * the store's refetch — sends through here, so credentials, headers, the error decode, the records
+ * envelope and the principal fence are decided once. A GET is a read: abortable on `rescope()`,
+ * deduped when a `ClientFlight` is supplied. Anything else is a write: never deduped, never
+ * aborted by the fence, and its records never adopted across one.
+ *
+ * `createClientFlight` is NOT imported here at value level — a caller passes one, and only then
+ * does its graph enter the bundle. Neither is `traceHeaders()`: the trace and budget headers come
+ * from an outbound slot that `runWithContext`/`startSpan` fill SERVER-side (`outbound-headers.ts`),
+ * so a browser, which never has either, carries zero bytes of telemetry, context or logger.
+ *
+ * Measured `bun build --target=browser --minify` through the barrel, As of 2026-09-22 (before →
+ * after the outbound slot): `rpc` 23,164 → 18,119 B; `queryClient` 24,100 → 22,897 B (the rest is
+ * `@ultimat3/query`'s anchored `registry.ts`); `clientTransport` 13,571 B; `pageClient` 8,139 B;
+ * `UltimateError` 7,679 B. ~7.6 kB of every barrel import is the error-code registry that the
+ * anchored `schema-error-codes.ts` registers into — `pageClient` straight from its module is 332 B.
+ */
+
+import type { Answer, TransportRequest } from './client-dispatch';
+import { dispatch } from './client-dispatch';
+import { transportFailed } from './client-problem';
+import { scopeChanged } from './client-scope-error';
+import type { RecordEnvelope } from './record-envelope';
+import { decodeRecordEnvelope } from './record-envelope';
+import { pageClient, recordSink } from './record-sink';
+
+const ONCE = { attempts: 1 } as const;
+
+export async function clientTransport<T = unknown>(req: TransportRequest): Promise<T> {
+  const read = req.method === 'GET';
+  const issued = pageClient().scope.epoch;
+  const flight = req.flight;
+  const answer: Answer =
+    flight === undefined
+      ? await dispatch(req, read, issued, undefined)
+      : await flight.run({
+          // A mutation never joins another mutation, idempotency key or not: the key is for the
+          // server's replay, and sharing one dispatch would hide the second intent from it.
+          key: read ? flight.keyFor(req.url, { signal: req.signal, fresh: req.fresh }) : undefined,
+          abortable: read,
+          // A stream is read once, so a second attempt re-sends a body that is already spent —
+          // and fails as the network would, until the attempts run out. One attempt, always.
+          retry: req.rawBody instanceof ReadableStream ? ONCE : req.retry,
+          run: (signal) => dispatch(req, read, issued, signal),
+          // `dispatch` makes every wire failure `X_CLIENT_TRANSPORT_FAILED`; a bare throw that
+          // reaches the flight is a caller hook's, never the network's.
+          classified: true,
+        });
+  const current = pageClient().scope.epoch;
+  // A read that raced the abort still belongs to the previous principal.
+  if (read && current !== issued) throw scopeChanged(req.url, issued, current);
+  if (req.rawBody !== undefined) return undefined as T;
+  const envelope = unwrap(answer, req.url, read);
+  // A write that crossed a rescope HAS landed, so its caller is told — but its rows are the
+  // previous principal's, and the new scope's store never sees them.
+  if (current === issued) {
+    adopt(envelope);
+    if (answer.enveloped) req.onEnvelope?.(envelope);
+  }
+  return envelope.data as T;
+}
+
+function unwrap(answer: Answer, url: string, read: boolean): RecordEnvelope {
+  let body: unknown;
+  try {
+    body = answer.text === '' ? undefined : (JSON.parse(answer.text) as unknown);
+  } catch (error) {
+    throw transportFailed(
+      'body',
+      `${url} answered 2xx with a body that is not JSON — a proxy answered instead of the app`,
+      read ? 'retryable' : undefined,
+      { url },
+      error,
+    );
+  }
+  return answer.enveloped ? decodeRecordEnvelope(body) : { data: body };
+}
+
+/** Adopt, then remove: a key in both is gone, never resurrected by the same answer. */
+function adopt(envelope: RecordEnvelope): void {
+  const sink = recordSink();
+  if (sink === undefined) return;
+  for (const [type, rows] of Object.entries(envelope.records ?? {})) sink.adopt(type, rows);
+  for (const [type, keys] of Object.entries(envelope.removed ?? {})) sink.remove(type, keys);
+}

package/src/config-count.ts

@@ -0,0 +1,19 @@
+// Single responsibility: the numeric domain a config count or window must sit in. Takes the key as
+// a string and the value as `unknown`, because `validate` is the boundary an untyped JS config
+// crosses — a `'60s'` arrives here however the interface types the field.
+
+import { describeValue } from './error-render';
+
+/**
+ * Why `value` is not a whole number ≥ `min`, or `undefined` when it is one. `NaN`, `Infinity` and
+ * `2.5` each passed `concurrency < 1` — every comparison with `NaN` is false — and a fraction or an
+ * infinity then reaches `Array.from({ length })`, a `setTimeout` or a loop bound.
+ */
+export function countIssue(key: string, value: unknown, min: 0 | 1): string | undefined {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= min) return undefined;
+  // A number is printed as itself — `describeValue` answers "a number" for 2.5 and -3 alike.
+  const shown = typeof value === 'number' ? numberText(value) : describeValue(value);
+  return `${key} must be a whole number ${min === 1 ? 'of at least 1' : 'of 0 or more'}, not ${shown}`;
+}
+
+const numberText = (value: number): string => `${value}`;

package/src/config-fixes.ts

@@ -0,0 +1,23 @@
+// Single responsibility: the remedies `app.config.ts`'s validator appends to X_CONFIG_INVALID. Split
+// from `config.ts` so the validator stays under its line ceiling; each string is carried only when
+// its own key is what failed.
+
+export const BASE_FIX = 'edit app.config.ts to fix the fields named in cause, then run: x verify';
+
+/**
+ * Appended only when the zone is what failed. Axiom 4: an operator holding `'CET'` needs the
+ * spelling to write, and the two refused classes have different remedies — a single-label legacy
+ * name swaps mechanically, an abbreviation or an offset has no replacement at all because it names
+ * no jurisdiction. Deliberately parallel to `@ultimat3/time`'s `X_TIMEZONE_INVALID` fix, since the
+ * two refuse the same strings and an operator may meet either first.
+ */
+export const TIMEZONE_FIX =
+  "set defaultTimeZone to an Area/Location name, or UTC — list every accepted one with bun -e \"console.log(Intl.supportedValuesOf('timeZone').join('\\n'))\" — where a legacy single-label name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC), while an abbreviation or numeric offset (CET, EST5EDT, +01:00) carries no DST rule and has no replacement, so name the city whose clock you mean (Europe/Paris, America/New_York)";
+
+/**
+ * Appended only when a tier name is what failed, and it names the rename rather than the rule: the
+ * three refused spellings are the ones 8.0.0 accepted, and two of them have a mechanical
+ * replacement while `isr` has none — it is a `RenderMode`, and no cache tier ever served it.
+ */
+export const CACHE_TIER_FIX =
+  "in app.config.ts, rewrite cache.tiers with the rung names the ladder serves — request-memo, lru, redis, cdn — where memo becomes request-memo and shared becomes redis, and isr is dropped: it is a render mode, so move it to render: 'isr' on the routes that want it";

package/src/config-merge.ts

@@ -0,0 +1,36 @@
+// Single responsibility: how `defineConfig` layers `app.config.ts` and its `config/*.ts` overlays —
+// per section and key by key. Carries no config KEY on purpose: `config-readers` counts a property
+// access outside `config.ts` as a reader, so this file only ever sees sections as opaque records.
+
+/** A section's patch: every key optional, and an explicit `undefined` meaning "not said". */
+export type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
+
+/**
+ * Apply a partial section over its defaults. Explicit `undefined` never wins — that is what
+ * makes every config field deeply optional without `exactOptionalPropertyTypes` fighting back.
+ */
+export function section<T extends object>(base: T, patch: Input<T> | undefined): T {
+  if (patch === undefined) return base;
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out as T;
+}
+
+/**
+ * Every layer's patch applied in order, each one KEY BY KEY. The input and the overlays used to be
+ * `Object.assign`ed first and the section merged once, so `{ jobs: { maxAttempts: 9 } }` in an
+ * overlay replaced the base's whole `jobs` patch — its `queues` and `concurrency` fell back to the
+ * framework defaults — and an overlay's `{ realtime: undefined }` erased the base's section.
+ */
+export function layered<T extends object>(base: T, patches: readonly (Input<T> | undefined)[]): T {
+  return patches.reduce<T>((out, patch) => section(out, patch), base);
+}
+
+/** A whole-value key (`locales`, `roles`): the last layer that said something wins. */
+export function lastSaid<T>(base: T, values: readonly (T | undefined)[]): T {
+  let out = base;
+  for (const value of values) if (value !== undefined) out = value;
+  return out;
+}