floppy-disk 3.6.1 → 3.7.0-beta.2

package/react/create-query.d.ts

@@ -56,22 +56,156 @@ export type QueryState<TData, TError> = {
 } | {
     state: "SUCCESS_BUT_REVALIDATION_ERROR";
     isSuccess: true;
-    isError: false;
+    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>, {
-    variableHash: string;
-}> & {
+export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, AdditionalStoreApi<TData, TError>> & {
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
@@ -219,19 +353,19 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
     initialData?: never;
     initialDataIsStale?: never;
 })) => QueryState<TData, TError>) & {
-    variableHash: string;
+    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    getState: () => QueryState<TData, TError>;
+    subscribe: (subscriber: import("../vanilla.ts").Subscriber<QueryState<TData, TError>>) => () => void;
+    getSubscriberCount: () => number;
     /**
-     * Internal data, do not mutate!
+     * 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.
      */
-    metadata: {
-        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;
-    };
+    variableHash: string;
     /**
      * Sets initial data for the query if it has not been initialized.
      *
@@ -344,10 +478,10 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
      * - Should be used if an optimistic update fails.
      */
     rollbackOptimisticUpdate: () => TData;
-    subscribe: (subscriber: import("../vanilla.ts").Subscriber<QueryState<TData, TError>>) => () => void;
-    getSubscriberCount: () => number;
-    getState: () => QueryState<TData, TError>;
-    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
 }) & {
     /**
      * Executes all query instances.
@@ -382,3 +516,4 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
      */
     resetAll: () => void;
 };
+export {};

package/react/create-stores.d.ts

@@ -1,8 +1,37 @@
-import { type InitStoreOptions } from "../vanilla.ts";
+import { type InitStoreOptions, type StoreApi } from "../vanilla.ts";
 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.
  *
@@ -36,23 +65,12 @@ export type StoreKey = GoodInputForHash | {
  *
  * @see https://floppy-disk.vercel.app/docs/stores
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, {
-    key: TKey;
-    keyHash: string;
-}>) => (key?: TKey) => ((options?: {
+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) & {
-    delete: () => boolean;
-    setState: (value: import("../vanilla.ts").SetStateInput<TState>) => void;
-    getState: () => TState;
-    subscribe: (subscriber: import("../vanilla.ts").Subscriber<TState>) => () => void;
-    getSubscriberCount: () => number;
-    key: TKey;
-    keyHash: string;
-};
+}) => TState) & StoreApi<TState> & AdditionalStoreApi<TKey>;
 export {};

package/react/create-stream.d.ts

@@ -0,0 +1,88 @@
+import { type InitStoreOptions, type StoreApi } from "../vanilla.ts";
+import type { StoreKey } from "./create-stores.ts";
+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;
+};
+export type StreamState<TData, TError> = ({
+    connectionState: "INITIAL";
+    connectingAt: undefined;
+    connectedAt: undefined;
+    disconnectedAt: undefined;
+} & Extract<StreamDataState<TData, TError>, {
+    state: "INITIAL";
+}>) | ({
+    connectionState: "CONNECTING";
+    connectingAt: number;
+    connectedAt: number | undefined;
+    disconnectedAt: number | 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: {
+        get: () => Readonly<TConnection> | undefined;
+        reconnect: () => void;
+        disconnect: () => void;
+    };
+    data: {
+        reset: () => void;
+    };
+};
+export type StreamOptions<TConnection, TData, TError = Error> = InitStoreOptions<StreamState<TData, TError>, AdditionalStoreApi<TConnection>> & {
+    connection?: {
+        disconnectOn?: (trigger: DisconnectTrigger, state: StreamState<TData, TError>) => false | number;
+        reconnectOn?: (trigger: ReconnectTrigger, state: StreamState<TData, TError>) => boolean;
+    };
+    data?: {
+        gcTime?: number;
+    };
+};
+export declare const experimental_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>) & StoreApi<StreamState<TData, TError>> & AdditionalStoreApi<TConnection>;
+export {};

package/react.d.ts

@@ -5,3 +5,4 @@ export * from "./react/create-stores.ts";
 export * from "./react/create-query.ts";
 export { createMutation, type MutationOptions, type MutationState, } from "./react/create-mutation.ts";
 export * from "./react/use-mutation.ts";
+export * from "./react/create-stream.ts";