@client-compose/client 0.7.0 → 0.9.0

package/src/index.ts

@@ -12,31 +12,90 @@ import {
   type IslandEntry,
   type IslandRequest,
   type IslandResponse,
+  type PluralRules,
   PROTOCOL_VERSION,
+  type ScreenHead,
   type ScreenRequest,
   type ScreenResponse,
+  type StringParams,
 } from "@client-compose/protocol";
 
+import { buildStrings } from "./strings.ts";
+
+export {
+  appStrings,
+  buildStrings,
+  fetchStrings,
+  formatString,
+  pluralCategory,
+  StringsFetchError,
+  type StringValues,
+} from "./strings.ts";
+
 type OkEntry<P = unknown> = IslandEntry<P> & { status: "ok" };
 type ErrorEntry = IslandEntry & { status: "error" };
 
-export type IslandRenderer<R, P = unknown> = (props: P, entry: OkEntry<P>) => R;
+/**
+ * An island's props as its renderer gets them: with its strings as `t` (spec §4.7), if its
+ * descriptor declares any.
+ */
+export type WithStrings<P, S> = P & (unknown extends S ? unknown : { t: S });
+
+/**
+ * Renders an island: its props (with `t`, if it declares strings), its entry as the composer sent
+ * it, and the screen's plural rules (spec §4.7).
+ */
+export type IslandRenderer<R, P = unknown> = (props: P, entry: OkEntry, plurals?: PluralRules) => R;
+
+/** What a client shows for an island still pending in a stream's head (spec §4.6). */
+export type IslandPlaceholder<R> = () => R;
 
 export class IslandRegistry<R> {
   private renderers = new Map<string, Map<number, IslandRenderer<R>>>();
+  private placeholders = new Map<string, IslandPlaceholder<R>>();
+  private declaredStrings = new Map<string, StringParams>();
+  // Each entry's props with its `t`, made once: a screen streaming in plans again with each island
+  // that arrives, and the islands already shown keep the props they were rendered with.
+  private propsMade = new WeakMap<object, { plurals?: PluralRules; props: unknown }>();
+
+  /**
+   * Register a placeholder for an island version, shown while it's pending in a stream's head
+   * (spec §4.6). Each app draws its own: the protocol says nothing about how one looks.
+   */
+  registerPlaceholder(island: IslandDescriptor<unknown>, placeholder: IslandPlaceholder<R>): this {
+    this.placeholders.set(`${island.type}@${island.version}`, placeholder);
+    return this;
+  }
 
-  /** Register a renderer for a generated island descriptor: `register(ProfileHeaderV2, (props) => …)`. */
-  register<P>(island: IslandDescriptor<P>, render: IslandRenderer<R, P>): this;
+  /** The placeholder for an island version, if one was registered. */
+  placeholder(type: string, version: number): IslandPlaceholder<R> | undefined {
+    return this.placeholders.get(`${type}@${version}`);
+  }
+
+  /**
+   * Register a renderer for a generated island descriptor: `register(ProfileHeaderV2, (props) => …)`.
+   * If the island declares strings, its props have them as `t`: `props.t.heading`.
+   */
+  register<P, S>(
+    island: IslandDescriptor<P, S>,
+    render: IslandRenderer<R, WithStrings<P, S>>,
+  ): this;
   register<P>(type: string, version: number, render: IslandRenderer<R, P>): this;
-  register<P>(
-    islandOrType: IslandDescriptor<P> | string,
-    versionOrRender: number | IslandRenderer<R, P>,
+  register<P, S>(
+    islandOrType: IslandDescriptor<P, S> | string,
+    versionOrRender: number | IslandRenderer<R, WithStrings<P, S>>,
     maybeRender?: IslandRenderer<R, P>,
   ): this {
     if (typeof islandOrType !== "string") {
       if (typeof versionOrRender === "number") {
         throw new Error("register(descriptor, render): pass the renderer, not a version");
       }
+      const id = `${islandOrType.type}@${islandOrType.version}`;
+      if (islandOrType.strings) {
+        this.declaredStrings.set(id, islandOrType.strings);
+      } else {
+        this.declaredStrings.delete(id);
+      }
       return this.add(islandOrType.type, islandOrType.version, versionOrRender);
     }
     if (typeof versionOrRender !== "number" || !maybeRender) {
@@ -67,6 +126,27 @@ export class IslandRegistry<R> {
   get(type: string, version: number): IslandRenderer<R> | undefined {
     return this.renderers.get(type)?.get(version);
   }
+
+  /**
+   * An island's props as its renderer gets them: with its strings as `t`, built with the screen's
+   * plural rules, if its descriptor declares any.
+   */
+  propsOf(entry: OkEntry, plurals: PluralRules | undefined): unknown {
+    const declared = this.declaredStrings.get(`${entry.type}@${entry.version}`);
+    if (!declared) {
+      return entry.props;
+    }
+    const made = this.propsMade.get(entry);
+    if (made && made.plurals === plurals) {
+      return made.props;
+    }
+    const props = {
+      ...(typeof entry.props === "object" ? entry.props : {}),
+      t: buildStrings(declared, entry.strings, plurals),
+    };
+    this.propsMade.set(entry, { plurals, props });
+    return props;
+  }
 }
 
 export function buildRequest(
@@ -87,6 +167,8 @@ export function buildRequest(
 export interface PlannedIsland<R> {
   key: string;
   render: () => R;
+  /** It's a placeholder, for an island still pending in a stream's head (spec §4.6). */
+  pending?: boolean;
 }
 
 export type SkipReason = "unknown_island" | "unknown_status";
@@ -98,14 +180,30 @@ export interface PlanOptions<R> {
   onSkipped?: (entry: IslandEntry, reason: SkipReason) => void;
 }
 
-/** Turn a response into an ordered list of renderable islands. */
+/**
+ * Turn a screen, or a stream's head (spec §4.6), into an ordered list of renderable islands. An
+ * island still pending is its registered placeholder, or left out until it arrives.
+ */
 export function plan<R>(
   registry: IslandRegistry<R>,
-  response: ScreenResponse,
+  response: ScreenResponse | ScreenHead,
   options: PlanOptions<R> = {},
 ): PlannedIsland<R>[] {
   const out: PlannedIsland<R>[] = [];
   for (const entry of response.islands) {
+    if (entry.status === "pending") {
+      const placeholder = registry.get(entry.type, entry.version)
+        ? registry.placeholder(entry.type, entry.version)
+        : undefined;
+      if (placeholder) {
+        out.push({
+          key: entry.key,
+          render: placeholder,
+          pending: true,
+        });
+      }
+      continue;
+    }
     if (entry.status === "error") {
       const fallback = options.onError?.(entry);
       if (fallback !== undefined) {
@@ -122,7 +220,8 @@ export function plan<R>(
       options.onSkipped?.(entry, "unknown_island");
       continue;
     }
-    out.push({ key: entry.key, render: () => renderer(entry.props, entry) });
+    const props = registry.propsOf(entry, response.plurals);
+    out.push({ key: entry.key, render: () => renderer(props, entry, response.plurals) });
   }
   return out;
 }
@@ -150,13 +249,6 @@ function isIslandEntry(value: unknown): value is IslandEntry {
   return named && typeof value.version === "number" && typeof value.status === "string";
 }
 
-function isScreenResponse(value: unknown): value is ScreenResponse {
-  if (!isRecord(value) || typeof value.screen !== "string") {
-    return false;
-  }
-  return Array.isArray(value.islands) && value.islands.every(isIslandEntry);
-}
-
 /** An action's outcome: what a client needs of one is its status (the client fixtures, spec §8.2). */
 function isActionResponse(value: unknown): value is ActionResponse {
   return isRecord(value) && (value.status === "ok" || value.status === "error");
@@ -199,27 +291,163 @@ function jsonHeaders(init: HeadersInit | undefined): Headers {
   return headers;
 }
 
+/**
+ * Fetch a screen, all of it: its stream (spec §4.6) read to the end. Throws ScreenFetchError for a
+ * non-2xx response (e.g. `not_found`) or one that isn't a screen. To show its islands as they
+ * arrive, use openScreen.
+ */
 export async function fetchScreen(
   baseUrl: string,
   request: ScreenRequest,
   init: RequestInit = {},
   fetchImpl: typeof fetch = fetch,
 ): Promise<ScreenResponse> {
+  return collectScreen(await openScreen(baseUrl, request, init, fetchImpl));
+}
+
+// ---- Streams (spec §4.6) ----
+
+/** A screen as it arrives: its head, then each pending island as the composer resolves it. */
+export interface ScreenStream {
+  /** The screen, its islands resolved or pending. */
+  head: ScreenHead;
+  /**
+   * Each pending island's entry, as it arrives. If the stream ends early, those that never came
+   * arrive as errors: `incomplete`, retryable.
+   */
+  islands: AsyncIterable<IslandEntry>;
+}
+
+/**
+ * Request a screen, and resolve once its head has arrived. Throws ScreenFetchError for a non-2xx
+ * response (e.g. `not_found`) or one that isn't a screen's stream.
+ */
+export async function openScreen(
+  baseUrl: string,
+  request: ScreenRequest,
+  init: RequestInit = {},
+  fetchImpl: typeof fetch = fetch,
+): Promise<ScreenStream> {
   const res = await fetchImpl(`${baseUrl}/screens/${encodeURIComponent(request.screen)}`, {
     ...init,
     method: "POST",
     headers: jsonHeaders(init.headers),
     body: JSON.stringify(request),
   });
-  const text = await res.text();
   if (!res.ok) {
-    throw new ScreenFetchError(res.status, text);
+    throw new ScreenFetchError(res.status, await res.text());
   }
-  const response = parseJson(text);
-  if (!isScreenResponse(response)) {
-    throw new ScreenFetchError(res.status, text);
+  const lines = linesOf(res)[Symbol.asyncIterator]();
+  const first = await lines.next();
+  const head = first.done ? undefined : parseJson(first.value);
+  if (!isRecord(head) || head.kind !== "head" || !isScreenHead(head)) {
+    await lines.return?.();
+    throw new ScreenFetchError(res.status, first.done ? "" : first.value);
+  }
+  const { kind: _kind, ...screen } = head;
+  return { head: screen, islands: pendingIslands(screen, lines) };
+}
+
+/** Reads the rest of a stream, and returns the screen with every island in place. */
+export async function collectScreen(stream: ScreenStream): Promise<ScreenResponse> {
+  let head = stream.head;
+  for await (const entry of stream.islands) {
+    head = withIsland(head, entry);
+  }
+  return {
+    ...head,
+    islands: head.islands.filter((e): e is IslandEntry => e.status !== "pending"),
+  };
+}
+
+/** The head with a pending island's entry in its place; unchanged if the key isn't pending. */
+export function withIsland(head: ScreenHead, entry: IslandEntry): ScreenHead {
+  return {
+    ...head,
+    islands: head.islands.map((e) => (e.key === entry.key && e.status === "pending" ? entry : e)),
+  };
+}
+
+/** A screen's head and end as a stream, for a screen that's already complete (spec §4.6). */
+export function screenLines(screen: ScreenResponse): string {
+  return `${JSON.stringify({ kind: "head", ...screen })}\n${JSON.stringify({ kind: "end" })}\n`;
+}
+
+function isScreenHead(
+  value: Record<string, unknown>,
+): value is Record<string, unknown> & ScreenHead {
+  return (
+    typeof value.screen === "string" &&
+    Array.isArray(value.islands) &&
+    value.islands.every(isIslandEntry)
+  );
+}
+
+/** The islands pending in `head`, as `lines` bring them, until the end line. */
+async function* pendingIslands(
+  head: ScreenHead,
+  lines: AsyncIterator<string>,
+): AsyncIterable<IslandEntry> {
+  const waiting = new Map(
+    head.islands.filter((e) => e.status === "pending").map((e) => [e.key, e]),
+  );
+  try {
+    while (waiting.size > 0) {
+      const next = await lines.next();
+      if (next.done) {
+        break;
+      }
+      const line = parseJson(next.value);
+      if (!isRecord(line) || line.kind === "end") {
+        break;
+      }
+      // Lines of a kind it doesn't know, or for an island that isn't pending, are skipped (spec §4.6).
+      const entry = line.kind === "island" && isRecord(line.island) ? line.island : undefined;
+      if (entry?.status !== "pending" && isIslandEntry(entry) && waiting.delete(entry.key)) {
+        yield entry;
+      }
+    }
+  } finally {
+    await lines.return?.();
+  }
+  for (const e of waiting.values()) {
+    yield {
+      key: e.key,
+      type: e.type,
+      version: e.version,
+      status: "error",
+      error: { code: "incomplete", retryable: true },
+    };
+  }
+}
+
+/** A body's lines, as they arrive if the body can be read as a stream, or all at once. */
+async function* linesOf(res: Response): AsyncIterable<string> {
+  if (!res.body) {
+    yield* (await res.text()).split("\n").filter((line) => line !== "");
+    return;
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffered += decoder.decode(value, { stream: true });
+      const lines = buffered.split("\n");
+      buffered = lines.pop() ?? "";
+      yield* lines.filter((line) => line !== "");
+    }
+    buffered += decoder.decode();
+    if (buffered.trim() !== "") {
+      yield buffered;
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
   }
-  return response;
 }
 
 // ---- Island requests (spec §4.5) ----

package/src/proxy.ts

@@ -23,6 +23,7 @@ import {
   PROTOCOL_VERSION,
   type ScreenRequest,
   type ScreenResponse,
+  type StringsResponse,
 } from "@client-compose/protocol";
 
 import {
@@ -33,6 +34,7 @@ import {
   IslandFetchError,
   ScreenFetchError,
 } from "./index.ts";
+import { fetchStrings, StringsFetchError } from "./strings.ts";
 
 /** A screen request from the browser: the server sets the client context. */
 export type ProxiedScreenRequest = Omit<ScreenRequest, "client">;
@@ -76,6 +78,8 @@ export interface ComposerProxy {
    * server's context and headers. Resolves with the island's entry.
    */
   loadIsland(body: unknown): Promise<ProxyResult<IslandEntry>>;
+  /** Loads the app strings (spec §4.7) in the server's client context's language. */
+  loadStrings(): Promise<ProxyResult<StringsResponse>>;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -221,9 +225,33 @@ export function createComposerProxy(options: ComposerProxyOptions): ComposerProx
     }
   }
 
+  async function loadStrings(): Promise<ProxyResult<StringsResponse>> {
+    try {
+      return {
+        ok: true,
+        response: await fetchStrings(
+          options.baseUrl,
+          await options.client(),
+          await init(),
+          options.fetch,
+        ),
+      };
+    } catch (error) {
+      if (error instanceof StringsFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
+      throw error;
+    }
+  }
+
   return {
     performAction,
     loadScreen,
     loadIsland,
+    loadStrings,
   };
 }

package/src/strings.ts

@@ -0,0 +1,178 @@
+// Strings (spec §4.7): the words a client shows, from the composer. Templates are filled in here,
+// counted strings pick their variant by the language's plural rules, and an island's strings
+// become the typed `t` its renderer receives.
+
+import {
+  type AppStringsDescriptor,
+  type ClientContext,
+  type PluralRules,
+  PROTOCOL_VERSION,
+  type StringParams,
+  type Strings,
+  type StringsResponse,
+  type StringTemplate,
+} from "@client-compose/protocol";
+
+// ---- Plural rules ----
+
+/** A count's plural category in a language: the first whose condition holds, or "other". */
+export function pluralCategory(rules: PluralRules | undefined, count: number): string {
+  for (const [category, condition] of Object.entries(rules ?? {})) {
+    if (condition !== undefined && holds(condition, count)) {
+      return category;
+    }
+  }
+  return "other";
+}
+
+/**
+ * Whether a CLDR plural condition holds for a whole number: `or` of `and`s of relations like
+ * `i % 10 = 2..4` or `v = 0`. For a whole number, `n` and `i` are the number, and `v`, `w`, `f`,
+ * `t`, `c` and `e` are zero.
+ */
+function holds(condition: string, count: number): boolean {
+  return condition.split(" or ").some((all) => all.split(" and ").every((r) => relates(r, count)));
+}
+
+const RELATION = /^\s*([nivwftce])\s*(?:%\s*(\d+))?\s*(!=|=)\s*(.+?)\s*$/;
+
+function relates(relation: string, count: number): boolean {
+  const match = RELATION.exec(relation);
+  if (!match) {
+    return false;
+  }
+  const [, operand = "", modulus, op, ranges = ""] = match;
+  const base = operand === "n" || operand === "i" ? Math.abs(Math.trunc(count)) : 0;
+  const value = modulus === undefined ? base : base % Number(modulus);
+  const inRanges = ranges.split(",").some((range) => {
+    const [from = "", to] = range.trim().split("..");
+    return to === undefined ? value === Number(from) : value >= Number(from) && value <= Number(to);
+  });
+  return op === "=" ? inRanges : !inRanges;
+}
+
+// ---- Templates ----
+
+/** The values a string's params take. A counted string's `count` picks its variant. */
+export type StringValues = Record<string, string | number>;
+
+/**
+ * A string's words with its params filled in. Variants are chosen by the exact count, then its
+ * plural category, then `#*`.
+ */
+export function formatString(
+  template: StringTemplate | undefined,
+  values: StringValues = {},
+  plurals?: PluralRules,
+): string {
+  if (template === undefined) {
+    return "";
+  }
+  const text = typeof template === "string" ? template : variant(template, values.count, plurals);
+  return text.replace(/\{([A-Za-z0-9]+)\}/g, (slot, name: string) =>
+    name in values ? String(values[name]) : slot,
+  );
+}
+
+function variant(
+  variants: Record<string, string>,
+  count: string | number | undefined,
+  plurals: PluralRules | undefined,
+): string {
+  const n = Number(count);
+  if (Number.isFinite(n)) {
+    const exact = variants[`#${n}`];
+    if (exact !== undefined) {
+      return exact;
+    }
+    const category = variants[`#${pluralCategory(plurals, n)}`];
+    if (category !== undefined) {
+      return category;
+    }
+  }
+  return variants["#*"] ?? "";
+}
+
+/**
+ * Strings as a renderer receives them: each declared string with no params as its text, each with
+ * params as a function filling them in. A string the composer didn't send is empty.
+ */
+export function buildStrings<S>(
+  declared: StringParams,
+  strings: Strings | undefined,
+  plurals: PluralRules | undefined,
+): S {
+  const t: Record<string, string | ((values: StringValues) => string)> = {};
+  for (const [key, params] of Object.entries(declared)) {
+    const template = strings?.[key];
+    t[key] =
+      params.length === 0
+        ? formatString(template, {}, plurals)
+        : (values: StringValues) => formatString(template, values, plurals);
+  }
+  // The declared keys and params are the ones codegen typed S with.
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return t as S;
+}
+
+// ---- App strings ----
+
+/** The app strings, typed by their generated descriptor: `appStrings(AppStrings, response).retry`. */
+export function appStrings<S>(descriptor: AppStringsDescriptor<S>, response: StringsResponse): S {
+  return buildStrings<S>(descriptor.strings, response.strings, response.plurals);
+}
+
+/** Thrown for a strings request the composer didn't answer with 200 and its strings. */
+export class StringsFetchError extends Error {
+  readonly status: number;
+  readonly body: string;
+
+  constructor(status: number, body: string) {
+    super(`Strings request failed with status ${status}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function isStringsResponse(value: unknown): value is StringsResponse {
+  if (!isRecord(value) || typeof value.locale !== "string") {
+    return false;
+  }
+  return isRecord(value.plurals) && isRecord(value.strings);
+}
+
+/** Fetch the app strings in the client's language (spec §4.7). */
+export async function fetchStrings(
+  baseUrl: string,
+  client: ClientContext,
+  init: RequestInit = {},
+  fetchImpl: typeof fetch = fetch,
+): Promise<StringsResponse> {
+  const headers = new Headers(init.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const res = await fetchImpl(`${baseUrl}/strings`, {
+    ...init,
+    method: "POST",
+    headers,
+    body: JSON.stringify({ protocol: PROTOCOL_VERSION, client }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new StringsFetchError(res.status, text);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new StringsFetchError(res.status, text);
+  }
+  if (!isStringsResponse(parsed)) {
+    throw new StringsFetchError(res.status, text);
+  }
+  return parsed;
+}