@uniflowed/hooks 0.0.0-alpha.4 → 0.0.0-alpha.41

package/events.js

@@ -0,0 +1,300 @@
+// @flow
+//
+// `@uniflowed/hooks/events`: a stream the server is pushing.
+//
+// One hook, and it is here rather than in `./channels.js` for a reason that
+// module's header states from the other side: what belongs there is a value
+// crossing the page's boundary that is *not* the server, because a request is
+// `@uniflowed/query`'s and `@uniflowed/fetch`'s and comes with caching, retry
+// and revalidation that a broadcast does not want. An event stream is the
+// server and has none of that either — there is no cache entry, nothing to
+// revalidate, and no request to repeat. It is a connection, which is a third
+// thing, so it is a third file.
+//
+// `@uniflowed/server/events` is the other end of it.
+//
+// # What the platform already does, and the one thing it does not
+//
+// `EventSource` reconnects. It backs off, it sends the last `id:` it saw back
+// as `Last-Event-ID`, and it needs no help — for as long as the server keeps
+// answering. There is exactly one case where it gives up permanently: a
+// response that is not a `200` with `content-type: text/event-stream`. Then it
+// fires `error`, moves to `CLOSED`, and never tries again. A deployment
+// restarting behind a load balancer answers `502` for a second or two, and
+// every open stream in every tab is dead until somebody reloads the page.
+//
+// That is the case this hook exists for. When the browser gives up, it opens a
+// new `EventSource` on a doubling delay; when the browser is retrying on its
+// own it stays out of the way, because two reconnection schedules on one
+// connection is worse than either.
+//
+// The other half is that none of the platform's reconnecting is visible. An
+// application that wants to draw "reconnecting…" cannot ask `EventSource`
+// anything but `readyState`, and only from an event handler. [`status`] is that
+// as state.
+//
+// # What a reconnection this hook makes cannot carry
+//
+// `Last-Event-ID`. The browser sends it on its *own* retry and there is no way
+// to set it on a new `EventSource` — the constructor takes a URL and one flag.
+// So [`lastEventId`] is handed back, and a stream that needs to resume puts it
+// in the URL itself:
+//
+//   const stream = useEventSource(`/api/feed?after=${cursor ?? ""}`);
+//
+// Written down rather than worked around: a hook that silently appended a query
+// parameter would be inventing a protocol on the application's behalf.
+//
+// # Before hydration
+//
+// `status` is `"idle"` on the server and on the client's first render, through
+// `useSupported` — see the reason there. Nothing is opened during a render; the
+// connection is made in an effect, so a prerender neither connects nor pretends
+// it did. `"idle"` rather than `"connecting"` because they are different facts
+// and only one of them is true: nothing has been attempted here.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "@uniflowed/react";
+
+import { useSupported } from "./browser.js";
+import { useStableCallback } from "./lifecycle.js";
+
+/**
+ * The part of `EventSource` this module uses.
+ *
+ * Declared here rather than taken from Flow's library definition, for the
+ * reason `./channels.js` gives about `BroadcastChannel`: the constructor is
+ * looked up at runtime and may be absent, so it has to be a value with a known
+ * constructor signature, and the listener is typed with the two fields that are
+ * read — which removes an `instanceof MessageEvent` whose name is not defined
+ * in every host these tests run in.
+ */
+type StreamEvent = { data?: mixed, lastEventId?: mixed, ... };
+
+declare class Stream {
+  constructor(url: string, options?: { withCredentials?: boolean, ... }): void;
+  readonly readyState: number;
+  close(): void;
+  addEventListener(type: string, listener: (event: StreamEvent) => mixed): void;
+  removeEventListener(type: string, listener: (event: StreamEvent) => mixed): void;
+}
+
+/**
+ * `EventSource`, which is the host's rather than the document's.
+ *
+ * The same split `./channels.js` describes: in a browser the two are one
+ * object, and in a process where a document has been installed onto another
+ * runtime's global they are not — an event stream is a facility of the runtime,
+ * and a hosted `Window` is not required to carry one.
+ */
+declare var EventSource: Class<Stream> | void;
+
+function streamConstructor(): Class<Stream> | null {
+  return typeof EventSource === "undefined" ? null : (EventSource ?? null);
+}
+
+/** `EventSource.CLOSED`, spelled as the number so no global is read for it. */
+const CLOSED = 2;
+
+/** Where the connection is. */
+export type EventStreamStatus =
+  /** Nothing has been attempted: a prerender, no URL, or `enabled: false`. */
+  | "idle"
+  /** Opening, or reopening — by the browser or by this hook. */
+  | "connecting"
+  /** Receiving. */
+  | "open"
+  /** Closed on purpose, by `close()`. It will not reopen on its own. */
+  | "closed";
+
+/** One message, as the three fields the format carries. */
+export type ServerEvent = {|
+  /** The `event:` name, or `message` where the stream sent none. */
+  readonly name: string,
+  /** The `data:` payload, as text. */
+  readonly data: string,
+  /** The `id:`, or `null`. */
+  readonly id: string | null,
+|};
+
+/** How the connection behaves. */
+export type EventSourceOptions = {|
+  /**
+   * Named events to listen for, besides the unnamed `message`.
+   *
+   * A stream that sends `event: progress` delivers nothing to a `message`
+   * listener, which is the single most common way an event stream appears to
+   * be connected and silent.
+   */
+  readonly events?: $ReadOnlyArray<string>,
+  /** Send cookies to another origin. Same-origin streams do not need it. */
+  readonly withCredentials?: boolean,
+  /** `false` closes the connection and opens none; `null` for the URL does too. */
+  readonly enabled?: boolean,
+  /** Called for every event, for a stream whose messages are events. */
+  readonly onEvent?: (event: ServerEvent) => mixed,
+  /** Milliseconds before this hook's first reopen; doubles. Default 1000. */
+  readonly retryDelay?: number,
+  /** The ceiling the doubling stops at. Default 30000. */
+  readonly maxRetryDelay?: number,
+|};
+
+/** What `useEventSource` hands back. */
+export type UseEventSourceReturn = {|
+  readonly status: EventStreamStatus,
+  /**
+   * The most recent event, or `null` before one arrives.
+   *
+   * `./channels.js` deliberately does not hand back the last broadcast, and
+   * the argument there is that a message is an event: a tab that just opened
+   * has never received one and cannot ask. A stream is not that. It is a
+   * connection with a lifetime, and for as long as it is open "the latest
+   * message" is defined — which is what a progress bar, a price and a presence
+   * indicator all are. `onEvent` is there for the streams that really are
+   * events.
+   */
+  readonly last: ServerEvent | null,
+  /**
+   * The last `id:` seen, for a stream that resumes.
+   *
+   * The browser sends this itself when *it* reconnects. It is here for the
+   * reconnection this hook makes, which cannot; see the module header.
+   */
+  readonly lastEventId: string | null,
+  /** Close it. Nothing reopens until `enabled` or the URL changes. */
+  readonly close: () => void,
+  /** Whether this runtime has `EventSource` at all. */
+  readonly supported: boolean,
+|};
+
+const DEFAULT_RETRY = 1_000;
+const DEFAULT_MAX_RETRY = 30_000;
+
+/**
+ * Subscribe to a server-sent event stream.
+ *
+ * `url` is re-read when it changes, and a changed URL is a new connection —
+ * which is what makes the resume in the module header work at all. Pass `null`
+ * to connect to nothing, which is how a stream that depends on something not
+ * loaded yet waits without a second hook.
+ */
+export hook useEventSource(url: string | null, options?: EventSourceOptions): UseEventSourceReturn {
+  const supported = useSupported(() => streamConstructor() != null);
+  const [status, setStatus] = useState<EventStreamStatus>("idle");
+  const [last, setLast] = useState<ServerEvent | null>(null);
+  const [lastEventId, setLastEventId] = useState<string | null>(null);
+  // Bumped to ask for a new connection, which is the only thing that can
+  // reopen one the browser has given up on: `EventSource` in `CLOSED` cannot
+  // be restarted, so the effect has to run again with a new object.
+  const [attempt, setAttempt] = useState(0);
+  const [stopped, setStopped] = useState(false);
+
+  const onEvent = options?.onEvent;
+  const stable = useStableCallback((event: ServerEvent) => {
+    onEvent?.(event);
+  });
+
+  // The names are carried as one string rather than as the array the caller
+  // passed, and rebuilt inside the effect from it. An array literal in a
+  // render is a new array every time, so depending on one would tear the
+  // connection down on every keystroke anywhere in the component — and a ref
+  // written during a render is the other way to get this wrong, which this
+  // package's header rules out.
+  const key = (options?.events ?? []).join(",");
+  const withCredentials = options?.withCredentials === true;
+  const retryDelay = options?.retryDelay ?? DEFAULT_RETRY;
+  const maxRetryDelay = options?.maxRetryDelay ?? DEFAULT_MAX_RETRY;
+  // How many times *this hook* has reopened since the last success. Not
+  // `attempt`, which also moves for a URL change, and not state, because
+  // resetting it on `open` must not be a render.
+  const backoff = useRef(0);
+
+  const enabled = (options?.enabled ?? true) && !stopped;
+
+  useEffect(() => {
+    const Constructor = streamConstructor();
+    if (Constructor == null || url == null || !enabled) {
+      // The connection state mirrors whether the external stream exists.
+      // uf-lint-disable-next-line react-compiler/set-state-in-effect
+      setStatus(stopped ? "closed" : "idle");
+      return;
+    }
+
+    const source = new Constructor(url, { withCredentials });
+    setStatus("connecting");
+    let reopen: TimeoutID | null = null;
+
+    const onOpen = () => {
+      // The delay is reset here rather than on the first message: a stream
+      // that connects and sends nothing for an hour has still connected, and
+      // treating it as a failure would put the next real outage at the top of
+      // the backoff.
+      backoff.current = 0;
+      setStatus("open");
+    };
+
+    const onMessage = (name: string) => (event: StreamEvent) => {
+      const sent = event.lastEventId;
+      const id = typeof sent === "string" && sent !== "" ? sent : null;
+      const received: ServerEvent = { name, data: String(event.data ?? ""), id };
+      setLast(received);
+      if (id != null) {
+        setLastEventId(id);
+      }
+      stable(received);
+    };
+
+    const onError = () => {
+      if (source.readyState !== CLOSED) {
+        // The browser is retrying on its own, with `Last-Event-ID`, which is
+        // strictly better than anything this hook can do. Say so and wait.
+        setStatus("connecting");
+        return;
+      }
+      // It has given up — a non-200, or a body that was not an event stream.
+      // Nothing reopens this object, so a new one is asked for on a delay.
+      setStatus("connecting");
+      const wait = Math.min(retryDelay * 2 ** backoff.current, maxRetryDelay);
+      backoff.current += 1;
+      reopen = setTimeout(() => setAttempt((count) => count + 1), wait);
+    };
+
+    const listeners: Array<[string, (event: StreamEvent) => mixed]> = [
+      ["message", onMessage("message")],
+    ];
+    for (const name of key === "" ? [] : key.split(",")) {
+      listeners.push([name, onMessage(name)]);
+    }
+
+    source.addEventListener("open", onOpen);
+    source.addEventListener("error", onError);
+    for (const [name, listener] of listeners) {
+      source.addEventListener(name, listener);
+    }
+
+    return () => {
+      if (reopen != null) {
+        clearTimeout(reopen);
+      }
+      source.removeEventListener("open", onOpen);
+      source.removeEventListener("error", onError);
+      for (const [name, listener] of listeners) {
+        source.removeEventListener(name, listener);
+      }
+      // Closed as well as unsubscribed: an `EventSource` nobody is listening
+      // to still holds a connection and still reconnects, so leaving it open
+      // is a socket per navigation for the life of the tab.
+      source.close();
+    };
+    // `key` stands in for `options.events`, and `attempt` is what a reopen
+    // moves. `backoff` is a ref, and `stable` never changes identity.
+  }, [url, enabled, stopped, key, attempt, retryDelay, maxRetryDelay, withCredentials, stable]);
+
+  const close = useCallback(() => {
+    setStopped(true);
+  }, []);
+
+  return useMemo(
+    () => ({ status, last, lastEventId, close, supported }),
+    [status, last, lastEventId, close, supported],
+  );
+}

package/index.js

@@ -2,11 +2,22 @@
 //
 // `@uniflowed/hooks`: the hooks a React application writes anyway.
 //
-// Not a large collection. Every hook here is one that people write by hand in
-// every project and get subtly wrong in the same way each time — a timer that
-// calls a stale closure, a subscription re-established on every keystroke, a
-// slow request overwriting a fast one, persisted state that differs between the
-// server render and the first paint.
+// Every hook here is one that people write by hand in every project and get
+// subtly wrong in the same way each time — a timer that calls a stale closure,
+// a subscription re-established on every keystroke, a slow request overwriting
+// a fast one, persisted state that differs between the server render and the
+// first paint, a shortcut that fires while somebody is typing, a dialog that
+// unlocks the page while a second dialog is still open.
+//
+// VueUse is the benchmark, and most of what it offers is not here on purpose.
+// Its `Reactivity`, `Watch` and `Array` categories exist because Vue's `ref`
+// is a mutable box that has to be wrapped, unwrapped, synced and derived;
+// React has no box, and `useMemo` over a plain array is the whole of
+// `useArrayFilter`. Its `Component` category is Vue's template machinery —
+// `templateRef`, `unrefElement`, `useVModel` — which is `ref` and props here.
+// Porting either would have produced hooks whose only purpose was to look
+// familiar. The "Readiness" section below says what is here, what is
+// deliberately elsewhere in uf, and what is simply not built.
 //
 // # Prerendering is the constraint that shapes the surface
 //
@@ -21,23 +32,61 @@
 // its sidebar under 48rem wants `false` on the server and one that renders a
 // mobile menu wants `true`, and a library cannot know which.
 //
+// Where there is exactly one honest answer, the caller is not asked. `useHash`
+// takes no server value because the browser strips the fragment before the
+// request goes out, so `""` is not a default standing in for something better —
+// it is what the server knows, and offering an override would have invited a
+// caller to state a value that cannot be true.
+//
+// The hooks built on effects rather than stores — everything in `dom.js`, and
+// the three in `browser.js` whose first value only arrives in a callback — do
+// nothing at all before hydration, and report the same starting value on both
+// sides for that reason. Each module's header says which it is and why.
+//
+// # React's rules are the design, not a constraint on it
+//
+// Nothing here writes during a render, reads a ref during a render, or depends
+// on a render having happened exactly once. Callbacks that cross into effects
+// go through `useStableCallback`, whose ref is written in an insertion effect
+// rather than in the body, so Strict Mode's double render and a render the
+// React Compiler skips are both correct. Every effect's cleanup removes
+// exactly what its body added, which is what makes Strict Mode's
+// mount-unmount-mount balanced — including the module-level counters behind
+// `useScrollLock` and `useStorage`.
+//
 // # How the package is laid out
 //
-// Six modules beside this one, split by what a hook's subject is — because
+// Nine modules beside this one, split by what a hook's subject is — because
 // that is the question a reader looking for one actually asks:
 //
 // - `lifecycle.js` — the component itself: mounted, previous, run once.
-// - `state.js` — a value the component owns, with the operations that suit it.
+// - `state.js` — a value the component owns, with the operations that suit it:
+//   toggle, counter, list, set, cycle, undo/redo, storage.
 // - `timing.js` — when something runs: intervals, timeouts, debounce,
-//   throttle.
-// - `async.js` — one promise, and the stale-response bug.
-// - `browser.js` — the ambient environment: viewport, connection, preferences.
+//   throttle, frames, idleness, and the clock behind "3 minutes ago".
+// - `render.js` — what a render has to fix rather than derive: the instant it
+//   was made at, and the seed anything random on the page is drawn from.
+// - `async.js` — one promise: its states, its abort signal, its retries.
+// - `browser.js` — the ambient environment: viewport, scroll, connection,
+//   position, permissions, preferences, the fragment in the address bar. Its
+//   header carries the table of what every one of them renders before
+//   hydration.
 // - `dom.js` — one element the caller holds a ref to: listen, measure,
-//   observe.
+//   observe, press.
+// - `keyboard.js` — what is being pressed: a chord, and a held key.
+// - `channels.js` — a value that came from outside the page: another tab, the
+//   system clipboard.
+// - `events.js` — a stream the server is pushing, and where its reconnection
+//   is. Not `channels.js`, whose boundary is deliberately everything except
+//   the server, and not `@uniflowed/query`, because there is no cache entry
+//   and nothing to revalidate: a connection is a third thing.
 //
-// The two that are easiest to confuse are the last two, so each says so in its
-// own header: `browser.js` needs no ref because there is one browser, and
-// `dom.js` needs one because there are as many answers as there are elements.
+// The two that are easiest to confuse are `browser.js` and `dom.js`, so each
+// says so in its own header: `browser.js` needs no ref because there is one
+// browser, and `dom.js` needs one because there are as many answers as there
+// are elements. `keyboard.js` is neither, which is why it is a third file
+// rather than a corner of one of them, and its header says what the four hard
+// parts of a shortcut are.
 //
 // They sit here rather than under an `internal/`, and each has its own
 // subpath. Every name in them is exported from this file, so calling them
@@ -45,12 +94,82 @@
 // hop to reach the first line of code. `internal/` is for a module consumers
 // must not reach; this package has none.
 //
-// `lifecycle.js` is the one the others import — `timing.js`, `state.js` and
-// `dom.js` all want `useStableCallback` — and it is still a subject rather
-// than a bag of shared helpers. A hook goes there because it is about the
-// component's life, not because more than one file wanted it.
+// `lifecycle.js` and `browser.js` are the two the others import —
+// `useStableCallback` and `browserWindow` — and both are still subjects rather
+// than bags of shared helpers. A hook goes in `lifecycle.js` because it is
+// about the component's life, never because more than one file wanted it.
+//
+// # Readiness
+//
+// **Implemented and tested.** The component's life; the state shapes; every
+// timer, including the adaptive schedule behind `useTimeAgo`; `useAsync` with
+// abort and retry; media queries, colour scheme, reduced motion, online,
+// document visibility, window size and scroll, the address bar's fragment,
+// scroll lock; element size,
+// intersection, mutations, hover, focus-within, click-outside, long press,
+// element scroll, the element as state; key chords and held keys; storage with
+// cross-tab sync;
+// broadcast channels; the clipboard; a server-sent event stream, including the
+// one case the platform's own reconnection gives up on; the render anchor and
+// the seeded stream in `render.js`. `packages/hooks/hooks.test.js` covers
+// behaviour and cleanup, and `packages/hooks/hooks-ssr.test.js` renders the
+// whole surface in a process that has no DOM at all.
+//
+// **Experimental.** `useGeolocation`, `useNetwork` and `usePermission`. The
+// shapes are settled and the cleanup is right, but the browsers disagree about
+// them more than the rest of this package does: Network Information is
+// Chromium's alone, the Permissions API rejects rather than answers for names
+// it does not know, and geolocation cannot be exercised end to end in a
+// headless document — the tests cover the unsupported path, the subscription
+// and its teardown, not a real fix. Treat the fields as advisory.
+//
+// **Not implemented, and not planned here.** Everything whose subject is
+// somewhere else in uf: a request with a cache is `@uniflowed/query`, a form
+// field is `@uniflowed/form`, an atom two routes read is `@uniflowed/state`, a
+// rendered instant is `@uniflowed/web`'s `Time`, styling and dark mode are
+// `@uniflowed/stylex`, and a virtual list or an infinite scroller is
+// `@uniflowed/ui`. Beyond those: the device APIs VueUse wraps that a general
+// application does not reach for — Bluetooth, gamepads, USB, speech, wake
+// lock, screen capture, web workers, battery, vibration — are absent rather
+// than shallow. A wrapper over one of those is three lines and a `supported`
+// flag; what makes it worth shipping is knowing the failure modes, and this
+// package does not yet.
 
-export type { Async } from "./async.js";
+export type { Async, AsyncOptions } from "./async.js";
+export type {
+  BrowserHistory,
+  BrowserLocation,
+  BrowserNavigator,
+  BrowserWindow,
+  EffectiveConnectionType,
+  GeolocationReading,
+  Geoposition,
+  Network,
+  NetworkConnection,
+  NetworkMeasurement,
+  PermissionAnswer,
+  PermissionName,
+  ScrollOffset,
+  Size,
+} from "./browser.js";
+export type { UseBroadcastReturn, UseClipboardReturn } from "./channels.js";
+export type { ListenerOptions, ListenerTarget, MutationOptions, Ref } from "./dom.js";
+export type {
+  EventSourceOptions,
+  EventStreamStatus,
+  ServerEvent,
+  UseEventSourceReturn,
+} from "./events.js";
+export type { KeyComboOptions } from "./keyboard.js";
+export type { RenderEnvelope } from "./render.js";
+export type {
+  UseCounterReturn,
+  UseCycleReturn,
+  UseListReturn,
+  UseSetReturn,
+  UseToggleReturn,
+  UseUndoableReturn,
+} from "./state.js";
 
 export { useAsync } from "./async.js";
 export {
@@ -63,27 +182,63 @@ export {
   useUnmount,
 } from "./lifecycle.js";
 export {
+  useAnimationFrame,
   useDebouncedCallback,
   useDebouncedValue,
+  useIdle,
   useInterval,
+  useNow,
   useThrottledCallback,
+  useTimeAgo,
   useTimeout,
 } from "./timing.js";
 export {
+  browserWindow,
   useDocumentVisible,
+  useGeolocation,
+  useHash,
   useMediaQuery,
+  useNetwork,
   useOnline,
-  usePrefersReducedMotion,
+  usePermission,
   usePreferredColorScheme,
+  usePrefersReducedMotion,
+  useScrollLock,
+  useSupported,
+  useWindowScroll,
   useWindowSize,
 } from "./browser.js";
 export {
   useClickOutside,
   useElementRef,
   useElementSize,
+  useElementState,
   useEventListener,
   useFocusWithin,
   useHover,
   useIntersecting,
+  useLongPress,
+  useMutationObserver,
+  useScroll,
 } from "./dom.js";
-export { useCounter, useStorage, useToggle } from "./state.js";
+export { useKeyCombo, useKeyHeld } from "./keyboard.js";
+export {
+  RENDER_META,
+  RenderProvider,
+  useRandom,
+  useRenderEnvelope,
+  useRenderTimeZone,
+  useRenderedAt,
+  useShuffled,
+} from "./render.js";
+export { useBroadcast, useClipboard } from "./channels.js";
+export { useEventSource } from "./events.js";
+export {
+  useCounter,
+  useCycle,
+  useList,
+  useSet,
+  useStorage,
+  useToggle,
+  useUndoable,
+} from "./state.js";