@pixotope/query 0.9.0 → 0.11.0

package/src/useMutation.ts

@@ -1,37 +1,77 @@
 import { useCallback, useRef, useState } from "react";
 
+/**
+ * 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.
+ */
 export 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.
+ */
 export 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,
@@ -39,20 +79,37 @@ export interface MutationOptions<
   ) => TParams;
 }
 
-type TMutationError<TError> = TError | Error | null;
+/** The error type exposed via `error`/`onError`/`onSettled` on {@link MutationOptions}, {@link MutateOptions}, and {@link useMutation}'s return value. */
+export 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.
+ */
 export 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,
@@ -61,13 +118,26 @@ export interface MutateOptions<
   ) => void;
 }
 
-type MutationStatus = "idle" | "loading" | "success" | "error";
+/** The status of a {@link useMutation} call, as exposed via its return value's `status`. */
+export type MutationStatus = "idle" | "loading" | "success" | "error";
 type RaceErrorReason = "timeout";
 type RacePromises<T> = Promise<T | RaceErrorReason>;
 
+/**
+ * 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`.
+ */
 export class ComparisonFailError<TPayload = unknown> extends Error {
+  /** The result that `compareOrThrow` rejected. */
   public readonly payload: TPayload;
 
+  /**
+   * @param message - The error message.
+   * @param payload - The result that `compareOrThrow` rejected, preserved on the error.
+   */
   constructor(message: string, payload: TPayload) {
     super(message);
     this.name = this.constructor.name;
@@ -79,6 +149,33 @@ export class ComparisonFailError<TPayload = unknown> extends Error {
   }
 }
 
+/**
+ * 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) });
+ * ```
+ */
 export const useMutation = <
   TData = unknown,
   TError = TMutationError<unknown>,

package/src/useQuery.ts

@@ -1,5 +1,14 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
+/**
+ * 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}).
+ */
 export interface QueryOptions<
   TData = unknown,
   TError = unknown,
@@ -7,33 +16,101 @@ export interface QueryOptions<
   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;
 }
 
-type Functionize<T> = () => T;
-type QueryStatus = "idle" | "loading" | "success" | "error" | "timeout";
+/** A value, or a function returning it. Used to type {@link QueryOptions.initialData}. */
+export type Functionize<T> = () => T;
+/** The status of a {@link useQuery} call, as exposed via {@link UseQueryResult}'s `status`. */
+export type QueryStatus = "idle" | "loading" | "success" | "error" | "timeout";
 type RaceErrorReason = "timeout";
 type RacePromises<T> = Promise<T | RaceErrorReason>;
-type WithData<TData> = { data: TData | undefined };
-type TQueryKey = readonly any[];
-
-type TQueryError<TError> = TError | Error | null;
-
+/** Adds the `data` field to {@link UseQueryResult} when the query is not {@link QueryOptions.stateless}. */
+export type WithQueryData<TData> = { data: TData | undefined };
+/** The type of {@link QueryOptions.key}: an array whose serialized value determines when the query refetches. */
+export type TQueryKey = readonly any[];
+
+/** The error type exposed via {@link UseQueryResult}'s `error` and passed to `onError`/`onSettled`. */
+export 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.
+ */
 export type UseQueryResult<
   TData = unknown,
   TError = unknown,
@@ -41,12 +118,21 @@ export type UseQueryResult<
   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;
   // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-} & (Stateless extends true ? {} : WithData<TSelectData>);
+} & (Stateless extends true ? {} : WithQueryData<TSelectData>);
 
 function normalizeQueryKey(queryKey: TQueryKey): string {
   return JSON.stringify(queryKey);
@@ -74,6 +160,28 @@ type TInternalOptionsRef<TData> = {
 
 const getRandomUUID = () => Math.random().toString(36).substring(2, 15);
 
+/**
+ * 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),
+ * });
+ * ```
+ */
 export const useQuery = <
   TData = unknown,
   TError = TQueryError<unknown>,

package/src/useSubscription.ts

@@ -3,6 +3,16 @@ import {
   useSubscriptionCore,
 } from "./useSubscriptionCore";
 
+/**
+ * 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`.
+ */
 export type SubscriptionOptions<
   TData,
   TMessage = unknown,
@@ -12,13 +22,28 @@ export type SubscriptionOptions<
   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.
+ */
 export type TSubscriptionHandlerFunction<
   TMessage,
   TMetadata extends {} = {},
@@ -31,6 +56,28 @@ export type TSubscriptionHandlerFunction<
   } & { 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",
+ * });
+ * ```
+ */
 export function useSubscription<
   TData = unknown,
   TMessage = TData,
@@ -60,6 +107,22 @@ export function useSubscription<
   });
 }
 
+/**
+ * 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.
+ */
 export function buildServiceSubscriptionHook<TMetadata extends {} = {}>(
   subscriptionHandler: TSubscriptionHandlerFunction<unknown, TMetadata>,
   targetMachine: (machine: string | undefined) => string

package/src/useSubscriptionCore.ts

@@ -1,103 +1,116 @@
 /**
- * @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}.
  */
 
 import { shallowEqual } from "@pixotope/utils/comparison";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
-type SubscriptionState = "idle" | "subscribed" | "subscribing" | "error";
+/** The status of a {@link useSubscriptionCore} subscription, as exposed via {@link WithStatus.status}. */
+export type SubscriptionState = "idle" | "subscribed" | "subscribing" | "error";
 
+/** A function invoked with each message received on the subscription. */
 export 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.
+ */
 export 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.
+ */
 export 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;
 };
 
-type WithStatus = {
+/** Adds the `status` field to {@link SubscriptionCoreReturnType}. */
+export type WithStatus = {
   status: SubscriptionState;
 };
 
-type WithData<TData> = {
+/** Adds the `data` field to {@link SubscriptionCoreReturnType}. */
+export 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.
+ */
 export type SubscriptionCoreReturnType<
   TData,
   Stateless extends true | undefined,
 > = {
+  /** Unsubscribes (if currently subscribed) and immediately subscribes again. */
   reSubscribe: () => void;
   // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-} & (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.
  */
 export function useSubscriptionCore<
   TData = unknown,

package/typedoc.json

@@ -0,0 +1,3 @@
+{
+  "entryPoints": ["src/index.ts"]
+}