@faybl/react-utils 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @faybl/react-utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hooks for Faybl web apps.
+
+```
+npm install @faybl/react-utils
+```
+
+Every hook takes the faybl-client as `client` and does nothing until it has
+one. A list of rids or ids is compared by its content, so a new array with the
+same ids does not resubscribe.
+
+```js
+import { useChannelsLatest, useChannelsSeries, usePresence } from '@faybl/react-utils';
+
+const presenceById = usePresence({ client, identityIds });
+const latest = useChannelsLatest({ client, rids, commitMs: 1000, onError });
+const series = useChannelsSeries({ client, rids, windowSeconds: 3600 });
+```
+
+| Hook                | Returns                                                                |
+| ------------------- | ---------------------------------------------------------------------- |
+| `usePresence`       | `{ [identityId]: { ts, connected } }`, live                            |
+| `useChannelsLatest` | `{ [rid]: { ts, pl } }`, the last stored point, then live              |
+| `useChannelsSeries` | `{ [rid]: points }`, the last `windowSeconds`, oldest first, then live |
+
+The two channel hooks take two options:
+
+- `commitMs` collects live points and renders once per that many milliseconds.
+  Without it, every point renders as it arrives.
+- `onError(error, rid)` is called when a history read fails. The hooks report
+  nothing on their own.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@faybl/react-utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "React hooks for Faybl web apps",
+  "license": "TBD",
+  "author": "Arcturitech",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/arcturitech/faybl/utils/utils-js.git",
+    "directory": "packages/react-utils"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "dependencies": {
+    "@faybl/utils": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/commitBuffer.js

@@ -0,0 +1,38 @@
+/**
+ * Hands updates to `commit`, either one at a time as they are added or, with
+ * `intervalMs`, collected and together once per interval.
+ *
+ * `commit` receives the updates in the order they were added and is not called
+ * for an interval without any. After `stop`, pending and later updates are
+ * dropped.
+ */
+export const createCommitBuffer = ({ commit, intervalMs }) => {
+  /* eslint-disable functional/no-let -- Updates arriving between two commits must outlive the message callbacks that deliver them, and a stopped buffer must refuse reads that resolve after its component is gone. */
+  let pending = [];
+  let stopped = false;
+  /* eslint-enable functional/no-let */
+
+  const flush = () => {
+    if (pending.length === 0) return;
+    const updates = pending;
+    pending = [];
+    commit(updates);
+  };
+  const intervalId = intervalMs ? setInterval(flush, intervalMs) : undefined;
+
+  return {
+    add: (update) => {
+      if (stopped) return;
+      if (intervalId === undefined) {
+        commit([update]);
+        return;
+      }
+      pending = [...pending, update];
+    },
+    stop: () => {
+      stopped = true;
+      pending = [];
+      clearInterval(intervalId);
+    },
+  };
+};

package/src/idList.js

@@ -0,0 +1,10 @@
+const SEPARATOR = '|';
+
+/**
+ * A string that identifies a list of ids, for an effect's dependencies: a
+ * caller passing a new array with the same ids must not resubscribe. Empty
+ * entries and duplicates are dropped; an empty list gives ''.
+ */
+export const listKey = (ids = []) => [...new Set(ids.filter(Boolean))].join(SEPARATOR);
+
+export const keyList = (key) => (key ? key.split(SEPARATOR) : []);

package/src/index.js

@@ -0,0 +1,3 @@
+export { useChannelsLatest } from './useChannelsLatest.js';
+export { useChannelsSeries } from './useChannelsSeries.js';
+export { usePresence } from './usePresence.js';

package/src/point.js

@@ -0,0 +1,13 @@
+const timeOf = (point) => Date.parse(point?.ts);
+
+// A history read can resolve after a live message has arrived.
+export const newerPoint = (current, candidate) => {
+  if (!candidate) return current;
+  if (!current) return candidate;
+  return timeOf(candidate) >= timeOf(current) ? candidate : current;
+};
+
+export const mergeNewerPoint = (points, { rid, point }) => {
+  const next = newerPoint(points[rid], point);
+  return next === points[rid] ? points : { ...points, [rid]: next };
+};

package/src/series.js

@@ -0,0 +1,21 @@
+const timeOf = (point) => Date.parse(point.ts);
+
+const byTime = (left, right) => timeOf(left) - timeOf(right);
+
+// Points are kept oldest first. A live point normally belongs at the end.
+export const appendPoint = (point) => (points) => {
+  if (!point) return points;
+  const last = points.at(-1);
+  if (!last || timeOf(point) > timeOf(last)) return [...points, point];
+  if (points.some(({ ts }) => ts === point.ts)) return points;
+  return [...points, point].toSorted(byTime);
+};
+
+export const trimBefore = (fromMs) => (points) => {
+  const firstKept = points.findIndex((point) => timeOf(point) >= fromMs);
+  if (firstKept === 0) return points;
+  return firstKept === -1 ? [] : points.slice(firstKept);
+};
+
+export const mergeSeries = (history, live) =>
+  live.reduce((merged, point) => appendPoint(point)(merged), history);

package/src/useChannelsLatest.js

@@ -0,0 +1,57 @@
+import { fetchHistoryLast } from '@faybl/utils';
+import { useEffect, useEffectEvent, useState } from 'react';
+
+import { createCommitBuffer } from './commitBuffer.js';
+import { keyList, listKey } from './idList.js';
+import { mergeNewerPoint } from './point.js';
+
+const NO_POINTS = Object.freeze({});
+
+const applyAll = (updates) => (points) => updates.reduce(mergeNewerPoint, points);
+
+/**
+ * Latest `{ ts, pl }` per channel rid, as `{ [rid]: point }`.
+ *
+ * Reads the last stored point and then follows the channel live. The
+ * subscriptions exist only while the calling component is mounted.
+ * @param {object} params
+ * @param {object} params.client faybl-client
+ * @param {string[]} params.rids
+ * @param {number} [params.commitMs] Collect live points and render once per
+ *   this many milliseconds, instead of once per point
+ * @param {(error: Error, rid: string) => void} [params.onError] Called when
+ *   reading a channel's last point fails
+ */
+export const useChannelsLatest = ({ client, rids, commitMs, onError }) => {
+  const ridsKey = listKey(rids);
+  const [points, setPoints] = useState(NO_POINTS);
+  const reportError = useEffectEvent((error, rid) => onError?.(error, rid));
+
+  useEffect(() => {
+    if (!client || !ridsKey) return undefined;
+
+    const buffer = createCommitBuffer({
+      commit: (updates) => setPoints(applyAll(updates)),
+      intervalMs: commitMs,
+    });
+    const ridList = keyList(ridsKey);
+
+    const unsubscribers = ridList.map((rid) =>
+      client.channel.subscribe(rid, ({ data }) => buffer.add({ rid, point: data })),
+    );
+    ridList.forEach(async (rid) => {
+      try {
+        buffer.add({ rid, point: await fetchHistoryLast({ client, rid }) });
+      } catch (error) {
+        reportError(error, rid);
+      }
+    });
+
+    return () => {
+      buffer.stop();
+      unsubscribers.forEach((unsubscribe) => unsubscribe());
+    };
+  }, [client, ridsKey, commitMs]);
+
+  return points;
+};

package/src/useChannelsSeries.js

@@ -0,0 +1,79 @@
+import { fetchHistory } from '@faybl/utils';
+import { useEffect, useEffectEvent, useState } from 'react';
+
+import { createCommitBuffer } from './commitBuffer.js';
+import { keyList, listKey } from './idList.js';
+import { appendPoint, mergeSeries, trimBefore } from './series.js';
+
+const NO_SERIES = Object.freeze({});
+const NO_POINTS = Object.freeze([]);
+
+// Each update is `{ rid, change }`, where `change` maps the points of that channel.
+const applyAll = (updates, fromMs) => (series) =>
+  updates.reduce(
+    (changed, { rid, change }) => ({
+      ...changed,
+      [rid]: trimBefore(fromMs)(change(changed[rid] ?? NO_POINTS)),
+    }),
+    series,
+  );
+
+/**
+ * The last `windowSeconds` of each channel as stored, as `{ [rid]: points }`,
+ * oldest first.
+ *
+ * Reads the window from history and then follows the channels live. The
+ * subscriptions exist only while the calling component is mounted. With an
+ * empty list of rids nothing is read.
+ * @param {object} params
+ * @param {object} params.client faybl-client
+ * @param {string[]} params.rids
+ * @param {number} params.windowSeconds
+ * @param {number} [params.commitMs] Collect live points and render once per
+ *   this many milliseconds, instead of once per point
+ * @param {(error: Error, rid: string) => void} [params.onError] Called when
+ *   reading a channel's history fails
+ */
+export const useChannelsSeries = ({ client, rids, windowSeconds, commitMs, onError }) => {
+  const ridsKey = listKey(rids);
+  const requestKey = `${ridsKey}@${windowSeconds}`;
+  const [state, setState] = useState({ requestKey, series: NO_SERIES });
+  const reportError = useEffectEvent((error, rid) => onError?.(error, rid));
+
+  useEffect(() => {
+    if (!client || !ridsKey) return undefined;
+
+    const windowStartMs = () => Date.now() - windowSeconds * 1000;
+    const buffer = createCommitBuffer({
+      commit: (updates) => {
+        const change = applyAll(updates, windowStartMs());
+        setState((current) => ({
+          requestKey,
+          series: change(current.requestKey === requestKey ? current.series : NO_SERIES),
+        }));
+      },
+      intervalMs: commitMs,
+    });
+    const ridList = keyList(ridsKey);
+
+    const unsubscribers = ridList.map((rid) =>
+      client.channel.subscribe(rid, ({ data }) => buffer.add({ rid, change: appendPoint(data) })),
+    );
+    ridList.forEach(async (rid) => {
+      const from = new Date(windowStartMs()).toISOString();
+      try {
+        const { data = NO_POINTS } = await fetchHistory({ client, rid, from });
+        buffer.add({ rid, change: (live) => mergeSeries(data, live) });
+      } catch (error) {
+        reportError(error, rid);
+      }
+    });
+
+    return () => {
+      buffer.stop();
+      unsubscribers.forEach((unsubscribe) => unsubscribe());
+    };
+  }, [client, ridsKey, windowSeconds, requestKey, commitMs]);
+
+  return state.requestKey === requestKey ? state.series : NO_SERIES;
+};

package/src/usePresence.js

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react';
+
+import { keyList, listKey } from './idList.js';
+
+const NO_PRESENCE = Object.freeze({});
+
+/**
+ * Presence per identity, as `{ [identityId]: { ts, connected } }`.
+ *
+ * A thing logs in with its `id`, so that is its identity. The broker keeps the
+ * last presence message, which arrives right after subscribing. Nothing is
+ * subscribed without a client or ids.
+ * @param {object} params
+ * @param {object} params.client faybl-client
+ * @param {string[]} params.identityIds
+ */
+export const usePresence = ({ client, identityIds }) => {
+  const idsKey = listKey(identityIds);
+  const [presence, setPresence] = useState(NO_PRESENCE);
+
+  useEffect(() => {
+    if (!client || !idsKey) return undefined;
+    return client.presence.subscribe(keyList(idsKey), ({ identityId, data }) =>
+      setPresence((current) => ({ ...current, [identityId]: data })),
+    );
+  }, [client, idsKey]);
+
+  return presence;
+};