@ultimat3/core 27.1.0 → 27.2.0

package/README.md

@@ -753,7 +753,7 @@ read; `@ultimat3/jobs` re-exports both rather than keeping a second pair.
 
 | Export | The one answer | The question it settles |
 |---|---|---|
-| `clientTransport({ method, url, body?, rawBody?, headers?, signal?, idempotencyKey?, flight?, fresh?, retry?, onResponse?, decodeError?, onEnvelope?, fetchImpl? })` | every browser request | `credentials: 'same-origin'`, JSON in and out, the `idempotency-key` header, a non-2xx `problem+json` back into the server's code (`meta.origin: 'remote'`) unless `decodeError` answers first, a network `TypeError` into `X_CLIENT_TRANSPORT_FAILED`. A GET is abortable on `rescope()` and deduped only when a `flight` is passed (`fresh` refuses to join); any other method is never deduped and never aborted by the fence. `rawBody` goes out verbatim with no default header and resolves `undefined`. `onResponse` sees headers before the body is read. `onEnvelope` sees the decoded records envelope after adoption — the one way to learn the order of `records[type]`. `fetchImpl` defaults to `globalThis.fetch`, read at call time |
+| `clientTransport({ method, url, body?, rawBody?, headers?, signal?, idempotencyKey?, flight?, fresh?, retry?, responseType?, onResponse?, decodeError?, onEnvelope?, fetchImpl? })` | every browser request | `credentials: 'same-origin'`, JSON in and out, the `idempotency-key` header, a non-2xx `problem+json` back into the server's code (`meta.origin: 'remote'`) unless `decodeError` answers first, a network `TypeError` into `X_CLIENT_TRANSPORT_FAILED`. A GET is abortable on `rescope()` and deduped only when a `flight` is passed (`fresh` refuses to join); any other method is never deduped and never aborted by the fence. `rawBody` goes out verbatim with no default header and resolves `undefined` (the body as a string with `responseType: 'text'`). `responseType: 'text'` resolves a 2xx body as a string (typed `Promise<string>`), sends `accept: */*` unless `headers` names one, and adopts no envelope — for an HTML fragment or a CSV; a non-2xx is still decoded as a refusal. About 10.7 kB minified (4.6 kB gzipped) through `@ultimat3/core/page`, no titles table — pinned in `page-bundle.test.ts`. `onResponse` sees headers before the body is read. `onEnvelope` sees the decoded records envelope after adoption — the one way to learn the order of `records[type]`. `fetchImpl` defaults to `globalThis.fetch`, read at call time |
 | `actionPath(name)`, `actionRoute(name)`, `queryPath(name)`, `QUERY_PATH_PREFIX`, `splitWords`, `pluralize` | the one URL rule | `publishPost` → `/api/posts/publish`, `liveFeed` → `/_x/query/live-feed`. Tier 0 so `action`, `query` and `realtime` derive one URL with no sideways import |
 | `actionPath(name)` with no `style`, `renderedActionPathStyle()`, `CLIENT_PATH_STYLE_META` | the style nobody restates | `actionPath(name)` reads the document's `<meta name="ultimate-path-style">` stamp, so a browser caller derives under the style the server serves (`defineApi({ http: { pathStyle } })`). No document, no stamp or an unknown value is `'resource'` — a `'resource'` server writes no stamp. A named `style` is never overridden |
 | `RECORDS_HEADER`, `encodeRecordEnvelope`, `decodeRecordEnvelope`, `RecordRows` | `{ data, records?: { [type]: { [key]: Row } }, removed?: { [type]: key[] } }`, only behind `x-ultimate-records: 1` | how an answer carries entity rows without changing the wire of an answer that has none. A malformed envelope is `X_CLIENT_RECORD_ENVELOPE_INVALID` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "27.1.0",
+  "version": "27.2.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.1.0"
+    "@ultimat3/schema": "27.2.0"
   }
 }

package/src/client-dispatch.ts

@@ -54,6 +54,13 @@ export interface TransportRequest {
    * ORDER of `records[type]`, which the store (keyed, unordered) cannot give it back.
    */
   readonly onEnvelope?: ((envelope: RecordEnvelope) => void) | undefined;
+  /**
+   * How a 2xx body is read. `'json'` (the default) decodes it and adopts a records envelope;
+   * `'text'` answers the body as a string, untouched — an HTML fragment, a CSV — sends
+   * the wildcard `accept` unless `headers` says otherwise, and adopts nothing. A non-2xx is decoded as a
+   * refusal either way.
+   */
+  readonly responseType?: 'json' | 'text' | undefined;
   /** Sees every response before its body is read — a header check may throw its own refusal. */
   readonly onResponse?: ((response: Response) => void | Promise<void>) | undefined;
   /**
@@ -142,7 +149,9 @@ async function onTheWire<T>(
 
 function initOf(req: TransportRequest, signal: AbortSignal | undefined): RequestInit {
   const raw = req.rawBody !== undefined;
-  const headers: Record<string, string> = raw ? {} : { accept: 'application/json' };
+  const headers: Record<string, string> = raw
+    ? {}
+    : { accept: req.responseType === 'text' ? '*/*' : 'application/json' };
   if (req.body !== undefined && !raw) headers['content-type'] = 'application/json';
   if (req.idempotencyKey !== undefined) headers[IDEMPOTENCY_HEADER] = req.idempotencyKey;
   const body = raw ? req.rawBody : req.body === undefined ? undefined : JSON.stringify(req.body);

package/src/client-transport.ts

@@ -28,6 +28,11 @@ import { pageClient, recordSink } from './record-sink';
 
 const ONCE = { attempts: 1 } as const;
 
+/** `responseType: 'text'`: the 2xx body as a string, never decoded. */
+export function clientTransport(
+  req: TransportRequest & { readonly responseType: 'text' },
+): Promise<string>;
+export function clientTransport<T = unknown>(req: TransportRequest): Promise<T>;
 export async function clientTransport<T = unknown>(req: TransportRequest): Promise<T> {
   const read = req.method === 'GET';
   const issued = pageClient().scope.epoch;
@@ -62,6 +67,9 @@ export async function clientTransport<T = unknown>(req: TransportRequest): Promi
   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);
+  // Read as text: nothing to decode, and no records envelope — that is a JSON answer's. Before the
+  // `rawBody` return, so the overload's `Promise<string>` holds for a raw upload read as text too.
+  if (req.responseType === 'text') return answer.text as T;
   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