@client-compose/client 0.7.0 → 0.9.0

package/src/testing.ts

@@ -6,6 +6,7 @@
 //       screens: { profile: () => screen("profile", [island("header", ProfileHeaderV1, { name: "Ada" })]) },
 //       actions: { follow: () => actionOk(FollowUserV1, { followers: 8 }) },
 //       islands: { "profile/posts": (r) => islandResponse("profile", island("posts", PostsV1, …, "page:3")) },
+//       strings: () => stringsResponse("en", { retry: "Try again" }),
 //     });
 //     // pass gateway.fetch as the client's fetch, then assert on gateway.actionRequests()
 //
@@ -20,14 +21,22 @@ import {
   type IslandDescriptor,
   type IslandEntry,
   type IslandError,
+  type PendingIsland,
+  type PluralRules,
   PROTOCOL_VERSION,
   type ScreenMeta,
+  type Strings,
 } from "@client-compose/protocol";
 
-/** A response for the fake composer to send. */
+/**
+ * A response for the fake composer to send: a JSON body, or a screen's stream (spec §4.6), as
+ * lines that come when they're given.
+ */
 export interface FakeResponse {
   status: number;
-  body: unknown;
+  body?: unknown;
+  /** Opens the stream's body, for each request answered with it. */
+  stream?: () => ReadableStream<Uint8Array>;
 }
 
 /** A request the fake composer received. */
@@ -65,6 +74,11 @@ export interface RecordedActionRequest extends RecordedRequest {
   idempotencyKey: string | undefined;
 }
 
+/** A strings request (spec §4.7): the app strings, in the client's language. */
+export interface RecordedStringsRequest extends RecordedRequest {
+  client: ClientContext | undefined;
+}
+
 export interface FakeGatewayHandlers {
   /** By screen id. */
   screens?: Record<string, (request: RecordedScreenRequest) => FakeResponse>;
@@ -72,6 +86,8 @@ export interface FakeGatewayHandlers {
   actions?: Record<string, (request: RecordedActionRequest) => FakeResponse>;
   /** Island requests, by `"{screen}/{key}"`. */
   islands?: Record<string, (request: RecordedIslandRequest) => FakeResponse>;
+  /** The app strings (POST /strings). */
+  strings?: (request: RecordedStringsRequest) => FakeResponse;
   /** Anything else, e.g. uploads to storage: return undefined to leave a request to the others. */
   other?: (request: RecordedRequest) => FakeResponse | undefined;
 }
@@ -84,6 +100,7 @@ export interface FakeGateway {
   screenRequests(): RecordedScreenRequest[];
   islandRequests(): RecordedIslandRequest[];
   actionRequests(): RecordedActionRequest[];
+  stringsRequests(): RecordedStringsRequest[];
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -202,7 +219,21 @@ function asActionRequest(request: RecordedRequest): RecordedActionRequest | unde
   };
 }
 
+function asStringsRequest(request: RecordedRequest): RecordedStringsRequest | undefined {
+  const path = request.url.split("?")[0] ?? "";
+  if (!/\/strings\/?$/.test(path) || !isRecord(request.body)) {
+    return undefined;
+  }
+  return { ...request, client: clientContext(request.body.client) };
+}
+
 function respond(response: FakeResponse): Response {
+  if (response.stream) {
+    return new Response(response.stream(), {
+      status: response.status,
+      headers: { "content-type": "application/jsonl" },
+    });
+  }
   return new Response(JSON.stringify(response.body), {
     status: response.status,
     headers: { "content-type": "application/json" },
@@ -241,6 +272,10 @@ export function createFakeGateway(handlers: FakeGatewayHandlers = {}): FakeGatew
     if (actionRequest && actionHandler) {
       return respond(actionHandler(actionRequest));
     }
+    const stringsRequest = asStringsRequest(request);
+    if (stringsRequest && handlers.strings) {
+      return respond(handlers.strings(stringsRequest));
+    }
     throw new Error(
       `fake gateway: no handler for ${request.method} ${request.url} ${JSON.stringify(request.body)}`,
     );
@@ -251,6 +286,7 @@ export function createFakeGateway(handlers: FakeGatewayHandlers = {}): FakeGatew
     screenRequests: () => requests.flatMap((r) => asScreenRequest(r) ?? []),
     islandRequests: () => requests.flatMap((r) => asIslandRequest(r) ?? []),
     actionRequests: () => requests.flatMap((r) => asActionRequest(r) ?? []),
+    stringsRequests: () => requests.flatMap((r) => asStringsRequest(r) ?? []),
   };
 }
 
@@ -277,16 +313,24 @@ export function installFakeGateway(handlers: FakeGatewayHandlers = {}): Installe
 
 // ---- Responses ----
 
+/** More of an island's entry: its next page's cursor (spec §4.5), and its strings (spec §4.7). */
+export interface IslandOptions {
+  next?: string;
+  strings?: Strings;
+}
+
 /**
  * An island in a screen or island response, typed by its generated descriptor. Give `next` for an
- * island with more pages (spec §4.5).
+ * island with more pages (spec §4.5), or `{ next, strings }`.
  */
-export function island<P>(
+export function island<P, S>(
   key: string,
-  descriptor: IslandDescriptor<P>,
+  descriptor: IslandDescriptor<P, S>,
   props: P,
-  next?: string,
+  more?: string | IslandOptions,
 ): IslandEntry<P> {
+  const { next, strings } =
+    typeof more === "string" ? { next: more, strings: undefined } : (more ?? {});
   return {
     key,
     type: descriptor.type,
@@ -294,9 +338,16 @@ export function island<P>(
     status: "ok",
     props,
     ...(next !== undefined && { next }),
+    ...(strings !== undefined && { strings }),
   };
 }
 
+/** The language a screen is in, and its plural rules (spec §4.7). */
+export interface ScreenLanguage {
+  locale: string;
+  plurals: PluralRules;
+}
+
 /** An island that failed on the composer (spec §3.4). */
 export function islandError(
   key: string,
@@ -312,23 +363,121 @@ export function islandError(
   };
 }
 
-/** A screen response. */
+/** A screen, all of it at once: its stream's head with every island, then its end (spec §4.6). */
 export function screen(
   id: string,
   islands: IslandEntry<unknown>[],
   meta?: ScreenMeta,
+  language?: ScreenLanguage,
 ): FakeResponse {
+  const head = {
+    kind: "head",
+    protocol: PROTOCOL_VERSION,
+    screen: id,
+    islands,
+    ...(meta && { meta }),
+    ...language,
+  };
   return {
     status: 200,
-    body: {
-      protocol: PROTOCOL_VERSION,
-      screen: id,
-      islands,
-      ...(meta && { meta }),
+    stream: () => linesStream([head, { kind: "end" }]),
+  };
+}
+
+/** An island still being resolved, in a streamed screen's head (spec §4.6). */
+export function pending(key: string, descriptor: IslandDescriptor<unknown>): PendingIsland {
+  return {
+    key,
+    type: descriptor.type,
+    version: descriptor.version,
+    status: "pending",
+  };
+}
+
+/** A streamed screen whose lines a test sends, so it controls when each island arrives. */
+export interface StreamedScreen extends FakeResponse {
+  /** Sends a pending island's entry. */
+  send(entry: IslandEntry<unknown>): void;
+  /** Sends the end line. */
+  end(): void;
+  /** Ends the stream without its end line, as a dropped connection would. */
+  cut(): void;
+}
+
+/**
+ * A screen whose head is sent at once, with its islands resolved or `pending(…)`, and whose other
+ * lines are sent when the test says (spec §4.6). Answer one request with it.
+ *
+ *     const results = streamedScreen("search", [island("box", BoxV1, {}), pending("results", ResultsV1)]);
+ *     // render, check the placeholder, then:
+ *     results.send(island("results", ResultsV1, { items: [] }));
+ *     results.end();
+ */
+export function streamedScreen(
+  id: string,
+  islands: (IslandEntry<unknown> | PendingIsland)[],
+  meta?: ScreenMeta,
+  language?: ScreenLanguage,
+): StreamedScreen {
+  const encoder = new TextEncoder();
+  const queued: string[] = [];
+  let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let closed = false;
+  const write = (line: unknown) => {
+    const text = `${JSON.stringify(line)}\n`;
+    if (controller) {
+      controller.enqueue(encoder.encode(text));
+    } else {
+      queued.push(text);
+    }
+  };
+  const close = () => {
+    closed = true;
+    controller?.close();
+  };
+  write({
+    kind: "head",
+    protocol: PROTOCOL_VERSION,
+    screen: id,
+    islands,
+    ...(meta && { meta }),
+    ...language,
+  });
+  return {
+    status: 200,
+    stream: () =>
+      new ReadableStream<Uint8Array>({
+        start(c) {
+          controller = c;
+          for (const text of queued.splice(0)) {
+            c.enqueue(encoder.encode(text));
+          }
+          if (closed) {
+            c.close();
+          }
+        },
+      }),
+    send: (entry) => write({ kind: "island", island: entry }),
+    end: () => {
+      write({ kind: "end" });
+      close();
     },
+    cut: close,
   };
 }
 
+function linesStream(lines: unknown[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      for (const line of lines) {
+        controller.enqueue(encoder.encode(`${JSON.stringify(line)}\n`));
+      }
+      controller.close();
+    },
+  });
+}
+
 /** An island response (spec §4.5): a page of one island, or the island resolved again. */
 export function islandResponse(screen: string, entry: IslandEntry<unknown>): FakeResponse {
   return {
@@ -341,6 +490,23 @@ export function islandResponse(screen: string, entry: IslandEntry<unknown>): Fak
   };
 }
 
+/** The app strings in a language (spec §4.7), with its plural rules if its counted strings need them. */
+export function stringsResponse(
+  locale: string,
+  strings: Strings,
+  plurals: PluralRules = {},
+): FakeResponse {
+  return {
+    status: 200,
+    body: {
+      protocol: PROTOCOL_VERSION,
+      locale,
+      plurals,
+      strings,
+    },
+  };
+}
+
 /** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
 export function screenError(status: number, code: string): FakeResponse {
   return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };