floppy-disk 2.16.0 → 3.0.0-alpha.2

package/react.js

@@ -0,0 +1,511 @@
+'use strict';
+
+var react = require('react');
+var vanilla = require('floppy-disk/vanilla');
+
+const useIsomorphicLayoutEffect = vanilla.isClient ? react.useLayoutEffect : react.useEffect;
+
+const useStoreUpdateNotifier = (store, selector) => {
+  const [, reRender] = react.useState({});
+  const selectorRef = react.useRef(selector);
+  selectorRef.current = selector;
+  useIsomorphicLayoutEffect(
+    () => store.subscribe((state, prevState) => {
+      if (selectorRef.current === vanilla.identity) return reRender({});
+      const prevSlice = selectorRef.current(prevState);
+      const nextSlice = selectorRef.current(state);
+      if (!vanilla.shallow(prevSlice, nextSlice)) reRender({});
+    }),
+    [store]
+  );
+};
+const useStoreState = (store, selector = vanilla.identity) => {
+  useStoreUpdateNotifier(store, selector);
+  return selector(store.getState());
+};
+
+const createStore = (initialState, options) => {
+  const store = vanilla.initStore(initialState, options);
+  const useStore = (selector) => useStoreState(store, selector);
+  return Object.assign(useStore, store);
+};
+
+const createStores = (initialState, options) => {
+  const stores = /* @__PURE__ */ new Map();
+  const getStore = (key = {}) => {
+    const keyHash = vanilla.getHash(key);
+    let store;
+    if (stores.has(keyHash)) {
+      store = stores.get(keyHash);
+    } else {
+      store = vanilla.initStore(initialState, options);
+      stores.set(keyHash, store);
+    }
+    const useStore = (selector) => {
+      return useStoreState(store, selector);
+    };
+    return Object.assign(useStore, {
+      ...store,
+      delete: () => {
+        if (store.getSubscribers().size > 0) {
+          console.warn(
+            "Cannot delete store while it still has active subscribers. Unsubscribe all listeners before deleting the store."
+          );
+          return false;
+        }
+        store.setState(initialState);
+        return stores.delete(keyHash);
+      }
+    });
+  };
+  return getStore;
+};
+
+const INITIAL_STATE$1 = {
+  isPending: false,
+  isRevalidating: false,
+  isRetrying: false,
+  retryCount: 0,
+  state: "INITIAL",
+  isSuccess: false,
+  isError: false,
+  data: void 0,
+  dataUpdatedAt: void 0,
+  error: void 0,
+  errorUpdatedAt: void 0
+};
+const createQuery = (queryFn, options = {}) => {
+  const {
+    staleTime = 2500,
+    // 2.5 seconds,
+    gcTime = 5 * 60 * 1e3,
+    // 5 minutes
+    revalidateOnFocus = true,
+    revalidateOnReconnect = true,
+    onSuccess = vanilla.noop,
+    onError,
+    onSettled = vanilla.noop,
+    shouldRetry: shouldRetryFn = (_, s) => s.retryCount === 0 ? [true, 1500] : [false]
+  } = options;
+  const initialState = INITIAL_STATE$1;
+  const stores = /* @__PURE__ */ new Map();
+  const configureStoreEvents = () => ({
+    ...options,
+    onFirstSubscribe: (state, store) => {
+      var _a;
+      (_a = options.onFirstSubscribe) == null ? void 0 : _a.call(options, state, store);
+      const { metadata, revalidate: revalidate2 } = internals.get(store);
+      clearTimeout(metadata.garbageCollectionTimeoutId);
+      if (vanilla.isClient) {
+        if (revalidateOnFocus) {
+          focusListeners.add(revalidate2);
+          if (!focusListenersAdded) {
+            window.addEventListener("focus", onWindowFocus);
+            focusListenersAdded = true;
+          }
+        }
+        if (revalidateOnReconnect) {
+          onlineListeners.add(revalidate2);
+          if (!onlineListenersAdded) {
+            window.addEventListener("online", onWindowOnline);
+            onlineListenersAdded = true;
+          }
+        }
+      }
+    },
+    onLastUnsubscribe: (state, store) => {
+      var _a, _b;
+      (_a = options.onLastUnsubscribe) == null ? void 0 : _a.call(options, state, store);
+      const { metadata, revalidate: revalidate2 } = internals.get(store);
+      clearTimeout(metadata.retryTimeoutId);
+      (_b = metadata.retryResolver) == null ? void 0 : _b.call(metadata, state);
+      metadata.retryResolver = void 0;
+      metadata.garbageCollectionTimeoutId = setTimeout(() => {
+        store.setState(initialState);
+      }, gcTime);
+      if (vanilla.isClient) {
+        if (revalidateOnFocus) {
+          focusListeners.delete(revalidate2);
+          if (focusListeners.size === 0) {
+            window.removeEventListener("focus", onWindowFocus);
+            focusListenersAdded = false;
+          }
+        }
+        if (revalidateOnReconnect) {
+          onlineListeners.delete(revalidate2);
+          if (onlineListeners.size === 0) {
+            window.removeEventListener("online", onWindowOnline);
+            onlineListenersAdded = false;
+          }
+        }
+      }
+    }
+  });
+  const internals = /* @__PURE__ */ new WeakMap();
+  const configureInternals = (store, variable, variableHash) => ({
+    metadata: {},
+    setInitialData: (data, revalidate2 = false) => {
+      const state = store.getState();
+      if (state.state === "INITIAL" && state.data === void 0) {
+        const { metadata } = internals.get(store);
+        if (revalidate2) metadata.isInvalidated = true;
+        store.setState({
+          state: "SUCCESS",
+          isSuccess: true,
+          data,
+          dataUpdatedAt: Date.now()
+        });
+        return true;
+      }
+      return false;
+    },
+    execute: (overwriteOngoingExecution = false) => {
+      return execute(store, variable, overwriteOngoingExecution);
+    },
+    revalidate: (overwriteOngoingExecution = false) => {
+      return revalidate(store, variable, overwriteOngoingExecution);
+    },
+    invalidate: (overwriteOngoingExecution = false) => {
+      const { metadata } = internals.get(store);
+      metadata.isInvalidated = true;
+      if (store.getSubscribers().size > 0) {
+        internals.get(store).execute(overwriteOngoingExecution);
+        return true;
+      }
+      return false;
+    },
+    reset: () => {
+      var _a, _b;
+      const { metadata } = internals.get(store);
+      clearTimeout(metadata.retryTimeoutId);
+      if (metadata.retryResolver || metadata.promiseResolver) {
+        console.debug(
+          "Ongoing query execution was ignored due to reset(). The result will not update the store state."
+        );
+        (_a = metadata.promiseResolver) == null ? void 0 : _a.call(metadata, initialState);
+        (_b = metadata.retryResolver) == null ? void 0 : _b.call(metadata, initialState);
+        metadata.promiseResolver = void 0;
+        metadata.retryResolver = void 0;
+      }
+      metadata.promise = void 0;
+      store.setState(initialState);
+    },
+    delete: () => {
+      if (store.getSubscribers().size > 0) {
+        console.warn(
+          "Cannot delete query store while it still has active subscribers. Unsubscribe all listeners before deleting the store."
+        );
+        return false;
+      }
+      internals.get(store).reset();
+      return stores.delete(variableHash);
+    },
+    optimisticUpdate: (optimisticData) => {
+      const { metadata, revalidate: revalidate2, rollbackOptimisticUpdate } = internals.get(store);
+      metadata.rollbackData = store.getState().data;
+      store.setState({ data: optimisticData });
+      return { revalidate: revalidate2, rollback: rollbackOptimisticUpdate };
+    },
+    rollbackOptimisticUpdate: () => {
+      const { metadata } = internals.get(store);
+      store.setState({ data: metadata.rollbackData });
+      return metadata.rollbackData;
+    }
+  });
+  const execute = async (store, variable, overwriteOngoingExecution = false) => {
+    const { metadata } = internals.get(store);
+    if (!overwriteOngoingExecution && metadata.promise) return metadata.promise;
+    clearTimeout(metadata.retryTimeoutId);
+    const createPromise = () => {
+      const promise = new Promise((resolve) => {
+        metadata.promiseResolver = resolve;
+        const stateBeforeExecute = store.getState();
+        store.setState({
+          isPending: true,
+          isRevalidating: stateBeforeExecute.state === "SUCCESS",
+          isRetrying: !!metadata.retryResolver,
+          retryCount: metadata.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
+        });
+        queryFn(variable, stateBeforeExecute).then((data) => {
+          var _a;
+          if (data === void 0) {
+            console.error(
+              "Query function returned undefined. Successful responses must not be undefined."
+            );
+          }
+          if (!metadata.promiseResolver) return;
+          if (promise !== metadata.promise) return resolve(metadata.promise);
+          store.setState({
+            isPending: false,
+            isRevalidating: false,
+            isRetrying: false,
+            retryCount: 0,
+            state: "SUCCESS",
+            isSuccess: true,
+            isError: false,
+            data,
+            dataUpdatedAt: Date.now(),
+            error: void 0,
+            errorUpdatedAt: void 0
+          });
+          metadata.isInvalidated = false;
+          metadata.rollbackData = data;
+          resolve(store.getState());
+          (_a = metadata.retryResolver) == null ? void 0 : _a.call(metadata, store.getState());
+          metadata.retryResolver = void 0;
+          onSuccess(data, variable, stateBeforeExecute);
+          onSettled(variable, stateBeforeExecute);
+        }).catch((error) => {
+          var _a;
+          if (!metadata.promiseResolver && !metadata.retryResolver) return;
+          if (promise !== metadata.promise) return resolve(metadata.promise);
+          store.setState({
+            isPending: false,
+            isRevalidating: false,
+            isRetrying: false
+          });
+          const [shouldRetry, retryDelay] = shouldRetryFn(error, store.getState());
+          const hasSubscriber = store.getSubscribers().size > 0;
+          if (shouldRetry && hasSubscriber) {
+            metadata.retryResolver = resolve;
+            metadata.retryTimeoutId = setTimeout(createPromise, retryDelay);
+          } else {
+            store.setState({
+              isPending: false,
+              isRevalidating: false,
+              isRetrying: false,
+              retryCount: 0,
+              error,
+              errorUpdatedAt: Date.now(),
+              ...store.getState().data ? {
+                state: "SUCCESS_BUT_REVALIDATION_ERROR",
+                isError: false
+              } : {
+                state: "ERROR",
+                isError: true
+              }
+            });
+            const state = store.getState();
+            resolve(state);
+            (_a = metadata.retryResolver) == null ? void 0 : _a.call(metadata, state);
+            metadata.retryResolver = void 0;
+            if (onError) onError(error, variable, stateBeforeExecute);
+            else console.error(state);
+            onSettled(variable, stateBeforeExecute);
+          }
+        }).finally(() => {
+          if (metadata.promise === promise) {
+            metadata.promise = void 0;
+            metadata.promiseResolver = void 0;
+          }
+        });
+      });
+      metadata.promise = promise;
+      return promise;
+    };
+    return createPromise();
+  };
+  const revalidate = async (store, variable, overwriteOngoingExecution) => {
+    const { metadata } = internals.get(store);
+    if (!overwriteOngoingExecution && metadata.promise) return metadata.promise;
+    const state = store.getState();
+    if (state.dataUpdatedAt) {
+      const isFresh = state.dataUpdatedAt + staleTime > Date.now();
+      if (isFresh && !metadata.isInvalidated) return state;
+    }
+    return execute(store, variable, overwriteOngoingExecution);
+  };
+  const getStore = (variable = {}) => {
+    const variableHash = vanilla.getHash(variable);
+    let store;
+    if (stores.has(variableHash)) {
+      store = stores.get(variableHash);
+    } else {
+      store = vanilla.initStore(initialState, configureStoreEvents());
+      stores.set(variableHash, store);
+      internals.set(store, configureInternals(store, variable, variableHash));
+    }
+    const useStore = (options2 = {}, selector = vanilla.identity) => {
+      useStoreUpdateNotifier(store, selector);
+      useIsomorphicLayoutEffect(() => {
+        if (options2.enabled !== false) revalidate(store, variable);
+      }, [store, options2.enabled]);
+      const storeState = store.getState();
+      let storeStateToBeUsed = storeState;
+      const prevState = react.useRef({});
+      if (storeState.isSuccess) {
+        prevState.current = { data: storeState.data, dataUpdatedAt: storeState.dataUpdatedAt };
+      } else if (storeState.state === "INITIAL" && options2.keepPreviousData) {
+        storeStateToBeUsed = { ...storeState, ...prevState.current };
+      }
+      return selector(storeStateToBeUsed);
+    };
+    return Object.assign(useStore, {
+      subscribe: store.subscribe,
+      getSubscribers: store.getSubscribers,
+      getState: store.getState,
+      setState: (value) => {
+        console.debug("Manual setState (not via provided actions) on query store");
+        store.setState(value);
+      },
+      ...internals.get(store)
+    });
+  };
+  return Object.assign(getStore, {
+    /**
+     * Executes all query instances.
+     *
+     * @remarks
+     * - Useful for bulk refetching.
+     */
+    executeAll: (overwriteOngoingExecution) => {
+      stores.forEach((store) => internals.get(store).execute(overwriteOngoingExecution));
+    },
+    /**
+     * Revalidates all query instances.
+     *
+     * @remarks
+     * - Only re-fetches stale queries.
+     */
+    revalidateAll: (overwriteOngoingExecution) => {
+      stores.forEach((store) => internals.get(store).revalidate(overwriteOngoingExecution));
+    },
+    /**
+     * Invalidates all query instances.
+     *
+     * @remarks
+     * - Marks all queries as invalidated and triggers revalidation if active.
+     * - Invalidated queries bypass `staleTime` until successfully executed again.
+     */
+    invalidateAll: (overwriteOngoingExecution) => {
+      stores.forEach((store) => internals.get(store).invalidate(overwriteOngoingExecution));
+    },
+    /**
+     * Resets all query instances.
+     */
+    resetAll: () => {
+      stores.forEach((store) => internals.get(store).reset());
+    }
+  });
+};
+let focusListenersAdded = false;
+const focusListeners = /* @__PURE__ */ new Set();
+const onWindowFocus = () => [...focusListeners].forEach((fn) => fn());
+let onlineListenersAdded = false;
+const onlineListeners = /* @__PURE__ */ new Set();
+const onWindowOnline = () => [...onlineListeners].forEach((fn) => fn());
+
+const INITIAL_STATE = {
+  state: "INITIAL",
+  isPending: false,
+  isSuccess: false,
+  isError: false,
+  variable: void 0,
+  data: void 0,
+  dataUpdatedAt: void 0,
+  error: void 0,
+  errorUpdatedAt: void 0
+};
+const createMutation = (mutationFn, options = {}) => {
+  const { onSuccess = vanilla.noop, onError, onSettled = vanilla.noop } = options;
+  const initialState = INITIAL_STATE;
+  const store = vanilla.initStore(initialState, options);
+  const useStore = (selector) => useStoreState(store, selector);
+  const execute = (variable) => {
+    const stateBeforeExecute = store.getState();
+    if (stateBeforeExecute.isPending) {
+      console.warn(
+        "Mutation executed while a previous execution is still pending. This may cause race conditions or unexpected state updates."
+      );
+    }
+    store.setState({ isPending: true });
+    return new Promise((resolve) => {
+      mutationFn(variable, stateBeforeExecute).then((data) => {
+        store.setState({
+          state: "SUCCESS",
+          isPending: false,
+          isSuccess: true,
+          isError: false,
+          variable,
+          data,
+          dataUpdatedAt: Date.now(),
+          error: void 0,
+          errorUpdatedAt: void 0
+        });
+        resolve({ data, variable });
+        onSuccess(data, variable, stateBeforeExecute);
+      }).catch((error) => {
+        store.setState({
+          state: "ERROR",
+          isPending: false,
+          isSuccess: false,
+          isError: true,
+          variable,
+          data: void 0,
+          dataUpdatedAt: void 0,
+          error,
+          errorUpdatedAt: Date.now()
+        });
+        resolve({ error, variable });
+        if (onError) onError(error, variable, stateBeforeExecute);
+        else console.error(store.getState());
+      }).finally(() => {
+        onSettled(variable, stateBeforeExecute);
+      });
+    });
+  };
+  return Object.assign(useStore, {
+    subscribe: store.subscribe,
+    getSubscribers: store.getSubscribers,
+    getState: store.getState,
+    /**
+     * Manually updates the mutation state.
+     *
+     * @remarks
+     * - Intended for advanced use cases.
+     * - Prefer using provided mutation actions (`execute`, `reset`) instead.
+     */
+    setState: (value) => {
+      console.debug("Manual setState (not via provided actions) on mutation store");
+      store.setState(value);
+    },
+    /**
+     * Executes the mutation.
+     *
+     * @param variable - Input passed to the mutation function
+     *
+     * @returns A promise that always resolves with:
+     * - `{ data, variable }` on success
+     * - `{ error, variable }` on failure
+     *
+     * @remarks
+     * - If a mutation is already in progress, a warning is logged.
+     * - Concurrent executions are allowed but may lead to race conditions.
+     * - The promise never rejects to simplify async handling.
+     */
+    execute,
+    /**
+     * Resets the mutation state back to its initial state.
+     *
+     * @remarks
+     * - Does not cancel any ongoing request.
+     * - If a request is still pending, its result may override the reset state.
+     */
+    reset: () => {
+      if (store.getState().isPending) {
+        console.warn(
+          "Mutation state was reset while a request is still pending. The request will continue, but its result may override the reset state."
+        );
+      }
+      store.setState(initialState);
+    }
+  });
+};
+
+exports.createMutation = createMutation;
+exports.createQuery = createQuery;
+exports.createStore = createStore;
+exports.createStores = createStores;
+exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
+exports.useStoreState = useStoreState;
+exports.useStoreUpdateNotifier = useStoreUpdateNotifier;

package/vanilla/basic.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Check if this runs on browser.
+ */
+export declare const isClient: boolean;
+/**
+ * Empty function.
+ */
+export declare const noop: () => void;
+/**
+ * Identity function.
+ *
+ * It accepts 1 argument, and simply return it.
+ *
+ * `const identity = value => value`
+ */
+export declare const identity: <T>(value: T) => T;
+/**
+ * If the value is a function, it will invoke the function.\
+ * If the value is not a function, it will just return it.
+ */
+export declare const getValue: <T, P extends any[]>(valueOrComputeValueFn: T | ((...params: P) => T), ...params: P) => T;

package/vanilla/hash.d.ts

@@ -0,0 +1,7 @@
+export declare const isPlainObject: (value: any) => boolean;
+/**
+ * Get stable hash string from any value.
+ *
+ * Reference: https://github.com/TanStack/query/blob/v5.90.3/packages/query-core/src/utils.ts#L216
+ */
+export declare const getHash: (value?: any) => string;

package/vanilla/shallow.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shallow compare 2 values.
+ *
+ * Reference: https://github.com/pmndrs/zustand/blob/e414f7ccf41eae09517ee2dcb44c9f5ae8a35a25/src/vanilla/shallow.ts
+ */
+export declare const shallow: <T>(a: T, b: T) => boolean;

package/vanilla/store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Represents a partial state update.
+ *
+ * Can be either:
+ * - A partial object to merge into the current state
+ * - A function that receives the current state and returns a partial update
+ */
+export type SetState<TState> = Partial<TState> | ((state: TState) => Partial<TState>);
+/**
+ * A subscriber function that is called whenever the state updates.
+ *
+ * @param state - The latest state
+ * @param prevState - The previous state before the update
+ *
+ * @remarks
+ * - Subscribers are only called when the state actually changes.
+ * - Change detection is performed per key using `Object.is`.
+ */
+export type Subscriber<TState> = (state: TState, prevState: TState) => void;
+/**
+ * Core store API for managing state.
+ *
+ * @remarks
+ * - The store performs **shallow change detection per key** before notifying subscribers.
+ * - Subscribers are only notified when at least one field changes.
+ * - Designed to be framework-agnostic (React bindings are built separately).
+ */
+export type StoreApi<TState extends Record<string, any>> = {
+    setState: (value: SetState<TState>) => void;
+    getState: () => TState;
+    subscribe: (subscriber: Subscriber<TState>) => () => void;
+    getSubscribers: () => Set<Subscriber<TState>>;
+};
+/**
+ * Lifecycle hooks for the store.
+ *
+ * These hooks allow you to attach side effects based on subscription lifecycle.
+ *
+ * @remarks
+ * Useful for:
+ * - Lazy initialization (e.g. start fetching on first subscribe)
+ * - Cleanup (e.g. cancel timers, disconnect sockets)
+ * - Resource management (e.g. garbage collection)
+ */
+export type InitStoreOptions<TState extends Record<string, any>> = {
+    onFirstSubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    onSubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    onUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    onLastUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+};
+/**
+ * Creates a vanilla store with pub-sub capabilities.
+ *
+ * The store state is expected to be an **object**.\
+ * Updates are applied as partial merges, so non-object states are not supported.
+ *
+ * @param initialState - The initial state of the store
+ * @param options - Optional lifecycle hooks
+ *
+ * @returns A store API for managing state and subscriptions
+ *
+ * @remarks
+ * - State updates are **shallowly compared per key** before notifying subscribers.
+ * - Subscribers are only notified when at least one updated field changes (using `Object.is` comparison).
+ * - Subscribers receive both the new state and the previous state.
+ * - Lifecycle hooks allow side-effect management tied to subscription count.
+ *
+ * @example
+ * const store = initStore({ count: 0 });
+ *
+ * store.subscribe((state) => console.log(state.count));
+ * store.setState({ count: 1 }); // triggers subscriber
+ * store.setState({ count: 1 }); // no-op (no change)
+ */
+export declare const initStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => StoreApi<TState>;

package/vanilla.d.ts

@@ -0,0 +1,4 @@
+export * from './vanilla/basic';
+export * from './vanilla/shallow';
+export * from './vanilla/hash';
+export * from './vanilla/store';