@tokamakdev/plugin 0.1.0-beta.107 → 0.1.0-beta.114

package/src/testing.ts

@@ -1,43 +1,130 @@
 import { dispatch as dispatchEvent, type Dispatched } from "./registry.js";
+import { createNativeContext, type Availability, type NativeConnection, type NativePlatform, type Overflow, type TokamakContext } from "./context.js";
+import { encodeJson, decodeJson } from "./codec.js";
+import { nativeError, type NativeFailure } from "./native-protocol.mjs";
 
-/** A native transport that records the page's messages and replies as the native bridges do. */
+type Reply = (payload: Uint8Array, error: DOMException | undefined, done: boolean) => void;
+
+/** A request the native endpoint received. */
+export interface SentRequest {
+  type: string;
+  id: number;
+  plugin?: string;
+  method?: string;
+  payload?: Uint8Array;
+  /** A call's body. */
+  body?: ReadableStream<Uint8Array>;
+  /** A subscription's overflow policy. */
+  overflow?: Overflow;
+}
+
+/** A reply to a request: its value or failure, and whether it is the last. */
+export interface Answer {
+  value?: unknown;
+  error?: NativeFailure;
+  done?: boolean;
+}
+
+/** A request as `answer` sees it, with its decoded payload. */
+export interface Received {
+  id: number;
+  type: string;
+  plugin?: string;
+  method?: string;
+  arguments: unknown;
+}
+
+/** An invocation with an inspectable native endpoint. */
 export class FakeNativeTransport {
-  /** Every message the page posted, parsed. */
-  readonly sent: Record<string, unknown>[] = [];
-  onmessage: ((event: { data: string }) => void) | null = null;
+  readonly sent: SentRequest[] = [];
+  private nextId = 1;
+  private readonly pending = new Map<number, Reply>();
+  private answering: ((request: Received) => Answer | undefined) | undefined;
+  readonly ctx: TokamakContext;
 
-  postMessage(message: string): void {
-    this.sent.push(JSON.parse(message) as Record<string, unknown>);
+  /** An invocation on `platform`, whose plugins' operations have `availability`. */
+  constructor(platform: NativePlatform = "ios", availability: Availability = {}) {
+    this.ctx = createNativeContext({ waitUntil: () => undefined }, this.connection(platform), availability);
   }
 
-  /** The last message's type, plugin, method and arguments. */
-  lastRequest(): Record<string, unknown> {
-    const { type, plugin, method, arguments: arguments_ } = this.sent.at(-1) ?? {};
-    return { type, plugin, method, arguments: arguments_ };
+  private connection(platform: NativePlatform): NativeConnection {
+    return {
+      platform,
+      call: (plugin, method, payload, { body, signal } = {}) => new Promise((resolve, reject) => {
+        signal?.throwIfAborted();
+        const id = this.request({ type: "call", plugin, method, payload, body }, (value, error) => {
+          if (error) reject(error);
+          else resolve(value);
+        });
+        signal?.addEventListener("abort", () => {
+          this.cancel(id);
+          reject(signal.reason as Error);
+        }, { once: true });
+      }),
+      listen: (plugin, method, payload, { next, error, overflow = "error" }) => {
+        const id = this.request({ type: "subscribe", plugin, method, payload, overflow }, (value, failure, done) => {
+          if (failure) error(failure, done);
+          else next(value, done);
+        });
+        return () => { this.cancel(id); };
+      },
+    };
   }
 
-  /** Replies to the last message. */
-  respond(reply: { value?: unknown; error?: { name: string; message: string } }, done = true): void {
-    const { session, id } = this.sent.at(-1) ?? {};
-    this.deliver({ session, id, done, ...reply });
+  private request(request: Omit<SentRequest, "id">, reply: Reply): number {
+    const id = this.nextId++;
+    this.sent.push({ ...request, id, payload: request.payload?.slice() });
+    this.pending.set(id, reply);
+    const { answering } = this;
+    if (answering) {
+      queueMicrotask(() => {
+        const { type, plugin, method, payload } = request;
+        const answer = answering({ id, type, plugin, method, arguments: payload?.byteLength ? decodeJson(payload) : undefined });
+        if (answer) this.deliver(id, answer);
+      });
+    }
+    return id;
   }
 
-  /** Delivers `response` to the page. */
-  deliver(response: Record<string, unknown>): void {
-    this.onmessage?.({ data: JSON.stringify(response) });
+  /**
+   * Answers each later request, as it arrives, with what `answer` returns for it. Undefined leaves
+   * the request pending, for `respond` or `deliver`.
+   */
+  answer(answer: (request: Received) => Answer | undefined): void {
+    this.answering = answer;
   }
-}
 
-/** Installs a new fake as the page's native transport. */
-export function connectNative(): FakeNativeTransport {
-  const transport = new FakeNativeTransport();
-  globalThis.__tokamakNative = transport;
-  return transport;
+  /** Replies to the pending request `id`. A reply is the last unless `done` is false. */
+  deliver(id: number, { value, error, done = true }: Answer): void {
+    const reply = this.pending.get(id);
+    if (done) this.pending.delete(id);
+    reply?.(encodeJson(value), error && nativeError(error), done);
+  }
+
+  private cancel(id: number): void {
+    if (this.pending.delete(id)) this.sent.push({ type: "cancel", id });
+  }
+
+  lastRequest(): Record<string, unknown> {
+    const { type, plugin, method, payload } = this.sent.at(-1) ?? {};
+    return { type, plugin, method, arguments: payload ? decodeJson(payload) : undefined };
+  }
+
+  respond(reply: { value?: unknown; error?: NativeFailure }, done = true): void {
+    this.respondBytes(encodeJson(reply.value), done, reply.error && nativeError(reply.error));
+  }
+
+  respondBytes(payload: Uint8Array, done = true, error?: DOMException): void {
+    const id = this.sent.at(-1)?.id;
+    if (id === undefined) throw new Error("No native request is pending");
+    const reply = this.pending.get(id);
+    if (done) this.pending.delete(id);
+    reply?.(payload.slice(), error, done);
+  }
 }
 
-/** Removes the page's native transport. */
-export function disconnectNative(): void {
-  Reflect.deleteProperty(globalThis, "__tokamakNative");
+export function connectNative(platform?: NativePlatform, availability?: Availability): FakeNativeTransport {
+  return new FakeNativeTransport(platform, availability);
 }
 
 /**
@@ -48,7 +135,7 @@ export async function dispatch(
   name: string,
   event: unknown,
   env: unknown = {},
-  ctx: unknown = { waitUntil: () => undefined },
+  ctx: unknown = createNativeContext({ waitUntil: () => undefined }),
 ): Promise<Dispatched & { reported: unknown[] }> {
   const reported: unknown[] = [];
   const previous = Reflect.get(globalThis, "reportError") as unknown;

package/src/webview.ts

@@ -0,0 +1,25 @@
+import { decodeJson, encodeJson, type JsonValue } from "./codec.js";
+import type { NativeConnection } from "./context.js";
+
+/** Controls the app's WebView. Operations reject with `InvalidStateError` when what they need is unavailable. */
+export interface WebView {
+  /**
+   * Starts navigation to an app URL, or a path relative to the current page or the app origin.
+   * Resolves when navigation is accepted. Needs the WebView, not a loaded page.
+   */
+  navigate(url: string): Promise<void>;
+  /** The committed page's absolute URL, or null when no page is loaded. */
+  getCurrentPage(): Promise<string | null>;
+  /** Dispatches a window `message` event in the current page. Messages are not queued. */
+  postMessage(data: JsonValue): Promise<void>;
+}
+
+export function webview(connection: NativeConnection): WebView {
+  const call = async <T>(method: string, value: unknown = null): Promise<T> =>
+    decodeJson<T>(await connection.call("tokamak", `webview.${method}`, encodeJson(value)));
+  return Object.freeze({
+    navigate: async (url: string) => { await call<null>("navigate", url); },
+    getCurrentPage: () => call<string | null>("getCurrentPage"),
+    postMessage: async (data: JsonValue) => { await call<null>("postMessage", data); },
+  });
+}

package/src/worker.ts

@@ -0,0 +1,32 @@
+import { capabilitiesFor } from "./capabilities.mjs";
+import { nativeAvailability, type TokamakContext } from "./context.js";
+import type { TokamakEvent } from "./events.js";
+import { dispatch } from "./registry.js";
+
+export { capabilitiesFor } from "./capabilities.mjs";
+export { createNativeContext, nativeAvailability, nativeConnection } from "./context.js";
+export type { Availability, NativePlatform } from "./capabilities.mjs";
+export type { TokamakContext } from "./context.js";
+export type { WebView } from "./webview.js";
+export type { EventReply, EventType, TokamakEvent } from "./events.js";
+
+/** The application's native worker entrypoint. */
+export class TokamakEntrypoint<Env = Tokamak.Env> {
+  constructor(
+    protected readonly ctx: TokamakContext,
+    protected readonly env: Env,
+  ) {}
+
+  /** Runs the listeners registered for this event and resolves to their reply. */
+  event(event: TokamakEvent): unknown {
+    return dispatch(event.type, event.data, this.env, this.ctx).then(({ reply }) => reply);
+  }
+}
+
+/** The page module that tells generated clients which plugin operations the app's platform implements. */
+export function capabilitiesModule(ctx: TokamakContext): Response {
+  const capabilities = capabilitiesFor(ctx[nativeAvailability], ctx.platform);
+  return new Response(`export default ${JSON.stringify(capabilities)};\n`, {
+    headers: { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" },
+  });
+}