@ultimat3/core 27.3.0 → 27.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "27.3.0",
+  "version": "27.4.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "27.3.0"
+    "@ultimat3/schema": "27.4.0"
   }
 }

package/src/client-dispatch.ts

@@ -14,6 +14,7 @@ import { CLIENT_BUILD_META } from './page-meta';
 import type { RecordEnvelope } from './record-envelope';
 import { RECORDS_HEADER } from './record-envelope';
 import { outboundSlot, pageClient } from './record-sink';
+import { DATES_HEADER } from './wire-dates';
 
 export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
 
@@ -79,6 +80,8 @@ export interface TransportRequest {
 export interface Answer {
   readonly text: string;
   readonly enveloped: boolean;
+  /** `x-ultimate-dates`: which values of the data were instants (`wire-dates.ts`). */
+  readonly dates: string | null;
 }
 
 /** Called, never captured: a browser's `fetch` throws `Illegal invocation` when detached. */
@@ -111,7 +114,11 @@ export async function dispatch(
         problemError(response.status, text, req.url, stated)
       );
     }
-    return { text, enveloped: response.headers.get(RECORDS_HEADER) === '1' };
+    return {
+      text,
+      enveloped: response.headers.get(RECORDS_HEADER) === '1',
+      dates: response.headers.get(DATES_HEADER),
+    };
   } catch (error) {
     const current = pageClient().scope.epoch;
     if (read && current !== issued) throw scopeChanged(req.url, issued, current);

package/src/client-transport.ts

@@ -25,6 +25,7 @@ import { notifyClientWrite } from './client-writes';
 import type { RecordEnvelope } from './record-envelope';
 import { decodeRecordEnvelope } from './record-envelope';
 import { pageClient, recordSink } from './record-sink';
+import { reviveWireDates } from './wire-dates';
 
 const ONCE = { attempts: 1 } as const;
 
@@ -94,7 +95,9 @@ function unwrap(answer: Answer, url: string, read: boolean): RecordEnvelope {
       error,
     );
   }
-  return answer.enveloped ? decodeRecordEnvelope(body) : { data: body };
+  const envelope = answer.enveloped ? decodeRecordEnvelope(body) : { data: body };
+  // In place, on this caller's own parse: a deduped read's joiners each parsed their own copy.
+  return { ...envelope, data: reviveWireDates(envelope.data, answer.dates) };
 }
 
 /** Adopt, then remove: a key in both is gone, never resurrected by the same answer. */

package/src/context.ts

@@ -33,6 +33,7 @@
 import { type Actor, anonymousActor } from './actor';
 import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
+import { DEFAULT_LOCALE, DEFAULT_TIME_ZONE } from './default-locale';
 import { UltimateError } from './errors';
 import { finiteOption } from './finite-option';
 import { traceId as newTraceId, uuidV7 } from './ids';
@@ -157,13 +158,6 @@ const requestContext = asyncContext<Ctx>('the request context');
 
 const neverAborted = new AbortController().signal;
 
-/**
- * The framework's default locale — the ONE declaration: `@ultimat3/i18n` imports it rather than
- * restating it (a second `'en'` there could drift from the context's own default).
- */
-export const DEFAULT_LOCALE = 'en';
-export const DEFAULT_TIME_ZONE = 'UTC';
-
 function buildId(): string {
   return process.env['BUILD_ID'] ?? 'dev';
 }

package/src/default-locale.ts

@@ -0,0 +1,8 @@
+// The framework's default locale and time zone — the ONE declaration, in a leaf of its own:
+// `@ultimat3/i18n`'s translator reads the locale, and an island's translator
+// (`@ultimat3/i18n/subset`) must not carry the request context (`context.ts`, its async storage)
+// to read a constant.
+
+/** `@ultimat3/i18n` imports it rather than restating it: a second `'en'` there could drift. */
+export const DEFAULT_LOCALE = 'en';
+export const DEFAULT_TIME_ZONE = 'UTC';

package/src/index.ts

@@ -200,8 +200,6 @@ export { resolveConflict } from './conflict-policy';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
   ctxOf,
-  DEFAULT_LOCALE,
-  DEFAULT_TIME_ZONE,
   hasContext,
   runWithContext,
   throwIfAborted,
@@ -228,6 +226,7 @@ export {
 export type { Page } from './cursor-page';
 export { pageOf } from './cursor-page';
 export { compareDecimalText } from './decimal-order';
+export { DEFAULT_LOCALE, DEFAULT_TIME_ZONE } from './default-locale';
 export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
 export { recordDeprecatedCall, renderDeprecation } from './deprecation';
 export type { DevSecretsOptions } from './dev-secrets';
@@ -801,6 +800,7 @@ export {
   webhookSignature,
   webhookSigningString,
 } from './webhook-signature';
+export { DATES_HEADER, reviveWireDates, wireDatePaths } from './wire-dates';
 /**
  * A write's public name — the digest of its idempotency key — and the server scope that carries it
  * from `@ultimat3/action`'s HTTP projection to the layers that stamp it on a `records` frame.

package/src/page.ts

@@ -56,5 +56,7 @@ export type { PageClient, RecordSink } from './record-sink';
 export { pageClient } from './record-sink';
 // The key the theme boot script reads and the toggle island writes.
 export { THEME_STORAGE_KEY } from './theme-storage';
+// What `clientTransport` revives a read's instants by: the header the server names them in.
+export { DATES_HEADER, reviveWireDates } from './wire-dates';
 // A write's public name, so the page's store can recognise the `records` frame its own write made.
 export { isWriteDigest, WRITE_DIGEST_LENGTH, writeDigest } from './write-digest';

package/src/wire-dates.ts

@@ -0,0 +1,116 @@
+/**
+ * Which values of an answer were instants. `JSON.stringify` writes a `Date` as its ISO string and
+ * nothing on the far side can tell it from text, so a read's row typed `Date` reached its caller as
+ * a string — and every app converted at its own edge (`wireDate()`). The server knows: it walks the
+ * answer once, names each `Date` by its path in `x-ultimate-dates`, and `clientTransport` turns
+ * exactly those strings back into `Date`s. The body is unchanged, so a client that ignores the
+ * header reads what it always read.
+ *
+ * A path is a list of segments: a string is an object key, a number an array index, and `null`
+ * EVERY element of an array — what a list of rows folds to (`[[null, "publishedAt"]]`), so the
+ * header is one entry per column, not per row. A pattern that also matches a string that was not a
+ * `Date` is never folded: its instants are sent by exact path, so revival is exact either way.
+ */
+
+/** The response header naming an answer's instants. Absent when it holds none. */
+export const DATES_HEADER = 'x-ultimate-dates';
+
+type Segment = string | number | null;
+
+interface Pattern {
+  readonly exact: Segment[][];
+  /** A string that was not a `Date` sits at this pattern too, so folding it would revive text. */
+  text: boolean;
+}
+
+const isWalkable = (value: unknown): value is object =>
+  typeof value === 'object' &&
+  value !== null &&
+  // `JSON.stringify` writes what `toJSON` answers, not the object's keys — nothing to name inside.
+  typeof (value as { toJSON?: unknown }).toJSON !== 'function';
+
+/**
+ * The header value for an answer, or `undefined` when it holds no `Date`. URI-encoded JSON: a
+ * header value is bytes, and an object key may be any string.
+ */
+export function wireDatePaths(value: unknown): string | undefined {
+  const patterns = new Map<string, Pattern>();
+  const ancestors = new Set<object>();
+  const at = (pattern: Segment[]): Pattern => {
+    const key = JSON.stringify(pattern);
+    const found = patterns.get(key) ?? { exact: [], text: false };
+    patterns.set(key, found);
+    return found;
+  };
+  const walk = (node: unknown, pattern: Segment[], exact: Segment[]): void => {
+    if (node instanceof Date) {
+      if (!Number.isNaN(node.getTime())) at(pattern).exact.push(exact);
+      return;
+    }
+    if (typeof node === 'string') {
+      at(pattern).text = true;
+      return;
+    }
+    // A cycle is `JSON.stringify`'s refusal to make, one step later — never a stack overflow here.
+    if (!isWalkable(node) || ancestors.has(node)) return;
+    ancestors.add(node);
+    if (Array.isArray(node)) {
+      for (let index = 0; index < node.length; index += 1) {
+        walk(node[index], [...pattern, null], [...exact, index]);
+      }
+    } else {
+      for (const [key, item] of Object.entries(node))
+        walk(item, [...pattern, key], [...exact, key]);
+    }
+    ancestors.delete(node);
+  };
+  walk(value, [], []);
+  const paths: Segment[][] = [];
+  for (const [key, { exact, text }] of patterns) {
+    if (exact.length === 0) continue;
+    if (text) paths.push(...exact);
+    else paths.push(JSON.parse(key) as Segment[]);
+  }
+  return paths.length === 0 ? undefined : encodeURIComponent(JSON.stringify(paths));
+}
+
+/**
+ * Every string the header names, in a freshly parsed answer, turned back into a `Date` — in place.
+ * A header that does not parse revives nothing: it is a statement about the body, and a proxy that
+ * mangled it has not mangled the body.
+ */
+export function reviveWireDates<T>(value: T, header: string | null): T {
+  if (header === null || header === '') return value;
+  let paths: unknown;
+  try {
+    paths = JSON.parse(decodeURIComponent(header));
+  } catch {
+    return value;
+  }
+  if (!Array.isArray(paths)) return value;
+  const holder: { root: unknown } = { root: value };
+  for (const path of paths) if (Array.isArray(path)) revive(holder, 'root', path, 0);
+  return holder.root as T;
+}
+
+function revive(parent: object, key: string | number, path: readonly unknown[], depth: number) {
+  const node: unknown = (parent as Record<string | number, unknown>)[key];
+  if (depth === path.length) {
+    if (typeof node !== 'string') return;
+    const instant = new Date(node);
+    if (!Number.isNaN(instant.getTime()))
+      (parent as Record<string | number, unknown>)[key] = instant;
+    return;
+  }
+  const segment = path[depth];
+  if (Array.isArray(node)) {
+    if (segment === null) for (let i = 0; i < node.length; i += 1) revive(node, i, path, depth + 1);
+    else if (typeof segment === 'number' && segment < node.length)
+      revive(node, segment, path, depth + 1);
+  } else if (typeof node === 'object' && node !== null && typeof segment === 'string') {
+    // `JSON.parse` mints `__proto__` as an own key, and assigning through it sets the prototype.
+    if (segment !== '__proto__' && Object.hasOwn(node, segment)) {
+      revive(node, segment, path, depth + 1);
+    }
+  }
+}