@chelone/core 0.6.0 → 0.7.0

package/dist/realtime/sse-transport.js

@@ -0,0 +1,235 @@
+import { isRecord } from "../guards.js";
+import { reconnectDelay, resolveReconnectConfig } from "./reconnect-backoff.js";
+import { createTopicHub } from "./topic-hub.js";
+// src/realtime/sse-transport.ts
+function isWireEvent(value) {
+	return isRecord(value) && typeof value.type === "string" && (value.meta === void 0 || isRecord(value.meta));
+}
+var DEFAULT_IDLE_DISCONNECT_MS = 3e4;
+/**
+* Receives realtime events over server-sent events, one named event per topic,
+* and publishes with a POST.
+*/
+function sseTransport({ url, publishUrl, getAuthToken, withCredentials = false, reconnect, idleDisconnectMs = DEFAULT_IDLE_DISCONNECT_MS, topicFilterParam = "topics", onError, fetch: fetchOption }) {
+	const hub = createTopicHub({ onError });
+	hub.setStatus("idle");
+	const config = resolveReconnectConfig(reconnect);
+	let source = null;
+	let filter = /* @__PURE__ */ new Set();
+	let active = false;
+	let generation = 0;
+	let attempt = 0;
+	let dropped = false;
+	let openQueued = false;
+	let resolvingToken = false;
+	let retryTimer;
+	let idleTimer;
+	const readToken = async () => await getAuthToken?.() || void 0;
+	const stopStream = () => {
+		clearTimeout(retryTimer);
+		retryTimer = void 0;
+		source?.close();
+		source = null;
+		filter = /* @__PURE__ */ new Set();
+	};
+	const streamUrl = (topics, token) => {
+		const query = [`${encodeURIComponent(topicFilterParam)}=${encodeURIComponent(topics.join(","))}`, ...token === void 0 ? [] : [`token=${encodeURIComponent(token)}`]].join("&");
+		return `${url}${url.includes("?") ? "&" : "?"}${query}`;
+	};
+	const retryOrGiveUp = (failure) => {
+		const retrying = config.enabled && attempt < config.maxAttempts;
+		hub.report(failure(retrying));
+		if (!retrying) {
+			active = false;
+			hub.setStatus("disconnected");
+			return;
+		}
+		hub.setStatus("reconnecting");
+		retryTimer = setTimeout(() => {
+			retryTimer = void 0;
+			open(true);
+		}, reconnectDelay(attempt, config));
+		attempt += 1;
+	};
+	const handleError = (stream, opened) => {
+		if (source !== stream) return;
+		stopStream();
+		dropped ||= opened;
+		retryOrGiveUp((retrying) => ({
+			kind: "connect_failed",
+			retrying
+		}));
+	};
+	async function open(isRetry = false) {
+		stopStream();
+		const current = ++generation;
+		active = true;
+		resolvingToken = true;
+		let token;
+		try {
+			token = await readToken();
+		} catch (cause) {
+			if (current !== generation) return;
+			resolvingToken = false;
+			if (isRetry) {
+				retryOrGiveUp((retrying) => ({
+					kind: "auth_failed",
+					cause,
+					retrying
+				}));
+				return;
+			}
+			active = false;
+			hub.report({
+				kind: "auth_failed",
+				cause,
+				retrying: false
+			});
+			hub.setStatus("disconnected");
+			return;
+		}
+		if (current !== generation) return;
+		resolvingToken = false;
+		const topics = hub.topics();
+		if (topics.length === 0) {
+			goIdle();
+			return;
+		}
+		let stream;
+		try {
+			stream = new EventSource(streamUrl(topics, token), { withCredentials });
+		} catch {
+			active = false;
+			hub.report({
+				kind: "connect_failed",
+				retrying: false
+			});
+			hub.setStatus("disconnected");
+			return;
+		}
+		source = stream;
+		filter = new Set(topics);
+		let opened = false;
+		stream.addEventListener("open", () => {
+			if (source !== stream) return;
+			opened = true;
+			attempt = 0;
+			hub.setStatus("connected");
+			if (dropped) {
+				dropped = false;
+				hub.reconnected();
+			}
+		});
+		stream.addEventListener("error", () => handleError(stream, opened));
+		for (const topic of topics) stream.addEventListener(topic, (message) => {
+			if (source !== stream || !("data" in message)) return;
+			if (typeof message.data === "string") receive(topic, message.data);
+		});
+	}
+	const receive = (topic, data) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(data);
+		} catch (cause) {
+			hub.report({
+				kind: "parse_failed",
+				topic,
+				cause,
+				retrying: false
+			});
+			return;
+		}
+		if (isWireEvent(parsed)) hub.dispatch({
+			...parsed,
+			topic
+		});
+	};
+	const queueOpen = () => {
+		if (openQueued) return;
+		openQueued = true;
+		Promise.resolve().then(() => {
+			if (!openQueued) return;
+			openQueued = false;
+			if (!active) attempt = 0;
+			return open();
+		});
+	};
+	function goIdle() {
+		generation += 1;
+		resolvingToken = false;
+		clearTimeout(idleTimer);
+		idleTimer = void 0;
+		stopStream();
+		active = false;
+		dropped = false;
+		if (hub.getStatus() !== "idle") hub.setStatus("idle");
+	}
+	return {
+		subscribe(topic, callback) {
+			const stop = hub.subscribe(topic, callback);
+			clearTimeout(idleTimer);
+			idleTimer = void 0;
+			const covered = retryTimer !== void 0 || resolvingToken || filter.has(topic);
+			if (!active || !covered) queueOpen();
+			return () => {
+				stop();
+				if (hub.topics().length > 0 || !active) return;
+				clearTimeout(idleTimer);
+				idleTimer = setTimeout(goIdle, idleDisconnectMs);
+			};
+		},
+		async publish(topic, event) {
+			if (!publishUrl) throw new Error("sseTransport needs the publishUrl option to publish");
+			const headers = { "Content-Type": "application/json" };
+			try {
+				const token = await readToken();
+				if (token !== void 0) headers.Authorization = `Bearer ${token}`;
+			} catch (cause) {
+				hub.report({
+					kind: "auth_failed",
+					topic,
+					cause,
+					retrying: false
+				});
+				throw cause;
+			}
+			const doFetch = fetchOption ?? ((input, init) => globalThis.fetch(input, init));
+			try {
+				const response = await doFetch(publishUrl, {
+					method: "POST",
+					headers,
+					body: JSON.stringify({
+						topic,
+						event
+					}),
+					credentials: withCredentials ? "include" : void 0
+				});
+				if (!response.ok) throw new Error(`Publishing to ${topic} failed: ${response.status}`);
+			} catch (cause) {
+				hub.report({
+					kind: "send_failed",
+					topic,
+					cause,
+					retrying: false
+				});
+				throw cause;
+			}
+		},
+		onReconnect: hub.onReconnect,
+		onStatusChange: hub.onStatusChange,
+		onError: hub.onError,
+		getStatus: hub.getStatus,
+		close() {
+			openQueued = false;
+			generation += 1;
+			resolvingToken = false;
+			clearTimeout(idleTimer);
+			idleTimer = void 0;
+			stopStream();
+			active = false;
+			dropped = false;
+			hub.setStatus("disconnected");
+		}
+	};
+}
+export { sseTransport };

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.js

@@ -1,75 +1,66 @@
-const addListener = (listeners, listener) => {
-  listeners.add(listener);
-  return () => {
-    listeners.delete(listener);
-  };
+// src/realtime/topic-hub.ts
+var addListener = (listeners, listener) => {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
 };
-const isolate = (call) => {
-  try {
-    call();
-  } catch {
-  }
+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 = {
-        // type-escape: the hub stores callbacks for any payload; dispatch passes the event on unchanged.
-        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);
-    }
-  };
+	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
-};
+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;