steddy 0.1.1 → 0.1.3

package/README.md

@@ -10,6 +10,34 @@ Explainer: [https://cincinnatus101010.github.io/steddyweb/](https://cincinnatus1
 npm install steddy
 ```
 
+## App root
+
+Wire an isolated runtime once. On the server, create a **new** runtime per request — do not rely on the module singleton.
+
+```tsx
+import { useEffect } from "react";
+import {
+  attachDefaults,
+  createRuntime,
+  SteddyProvider,
+} from "steddy";
+
+const runtime = createRuntime();
+
+export function AppProviders({ children }: { children: React.ReactNode }) {
+  useEffect(() => attachDefaults(runtime.coordinator, runtime.store), []);
+  return (
+    <SteddyProvider store={runtime.store} coordinator={runtime.coordinator}>
+      {children}
+    </SteddyProvider>
+  );
+}
+```
+
+For Next.js / RSC: fetch on the server, `dump(runtime.store)`, pass `cache={payload}` into `SteddyProvider` on the client. `hydrateAll` preserves timestamps from `dump` so dedup can skip an immediate refetch.
+
+## Hook
+
 ```ts
 import { useSteddy } from "steddy";
 
@@ -21,6 +49,7 @@ function Profile({ id }: { id: string }) {
       if (!response.ok) throw new Error("failed");
       return response.json();
     },
+    { keepPreviousData: true, staleTime: 60_000 },
   );
 
   if (error) return <p>Failed to load</p>;
@@ -35,17 +64,39 @@ function Profile({ id }: { id: string }) {
 }
 ```
 
-`key === null` skips fetching. Plugins (`focusRevalidate`, `reconnectRevalidate`, `pollingRevalidate`, `retryOnError`) are opt-in named exports.
+`key === null` skips fetching. Options: `{ suspense: true }`, `{ keepPreviousData: true }`, `{ staleTime }` (default 2000ms dedup window).
+
+## Helpers
 
 ```ts
-import { defaultCoordinator, focusRevalidate, hydrate, clear } from "steddy";
+import {
+  createRuntime,
+  dump,
+  hydrateAll,
+  prefetch,
+  clear,
+} from "steddy";
+
+// Route loader / link hover — no mounted hook required
+await prefetch(["user", id], fetchUser, runtime);
+
+clear("user", runtime);
+```
+
+## Plugins (opt-in)
 
-hydrate("user", { name: "Ada" });
-focusRevalidate(defaultCoordinator);
-clear("user");
+```ts
+import { attachDefaults, focusRevalidate, measurePerf } from "steddy";
+
+// Or wire individually — pass store so focus/reconnect only hit subscribed keys
+focusRevalidate(coordinator, store);
+
+const perf = measurePerf(coordinator);
 ```
 
-Need an isolated cache (tests, multiple trees, SSR): wrap with `SteddyProvider` and pass `createStore()` + `createCoordinator(store)`, or `createRuntime()`. Pass `cache={dump(store)}` across an RSC boundary. `{ suspense: true }` throws the in-flight waiter. `{ keepPreviousData: true }` keeps the last value on screen while a new key loads. `useSteddyInfinite` keeps one cache entry per page; `mutate` writes every page, and `getKey` stops when a later page would reuse an earlier key. `ttlEvict` drops unused keys.
+Also: `reconnectRevalidate`, `pollingRevalidate`, `retryOnError` (fetcher wrapper), `ttlEvict`, `useSteddyInfinite`.
+
+`measurePerf(coordinator)` returns `{ starts, aborts, dedups, writes, errors, totalMs }`. Run `npm run bench` for coordinator microbenchmarks.
 
 ## Architecture
 

package/dist/index.cjs

@@ -8,6 +8,9 @@ var jsxRuntime = require('react/jsx-runtime');
 // src/coordinator.ts
 var DEDUP_WINDOW_MS = 2e3;
 var UNSUBSCRIBE_GRACE_MS = 0;
+function now() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
 function isAbortError(error) {
   return typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
 }
@@ -15,7 +18,16 @@ function createCoordinator(store) {
   const registered = /* @__PURE__ */ new Map();
   const inflight = /* @__PURE__ */ new Map();
   const releaseTimers = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
   let generation = 0;
+  function emit(event) {
+    if (listeners.size === 0) {
+      return;
+    }
+    for (const listener of listeners) {
+      listener(event);
+    }
+  }
   function cancelRelease(serializedKey) {
     const timer = releaseTimers.get(serializedKey);
     if (timer == null) {
@@ -29,6 +41,11 @@ function createCoordinator(store) {
     if (!current) {
       return;
     }
+    emit({
+      type: "abort",
+      key: serializedKey,
+      ms: now() - current.startedAt
+    });
     current.controller.abort();
     current.settle();
     inflight.delete(serializedKey);
@@ -40,9 +57,13 @@ function createCoordinator(store) {
     }
   }
   const coordinator = {
-    register(serializedKey, key, fetcher) {
+    register(serializedKey, key, fetcher, options) {
       cancelRelease(serializedKey);
-      registered.set(serializedKey, { key, fetcher });
+      registered.set(serializedKey, {
+        key,
+        fetcher,
+        staleTime: options?.staleTime ?? DEDUP_WINDOW_MS
+      });
     },
     unregister(serializedKey) {
       cancelRelease(serializedKey);
@@ -63,7 +84,9 @@ function createCoordinator(store) {
     async revalidate(serializedKey, fetcher, options) {
       if (!options?.force) {
         const entry = store.get(serializedKey);
-        if (entry && !entry.isValidating && entry.error == null && entry.data !== void 0 && Date.now() - entry.timestamp < DEDUP_WINDOW_MS) {
+        const staleTime = registered.get(serializedKey)?.staleTime ?? DEDUP_WINDOW_MS;
+        if (entry && !entry.isValidating && entry.error == null && entry.hasData && Date.now() - entry.timestamp < staleTime) {
+          emit({ type: "dedup", key: serializedKey });
           return;
         }
       }
@@ -87,15 +110,19 @@ function createCoordinator(store) {
           settleWaiter();
         }
       };
+      const startedAt = now();
       inflight.set(serializedKey, {
         controller,
         generation: currentGeneration,
         waiter,
-        settle
+        settle,
+        startedAt
       });
+      emit({ type: "start", key: serializedKey });
       const previous = store.get(serializedKey);
       store.set(serializedKey, {
         data: previous?.data,
+        hasData: previous?.hasData ?? false,
         error: previous?.error,
         timestamp: previous?.timestamp ?? 0,
         isValidating: true
@@ -109,10 +136,16 @@ function createCoordinator(store) {
         inflight.delete(serializedKey);
         store.set(serializedKey, {
           data,
+          hasData: true,
           error: void 0,
           timestamp: Date.now(),
           isValidating: false
         });
+        emit({
+          type: "write",
+          key: serializedKey,
+          ms: now() - startedAt
+        });
       } catch (error) {
         const stillCurrent = inflight.get(serializedKey)?.generation === currentGeneration;
         if (!stillCurrent || controller.signal.aborted || isAbortError(error)) {
@@ -122,10 +155,16 @@ function createCoordinator(store) {
         const current = store.get(serializedKey);
         store.set(serializedKey, {
           data: current?.data,
+          hasData: current?.hasData ?? false,
           error,
           timestamp: current?.timestamp ?? 0,
           isValidating: false
         });
+        emit({
+          type: "error",
+          key: serializedKey,
+          ms: now() - startedAt
+        });
         throw error;
       } finally {
         settle();
@@ -145,7 +184,7 @@ function createCoordinator(store) {
       abortInternal(serializedKey, true);
     },
     evict(options) {
-      const now = Date.now();
+      const now2 = Date.now();
       const removable = [];
       for (const key of store.keys()) {
         if (inflight.has(key) || store.subscriberCount(key) > 0) {
@@ -160,7 +199,7 @@ function createCoordinator(store) {
       const victims = /* @__PURE__ */ new Set();
       if (options.maxAge != null) {
         for (const item of removable) {
-          if (now - item.timestamp >= options.maxAge) {
+          if (now2 - item.timestamp >= options.maxAge) {
             victims.add(item.key);
           }
         }
@@ -195,6 +234,12 @@ function createCoordinator(store) {
         abortInternal(key, false);
       }
       registered.clear();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
     }
   };
   return coordinator;
@@ -203,6 +248,7 @@ function createCoordinator(store) {
 // src/store.ts
 var EMPTY_SNAPSHOT = Object.freeze({
   data: void 0,
+  hasData: false,
   error: void 0,
   timestamp: 0,
   isValidating: false
@@ -224,6 +270,10 @@ function createStore() {
       return entries.get(key);
     },
     set(key, entry) {
+      const existing = entries.get(key);
+      if (existing && Object.is(existing.data, entry.data) && existing.hasData === entry.hasData && existing.error === entry.error && existing.timestamp === entry.timestamp && existing.isValidating === entry.isValidating) {
+        return;
+      }
       entries.set(key, entry);
       emit(key);
     },
@@ -325,6 +375,7 @@ function createMutate(store, coordinator) {
       if (isThenable(next)) {
         store.set(serialized, {
           data: currentData,
+          hasData: previous?.hasData ?? false,
           error: previous?.error,
           timestamp: previous?.timestamp ?? 0,
           isValidating: true
@@ -332,6 +383,7 @@ function createMutate(store, coordinator) {
         const resolved = await next;
         store.set(serialized, {
           data: resolved,
+          hasData: true,
           error: void 0,
           timestamp: Date.now(),
           isValidating: revalidate
@@ -339,6 +391,7 @@ function createMutate(store, coordinator) {
       } else {
         store.set(serialized, {
           data: next,
+          hasData: true,
           error: void 0,
           timestamp: Date.now(),
           isValidating: revalidate
@@ -355,6 +408,7 @@ function createMutate(store, coordinator) {
         const current = store.get(serialized);
         store.set(serialized, {
           data: current?.data,
+          hasData: current?.hasData ?? false,
           error,
           timestamp: current?.timestamp ?? Date.now(),
           isValidating: false
@@ -386,24 +440,44 @@ function SteddyProvider({
   cache,
   children
 }) {
-  const value = react.useMemo(() => {
-    if (cache) {
-      hydrateAll(cache, store);
+  const hydratedFingerprint = react.useRef(null);
+  react.useEffect(() => {
+    if (!cache) {
+      hydratedFingerprint.current = null;
+      return;
+    }
+    const fingerprint = JSON.stringify(cache);
+    if (hydratedFingerprint.current === fingerprint) {
+      return;
     }
-    return {
+    hydratedFingerprint.current = fingerprint;
+    hydrateAll(cache, store);
+  }, [cache, store]);
+  const value = react.useMemo(
+    () => ({
       store,
       coordinator,
       mutate: createMutate(store, coordinator)
-    };
-  }, [store, coordinator, cache]);
+    }),
+    [store, coordinator]
+  );
   return /* @__PURE__ */ jsxRuntime.jsx(SteddyContext.Provider, { value, children });
 }
+var warnedDefaultOnServer = false;
 function useSteddyRuntime() {
-  return react.useContext(SteddyContext);
+  const runtime = react.useContext(SteddyContext);
+  if (process.env.NODE_ENV !== "production" && typeof window === "undefined" && runtime === defaultRuntime && !warnedDefaultOnServer) {
+    warnedDefaultOnServer = true;
+    console.warn(
+      "[steddy] useSteddy on the server without SteddyProvider shares one cache across requests. Use createRuntime() per request."
+    );
+  }
+  return runtime;
 }
 function hydrate(key, data, store = defaultStore) {
   store.set(serializeKey(key), {
     data,
+    hasData: true,
     error: void 0,
     timestamp: 0,
     isValidating: false
@@ -413,7 +487,7 @@ function dump(store = defaultStore) {
   const snapshot = {};
   for (const key of store.keys()) {
     const entry = store.get(key);
-    if (!entry || entry.data === void 0) {
+    if (!entry?.hasData) {
       continue;
     }
     snapshot[key] = { data: entry.data, timestamp: entry.timestamp };
@@ -424,12 +498,23 @@ function hydrateAll(snapshot, store = defaultStore) {
   for (const [key, payload] of Object.entries(snapshot)) {
     store.set(key, {
       data: payload.data,
+      hasData: true,
       error: void 0,
-      timestamp: 0,
+      timestamp: payload.timestamp,
       isValidating: false
     });
   }
 }
+async function prefetch(key, fetcher, runtime = defaultRuntime) {
+  const serialized = serializeKey(key);
+  runtime.coordinator.register(serialized, key, fetcher);
+  try {
+    await runtime.coordinator.revalidate(serialized);
+  } catch {
+  } finally {
+    runtime.coordinator.unregister(serialized);
+  }
+}
 function clear(key, runtime = defaultRuntime) {
   if (key === void 0) {
     for (const active of runtime.coordinator.getRegisteredKeys()) {
@@ -468,11 +553,15 @@ function useSteddy(key, fetcher, options) {
   fetcherRef.current = fetcher;
   const keyRef = react.useRef(key);
   keyRef.current = key;
+  const staleTime = options?.staleTime ?? DEDUP_WINDOW_MS;
+  const staleTimeRef = react.useRef(staleTime);
+  staleTimeRef.current = staleTime;
   if (serialized != null && key != null) {
     coordinator.register(
       serialized,
       key,
-      (k, ctx) => fetcherRef.current(k, ctx)
+      (k, ctx) => fetcherRef.current(k, ctx),
+      { staleTime: staleTimeRef.current }
     );
   }
   const subscribe = react.useCallback(
@@ -485,7 +574,8 @@ function useSteddy(key, fetcher, options) {
       coordinator.register(
         serialized,
         originalKey,
-        (k, ctx) => fetcherRef.current(k, ctx)
+        (k, ctx) => fetcherRef.current(k, ctx),
+        { staleTime: staleTimeRef.current }
       );
       const unsubscribe = store.subscribe(serialized, onStoreChange);
       if (!coordinator.isInFlight(serialized)) {
@@ -521,15 +611,15 @@ function useSteddy(key, fetcher, options) {
   const previousRef = react.useRef(
     void 0
   );
-  if (serialized != null && snapshot.data !== void 0) {
+  if (serialized != null && snapshot.hasData) {
     previousRef.current = { serialized, data: snapshot.data };
   }
-  const data = keepPreviousData && serialized != null && snapshot.data === void 0 && snapshot.error == null && previousRef.current != null && previousRef.current.serialized !== serialized ? previousRef.current.data : snapshot.data;
+  const data = keepPreviousData && serialized != null && !snapshot.hasData && snapshot.error == null && previousRef.current != null && previousRef.current.serialized !== serialized ? previousRef.current.data : snapshot.data;
   if (options?.suspense && serialized != null) {
     if (snapshot.error != null) {
       throw snapshot.error;
     }
-    if (snapshot.data === void 0 && data === void 0) {
+    if (!snapshot.hasData && data === void 0) {
       const waiter = coordinator.getInFlightPromise(serialized) ?? coordinator.revalidate(serialized).catch(() => {
       });
       throw waiter;
@@ -538,7 +628,7 @@ function useSteddy(key, fetcher, options) {
   return {
     data,
     error: snapshot.error,
-    isLoading: serialized != null && data === void 0 && snapshot.error == null,
+    isLoading: serialized != null && !snapshot.hasData && snapshot.error == null && data === void 0,
     isValidating: snapshot.isValidating,
     mutate: boundMutate
   };
@@ -629,7 +719,7 @@ function useSteddyInfinite(getKey, fetcher, options) {
     );
     const fingerprint = currentPages.map((page) => {
       const entry = store.getSnapshot(page.serialized);
-      return `${page.serialized}:${entry.timestamp}:${entry.isValidating ? 1 : 0}:${entry.error == null ? 0 : 1}:${entry.data === void 0 ? 0 : 1}`;
+      return `${page.serialized}:${entry.timestamp}:${entry.isValidating ? 1 : 0}:${entry.error == null ? 0 : 1}:${entry.hasData ? 1 : 0}`;
     }).join("|");
     if (snapshotRef.current.fingerprint === fingerprint) {
       return snapshotRef.current;
@@ -646,7 +736,7 @@ function useSteddyInfinite(getKey, fetcher, options) {
       if (entry.error != null && error === void 0) {
         error = entry.error;
       }
-      if (entry.data === void 0) {
+      if (!entry.hasData) {
         missing = true;
         break;
       }
@@ -713,6 +803,7 @@ function useSteddyInfinite(getKey, fetcher, options) {
           }
           store.set(page.serialized, {
             data: pagesValue[index],
+            hasData: true,
             error: void 0,
             timestamp: Date.now(),
             isValidating: revalidate
@@ -742,7 +833,7 @@ function useSteddyInfinite(getKey, fetcher, options) {
   return {
     data: snapshot.data,
     error: snapshot.error,
-    isLoading: first != null && firstEntry?.data === void 0 && firstEntry?.error == null,
+    isLoading: first != null && !firstEntry?.hasData && firstEntry?.error == null,
     isValidating: snapshot.isValidating,
     size,
     setSize,
@@ -750,23 +841,37 @@ function useSteddyInfinite(getKey, fetcher, options) {
   };
 }
 
+// src/plugins/subscribedKeys.ts
+function keysWithSubscribers(keys, store) {
+  return keys.filter((key) => store.subscriberCount(key) > 0);
+}
+
 // src/plugins/focus.ts
-function focusRevalidate(coordinator) {
-  const onFocus = () => {
-    for (const key of coordinator.getRegisteredKeys()) {
+function focusRevalidate(coordinator, store) {
+  const run = () => {
+    if (typeof document !== "undefined" && document.visibilityState !== "visible") {
+      return;
+    }
+    const keys = store ? keysWithSubscribers(coordinator.getRegisteredKeys(), store) : coordinator.getRegisteredKeys();
+    for (const key of keys) {
       void coordinator.revalidate(key);
     }
   };
-  window.addEventListener("focus", onFocus);
+  if (typeof document === "undefined") {
+    return () => {
+    };
+  }
+  document.addEventListener("visibilitychange", run);
   return () => {
-    window.removeEventListener("focus", onFocus);
+    document.removeEventListener("visibilitychange", run);
   };
 }
 
 // src/plugins/reconnect.ts
-function reconnectRevalidate(coordinator) {
+function reconnectRevalidate(coordinator, store) {
   const onOnline = () => {
-    for (const key of coordinator.getRegisteredKeys()) {
+    const keys = store ? keysWithSubscribers(coordinator.getRegisteredKeys(), store) : coordinator.getRegisteredKeys();
+    for (const key of keys) {
       void coordinator.revalidate(key);
     }
   };
@@ -843,9 +948,71 @@ function ttlEvict(coordinator, options) {
   };
 }
 
+// src/plugins/measure.ts
+function measurePerf(coordinator, onEvent) {
+  const snap = {
+    starts: 0,
+    aborts: 0,
+    dedups: 0,
+    writes: 0,
+    errors: 0,
+    totalMs: 0
+  };
+  const stop = coordinator.subscribe((event) => {
+    switch (event.type) {
+      case "start":
+        snap.starts += 1;
+        break;
+      case "abort":
+        snap.aborts += 1;
+        snap.totalMs += event.ms;
+        break;
+      case "dedup":
+        snap.dedups += 1;
+        break;
+      case "write":
+        snap.writes += 1;
+        snap.totalMs += event.ms;
+        break;
+      case "error":
+        snap.errors += 1;
+        snap.totalMs += event.ms;
+        break;
+    }
+    onEvent?.(event);
+  });
+  return {
+    snapshot: () => ({ ...snap }),
+    reset() {
+      snap.starts = 0;
+      snap.aborts = 0;
+      snap.dedups = 0;
+      snap.writes = 0;
+      snap.errors = 0;
+      snap.totalMs = 0;
+    },
+    stop
+  };
+}
+
+// src/plugins/attachDefaults.ts
+function attachDefaults(coordinator, store, options) {
+  const stops = [
+    focusRevalidate(coordinator, store),
+    reconnectRevalidate(coordinator, store),
+    ttlEvict(coordinator, options?.ttl ?? { maxAge: 3e5 })
+  ];
+  return () => {
+    for (const stop of stops) {
+      stop();
+    }
+  };
+}
+
 exports.DEDUP_WINDOW_MS = DEDUP_WINDOW_MS;
 exports.SteddyProvider = SteddyProvider;
 exports.UNSUBSCRIBE_GRACE_MS = UNSUBSCRIBE_GRACE_MS;
+exports.attachDefaults = attachDefaults;
 exports.clear = clear;
 exports.createCoordinator = createCoordinator;
 exports.createMutate = createMutate;
@@ -857,8 +1024,10 @@ exports.dump = dump;
 exports.focusRevalidate = focusRevalidate;
 exports.hydrate = hydrate;
 exports.hydrateAll = hydrateAll;
+exports.measurePerf = measurePerf;
 exports.mutate = mutate;
 exports.pollingRevalidate = pollingRevalidate;
+exports.prefetch = prefetch;
 exports.reconnectRevalidate = reconnectRevalidate;
 exports.retryOnError = retryOnError;
 exports.serializeKey = serializeKey;