@pixotope/query 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,61 +1,266 @@
 import * as _pixotope_zmq_client from '@pixotope/zmq-client';
 import { ZMQClient, TSocketServerCallOptions, ZMQProxyWSClient } from '@pixotope/zmq-client';
 
+/**
+ * Configuration options for {@link useQuery}.
+ *
+ * @typeParam TData - The raw data type returned by `queryFn`.
+ * @typeParam TError - The error type reported to `onError`/`onSettled` and exposed via `error`.
+ * @typeParam TParams - The type of the parameters passed to `refetch`/`queryFn`.
+ * @typeParam TSelectData - The type of the data after `select` has been applied. Defaults to `TData`.
+ * @typeParam Stateless - When `true`, the hook does not keep fetched data in state (see {@link QueryOptions.stateless}).
+ */
 interface QueryOptions<TData = unknown, TError = unknown, TParams = void, TSelectData = TData, Stateless extends true | undefined = undefined> {
+    /**
+     * Function that fetches the data for this query. Called automatically on mount, whenever
+     * `key` changes, and whenever `refetch` is invoked.
+     * @param params - The params passed to `refetch`, or `undefined`/`void` for an automatic fetch.
+     * @param queryInfo - Contextual info about the current query: `key` is the normalized query
+     * key currently in use, and `lastFetchedAt` is the timestamp (ms) of the last successful fetch,
+     * or `undefined` if the query has never succeeded.
+     * @returns A promise that resolves with the fetched data.
+     */
     queryFn: (params: TParams | undefined | void, queryInfo: {
         key: TQueryKey | undefined;
         lastFetchedAt: number | undefined;
     }) => Promise<TData>;
+    /** Called after `queryFn` resolves successfully, with the raw (pre-`select`) data. */
     onSuccess?: (data: TData) => Promise<void> | void;
+    /** Called after `queryFn` rejects, or after `compareOrThrow` reports a failed comparison. */
     onError?: (error: TQueryError<TError>) => Promise<void> | void;
+    /**
+     * Called after every fetch attempt settles, whether it succeeded or failed. Exactly one of
+     * `data`/`error` will be defined.
+     */
     onSettled?: (data: TData | undefined, error: TQueryError<TError> | undefined) => Promise<void> | void;
+    /**
+     * Maximum time, in milliseconds, to wait for `queryFn` to resolve before the query is
+     * considered failed with a `timeout` error. When omitted, the query never times out.
+     */
     timeout?: number;
+    /**
+     * Whether the query is allowed to fetch. When `false`, `queryFn` is not called on mount,
+     * on `key` changes, or on an interval/focus refetch.
+     * @default true
+     */
     enabled?: boolean;
+    /**
+     * Data (or a function returning data) to seed `data` with before the first fetch resolves.
+     */
     initialData?: TData | Functionize<TData>;
+    /**
+     * Transforms the raw fetched data into the shape consumers should receive via `data`. Applied
+     * on every render, not just on fetch, so it should be cheap and side-effect free.
+     */
     select?: (data: TData) => TSelectData;
+    /**
+     * Whether to automatically refetch when the browser window regains focus.
+     * @default false
+     */
     refetchOnWindowFocus?: boolean;
+    /**
+     * When greater than `0`, automatically refetches on this interval (in milliseconds), as long
+     * as at least this much time has passed since the last successful fetch.
+     * @default 0
+     */
     refetchInterval?: number;
+    /**
+     * Function that will be called with the freshly fetched data before it is stored. Returning
+     * `true` causes the fetch to be treated as a failure (status becomes `"error"`, `onError`/
+     * `onSettled` are called) instead of a success.
+     */
     compareOrThrow?: (data: TData) => boolean;
+    /**
+     * Whether the query is stateless. When `true`, fetched data is not stored by the hook and the
+     * returned object will not include a `data` field.
+     * @default false
+     */
     stateless?: Stateless;
+    /**
+     * The query key. Whenever this array's serialized value changes, the query automatically
+     * refetches. Pass a stable/memoized array to avoid unintended refetches.
+     */
     key?: TQueryKey;
 }
+/** A value, or a function returning it. Used to type {@link QueryOptions.initialData}. */
 type Functionize<T> = () => T;
+/** The status of a {@link useQuery} call, as exposed via {@link UseQueryResult}'s `status`. */
 type QueryStatus = "idle" | "loading" | "success" | "error" | "timeout";
-type WithData$1<TData> = {
+/** Adds the `data` field to {@link UseQueryResult} when the query is not {@link QueryOptions.stateless}. */
+type WithQueryData<TData> = {
     data: TData | undefined;
 };
+/** The type of {@link QueryOptions.key}: an array whose serialized value determines when the query refetches. */
 type TQueryKey = readonly any[];
+/** The error type exposed via {@link UseQueryResult}'s `error` and passed to `onError`/`onSettled`. */
 type TQueryError<TError> = TError | Error | null;
+/**
+ * The value returned by {@link useQuery}.
+ *
+ * @typeParam TData - The (post-`select`) data type exposed via `data`.
+ * @typeParam TError - The error type exposed via `error`.
+ * @typeParam TParams - The type of the parameters accepted by `refetch`.
+ * @typeParam TSelectData - The type of the data after `select` has been applied.
+ * @typeParam Stateless - When `true`, the `data` field is omitted from the result.
+ */
 type UseQueryResult<TData = unknown, TError = unknown, TParams = void, TSelectData = TData, Stateless extends true | undefined = undefined> = {
+    /** The error from the most recent failed fetch, or `null` if the last fetch succeeded (or none has happened yet). */
     error: TQueryError<TError>;
+    /** The current status of the query: `"idle"`, `"loading"`, `"success"`, `"error"`, or `"timeout"`. */
     status: QueryStatus;
+    /**
+     * Manually triggers a fetch, bypassing `enabled`'s effect on automatic fetches (it still
+     * respects the current `enabled` value at call time).
+     * @param params - Params to pass to `queryFn` for this fetch.
+     * @returns A promise that resolves once the fetch has settled.
+     */
     refetch: (params: TParams | void | undefined) => Promise<void>;
+    /** Clears `data`, `error` and `status` back to their initial values, then triggers a refetch. */
     reset: () => void;
-} & (Stateless extends true ? {} : WithData$1<TSelectData>);
+} & (Stateless extends true ? {} : WithQueryData<TSelectData>);
+/**
+ * React hook for fetching, caching (per-render, in component state) and refetching async data.
+ *
+ * `queryFn` runs automatically on mount, whenever `key` changes, and whenever `refetch` is
+ * called. It races against `timeout` (when provided), and its result is exposed via `data`
+ * (after `select`, if provided), `status`, and `error`.
+ *
+ * @typeParam TData - The raw data type returned by `queryFn`.
+ * @typeParam TError - The error type surfaced via `error` and `onError`.
+ * @typeParam TParams - The type of the parameters accepted by `refetch`.
+ * @typeParam TSelected - The type of the data after `select` has been applied. Defaults to `TData`.
+ * @typeParam Stateless - When `true`, the hook does not keep fetched data in state.
+ * @param options - See {@link QueryOptions}.
+ * @returns See {@link UseQueryResult}.
+ * @example
+ * ```tsx
+ * const { data, status, error, refetch } = useQuery({
+ *   key: ["user", userId],
+ *   queryFn: () => fetchUser(userId),
+ * });
+ * ```
+ */
 declare const useQuery: <TData = unknown, TError = unknown, TParams = void, TSelected = TData, Stateless extends true | undefined = undefined>({ queryFn, ...options }: QueryOptions<TData, TError, TParams, TSelected, Stateless>) => UseQueryResult<TSelected, TError, TParams, TSelected, Stateless>;
 
+/**
+ * The async function a mutation invokes to perform its side effect.
+ * @typeParam TData - The type of data the mutation resolves with.
+ * @typeParam TParams - The type of the variables passed in to trigger the mutation.
+ * @typeParam TMetadata - The type of the optional, per-call metadata.
+ * @param params - The variables for this mutation call.
+ * @param meta - Optional per-call metadata, passed through unchanged from `mutate`/`mutateAsync`.
+ * @returns A promise that resolves with the mutation's result.
+ */
 type MutationFunction<TData = unknown, TParams = unknown, TMetadata = unknown> = (params: TParams, meta?: TMetadata) => Promise<TData>;
+/**
+ * Configuration options for {@link useMutation}.
+ *
+ * @typeParam TData - The type of data `mutationFn` resolves with.
+ * @typeParam TError - The error type reported to `onError`/`onSettled` and exposed via `error`.
+ * @typeParam TParams - The type of the variables passed in to trigger the mutation.
+ * @typeParam TMetadata - The type of the optional, per-call metadata.
+ */
 interface MutationOptions<TData = unknown, TError = unknown, TParams = void, TMetadata = unknown> {
+    /** The async function invoked by `mutate`/`mutateAsync` to perform the mutation. */
     mutationFn: MutationFunction<TData, TParams, TMetadata>;
+    /** Default variables passed to `prepareParams` (as its `defaults` argument) for every call. */
     params?: TParams;
+    /** Called after `mutationFn` resolves successfully. */
     onSuccess?: (data: TData, variables: TParams, meta?: TMetadata) => Promise<unknown> | unknown;
+    /** Called after `mutationFn` rejects, or after `compareOrThrow` reports a failed comparison. */
     onError?: (error: TMutationError<TError>, variables: TParams, meta?: TMetadata) => Promise<unknown> | unknown;
+    /**
+     * Called after every mutation attempt settles, whether it succeeded or failed. Exactly one of
+     * `data`/`error` will be defined.
+     */
     onSettled?: (data: TData | undefined, error: TMutationError<TError> | null, variables: TParams, meta?: TMetadata) => Promise<unknown> | unknown;
+    /**
+     * Function that will be called with the result of `mutationFn` before it is stored. Returning
+     * `true` causes the call to fail with a {@link ComparisonFailError} instead of succeeding.
+     */
     compareOrThrow?: (result: TData | TError) => boolean;
+    /**
+     * Maximum time, in milliseconds, to wait for `mutationFn` to resolve before the call is
+     * considered failed with a `timeout` error. When omitted, the call never times out.
+     */
     timeout?: number;
+    /**
+     * Transforms the variables passed to `mutate`/`mutateAsync` before they reach `mutationFn`.
+     * @param variables - The variables passed to this call.
+     * @param defaults - The `params` configured on the hook, if any.
+     * @param meta - The per-call metadata, if any.
+     * @returns The variables to actually pass to `mutationFn`.
+     */
     prepareParams?: (variables: TParams, defaults?: TParams, meta?: TMetadata) => TParams;
 }
+/** The error type exposed via `error`/`onError`/`onSettled` on {@link MutationOptions}, {@link MutateOptions}, and {@link useMutation}'s return value. */
 type TMutationError<TError> = TError | Error | null;
+/**
+ * Per-call callback overrides accepted as the second argument to `mutate` (see
+ * {@link useMutation}'s return value). Called in addition to the callbacks configured via
+ * {@link MutationOptions}.
+ *
+ * @typeParam TData - The type of data the mutation resolves with.
+ * @typeParam TError - The error type reported to `onError`/`onSettled`.
+ * @typeParam TParams - The type of the variables passed in to trigger the mutation.
+ * @typeParam TMetadata - The type of the optional, per-call metadata.
+ */
 interface MutateOptions<TData = unknown, TError = unknown, TParams = void, TMetadata = unknown> {
+    /** Called after `mutationFn` resolves successfully. */
     onSuccess?: (data: TData, variables: TParams, meta?: TMetadata) => void;
+    /** Called after `mutationFn` rejects, or after `compareOrThrow` reports a failed comparison. */
     onError?: (error: TMutationError<TError>, variables: TParams, meta?: TMetadata) => void;
+    /**
+     * Called after every mutation attempt settles, whether it succeeded or failed. Exactly one of
+     * `data`/`error` will be defined.
+     */
     onSettled?: (data: TData | undefined, error: TMutationError<TError> | null, variables: TParams, meta?: TMetadata) => void;
 }
+/** The status of a {@link useMutation} call, as exposed via its return value's `status`. */
 type MutationStatus = "idle" | "loading" | "success" | "error";
+/**
+ * Error thrown (and stored as the mutation's `error`) when a mutation's `compareOrThrow` option
+ * returns `true` for a successfully resolved result, i.e. the call is treated as a failure
+ * despite `mutationFn` not rejecting.
+ *
+ * @typeParam TPayload - The type of the offending result, available via `payload`.
+ */
 declare class ComparisonFailError<TPayload = unknown> extends Error {
+    /** The result that `compareOrThrow` rejected. */
     readonly payload: TPayload;
+    /**
+     * @param message - The error message.
+     * @param payload - The result that `compareOrThrow` rejected, preserved on the error.
+     */
     constructor(message: string, payload: TPayload);
 }
+/**
+ * React hook for triggering an async side effect (a "mutation") and tracking its status, result
+ * and error, without fetching automatically the way {@link useQuery} does.
+ *
+ * @typeParam TData - The type of data `mutationFn` resolves with.
+ * @typeParam TError - The error type surfaced via `error` and `onError`.
+ * @typeParam TParams - The type of the variables passed in to trigger the mutation.
+ * @typeParam TMetadata - The type of the optional, per-call metadata.
+ * @param options - See {@link MutationOptions}.
+ * @returns An object with:
+ *  - `status` - the current status: `"idle"`, `"loading"`, `"success"`, or `"error"`.
+ *  - `result` - the data from the most recently successful call, if any.
+ *  - `error` - the error from the most recently failed call, if any.
+ *  - `mutate` - fire-and-forget trigger; accepts per-call `variables` and, optionally,
+ *    {@link MutateOptions} plus `meta`.
+ *  - `mutateAsync` - same as `mutate`, but returns the promise from `mutationFn` (rejects on
+ *    failure) so callers can `await` it.
+ *  - `reset` - resets `status`, `result` and `error` back to their initial values.
+ * @example
+ * ```tsx
+ * const { mutate, status } = useMutation({
+ *   mutationFn: (vars: { name: string }) => createUser(vars),
+ * });
+ *
+ * mutate({ name: "Ada" }, { onSuccess: (user) => console.log(user.id) });
+ * ```
+ */
 declare const useMutation: <TData = unknown, TError = unknown, TParams = void, TMetadata = unknown>(options: MutationOptions<TData, TError, TParams, TMetadata>) => {
     mutateAsync: (params: TParams, meta?: TMetadata) => Promise<TData>;
     status: MutationStatus;
@@ -67,12 +272,36 @@ declare const useMutation: <TData = unknown, TError = unknown, TParams = void, T
     error: TMutationError<TError>;
 };
 
+/**
+ * Describes the data/error/params types for a single remote function, keyed by function name in
+ * a `TFnToParams` map. Used with {@link buildMutationHook} and {@link buildQueryHook} to give the
+ * hooks they build full type inference for `func`, its params and its result, based on the
+ * function name passed in.
+ *
+ * @example
+ * ```ts
+ * type MyFunctions = {
+ *   createUser: MutationInfo<User, ApiError, { name: string }>;
+ * };
+ * ```
+ */
 type MutationInfo<TData, TError, TParams> = {
     data: TData;
     error: TError;
     params: TParams;
 };
+/** The constraint a `TFnToParams` map must satisfy for {@link buildMutationHook}/{@link buildQueryHook}: a record of function name to its {@link MutationInfo}. */
 type FnToParamsBase = Record<string, MutationInfo<unknown, unknown, unknown>>;
+/**
+ * The shape of a ZMQ remote-call function, as bound by {@link bindPromiseFunction}. Given a
+ * service/function/parameters triple, it performs the call and resolves with the response.
+ *
+ * @typeParam TResponse - The type of data the call resolves with.
+ * @typeParam TParams - The type of the `parameters` sent with the call.
+ * @typeParam TExtraParams - The type of the optional `meta` passed alongside the call.
+ * @param args - The service and function to call, its parameters, and call options/metadata.
+ * @returns A promise that resolves with the call's result.
+ */
 type TPromiseFunction<TResponse, TParams, TExtraParams> = (args: Omit<ZMQClient.Call<TResponse, {
     functionName: string;
     parameters: TParams;
@@ -80,123 +309,217 @@ type TPromiseFunction<TResponse, TParams, TExtraParams> = (args: Omit<ZMQClient.
 }>, "id"> & {
     meta?: TExtraParams;
 }) => Promise<TResponse>;
+/**
+ * Internal helper backing the hook returned by {@link buildMutationHook}. Wraps a ZMQ
+ * `promiseFunc` call for a single remote function name into a {@link useMutation} instance.
+ */
 declare const useCallMutationBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TMetadata = unknown>(promiseFunc: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, service: (meta?: TMetadata) => string, options?: Omit<MutationOptions<TData, TError, TParams, TMetadata>, "mutationFn">) => {
     mutateAsync: (params: TParams, meta?: TMetadata | undefined) => Promise<TData>;
-    status: "idle" | "loading" | "success" | "error";
+    status: MutationStatus;
     result: TData | undefined;
     mutate: (variables: TParams, options?: (MutateOptions<TData, TError, TParams, TMetadata> & {
         meta?: TMetadata | undefined;
     }) | undefined) => void;
     reset: () => void;
-    error: Error | TError | null;
+    error: TMutationError<TError>;
 };
+/**
+ * Builds a `useMutation`-like hook for calling remote ZMQ functions by name, with full type
+ * inference of `data`/`error`/`params` from the `TFnToParams` map.
+ *
+ * This is the recommended way to expose a typed mutation hook for a service: call this once
+ * with a bound {@link TPromiseFunction} (see {@link bindPromiseFunction}) and a function that
+ * resolves the target service name, then export the resulting hook for consumers.
+ *
+ * @typeParam TFnToParams - A map from remote function name to its {@link MutationInfo}
+ * (data/error/params types).
+ * @typeParam TMetadata - The type of the optional metadata forwarded to `genTargetService` and `promiseFunc`.
+ * @param promiseFunc - The transport function that performs the actual remote call.
+ * @param genTargetService - Resolves the target service name for a call, given its metadata.
+ * @returns A `useCallMutationBuilder` hook: call it with a function name (a key of
+ * `TFnToParams`) and the same options as {@link useMutation} (minus `mutationFn`) to get a
+ * mutation scoped to that remote function.
+ * @example
+ * ```ts
+ * const useCreateUser = buildMutationHook<MyFunctions>(
+ *   bindPromiseFunction(proxyClient),
+ *   () => "UserService"
+ * );
+ * ```
+ */
 declare function buildMutationHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunc: TPromiseFunction<unknown, unknown, unknown>, genTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams>(func: TFn, options?: Parameters<typeof useCallMutationBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TMetadata>>[3]) => {
     mutateAsync: (params: TFnToParams[TFn]["params"], meta?: TMetadata | undefined) => Promise<TFnToParams[TFn]["data"]>;
-    status: "idle" | "loading" | "success" | "error";
+    status: MutationStatus;
     result: TFnToParams[TFn]["data"] | undefined;
     mutate: (variables: TFnToParams[TFn]["params"], options?: (MutateOptions<TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TMetadata> & {
         meta?: TMetadata | undefined;
     }) | undefined) => void;
     reset: () => void;
-    error: Error | TFnToParams[TFn]["error"] | null;
+    error: TMutationError<TFnToParams[TFn]["error"]>;
 };
-declare const useCallQueryBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TSelect = TData, TMetadata = unknown>(promiseFunction: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, params: TParams, service: (meta?: TMetadata) => string, options?: Omit<QueryOptions<TData, TError, TParams, TSelect>, "queryFn"> & {
+/**
+ * Internal helper backing the hook returned by {@link buildQueryHook}. Wraps a ZMQ
+ * `promiseFunction` call for a single remote function name into a {@link useQuery} instance.
+ */
+declare const useCallQueryBase: <TFnToParams extends FnToParamsBase, TData = unknown, TError = unknown, TParams = unknown, TSelect = TData, TMetadata = unknown, TStateless extends true | undefined = undefined>(promiseFunction: TPromiseFunction<TData, TParams, TMetadata>, functionName: keyof TFnToParams, params: TParams, service: (meta?: TMetadata) => string, options?: Omit<QueryOptions<TData, TError, TParams, TSelect, TStateless>, "queryFn"> & {
     meta?: TMetadata;
-}) => UseQueryResult<TSelect, TError, TParams, TSelect, undefined>;
-declare function buildQueryHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunction: TPromiseFunction<unknown, unknown, unknown>, getTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams, TSelect = TFnToParams[TFn]["data"]>(func: TFn, params: TFnToParams[TFn]["params"], options?: Parameters<typeof useCallQueryBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, TMetadata>>[4] & {
+}) => UseQueryResult<TSelect, TError, TParams, TSelect, TStateless>;
+/**
+ * Builds a `useQuery`-like hook for calling remote ZMQ functions by name, with full type
+ * inference of `data`/`error`/`params` from the `TFnToParams` map.
+ *
+ * This is the recommended way to expose a typed query hook for a service: call this once with a
+ * bound {@link TPromiseFunction} (see {@link bindPromiseFunction}) and a function that resolves
+ * the target service name, then export the resulting hook for consumers.
+ *
+ * @typeParam TFnToParams - A map from remote function name to its {@link MutationInfo}
+ * (data/error/params types).
+ * @typeParam TMetadata - The type of the optional metadata forwarded to `getTargetService` and `promiseFunction`.
+ * @param promiseFunction - The transport function that performs the actual remote call.
+ * @param getTargetService - Resolves the target service name for a call, given its metadata.
+ * @returns A `useCallQueryBuilder` hook: call it with a function name (a key of `TFnToParams`),
+ * the params for that call, and the same options as {@link useQuery} (minus `queryFn`) to get a
+ * query scoped to that remote function.
+ * @example
+ * ```ts
+ * const useGetUser = buildQueryHook<MyFunctions>(
+ *   bindPromiseFunction(proxyClient),
+ *   () => "UserService"
+ * );
+ *
+ * const { data } = useGetUser("getUser", { id: userId });
+ * ```
+ */
+declare function buildQueryHook<TFnToParams extends FnToParamsBase, TMetadata = unknown>(promiseFunction: TPromiseFunction<unknown, unknown, unknown>, getTargetService: (meta?: TMetadata) => string): <TFn extends keyof TFnToParams, TSelect = TFnToParams[TFn]["data"], TStateless extends true | undefined = undefined>(func: TFn, params: TFnToParams[TFn]["params"], options?: Parameters<typeof useCallQueryBase<TFnToParams, TFnToParams[TFn]["data"], TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, TMetadata, TStateless>>[4] & {
     meta?: TMetadata;
-}) => UseQueryResult<TSelect, TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, undefined>;
+}) => UseQueryResult<TSelect, TFnToParams[TFn]["error"], TFnToParams[TFn]["params"], TSelect, TStateless>;
 
 /**
- * @fileoverview useSubscriptionCore
- * @name useSubscriptionCore.ts
- * @description useSubscriptionCore | This hook handle core subscription logic
- * and provides a way to subscribe and unsubscribe to a topic via any callback
+ * Core subscription logic: subscribe and unsubscribe to a topic via any
+ * callback-based transport. See {@link useSubscriptionCore}.
  */
+/** The status of a {@link useSubscriptionCore} subscription, as exposed via {@link WithStatus.status}. */
 type SubscriptionState = "idle" | "subscribed" | "subscribing" | "error";
+/** A function invoked with each message received on the subscription. */
 type MessageHandler<TMessage> = (message: TMessage) => void;
+/**
+ * Handle passed to a {@link SubscriptionCoreOptions.subscriberFn} implementation so it can report
+ * subscription lifecycle events back into the hook.
+ */
 type Connection = {
+    /** Marks the subscription as `"subscribed"`. Call this once the subscription is confirmed active. */
     acknowledge: () => void;
 };
+/**
+ * Configuration options for {@link useSubscriptionCore}.
+ *
+ * @typeParam TData - The data type exposed via `data`, after `select` (if provided).
+ * @typeParam TMessage - The raw message type passed to `subscriberFn`'s handler.
+ * @typeParam Stateless - When `true`, the hook does not keep the latest message in state.
+ */
 type SubscriptionCoreOptions<TData, TMessage = TData, Stateless extends true | undefined = undefined> = {
-    /**
-     * @description Function that will be called when the message is received.
-     */
+    /** Function that will be called when the message is received. */
     onMessage?: (message: TMessage) => void;
-    /**
-     * @description Function that will be called when the subscription is created.
-     */
+    /** Function that will be called when the subscription is created. */
     onSubscribed?: (message: TMessage) => void;
-    /**
-     * @description Function that will be called when the subscription is created.
-     */
+    /** Function that will be called when the subscription errors. */
     onError?: (error: TMessage) => void;
     /**
-     * @description Whether the subscription is enabled.
+     * Whether the subscription is enabled.
      * @default true
      */
     enabled?: boolean;
     /**
-     * @description Function that will be called before the message is processed.
+     * Function that will be called before the message is processed.
      * Returning `true` will cause the message to not be set to state and call {@link onError} if provided.
      * Status will be set to `error`.
      */
     compareOrThrow?: (data: TMessage) => boolean;
-    /**
-     * @description Function that will be called to select the data from the message.
-     */
+    /** Function that will be called to select the data from the message. */
     select?: (data: TMessage) => TData;
     /**
-     * @description Initial state of the subscription.
+     * Initial state of the subscription.
      * @default undefined
      */
     initialState?: TData;
-    /**
-     * @description Function that will be called when the subscription is created.
-     */
+    /** Function that will be called when the subscription is created. */
     subscriberFn: (handler: MessageHandler<TMessage>, connection: Connection) => () => void /** unsubscribe Fn */;
     /**
-     * @description Whether the subscription is stateless. Data will not be
+     * Whether the subscription is stateless. Data will not be
      * stored by the hook internally.
      * @default false
      */
     stateless?: Stateless;
     /**
-     * @description Custom equality function for comparing data.
+     * Custom equality function for comparing data.
      * @default shallowEqual
      */
     isEqual?: <T = TData>(a: T, b: T) => boolean;
 };
+/** Adds the `status` field to {@link SubscriptionCoreReturnType}. */
 type WithStatus = {
     status: SubscriptionState;
 };
-type WithData<TData> = {
+/** Adds the `data` field to {@link SubscriptionCoreReturnType}. */
+type WithSubscriptionData<TData> = {
     data: TData;
 };
+/**
+ * The value returned by {@link useSubscriptionCore}.
+ *
+ * @typeParam TData - The data type exposed via `data`.
+ * @typeParam Stateless - When `true`, `status` and `data` are omitted from the result.
+ */
 type SubscriptionCoreReturnType<TData, Stateless extends true | undefined> = {
+    /** Unsubscribes (if currently subscribed) and immediately subscribes again. */
     reSubscribe: () => void;
-} & (Stateless extends true ? {} : WithStatus & WithData<TData>);
+} & (Stateless extends true ? {} : WithStatus & WithSubscriptionData<TData>);
 /**
- * @description `useSubscriptionCore` | This hook handle core subscription logic
- * and provides a way to subscribe and unsubscribe to a topic via any callback.
- * The hook expose a handler function. All the consumer code need to do is to
- * call this handler function with the message received from the topic or pass
- * it directly to the callback function that is passed to the subscriberFn.
+ * `useSubscriptionCore` handles core subscription logic and provides a way to
+ * subscribe and unsubscribe to a topic via any callback. The hook exposes a
+ * handler function - all the consumer code needs to do is call this handler
+ * function with the message received from the topic, or pass it directly to
+ * the callback function that is passed to `subscriberFn`.
  *  - `status` - current status of the subscription
  *  - `data` - the data after the select function is applied to the message
  *  - `reSubscribe` - function that can be called to re-subscribe to the topic
  *
- * An example how this hook works can be found in {@link ./useSubscription.ts}
+ * See {@link useSubscription} for an example of how this hook is used.
  */
 declare function useSubscriptionCore<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined>(options: SubscriptionCoreOptions<TData, TMessage, Stateless>): SubscriptionCoreReturnType<TData, Stateless>;
 
+/**
+ * Configuration options for {@link useSubscription}. Extends {@link SubscriptionCoreOptions}
+ * (minus `subscriberFn`, which `useSubscription` builds internally) with the service/topic pair
+ * that identifies what to subscribe to.
+ *
+ * @typeParam TData - The data type exposed via `data`, after `select` (if provided).
+ * @typeParam TMessage - The raw message type received from the topic.
+ * @typeParam Stateless - When `true`, the hook does not keep the latest message in state.
+ * @typeParam TMetadata - The type of the optional metadata forwarded to `subscriptionHandler`.
+ */
 type SubscriptionOptions<TData, TMessage = unknown, Stateless extends true | undefined = undefined, TMetadata extends {} = {}> = Omit<SubscriptionCoreOptions<TData, TMessage, Stateless>, "subscriberFn"> & {
+    /** The name of the service/machine that owns the topic being subscribed to. */
     service: string;
+    /** The name of the topic to subscribe to. */
     topic: string;
+    /** How many levels deep to mirror nested updates. Forwarded as-is to `subscriptionHandler`. */
     maxDownwardDepth?: number;
 } & {
+    /** Optional metadata forwarded to `subscriptionHandler` alongside the subscription request. */
     meta?: TMetadata;
 };
+/**
+ * The shape of a low-level subscription transport function, e.g. one bound to a ZMQ proxy client
+ * via {@link bindClientSocketProxy}. Given subscription details, it starts the subscription and
+ * returns an unsubscribe function.
+ *
+ * @typeParam TMessage - The raw message type delivered to `callback`.
+ * @typeParam TMetadata - The type of the optional metadata passed through `opts.meta`.
+ * @param opts - The service/topic to subscribe to, the callback to invoke per message, and any
+ * transport-specific options.
+ * @returns A function that unsubscribes from the topic.
+ */
 type TSubscriptionHandlerFunction<TMessage, TMetadata extends {} = {}> = (opts: {
     service: string;
     name: string;
@@ -205,13 +528,87 @@ type TSubscriptionHandlerFunction<TMessage, TMetadata extends {} = {}> = (opts:
 } & {
     meta?: TMetadata;
 }) => () => void;
+/**
+ * React hook that subscribes to a `service`/`topic` pair via a transport-specific
+ * `subscriptionHandler` (see {@link TSubscriptionHandlerFunction}), managing subscribe/unsubscribe
+ * across the component's lifecycle. Built on top of {@link useSubscriptionCore} — see that hook
+ * for the mechanics of status tracking, `select`, `compareOrThrow`, etc.
+ *
+ * @typeParam TData - The data type exposed via `data`, after `select` (if provided).
+ * @typeParam TMessage - The raw message type received from the topic.
+ * @typeParam Stateless - When `true`, the hook does not keep the latest message in state.
+ * @typeParam TMetadata - The type of the optional metadata forwarded to `subscriptionHandler`.
+ * @param subscriptionHandler - The transport function that performs the actual subscribe/unsubscribe.
+ * @param options - See {@link SubscriptionOptions}.
+ * @returns See {@link SubscriptionCoreReturnType}: `status`, `data` and `reSubscribe`
+ * (`data`/`status` are omitted when `Stateless` is `true`).
+ * @example
+ * ```tsx
+ * const { data, status } = useSubscription(bindClientSocketProxy(proxyClient), {
+ *   service: "MyService",
+ *   topic: "MyTopic",
+ * });
+ * ```
+ */
 declare function useSubscription<TData = unknown, TMessage = TData, Stateless extends true | undefined = undefined, TMetadata extends {} = {}>(subscriptionHandler: TSubscriptionHandlerFunction<TMessage, TMetadata>, options: SubscriptionOptions<TData, TMessage, Stateless, TMetadata>): SubscriptionCoreReturnType<TData, Stateless>;
+/**
+ * Builds a `useSubscription`-like hook that is pre-bound to a specific transport
+ * (`subscriptionHandler`) and a way of resolving the target service/machine name, so calling code
+ * only needs to supply the `topic` (and, optionally, override the `machine`).
+ *
+ * This is the building block behind per-domain subscription hooks: a package can call this once
+ * with its own transport binder and machine-resolution logic, and export the resulting hook for
+ * consumers to use without having to know about services/transports at all.
+ *
+ * @typeParam TMetadata - The type of the optional metadata forwarded to `subscriptionHandler`.
+ * @param subscriptionHandler - The transport function that performs the actual subscribe/unsubscribe.
+ * @param targetMachine - Resolves the service name to subscribe on, given an optional `machine`
+ * override supplied by the caller of the built hook.
+ * @returns A `useSubscriptionBuilder` hook with the same options as {@link useSubscription} minus
+ * `service`, plus an optional `machine` override.
+ */
 declare function buildServiceSubscriptionHook<TMetadata extends {} = {}>(subscriptionHandler: TSubscriptionHandlerFunction<unknown, TMetadata>, targetMachine: (machine: string | undefined) => string): <TData, TMessage = TData, Stateless extends true | undefined = undefined>(options: Omit<SubscriptionOptions<TData, TMessage, Stateless, TMetadata>, "service"> & {
     machine?: string;
 }) => SubscriptionCoreReturnType<TData, Stateless>;
 
+/**
+ * The parameters a {@link TSubscriptionHandlerFunction} receives, as consumed by
+ * {@link bindClientSocketProxy}.
+ * @typeParam TMetadata - The type of the optional metadata carried on `opts.meta`.
+ */
 type TProxySubscriptionHandlerParams<TMetadata extends {} = {}> = Parameters<Parameters<typeof buildServiceSubscriptionHook<TMetadata>>[0]>[0];
+/**
+ * Adapts a {@link @pixotope/zmq-client!ZMQProxyWSClient}'s `mirror` method into a
+ * {@link TSubscriptionHandlerFunction}, so it can be passed to {@link useSubscription} or
+ * {@link buildServiceSubscriptionHook}.
+ *
+ * @param socketClientProxy - The ZMQ proxy WebSocket client to subscribe through.
+ * @returns A subscription handler function that mirrors the requested service/topic and
+ * unwraps each message's `.message` payload before invoking the caller's callback.
+ * @example
+ * ```ts
+ * const useMySubscription = buildServiceSubscriptionHook(
+ *   bindClientSocketProxy(proxyClient),
+ *   (machine) => machine ?? "DefaultMachine"
+ * );
+ * ```
+ */
 declare function bindClientSocketProxy(socketClientProxy: ZMQProxyWSClient): (args: TProxySubscriptionHandlerParams) => () => void;
+/**
+ * Adapts a {@link @pixotope/zmq-client!ZMQProxyWSClient}'s `callAsync` method into a {@link TPromiseFunction}, so it
+ * can be passed to {@link buildMutationHook} or {@link buildQueryHook}.
+ *
+ * @param clientSocketProxy - The ZMQ proxy WebSocket client to call through.
+ * @returns A promise function that performs the remote call and resolves with the unwrapped
+ * `.message.Result` payload (rejecting if the call times out or fails).
+ * @example
+ * ```ts
+ * const useCreateUser = buildMutationHook<MyFunctions>(
+ *   bindPromiseFunction(proxyClient),
+ *   () => "UserService"
+ * );
+ * ```
+ */
 declare function bindPromiseFunction(clientSocketProxy: ZMQProxyWSClient): (args: Omit<_pixotope_zmq_client.ZMQClient.Call<unknown, {
     functionName: string;
     parameters: unknown;
@@ -220,4 +617,4 @@ declare function bindPromiseFunction(clientSocketProxy: ZMQProxyWSClient): (args
     meta?: unknown;
 }) => Promise<unknown>;
 
-export { ComparisonFailError, type Connection, type MessageHandler, type MutateOptions, type MutationFunction, type MutationInfo, type MutationOptions, type QueryOptions, type SubscriptionCoreOptions, type SubscriptionCoreReturnType, type SubscriptionOptions, type TPromiseFunction, type TProxySubscriptionHandlerParams, type TSubscriptionHandlerFunction, type UseQueryResult, bindClientSocketProxy, bindPromiseFunction, buildMutationHook, buildQueryHook, buildServiceSubscriptionHook, useMutation, useQuery, useSubscription, useSubscriptionCore };
+export { ComparisonFailError, type Connection, type FnToParamsBase, type Functionize, type MessageHandler, type MutateOptions, type MutationFunction, type MutationInfo, type MutationOptions, type MutationStatus, type QueryOptions, type QueryStatus, type SubscriptionCoreOptions, type SubscriptionCoreReturnType, type SubscriptionOptions, type SubscriptionState, type TMutationError, type TPromiseFunction, type TProxySubscriptionHandlerParams, type TQueryError, type TQueryKey, type TSubscriptionHandlerFunction, type UseQueryResult, type WithQueryData, type WithStatus, type WithSubscriptionData, bindClientSocketProxy, bindPromiseFunction, buildMutationHook, buildQueryHook, buildServiceSubscriptionHook, useMutation, useQuery, useSubscription, useSubscriptionCore };