@nkzw/fate-devtools 0.0.0-stage → 2.0.0

package/lib/src-CBLiWt9-.mjs

@@ -0,0 +1,556 @@
+// src/protocol.ts
+/**
+* Messages exchanged between an app running fate and the devtools panel.
+*
+* Both sides talk over a `BroadcastChannel`, so the panel works inside the
+* Vite DevTools dock (served from the dev server's origin) and as a standalone
+* tab on the same origin.
+*/
+const channelName = "fate-devtools";
+/** The app page exposes its page id here so an embedded panel can pick its own clients. */
+const pageIdGlobal = "__FATE_DEVTOOLS_PAGE_ID__";
+const isPanelMessage = (value) => typeof value === "object" && value !== null && value.source === "fate-devtools:panel";
+const listKeySeparator = " __fate__ ";
+const decodeListKeyPart = (part) => {
+	try {
+		return decodeURIComponent(part);
+	} catch {
+		return part;
+	}
+};
+/**
+* Splits a fate list key (`owner __fate__ field __fate__ hash`) into its parts.
+* Root lists are owned by `__root__`.
+*/
+const parseListKey = (key) => {
+	const parts = key.split(listKeySeparator);
+	return parts.length >= 3 ? {
+		field: decodeListKeyPart(parts[1]),
+		hash: decodeListKeyPart(parts[2]),
+		owner: decodeListKeyPart(parts[0])
+	} : {
+		field: key,
+		hash: "default",
+		owner: ""
+	};
+};
+// src/serialize.ts
+const maxDepth = 12;
+const maxArrayLength = 200;
+const maxStringLength = 2e3;
+/**
+* Converts arbitrary values into plain JSON that can cross a
+* `BroadcastChannel`. Cycles, functions, class instances, and very large
+* values are summarized instead of throwing.
+*/
+function toJSONValue(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+	switch (typeof value) {
+		case "string": return value.length > maxStringLength ? `${value.slice(0, maxStringLength)}… (${value.length} chars)` : value;
+		case "number": return Number.isFinite(value) ? value : String(value);
+		case "boolean": return value;
+		case "bigint": return `${value}n`;
+		case "undefined": return null;
+		case "symbol": return value.toString();
+		case "function": return `ƒ ${value.name || "anonymous"}()`;
+	}
+	if (value === null) return null;
+	const object = value;
+	const tag = Object.prototype.toString.call(object);
+	if (tag === "[object Date]") {
+		const date = object;
+		return Number.isNaN(date.getTime()) ? "Invalid Date" : date.toISOString();
+	}
+	if (tag === "[object Error]") {
+		const error = object;
+		return {
+			message: error.message,
+			name: error.name
+		};
+	}
+	if (seen.has(object)) return "[Circular]";
+	if (depth >= maxDepth) return Array.isArray(object) ? `[Array(${object.length})]` : "[Object]";
+	const ref = getNodeRef(object);
+	if (ref !== void 0) return { $ref: ref };
+	seen.add(object);
+	try {
+		if (tag === "[object Map]") return Object.fromEntries([...object].slice(0, maxArrayLength).map(([key, entry]) => [String(key), toJSONValue(entry, depth + 1, seen)]));
+		if (tag === "[object Set]" || Array.isArray(object)) {
+			const items = [...object];
+			const result = items.slice(0, maxArrayLength).map((entry) => toJSONValue(entry, depth + 1, seen));
+			return items.length > maxArrayLength ? [...result, `… ${items.length - maxArrayLength} more`] : result;
+		}
+		const result = {};
+		for (const key of Object.keys(object)) {
+			let entry;
+			try {
+				entry = object[key];
+			} catch (error) {
+				entry = error;
+			}
+			result[key] = toJSONValue(entry, depth + 1, seen);
+		}
+		return result;
+	} finally {
+		seen.delete(object);
+	}
+}
+/**
+* fate stores relations as frozen objects keyed by a private symbol. The
+* devtools turn them into `{ $ref: 'Type:id' }` so the panel can link to them.
+*/
+const getNodeRef = (object) => {
+	for (const symbol of Object.getOwnPropertySymbols(object)) if (symbol.description === "__fate__node-ref") {
+		const id = object[symbol];
+		return typeof id === "string" ? id : void 0;
+	}
+};
+const errorMessage = (error) => error instanceof Error ? error.message : typeof error === "string" ? error : JSON.stringify(toJSONValue(error));
+// src/index.ts
+const operationKinds = /* @__PURE__ */ new Set([
+	"fetchById",
+	"fetchList",
+	"fetchQuery",
+	"mutate",
+	"mutateDurably",
+	"subscribeById",
+	"subscribeConnection"
+]);
+const watcherTimeout = 5e3;
+const snapshotDelay = 120;
+const maxRecords = 5e3;
+const pageId = Math.random().toString(36).slice(2, 10);
+let nextClientId = 0;
+const parseEntityId = (id) => {
+	const index = id.indexOf(":");
+	return index < 0 ? {
+		rawId: id,
+		type: ""
+	} : {
+		rawId: id.slice(index + 1),
+		type: id.slice(0, index)
+	};
+};
+const nestedKeys = (value, prefix = "") => {
+	if (!value || typeof value !== "object") return [];
+	return Object.entries(value).flatMap(([key, entry]) => typeof entry === "function" ? [`${prefix}${key}`] : nestedKeys(entry, `${prefix}${key}.`));
+};
+const toPaths = (select) => {
+	if (!select || typeof select !== "object" || !(Symbol.iterator in select)) return [];
+	return [...select].map(String).sort();
+};
+/** Keeps a bounded log, dropping the oldest entries first. */
+var RingLog = class {
+	constructor(size) {
+		this.size = size;
+		this.entries = [];
+	}
+	push(entry) {
+		this.entries.push(entry);
+		if (this.entries.length > this.size) this.entries.splice(0, this.entries.length - this.size);
+	}
+	clear() {
+		this.entries = [];
+	}
+	values() {
+		return this.entries;
+	}
+};
+const connections = /* @__PURE__ */ new WeakMap();
+/**
+* Connects a fate client to the devtools panel. Returns a function that
+* disconnects it again and restores the client's original transport.
+*
+* Connecting the same client more than once is safe; the client stays
+* connected until every returned disposer has been called.
+*
+* The devtools are intended for development. Guard the call with
+* `import.meta.env.DEV` (or your bundler's equivalent) to keep them out of
+* production bundles.
+*/
+function connectFateDevtools(client, options = {}) {
+	if (typeof BroadcastChannel === "undefined") return () => {};
+	const existing = connections.get(client);
+	if (existing) {
+		existing.refCount++;
+		return once(() => release(client, existing));
+	}
+	const connection = {
+		dispose: attach(client, options),
+		refCount: 1
+	};
+	connections.set(client, connection);
+	return once(() => release(client, connection));
+}
+const once = (fn) => {
+	let called = false;
+	return () => {
+		if (!called) {
+			called = true;
+			fn();
+		}
+	};
+};
+const release = (client, connection) => {
+	connection.refCount--;
+	if (connection.refCount === 0) {
+		connections.delete(client);
+		connection.dispose();
+	}
+};
+function attach(client, options) {
+	const logSize = options.logSize ?? 300;
+	globalThis[pageIdGlobal] = pageId;
+	const summary = {
+		id: `${pageId}:${nextClientId++}`,
+		name: options.name ?? "fate",
+		pageId,
+		url: typeof location === "undefined" ? "" : location.href
+	};
+	const channel = new BroadcastChannel(channelName);
+	const operations = new RingLog(logSize);
+	const changes = new RingLog(logSize);
+	const watchers = /* @__PURE__ */ new Map();
+	let nextOperationId = 0;
+	let nextChangeId = 0;
+	let snapshotTimer;
+	let disposed = false;
+	const post = (message) => {
+		if (!disposed) channel.postMessage(message);
+	};
+	const isWatched = () => {
+		const now = Date.now();
+		for (const [watcher, lastSeen] of watchers) if (now - lastSeen > watcherTimeout) watchers.delete(watcher);
+		return watchers.size > 0;
+	};
+	const sendSnapshot = () => {
+		snapshotTimer = void 0;
+		if (!disposed && isWatched()) post({
+			snapshot: takeSnapshot(),
+			source: "fate-devtools:app",
+			type: "snapshot"
+		});
+	};
+	const scheduleSnapshot = () => {
+		if (snapshotTimer === void 0 && watchers.size > 0) snapshotTimer = setTimeout(sendSnapshot, snapshotDelay);
+	};
+	const originalTransport = client.transport;
+	if (originalTransport) {
+		const wrapped = /* @__PURE__ */ new Map();
+		client.transport = new Proxy(originalTransport, { get(target, property, receiver) {
+			const value = Reflect.get(target, property, receiver);
+			if (typeof value !== "function" || !operationKinds.has(property)) return value;
+			let fn = wrapped.get(property);
+			if (!fn) {
+				fn = instrument(property, value.bind(target));
+				wrapped.set(property, fn);
+			}
+			return fn;
+		} });
+	}
+	function instrument(kind, fn) {
+		return (...args) => {
+			const entry = startOperation(kind, args);
+			operations.push(entry);
+			scheduleSnapshot();
+			const settle = (status, value) => {
+				entry.endedAt = Date.now();
+				entry.status = status;
+				if (status === "error") entry.error = errorMessage(value);
+				else entry.result = toJSONValue(value);
+				scheduleSnapshot();
+			};
+			if (kind === "subscribeById" || kind === "subscribeConnection") {
+				const handlerIndex = kind === "subscribeById" ? 4 : 5;
+				const handlers = args[handlerIndex];
+				if (handlers) {
+					const event = (name) => (...eventArgs) => {
+						entry.events = (entry.events ?? 0) + 1;
+						entry.result = toJSONValue(eventArgs[0]);
+						scheduleSnapshot();
+						return handlers[name]?.(...eventArgs);
+					};
+					args[handlerIndex] = {
+						...handlers,
+						...handlers.onData && { onData: event("onData") },
+						...handlers.onDelete && { onDelete: event("onDelete") },
+						...handlers.onEvent && { onEvent: event("onEvent") },
+						onError: (error) => {
+							entry.error = errorMessage(error);
+							entry.status = "error";
+							scheduleSnapshot();
+							handlers.onError?.(error);
+						}
+					};
+				}
+				try {
+					const unsubscribe = fn(...args);
+					entry.status = "live";
+					return () => {
+						entry.endedAt = Date.now();
+						if (entry.status === "live") entry.status = "closed";
+						scheduleSnapshot();
+						return unsubscribe();
+					};
+				} catch (error) {
+					settle("error", error);
+					throw error;
+				}
+			}
+			try {
+				const result = fn(...args);
+				Promise.resolve(result).then((value) => settle("success", value), (error) => settle("error", error));
+				return result;
+			} catch (error) {
+				settle("error", error);
+				throw error;
+			}
+		};
+	}
+	function startOperation(kind, args) {
+		const base = {
+			id: nextOperationId++,
+			kind,
+			startedAt: Date.now(),
+			status: "pending"
+		};
+		switch (kind) {
+			case "fetchById": return {
+				...base,
+				args: toJSONValue(args[3]),
+				input: toJSONValue({ ids: args[1] }),
+				name: String(args[0]),
+				select: toPaths(args[2])
+			};
+			case "fetchList":
+			case "fetchQuery": return {
+				...base,
+				args: toJSONValue(args[2]),
+				name: String(args[0]),
+				select: toPaths(args[1])
+			};
+			case "mutate": return {
+				...base,
+				args: toJSONValue(args[3]),
+				input: toJSONValue(args[1]),
+				name: String(args[0]),
+				select: toPaths(args[2])
+			};
+			case "mutateDurably": return {
+				...base,
+				args: toJSONValue(args[4]),
+				input: toJSONValue({
+					identity: args[3],
+					input: args[1]
+				}),
+				name: String(args[0]),
+				select: toPaths(args[2])
+			};
+			case "subscribeById": return {
+				...base,
+				args: toJSONValue(args[3]),
+				input: toJSONValue({ id: args[1] }),
+				name: String(args[0]),
+				select: toPaths(args[2])
+			};
+			case "subscribeConnection": return {
+				...base,
+				args: toJSONValue({
+					args: args[2],
+					selectionArgs: args[4]
+				}),
+				input: toJSONValue({ type: args[1] }),
+				name: String(args[0]),
+				select: toPaths(args[3])
+			};
+		}
+	}
+	const store = client.store;
+	const hadOwnOnChange = !!store && Object.hasOwn(store, "onChange");
+	const originalOnChange = store?.onChange;
+	if (store) store.onChange = (change, owner) => {
+		try {
+			changes.push({
+				at: Date.now(),
+				id: nextChangeId++,
+				...change.invalidated && { invalidated: true },
+				key: String(change.key),
+				kind: change.kind,
+				optimistic: !!store.isRecordingOptimistic || !!store.hasOptimisticUpdates,
+				...change.paths && { paths: [...change.paths].map(String) }
+			});
+			scheduleSnapshot();
+		} catch {}
+		return originalOnChange?.call(store, change, owner);
+	};
+	const unsubscribePersistence = client.persistence?.subscribe?.(scheduleSnapshot);
+	function takeSnapshot() {
+		const state = store?.dehydrate?.() ?? {
+			coverage: [],
+			lists: [],
+			records: []
+		};
+		const confirmed = store?.hasOptimisticUpdates ? store.dehydrateConfirmed?.() : void 0;
+		const confirmedRecords = confirmed ? new Map(confirmed.records) : void 0;
+		const confirmedLists = confirmed ? new Map(confirmed.lists) : void 0;
+		const coverage = new Map(state.coverage);
+		const stale = new Map(state.stale ?? []);
+		const records = state.records.slice(0, maxRecords).map(([id, record]) => {
+			const { rawId, type } = parseEntityId(String(id));
+			return {
+				coverage: coverage.get(id) ?? [],
+				id,
+				lists: store?.getListKeysForEntity?.(id) ?? [],
+				optimistic: !!confirmedRecords && confirmedRecords.get(id) !== record,
+				rawId,
+				record: toJSONValue(record),
+				stale: stale.get(id) ?? [],
+				type
+			};
+		});
+		const lists = state.lists.map(([key, list]) => {
+			const { field, owner } = parseListKey(key);
+			return {
+				field,
+				ids: list.ids.map(String),
+				key,
+				optimistic: !!confirmedLists && confirmedLists.get(key) !== list,
+				owner,
+				...list.pagination !== void 0 && { pagination: toJSONValue(list.pagination) },
+				state: toJSONValue(list)
+			};
+		});
+		return {
+			changes: [...changes.values()],
+			...typeof client.hydrationScope === "string" && { hydrationScope: client.hydrationScope },
+			id: summary.id,
+			lists,
+			live: [...client.liveSubscriptions ?? []].map(([key, subscription]) => ({
+				key,
+				subscribers: subscription.count ?? 0
+			})),
+			mutations: nestedKeys(client.mutations).sort(),
+			name: summary.name,
+			operations: operations.values().map((entry) => ({ ...entry })),
+			optimisticUpdates: !!store?.hasOptimisticUpdates,
+			...client.persistence?.getSnapshot && { persistence: toJSONValue(client.persistence.getSnapshot()) },
+			records,
+			requests: getRequests(client),
+			roots: Object.keys(client.roots ?? {}).sort(),
+			takenAt: Date.now(),
+			types: [...client.types?.keys() ?? []].sort()
+		};
+	}
+	function runAction(action) {
+		switch (action.type) {
+			case "gc":
+				client.gc?.();
+				break;
+			case "clear-log":
+				operations.clear();
+				changes.clear();
+				break;
+			case "invalidate-record":
+				store?.invalidateRecord?.(action.id);
+				break;
+			case "invalidate-all":
+				for (const [id] of store?.dehydrate?.().records ?? []) store?.invalidateRecord?.(id);
+				break;
+			case "delete-record": {
+				const { rawId, type } = parseEntityId(action.id);
+				client.deleteRecord?.(type, rawId);
+				break;
+			}
+			case "log-record": {
+				const record = store?.dehydrate?.().records.find(([id]) => id === action.id)?.[1];
+				globalThis.$fate = record;
+				console.log(`fate-devtools: ${action.id} (available as $fate)`, record);
+				break;
+			}
+		}
+		scheduleSnapshot();
+	}
+	const onMessage = (event) => {
+		const message = event.data;
+		if (!isPanelMessage(message)) return;
+		if (message.type === "discover") {
+			post({
+				client: summary,
+				source: "fate-devtools:app",
+				type: "connected"
+			});
+			return;
+		}
+		if (message.clientId !== summary.id) return;
+		switch (message.type) {
+			case "watch":
+				watchers.set(message.panelId, Date.now());
+				scheduleSnapshot();
+				break;
+			case "unwatch":
+				watchers.delete(message.panelId);
+				break;
+			case "action": try {
+				runAction(message.action);
+			} catch (error) {
+				console.error("fate-devtools: Action failed.", error);
+			}
+		}
+	};
+	channel.addEventListener("message", onMessage);
+	post({
+		client: summary,
+		source: "fate-devtools:app",
+		type: "connected"
+	});
+	const onPageHide = () => post({
+		clientId: summary.id,
+		source: "fate-devtools:app",
+		type: "disconnected"
+	});
+	globalThis.addEventListener?.("pagehide", onPageHide);
+	return () => {
+		onPageHide();
+		disposed = true;
+		globalThis.removeEventListener?.("pagehide", onPageHide);
+		if (snapshotTimer !== void 0) clearTimeout(snapshotTimer);
+		unsubscribePersistence?.();
+		channel.removeEventListener("message", onMessage);
+		channel.close();
+		if (originalTransport) client.transport = originalTransport;
+		if (store) {
+			if (hadOwnOnChange) store.onChange = originalOnChange;
+			else delete store.onChange;
+		}
+	};
+}
+function getRequests(client) {
+	const retained = client.operationLifetime?.operations;
+	const entries = /* @__PURE__ */ new Map();
+	const add = (descriptor, mode, status) => {
+		const key = descriptor?.key;
+		if (!key) return;
+		const existing = entries.get(key);
+		const modes = existing?.modes ?? [];
+		entries.set(key, {
+			items: existing?.items ?? (descriptor.items ?? []).map((item) => ({
+				...item.argsPayload !== void 0 && { args: toJSONValue(item.argsPayload) },
+				...item.ids && { ids: item.ids.map(String) },
+				kind: String(item.kind ?? ""),
+				name: String(item.name ?? ""),
+				paths: toPaths(item.plan?.paths),
+				...item.procedure && { procedure: item.procedure },
+				type: String(item.type ?? "")
+			})),
+			key,
+			modes: mode ? [...modes, {
+				mode,
+				status: status ?? "unknown"
+			}] : modes,
+			retainers: retained?.get(key)?.refCount ?? 0
+		});
+	};
+	for (const [, modes] of client.requests ?? []) for (const [mode, handle] of modes) add(handle.descriptor, mode, handle.status);
+	for (const [, operation] of retained ?? []) add(operation.descriptor);
+	return [...entries.values()];
+}
+export { connectFateDevtools as t };

package/lib/vite.d.mts

@@ -0,0 +1,31 @@
+import { Plugin } from "vite";
+export type FateDevtoolsPluginOptions = Readonly<{
+  /** Path the panel is served from. Defaults to `/__fate-devtools/`. */
+  base?: string;
+}>;
+/**
+ * The subset of the Vite DevTools Kit context this plugin uses. Declared here
+ * so `@vitejs/devtools` stays an optional peer dependency.
+ */
+type DevToolsSetupContext = {
+  docks: {
+    register: (entry: {
+      category?: string;
+      icon: string;
+      id: string;
+      title: string;
+      type: 'iframe';
+      url: string;
+    }) => unknown;
+  };
+};
+export type FateDevtoolsPlugin = Plugin & {
+  devtools: {
+    setup: (context: DevToolsSetupContext) => void;
+  };
+};
+/**
+ * Registers the fate panel with Vite DevTools and serves it during development.
+ */
+export declare function fateDevtools({ base }?: FateDevtoolsPluginOptions): FateDevtoolsPlugin;
+export {};

package/lib/vite.mjs

@@ -0,0 +1,98 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+// src/vite.ts
+/**
+* Vite plugin for the fate devtools.
+*
+* Adds a "fate" panel to Vite DevTools and serves the same panel as a
+* standalone page at `/__fate-devtools/`.
+*
+* @example
+* import { fateDevtools } from '@nkzw/fate-devtools/vite';
+*
+* export default defineConfig({
+*   devtools: true,
+*   plugins: [fateDevtools()],
+* });
+*
+* @module @nkzw/fate-devtools/vite
+*/
+const contentTypes = {
+	".css": "text/css; charset=utf-8",
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml"
+};
+const icon = `data:image/svg+xml,${encodeURIComponent("<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\"><rect width=\"64\" height=\"64\" rx=\"18\" fill=\"#3d87f5\"/><text x=\"18\" y=\"47\" fill=\"white\" font-family=\"Georgia,serif\" font-style=\"italic\" font-size=\"52\">f</text></svg>")}`;
+const findPanelDirectory = () => {
+	const candidates = [new URL("./panel/", import.meta.url), new URL("../lib/panel/", import.meta.url)];
+	for (const candidate of candidates) {
+		const directory = fileURLToPath(candidate);
+		if (existsSync(join(directory, "index.html"))) return directory;
+	}
+	return null;
+};
+/**
+* Registers the fate panel with Vite DevTools and serves it during development.
+*/
+function fateDevtools({ base = "/__fate-devtools/" } = {}) {
+	const mountPath = base.endsWith("/") ? base : `${base}/`;
+	return {
+		apply: "serve",
+		configureServer(server) {
+			const directory = findPanelDirectory();
+			server.middlewares.use(async (request, response, next) => {
+				const url = request.url?.split("?")[0];
+				if (!url || url !== mountPath.slice(0, -1) && !url.startsWith(mountPath)) return next();
+				if (!directory) {
+					response.statusCode = 500;
+					response.end("fate-devtools: The panel has not been built. Run `vp run build` in @nkzw/fate-devtools.");
+					return;
+				}
+				if (url === mountPath.slice(0, -1)) {
+					response.statusCode = 302;
+					response.setHeader("Location", mountPath);
+					response.end();
+					return;
+				}
+				let path;
+				try {
+					path = decodeURIComponent(url.slice(mountPath.length));
+				} catch {
+					response.statusCode = 400;
+					response.end();
+					return;
+				}
+				const file = normalize(join(directory, path || "index.html"));
+				if (!file.startsWith(directory.endsWith(sep) ? directory : directory + sep)) {
+					response.statusCode = 403;
+					response.end();
+					return;
+				}
+				try {
+					const body = await readFile(existsSync(file) ? file : join(directory, "index.html"));
+					response.setHeader("Content-Type", contentTypes[extname(file)] ?? "application/octet-stream");
+					response.setHeader("Cache-Control", "no-cache");
+					response.end(body);
+				} catch {
+					next();
+				}
+			});
+		},
+		devtools: { setup(context) {
+			context.docks.register({
+				category: "app",
+				icon,
+				id: "fate",
+				title: "fate",
+				type: "iframe",
+				url: mountPath
+			});
+		} },
+		name: "fate:devtools"
+	};
+}
+export { fateDevtools };