@chelone/core 0.5.0 → 0.7.0

package/dist/realtime/status-store.js

@@ -1,33 +1,28 @@
 import { createMicroStore } from "../store/micro-store.js";
+// src/realtime/status-store.ts
 function readStatus(source) {
-  if (source.getStatus) return source.getStatus();
-  return source.onStatusChange ? "disconnected" : "idle";
+	if (source.getStatus) return source.getStatus();
+	return source.onStatusChange ? "disconnected" : "idle";
 }
+/** Follows the connection while it has a subscriber, and lets go of it at zero. */
 function createRealtimeStatusStore(source) {
-  const store = createMicroStore(
-    { status: readStatus(source), lastError: null },
-    {
-      onSubscribed() {
-        const status = readStatus(source);
-        store.setState(
-          status === "connected" ? { status, lastError: null } : { status }
-        );
-        const stops = [
-          source.onStatusChange?.(
-            (status2) => store.setState(
-              status2 === "connected" ? { status: status2, lastError: null } : { status: status2 }
-            )
-          ),
-          source.onError?.((lastError) => store.setState({ lastError }))
-        ];
-        return () => {
-          for (const stop of stops) stop?.();
-        };
-      }
-    }
-  );
-  return store;
+	const store = createMicroStore({
+		status: readStatus(source),
+		lastError: null
+	}, { onSubscribed() {
+		const status = readStatus(source);
+		store.setState(status === "connected" ? {
+			status,
+			lastError: null
+		} : { status });
+		const stops = [source.onStatusChange?.((status) => store.setState(status === "connected" ? {
+			status,
+			lastError: null
+		} : { status })), source.onError?.((lastError) => store.setState({ lastError }))];
+		return () => {
+			for (const stop of stops) stop?.();
+		};
+	} });
+	return store;
 }
-export {
-  createRealtimeStatusStore
-};
+export { createRealtimeStatusStore };

package/dist/realtime/topic-hub.d.ts

@@ -0,0 +1,24 @@
+import type { RealtimeConnectionStatus, RealtimeEvent, RealtimeTransport, RealtimeTransportError } from "./types.js";
+export interface TopicHubOptions {
+    /** Called for every reported error, like a listener from `onError()`. */
+    onError?: (error: RealtimeTransportError) => void;
+}
+/**
+ * The subscriber bookkeeping every transport needs: per-topic subscriptions,
+ * isolated dispatch, and the status, reconnect and error listeners.
+ */
+export interface TopicHub extends Required<Pick<RealtimeTransport, "subscribe" | "onReconnect" | "onStatusChange" | "getStatus" | "onError">> {
+    /** Calls the subscribers of `event.topic`; a throwing one is reported. */
+    dispatch(event: RealtimeEvent): void;
+    /** Whether any subscriber is listening on `topic`. */
+    has(topic: string): boolean;
+    /** Every topic with a subscriber, in the order each was first subscribed. */
+    topics(): string[];
+    /** Calls the `onError` option and every `onError` listener. */
+    report(error: RealtimeTransportError): void;
+    setStatus(status: RealtimeConnectionStatus): void;
+    /** Calls every `onReconnect` listener. */
+    reconnected(): void;
+}
+/** Starts `"connected"`; a transport that connects asynchronously sets its own status. */
+export declare function createTopicHub({ onError }?: TopicHubOptions): TopicHub;

package/dist/realtime/topic-hub.js

@@ -0,0 +1,66 @@
+// src/realtime/topic-hub.ts
+var addListener = (listeners, listener) => {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+};
+var isolate = (call) => {
+	try {
+		call();
+	} catch {}
+};
+/** Starts `"connected"`; a transport that connects asynchronously sets its own status. */
+function createTopicHub({ onError } = {}) {
+	const subscribers = /* @__PURE__ */ new Map();
+	const reconnectListeners = /* @__PURE__ */ new Set();
+	const statusListeners = /* @__PURE__ */ new Set();
+	const errorListeners = /* @__PURE__ */ new Set();
+	let status = "connected";
+	const report = (error) => {
+		for (const listener of [...onError ? [onError] : [], ...errorListeners]) isolate(() => listener(error));
+	};
+	return {
+		subscribe(topic, callback) {
+			const subscription = { callback };
+			const set = subscribers.get(topic) ?? /* @__PURE__ */ new Set();
+			set.add(subscription);
+			subscribers.set(topic, set);
+			return () => {
+				set.delete(subscription);
+				if (set.size === 0 && subscribers.get(topic) === set) subscribers.delete(topic);
+			};
+		},
+		dispatch(event) {
+			const live = subscribers.get(event.topic);
+			for (const subscription of [...live ?? []]) {
+				if (!live?.has(subscription)) continue;
+				try {
+					subscription.callback(event);
+				} catch (cause) {
+					report({
+						kind: "handler_threw",
+						topic: event.topic,
+						cause,
+						retrying: false
+					});
+				}
+			}
+		},
+		has: (topic) => subscribers.has(topic),
+		topics: () => [...subscribers.keys()],
+		report,
+		onReconnect: (callback) => addListener(reconnectListeners, callback),
+		onStatusChange: (callback) => addListener(statusListeners, callback),
+		onError: (callback) => addListener(errorListeners, callback),
+		getStatus: () => status,
+		setStatus(next) {
+			status = next;
+			for (const listener of [...statusListeners]) isolate(() => listener(next));
+		},
+		reconnected() {
+			for (const listener of [...reconnectListeners]) isolate(listener);
+		}
+	};
+}
+export { createTopicHub };

package/dist/realtime/topics.js

@@ -1,12 +1,10 @@
-const resourceTopic = (resource) => `resource/${resource}`;
-const recordTopic = (resource, id) => `resource/${resource}/${id}`;
-const lockResourceTopic = (resource) => `lock/${resource}`;
-const lockTopic = (resource, id) => `lock/${resource}/${id}`;
-const presenceTopic = (resource, id) => `presence/${resource}/${id}`;
-export {
-  lockResourceTopic,
-  lockTopic,
-  presenceTopic,
-  recordTopic,
-  resourceTopic
-};
+// src/realtime/topics.ts
+/** Events for the resource as a whole: creates, and the ids of any write. */
+var resourceTopic = (resource) => `resource/${resource}`;
+/** Events for one record. `1` and `"1"` give the same topic. */
+var recordTopic = (resource, id) => `resource/${resource}/${id}`;
+var lockResourceTopic = (resource) => `lock/${resource}`;
+var lockTopic = (resource, id) => `lock/${resource}/${id}`;
+/** Who is on one record. `1` and `"1"` give the same topic. */
+var presenceTopic = (resource, id) => `presence/${resource}/${id}`;
+export { lockResourceTopic, lockTopic, presenceTopic, recordTopic, resourceTopic };

package/dist/realtime/types.js

@@ -1,13 +1,11 @@
-class LockConflictError extends Error {
-  kind = "LockConflictError";
-  existingLock;
-  constructor(existingLock) {
-    super(
-      `Resource ${existingLock.resource}/${String(existingLock.recordId)} is locked by ${String(existingLock.identity)}`
-    );
-    this.existingLock = existingLock;
-  }
-}
-export {
-  LockConflictError
+// src/realtime/types.ts
+/** Rejected by `lock()` when another identity already holds the record. */
+var LockConflictError = class extends Error {
+	kind = "LockConflictError";
+	existingLock;
+	constructor(existingLock) {
+		super(`Resource ${existingLock.resource}/${String(existingLock.recordId)} is locked by ${String(existingLock.identity)}`);
+		this.existingLock = existingLock;
+	}
 };
+export { LockConflictError };

package/dist/realtime/unread-count.js

@@ -1,27 +1,27 @@
 import { resourceTopic } from "./topics.js";
-const DEFAULT_EVENTS = ["created"];
+// src/realtime/unread-count.ts
+var DEFAULT_EVENTS = ["created"];
+/**
+* The store key of a resource's unread count for an event list. The default
+* `["created"]` keeps `realtime.unread.<resource>`; any other list adds its
+* sorted, de-duplicated types as a suffix, so the order of `events` never
+* splits a count and links watching different events never share one.
+*/
 function unreadKey(resource, events = DEFAULT_EVENTS) {
-  const types = [...new Set(events)].sort();
-  const base = `realtime.unread.${resource}`;
-  return types.length === 1 && types[0] === "created" ? base : `${base}.${types.join("+")}`;
+	const types = [...new Set(events)].sort();
+	const base = `realtime.unread.${resource}`;
+	return types.length === 1 && types[0] === "created" ? base : `${base}.${types.join("+")}`;
 }
-function subscribeUnreadCount({
-  dataProvider,
-  store,
-  resource,
-  events = DEFAULT_EVENTS
-}) {
-  const key = unreadKey(resource, events);
-  return dataProvider.subscribe(resourceTopic(resource), (event) => {
-    if (!events.includes(event.type)) return;
-    store.setItem(key, (store.getItem(key) ?? 0) + 1);
-  });
+/** Adds one to the count under `unreadKey(resource, events)` for each listed event. Returns the teardown. */
+function subscribeUnreadCount({ dataProvider, store, resource, events = DEFAULT_EVENTS }) {
+	const key = unreadKey(resource, events);
+	return dataProvider.subscribe(resourceTopic(resource), (event) => {
+		if (!events.includes(event.type)) return;
+		store.setItem(key, (store.getItem(key) ?? 0) + 1);
+	});
 }
+/** Resets the count of one event list; pass the same `events` the link subscribed with. */
 function clearUnread(store, resource, events) {
-  store.setItem(unreadKey(resource, events), 0);
+	store.setItem(unreadKey(resource, events), 0);
 }
-export {
-  clearUnread,
-  subscribeUnreadCount,
-  unreadKey
-};
+export { clearUnread, subscribeUnreadCount, unreadKey };

package/dist/realtime/websocket-transport.d.ts

@@ -0,0 +1,32 @@
+import { type RealtimeReconnectConfig } from "./reconnect-backoff.js";
+import type { RealtimeTransport, RealtimeTransportError } from "./types.js";
+export interface WebSocketTransportOptions {
+    url: string;
+    /** Subprotocols offered on every connection. */
+    protocols?: string[];
+    /** Read before every connection, so a retry carries a fresh token. */
+    getAuthToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Where the token goes. `"query"` (default) adds a URL-encoded `token`
+     * parameter; `"subprotocol"` offers it after `protocols` and keeps it out of
+     * the URL.
+     */
+    authMode?: "query" | "subprotocol";
+    reconnect?: RealtimeReconnectConfig;
+    /** Close the socket after this long with no subscriber. Default 30000. */
+    idleDisconnectMs?: number;
+    /** Ping this often; a ping with no reply by the next one is a drop. Default 30000. */
+    heartbeatMs?: number;
+    /** Called for every transport error, like a listener from `onError()`. */
+    onError?: (error: RealtimeTransportError) => void;
+}
+/** A `RealtimeTransport` with every optional member, plus `close()`. */
+export interface WebSocketTransport extends Required<RealtimeTransport> {
+    /**
+     * Closes the socket, rejects queued publishes and sets `"disconnected"`.
+     * A later subscribe or publish opens again.
+     */
+    close(): void;
+}
+/** Carries realtime events over one WebSocket and reconnects with backoff. */
+export declare function webSocketTransport({ url, protocols, getAuthToken, authMode, reconnect, idleDisconnectMs, heartbeatMs, onError, }: WebSocketTransportOptions): WebSocketTransport;

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