@client-compose/client 0.6.0 → 0.8.0

package/src/proxy.ts

@@ -18,15 +18,26 @@ import {
   type ActionResponse,
   type Capabilities,
   type ClientContext,
+  type IslandEntry,
+  type IslandRequest,
   PROTOCOL_VERSION,
   type ScreenRequest,
   type ScreenResponse,
 } from "@client-compose/protocol";
 
-import { ActionFetchError, fetchAction, fetchScreen, ScreenFetchError } from "./index.ts";
+import {
+  ActionFetchError,
+  fetchAction,
+  fetchIsland,
+  fetchScreen,
+  IslandFetchError,
+  ScreenFetchError,
+} from "./index.ts";
 
 /** A screen request from the browser: the server sets the client context. */
 export type ProxiedScreenRequest = Omit<ScreenRequest, "client">;
+/** An island request from the browser: the server sets the client context. */
+export type ProxiedIslandRequest = Omit<IslandRequest, "client">;
 /** An action request from the browser: the server sets the client context. */
 export type ProxiedActionRequest = Omit<ActionRequest, "client">;
 
@@ -60,6 +71,11 @@ export interface ComposerProxy {
   performAction(body: unknown): Promise<ProxyResult<ActionResponse>>;
   /** Checks a browser's screen request, then loads it with the server's context and headers. */
   loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>>;
+  /**
+   * Checks a browser's island request (a page of an island, spec §4.5), then loads it with the
+   * server's context and headers. Resolves with the island's entry.
+   */
+  loadIsland(body: unknown): Promise<ProxyResult<IslandEntry>>;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -78,25 +94,48 @@ function isStringRecord(value: unknown): value is Record<string, string> {
   return isRecord(value) && Object.values(value).every((v) => typeof v === "string");
 }
 
+// Each guard returns at the first thing a request gets wrong, so it checks no more than it must.
+
 export function isProxiedScreenRequest(value: unknown): value is ProxiedScreenRequest {
-  return (
-    isRecord(value) &&
-    value.protocol === PROTOCOL_VERSION &&
-    typeof value.screen === "string" &&
-    (value.params === undefined || isStringRecord(value.params)) &&
-    isCapabilities(value.islands)
-  );
+  if (!isRecord(value) || value.protocol !== PROTOCOL_VERSION) {
+    return false;
+  }
+  if (typeof value.screen !== "string") {
+    return false;
+  }
+  if (value.params !== undefined && !isStringRecord(value.params)) {
+    return false;
+  }
+  return isCapabilities(value.islands);
+}
+
+export function isProxiedIslandRequest(value: unknown): value is ProxiedIslandRequest {
+  if (!isRecord(value) || value.protocol !== PROTOCOL_VERSION) {
+    return false;
+  }
+  if (typeof value.screen !== "string" || typeof value.key !== "string") {
+    return false;
+  }
+  if (typeof value.version !== "number" || !Number.isInteger(value.version)) {
+    return false;
+  }
+  if (value.params !== undefined && !isStringRecord(value.params)) {
+    return false;
+  }
+  return value.cursor === undefined || typeof value.cursor === "string";
 }
 
 export function isProxiedActionRequest(value: unknown): value is ProxiedActionRequest {
-  return (
-    isRecord(value) &&
-    value.protocol === PROTOCOL_VERSION &&
-    typeof value.action === "string" &&
-    typeof value.version === "number" &&
-    "input" in value &&
-    (value.idempotencyKey === undefined || typeof value.idempotencyKey === "string")
-  );
+  if (!isRecord(value) || value.protocol !== PROTOCOL_VERSION) {
+    return false;
+  }
+  if (typeof value.action !== "string" || typeof value.version !== "number") {
+    return false;
+  }
+  if (!("input" in value)) {
+    return false;
+  }
+  return value.idempotencyKey === undefined || typeof value.idempotencyKey === "string";
 }
 
 /** What the composer itself answers to a malformed request. */
@@ -108,12 +147,17 @@ const BAD_REQUEST = {
 
 export function createComposerProxy(options: ComposerProxyOptions): ComposerProxy {
   async function init(): Promise<RequestInit> {
-    const headers = (await options.headers?.()) ?? {};
-    return { ...options.requestInit, headers: { ...options.requestInit?.headers, ...headers } };
+    const headers = new Headers(options.requestInit?.headers);
+    for (const [name, value] of Object.entries((await options.headers?.()) ?? {})) {
+      headers.set(name, value);
+    }
+    return { ...options.requestInit, headers };
   }
 
   async function performAction(body: unknown): Promise<ProxyResult<ActionResponse>> {
-    if (!isProxiedActionRequest(body)) return BAD_REQUEST;
+    if (!isProxiedActionRequest(body)) {
+      return BAD_REQUEST;
+    }
     const request: ActionRequest = { ...body, client: await options.client() };
     try {
       const response = await fetchAction(options.baseUrl, request, await init(), options.fetch);
@@ -122,14 +166,21 @@ export function createComposerProxy(options: ComposerProxyOptions): ComposerProx
         response: (await options.onActionResponse?.(request, response)) ?? response,
       };
     } catch (error) {
-      if (error instanceof ActionFetchError)
-        return { ok: false, status: error.status, body: error.body };
+      if (error instanceof ActionFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
       throw error;
     }
   }
 
   async function loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>> {
-    if (!isProxiedScreenRequest(body)) return BAD_REQUEST;
+    if (!isProxiedScreenRequest(body)) {
+      return BAD_REQUEST;
+    }
     const request: ScreenRequest = { ...body, client: await options.client() };
     try {
       return {
@@ -137,11 +188,42 @@ export function createComposerProxy(options: ComposerProxyOptions): ComposerProx
         response: await fetchScreen(options.baseUrl, request, await init(), options.fetch),
       };
     } catch (error) {
-      if (error instanceof ScreenFetchError)
-        return { ok: false, status: error.status, body: error.body };
+      if (error instanceof ScreenFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async function loadIsland(body: unknown): Promise<ProxyResult<IslandEntry>> {
+    if (!isProxiedIslandRequest(body)) {
+      return BAD_REQUEST;
+    }
+    const request: IslandRequest = { ...body, client: await options.client() };
+    try {
+      return {
+        ok: true,
+        response: await fetchIsland(options.baseUrl, request, await init(), options.fetch),
+      };
+    } catch (error) {
+      if (error instanceof IslandFetchError) {
+        return {
+          ok: false,
+          status: error.status,
+          body: error.body,
+        };
+      }
       throw error;
     }
   }
 
-  return { performAction, loadScreen };
+  return {
+    performAction,
+    loadScreen,
+    loadIsland,
+  };
 }

package/src/testing.ts

@@ -5,6 +5,7 @@
 //     const gateway = createFakeGateway({
 //       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")) },
 //     });
 //     // pass gateway.fetch as the client's fetch, then assert on gateway.actionRequests()
 //
@@ -19,14 +20,20 @@ import {
   type IslandDescriptor,
   type IslandEntry,
   type IslandError,
+  type PendingIsland,
   PROTOCOL_VERSION,
   type ScreenMeta,
 } 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. */
@@ -46,6 +53,16 @@ export interface RecordedScreenRequest extends RecordedRequest {
   islands: Capabilities;
 }
 
+/** An island request (spec §4.5): a page of one island, or the island resolved again. */
+export interface RecordedIslandRequest extends RecordedRequest {
+  screen: string;
+  key: string;
+  version: number;
+  params: Record<string, string>;
+  cursor: string | undefined;
+  client: ClientContext | undefined;
+}
+
 export interface RecordedActionRequest extends RecordedRequest {
   action: string;
   version: number;
@@ -59,6 +76,8 @@ export interface FakeGatewayHandlers {
   screens?: Record<string, (request: RecordedScreenRequest) => FakeResponse>;
   /** By action name. */
   actions?: Record<string, (request: RecordedActionRequest) => FakeResponse>;
+  /** Island requests, by `"{screen}/{key}"`. */
+  islands?: Record<string, (request: RecordedIslandRequest) => FakeResponse>;
   /** Anything else, e.g. uploads to storage: return undefined to leave a request to the others. */
   other?: (request: RecordedRequest) => FakeResponse | undefined;
 }
@@ -69,6 +88,7 @@ export interface FakeGateway {
   /** Every request received, in order. */
   requests: RecordedRequest[];
   screenRequests(): RecordedScreenRequest[];
+  islandRequests(): RecordedIslandRequest[];
   actionRequests(): RecordedActionRequest[];
 }
 
@@ -76,14 +96,18 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
 function strings(value: unknown): Record<string, string> {
-  if (!isRecord(value)) return {};
+  if (!isRecord(value)) {
+    return {};
+  }
   return Object.fromEntries(
     Object.entries(value).filter((e): e is [string, string] => typeof e[1] === "string"),
   );
 }
 
 function capabilities(value: unknown): Capabilities {
-  if (!isRecord(value)) return {};
+  if (!isRecord(value)) {
+    return {};
+  }
   return Object.fromEntries(
     Object.entries(value).map(([type, versions]) => [
       type,
@@ -97,13 +121,20 @@ function clientContext(value: unknown): ClientContext | undefined {
     !isRecord(value) ||
     typeof value.platform !== "string" ||
     typeof value.appVersion !== "string"
-  )
+  ) {
     return undefined;
-  return { ...value, platform: value.platform, appVersion: value.appVersion } as ClientContext;
+  }
+  return {
+    ...value,
+    platform: value.platform,
+    appVersion: value.appVersion,
+  } as ClientContext;
 }
 
 function parseBody(body: unknown): unknown {
-  if (typeof body !== "string") return body;
+  if (typeof body !== "string") {
+    return body;
+  }
   try {
     return JSON.parse(body) as unknown;
   } catch {
@@ -112,7 +143,9 @@ function parseBody(body: unknown): unknown {
 }
 
 function urlOf(input: RequestInfo | URL): string {
-  if (typeof input === "string") return input;
+  if (typeof input === "string") {
+    return input;
+  }
   return input instanceof URL ? input.href : input.url;
 }
 
@@ -122,10 +155,16 @@ function headersOf(init: HeadersInit | undefined): Record<string, string> {
   return out;
 }
 
+function isIslandURL(url: string): boolean {
+  return /\/screens\/[^/]+\/islands\/[^/?]+/.test(url);
+}
+
 function asScreenRequest(request: RecordedRequest): RecordedScreenRequest | undefined {
   const { body } = request;
-  if (!request.url.includes("/screens/") || !isRecord(body) || typeof body.screen !== "string")
+  const isScreen = request.url.includes("/screens/") && !isIslandURL(request.url);
+  if (!isScreen || !isRecord(body) || typeof body.screen !== "string") {
     return undefined;
+  }
   return {
     ...request,
     screen: body.screen,
@@ -135,10 +174,30 @@ function asScreenRequest(request: RecordedRequest): RecordedScreenRequest | unde
   };
 }
 
+function asIslandRequest(request: RecordedRequest): RecordedIslandRequest | undefined {
+  const { body } = request;
+  if (!isIslandURL(request.url) || !isRecord(body)) {
+    return undefined;
+  }
+  if (typeof body.screen !== "string" || typeof body.key !== "string") {
+    return undefined;
+  }
+  return {
+    ...request,
+    screen: body.screen,
+    key: body.key,
+    version: typeof body.version === "number" ? body.version : 0,
+    params: strings(body.params),
+    cursor: typeof body.cursor === "string" ? body.cursor : undefined,
+    client: clientContext(body.client),
+  };
+}
+
 function asActionRequest(request: RecordedRequest): RecordedActionRequest | undefined {
   const { body } = request;
-  if (!request.url.includes("/actions/") || !isRecord(body) || typeof body.action !== "string")
+  if (!request.url.includes("/actions/") || !isRecord(body) || typeof body.action !== "string") {
     return undefined;
+  }
   return {
     ...request,
     action: body.action,
@@ -150,6 +209,12 @@ function asActionRequest(request: RecordedRequest): RecordedActionRequest | unde
 }
 
 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" },
@@ -169,13 +234,25 @@ export function createFakeGateway(handlers: FakeGatewayHandlers = {}): FakeGatew
     requests.push(request);
 
     const other = handlers.other?.(request);
-    if (other) return respond(other);
+    if (other) {
+      return respond(other);
+    }
+    const islandRequest = asIslandRequest(request);
+    const islandHandler =
+      islandRequest && handlers.islands?.[`${islandRequest.screen}/${islandRequest.key}`];
+    if (islandRequest && islandHandler) {
+      return respond(islandHandler(islandRequest));
+    }
     const screenRequest = asScreenRequest(request);
     const screenHandler = screenRequest && handlers.screens?.[screenRequest.screen];
-    if (screenRequest && screenHandler) return respond(screenHandler(screenRequest));
+    if (screenRequest && screenHandler) {
+      return respond(screenHandler(screenRequest));
+    }
     const actionRequest = asActionRequest(request);
     const actionHandler = actionRequest && handlers.actions?.[actionRequest.action];
-    if (actionRequest && actionHandler) return respond(actionHandler(actionRequest));
+    if (actionRequest && actionHandler) {
+      return respond(actionHandler(actionRequest));
+    }
     throw new Error(
       `fake gateway: no handler for ${request.method} ${request.url} ${JSON.stringify(request.body)}`,
     );
@@ -184,6 +261,7 @@ export function createFakeGateway(handlers: FakeGatewayHandlers = {}): FakeGatew
     fetch: fakeFetch,
     requests,
     screenRequests: () => requests.flatMap((r) => asScreenRequest(r) ?? []),
+    islandRequests: () => requests.flatMap((r) => asIslandRequest(r) ?? []),
     actionRequests: () => requests.flatMap((r) => asActionRequest(r) ?? []),
   };
 }
@@ -211,9 +289,24 @@ export function installFakeGateway(handlers: FakeGatewayHandlers = {}): Installe
 
 // ---- Responses ----
 
-/** An island in a screen response, typed by its generated descriptor. */
-export function island<P>(key: string, descriptor: IslandDescriptor<P>, props: P): IslandEntry<P> {
-  return { key, type: descriptor.type, version: descriptor.version, status: "ok", props };
+/**
+ * An island in a screen or island response, typed by its generated descriptor. Give `next` for an
+ * island with more pages (spec §4.5).
+ */
+export function island<P>(
+  key: string,
+  descriptor: IslandDescriptor<P>,
+  props: P,
+  next?: string,
+): IslandEntry<P> {
+  return {
+    key,
+    type: descriptor.type,
+    version: descriptor.version,
+    status: "ok",
+    props,
+    ...(next !== undefined && { next }),
+  };
 }
 
 /** An island that failed on the composer (spec §3.4). */
@@ -222,18 +315,135 @@ export function islandError(
   descriptor: IslandDescriptor<unknown>,
   error: IslandError,
 ): IslandEntry {
-  return { key, type: descriptor.type, version: descriptor.version, status: "error", error };
+  return {
+    key,
+    type: descriptor.type,
+    version: descriptor.version,
+    status: "error",
+    error,
+  };
 }
 
-/** 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,
 ): FakeResponse {
+  const head = {
+    kind: "head",
+    protocol: PROTOCOL_VERSION,
+    screen: id,
+    islands,
+    ...(meta && { meta }),
+  };
   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,
+): 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 }),
+  });
+  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 {
+    status: 200,
+    body: {
+      protocol: PROTOCOL_VERSION,
+      screen,
+      island: entry,
+    },
   };
 }
 
@@ -248,8 +458,20 @@ export function actionOk<I, R, E extends DeclaredError>(
   result: R,
   effects?: ActionEffects,
 ): FakeResponse {
-  const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
-  return { status: 200, body: { ...base, status: "ok", result, ...(effects && { effects }) } };
+  const base = {
+    protocol: PROTOCOL_VERSION,
+    action: action.action,
+    version: action.version,
+  };
+  return {
+    status: 200,
+    body: {
+      ...base,
+      status: "ok",
+      result,
+      ...(effects && { effects }),
+    },
+  };
 }
 
 /** An action that ended with one of its declared errors. */
@@ -257,8 +479,19 @@ export function actionError<I, R, E extends DeclaredError>(
   action: ActionDescriptor<I, R, E>,
   error: E,
 ): FakeResponse {
-  const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
-  return { status: 200, body: { ...base, status: "error", error } };
+  const base = {
+    protocol: PROTOCOL_VERSION,
+    action: action.action,
+    version: action.version,
+  };
+  return {
+    status: 200,
+    body: {
+      ...base,
+      status: "error",
+      error,
+    },
+  };
 }
 
 /** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */