yuustate 0.0.1 → 3.9.0

package/esm/react/create-query.d.mts

@@ -0,0 +1,519 @@
+import { type InitStoreOptions, type SetStateInput } from "yuustate/vanilla";
+import type { StoreKey } from "./create-stores.mjs";
+/**
+ * Represents the state of a query.
+ *
+ * @remarks
+ * A query manages cached results of an async operation with lifecycle awareness.
+ *
+ * State variants:
+ * - `INITIAL` → no execution has occurred yet
+ * - `SUCCESS` → execution completed successfully
+ * - `ERROR` → initial execution failed (no data available)
+ * - `SUCCESS_BUT_REVALIDATION_ERROR` → data exists, but a revalidation failed
+ *
+ * Flags:
+ * - `isPending` → an execution is currently in progress
+ * - `isRevalidating` → re-executing while already having data
+ * - `isRetrying` → retrying after a failure
+ *
+ * @remarks
+ * - Data and error are mutually exclusive except in `SUCCESS_BUT_REVALIDATION_ERROR`.
+ */
+export type QueryState<TData, TError> = {
+    isPending: boolean;
+    isRevalidating: boolean;
+    willRetryAt: undefined | number;
+    isRetrying: boolean;
+    retryCount: number;
+} & ({
+    state: "INITIAL";
+    isSuccess: false;
+    isError: false;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    dataStaleAt: undefined;
+    error: undefined;
+    errorUpdatedAt: undefined;
+} | {
+    state: "SUCCESS";
+    isSuccess: true;
+    isError: false;
+    data: TData;
+    dataUpdatedAt: number;
+    dataStaleAt: undefined | number;
+    error: undefined;
+    errorUpdatedAt: undefined;
+} | {
+    state: "ERROR";
+    isSuccess: false;
+    isError: true;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    dataStaleAt: undefined;
+    error: TError;
+    errorUpdatedAt: number;
+} | {
+    state: "SUCCESS_BUT_REVALIDATION_ERROR";
+    isSuccess: true;
+    isError: true;
+    data: TData;
+    dataUpdatedAt: number;
+    dataStaleAt: undefined | number;
+    error: TError;
+    errorUpdatedAt: number;
+});
+type Internal<TData, TError> = {
+    isInvalidated?: boolean;
+    promise?: Promise<QueryState<TData, TError>> | undefined;
+    promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
+    retryTimeoutId?: number;
+    retryResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
+    garbageCollectionTimeoutId?: number;
+    rollbackData?: TData | undefined;
+};
+type AdditionalStoreApi<TData, TError> = {
+    /**
+     * A deterministic hash string derived from the query variable.
+     *
+     * Used as the unique identifier for this query instance in the internal cache.
+     *
+     * @remarks
+     * - Structurally identical variables will produce the same hash.
+     */
+    variableHash: string;
+    /**
+     * Sets initial data for the query if it has not been initialized.
+     *
+     * @param data - Initial data
+     * @param revalidate - Whether to mark the data as invalidated (will trigger revalidation)
+     *
+     * @returns `true` if the data was set, `false` otherwise
+     *
+     * @remarks
+     * - Only applies when the query is in the `INITIAL` state.
+     * - Useful for hydration or preloaded data.
+     */
+    setInitialData: (data: TData, revalidate?: boolean) => boolean;
+    /**
+     * Executes the query function.
+     *
+     * @param options - Execution options
+     * @param options.overwriteOngoingExecution - Whether to start a new execution instead of reusing an ongoing one (default: `true`)
+     *
+     * @returns A promise resolving to the latest query state
+     *
+     * @remarks
+     * - By default, each call **starts a new execution** even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     * - Handles:
+     *   - Pending state
+     *   - Success state
+     *   - Error state
+     *   - Retry logic
+     */
+    execute: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Re-executes the query if needed based on freshness or invalidation.
+     *
+     * @param options - Revalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns The current state if still fresh, otherwise a promise of the new state
+     *
+     * @remarks
+     * - Skips execution if data is still fresh (`staleTime`) **AND** the query has not been invalidated.
+     * - If execution is not skipped, by default it will start a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    revalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Marks the query as invalidated and optionally triggers re-execution.
+     *
+     * @param options - Invalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns `true` if execution was triggered, `false` otherwise
+     *
+     * @remarks
+     * - Invalidated queries are treated as stale regardless of `staleTime`.
+     * - The next `revalidate` will always execute until a successful result clears the invalidation.
+     * - If there are active subscribers: Execution is triggered immediately.
+     * - Otherwise: The query remains invalidated and will execute on the next revalidation.
+     * - By default, starts a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    invalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => boolean;
+    /**
+     * Resets the query state to its initial state.
+     *
+     * @remarks
+     * - Cancels retry logic and ignores any ongoing execution results.
+     */
+    reset: () => void;
+    /**
+     * Deletes the query store for the current variable.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers.
+     */
+    delete: () => boolean;
+    /**
+     * Performs an optimistic update on the query data.
+     *
+     * @param data - Optimistic data to set
+     *
+     * @returns Controls for managing the optimistic update
+     *
+     * @remarks
+     * - Temporarily replaces the current data.
+     * - Stores previous data for rollback.
+     * - Commonly used with mutations for instant UI updates.
+     *
+     * @example
+     * const { rollback, revalidate } = query.optimisticUpdate(newData);
+     */
+    optimisticUpdate: (data: TData) => {
+        revalidate: () => Promise<QueryState<TData, TError>>;
+        rollback: () => TData;
+    };
+    /**
+     * Restores the data before the last optimistic update.
+     *
+     * @returns The restored data
+     *
+     * @remarks
+     * - Should be used if an optimistic update fails.
+     */
+    rollbackOptimisticUpdate: () => TData;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
+};
+/**
+ * Configuration options for a query.
+ *
+ * @remarks
+ * Controls caching, retry behavior, lifecycle, and side effects of an async operation.
+ */
+export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, AdditionalStoreApi<TData, TError>> & {
+    /**
+     * Time (in milliseconds) that data is considered fresh.
+     *
+     * While fresh, revalidation will be skipped unless explicitly invalidated.
+     *
+     * @default 2500 ms (2.5 seconds)
+     */
+    staleTime?: number;
+    /**
+     * Time (in milliseconds) before unused queries are garbage collected.
+     *
+     * Starts counting after the last subscriber unsubscribes.
+     *
+     * @default 5 minutes
+     */
+    gcTime?: number;
+    /**
+     * Whether to revalidate when the window gains focus.
+     *
+     * @default true
+     */
+    revalidateOnFocus?: boolean;
+    /**
+     * Whether to revalidate when the network reconnects.
+     *
+     * @default true
+     */
+    revalidateOnReconnect?: boolean;
+    /**
+     * Called when the query succeeds.
+     */
+    onSuccess?: (data: TData, variable: TVariable, stateBeforeExecute: QueryState<TData, TError>) => void;
+    /**
+     * Called when the query fails and will not retry.
+     */
+    onError?: (error: TError, variable: TVariable, stateBeforeExecute: QueryState<TData, TError>) => void;
+    /**
+     * Called after the query settles (success or final failure).
+     */
+    onSettled?: (variable: TVariable, stateBeforeExecute: QueryState<TData, TError>) => void;
+    /**
+     * Determines whether a failed query should retry.
+     *
+     * @returns
+     * - `[true, delay]` to retry after `delay` milliseconds
+     * - `[false]` to stop retrying
+     *
+     * @default Retries once after 1500ms
+     *
+     * @example
+     * shouldRetry: (error, state) => {
+     *   if (error?.status === 401 || error?.code === 'UNAUTHORIZED') return [false];
+     *   if (state.retryCount < 3) return [true, 1000 * 2 ** state.retryCount];
+     *   return [false];
+     * }
+     */
+    shouldRetry?: (error: TError, currentState: QueryState<TData, TError>) => [true, number] | [false];
+};
+/**
+ * Creates a query factory for managing cached async operations.
+ *
+ * @param queryFn - Async function to resolve data
+ * @param options - Optional configuration for caching, retry, and lifecycle
+ *
+ * @returns A function to retrieve or create a query instance by variable
+ *
+ * @remarks
+ * - Queries are **keyed by variable** (via deterministic hashing).
+ * - Each unique variable maps to its own store instance.
+ *
+ * Core features:
+ * - Caching via `staleTime`
+ * - Explicit invalidation (independent of freshness)
+ * - Retry logic via `shouldRetry`
+ * - Background revalidation (focus / reconnect)
+ * - Garbage collection via `gcTime`
+ *
+ * Execution behavior:
+ * - By default, executions **overwrite ongoing executions**
+ * - Set `overwriteOngoingExecution: false` to enable deduplication
+ * - Internal revalidation (focus/reconnect) uses deduplication by default
+ *
+ * @example
+ * const userQuery = createQuery<UserDetail, { id: string }>(async ({ id }) => {
+ *   return api.getUser(id);
+ * });
+ *
+ * function MyComponent({ id }: { id: string }) {
+ *   const useUserQuery = userQuery({ id });
+ *   const state = useUserQuery();
+ *   // ...
+ * }
+ *
+ * @see https://yuustate.vercel.app/docs/query
+ */
+export declare const createQuery: <TData, TVariable extends StoreKey = never, TError = Error>(queryFn: (variable: TVariable, currentState: QueryState<TData, TError>, variableHash: string) => Promise<TData>, options?: QueryOptions<TData, TVariable, TError>) => ((variable?: TVariable) => ((options?: {
+    /**
+     * Whether the query should be ravalidated automatically on mount.
+     *
+     * Revalidate means execute the queryFn **if stale/invalidated**.
+     *
+     * @default true
+     */
+    revalidateOnMount?: boolean;
+    /**
+     * Whether to keep previous successful data while a new variable is loading.
+     *
+     * @remarks
+     * - Only applies when the query is in the `INITIAL` state (no data & no error).
+     * - Intended for variable changes:
+     *   when switching from one variable to another, the previous data is temporarily shown
+     *   while the new execution is in progress.
+     * - Once the new execution resolves (success or error), the previous data is no longer used.
+     * - Prevents UI flicker (e.g. empty/loading state) during transitions.
+     *
+     * @example
+     * // Switching from userId=1 → userId=2
+     * // While loading userId=2, still show userId=1 data
+     * useQuery({ id: userId }, { keepPreviousData: true });
+     */ keepPreviousData?: boolean;
+} & ({
+    /**
+     * Initial data used on first render (and will also update the store state right after that)
+     *
+     * If provided, `initialData` will be applied **once per query-store instance**
+     */
+    initialData: TData;
+    /**
+     * Whether the provided `initialData` should be treated as stale.
+     *
+     * @remarks
+     * - If `true`, a revalidation (refetch) will be triggered immediately.
+     * - If `false` (default), `initialData` is treated as fresh and will not be revalidated.
+     *
+     * @default false
+     *
+     * @example
+     * useQuery({
+     *   initialData: dataFromSSR,
+     *   initialDataIsStale: true, // force refetch
+     * });
+     */
+    initialDataIsStale?: boolean;
+} | {
+    initialData?: never;
+    initialDataIsStale?: never;
+})) => QueryState<TData, TError>) & {
+    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    getState: () => QueryState<TData, TError>;
+    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<QueryState<TData, TError>>) => () => void;
+    getSubscriberCount: () => number;
+    /**
+     * A deterministic hash string derived from the query variable.
+     *
+     * Used as the unique identifier for this query instance in the internal cache.
+     *
+     * @remarks
+     * - Structurally identical variables will produce the same hash.
+     */
+    variableHash: string;
+    /**
+     * Sets initial data for the query if it has not been initialized.
+     *
+     * @param data - Initial data
+     * @param revalidate - Whether to mark the data as invalidated (will trigger revalidation)
+     *
+     * @returns `true` if the data was set, `false` otherwise
+     *
+     * @remarks
+     * - Only applies when the query is in the `INITIAL` state.
+     * - Useful for hydration or preloaded data.
+     */
+    setInitialData: (data: TData, revalidate?: boolean) => boolean;
+    /**
+     * Executes the query function.
+     *
+     * @param options - Execution options
+     * @param options.overwriteOngoingExecution - Whether to start a new execution instead of reusing an ongoing one (default: `true`)
+     *
+     * @returns A promise resolving to the latest query state
+     *
+     * @remarks
+     * - By default, each call **starts a new execution** even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     * - Handles:
+     *   - Pending state
+     *   - Success state
+     *   - Error state
+     *   - Retry logic
+     */
+    execute: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Re-executes the query if needed based on freshness or invalidation.
+     *
+     * @param options - Revalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns The current state if still fresh, otherwise a promise of the new state
+     *
+     * @remarks
+     * - Skips execution if data is still fresh (`staleTime`) **AND** the query has not been invalidated.
+     * - If execution is not skipped, by default it will start a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    revalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Marks the query as invalidated and optionally triggers re-execution.
+     *
+     * @param options - Invalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns `true` if execution was triggered, `false` otherwise
+     *
+     * @remarks
+     * - Invalidated queries are treated as stale regardless of `staleTime`.
+     * - The next `revalidate` will always execute until a successful result clears the invalidation.
+     * - If there are active subscribers: Execution is triggered immediately.
+     * - Otherwise: The query remains invalidated and will execute on the next revalidation.
+     * - By default, starts a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    invalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => boolean;
+    /**
+     * Resets the query state to its initial state.
+     *
+     * @remarks
+     * - Cancels retry logic and ignores any ongoing execution results.
+     */
+    reset: () => void;
+    /**
+     * Deletes the query store for the current variable.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers.
+     */
+    delete: () => boolean;
+    /**
+     * Performs an optimistic update on the query data.
+     *
+     * @param data - Optimistic data to set
+     *
+     * @returns Controls for managing the optimistic update
+     *
+     * @remarks
+     * - Temporarily replaces the current data.
+     * - Stores previous data for rollback.
+     * - Commonly used with mutations for instant UI updates.
+     *
+     * @example
+     * const { rollback, revalidate } = query.optimisticUpdate(newData);
+     */
+    optimisticUpdate: (data: TData) => {
+        revalidate: () => Promise<QueryState<TData, TError>>;
+        rollback: () => TData;
+    };
+    /**
+     * Restores the data before the last optimistic update.
+     *
+     * @returns The restored data
+     *
+     * @remarks
+     * - Should be used if an optimistic update fails.
+     */
+    rollbackOptimisticUpdate: () => TData;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
+}) & {
+    /**
+     * Executes all query instances.
+     *
+     * @remarks
+     * - Useful for bulk refetching.
+     */
+    executeAll: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => void;
+    /**
+     * Revalidates all query instances.
+     *
+     * @remarks
+     * - Only re-fetches stale queries.
+     */
+    revalidateAll: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => void;
+    /**
+     * Invalidates all query instances.
+     *
+     * @remarks
+     * - Marks all queries as invalidated and triggers revalidation if active.
+     * - Invalidated queries bypass `staleTime` until successfully executed again.
+     */
+    invalidateAll: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => void;
+    /**
+     * Resets all query instances.
+     */
+    resetAll: () => void;
+};
+export {};

package/esm/react/create-store.d.mts

@@ -0,0 +1,35 @@
+import { type InitStoreOptions } from "yuustate/vanilla";
+/**
+ * Creates a single store with a bound React hook.
+ *
+ * @param initialState - The initial state of the store
+ * @param options - Optional lifecycle hooks
+ *
+ * @returns A function that acts as both:
+ * - A React hook for subscribing to the store
+ * - The store API (getState, setState, subscribe, etc.)
+ *
+ * @remarks
+ * - Combines the vanilla store with React integration.
+ * - The returned function can be used directly as a hook.
+ *   - The hook uses Proxy-based tracking to automatically detect which state fields are used.
+ *   - Components will only re-render when the accessed values change.
+ *
+ * @example
+ * const useMyStore = createStore({ foo: 1, bar: 2 });
+ *
+ * function Component() {
+ *   const state = useMyStore();
+ *   return <div>{state.foo}</div>;
+ * }
+ *
+ * useMyStore.setState({ foo: 2 }); // only components using foo will re-render
+ *
+ * @see https://yuustate.vercel.app/docs/store
+ */
+export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => ((options?: {
+    /**
+     * Initial state used on first render (and will also update the store state right after that)
+     */
+    initialState?: Partial<TState>;
+}) => TState) & import("../vanilla.d.mts").StoreApi<TState>;

package/esm/react/create-stores.d.mts

@@ -0,0 +1,76 @@
+import { type InitStoreOptions, type StoreApi } from "yuustate/vanilla";
+type GoodInputForHash = string | number | boolean | null | Date;
+export type StoreKey = GoodInputForHash | {
+    [key: string | number]: StoreKey | StoreKey[];
+};
+type AdditionalStoreApi<TKey> = {
+    /**
+     * The original key used to identify this store instance.\
+     * This value is not hashed and is preserved as-is.
+     */
+    key: TKey;
+    /**
+     * A deterministic hash string derived from {@link key}.
+     *
+     * Used internally as the unique identifier for caching and retrieving store instances.
+     *
+     * @remarks
+     * - Guarantees that structurally identical keys produce the same hash.
+     */
+    keyHash: string;
+    /**
+     * Deletes this store instance from the internal cache.
+     *
+     * @returns `true` if the store was successfully deleted, otherwise `false`.
+     *
+     * @remarks
+     * - If there are active subscribers, the deletion is ignored and `false` is returned.
+     * - When deletion succeeds:
+     *   - The store is removed from the cache.
+     *   - Its state is reset to the initial state.
+     * - Intended for manual cleanup of unused or ephemeral stores.
+     */
+    delete: () => boolean;
+};
+/**
+ * Creates a factory for multiple stores identified by a key.
+ *
+ * @param initialState - The initial state for each store instance
+ * @param options - Optional lifecycle hooks
+ *
+ * @returns A function to retrieve or create a store by key
+ *
+ * @remarks
+ * - Each unique key maps to a separate store instance.
+ * - Keys are deterministically hashed, ensuring stable identity.
+ * - Stores are lazily created and cached.
+ * - Each store has its own state, subscribers, and lifecycle.
+ * - Each returned store includes:
+ *   - React hook (with Proxy-based tracking)
+ *   - Store API methods
+ *   - `delete()` for manual cleanup
+ * - Useful for scenarios like:
+ *   - Query caches
+ *   - Entity-based state
+ *   - Dynamic instances
+ *
+ * @example
+ * const userStore = createStores<{ name: string }, { id: number }>({ name: '' });
+ *
+ * function Component() {
+ *   const useUserStore = userStore({ id: 1 });
+ *   const state = useUserStore();
+ *   return <div>{state.name}</div>;
+ * }
+ *
+ * @see https://yuustate.vercel.app/docs/stores
+ */
+export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, AdditionalStoreApi<TKey>>) => (key?: TKey) => ((options?: {
+    /**
+     * Initial state used on first render (and will also update the store state right after that)
+     *
+     *  If provided, `initialState` will be applied **once per store instance**
+     */
+    initialState?: Partial<TState>;
+}) => TState) & StoreApi<TState> & AdditionalStoreApi<TKey>;
+export {};