@chelone/core 0.6.0 → 0.7.0

package/dist/realtime/websocket-transport.js

@@ -0,0 +1,306 @@
+import { reconnectDelay, resolveReconnectConfig } from "./reconnect-backoff.js";
+import { createTopicHub } from "./topic-hub.js";
+// src/realtime/websocket-transport.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isServerFrame(value) {
+	if (!isObject(value)) return false;
+	if (!("topic" in value) || typeof value.topic !== "string") return false;
+	if (!("type" in value) || typeof value.type !== "string") return false;
+	return !("meta" in value) || value.meta === void 0 || isObject(value.meta);
+}
+var isPong = (value) => isObject(value) && "op" in value && value.op === "pong";
+function parseFrame(data) {
+	try {
+		if (typeof data !== "string") throw new Error("frame is not text");
+		const frame = JSON.parse(data);
+		if (isPong(frame)) return { kind: "pong" };
+		if (isServerFrame(frame)) return {
+			kind: "event",
+			event: frame
+		};
+		throw new Error("frame is not a realtime event");
+	} catch (cause) {
+		return {
+			kind: "invalid",
+			cause: cause instanceof Error ? cause : /* @__PURE__ */ new Error("frame is invalid")
+		};
+	}
+}
+/** Carries realtime events over one WebSocket and reconnects with backoff. */
+function webSocketTransport({ url, protocols = [], getAuthToken, authMode = "query", reconnect, idleDisconnectMs = 3e4, heartbeatMs = 3e4, onError }) {
+	const hub = createTopicHub({ onError });
+	const backoff = resolveReconnectConfig(reconnect);
+	hub.setStatus("idle");
+	let connection = null;
+	let connecting = false;
+	let epoch = 0;
+	let attempt = 0;
+	let lostConnection = false;
+	let retryTimer;
+	let idleTimer;
+	let heartbeatTimer;
+	let queue = [];
+	const setStatus = (status) => {
+		if (hub.getStatus() !== status) hub.setStatus(status);
+	};
+	const rejectQueue = (reason) => {
+		const rejected = queue;
+		queue = [];
+		for (const publish of rejected) publish.reject(reason);
+	};
+	const send = (target, frame, topic) => {
+		try {
+			target.socket.send(JSON.stringify(frame));
+			return null;
+		} catch (cause) {
+			hub.report({
+				kind: "send_failed",
+				topic,
+				cause,
+				retrying: false
+			});
+			return cause instanceof Error ? cause : /* @__PURE__ */ new Error("send failed");
+		}
+	};
+	const stopHeartbeat = () => {
+		clearInterval(heartbeatTimer);
+		heartbeatTimer = void 0;
+	};
+	const detach = (target) => {
+		stopHeartbeat();
+		target.socket.removeEventListener("open", target.onOpen);
+		target.socket.removeEventListener("message", target.onMessage);
+		target.socket.removeEventListener("close", target.onClose);
+		try {
+			target.socket.close();
+		} catch {}
+		if (connection === target) connection = null;
+	};
+	const teardown = () => {
+		epoch += 1;
+		connecting = false;
+		attempt = 0;
+		lostConnection = false;
+		clearTimeout(retryTimer);
+		retryTimer = void 0;
+		clearTimeout(idleTimer);
+		idleTimer = void 0;
+		if (connection) detach(connection);
+	};
+	const touchIdle = () => {
+		clearTimeout(idleTimer);
+		idleTimer = void 0;
+		if (hub.topics().length > 0) return;
+		idleTimer = setTimeout(() => {
+			idleTimer = void 0;
+			if (hub.topics().length > 0) return;
+			if (!connection && !connecting && retryTimer === void 0) return;
+			teardown();
+			rejectQueue(/* @__PURE__ */ new Error("webSocketTransport went idle"));
+			setStatus("idle");
+		}, idleDisconnectMs);
+	};
+	const giveUp = (reason) => {
+		rejectQueue(reason);
+		setStatus("disconnected");
+	};
+	const lose = (target, clean, cause) => {
+		detach(target);
+		clearTimeout(idleTimer);
+		if (target.opened) lostConnection = true;
+		if (clean) {
+			setStatus("disconnected");
+			return;
+		}
+		if (backoff.enabled && attempt < backoff.maxAttempts) {
+			const delay = reconnectDelay(attempt, backoff);
+			attempt += 1;
+			hub.report({
+				kind: "connect_failed",
+				cause,
+				retrying: true
+			});
+			setStatus("reconnecting");
+			retryTimer = setTimeout(() => {
+				retryTimer = void 0;
+				connect();
+			}, delay);
+			touchIdle();
+			return;
+		}
+		hub.report({
+			kind: "connect_failed",
+			cause,
+			retrying: false
+		});
+		giveUp(/* @__PURE__ */ new Error("webSocketTransport could not connect"));
+	};
+	const heartbeat = (target) => {
+		if (target.awaitingPong) {
+			lose(target, false, { reason: "heartbeat missed" });
+			return;
+		}
+		target.awaitingPong = true;
+		send(target, { op: "ping" });
+	};
+	const handleMessage = (target, message) => {
+		target.awaitingPong = false;
+		const parsed = parseFrame(message.data);
+		if (parsed.kind === "pong") return;
+		if (parsed.kind === "invalid") {
+			hub.report({
+				kind: "parse_failed",
+				cause: parsed.cause,
+				retrying: false
+			});
+			return;
+		}
+		const { topic, type, payload, meta } = parsed.event;
+		hub.dispatch({
+			topic,
+			type,
+			payload,
+			...meta ? { meta } : {}
+		});
+	};
+	const handleOpen = (target) => {
+		target.opened = true;
+		attempt = 0;
+		setStatus("connected");
+		for (const topic of hub.topics()) send(target, {
+			op: "subscribe",
+			topic
+		});
+		const flushed = queue;
+		queue = [];
+		for (const { topic, event, resolve, reject } of flushed) {
+			const failure = send(target, {
+				op: "publish",
+				topic,
+				event
+			}, topic);
+			if (failure) reject(failure);
+			else resolve();
+		}
+		heartbeatTimer = setInterval(() => heartbeat(target), heartbeatMs);
+		touchIdle();
+		if (lostConnection) {
+			lostConnection = false;
+			hub.reconnected();
+		}
+	};
+	const open = (token) => {
+		let target;
+		try {
+			const address = token && authMode === "query" ? `${url}${url.includes("?") ? "&" : "?"}token=${encodeURIComponent(token)}` : url;
+			const offered = token && authMode === "subprotocol" ? [...protocols, token] : protocols;
+			target = {
+				socket: offered.length > 0 ? new WebSocket(address, offered) : new WebSocket(address),
+				opened: false,
+				awaitingPong: false,
+				onOpen: () => handleOpen(target),
+				onMessage: (message) => handleMessage(target, message),
+				onClose: (event) => lose(target, event.wasClean, {
+					code: event.code,
+					reason: event.reason
+				})
+			};
+		} catch (error) {
+			const name = error instanceof Error ? error.name : "Error";
+			const cause = /* @__PURE__ */ new Error(`WebSocket constructor failed: ${name}`);
+			hub.report({
+				kind: "connect_failed",
+				cause,
+				retrying: false
+			});
+			giveUp(cause);
+			return;
+		}
+		connection = target;
+		target.socket.addEventListener("open", target.onOpen);
+		target.socket.addEventListener("message", target.onMessage);
+		target.socket.addEventListener("close", target.onClose);
+	};
+	async function connect() {
+		connecting = true;
+		const startedAt = epoch;
+		let token;
+		if (getAuthToken) {
+			try {
+				token = await getAuthToken();
+			} catch (cause) {
+				if (epoch !== startedAt) return;
+				connecting = false;
+				hub.report({
+					kind: "auth_failed",
+					cause,
+					retrying: false
+				});
+				giveUp(cause instanceof Error ? cause : /* @__PURE__ */ new Error("auth failed"));
+				return;
+			}
+			if (epoch !== startedAt) return;
+		}
+		connecting = false;
+		open(token);
+	}
+	const ensureOpen = () => {
+		if (connection || connecting || retryTimer !== void 0) return;
+		attempt = 0;
+		connect();
+	};
+	return {
+		subscribe(topic, callback) {
+			const first = !hub.has(topic);
+			const unsubscribe = hub.subscribe(topic, callback);
+			touchIdle();
+			if (first && connection?.opened) send(connection, {
+				op: "subscribe",
+				topic
+			}, topic);
+			ensureOpen();
+			let done = false;
+			return () => {
+				if (done) return;
+				done = true;
+				unsubscribe();
+				if (!hub.has(topic) && connection?.opened) send(connection, {
+					op: "unsubscribe",
+					topic
+				}, topic);
+				touchIdle();
+			};
+		},
+		publish(topic, event) {
+			if (connection?.opened) {
+				touchIdle();
+				const failure = send(connection, {
+					op: "publish",
+					topic,
+					event
+				}, topic);
+				return failure ? Promise.reject(failure) : Promise.resolve();
+			}
+			return new Promise((resolve, reject) => {
+				queue.push({
+					topic,
+					event,
+					resolve,
+					reject
+				});
+				touchIdle();
+				ensureOpen();
+			});
+		},
+		onReconnect: hub.onReconnect,
+		onStatusChange: hub.onStatusChange,
+		onError: hub.onError,
+		getStatus: hub.getStatus,
+		close() {
+			teardown();
+			rejectQueue(/* @__PURE__ */ new Error("webSocketTransport is closed"));
+			setStatus("disconnected");
+		}
+	};
+}
+export { webSocketTransport };

package/dist/resource/describe-resource.d.ts

@@ -28,6 +28,8 @@ export interface ResourceDescriptor {
     resource: string;
     fields: FieldDescriptor[];
 }
+/** For core's block editor helpers; not exported from the package index. */
+export declare function describeField(source: string, schema: unknown, references: ResourceConfig["references"]): FieldDescriptor;
 /**
  * Turns a resource's registered Zod schema (Zod 3 or Zod 4) into one descriptor per field, in
  * schema key order. Returns `undefined` when there is no schema to read or it