yuustate 0.0.1 → 3.9.0

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

@@ -0,0 +1,343 @@
+import { type InitStoreOptions, type SetStateInput } from "yuustate/vanilla";
+import type { StoreKey } from "./create-stores.mjs";
+type StreamDataState<TData, TError> = {
+    state: "INITIAL";
+    isSuccess: false;
+    isError: false;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: undefined;
+    errorUpdatedAt: undefined;
+} | {
+    state: "SUCCESS";
+    isSuccess: true;
+    isError: false;
+    data: TData;
+    dataUpdatedAt: number;
+    error: undefined;
+    errorUpdatedAt: undefined;
+} | {
+    state: "ERROR";
+    isSuccess: false;
+    isError: true;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: TError;
+    errorUpdatedAt: number;
+} | {
+    state: "SUCCESS_BUT_THEN_ERROR";
+    isSuccess: true;
+    isError: true;
+    data: TData;
+    dataUpdatedAt: number;
+    error: TError;
+    errorUpdatedAt: number;
+};
+/**
+ * Represents the full state of a stream.
+ *
+ * @remarks
+ * A stream consists of two independent concerns:
+ *
+ * 1. **Connection state** — lifecycle of the underlying connection
+ * 2. **Data state** — lifecycle of emitted data
+ *
+ * These two are combined into a single state object.
+ *
+ * ---
+ *
+ * ## Connection lifecycle
+ *
+ * - `INITIAL` → no connection has been established
+ * - `CONNECTING` → connection is being established
+ * - `CONNECTED` → connection is active
+ * - `DISCONNECTED` → connection was previously established but is now closed
+ *
+ * Timestamps:
+ * - `connectingAt` → when connection attempt started
+ * - `connectedAt` → when connection was established
+ * - `disconnectedAt` → when connection was closed
+ *
+ * ---
+ *
+ * ## Data lifecycle
+ *
+ * - `INITIAL` → no data has been received
+ * - `SUCCESS` → data has been received successfully
+ * - `ERROR` → error occurred before any data
+ * - `SUCCESS_BUT_THEN_ERROR` → data exists, but a later error occurred
+ *
+ * ---
+ *
+ * ## Notes
+ *
+ * - Connection state and data state evolve independently.
+ * - A stream may be:
+ *   - connected but have no data yet
+ *   - disconnected but still retain previous data
+ * - Errors do not necessarily reset data.
+ */
+export type StreamState<TData, TError> = ({
+    connectionState: "INITIAL";
+    connectingAt: undefined;
+    connectedAt: undefined;
+    disconnectedAt: undefined;
+} & Extract<StreamDataState<TData, TError>, {
+    state: "INITIAL";
+}>) | ({
+    connectionState: "CONNECTING";
+    connectingAt: number;
+    connectedAt: undefined;
+    disconnectedAt: undefined;
+} & StreamDataState<TData, TError>) | ({
+    connectionState: "CONNECTED";
+    connectingAt: number;
+    connectedAt: number;
+    disconnectedAt: undefined;
+} & StreamDataState<TData, TError>) | ({
+    connectionState: "DISCONNECTED";
+    connectingAt: number;
+    connectedAt: number | undefined;
+    disconnectedAt: number;
+} & StreamDataState<TData, TError>);
+type DisconnectTrigger = "last-unsubscribe" | "document-hidden" | "offline";
+type ReconnectTrigger = "first-subscribe" | "document-visible" | "online";
+type AdditionalStoreApi<TConnection> = {
+    variableHash: string;
+    /**
+     * Connection controls for the stream.
+     *
+     * @remarks
+     * Provides imperative control over the underlying connection.
+     */
+    connection: {
+        /**
+         * Returns the current connection instance.
+         *
+         * @returns The active connection or `undefined` if not connected
+         */
+        get: () => Readonly<TConnection> | undefined;
+        /**
+         * Forces a reconnection.
+         *
+         * @remarks
+         * - Cancels any scheduled disconnect
+         * - Starts a new connection if not already connecting
+         */
+        reconnect: () => void;
+        /**
+         * Immediately disconnects the current connection.
+         *
+         * @remarks
+         * - Ignores disconnect delay rules
+         * - Updates connection state to `DISCONNECTED`
+         */
+        disconnect: () => void;
+    };
+    /**
+     * Data controls for the stream.
+     */
+    data: {
+        /**
+         * Resets the data state back to `INITIAL`.
+         *
+         * @remarks
+         * - Does not affect connection state
+         * - Useful for clearing stale or invalid data
+         */
+        reset: () => void;
+    };
+    /**
+     * Deletes the stream instance.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers
+     * - Clears connection, state, and cached instance
+     */
+    delete: () => boolean;
+};
+/**
+ * Configuration options for a stream.
+ *
+ * @remarks
+ * Controls connection lifecycle, reconnection behavior, and data retention.
+ */
+export type StreamOptions<TConnection, TData, TError = Error> = InitStoreOptions<StreamState<TData, TError>, AdditionalStoreApi<TConnection>> & {
+    /**
+     * Connection-related behavior.
+     */
+    connection?: {
+        /**
+         * Determines when a connection should be disconnected.
+         *
+         * @param trigger - The reason for the disconnect attempt
+         * @param state - Current stream state
+         *
+         * @returns
+         * - `number` → delay (ms) before disconnecting
+         * - `false` → prevent disconnection
+         *
+         * @default Disconnect after 5 seconds for any triggers
+         *
+         * @remarks
+         * Triggers:
+         * - `"last-unsubscribe"` → no active subscribers
+         * - `"document-hidden"` → tab becomes hidden
+         * - `"offline"` → network goes offline
+         */
+        disconnectOn?: (trigger: DisconnectTrigger, state: StreamState<TData, TError>) => false | number;
+        /**
+         * Determines whether a connection should reconnect.
+         *
+         * @param trigger - The reason for the reconnect attempt
+         * @param state - Current stream state
+         *
+         * @returns `true` to reconnect, otherwise `false`
+         *
+         * @default No reconnection if already connected
+         *
+         * @remarks
+         * Triggers:
+         * - `"first-subscribe"` → first subscriber appears
+         * - `"document-visible"` → tab becomes visible
+         * - `"online"` → network reconnects
+         */
+        reconnectOn?: (trigger: ReconnectTrigger, state: StreamState<TData, TError>) => boolean;
+    };
+    /**
+     * Data-related behavior.
+     */
+    data?: {
+        /**
+         * Time (in milliseconds) before unused stream data is garbage collected.
+         *
+         * Starts counting after disconnection.
+         *
+         * @default 5 minutes
+         */
+        gcTime?: number;
+    };
+};
+/**
+ * Creates a stream factory for managing real-time connections.
+ *
+ * @param connect - Function to establish a connection
+ * @param disconnect - Function to close a connection
+ * @param options - Optional configuration for lifecycle and behavior
+ *
+ * @returns A function to retrieve or create a stream instance by variable
+ *
+ * @remarks
+ * - Designed for **long-lived, push-based async sources**, such as: WebSocket, SSE, realtime databases
+ * - A stream consists of two independent concerns:
+ *   1. **Connection state** — lifecycle of the underlying connection
+ *   2. **Data state** — lifecycle of emitted data
+ * - Connection lifecycle:
+ *   - Connection is established when needed (e.g. first subscriber)
+ *   - Connection may be disconnected based on triggers: no subscribers, tab hidden, offline
+ * - Streams are **keyed by variable** (via deterministic hashing).
+ * - Each unique variable maps to its own stream instance.
+ *
+ * ---
+ *
+ * ## Execution model
+ *
+ * - Streams are **lazy**: No connection until there is a subscriber
+ * - Streams are **shared**: Multiple subscribers reuse the same connection
+ * - Streams are **stateful**: Data persists across reconnects (unless reset or GC)
+ *
+ * ---
+ *
+ * @example
+ * const chatStream = createStream(
+ *   (roomId, emit) => {
+ *     const ws = new WebSocket(`/chat/${roomId}`);
+ *
+ *     ws.onopen = () => emit.connected();
+ *     ws.onmessage = (e) => {
+ *       const msg = JSON.parse(e.data);
+ *       emit.data((prev) => [...(prev ?? []), msg]);
+ *     };
+ *     ws.onerror = (err) => emit.error(err);
+ *
+ *     return ws;
+ *   },
+ *   (ws) => ws.close()
+ * );
+ *
+ * function Chat({ roomId }) {
+ *   const useChat = chatStream(roomId);
+ *   const state = useChat();
+ *
+ *   return <div>{state.data?.length}</div>;
+ * }
+ */
+export declare const createStream: <TConnection, TData, TVariable extends StoreKey, TError = Error>(connect: (variable: TVariable, emit: {
+    connected: () => void;
+    data: (reducer: (data: TData | undefined) => TData) => void;
+    error: (error: TError) => void;
+}) => TConnection, disconnect: (connection: TConnection) => void, options?: StreamOptions<TConnection, TData, TError>) => (variable?: TVariable) => ((options?: {
+    initialData?: TData;
+}) => StreamState<TData, TError>) & {
+    setState: (value: SetStateInput<StreamState<TData, TError>>) => void;
+    getState: () => StreamState<TData, TError>;
+    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<StreamState<TData, TError>>) => () => void;
+    getSubscriberCount: () => number;
+    variableHash: string;
+    /**
+     * Connection controls for the stream.
+     *
+     * @remarks
+     * Provides imperative control over the underlying connection.
+     */
+    connection: {
+        /**
+         * Returns the current connection instance.
+         *
+         * @returns The active connection or `undefined` if not connected
+         */
+        get: () => Readonly<TConnection> | undefined;
+        /**
+         * Forces a reconnection.
+         *
+         * @remarks
+         * - Cancels any scheduled disconnect
+         * - Starts a new connection if not already connecting
+         */
+        reconnect: () => void;
+        /**
+         * Immediately disconnects the current connection.
+         *
+         * @remarks
+         * - Ignores disconnect delay rules
+         * - Updates connection state to `DISCONNECTED`
+         */
+        disconnect: () => void;
+    };
+    /**
+     * Data controls for the stream.
+     */
+    data: {
+        /**
+         * Resets the data state back to `INITIAL`.
+         *
+         * @remarks
+         * - Does not affect connection state
+         * - Useful for clearing stale or invalid data
+         */
+        reset: () => void;
+    };
+    /**
+     * Deletes the stream instance.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers
+     * - Clears connection, state, and cached instance
+     */
+    delete: () => boolean;
+};
+export {};

package/esm/react/use-isomorphic-layout-effect.d.mts

@@ -0,0 +1,6 @@
+import { useLayoutEffect } from "react";
+/**
+ * Does exactly same as `useLayoutEffect`.\
+ * It will use `useEffect` in **server-side** to prevent warning when executed on server-side.
+ */
+export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;

package/esm/react/use-mutation.d.mts

@@ -0,0 +1,84 @@
+import { type MutationOptions, type MutationState } from "./create-mutation.mjs";
+/**
+ * A hook for managing async mutation state.
+ *
+ * @param mutationFn - Async function that performs the mutation.
+ * Receives the input variable and the state snapshot before execution.
+ *
+ * @param options - Optional lifecycle callbacks:
+ * - `onSuccess(data, variable, stateBeforeExecute)`
+ * - `onError(error, variable, stateBeforeExecute)`
+ * - `onSettled(variable, stateBeforeExecute)`
+ *
+ * @returns A tuple containing:
+ * - state: The current mutation state (render snapshot)
+ * - controls: An object with mutation actions and helpers
+ *
+ * @remarks
+ * - No retry mechanism is provided by default.
+ * - The mutation always resolves (never throws): the result contains either `data` or `error`.
+ * - If multiple executions triggered at the same time:
+ *   - Only the latest execution is allowed to update the state.
+ *   - Results from previous executions are ignored if a newer one exists.
+ *
+ * @see https://yuustate.vercel.app/docs/mutation
+ */
+export declare const useMutation: <TData, TVariable = undefined, TError = Error>(
+/**
+ * Async function that performs the mutation.
+ *
+ * @remarks
+ * - Does NOT need to be memoized (e.g. `useCallback`).
+ * - The latest function reference is always used internally.
+ */
+mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => Promise<TData>, 
+/**
+ * Optional lifecycle callbacks.
+ *
+ * @remarks
+ * - Callbacks do NOT need to be memoized.
+ * - The latest callbacks are always used internally.
+ */
+options?: MutationOptions<TData, TVariable, TError>) => [MutationState<TData, TVariable, TError>, {
+    /**
+     * 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
+     * - The promise never rejects to simplify async handling.
+     * - If a mutation is already in progress, a warning is logged.
+     * - When a new execution starts, all previous pending executions will resolve with the result of the latest execution.
+     */
+    execute: TVariable extends undefined ? () => Promise<{
+        variable: undefined;
+        data?: TData;
+        error?: TError;
+    }> : (variable: TVariable) => Promise<{
+        variable: TVariable;
+        data?: TData;
+        error?: TError;
+    }>;
+    /**
+     * Resets the mutation state back to its initial state.
+     *
+     * @remarks
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
+     */
+    reset: () => void;
+    /**
+     * Returns the latest mutation state directly from the internal ref.
+     *
+     * @returns The most up-to-date mutation state.
+     *
+     * @remarks
+     * - Unlike the `state` returned by the hook, this value is not tied to React render cycles.
+     * - Use this inside async flows or event handlers to avoid stale reads.
+     */
+    getLatestState: () => MutationState<TData, TVariable, TError>;
+}];

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

@@ -0,0 +1,34 @@
+import { type StoreApi } from "yuustate/vanilla";
+type Path = Array<string | number | symbol>;
+export declare const getValueByPath: (obj: any, path: Path) => any;
+export declare const isPrefixPath: (candidatePrefix: Path, targetPath: Path) => boolean;
+export declare const compressPaths: (paths: Path[]) => Path[];
+export declare const useStoreStateProxy: <TState extends Record<string, any>>(storeState: TState) => readonly [TState, import("react").RefObject<Path[]>];
+export declare const NO_INITIAL_VALUE: {};
+export declare const useStoreStateWithInitializer: <TState extends Record<string, any>>(store: StoreApi<TState>, initialState?: Partial<TState>) => readonly [TState, import("react").RefObject<WeakMap<StoreApi<TState>, number>>];
+/**
+ * React hook for subscribing to a store using automatic dependency tracking.
+ *
+ * @param store - The store instance to subscribe to
+ * @param options - Optional configuration
+ * @param options.initialState - Initial state used on first render (and will also update the store state right after that)
+ *
+ * @returns A proxied version of the store state
+ *
+ * @remarks
+ * - This hook uses a **Proxy-based tracking mechanism** to detect which parts of the state are accessed during render.
+ * - The component will only re-render when the **accessed values actually change**.
+ * - State must be treated as **immutable**:
+ *   - Updates must replace objects rather than mutate them
+ *   - Otherwise, changes may not be detected
+ * - If provided, `initialState` will be applied **once per store instance**
+ *
+ * @example
+ * const state = useStoreState(store);
+ * return <div>{state.user.name}</div>;
+ * // Component will only re-render if `user.name` changes
+ */
+export declare const useStoreState: <TState extends Record<string, any>>(store: StoreApi<TState>, options?: {
+    initialState?: Partial<TState>;
+}) => TState;
+export {};

package/esm/react.d.mts

@@ -0,0 +1,8 @@
+export * from "./react/use-isomorphic-layout-effect.mjs";
+export { useStoreState } from "./react/use-store.mjs";
+export * from "./react/create-store.mjs";
+export * from "./react/create-stores.mjs";
+export * from "./react/create-query.mjs";
+export { createMutation, type MutationOptions, type MutationState, } from "./react/create-mutation.mjs";
+export * from "./react/use-mutation.mjs";
+export * from "./react/create-stream.mjs";