steddy 0.1.0 → 0.1.2

package/README.md

@@ -45,7 +45,7 @@ focusRevalidate(defaultCoordinator);
 clear("user");
 ```
 
-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. `useSteddyInfinite` keeps one cache entry per page. `ttlEvict` drops unused keys.
+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. `measurePerf(coordinator)` subscribes to fetch events and returns `{ starts, aborts, dedups, writes, errors, totalMs }`. Run `npm run bench` for coordinator microbenchmarks.
 
 ## Architecture
 
@@ -55,7 +55,7 @@ plugins → coordinator → store
               hooks
 ```
 
-A new request for the same key **aborts** the in-flight one. Aborted requests do not write to the store. Optimistic `mutate` rolls back on error by default.
+A new request for the same key **aborts** the in-flight one. Aborted requests do not write to the store. The last subscriber’s unmount delays that abort by a tick so a remount can reuse the waiter. Optimistic `mutate` rolls back on error by default.
 
 ## License
 

package/dist/index.cjs

@@ -7,18 +7,45 @@ 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";
 }
 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) {
+      return;
+    }
+    clearTimeout(timer);
+    releaseTimers.delete(serializedKey);
+  }
   function abortInternal(serializedKey, markIdle) {
     const current = inflight.get(serializedKey);
     if (!current) {
       return;
     }
+    emit({
+      type: "abort",
+      key: serializedKey,
+      ms: now() - current.startedAt
+    });
     current.controller.abort();
     current.settle();
     inflight.delete(serializedKey);
@@ -31,15 +58,30 @@ function createCoordinator(store) {
   }
   const coordinator = {
     register(serializedKey, key, fetcher) {
+      cancelRelease(serializedKey);
       registered.set(serializedKey, { key, fetcher });
     },
     unregister(serializedKey) {
+      cancelRelease(serializedKey);
       registered.delete(serializedKey);
     },
+    scheduleRelease(serializedKey) {
+      cancelRelease(serializedKey);
+      const timer = setTimeout(() => {
+        releaseTimers.delete(serializedKey);
+        if (store.subscriberCount(serializedKey) > 0) {
+          return;
+        }
+        abortInternal(serializedKey, true);
+        registered.delete(serializedKey);
+      }, UNSUBSCRIBE_GRACE_MS);
+      releaseTimers.set(serializedKey, timer);
+    },
     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) {
+          emit({ type: "dedup", key: serializedKey });
           return;
         }
       }
@@ -63,12 +105,15 @@ 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,
@@ -89,6 +134,11 @@ function createCoordinator(store) {
           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)) {
@@ -102,6 +152,11 @@ function createCoordinator(store) {
           timestamp: current?.timestamp ?? 0,
           isValidating: false
         });
+        emit({
+          type: "error",
+          key: serializedKey,
+          ms: now() - startedAt
+        });
         throw error;
       } finally {
         settle();
@@ -117,10 +172,11 @@ function createCoordinator(store) {
       return [...registered.keys()];
     },
     abort(serializedKey) {
+      cancelRelease(serializedKey);
       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) {
@@ -135,7 +191,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);
           }
         }
@@ -155,6 +211,7 @@ function createCoordinator(store) {
         }
       }
       for (const key of victims) {
+        cancelRelease(key);
         abortInternal(key, false);
         registered.delete(key);
         store.delete(key);
@@ -162,10 +219,19 @@ function createCoordinator(store) {
       return [...victims];
     },
     reset() {
+      for (const key of [...releaseTimers.keys()]) {
+        cancelRelease(key);
+      }
       for (const key of [...inflight.keys()]) {
         abortInternal(key, false);
       }
       registered.clear();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
     }
   };
   return coordinator;
@@ -466,8 +532,7 @@ function useSteddy(key, fetcher, options) {
       return () => {
         unsubscribe();
         if (store.subscriberCount(serialized) === 0) {
-          coordinator.abort(serialized);
-          coordinator.unregister(serialized);
+          coordinator.scheduleRelease(serialized);
         }
       };
     },
@@ -489,26 +554,38 @@ function useSteddy(key, fetcher, options) {
     },
     [runtimeMutate]
   );
+  const keepPreviousData = options?.keepPreviousData === true;
+  const previousRef = react.useRef(
+    void 0
+  );
+  if (serialized != null && snapshot.data !== void 0) {
+    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;
   if (options?.suspense && serialized != null) {
     if (snapshot.error != null) {
       throw snapshot.error;
     }
-    if (snapshot.data === void 0) {
+    if (snapshot.data === void 0 && data === void 0) {
       const waiter = coordinator.getInFlightPromise(serialized) ?? coordinator.revalidate(serialized).catch(() => {
       });
       throw waiter;
     }
   }
   return {
-    data: snapshot.data,
+    data,
     error: snapshot.error,
-    isLoading: serialized != null && snapshot.data === void 0 && snapshot.error == null,
+    isLoading: serialized != null && data === void 0 && snapshot.error == null,
     isValidating: snapshot.isValidating,
     mutate: boundMutate
   };
 }
+function isThenable2(value) {
+  return typeof value === "object" && value !== null && typeof value.then === "function";
+}
 function collectPages(getKey, getData, size) {
   const pages = [];
+  const seen = /* @__PURE__ */ new Set();
   let previous;
   for (let index = 0; index < size; index++) {
     const key = getKey(index, previous);
@@ -516,13 +593,17 @@ function collectPages(getKey, getData, size) {
       break;
     }
     const serialized = serializeKey(key);
+    if (seen.has(serialized)) {
+      break;
+    }
+    seen.add(serialized);
     pages.push({ key, serialized });
     previous = getData(serialized);
   }
   return pages;
 }
 function useSteddyInfinite(getKey, fetcher, options) {
-  const { store, coordinator, mutate: runtimeMutate } = useSteddyRuntime();
+  const { store, coordinator } = useSteddyRuntime();
   const [size, setSizeState] = react.useState(options?.initialSize ?? 1);
   const fetcherRef = react.useRef(fetcher);
   fetcherRef.current = fetcher;
@@ -564,8 +645,7 @@ function useSteddyInfinite(getKey, fetcher, options) {
         for (const [index, page] of currentPages.entries()) {
           unsubscribes[index]?.();
           if (store.subscriberCount(page.serialized) === 0) {
-            coordinator.abort(page.serialized);
-            coordinator.unregister(page.serialized);
+            coordinator.scheduleRelease(page.serialized);
           }
         }
       };
@@ -628,32 +708,71 @@ function useSteddyInfinite(getKey, fetcher, options) {
   );
   const boundMutate = react.useCallback(
     async (updater, mutateOptions) => {
+      const revalidate = mutateOptions?.revalidate ?? true;
+      const rollbackOnError = mutateOptions?.rollbackOnError ?? true;
       const currentPages = collectPages(
         getKeyRef.current,
         (serialized) => store.get(serialized)?.data,
         size
       );
-      const first2 = currentPages[0];
-      if (!first2) {
+      if (currentPages.length === 0) {
         return void 0;
       }
-      if (updater !== void 0 && typeof updater !== "function") {
-        const pagesValue = updater;
-        const firstPage = pagesValue[0];
-        if (firstPage !== void 0) {
-          await runtimeMutate(first2.key, firstPage, mutateOptions);
+      const previous = currentPages.map((page) => ({
+        serialized: page.serialized,
+        entry: store.get(page.serialized)
+      }));
+      const restore = () => {
+        for (const item of previous) {
+          if (item.entry === void 0) {
+            store.delete(item.serialized);
+          } else {
+            store.set(item.serialized, item.entry);
+          }
         }
-        return pagesValue;
+      };
+      try {
+        const loaded = [];
+        for (const page of currentPages) {
+          const pageData = store.get(page.serialized)?.data;
+          if (pageData === void 0) {
+            break;
+          }
+          loaded.push(pageData);
+        }
+        const current = loaded.length === 0 ? void 0 : loaded;
+        const next = typeof updater === "function" ? updater(current) : updater;
+        const resolved = isThenable2(next) ? await next : next;
+        const pagesValue = resolved;
+        for (const [index, page] of currentPages.entries()) {
+          if (index >= pagesValue.length) {
+            break;
+          }
+          store.set(page.serialized, {
+            data: pagesValue[index],
+            error: void 0,
+            timestamp: Date.now(),
+            isValidating: revalidate
+          });
+        }
+        if (revalidate) {
+          await Promise.all(
+            currentPages.map(
+              (page) => coordinator.revalidate(page.serialized, void 0, {
+                force: true
+              })
+            )
+          );
+        }
+        return currentPages.map((page) => store.get(page.serialized)?.data).filter((page) => page !== void 0);
+      } catch (error) {
+        if (rollbackOnError) {
+          restore();
+        }
+        throw error;
       }
-      await Promise.all(
-        currentPages.map(
-          (page) => coordinator.revalidate(page.serialized, void 0, { force: true }).catch(() => {
-          })
-        )
-      );
-      return currentPages.map((page) => store.get(page.serialized)?.data).filter((page) => page !== void 0);
     },
-    [coordinator, runtimeMutate, size, store]
+    [coordinator, size, store]
   );
   const first = pages[0];
   const firstEntry = first ? store.getSnapshot(first.serialized) : void 0;
@@ -761,8 +880,56 @@ 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
+  };
+}
+
 exports.DEDUP_WINDOW_MS = DEDUP_WINDOW_MS;
 exports.SteddyProvider = SteddyProvider;
+exports.UNSUBSCRIBE_GRACE_MS = UNSUBSCRIBE_GRACE_MS;
 exports.clear = clear;
 exports.createCoordinator = createCoordinator;
 exports.createMutate = createMutate;
@@ -774,6 +941,7 @@ exports.dump = dump;
 exports.focusRevalidate = focusRevalidate;
 exports.hydrate = hydrate;
 exports.hydrateAll = hydrateAll;
+exports.measurePerf = measurePerf;
 exports.mutate = mutate;
 exports.pollingRevalidate = pollingRevalidate;
 exports.reconnectRevalidate = reconnectRevalidate;