floppy-disk 3.0.0-experimental.1 → 3.0.1

package/vanilla/basic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check if this runs on browser.
+ */
+export declare const isClient: boolean;
+/**
+ * Empty function.
+ */
+export declare const noop: () => void;
+/**
+ * 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/store.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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
+ * @param changedKeys - The top-level keys that changed (shallow diff)
+ *
+ * @remarks
+ * - Subscribers are only called when at least one field changes.
+ * - Change detection is performed per key using `Object.is`.
+ * - `changedKeys` only includes top-level keys; nested changes must be inferred by the consumer.
+ */
+export type Subscriber<TState> = (state: TState, prevState: TState, changedKeys: Array<keyof 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.
+ * - State is treated as **immutable**. Mutating nested values directly will not trigger updates.
+ * - Designed to be framework-agnostic (React bindings are built separately).
+ * - By default, `setState` is **disabled on the server** to prevent accidental shared state between requests.
+ */
+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;
+    /**
+     * By default, calling `setState` on the server is disallowed to prevent shared state across requests.
+     * Set this to `true` only if you explicitly intend to mutate state during server execution.
+     */
+    allowSetStateServerSide?: boolean;
+};
+/**
+ * Creates a vanilla store with pub-sub capabilities.
+ *
+ * The store state must be an **object**.\
+ * Updates are applied as shallow 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 the new state, previous state, and changed top-level keys.
+ * - State is expected to be treated as **immutable**.
+ *   - Mutating nested values directly will not trigger updates.
+ * - Lifecycle hooks allow side-effect management tied to subscription count.
+ * - By default, `setState` is **not allowed on the server** to prevent accidental shared state between requests.
+ *   - This helps avoid leaking data between users in server environments.
+ *   - If you intentionally want to allow this behavior, set `allowSetStateServerSide: true`.
+ *
+ * @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,3 @@
+export * from './vanilla/basic';
+export * from './vanilla/hash';
+export * from './vanilla/store';

package/vanilla.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const isClient = typeof window !== "undefined" && !("Deno" in window);
+const noop = () => {
+};
+const getValue = (valueOrComputeValueFn, ...params) => {
+  if (typeof valueOrComputeValueFn === "function") {
+    return valueOrComputeValueFn(...params);
+  }
+  return valueOrComputeValueFn;
+};
+
+const hasObjectPrototype = (value) => {
+  return Object.prototype.toString.call(value) === "[object Object]";
+};
+const isPlainObject = (value) => {
+  if (!hasObjectPrototype(value)) return false;
+  const ctor = value.constructor;
+  if (typeof ctor === "undefined") return true;
+  const prot = ctor.prototype;
+  if (!hasObjectPrototype(prot)) return false;
+  if (!prot.hasOwnProperty("isPrototypeOf")) return false;
+  if (Object.getPrototypeOf(value) !== Object.prototype) return false;
+  return true;
+};
+const getHash = (value) => JSON.stringify(
+  value,
+  (_, val) => isPlainObject(val) ? Object.keys(val).sort().reduce((result, key) => {
+    result[key] = val[key];
+    return result;
+  }, {}) : val
+);
+
+const initStore = (initialState, options = {}) => {
+  const {
+    onFirstSubscribe = noop,
+    onSubscribe = noop,
+    onUnsubscribe = noop,
+    onLastUnsubscribe = noop,
+    allowSetStateServerSide = false
+  } = options;
+  const subscribers = /* @__PURE__ */ new Set();
+  const getSubscribers = () => subscribers;
+  const subscribe = (subscriber) => {
+    subscribers.add(subscriber);
+    if (subscribers.size === 1) onFirstSubscribe(state, storeApi);
+    onSubscribe(state, storeApi);
+    return () => {
+      subscribers.delete(subscriber);
+      onUnsubscribe(state, storeApi);
+      if (subscribers.size === 0) onLastUnsubscribe(state, storeApi);
+    };
+  };
+  let state = initialState;
+  const getState = () => state;
+  const setState = (value) => {
+    if (!isClient && !allowSetStateServerSide) {
+      console.error(
+        "setState on the server is not allowed by default. Set `allowSetStateServerSide: true` to allow it."
+      );
+      return;
+    }
+    const prevState = state;
+    const newValue = getValue(value, state);
+    const changedKeys = [];
+    for (const key in newValue) {
+      if (!Object.is(prevState[key], newValue[key])) {
+        changedKeys.push(key);
+      }
+    }
+    if (changedKeys.length === 0) return;
+    state = { ...prevState, ...newValue };
+    [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
+  };
+  const storeApi = {
+    getState,
+    setState,
+    subscribe,
+    getSubscribers
+  };
+  return storeApi;
+};
+
+exports.getHash = getHash;
+exports.getValue = getValue;
+exports.initStore = initStore;
+exports.isClient = isClient;
+exports.isPlainObject = isPlainObject;
+exports.noop = noop;

package/esm/index.d.ts

@@ -1,8 +0,0 @@
-export * from './vanilla/init-store';
-export * from './vanilla/fetcher';
-export * from './react/create-store';
-export * from './react/create-stores';
-export * from './react/create-query';
-export * from './react/create-bi-direction-query';
-export * from './react/create-mutation';
-export * from './react/with-context';

package/esm/index.js

@@ -1,8 +0,0 @@
-export * from './vanilla/init-store';
-export * from './vanilla/fetcher';
-export * from './react/create-store';
-export * from './react/create-stores';
-export * from './react/create-query';
-export * from './react/create-bi-direction-query';
-export * from './react/create-mutation';
-export * from './react/with-context';

package/esm/react/create-bi-direction-query.d.ts

@@ -1,166 +0,0 @@
-import { Maybe } from '../utils';
-import { CreateQueryOptions, QueryState } from './create-query';
-import { StoreKey } from './create-stores';
-export declare const createBiDirectionQuery: <TKey extends StoreKey = StoreKey, TResponse = any, TData extends any[] = any[], TError = unknown, TPageParam = any>(queryFn: (key: TKey, state: QueryState<TKey, TResponse, TData, TError, TPageParam>, direction: 'prev' | 'next') => Promise<TResponse>, options: Omit<CreateQueryOptions<TKey, TResponse, TData, TError, TPageParam>, "select" | "getNextPageParam"> & {
-    getPrevPageParam: (lastPage: TResponse, index: number, stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError, TPageParam>) => Maybe<TPageParam>;
-    getNextPageParam: (lastPage: TResponse, index: number, stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError, TPageParam>) => Maybe<TPageParam>;
-    select: (response: TResponse, state: Pick<QueryState<TKey, TResponse, TData, TError, TPageParam>, "data" | "key">, direction: 'prev' | 'next') => TData;
-}) => {
-    (...args: [Maybe<TKey>, import("..").SelectDeps<QueryState<TKey, TResponse, TData, TError, TPageParam>>?] | [import("..").SelectDeps<QueryState<TKey, TResponse, TData, TError, TPageParam>>?]): {
-        data: (never[] | TData)[number][];
-        fetchPrevPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        hasPrevPage: boolean;
-        isWaitingPrevPage: boolean;
-        key: TKey;
-        keyHash: string;
-        fetch: () => void;
-        forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        fetchNextPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        reset: () => void;
-        optimisticUpdate: (response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => TResponse)) => {
-            revert: () => void;
-            invalidate: () => void;
-        };
-        isWaiting: boolean;
-        isWaitingNextPage: boolean;
-        isRefetching: boolean;
-        isRefetchError: boolean;
-        isPreviousData: boolean;
-        isOptimisticData: boolean;
-        error: TError | undefined;
-        errorUpdatedAt: number | undefined;
-        retryCount: number;
-        isGoingToRetry: boolean;
-        pageParam: Maybe<TPageParam>;
-        pageParams: Maybe<TPageParam>[];
-        hasNextPage: boolean;
-        retryNextPageCount: number;
-        isGoingToRetryNextPage: boolean;
-        status: "loading";
-        isLoading: true;
-        isSuccess: false;
-        isError: false;
-        response: undefined;
-        responseUpdatedAt: undefined;
-    } | {
-        data: (never[] | TData)[number][];
-        fetchPrevPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        hasPrevPage: boolean;
-        isWaitingPrevPage: boolean;
-        key: TKey;
-        keyHash: string;
-        fetch: () => void;
-        forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        fetchNextPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        reset: () => void;
-        optimisticUpdate: (response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => TResponse)) => {
-            revert: () => void;
-            invalidate: () => void;
-        };
-        isWaiting: boolean;
-        isWaitingNextPage: boolean;
-        isRefetching: boolean;
-        isRefetchError: boolean;
-        isPreviousData: boolean;
-        isOptimisticData: boolean;
-        error: TError | undefined;
-        errorUpdatedAt: number | undefined;
-        retryCount: number;
-        isGoingToRetry: boolean;
-        pageParam: Maybe<TPageParam>;
-        pageParams: Maybe<TPageParam>[];
-        hasNextPage: boolean;
-        retryNextPageCount: number;
-        isGoingToRetryNextPage: boolean;
-        status: "error";
-        isLoading: false;
-        isSuccess: false;
-        isError: true;
-        response: undefined;
-        responseUpdatedAt: undefined;
-    } | {
-        data: (never[] | TData)[number][];
-        fetchPrevPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        hasPrevPage: boolean;
-        isWaitingPrevPage: boolean;
-        key: TKey;
-        keyHash: string;
-        fetch: () => void;
-        forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        fetchNextPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        reset: () => void;
-        optimisticUpdate: (response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => TResponse)) => {
-            revert: () => void;
-            invalidate: () => void;
-        };
-        isWaiting: boolean;
-        isWaitingNextPage: boolean;
-        isRefetching: boolean;
-        isRefetchError: boolean;
-        isPreviousData: boolean;
-        isOptimisticData: boolean;
-        error: TError | undefined;
-        errorUpdatedAt: number | undefined;
-        retryCount: number;
-        isGoingToRetry: boolean;
-        pageParam: Maybe<TPageParam>;
-        pageParams: Maybe<TPageParam>[];
-        hasNextPage: boolean;
-        retryNextPageCount: number;
-        isGoingToRetryNextPage: boolean;
-        status: "success";
-        isLoading: false;
-        isSuccess: true;
-        isError: false;
-        response: TResponse;
-        responseUpdatedAt: number | undefined;
-    };
-    get(): {
-        prev: QueryState<TKey, TResponse, TData, TError, TPageParam>;
-        next: QueryState<TKey, TResponse, TData, TError, TPageParam>;
-    };
-    setInitialResponse: (options: {
-        key?: Maybe<TKey>;
-        response: TResponse;
-        skipRevalidation?: boolean | undefined;
-    }) => void;
-    reset(): void;
-    resetSpecificKey(key: Maybe<TKey>): void;
-    invalidate: () => void;
-    invalidateSpecificKey: (key?: Maybe<TKey>) => void;
-    suspend: (key?: Maybe<TKey>) => {
-        key: TKey;
-        keyHash: string;
-        fetch: () => void;
-        forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        fetchNextPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
-        reset: () => void;
-        optimisticUpdate: (response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => TResponse)) => {
-            revert: () => void;
-            invalidate: () => void;
-        };
-        isWaiting: boolean;
-        isWaitingNextPage: boolean;
-        isRefetching: boolean;
-        isRefetchError: boolean;
-        isPreviousData: boolean;
-        isOptimisticData: boolean;
-        error: TError | undefined;
-        errorUpdatedAt: number | undefined;
-        retryCount: number;
-        isGoingToRetry: boolean;
-        pageParam: Maybe<TPageParam>;
-        pageParams: Maybe<TPageParam>[];
-        hasNextPage: boolean;
-        retryNextPageCount: number;
-        isGoingToRetryNextPage: boolean;
-    } & {
-        status: "success";
-        isLoading: false;
-        isSuccess: true;
-        isError: false;
-        data: TData;
-        response: TResponse;
-        responseUpdatedAt: number | undefined;
-    };
-};

package/esm/react/create-bi-direction-query.js

@@ -1,74 +0,0 @@
-import { hasValue } from '../utils';
-import { createQuery } from './create-query';
-export const createBiDirectionQuery = (queryFn, options) => {
-    const { getPrevPageParam, getNextPageParam, select, ...restOptions } = options;
-    const usePrevPagesQuery = createQuery((key, state) => queryFn(key, state, 'prev'), {
-        defaultDeps: (state) => [
-            state.isWaiting,
-            state.data,
-            state.error,
-            state.isWaitingNextPage,
-            state.hasNextPage,
-        ],
-        fetchOnMount: false,
-        getNextPageParam: getPrevPageParam,
-        select: (response, state) => select(response, state, 'prev'),
-        ...restOptions,
-    });
-    const useNextPagesQuery = createQuery(async (key, state) => {
-        const isInitialPage = state.pageParam === undefined;
-        const pQuery = usePrevPagesQuery.get(key);
-        try {
-            const response = await queryFn(key, state, 'next');
-            if (isInitialPage) {
-                const prevPageParam = getPrevPageParam(response, 1, pQuery);
-                usePrevPagesQuery.set(key, (prev) => ({
-                    pageParams: [prevPageParam, ...prev.pageParams.slice(1)],
-                    hasNextPage: prev.isLoading ? hasValue(prevPageParam) : prev.hasNextPage,
-                }));
-                if (!pQuery.isLoading)
-                    pQuery.forceFetch();
-            }
-            return response;
-        }
-        catch (error) {
-            if (isInitialPage && !pQuery.isLoading)
-                pQuery.reset();
-            throw error;
-        }
-    }, {
-        getNextPageParam: getNextPageParam,
-        select: (response, state) => select(response, state, 'next'),
-        ...restOptions,
-    });
-    const useBiDirectionQuery = (...args) => {
-        const pQuery = usePrevPagesQuery(...args);
-        const nQuery = useNextPagesQuery(...args);
-        return {
-            ...nQuery,
-            data: [...(pQuery.data || []), ...(nQuery.data || [])],
-            fetchPrevPage: pQuery.fetchNextPage,
-            hasPrevPage: pQuery.hasNextPage,
-            isWaitingPrevPage: pQuery.isWaitingNextPage || (pQuery.isLoading && pQuery.isWaiting),
-        };
-    };
-    useBiDirectionQuery.get = () => {
-        return {
-            prev: usePrevPagesQuery.get(),
-            next: useNextPagesQuery.get(),
-        };
-    };
-    useBiDirectionQuery.setInitialResponse = useNextPagesQuery.setInitialResponse;
-    useBiDirectionQuery.reset = () => {
-        usePrevPagesQuery.reset();
-        useNextPagesQuery.reset();
-    };
-    useBiDirectionQuery.resetSpecificKey = (key) => {
-        usePrevPagesQuery.resetSpecificKey(key);
-        useNextPagesQuery.resetSpecificKey(key);
-    };
-    useBiDirectionQuery.invalidate = useNextPagesQuery.invalidate;
-    useBiDirectionQuery.invalidateSpecificKey = useNextPagesQuery.invalidateSpecificKey;
-    useBiDirectionQuery.suspend = useNextPagesQuery.suspend;
-    return useBiDirectionQuery;
-};

package/esm/react/create-mutation.d.ts

@@ -1,39 +0,0 @@
-import { InitStoreOptions } from '../vanilla/init-store';
-import { UseStore } from './create-store';
-export type MutationState<TVar, TResponse = any, TError = unknown> = {
-    /**
-     * Network fetching status.
-     */
-    isWaiting: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-    response: TResponse | undefined;
-    responseUpdatedAt: number | undefined;
-    error: TError | undefined;
-    errorUpdatedAt: number | undefined;
-    /**
-     * Mutate function.
-     *
-     * @returns Promise that will always get resolved.
-     */
-    mutate: TVar extends undefined ? () => Promise<{
-        response?: TResponse;
-        error?: TError;
-        variables?: TVar;
-    }> : (variables: TVar) => Promise<{
-        response?: TResponse;
-        error?: TError;
-        variables?: TVar;
-    }>;
-};
-export type UseMutation<TVar, TResponse = any, TError = unknown> = UseStore<MutationState<TVar, TResponse, TError>>;
-export type CreateMutationOptions<TVar, TResponse = any, TError = unknown> = InitStoreOptions<MutationState<TVar, TResponse, TError>> & {
-    onMutate?: (variables: TVar, stateBeforeMutate: MutationState<TVar, TResponse, TError>) => void;
-    onSuccess?: (response: TResponse, variables: TVar, stateBeforeMutate: MutationState<TVar, TResponse, TError>) => void;
-    onError?: (error: TError, variables: TVar, stateBeforeMutate: MutationState<TVar, TResponse, TError>) => void;
-    onSettled?: (variables: TVar, stateBeforeMutate: MutationState<TVar, TResponse, TError>) => void;
-};
-/**
- * @see https://floppy-disk.vercel.app/docs/api#createmutation
- */
-export declare const createMutation: <TVar, TResponse = any, TError = unknown>(mutationFn: (variables: TVar, state: MutationState<TVar, TResponse, TError>) => Promise<TResponse>, options?: CreateMutationOptions<TVar, TResponse, TError>) => UseMutation<TVar, TResponse, TError>;

package/esm/react/create-mutation.js

@@ -1,56 +0,0 @@
-import { noop } from '../utils';
-import { createStore } from './create-store';
-/**
- * @see https://floppy-disk.vercel.app/docs/api#createmutation
- */
-export const createMutation = (mutationFn, options = {}) => {
-    const { onMutate = noop, onSuccess = noop, onError, onSettled = noop, ...createStoreOptions } = options;
-    const useMutation = createStore(({ set, get }) => ({
-        isWaiting: false,
-        isSuccess: false,
-        isError: false,
-        response: undefined,
-        responseUpdatedAt: undefined,
-        error: undefined,
-        errorUpdatedAt: undefined,
-        mutate: ((variables) => {
-            set({ isWaiting: true });
-            const stateBeforeMutate = get();
-            onMutate(variables, stateBeforeMutate);
-            return new Promise((resolve) => {
-                mutationFn(variables, stateBeforeMutate)
-                    .then((response) => {
-                    set({
-                        isWaiting: false,
-                        isSuccess: true,
-                        isError: false,
-                        response,
-                        responseUpdatedAt: Date.now(),
-                        error: undefined,
-                        errorUpdatedAt: undefined,
-                    });
-                    onSuccess(response, variables, stateBeforeMutate);
-                    resolve({ response, variables });
-                })
-                    .catch((error) => {
-                    set({
-                        isWaiting: false,
-                        isSuccess: false,
-                        isError: true,
-                        error,
-                        errorUpdatedAt: Date.now(),
-                    });
-                    if (onError)
-                        onError(error, variables, stateBeforeMutate);
-                    else
-                        console.error(error, variables, get());
-                    resolve({ error, variables });
-                })
-                    .finally(() => {
-                    onSettled(variables, stateBeforeMutate);
-                });
-            });
-        }),
-    }), createStoreOptions);
-    return useMutation;
-};