@jigs.design/client 0.3.0 → 0.3.1

package/dist/client.d.ts

@@ -71,6 +71,13 @@ export interface PageResult {
 export interface JigsClient {
   /** URL of the sandbox frame document. */
   readonly frame: string;
+  /**
+   * Keeps the push channel from closing until the returned function is
+   * called; it does not open one. A view holds it from `start` to `stop`,
+   * so a program that reads no query for a while, as one still streaming
+   * may, does not close and reopen the stream.
+   */
+  hold: () => () => void;
   /** Refetches every query with this name, for every input. */
   invalidate: (name: string) => Promise<void>;
   /**

package/dist/client.js

@@ -6,9 +6,9 @@ const DEFAULT_STALE_TIME = 6e4;
 const RETRYABLE = /* @__PURE__ */ new Set(["NETWORK", "UNAVAILABLE"]);
 const MAX_RETRIES = 2;
 /**
-* How long the push channel stays open after the last query unsubscribes:
-* a program swap re-creates its observers after a round trip to the
-* sandbox, not within a tick.
+* How long the push channel stays open once nothing observes or holds it:
+* a view that remounts, or a block that becomes another, subscribes again
+* well within it.
 */
 const CHANNEL_LINGER_MS = 1e3;
 /** When a channel the server refused or ended is tried again, with queries still observed. */
@@ -16,13 +16,16 @@ const CHANNEL_REOPEN_MS = 3e5;
 /** The refetch after a gap in the channel waits up to this long, so tabs do not all hit the server at once. */
 const GAP_SPREAD_MS = 2e3;
 /**
-* The push channel: open while any query or page is observed, and its events
-* applied to the cache. It refetches everything on screen only after a gap
+* The push channel: opened by the first query or page observed, kept open
+* while any is observed or a view holds it, and its events applied to the
+* cache. It refetches everything on screen only after a gap
 * it cannot account for: a connection lost without a `close` event, to a
 * server that did not replay what it missed.
 */
 function createChannel(transport, handlers) {
 	let observers = 0;
+	/** Views mounted: they keep an open channel open, but do not open one. */
+	let holds = 0;
 	let running = null;
 	let linger;
 	let reopen;
@@ -53,16 +56,32 @@ function createChannel(transport, handlers) {
 		running = controller;
 		consume(transport.events({ signal: controller.signal }), controller.signal);
 	};
+	/** Closes the channel after the linger, once nothing observes or holds it. */
+	const closeWhenIdle = () => {
+		if (observers > 0 || holds > 0) return;
+		clearTimeout(linger);
+		linger = setTimeout(() => {
+			clearTimeout(reopen);
+			running?.abort();
+			running = null;
+		}, CHANNEL_LINGER_MS);
+	};
 	return {
+		hold: () => {
+			holds += 1;
+			clearTimeout(linger);
+			let held = true;
+			return () => {
+				if (held) {
+					held = false;
+					holds -= 1;
+					closeWhenIdle();
+				}
+			};
+		},
 		release: () => {
 			observers -= 1;
-			if (observers > 0) return;
-			clearTimeout(linger);
-			linger = setTimeout(() => {
-				clearTimeout(reopen);
-				running?.abort();
-				running = null;
-			}, CHANNEL_LINGER_MS);
+			closeWhenIdle();
 		},
 		retain: () => {
 			observers += 1;
@@ -169,6 +188,7 @@ function createJigsClient(options) {
 	});
 	return {
 		frame: transport.frame,
+		hold: channel.hold,
 		invalidate: (name) => queries.invalidateQueries({ queryKey: [name] }),
 		invalidatePage,
 		mutate: async (name, input, procedure) => {

package/dist/view/controller.d.ts

@@ -1,5 +1,5 @@
 import { ConfirmFunction, JigsClient } from "../client.js";
-import { Program, PropSchema, RuntimeError, WireArg } from "@jigs.design/protocol";
+import { JsonValue, Program, PropSchema, RuntimeError, WireArg } from "@jigs.design/protocol";
 import { TreeNode, TreeStore } from "@jigs.design/runtime";
 //#region src/view/controller.d.ts
 /** What the view shows beside the tree: a snapshot, replaced on each change. */
@@ -91,6 +91,12 @@ export interface ViewController {
    * `signal` aborted.
    */
   setConfirmHandler: (handler: ConfirmFunction | undefined) => void;
+  /**
+   * Replaces the provided data, by slot name. Every read of a slot whose
+   * value changed, compared as JSON, gets the new value, as a refetched
+   * query's does; a slot left out reads as `UNAVAILABLE`.
+   */
+  setData: (values: Readonly<Record<string, JsonValue>> | undefined) => void;
   /** Replaces what each new issue is given to; `undefined` stops reporting. */
   setIssueHandler: (handler: ((issue: ViewIssue) => void) | undefined) => void;
   /**

package/dist/view/controller.js

@@ -35,6 +35,15 @@ const NO_ACTIONS = {
 	},
 	status: "error"
 };
+/** What a read of slot `name` gets when the page provides no value for it. */
+const notProvided = (name) => ({
+	data: null,
+	error: {
+		code: "UNAVAILABLE",
+		message: `The page provided no "${name}"`
+	},
+	status: "error"
+});
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** The runtime errors of a result, as text React can draw. The frame is not trusted. */
 function parseErrors(list) {
@@ -73,6 +82,10 @@ function createViewController(client) {
 	const store = createTreeStore();
 	const listeners = /* @__PURE__ */ new Set();
 	const observers = /* @__PURE__ */ new Map();
+	/** Reads of provided slots, answered here, never fetched: key to slot name. */
+	const slotReads = /* @__PURE__ */ new Map();
+	/** The page's provided data, each value with its JSON to compare by. */
+	let provided = /* @__PURE__ */ new Map();
 	const sent = /* @__PURE__ */ new Map();
 	let iframe = null;
 	let ready = false;
@@ -107,6 +120,8 @@ function createViewController(client) {
 	* still showing cannot run a mutation for a program that is gone.
 	*/
 	let confirmationScope = new AbortController();
+	/** Lets the push channel close; set while the view is started. */
+	let unhold = null;
 	const withdrawConfirmations = () => {
 		confirmationScope.abort();
 		confirmationScope = new AbortController();
@@ -241,8 +256,18 @@ function createViewController(client) {
 	const dropObservers = () => {
 		for (const unsubscribe of observers.values()) unsubscribe();
 		observers.clear();
+		slotReads.clear();
 		sent.clear();
 	};
+	/** What a read of slot `name` gets now. */
+	const slotResult = (name) => {
+		const entry = provided.get(name);
+		return entry === void 0 ? notProvided(name) : {
+			data: entry.value,
+			error: null,
+			status: "success"
+		};
+	};
 	/** The running program's entry for `name`, if it is one of `kinds`. */
 	const procedure = (name, kinds) => {
 		if (running === null || !Object.hasOwn(running.procedures, name)) return;
@@ -253,7 +278,7 @@ function createViewController(client) {
 	const checkedReads = (reads) => {
 		const wanted = /* @__PURE__ */ new Map();
 		for (const read of reads) {
-			if (!isRecord(read) || typeof read.key !== "string" || typeof read.name !== "string" || procedure(read.name, ["query"]) === void 0) {
+			if (!isRecord(read) || typeof read.key !== "string" || typeof read.name !== "string" || procedure(read.name, ["data", "query"]) === void 0) {
 				drop("The sandbox read a query this program does not declare");
 				continue;
 			}
@@ -275,9 +300,20 @@ function createViewController(client) {
 			observers.delete(key);
 			sent.delete(key);
 		}
-		for (const [key, read] of wanted) if (!observers.has(key)) observers.set(key, client.observe(read.name, read.input, (result) => {
-			sendQuery(key, result);
-		}));
+		for (const key of slotReads.keys()) if (!wanted.has(key)) {
+			slotReads.delete(key);
+			sent.delete(key);
+		}
+		for (const [key, read] of wanted) {
+			if (procedure(read.name, ["data"]) !== void 0) {
+				slotReads.set(key, read.name);
+				sendQuery(key, slotResult(read.name));
+				continue;
+			}
+			if (!observers.has(key)) observers.set(key, client.observe(read.name, read.input, (result) => {
+				sendQuery(key, result);
+			}));
+		}
 	};
 	/** Marks the call `answered` done; returns whether it was a handler call. */
 	const answer = (answered) => {
@@ -478,6 +514,19 @@ function createViewController(client) {
 		setConfirmHandler: (handler) => {
 			confirmHandler = handler;
 		},
+		setData: (values) => {
+			const next = /* @__PURE__ */ new Map();
+			for (const [name, value] of Object.entries(values ?? {})) {
+				const text = JSON.stringify(value);
+				const before = provided.get(name);
+				next.set(name, before?.text === text ? before : {
+					text,
+					value
+				});
+			}
+			provided = next;
+			for (const [key, name] of slotReads) sendQuery(key, slotResult(name));
+		},
 		setIssueHandler: (handler) => {
 			issueHandler = handler;
 		},
@@ -497,6 +546,7 @@ function createViewController(client) {
 				if (iframe === frame && !ready && startup === null) startup = setTimeout(diagnoseFrame, STARTUP_MS);
 			});
 			iframe = frame;
+			unhold = client.hold();
 			window.addEventListener("message", onMessage);
 			document.body.append(frame);
 		},
@@ -520,8 +570,11 @@ function createViewController(client) {
 			latestDocument = void 0;
 			actionHandler = void 0;
 			confirmHandler = void 0;
+			provided = /* @__PURE__ */ new Map();
 			withdrawConfirmations();
 			dropObservers();
+			unhold?.();
+			unhold = null;
 			store.reset();
 			status = idle;
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/client",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "createJigsClient: the browser's transport and query cache. No React.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@tanstack/query-core": "5.104.4",
-    "@jigs.design/protocol": "0.3.0",
-    "@jigs.design/runtime": "0.3.0"
+    "@jigs.design/runtime": "0.3.1",
+    "@jigs.design/protocol": "0.3.1"
   }
 }