@panyam/tsappkit 0.2.0 → 0.6.0

package/src/page/mount.ts

@@ -1,3 +1,4 @@
+import { parseLoad } from "./load";
 import type { IslandSpec, PageSpec } from "./spec";
 
 /**
@@ -6,18 +7,65 @@ import type { IslandSpec, PageSpec } from "./spec";
  */
 export type IslandFactory<Ctx, El, C, B> = (el: El, island: IslandSpec, ctx: Ctx, bus: B) => C;
 
-/** The islands an entry can mount, by name. An entry bundles only what its registry names. */
-export type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B>>;
+const LAZY: unique symbol = Symbol("lazy island");
+
+/** A registry entry whose factory is loaded when the island mounts. Made by lazy. */
+export interface LazyIsland<Ctx, El, C, B> {
+  readonly [LAZY]: () => Promise<IslandFactory<Ctx, El, C, B> | { default: IslandFactory<Ctx, El, C, B> }>;
+}
+
+/**
+ * A registry entry that loads its island's module only when the island
+ * mounts: `hero: lazy(() => import("./islands/hero"))`. With esbuild's
+ * --splitting each such module is its own chunk, so a page downloads only the
+ * islands its spec names, each when its `load` says. `load` resolves to the
+ * factory or to a module whose default export is the factory.
+ *
+ * A lazy island always mounts late, even an eager one, since its chunk
+ * arrives after the page has started; goapplib's page.Assets writes
+ * modulepreload links for the eager ones so that wait is short.
+ */
+export function lazy<Ctx, El, C, B>(
+  load: () => Promise<IslandFactory<Ctx, El, C, B> | { default: IslandFactory<Ctx, El, C, B> }>,
+): LazyIsland<Ctx, El, C, B> {
+  return { [LAZY]: load };
+}
+
+/**
+ * The islands an entry can mount, by name: a factory, bundled with the entry,
+ * or a lazy entry, loaded as its own chunk when the island mounts.
+ */
+export type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B> | LazyIsland<Ctx, El, C, B>>;
+
+/** How mountIslands handles islands that shouldn't mount at once. */
+export interface MountOptions<El, C> {
+  /**
+   * Gets each island whose `load` isn't eager, with the slot it will mount
+   * in; call `mount` when it's time (IslandPage passes scheduleMount). An
+   * island with a `load` parseLoad doesn't know is logged and mounted at once
+   * instead, so it still shows up.
+   */
+  defer?: (island: IslandSpec, el: El, mount: () => void) => void;
+  /** Gets what the factory built for each island mounted later: through `defer`, or from a lazy entry. */
+  onLateMount?: (component: C, island: IslandSpec) => void;
+}
 
 /**
  * Mounts every island in `spec` into the element `findSlot` gives for its
- * slot, and returns what the factories built, in spec order. `context` builds
- * the page's shared services; it's called once, before the first island
- * mounts, and not at all on a page with nothing to mount, so a page without
- * islands doesn't start what they'd share. An island the registry doesn't
- * know, a slot that isn't on the page, or a factory that throws is reported
- * through `log` and skipped, so one bad entry doesn't take the rest of the
- * page down with it.
+ * slot, and returns what the factories built at once, in spec order. With
+ * `options.defer`, an island whose `load` isn't eager is handed to it instead
+ * and reported through `options.onLateMount` when it mounts; without it,
+ * every island mounts now whatever its `load` says. A lazy entry is loaded
+ * when its island would mount and is reported through `onLateMount` too, so
+ * it's never in the returned list.
+ *
+ * `context` builds the page's shared services; it's called once, before the
+ * first island mounts (eager or late), and not at all on a page with nothing
+ * to mount, so a page without islands doesn't start what they'd share. An
+ * island the registry doesn't know, a slot that isn't on the page, or a
+ * factory that throws (now or later), or a lazy entry that fails to load, is
+ * reported through `log` and skipped,
+ * so one bad entry doesn't take the rest of the page down with it.
  *
  * Plain types throughout (no DOM), so it runs under node in tests and on a
  * bare page without BasePage.
@@ -29,12 +77,13 @@ export function mountIslands<Ctx, El, C, B>(
   context: () => Ctx,
   bus: B,
   log: (message: string) => void,
+  options: MountOptions<El, C> = {},
 ): C[] {
   const out: C[] = [];
   let ctx: Ctx | undefined;
   for (const island of spec.islands) {
-    const factory = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : undefined;
-    if (!factory) {
+    const entry = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : undefined;
+    if (!entry) {
       log(`page spec: no island called "${island.name}" in this page's registry`);
       continue;
     }
@@ -43,12 +92,52 @@ export function mountIslands<Ctx, El, C, B>(
       log(`page spec: island "${island.name}" wants slot "${island.slot}", which isn't on the page`);
       continue;
     }
-    try {
-      ctx ??= context();
-      out.push(factory(el, island, ctx, bus));
-    } catch (err) {
-      log(`page spec: island "${island.name}" failed to mount: ${err instanceof Error ? err.message : String(err)}`);
+    const build = (factory: IslandFactory<Ctx, El, C, B>): C | undefined => {
+      try {
+        ctx ??= context();
+        return factory(el, island, ctx, bus);
+      } catch (err) {
+        log(`page spec: island "${island.name}" failed to mount: ${message(err)}`);
+        return undefined;
+      }
+    };
+    const mountLate = () => {
+      const late = (factory: IslandFactory<Ctx, El, C, B>) => {
+        const c = build(factory);
+        if (c !== undefined) options.onLateMount?.(c, island);
+      };
+      if (typeof entry === "function") {
+        late(entry);
+        return;
+      }
+      // The executor turns a loader that throws into a rejection, logged like any other.
+      new Promise<Awaited<ReturnType<(typeof entry)[typeof LAZY]>>>((resolve) => resolve(entry[LAZY]())).then(
+        (m) => {
+          const factory = typeof m === "function" ? m : m?.default;
+          if (typeof factory === "function") late(factory);
+          else log(`page spec: island "${island.name}" loaded, but its module has no factory (a default export or the function itself)`);
+        },
+        (err) => log(`page spec: island "${island.name}" failed to load: ${message(err)}`),
+      );
+    };
+    const strategy = parseLoad(island.load);
+    if (strategy === null) {
+      log(`page spec: island "${island.name}" has load "${island.load}", which isn't eager, idle, visible or media:<query>; mounting it now`);
+    }
+    if (options.defer && strategy !== null && strategy.kind !== "eager") {
+      options.defer(island, el, mountLate);
+      continue;
     }
+    if (typeof entry !== "function") {
+      mountLate();
+      continue;
+    }
+    const c = build(entry);
+    if (c !== undefined) out.push(c);
   }
   return out;
 }
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/page/spec.ts

@@ -15,6 +15,12 @@ export interface IslandSpec {
   presentation?: string;
   /** Handed to the factory as is. Always an object. */
   config: Record<string, unknown>;
+  /**
+   * When it mounts: `eager` (also when absent), `idle`, `visible` or
+   * `media:<query>` (see parseLoad). IslandPage waits for it; mountIslands
+   * does when given a `defer`.
+   */
+  load?: string;
 }
 
 export interface PageSpec {
@@ -61,6 +67,7 @@ export function readSpec<Ext extends object>(text: string | null | undefined, ex
       slot: is.slot,
       ...(typeof is.presentation === "string" && { presentation: is.presentation }),
       config: isObject(is.config) ? is.config : {},
+      ...(typeof is.load === "string" && { load: is.load }),
     });
   }
   const spec: PageSpec = { layout: raw.layout, islands };

package/src/wasmhost/client.ts

@@ -126,15 +126,41 @@ export function workerFetch(worker: Worker): (input: RequestInfo | URL, init?: R
  * each Uint8Array is empty here afterwards; copy first anything the page still needs. Resolves once
  * the worker has mounted them (and, for a rebuild-mode host, rebuilt its handler).
  */
-export async function mountFiles(worker: Worker, name: string, files: Files): Promise<void> {
+export function mountFiles(worker: Worker, name: string, files: Files): Promise<void> {
+  return sendFiles(worker, "mount", name, files);
+}
+
+/**
+ * Adds `files` to the mount `name`, keeping the files it already holds; a file at a path the mount
+ * already has is replaced, and a missing mount is created. This suits a page that brings files in a
+ * piece at a time, since it only sends what's new. The worker checks the whole batch first, so a
+ * rejection (a path that is already a directory, say) leaves the mount as it was. Buffers are
+ * transferred as with mountFiles.
+ */
+export function addFiles(worker: Worker, name: string, files: Files): Promise<void> {
+  return sendFiles(worker, "add", name, files);
+}
+
+async function sendFiles(worker: Worker, kind: "mount" | "add", name: string, files: Files): Promise<void> {
   const transfer = new Set<ArrayBuffer>();
   for (const b of Object.values(files)) {
     // A tag check rather than instanceof, which fails for a buffer from another realm (an iframe),
     // and a SharedArrayBuffer can't be transferred.
     if (Object.prototype.toString.call(b.buffer) === "[object ArrayBuffer]") transfer.add(b.buffer as ArrayBuffer);
   }
-  const reply = await channel(worker).call({ kind: "mount", name, files }, [...transfer]);
+  const reply = await channel(worker).call({ kind, name, files }, [...transfer]);
+  if (!reply.ok) throw new Error(reply.error);
+}
+
+/**
+ * The bytes of linear memory the worker's wasm holds. Wasm memory grows and never shrinks, so this
+ * is the peak the engine has needed so far, which is what an app weighs before giving a browser a
+ * bigger job.
+ */
+export async function workerMemory(worker: Worker): Promise<number> {
+  const reply = await channel(worker).call({ kind: "stats" }, []);
   if (!reply.ok) throw new Error(reply.error);
+  return reply.memoryBytes ?? 0;
 }
 
 /** Removes the mount `name`. Removing a name that isn't mounted succeeds. */

package/src/wasmhost/index.ts

@@ -1,3 +1,3 @@
-export { startWorker, workerFetch, mountFiles, unmountFiles } from "./client";
+export { startWorker, workerFetch, mountFiles, addFiles, unmountFiles, workerMemory } from "./client";
 export type { StartWorkerOptions, Files } from "./client";
 export { filesFromDrop, filesFromFileList } from "./drop";

package/src/wasmhost/protocol.ts

@@ -14,10 +14,20 @@ export type HostRequest =
       body: Uint8Array | null;
     }
   | { id: number; kind: "mount"; name: string; files: Files }
+  | { id: number; kind: "add"; name: string; files: Files }
+  | { id: number; kind: "stats" }
   | { id: number; kind: "unmount"; name: string };
 
 export type HostReply =
-  | { id: number; ok: true; status?: number; headers?: Record<string, string>; body?: Uint8Array }
+  | {
+      id: number;
+      ok: true;
+      status?: number;
+      headers?: Record<string, string>;
+      body?: Uint8Array;
+      /** For stats: the wasm linear memory's size, which only grows. */
+      memoryBytes?: number;
+    }
   | { id: number; ok: false; error: string };
 
 /** Sent once when the wasm has loaded (or failed to), and again if the Go program exits. */

package/src/wasmhost/worker.ts

@@ -17,6 +17,7 @@ interface Exports {
     body: Uint8Array | null,
   ): Promise<{ status: number; headers: Record<string, string>; body: Uint8Array }>;
   mount(name: string, files: Files): Promise<void>;
+  add(name: string, files: Files): Promise<void>;
   unmount(name: string): Promise<void>;
 }
 
@@ -35,6 +36,9 @@ const wasmUrl = params.get("wasm") ?? "app.wasm";
 const execUrl = params.get("exec") ?? "wasm_exec.js";
 const ns = params.get("ns") ?? "wasmhost";
 
+// The wasm's linear memory, exported by Go as `mem`. It only grows, so its size is the peak so far.
+let memory: WebAssembly.Memory | undefined;
+
 const post = (m: HostStatus | HostReply, transfer: Transferable[] = []) => self.postMessage(m, transfer);
 
 async function boot(): Promise<Exports> {
@@ -50,6 +54,7 @@ async function boot(): Promise<Exports> {
   const { instance } = res.headers.get("content-type")?.startsWith("application/wasm")
     ? await WebAssembly.instantiateStreaming(res, go.importObject)
     : await WebAssembly.instantiate(await res.arrayBuffer(), go.importObject);
+  memory = instance.exports.mem as WebAssembly.Memory | undefined;
   void go.run(instance).then(() => post({ exited: "the Go program exited" }));
   await ready;
   return self[ns] as Exports;
@@ -71,9 +76,17 @@ self.onmessage = async (ev) => {
     } else if (req.kind === "mount") {
       await host.mount(req.name, req.files);
       post({ id: req.id, ok: true });
-    } else {
+    } else if (req.kind === "add") {
+      await host.add(req.name, req.files);
+      post({ id: req.id, ok: true });
+    } else if (req.kind === "stats") {
+      post({ id: req.id, ok: true, memoryBytes: memory?.buffer.byteLength ?? 0 });
+    } else if (req.kind === "unmount") {
       await host.unmount(req.name);
       post({ id: req.id, ok: true });
+    } else {
+      // A page newer than this worker can send a kind it doesn't know; say so rather than guess.
+      throw new Error(`unknown request kind ${JSON.stringify((req as { kind: unknown }).kind)}`);
     }
   } catch (err) {
     post({ id: req.id, ok: false, error: err instanceof Error ? err.message : String(err) });