@chelone/core 0.6.0 → 0.9.0

package/dist/realtime/lock-session.js

@@ -1,82 +1,95 @@
 import { createMicroStore } from "../store/micro-store.js";
-const toError = (error) => error instanceof Error ? error : new Error(String(error));
-function createLockSession({
-  dataProvider,
-  resource,
-  id,
-  getIdentity,
-  meta,
-  onError
-}) {
-  const store = createMicroStore({
-    lock: null,
-    isLocking: false,
-    error: null
-  });
-  const metaParam = meta ? { meta } : {};
-  let held = null;
-  let running = false;
-  let epoch = 0;
-  let queue = Promise.resolve();
-  const enqueue = (step) => {
-    queue = queue.then(step).catch(() => {
-    });
-    return queue;
-  };
-  const acquire = async (myEpoch) => {
-    const isCurrent = () => epoch === myEpoch;
-    try {
-      const identity = await getIdentity();
-      const lock = await dataProvider.lock(resource, {
-        id,
-        identity,
-        ...metaParam
-      });
-      held = { identity };
-      if (isCurrent()) store.setState({ lock, isLocking: false });
-    } catch (cause) {
-      if (!isCurrent()) return;
-      const error = toError(cause);
-      store.setState({ isLocking: false, error });
-      onError?.(error);
-    }
-  };
-  const release = async () => {
-    if (!held) return;
-    const { identity } = held;
-    held = null;
-    try {
-      await dataProvider.unlock(resource, { id, identity, ...metaParam });
-    } catch (cause) {
-      onError?.(toError(cause));
-    }
-  };
-  return {
-    store,
-    start() {
-      if (running) return queue;
-      running = true;
-      const myEpoch = ++epoch;
-      store.setState({ isLocking: true, error: null });
-      return enqueue(() => acquire(myEpoch));
-    },
-    stop() {
-      if (!running) return queue;
-      running = false;
-      epoch++;
-      store.setState({ lock: null, isLocking: false, error: null });
-      return enqueue(release);
-    }
-  };
+// src/realtime/lock-session.ts
+var toError = (error) => error instanceof Error ? error : new Error(String(error));
+/**
+* Takes a record's lock on `start()` and gives it back on `stop()`. Steps run
+* one after another, so a `stop()` that arrives while `lock` is in flight
+* releases the lock once it lands, and `start()`, `stop()`, `start()` in one
+* tick ends holding it. Locks carry no expiry: a crashed tab leaves its lock
+* until the lock provider drops it.
+*/
+function createLockSession({ dataProvider, resource, id, getIdentity, meta, onError }) {
+	const store = createMicroStore({
+		lock: null,
+		isLocking: false,
+		error: null
+	});
+	const metaParam = meta ? { meta } : {};
+	let held = null;
+	let running = false;
+	let epoch = 0;
+	let queue = Promise.resolve();
+	const enqueue = (step) => {
+		queue = queue.then(step).catch(() => {});
+		return queue;
+	};
+	const acquire = async (myEpoch) => {
+		const isCurrent = () => epoch === myEpoch;
+		try {
+			const identity = await getIdentity();
+			const lock = await dataProvider.lock(resource, {
+				id,
+				identity,
+				...metaParam
+			});
+			held = { identity };
+			if (isCurrent()) store.setState({
+				lock,
+				isLocking: false
+			});
+		} catch (cause) {
+			if (!isCurrent()) return;
+			const error = toError(cause);
+			store.setState({
+				isLocking: false,
+				error
+			});
+			onError?.(error);
+		}
+	};
+	const release = async () => {
+		if (!held) return;
+		const { identity } = held;
+		held = null;
+		try {
+			await dataProvider.unlock(resource, {
+				id,
+				identity,
+				...metaParam
+			});
+		} catch (cause) {
+			onError?.(toError(cause));
+		}
+	};
+	return {
+		store,
+		start() {
+			if (running) return queue;
+			running = true;
+			const myEpoch = ++epoch;
+			store.setState({
+				isLocking: true,
+				error: null
+			});
+			return enqueue(() => acquire(myEpoch));
+		},
+		stop() {
+			if (!running) return queue;
+			running = false;
+			epoch++;
+			store.setState({
+				lock: null,
+				isLocking: false,
+				error: null
+			});
+			return enqueue(release);
+		}
+	};
 }
+/** The explicit identity wins; otherwise the auth provider's. */
 async function resolveLockIdentity(authProvider, explicit) {
-  if (explicit !== void 0) return explicit;
-  if (authProvider?.getIdentity) return (await authProvider.getIdentity()).id;
-  throw new Error(
-    "no identity available. Pass identity explicitly or configure an authProvider."
-  );
+	if (explicit !== void 0) return explicit;
+	if (authProvider?.getIdentity) return (await authProvider.getIdentity()).id;
+	throw new Error("no identity available. Pass identity explicitly or configure an authProvider.");
 }
-export {
-  createLockSession,
-  resolveLockIdentity
-};
+export { createLockSession, resolveLockIdentity };

package/dist/realtime/memory-transport.js

@@ -1,27 +1,27 @@
 import { createTopicHub } from "./topic-hub.js";
-function memoryTransport({
-  delayMs,
-  onError
-} = {}) {
-  const hub = createTopicHub({ onError });
-  const publishedEvents = [];
-  return {
-    publishedEvents,
-    subscribe: hub.subscribe,
-    async publish(topic, event) {
-      const full = { topic, ...event };
-      publishedEvents.push(full);
-      if (delayMs) await new Promise((resolve) => setTimeout(resolve, delayMs));
-      hub.dispatch(full);
-    },
-    onReconnect: hub.onReconnect,
-    onStatusChange: hub.onStatusChange,
-    onError: hub.onError,
-    getStatus: hub.getStatus,
-    simulateReconnect: hub.reconnected,
-    setStatus: hub.setStatus
-  };
+// src/realtime/memory-transport.ts
+/** Routes events by topic inside one process, with no server or client library. */
+function memoryTransport({ delayMs, onError } = {}) {
+	const hub = createTopicHub({ onError });
+	const publishedEvents = [];
+	return {
+		publishedEvents,
+		subscribe: hub.subscribe,
+		async publish(topic, event) {
+			const full = {
+				topic,
+				...event
+			};
+			publishedEvents.push(full);
+			if (delayMs) await new Promise((resolve) => setTimeout(resolve, delayMs));
+			hub.dispatch(full);
+		},
+		onReconnect: hub.onReconnect,
+		onStatusChange: hub.onStatusChange,
+		onError: hub.onError,
+		getStatus: hub.getStatus,
+		simulateReconnect: hub.reconnected,
+		setStatus: hub.setStatus
+	};
 }
-export {
-  memoryTransport
-};
+export { memoryTransport };

package/dist/realtime/presence.js

@@ -1,128 +1,126 @@
+import { isRecord } from "../guards.js";
 import { createMicroStore } from "../store/micro-store.js";
-const toError = (error) => error instanceof Error ? error : new Error(String(error));
-const sameUser = (a, b) => a.id === b.id && a.name === b.name && a.avatar === b.avatar;
-const isRecord = (value) => typeof value === "object" && value !== null;
-const isPresenceUser = (value) => isRecord(value) && typeof value.id === "string" && typeof value.name === "string";
-function createPresenceSession({
-  dataProvider,
-  topic,
-  user,
-  sessionId = crypto.randomUUID(),
-  heartbeatMs = 15e3,
-  staleMs = 3e4,
-  now = Date.now,
-  onError
-}) {
-  const store = createMicroStore({ users: [] });
-  const sessions = /* @__PURE__ */ new Map();
-  let running = false;
-  let unsubscribe;
-  let unsubscribeReconnect;
-  let heartbeat;
-  let sweep;
-  const report = (cause) => {
-    try {
-      onError?.(toError(cause));
-    } catch {
-    }
-  };
-  const publish = (type, payload) => {
-    try {
-      dataProvider.publish(topic, { type, payload }).catch(report);
-    } catch (cause) {
-      report(cause);
-    }
-  };
-  const announce = () => publish("presence", { sessionId, user });
-  const refresh = () => {
-    const live = /* @__PURE__ */ new Map();
-    for (const entry of sessions.values()) live.set(entry.user.id, entry.user);
-    const previous = store.getSnapshot().users;
-    const users = previous.flatMap((listed) => live.get(listed.id) ?? []);
-    const listedIds = new Set(users.map((listed) => listed.id));
-    for (const [id, other] of live) if (!listedIds.has(id)) users.push(other);
-    const unchanged = users.length === previous.length && users.every((other, index) => {
-      const prior = previous[index];
-      return prior !== void 0 && sameUser(other, prior);
-    });
-    if (!unchanged) store.setState({ users });
-  };
-  const handle = ({ type, payload }) => {
-    try {
-      if (!isRecord(payload) || typeof payload.sessionId !== "string") return;
-      const from = payload.sessionId;
-      if (from === sessionId) return;
-      if (type === "presence_leave") {
-        sessions.delete(from);
-        refresh();
-      } else if (type === "presence" && isPresenceUser(payload.user)) {
-        const known = sessions.has(from);
-        sessions.set(from, { user: payload.user, heardAt: now() });
-        if (!known) announce();
-        refresh();
-      }
-    } catch (cause) {
-      report(cause);
-    }
-  };
-  return {
-    store,
-    start() {
-      if (running) return;
-      running = true;
-      unsubscribe = dataProvider.subscribe(topic, handle);
-      unsubscribeReconnect = dataProvider.onReconnect?.(announce);
-      announce();
-      heartbeat = setInterval(announce, heartbeatMs);
-      sweep = setInterval(
-        () => {
-          try {
-            const cutoff = now() - staleMs;
-            for (const [id, entry] of sessions)
-              if (entry.heardAt < cutoff) sessions.delete(id);
-            refresh();
-          } catch (cause) {
-            report(cause);
-          }
-        },
-        Math.min(staleMs / 2, 5e3)
-      );
-    },
-    stop() {
-      if (!running) return;
-      running = false;
-      unsubscribe?.();
-      unsubscribe = void 0;
-      unsubscribeReconnect?.();
-      unsubscribeReconnect = void 0;
-      clearInterval(heartbeat);
-      clearInterval(sweep);
-      heartbeat = sweep = void 0;
-      publish("presence_leave", { sessionId });
-      sessions.clear();
-      try {
-        store.setState({ users: [] });
-      } catch (cause) {
-        report(cause);
-      }
-    }
-  };
+// src/realtime/presence.ts
+var toError = (error) => error instanceof Error ? error : new Error(String(error));
+var sameUser = (a, b) => a.id === b.id && a.name === b.name && a.avatar === b.avatar;
+var isPresenceUser = (value) => isRecord(value) && typeof value.id === "string" && typeof value.name === "string";
+/**
+* Announces `user` on `topic` and keeps the other users who announce there.
+* Self is told by `sessionId`, not by user id, so a second tab of the same
+* person still counts. Staleness is measured with `now()` at receipt, never
+* from a time the sender wrote.
+*/
+function createPresenceSession({ dataProvider, topic, user, sessionId = crypto.randomUUID(), heartbeatMs = 15e3, staleMs = 3e4, now = Date.now, onError }) {
+	const store = createMicroStore({ users: [] });
+	const sessions = /* @__PURE__ */ new Map();
+	let running = false;
+	let unsubscribe;
+	let unsubscribeReconnect;
+	let heartbeat;
+	let sweep;
+	const report = (cause) => {
+		try {
+			onError?.(toError(cause));
+		} catch {}
+	};
+	const publish = (type, payload) => {
+		try {
+			dataProvider.publish(topic, {
+				type,
+				payload
+			}).catch(report);
+		} catch (cause) {
+			report(cause);
+		}
+	};
+	const announce = () => publish("presence", {
+		sessionId,
+		user
+	});
+	const refresh = () => {
+		const live = /* @__PURE__ */ new Map();
+		for (const entry of sessions.values()) live.set(entry.user.id, entry.user);
+		const previous = store.getSnapshot().users;
+		const users = previous.flatMap((listed) => live.get(listed.id) ?? []);
+		const listedIds = new Set(users.map((listed) => listed.id));
+		for (const [id, other] of live) if (!listedIds.has(id)) users.push(other);
+		if (!(users.length === previous.length && users.every((other, index) => {
+			const prior = previous[index];
+			return prior !== void 0 && sameUser(other, prior);
+		}))) store.setState({ users });
+	};
+	const handle = ({ type, payload }) => {
+		try {
+			if (!isRecord(payload) || typeof payload.sessionId !== "string") return;
+			const from = payload.sessionId;
+			if (from === sessionId) return;
+			if (type === "presence_leave") {
+				sessions.delete(from);
+				refresh();
+			} else if (type === "presence" && isPresenceUser(payload.user)) {
+				const known = sessions.has(from);
+				sessions.set(from, {
+					user: payload.user,
+					heardAt: now()
+				});
+				if (!known) announce();
+				refresh();
+			}
+		} catch (cause) {
+			report(cause);
+		}
+	};
+	return {
+		store,
+		start() {
+			if (running) return;
+			running = true;
+			unsubscribe = dataProvider.subscribe(topic, handle);
+			unsubscribeReconnect = dataProvider.onReconnect?.(announce);
+			announce();
+			heartbeat = setInterval(announce, heartbeatMs);
+			sweep = setInterval(() => {
+				try {
+					const cutoff = now() - staleMs;
+					for (const [id, entry] of sessions) if (entry.heardAt < cutoff) sessions.delete(id);
+					refresh();
+				} catch (cause) {
+					report(cause);
+				}
+			}, Math.min(staleMs / 2, 5e3));
+		},
+		stop() {
+			if (!running) return;
+			running = false;
+			unsubscribe?.();
+			unsubscribe = void 0;
+			unsubscribeReconnect?.();
+			unsubscribeReconnect = void 0;
+			clearInterval(heartbeat);
+			clearInterval(sweep);
+			heartbeat = sweep = void 0;
+			publish("presence_leave", { sessionId });
+			sessions.clear();
+			try {
+				store.setState({ users: [] });
+			} catch (cause) {
+				report(cause);
+			}
+		}
+	};
 }
 function toPresenceUser(identity) {
-  const id = String(identity.id);
-  return {
-    id,
-    name: identity.fullName || id,
-    ...typeof identity.avatar === "string" ? { avatar: identity.avatar } : {}
-  };
+	const id = String(identity.id);
+	return {
+		id,
+		name: identity.fullName || id,
+		...typeof identity.avatar === "string" ? { avatar: identity.avatar } : {}
+	};
 }
+/** The first letters of the first two words, or `?` for a blank name. */
 function getPresenceInitials(name) {
-  const words = name.trim().split(/\s+/).filter(Boolean).slice(0, 2);
-  if (words.length === 0) return "?";
-  return words.map((word) => Array.from(word)[0]).join("").toUpperCase();
+	const words = name.trim().split(/\s+/).filter(Boolean).slice(0, 2);
+	if (words.length === 0) return "?";
+	return words.map((word) => Array.from(word)[0]).join("").toUpperCase();
 }
-export {
-  createPresenceSession,
-  getPresenceInitials,
-  toPresenceUser
-};
+export { createPresenceSession, getPresenceInitials, toPresenceUser };

package/dist/realtime/realtime-data-provider.d.ts

@@ -11,4 +11,14 @@ import type { RealtimeDataProvider, RealtimeDataProviderOptions, RealtimeTranspo
 export declare function realtimeDataProvider<TResources extends ResourceMap = ResourceMap>(base: DataProvider<TResources>, transport: RealtimeTransport, { locks }?: RealtimeDataProviderOptions): RealtimeDataProvider<TResources>;
 /** True when `dataProvider` was wrapped with `realtimeDataProvider()`. */
 export declare function isRealtimeDataProvider<TResources extends ResourceMap = ResourceMap>(dataProvider: DataProvider<TResources>): dataProvider is RealtimeDataProvider<TResources>;
+declare const transportMembers: readonly ["onReconnect", "onStatusChange", "getStatus", "onError"];
+/** The optional transport members a data provider may carry without being a full `RealtimeDataProvider`. */
+export type TransportMembers = Pick<RealtimeDataProvider, (typeof transportMembers)[number]>;
+/**
+ * True when every transport member `dataProvider` has is a function. Absent
+ * members are fine: they are optional, and a provider with only some of them
+ * (no `publish`, say) still reports reconnects and status.
+ */
+export declare function hasTransportMembers<TResources extends ResourceMap = ResourceMap>(dataProvider: DataProvider<TResources>): dataProvider is DataProvider<TResources> & TransportMembers;
 export declare function assertRealtimeDataProvider<TResources extends ResourceMap = ResourceMap>(dataProvider: DataProvider<TResources>, caller: string): asserts dataProvider is RealtimeDataProvider<TResources>;
+export {};

package/dist/realtime/realtime-data-provider.js

@@ -1,49 +1,52 @@
 import { copyMembers } from "./copy-members.js";
-const noLockProvider = (method) => Promise.reject(
-  new Error(
-    `realtimeDataProvider: ${method}() called but no LockProvider was configured`
-  )
-);
+// src/realtime/realtime-data-provider.ts
+var noLockProvider = (method) => Promise.reject(/* @__PURE__ */ new Error(`realtimeDataProvider: ${method}() called but no LockProvider was configured`));
+/**
+* Adds `subscribe`, `publish` and the lock methods to any data provider. The
+* optional transport members are copied only when the transport has them, so
+* `"getStatus" in dataProvider` tells a caller whether it can read a status.
+* Wrap the result of `combineDataProviders`, not the reverse: it keeps only
+* the nine verbs.
+*/
 function realtimeDataProvider(base, transport, { locks } = {}) {
-  const lockMethods = {
-    lock: (resource, params) => locks ? locks.lock(resource, params) : noLockProvider("lock"),
-    unlock: (resource, params) => locks ? locks.unlock(resource, params) : noLockProvider("unlock"),
-    getLock: (resource, params) => locks ? locks.getLock(resource, params) : noLockProvider("getLock"),
-    getLocks: (resource, params) => locks ? locks.getLocks(resource, params) : noLockProvider("getLocks")
-  };
-  const provider = {
-    ...copyMembers(base),
-    ...lockMethods,
-    subscribe: (topic, callback) => transport.subscribe(topic, callback),
-    publish: (topic, event) => transport.publish(topic, event)
-  };
-  if (transport.onReconnect) {
-    provider.onReconnect = transport.onReconnect.bind(transport);
-  }
-  if (transport.onStatusChange) {
-    provider.onStatusChange = transport.onStatusChange.bind(transport);
-  }
-  if (transport.getStatus) {
-    provider.getStatus = transport.getStatus.bind(transport);
-  }
-  if (transport.onError) {
-    provider.onError = transport.onError.bind(transport);
-  }
-  return provider;
+	const lockMethods = {
+		lock: (resource, params) => locks ? locks.lock(resource, params) : noLockProvider("lock"),
+		unlock: (resource, params) => locks ? locks.unlock(resource, params) : noLockProvider("unlock"),
+		getLock: (resource, params) => locks ? locks.getLock(resource, params) : noLockProvider("getLock"),
+		getLocks: (resource, params) => locks ? locks.getLocks(resource, params) : noLockProvider("getLocks")
+	};
+	const provider = {
+		...copyMembers(base),
+		...lockMethods,
+		subscribe: (topic, callback) => transport.subscribe(topic, callback),
+		publish: (topic, event) => transport.publish(topic, event)
+	};
+	if (transport.onReconnect) provider.onReconnect = transport.onReconnect.bind(transport);
+	if (transport.onStatusChange) provider.onStatusChange = transport.onStatusChange.bind(transport);
+	if (transport.getStatus) provider.getStatus = transport.getStatus.bind(transport);
+	if (transport.onError) provider.onError = transport.onError.bind(transport);
+	return provider;
 }
+/** True when `dataProvider` was wrapped with `realtimeDataProvider()`. */
 function isRealtimeDataProvider(dataProvider) {
-  const candidate = dataProvider;
-  return typeof candidate.subscribe === "function" && typeof candidate.publish === "function";
+	const candidate = dataProvider;
+	return typeof candidate.subscribe === "function" && typeof candidate.publish === "function";
+}
+var transportMembers = [
+	"onReconnect",
+	"onStatusChange",
+	"getStatus",
+	"onError"
+];
+/**
+* True when every transport member `dataProvider` has is a function. Absent
+* members are fine: they are optional, and a provider with only some of them
+* (no `publish`, say) still reports reconnects and status.
+*/
+function hasTransportMembers(dataProvider) {
+	return transportMembers.every((name) => !(name in dataProvider) || typeof Reflect.get(dataProvider, name) === "function");
 }
 function assertRealtimeDataProvider(dataProvider, caller) {
-  if (!isRealtimeDataProvider(dataProvider)) {
-    throw new Error(
-      `${caller}: dataProvider does not implement subscribe(). Wrap it with realtimeDataProvider().`
-    );
-  }
+	if (!isRealtimeDataProvider(dataProvider)) throw new Error(`${caller}: dataProvider does not implement subscribe(). Wrap it with realtimeDataProvider().`);
 }
-export {
-  assertRealtimeDataProvider,
-  isRealtimeDataProvider,
-  realtimeDataProvider
-};
+export { assertRealtimeDataProvider, hasTransportMembers, isRealtimeDataProvider, realtimeDataProvider };

package/dist/realtime/reconnect-backoff.js

@@ -0,0 +1,17 @@
+// src/realtime/reconnect-backoff.ts
+function resolveReconnectConfig(config = {}) {
+	return {
+		enabled: config.enabled ?? true,
+		initialDelayMs: config.initialDelayMs ?? 1e3,
+		maxDelayMs: config.maxDelayMs ?? 3e4,
+		maxAttempts: config.maxAttempts ?? Number.POSITIVE_INFINITY,
+		jitter: config.jitter ?? .3
+	};
+}
+/** The wait before retry number `attempt` (from 0): exponential, capped, then jittered. */
+function reconnectDelay(attempt, config, random = Math.random) {
+	const base = Math.min(config.initialDelayMs * 2 ** attempt, config.maxDelayMs);
+	const spread = base * config.jitter;
+	return Math.max(0, base + (random() * 2 - 1) * spread);
+}
+export { reconnectDelay, resolveReconnectConfig };

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

@@ -0,0 +1,31 @@
+import { type RealtimeReconnectConfig } from "./reconnect-backoff.js";
+import type { RealtimeTransport, RealtimeTransportError } from "./types.js";
+export interface SseTransportOptions {
+    /** The stream URL; the topic filter and the token are appended to its query. */
+    url: string;
+    /** Where `publish` POSTs. Without it `publish` rejects. */
+    publishUrl?: string;
+    /** The bearer token for the stream (as `token`) and for the publish POST. */
+    getAuthToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Sent to `EventSource` and as `credentials: "include"` on the publish POST. */
+    withCredentials?: boolean;
+    reconnect?: RealtimeReconnectConfig;
+    /** How long the stream stays open with no subscriber. Default 30000. */
+    idleDisconnectMs?: number;
+    /** The query parameter that carries the topics. Default `"topics"`. */
+    topicFilterParam?: string;
+    /** Called for every transport error, like a listener from `onError()`. */
+    onError?: (error: RealtimeTransportError) => void;
+    /** Used for the publish POST. Default the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** A `RealtimeTransport` with every optional member, plus `close()`. */
+export interface SseTransport extends Required<RealtimeTransport> {
+    /** Closes the stream and sets `"disconnected"`; a later subscribe opens again. */
+    close(): void;
+}
+/**
+ * Receives realtime events over server-sent events, one named event per topic,
+ * and publishes with a POST.
+ */
+export declare function sseTransport({ url, publishUrl, getAuthToken, withCredentials, reconnect, idleDisconnectMs, topicFilterParam, onError, fetch: fetchOption, }: SseTransportOptions): SseTransport;