@client-compose/client 0.5.1 → 0.7.0

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()
 //
@@ -46,6 +47,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 +70,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 +82,7 @@ export interface FakeGateway {
   /** Every request received, in order. */
   requests: RecordedRequest[];
   screenRequests(): RecordedScreenRequest[];
+  islandRequests(): RecordedIslandRequest[];
   actionRequests(): RecordedActionRequest[];
 }
 
@@ -76,14 +90,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 +115,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 +137,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 +149,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 +168,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,
@@ -169,13 +222,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 +249,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 +277,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,7 +303,13 @@ 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. */
@@ -233,7 +320,24 @@ export function screen(
 ): FakeResponse {
   return {
     status: 200,
-    body: { protocol: PROTOCOL_VERSION, screen: id, islands, ...(meta && { meta }) },
+    body: {
+      protocol: PROTOCOL_VERSION,
+      screen: id,
+      islands,
+      ...(meta && { meta }),
+    },
+  };
+}
+
+/** 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 +352,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 +373,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). */