Document all store states

[SanariSan]

We have recently adopted nanostores and nanostores/query on a fresh Astro SSG project, and even though I really enjoy it, I had to spend quite a lot of time reading source code to grasp all possible atom states and related call return values, as they were not clear to me. Working with an LLM that was aware of the source code, I assembled JSDoc documentation to document "what to expect" and would like to propose adding that to the library as well. Obviously, this should be carefully re-checked and the wording might be awkward, but the main idea should be clear. Thanks for creating this masterpiece.

Fetcher Store:

/**
 * ========================================================================
 *                      Fetcher Store State Documentation
 * ========================================================================
 *
 * A `fetcherStore` is a MapStore that tracks the state of an asynchronous
 * data-fetching operation. Its state transitions are managed by Nano Stores'
- * lifecycle events (`onStart`, `onStop`) and its interaction with a global cache.
 *
 * @typedef {object} FetcherStoreValue
 * @property {boolean} loading - `true` if a fetch operation is currently in-flight.
 * @property {any} [data] - The successfully resolved data from the last fetch.
 * @property {any} [error] - The error object from the last failed fetch.
 * @property {Promise<any>} [promise] - The in-flight promise of the current fetch operation.
 */

/**
 * --------------------------------
 *   Initial State & "Off" State
 * --------------------------------
 * This is the state of the store before its first subscription, or after its
 * last subscriber has been removed. In this state, the store is completely
 * passive and holds no data locally.
 *
 * @type {FetcherStoreValue}
 * @example { loading: false }
 */

/**
 * --------------------------------
 *        Active States
 * --------------------------------
 */

/**
 * ### State 1: Loading (No Cache)
 * Occurs on the first mount for a given key when no cache exists, or when the
 * cache has been invalidated (`.invalidate()`).
 *
 * @type {FetcherStoreValue}
 * @example { loading: true, promise: Promise<...> }
 */

/**
 * ### State 2: Loading (Stale-While-Revalidate)
 * Occurs on mount when a valid but "stale" (past `dedupeTime`) cache entry
 * exists. The UI can show the old `data` immediately while a new fetch
 * runs in the background.
 *
 * @type {FetcherStoreValue}
 * @example { data: [stale_data], loading: true, promise: Promise<...> }
 */

/**
 * ### State 3: Success (Deduplicated)
 * Occurs on mount when a valid and "fresh" (within `dedupeTime`) cache entry
 * exists. The data is served directly from the cache and no network request
 * is made.
 *
 * @type {FetcherStoreValue}
 * @example { data: [cached_data], loading: false }
 */

/**
 * ### State 4: Success (Freshly Fetched)
 * The state after a successful network request.
 *
 * @type {FetcherStoreValue}
 * @example { data: [fresh_data], loading: false }
 */

/**
 * --------------------------------
 *         Edge Case States
 * --------------------------------
 */

/**
 * ### Edge Case A: Revalidation Failure
 * Occurs when a revalidation fetch fails while the store already holds valid
 * (but now stale) data. This allows the UI to show the last known good data
 * alongside an error indicator, preventing a blank screen.
 *
 * @type {FetcherStoreValue}
 * @example { data: [stale_data], error: [the_error], loading: false }
 */

/**
 * ### Edge Case B: Conditional Fetching Disabled
 * Occurs when one of the dynamic keys of a `fetcherStore` becomes falsy
 * (e.g., `null`, `undefined`, `false`). The store reverts to its initial state
 * even if it remains subscribed in the UI, effectively pausing the fetch.
 *
 * @type {FetcherStoreValue}
 * @example { loading: false }
 */

Mutator Store:

/**
 * ========================================================================
 *                      Mutator Store State Documentation
 * ========================================================================
 *
 * A `mutatorStore` is a MapStore that tracks the state of an active mutation
 * (e.g., a POST or PUT request). Its state is simpler and is only changed by
 * direct calls to its `.mutate()` method.
 *
 * @typedef {object} MutatorStoreValue
 * @property {boolean} loading - `true` if a mutation is currently in-flight.
 * @property {Function} mutate - The function to trigger the mutation.
 * @property {any} [data] - The successfully resolved data from the last mutation.
 * @property {any} [error] - The error object from the last failed mutation.
 */

/**
 * --------------------------------
 *   Initial State & "Off" State
 * --------------------------------
 * This is the state of the store before `.mutate()` has been called, or after
 * its last subscriber has been removed. Any `data` or `error` from a previous
 * run is cleared.
 *
 * @type {MutatorStoreValue}
 * @example { mutate: [Function], loading: false }
 */

/**
 * --------------------------------
 *        Active States
 * --------------------------------
 */

/**
 * ### State 1: Loading
 * The state immediately after `.mutate()` is called and before the async
 * operation completes. `data` and `error` from any previous run are cleared.
 *
 * @type {MutatorStoreValue}
 * @example { mutate: [Function], loading: true }
 */

/**
 * ### State 2: Success
 * The state after the mutation's async operation resolves successfully.
 * The `data` field contains the return value of the operation.
 *
 * @type {MutatorStoreValue}
 * @example { mutate: [Function], loading: false, data: [the_result] }
 */

/**
 * ### State 3: Error
 * The state after the mutation's async operation rejects.
 * The `error` field contains the thrown error.
 *
 * @type {MutatorStoreValue}
 * @example { mutate: [Function], loading: false, error: [the_error] }
 */

/**
 * --------------------------------
 *         Edge Case States
 * --------------------------------
 */

/**
 * ### Edge Case A: Result Discarded After Unsubscribe
 * If the last subscriber to a `mutatorStore` unmounts while a mutation is
 * in-flight, the final result (`data` or `error`) of that mutation will be
 * discarded. The store will remain in its clean "off" state. This prevents
 * race conditions where a result from a stale operation could affect a newly
 * mounted component.
 *
 * @type {MutatorStoreValue}
 * @example { mutate: [Function], loading: false }
 */

/**
 * ### Edge Case B: Promise Resolution on `.mutate()`
 * The `Promise` returned by the `.mutate()` method itself has specific behaviors.
 *
 * - **On Throttle:** If a mutation is already in-flight, subsequent calls (by
 *   default) are throttled. The returned `Promise` will resolve immediately
 *   with `undefined`.
 *
 * - **On Error:** If the mutation function throws an error, the returned
 *   `Promise` will still *resolve* (not reject) with a value of `undefined`.
 *   The error is caught internally and set on the store's `.error` property.
 *   This prevents unhandled promise rejections.
 *
 * - **Important:** To retrieve error information from a `.mutate()` call when
 *   the promise resolves to `undefined`, the store must have at least one active
 *   listener. Without a listener, the error state will not be set and you won't
 *   be able to access it via `.get().error`. This is typically not an issue in
 *   components using `useStore`, but when calling `.mutate()` outside of components,
 *   you need to manually add a listener first:
 *
*   @example
 *   const unlisten = $mutatorStore.listen(() => {});
 *   try {
 *     const result = await $mutatorStore.mutate();
 * 
 *     // Check for throttle or error
 *     if (result === undefined || $mutatorStore.get().error) {
 *       throw $mutatorStore.get().error ?? new Error("Throttled");
 *     }
 * 
 *     return result;
 *   } finally {
 *     unlisten();
 *   }
 */

[SanariSan]

As a side note, I also came up with a recipe for instant cache hydration in the typical async useStore flow that allows determining if the cache had data right from the first render and acting accordingly (for example, either playing a fade-in transition as after the first data load or showing data instantly). This is possible due to the synchronous nature of the library and its lifecycle hooks such as onStart and the way subscribe works by immediately calling the callback on the store. This pattern might be worth considering for inclusion in the documentation as well:

/**
 * A hook that synchronously determines if a nanostores/query store
 * was hydrated with cached data on its initial mount.
 *
 * @param store The nanostores/query store instance to check.
 * @returns A boolean that is `true` if the store had data on mount, and `false` otherwise.
 *          This value is stable for the lifetime of the component.
 */
export const useIsCachedOnMount = (store) => {
  const [isCached] = useState(() => {
    let wasCached = false;
    // Subscribe to force the synchronous `onStart` hydration logic.
    const unsubscribe = store.subscribe((value) => {
      // If the value has data after the synchronous onStart, it was cached.
      if (value.data) {
        wasCached = true;
      }
    });
    // Only needed the immediate side-effect, so clean up right away.
    unsubscribe();
    return wasCached;
  });
  return isCached;
};

Example usage from project (redacted):

export const DataComponent = ({ itemId }) => {
  const $dataStore = useMemo(
    () => createDataStore({ id: itemId }),
    [itemId],
  );
  
  const { data, loading } = useStore($dataStore);
  const wasCachedOnMount = useIsCachedOnMount($dataStore);

  const { isMounted, isActive } = useFadeTransition({
    isVisible: data !== undefined,
    delay: 200,
    skipAnimationOnMount: wasCachedOnMount,
  });

  return isMounted && (
    <div
      className={cn(
        "opacity-0 transition-opacity duration-200",
        isActive && "opacity-100",
      )}
    >{/* ... */}</div>
  );
};

Supplementary hooks used:

/**
 * Hook that delays unmounting of components to allow exit animations to complete.
 * When isVisible becomes true, isMounted immediately becomes true.
 * When isVisible becomes false, isMounted stays true for the specified delay, then becomes false.
 * This prevents the component from being removed from the DOM before animations finish.
 * @param isVisible - Whether the component should be visible.
 * @param delay - Time in milliseconds to wait before unmounting after isVisible becomes false. Defaults to 200ms.
 * @returns isMounted - A boolean indicating whether the component should remain in the DOM.
 */
const useDelayedUnmount = ({
  isVisible,
  delay = 200,
}: {
  isVisible: boolean;
  delay?: number;
}) => {
  const [isMounted, setIsMounted] = useState(false);
  const timerRef = useRef<NodeJS.Timeout | null>(null);

  useEffect(() => {
    if (isVisible && !isMounted) {
      setIsMounted(true);
    } else if (!isVisible && isMounted) {
      timerRef.current = setTimeout(() => {
        setIsMounted(false);
      }, delay);
    }

    return () => {
      if (timerRef.current !== null) clearTimeout(timerRef.current);
    };
  }, [isVisible, isMounted, delay]);

  return { isMounted };
};

/**
 * Manages the "active" state for a fade-in/out transition.
 * It uses requestAnimationFrame to ensure the fade-in transition triggers correctly
 * after the component is mounted.
 * @param isVisible - The desired final state (visible or not).
 * @param isMounted - Whether the component is currently in the DOM.
 * @param skipAnimationOnMount - If true, the component will be active immediately on the first render.
 * @returns isActive - A boolean to control the 'active' CSS class for transitions.
 */
export const useFadeIn = ({
  isVisible,
  isMounted,
  skipAnimationOnMount = false,
}: {
  isVisible: boolean;
  isMounted: boolean;
  skipAnimationOnMount?: boolean;
}) => {
  const [isActive, setIsActive] = useState(isVisible && skipAnimationOnMount);

  useEffect(() => {
    if (skipAnimationOnMount && isVisible) {
      setIsActive(true);
      return;
    }

    if (isMounted && isVisible) {
      const frameId = requestAnimationFrame(() => {
        setIsActive(true);
      });
      return () => cancelAnimationFrame(frameId);
    }

    if (!isVisible) {
      setIsActive(false);
    }

    return;
  }, [isMounted, isVisible, skipAnimationOnMount]);

  return { isActive };
};

/**
 * A composed hook that combines mounting/unmounting logic with fade-in/out
 * transition state management.
 * @param isVisible - Whether the component should be visible.
 * @param fadeOutDelay - The duration of the fade-out transition.
 * @param skipAnimationOnMount - If true, the component appears without a fade-in animation on initial mount.
 * @returns isMounted and isActive states to control rendering and CSS classes.
 */
export const useFadeTransition = ({
  isVisible,
  fadeOutDelay = 200,
  skipAnimationOnMount = false,
}: {
  isVisible: boolean;
  fadeOutDelay?: number;
  skipAnimationOnMount?: boolean;
}) => {
  const { isMounted } = useDelayedUnmount({ isVisible, delay: fadeOutDelay });
  const { isActive } = useFadeIn({
    isVisible,
    isMounted,
    skipAnimationOnMount,
  });

  return { isMounted, isActive };
};