@synnaxlabs/pluto 0.43.0 → 0.44.0

package/dist/src/flux/list.d.ts

@@ -0,0 +1,251 @@
+import { Synnax as Client } from '@synnaxlabs/client';
+import { compare, CrudeTimeSpan, Destructor, MultiSeries, record } from '@synnaxlabs/x';
+import { flux } from './aether';
+import { FetchOptions, Params } from './aether/params';
+import { Result } from './result';
+import { CreateRetrieveArgs } from './retrieve';
+import { state } from '../state';
+/**
+ * Function interface for getting items from a list by key(s).
+ *
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+interface GetItem<K extends record.Key, E extends record.Keyed<K>> {
+    /** Get a single item by key, returns undefined if not found */
+    (key: K): E | undefined;
+    /** Get multiple items by an array of keys */
+    (keys: K[]): E[];
+}
+/**
+ * Options for async list operations.
+ */
+interface AsyncListOptions extends FetchOptions {
+    /**
+     * How to modify the list when new data is retrieved. In append mode, new entries
+     * will be added to the end of the list. In replace mode, the list will be replaced
+     * with the new data.
+     */
+    mode?: "append" | "replace";
+}
+/**
+ * Return type for the list hook, providing comprehensive list management utilities.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export type UseListReturn<RetrieveParams extends Params, K extends record.Key, E extends record.Keyed<K>> = Omit<Result<K[]>, "data"> & {
+    /** Function to trigger a list retrieval operation (fire-and-forget) */
+    retrieve: (params: state.SetArg<RetrieveParams, Partial<RetrieveParams>>, options?: AsyncListOptions) => void;
+    /** Function to trigger a list retrieval operation and await the result */
+    retrieveAsync: (params: state.SetArg<RetrieveParams, Partial<RetrieveParams>>, options?: AsyncListOptions) => Promise<void>;
+    /** Array of keys for the items currently in the list */
+    data: K[];
+    /** Function to get items by key, with automatic lazy loading */
+    getItem: GetItem<K, E>;
+    /** Function to subscribe to changes for specific items */
+    subscribe: (callback: () => void, key: K) => Destructor;
+};
+/**
+ * Arguments for retrieving a single item by key.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ */
+export interface RetrieveByKeyArgs<RetrieveParams extends Params, K extends record.Key> {
+    /** Parameters for the retrieve operation */
+    params: Partial<RetrieveParams>;
+    /** The key of the item to retrieve */
+    key: K;
+    /** The Synnax client instance */
+    client: Client;
+}
+/**
+ * Configuration arguments for creating a list query.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export interface CreateListArgs<RetrieveParams extends Params, K extends record.Key, E extends record.Keyed<K>> extends Omit<CreateRetrieveArgs<RetrieveParams, E[]>, "listeners"> {
+    /** Function to retrieve a single item by key for lazy loading */
+    retrieveByKey: (args: RetrieveByKeyArgs<RetrieveParams, K>) => Promise<E | undefined>;
+    /** Optional listeners for real-time list updates */
+    listeners?: ListListenerConfig<RetrieveParams, K, E>[];
+}
+/**
+ * Arguments for using a list hook.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export interface UseListArgs<RetrieveParams extends Params, K extends record.Key, E extends record.Keyed<K>> {
+    /** Initial parameters for the list query */
+    initialParams?: RetrieveParams;
+    /** Optional filter function to apply to items */
+    filter?: (item: E) => boolean;
+    /** Optional function to sort the list */
+    sort?: compare.Comparator<E>;
+    /** Debounce time for retrieve operations */
+    retrieveDebounce?: CrudeTimeSpan;
+}
+/**
+ * List hook function signature.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export interface UseList<RetrieveParams extends Params, K extends record.Key, E extends record.Keyed<K>> {
+    (args?: UseListArgs<RetrieveParams, K, E>): UseListReturn<RetrieveParams, K, E>;
+}
+type ListChangeMode = "prepend" | "append" | "replace";
+interface ListenerOnChangeOptions {
+    mode?: ListChangeMode;
+}
+/**
+ * Extra arguments passed to list listener handlers.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export interface ListListenerExtraArgs<RetrieveParams extends Params, K extends record.Key, E extends record.Keyed<K>> {
+    changed: MultiSeries;
+    /** The current retrieve parameters */
+    params: RetrieveParams;
+    /** The Synnax client instance */
+    client: Client;
+    /** Function to update a specific item in the list */
+    onChange: (key: K, e: state.SetArg<E | null>, opts?: ListenerOnChangeOptions) => void;
+    /** Function to remove an item from the list */
+    onDelete: (key: K) => void;
+}
+/**
+ * Configuration for a list listener that handles real-time updates.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export interface ListListenerConfig<RetrieveParams extends Params, K extends record.Key, E extends record.Keyed<K>> {
+    /** The channel to listen to for real-time updates */
+    channel: string;
+    /** The function to call when a new value is received from the channel */
+    onChange: flux.ListenerHandler<MultiSeries, ListListenerExtraArgs<RetrieveParams, K, E>>;
+}
+/**
+ * Creates a list query hook that provides comprehensive list management with real-time updates.
+ *
+ * This function creates a React hook that handles:
+ * - List data retrieval with loading states
+ * - Individual item lazy loading
+ * - Real-time synchronization with server state
+ * - Pagination and infinite scrolling support
+ * - Item filtering and search
+ * - Optimistic updates and error handling
+ * - Subscribe to individual item changes
+ *
+ * @template P The type of parameters for the list query
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ * @param config Configuration object with list retrieval functions and settings
+ * @returns A React hook for managing the list
+ *
+ * @example
+ * ```typescript
+ * interface UserListParams extends Params {
+ *   department?: string;
+ *   searchTerm?: string;
+ *   offset?: number;
+ *   limit?: number;
+ * }
+ *
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ *   department: string;
+ * }
+ *
+ * const useUserList = createList<UserListParams, number, User>({
+ *   name: "users",
+ *   retrieve: async ({ params, client }) => {
+ *     return await client.users.list(params);
+ *   },
+ *   retrieveByKey: async ({ key, client }) => {
+ *     return await client.users.get(key);
+ *   },
+ *   listeners: [
+ *     {
+ *       channel: "user_updates",
+ *       onChange: ({ changed, onChange, onDelete }) => {
+ *         const updates = changed.get("user_updates");
+ *         updates.forEach(update => {
+ *           if (update.deleted) {
+ *             onDelete(update.id);
+ *           } else {
+ *             onChange(update.id, update);
+ *           }
+ *         });
+ *       }
+ *     }
+ *   ]
+ * });
+ *
+ * // Usage in component
+ * const { data, getItem, retrieve, variant } = useUserList({
+ *   initialParams: { department: "engineering" },
+ *   filter: (user) => user.name.includes("John")
+ * });
+ *
+ * // Get individual user (lazy loaded if not in cache)
+ * const user = getItem(123);
+ *
+ * // Load more users
+ * retrieve({ offset: data.length, limit: 10 }, { mode: "append" });
+ * ```
+ */
+export declare const createList: <P extends Params, K extends record.Key, E extends record.Keyed<K>>({ name, listeners, retrieve, retrieveByKey, }: CreateListArgs<P, K, E>) => UseList<P, K, E>;
+/**
+ * Arguments for the useListItem hook.
+ *
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ */
+export interface UseListItemArgs<K extends record.Key, E extends record.Keyed<K>> extends Pick<UseListReturn<Params, K, E>, "subscribe" | "getItem"> {
+    /** The key of the item to retrieve and subscribe to */
+    key: K;
+}
+/**
+ * Hook for subscribing to and retrieving individual items from a list.
+ *
+ * This hook provides a way to efficiently track individual items from a list
+ * with automatic re-rendering when the item changes. It uses React's
+ * useSyncExternalStore to provide optimal performance.
+ *
+ * @template K The type of the key (must be a record key)
+ * @template E The type of the entity (must be keyed by K)
+ * @param args Configuration object with key and list utilities
+ * @returns The current item data, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const userList = useUserList();
+ * const user = useListItem({
+ *   key: userId,
+ *   subscribe: userList.subscribe,
+ *   getItem: userList.getItem
+ * });
+ *
+ * // Component will re-render when this specific user changes
+ * if (user) {
+ *   return <div>{user.name} - {user.email}</div>;
+ * }
+ * ```
+ */
+export declare const useListItem: <K extends record.Key, E extends record.Keyed<K>>({ key, subscribe, getItem, }: UseListItemArgs<K, E>) => E | undefined;
+export {};
+//# sourceMappingURL=list.d.ts.map

package/dist/src/flux/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/flux/list.ts"],"names":[],"mappings":"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"}

package/dist/src/flux/list.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=list.spec.d.ts.map

package/dist/src/flux/list.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.spec.d.ts","sourceRoot":"","sources":["../../../src/flux/list.spec.tsx"],"names":[],"mappings":""}

package/dist/src/flux/listeners.d.ts

@@ -0,0 +1,4 @@
+import { MultiSeries } from '@synnaxlabs/x';
+import { flux } from './aether';
+export declare const useListener: (listeners: flux.ListenerSpec<MultiSeries, {}> | flux.ListenerSpec<MultiSeries, {}>[]) => void;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/src/flux/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../../src/flux/listeners.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAIrC,eAAO,MAAM,WAAW,GACtB,WAAW,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,KACnF,IAOF,CAAC"}

package/dist/src/flux/listeners.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=listeners.spec.d.ts.map

package/dist/src/flux/listeners.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.spec.d.ts","sourceRoot":"","sources":["../../../src/flux/listeners.spec.tsx"],"names":[],"mappings":""}

package/dist/src/flux/result.d.ts

@@ -0,0 +1,101 @@
+import { status } from '@synnaxlabs/x';
+import { state } from '../state';
+/**
+ * The result of a query operation that can be in one of three states:
+ * - `loading` - Data is currently being fetched from the server
+ * - `error` - An error occurred while fetching data, or while handling values provided
+ *   to a listener
+ * - `success` - Data was successfully fetched and is available in the `data` field
+ *
+ * @template Data The type of data being retrieved, must extend state.State
+ *
+ * @example
+ * ```typescript
+ * const result: Result<User[]> = {
+ *   variant: "success",
+ *   data: [{ id: 1, name: "John" }],
+ *   error: null,
+ *   message: "Retrieved users"
+ * };
+ * ```
+ */
+export type Result<Data extends state.State> = {
+    variant: "error";
+    status: status.Status<status.ExceptionDetails, "error">;
+    data: null;
+    listenersMounted: boolean;
+} | {
+    variant: "success";
+    status: status.Status<undefined, "success">;
+    data: Data;
+    listenersMounted: boolean;
+} | {
+    variant: "loading";
+    status: status.Status<undefined, "loading">;
+    data: null | Data;
+    listenersMounted: boolean;
+};
+/**
+ * Factory function to create a loading result state.
+ *
+ * @template Data The type of data being retrieved
+ * @param name The name of the resource being retrieved (used in status messages)
+ * @param op The operation being performed (e.g., "retrieving", "updating")
+ * @param data Optional existing data to preserve during loading
+ * @returns A Result object in loading state
+ *
+ * @example
+ * ```typescript
+ * const loadingResult = pendingResult<User[]>("users", "retrieving");
+ * // Returns: { variant: "loading", data: null, error: null, message: "Retrieving users" }
+ * ```
+ */
+export declare const pendingResult: <Data extends state.State>(name: string, op: string, data: Data | null, listenersMounted: boolean) => Result<Data>;
+/**
+ * Factory function to create a success result state.
+ *
+ * @template Data The type of data being retrieved
+ * @param name The name of the resource being retrieved (used in status messages)
+ * @param op The operation that was performed (e.g., "retrieved", "updated")
+ * @param data The successfully retrieved data
+ * @returns A Result object in success state
+ *
+ * @example
+ * ```typescript
+ * const successResult = successResult<User[]>("users", "retrieved", userList);
+ * // Returns: { variant: "success", data: userList, error: null, message: "Retrieved users" }
+ * ```
+ */
+export declare const successResult: <Data extends state.State>(name: string, op: string, data: Data, listenersMounted: boolean) => Result<Data>;
+/**
+ * Factory function to create an error result state.
+ *
+ * @template Data The type of data being retrieved
+ * @param name The name of the resource being retrieved (used in status messages)
+ * @param op The operation that failed (e.g., "retrieve", "update")
+ * @param error The error that occurred
+ * @returns A Result object in error state
+ *
+ * @example
+ * ```typescript
+ * const errorResult = errorResult<User[]>("users", "retrieve", new Error("Network error"));
+ * // Returns: { variant: "error", data: null, error: Error, message: "Failed to retrieve users" }
+ * ```
+ */
+export declare const errorResult: <Data extends state.State>(name: string, op: string, error: unknown, listenersMounted: boolean) => Result<Data>;
+/**
+ * Factory function to create an error result for operations that require a connected client.
+ *
+ * @template Data The type of data being retrieved
+ * @param name The name of the resource being retrieved
+ * @param opName The operation that cannot be performed
+ * @returns A Result object in error state with a DisconnectedError
+ *
+ * @example
+ * ```typescript
+ * const result = nullClientResult<User[]>("users", "retrieve");
+ * // Returns error result with message: "Cannot retrieve users because no cluster is connected."
+ * ```
+ */
+export declare const nullClientResult: <Data extends state.State>(name: string, opName: string, listenersMounted: boolean) => Result<Data>;
+//# sourceMappingURL=result.d.ts.map

package/dist/src/flux/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/flux/result.ts"],"names":[],"mappings":"AAUA,OAAO,EAAY,MAAM,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,MAAM,CAAC,IAAI,SAAS,KAAK,CAAC,KAAK,IACvC;IACE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,EAAE,IAAI,CAAC;IACX,gBAAgB,EAAE,OAAO,CAAC;CAC3B,GACD;IACE,OAAO,EAAE,SAAS,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,EAAE,IAAI,CAAC;IACX,gBAAgB,EAAE,OAAO,CAAC;CAC3B,GACD;IACE,OAAO,EAAE,SAAS,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEN;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,SAAS,KAAK,CAAC,KAAK,EACpD,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,MAAM,IAAI,GAAG,IAAI,EACjB,kBAAkB,OAAO,KACxB,MAAM,CAAC,IAAI,CAQZ,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,SAAS,KAAK,CAAC,KAAK,EACpD,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,MAAM,IAAI,EACV,kBAAkB,OAAO,KACxB,MAAM,CAAC,IAAI,CAQZ,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,SAAS,KAAK,CAAC,KAAK,EAClD,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,OAAO,OAAO,EACd,kBAAkB,OAAO,KACxB,MAAM,CAAC,IAAI,CAKZ,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,IAAI,SAAS,KAAK,CAAC,KAAK,EACvD,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,kBAAkB,OAAO,KACxB,MAAM,CAAC,IAAI,CAMX,CAAC"}

package/dist/src/flux/result.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=result.spec.d.ts.map

package/dist/src/flux/result.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.spec.d.ts","sourceRoot":"","sources":["../../../src/flux/result.spec.tsx"],"names":[],"mappings":""}

package/dist/src/flux/retrieve.d.ts

@@ -0,0 +1,213 @@
+import { channel, Synnax as Client } from '@synnaxlabs/client';
+import { MultiSeries } from '@synnaxlabs/x';
+import { flux } from './aether';
+import { FetchOptions, Params } from './aether/params';
+import { Result } from './result';
+import { state } from '../state';
+/**
+ * Extra arguments passed to retrieve listener handlers.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ */
+interface RetrieveListenerExtraArgs<RetrieveParams, Data extends state.State> {
+    /** The current retrieve parameters */
+    params: RetrieveParams;
+    /** The Synnax client instance */
+    client: Client;
+    /** Function that updates the query data when a new value is received */
+    onChange: state.Setter<Data>;
+}
+/**
+ * Configuration for a listener that is called whenever a new value is received
+ * from the specified channel. The listener is called with the new value and can
+ * choose to update the state of the query by calling the `onChange` function.
+ *
+ * The listener will not be called if the query is in a loading or an error state.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ */
+export interface RetrieveListenerConfig<RetrieveParams, Data extends state.State> {
+    /** The channel to listen to for real-time updates */
+    channel: channel.Name;
+    /** The function to call when a new value is received from the channel */
+    onChange: flux.ListenerHandler<MultiSeries, RetrieveListenerExtraArgs<RetrieveParams, Data>>;
+}
+/**
+ * Arguments passed to the `retrieve` function when executing a query.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ */
+export interface RetrieveArgs<RetrieveParams> {
+    /** The Synnax client instance for making requests */
+    client: Client;
+    /** The parameters for the retrieve operation */
+    params: RetrieveParams;
+}
+/**
+ * Configuration arguments for creating a retrieve query.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ */
+export interface CreateRetrieveArgs<RetrieveParams, Data extends state.State> {
+    /**
+     * The name of the resource being retrieved. This is used to make pretty messages for
+     * the various query states. This name should be in a human readable format and
+     * capitalized as a proper noun.
+     */
+    name: string;
+    /** Function executed when the query is evaluated or the query parameters change. */
+    retrieve: (args: RetrieveArgs<RetrieveParams>) => Promise<Data>;
+    /**
+     * Listeners to mount to the query. These listeners will be re-mounted when
+     * the query parameters change and/or the client disconnects/re-connects or clusters
+     * are switched.
+     *
+     * These listeners will NOT be remounted when the identity of the onChange function
+     * changes, as the onChange function should be static.
+     */
+    listeners?: RetrieveListenerConfig<RetrieveParams, Data>[];
+}
+/**
+ * Arguments for the observable retrieve hook.
+ *
+ * @template V The type of data being retrieved
+ */
+export interface UseObservableRetrieveArgs<V extends state.State> {
+    /** Callback function to handle state changes */
+    onChange: state.Setter<Result<V>>;
+}
+/**
+ * Return type for the observable retrieve hook.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ */
+export interface UseObservableRetrieveReturn<RetrieveParams extends Params> {
+    /** Function to trigger a retrieve operation (fire-and-forget) */
+    retrieve: (params: state.SetArg<RetrieveParams, Partial<RetrieveParams>>, options?: FetchOptions) => void;
+    /** Function to trigger a retrieve operation and await the result */
+    retrieveAsync: (params: state.SetArg<RetrieveParams, Partial<RetrieveParams>>, options?: FetchOptions) => Promise<void>;
+}
+/**
+ * Return type for the stateful retrieve hook, combining result state with retrieve functions.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ */
+export type UseStatefulRetrieveReturn<RetrieveParams extends Params, Data extends state.State> = Result<Data> & UseObservableRetrieveReturn<RetrieveParams>;
+/**
+ * Arguments for the direct retrieve hook.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ */
+export interface UseDirectRetrieveArgs<RetrieveParams extends Params> {
+    /** Parameters for the retrieve operation */
+    params: RetrieveParams;
+}
+/**
+ * Return type for the direct retrieve hook.
+ *
+ * @template Data The type of data being retrieved
+ */
+export type UseDirectRetrieveReturn<Data extends state.State> = Result<Data>;
+/**
+ * Arguments for the effect retrieve hook.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ */
+export interface UseEffectRetrieveArgs<RetrieveParams extends Params, Data extends state.State> extends UseObservableRetrieveArgs<Data> {
+    /** Parameters for the retrieve operation */
+    params: RetrieveParams;
+}
+/**
+ * Return type for the createRetrieve function.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ */
+export interface CreateRetrieveReturn<RetrieveParams extends Params, Data extends state.State> {
+    /**
+     * Hook that automatically fetches data when parameters change and returns the result state.
+     * Use this for most cases where you want React to handle the data fetching lifecycle automatically.
+     * Data is fetched when the component mounts and re-fetched whenever params change.
+     */
+    useDirect: (args: UseDirectRetrieveArgs<RetrieveParams>) => UseDirectRetrieveReturn<Data>;
+    /**
+     * Hook that triggers data fetching as a side effect when parameters change but returns nothing.
+     * Use this when you need to trigger data fetching but handle the result state externally
+     * (e.g., through the onChange callback). Returns void - no state is managed internally.
+     */
+    useEffect: (args: UseEffectRetrieveArgs<RetrieveParams, Data>) => void;
+    /**
+     * Hook that provides manual control over when data is fetched, with internal state management.
+     * Use this when you need to trigger data fetching based on user actions or specific events.
+     * Returns both the current state (data, variant, error) and functions to manually trigger retrieval.
+     */
+    useStateful: () => UseStatefulRetrieveReturn<RetrieveParams, Data>;
+}
+/**
+ * Creates a retrieve query system that provides hooks for fetching data with different control patterns.
+ *
+ * This function creates a set of React hooks that handle data retrieval with
+ * proper loading states, error handling, caching, and real-time updates. It provides
+ * two hook variants for different use cases:
+ *
+ * - `useDirect`: Automatically fetches data when parameters change. Best for most use cases.
+ * - `useEffect`: Triggers data fetching as a side effect without returning state. Use when handling results externally.
+ *
+ * @template RetrieveParams The type of parameters for the retrieve operation
+ * @template Data The type of data being retrieved
+ * @param factoryArgs Configuration object containing the retrieve function and resource name
+ * @returns Object containing hooks for different retrieve patterns
+ *
+ * @example
+ * ```typescript
+ * interface UserRetrieveParams extends Params {
+ *   userId: number;
+ *   includeProfile?: boolean;
+ * }
+ *
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userRetrieve = createRetrieve<UserRetrieveParams, User>({
+ *   name: "User",
+ *   retrieve: async ({ params, client }) => {
+ *     return await client.users.get(params.userId, {
+ *       includeProfile: params.includeProfile
+ *     });
+ *   },
+ *   listeners: [
+ *     {
+ *       channel: "user_updates",
+ *       onChange: ({ changed, params, onChange }) => {
+ *         const updatedUser = changed.get("user_updates");
+ *         if (updatedUser.id === params.userId) {
+ *           onChange(updatedUser);
+ *         }
+ *       }
+ *     }
+ *   ]
+ * });
+ *
+ * // Automatic fetching - data loads when component mounts and when userId changes
+ * const { data, variant, error } = userRetrieve.useDirect({
+ *   params: { userId: 123, includeProfile: true }
+ * });
+ *
+ * // Side effect only - trigger fetching but handle result elsewhere
+ * userRetrieve.useEffect({
+ *   params: { userId: 123 },
+ *   onChange: (result) => analyticsService.track('user_loaded', result)
+ * });
+ * ```
+ */
+export declare const createRetrieve: <RetrieveParams extends Params, Data extends state.State>(factoryArgs: CreateRetrieveArgs<RetrieveParams, Data>) => CreateRetrieveReturn<RetrieveParams, Data>;
+export {};
+//# sourceMappingURL=retrieve.d.ts.map

package/dist/src/flux/retrieve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/flux/retrieve.ts"],"names":[],"mappings":"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"}

package/dist/src/flux/retrieve.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=retrieve.spec.d.ts.map

package/dist/src/flux/retrieve.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.spec.d.ts","sourceRoot":"","sources":["../../../src/flux/retrieve.spec.tsx"],"names":[],"mappings":""}