@tokamakdev/plugin 0.1.0-beta.81 → 0.1.0-beta.83

package/README.md

@@ -0,0 +1,67 @@
+# @tokamakdev/plugin
+
+The shared base of tokamak plugins: the page's native transport, Worker events,
+and test fakes.
+
+| Entry | Contents |
+| --- | --- |
+| `@tokamakdev/plugin` | `FrontendPlugin`, the base class of a plugin's page API |
+| `@tokamakdev/plugin/events` | `defineEvent`, which defines a plugin's Worker events |
+| `@tokamakdev/plugin/testing` | A fake native transport, and `dispatch`, which runs event listeners as the runtime does |
+
+A plugin lists `@tokamakdev/plugin` as a peer dependency, so an app has one
+copy of it, shared with `@tokamakdev/tok`, which depends on it.
+
+## Worker events
+
+A plugin's native code delivers events to the app's Worker, whose listeners
+register in `src/tokamak.ts` and run even when no page is loaded, such as when
+the system starts the app in the background.
+
+The plugin defines each event in its own `/events` entry, which apps import:
+
+```ts
+// events/index.ts, exported as "./events" in package.json
+import { defineEvent } from "@tokamakdev/plugin/events";
+
+/** Receives each alarm as it rings. A returned number snoozes it for that many minutes. */
+export const onRing = defineEvent<{ id: string }, number>("alarms.ring");
+```
+
+`defineEvent<T, Reply>(name)` returns the function that registers listeners,
+typed with the event's data `T` and the `Reply` its listeners may return. The
+name is the plugin's ID, a `.`, and the event's name. The event's reply is the
+first value, in registration order, that a listener returns other than
+`undefined`.
+
+The native side emits the event through the host the plugin is created with,
+which prefixes the plugin's ID, so listeners of `alarms.ring` receive
+`host.emit("ring", …)`. Events are JSON:
+
+```swift
+host.emit("ring", event: ["id": alarm.id], timeout: 10) { result in
+  // `result` is the reply, parsed from JSON, or nil when no listener replies.
+}
+```
+
+```kotlin
+// Blocks, so call it off the main thread.
+val reply = host.emit("ring", JSONObject().put("id", alarm.id).toString(), 10_000)
+// `reply` is the reply's JSON, "null" when no listener replies.
+```
+
+`timeout` includes starting the runtime when the app is not running. `emit`
+fails when the Worker cannot run, or when a listener has not returned by the
+timeout; it is not retried. The runtime starts no Worker for an event without
+listeners, so emit each event the plugin defines whether or not the app
+listens. Plugin IDs contain no `.`.
+
+Test listeners with `dispatch` from `@tokamakdev/plugin/testing`, which runs
+them as the runtime does and returns what they threw:
+
+```ts
+import { dispatch } from "@tokamakdev/plugin/testing";
+
+onRing(() => 5);
+const { reply, reported } = await dispatch("alarms.ring", { id: "a1" }, env);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin",
-  "version": "0.1.0-beta.81",
+  "version": "0.1.0-beta.83",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -9,7 +9,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./worker": "./src/worker.ts",
+    "./events": "./src/events.ts",
     "./testing": "./src/testing.ts"
   },
   "files": [

package/src/entrypoint.js

@@ -0,0 +1,12 @@
+// The tokamak Vite plugin exports this class from the entry Worker in tokamak builds and
+// development, where the runtime and `tok dev` call `dispatch` to deliver events.
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+import { dispatch } from "./registry.ts";
+
+export class TokamakEvents extends WorkerEntrypoint {
+  /** Runs the listeners of the event `name` and returns `{ reply, listened }`. */
+  dispatch(name, event) {
+    return dispatch(name, event, this.env, this.ctx);
+  }
+}

package/src/events.ts

@@ -0,0 +1,35 @@
+import { register, type RegisteredListener } from "./registry.js";
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- `wrangler types` declares the Worker's bindings here.
+  namespace Cloudflare {
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the app's `wrangler types` declares the members.
+    interface Env {}
+  }
+}
+
+/** The invocation a listener runs in. */
+export interface EventContext {
+  /** Keeps the event running until `promise` settles or the event's deadline passes. */
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/** Receives an event of type `T` with the Worker's `env`, and may return a `Reply`. */
+export type Listener<T, Reply = void> = (
+  event: T,
+  env: Cloudflare.Env,
+  ctx: EventContext,
+) => Reply | undefined | Promise<Reply | undefined>;
+
+/**
+ * Defines the event `name` and returns the function that registers its listeners. The event's
+ * reply is the first value, in registration order, that a listener returns other than
+ * `undefined`.
+ */
+export function defineEvent<T, Reply = void>(
+  name: string,
+): (listener: Listener<T, Reply>) => void {
+  return (listener) => {
+    register(name, listener as RegisteredListener);
+  };
+}

package/src/registry.ts

@@ -0,0 +1,40 @@
+/** A registered listener. */
+export type RegisteredListener = (event: unknown, env: unknown, ctx: unknown) => unknown;
+
+/** What a dispatch returns. */
+export interface Dispatched {
+  /** The first value, in registration order, that a listener returned other than `undefined`. */
+  reply: unknown;
+  /** The names of the events that have listeners. */
+  listened: string[];
+}
+
+/** Every listener, by event name, in registration order. */
+const listeners = new Map<string, RegisteredListener[]>();
+
+export function register(name: string, listener: RegisteredListener): void {
+  const registered = listeners.get(name);
+  if (registered) registered.push(listener);
+  else listeners.set(name, [listener]);
+}
+
+/**
+ * Runs the listeners of the event `name` and waits for them to settle. A listener that throws is
+ * reported with `reportError`, and the others still run.
+ */
+export async function dispatch(
+  name: string,
+  event: unknown,
+  env: unknown,
+  ctx: unknown,
+): Promise<Dispatched> {
+  const results = await Promise.allSettled(
+    (listeners.get(name) ?? []).map(async (listener) => await listener(event, env, ctx)),
+  );
+  let reply: unknown;
+  for (const result of results) {
+    if (result.status === "rejected") reportError(result.reason);
+    else if (reply === undefined) reply = result.value;
+  }
+  return { reply, listened: [...listeners.keys()] };
+}

package/src/testing.ts

@@ -1,3 +1,5 @@
+import { dispatch as dispatchEvent, type Dispatched } from "./registry.js";
+
 /** A native transport that records the page's messages and replies as the native bridges do. */
 export class FakeNativeTransport {
   /** Every message the page posted, parsed. */
@@ -37,3 +39,23 @@ export function connectNative(): FakeNativeTransport {
 export function disconnectNative(): void {
   Reflect.deleteProperty(globalThis, "__tokamakNative");
 }
+
+/**
+ * Runs the listeners of the event `name` as the runtime does, returning the reply, the events
+ * that have listeners, and what listeners threw, which the runtime reports with `reportError`.
+ */
+export async function dispatch(
+  name: string,
+  event: unknown,
+  env: unknown = {},
+  ctx: unknown = { waitUntil: () => undefined },
+): Promise<Dispatched & { reported: unknown[] }> {
+  const reported: unknown[] = [];
+  const previous = Reflect.get(globalThis, "reportError") as unknown;
+  globalThis.reportError = (error: unknown) => reported.push(error);
+  try {
+    return { ...(await dispatchEvent(name, event, env, ctx)), reported };
+  } finally {
+    Reflect.set(globalThis, "reportError", previous);
+  }
+}

package/src/worker.ts

@@ -1,17 +0,0 @@
-declare const process:
-  | { readonly env: { readonly NODE_ENV?: string; readonly TOKAMAK_RUNTIME?: string } }
-  | undefined;
-
-/**
- * Whether the Worker serves the tokamak runtime's calls to endpoints under `/tokamak/`: in a
- * tokamak app, where the runtime sets `TOKAMAK_RUNTIME`, and in development. Those endpoints
- * refuse requests otherwise.
- */
-export function acceptsRuntimeCalls(): boolean {
-  // One expression: Rollup 4.63.0 drops callers' checks when this is an early return followed
-  // by a return of `typeof process !== "undefined" && false`.
-  return (
-    typeof process !== "undefined" &&
-    (process.env.NODE_ENV === "development" || process.env.TOKAMAK_RUNTIME === "true")
-  );
-}