stream-chat-react-native-core 10.0.0-rc.1 → 10.0.0-rc.2

package/src/components/ChannelPreview/hooks/useChannelPreviewDisplayPresence.ts

@@ -5,12 +5,8 @@ import { useChatContext } from '../../../contexts/chatContext/ChatContext';
 import { useSyncClientEventsToChannel } from '../../../hooks/useSyncClientEvents';
 
 /**
- * Selector to get the display avatar presence for channel preview
- * @param channel
- * @param client
- * @returns boolean
- *
- * NOTE: If you want to listen to the value changes where you call the hook, the selector should return primitive values instead of object.
+ * Whether the other member of a two-member channel is online. Returns a primitive so each read of
+ * the snapshot is stable.
  */
 const selector = (channel: Channel, client: StreamChat) => {
   const members = channel.state.members;
@@ -24,10 +20,10 @@ const selector = (channel: Channel, client: StreamChat) => {
 const keys: EventType[] = ['user.presence.changed', 'user.updated'];
 
 /**
- * Hook to set the display avatar presence for channel preview
- * @param {*} channel
+ * Whether the avatar of a channel preview shows the online presence indicator.
  *
- * @returns {boolean} e.g., true
+ * @param channel The channel being previewed.
+ * @returns True when the channel has exactly two members and the other one is online.
  */
 export function useChannelPreviewDisplayPresence(channel: Channel) {
   const { client } = useChatContext();

package/src/components/ChannelPreview/hooks/useChannelPreviewDraftMessage.ts

@@ -17,9 +17,10 @@ export type UseChannelPreviewDraftMessageProps = {
 };
 
 /**
- * Hook to get the draft message for a channel preview.
- * @param {UseChannelPreviewDraftMessageProps} param0
- * @returns {DraftMessage | undefined}
+ * The channel's message composer content as a draft message.
+ *
+ * @param params.channel The channel being previewed.
+ * @returns The draft, or `undefined` when the composer is empty or has no text and no attachments.
  */
 export const useChannelPreviewDraftMessage = ({ channel }: UseChannelPreviewDraftMessageProps) => {
   const { text: draftText } = useStateStore(

package/src/components/ChannelPreview/hooks/useChannelPreviewPollLabel.ts

@@ -16,9 +16,10 @@ const selector = (nextValue: PollState) => ({
 });
 
 /**
- * Hook to get the label of the poll
- * @param pollId - The id of the poll
- * @returns The label of the poll
+ * The preview label for the latest vote on a poll, such as "You voted: Option".
+ *
+ * @param params.pollId ID of the poll.
+ * @returns The label, or `undefined` when the poll has no votes.
  */
 export const useChannelPreviewPollLabel = ({ pollId }: UseChannelPreviewPollLabelProps) => {
   const { client } = useChatContext();

package/src/components/ChannelPreview/hooks/useChannelTypingState.ts

@@ -7,10 +7,11 @@ type UseChannelTypingStateProps = {
 };
 
 /**
- * Typing users for a channel-preview row. A thin wrapper over the shared `useChannelTypingUsers`
- * core (the same reactive `channel.state.typing` source the in-channel indicator uses). The preview
- * row isn't inside a `<Channel>` provider, so the channel is passed as a prop rather than read from
- * context.
+ * The users typing in a channel preview row. The channel is a parameter because the row renders
+ * outside a `<Channel>` provider.
+ *
+ * @param params.channel The channel being previewed.
+ * @returns The typing users as `usersTyping`.
  */
 export const useChannelTypingState = ({ channel }: UseChannelTypingStateProps) => {
   const usersTyping = useChannelTypingUsers(channel);

package/src/components/ChannelPreview/hooks/useIsChannelMuted.ts

@@ -13,8 +13,10 @@ const selector = (state: { muteStatus: ChannelMuteStatus }) => ({
 });
 
 /**
- * Returns this channel's mute status, sourced reactively from `channel.state.muteStatus` (kept in
- * sync with `client.mutedChannels` on `notification.channel_mutes_updated` / `health.check`).
+ * The channel's mute status, read reactively from `channel.state.muteStatus`.
+ *
+ * @param channel The channel to read.
+ * @returns The mute status, which reads as unmuted until the state reports otherwise.
  */
 export const useIsChannelMuted = (channel: Channel) =>
   useStateStore(channel?.state, selector)?.muteStatus ?? defaultMuteStatus;

package/src/components/Chat/Chat.tsx

@@ -33,94 +33,52 @@ init();
 export type ChatProps = Pick<ChatContextValue, 'client'> &
   Partial<Pick<ChatContextValue, 'isMessageAIGenerated'>> & {
     /**
-     * When false, ws connection won't be disconnection upon backgrounding the app.
-     * To receive push notifications, its necessary that user doesn't have active
-     * websocket connection. So by default, we disconnect websocket connection when
-     * app goes to background, and reconnect when app comes to foreground.
+     * Whether to close the WebSocket connection while the app is in the background and reopen it in
+     * the foreground. Push notifications are only delivered while no connection is active. Defaults
+     * to true.
      */
     closeConnectionOnBackground?: boolean;
-    /**
-     * Enables offline storage and loading for chat data.
-     */
+    /** Enables offline storage and loading for chat data. Defaults to false. */
     enableOfflineSupport?: boolean;
     /**
-     * Encrypts the offline database at rest with SQLCipher, using the key this
-     * resolves to. Only relevant when `enableOfflineSupport` is enabled. Leaving it
-     * unset keeps the offline database unencrypted, which is the default.
+     * Resolves the key that encrypts the offline database at rest with SQLCipher. Only applies with
+     * `enableOfflineSupport`; when unset the database is unencrypted.
      *
-     * Requires a native build of `@op-engineering/op-sqlite` that includes SQLCipher.
-     * Add the following to your application's `package.json` and rebuild the native
-     * app - without the flag the key is accepted and then silently ignored:
-     *
-     * ```json
-     * { "op-sqlite": { "sqlcipher": true } }
-     * ```
+     * Needs a native `@op-engineering/op-sqlite` build with SQLCipher
+     * (`{ "op-sqlite": { "sqlcipher": true } }` in the app's `package.json`).
      *
-     * **Wrap `<Chat>` in an error boundary.** If the database cannot be opened with
-     * the encryption you asked for, `<Chat>` throws a {@link SqliteClientError}
-     * from render instead of continuing without it. The SDK deliberately takes no
-     * recovery action of its own - it never deletes data, and never silently falls
-     * back to an unencrypted or absent cache. Discriminate on `code`:
+     * When the database cannot be opened with the requested encryption, `<Chat>` throws a
+     * {@link SqliteClientError} from render, so wrap it in an error boundary. The SDK never deletes
+     * data or falls back to an unencrypted cache. Branch on `code`:
+     * - `OFFLINE_DB_UNREADABLE`: the existing file cannot be read with this key. Call
+     *   `SqliteClient.deleteDatabase()` and re-mount; actions queued while offline are lost.
+     * - `ENCRYPTION_KEY_UNAVAILABLE`: the key could not be read (such as a locked keychain). The
+     *   database is untouched; re-mount to retry.
+     * - `SQLCIPHER_BUILD_MISSING`: the native build lacks SQLCipher. Re-mount with
+     *   `enableOfflineSupport={false}` so nothing is persisted unencrypted.
      *
-     * - `OFFLINE_DB_UNREADABLE` - the file exists but this key cannot read it (the
-     *   key changed, or the database predates encryption). **Recommended recovery:
-     *   `SqliteClient.deleteDatabase()`, then re-mount `<Chat>`.** The contents are a
-     *   cache and are refetched from the server; the exception is actions queued while
-     *   offline, which are lost - prompt the user first if that matters to you.
-     * - `ENCRYPTION_KEY_UNAVAILABLE` - the key could not be read (a locked keychain, a
-     *   launch before first unlock). The database is untouched. **Recommended
-     *   recovery: re-mount to retry** once the key is readable - for example when the
-     *   app next returns to the foreground.
-     * - `SQLCIPHER_BUILD_MISSING` - the native build has no SQLCipher, so the key
-     *   would be ignored and the database written in plaintext. Not recoverable at
-     *   runtime; it needs the build flag above and a new binary. **Recommended
-     *   recovery: re-mount with `enableOfflineSupport={false}`** so nothing is
-     *   persisted unencrypted.
-     *
-     * The key must be **stable for the lifetime of the database file**. There is no
-     * rekey path, so a key that changes costs one `OFFLINE_DB_UNREADABLE` and a
-     * rebuild. To rotate without paying that, rotate a key-encryption key and keep the
-     * database key it protects unchanged (envelope encryption).
-     *
-     * Switching encryption on, or back off, leaves a database from the other mode on
-     * disk and so raises `OFFLINE_DB_UNREADABLE` once in each direction. Deleting it
-     * from your boundary is all that is needed.
+     * The key must stay the same for the life of the database file, as there is no rekey. Switching
+     * encryption on or off raises `OFFLINE_DB_UNREADABLE` once, until the old database is deleted.
      */
     getOfflineDbEncryptionKey?: () => Promise<string | undefined>;
     /**
-     * Optional positive cap on the number of events a single `/sync` response may
-     * contain before the offline sync manager skips replaying those events into
-     * local storage.
-     *
-     * On reconnect the SDK downloads the events missed while offline and writes
-     * them to the offline DB. For a very large payload this replay is both costly
-     * on-device and unnecessary for what the user is looking at — the active
-     * channel list and any open channel are refreshed independently on reconnect
-     * (by `client.connectionRecovery`). When the payload exceeds this
-     * limit the replay is skipped and that reconnect refresh covers the visible
-     * channels; inactive channels are hydrated on their next explicit query. The
-     * last-sync timestamp is still advanced so the same payload is not retried.
-     *
-     * Defaults to {@link DEFAULT_MAX_SYNC_EVENTS_LIMIT} (250). Pass `false` to
-     * disable the limit entirely (replay every event — the historical behavior).
-     *
-     * Only relevant when `enableOfflineSupport` is enabled.
+     * Positive cap on how many events of a single `/sync` response the offline sync manager replays
+     * into local storage on reconnect. Above the cap the replay is skipped, the reconnect refresh
+     * covers the visible channels, and the last-sync timestamp still advances. `false` disables the
+     * cap. Only applies with `enableOfflineSupport`.
      *
      * @default 250
      */
     maxSyncEventsLimit?: number | false;
     /**
-     * When true, multipart uploads use the SDK's native upload adapter when available.
-     * When false, uploads stay on the default axios adapter.
-     *
-     * This only controls whether the native adapter gets installed by this Chat instance.
-     * It does not uninstall an adapter that was already installed on the client.
+     * Installs the SDK's native multipart upload adapter on the client when true and available;
+     * otherwise uploads use the default axios adapter. An adapter already installed stays in place.
      *
      * @default false
      */
     useNativeMultipartUpload?: boolean;
     /**
-     * Instance of Streami18n class should be provided to Chat component to enable internationalization.
+     * The `Streami18n` instance that enables internationalization.
      *
      * The SDK ships English only. Add a language by registering a dictionary keyed by the SDK's
      * dotted translation keys, then switching to it:
@@ -140,9 +98,8 @@ export type ChatProps = Pick<ChatContextValue, 'client'> &
      */
     i18nInstance?: Streami18n;
     /**
-     * You can pass the theme object to customize the styles of Chat components. You can check the default theme in [theme.ts](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/contexts/themeContext/utils/theme.ts)
-     *
-     * Please check section about [themes in cookbook](https://github.com/GetStream/stream-chat-react-native/wiki/Cookbook-v3.0#theme) for details.
+     * Theme overrides, merged over the default theme in
+     * [theme.ts](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/contexts/themeContext/utils/theme.ts).
      *
      * ```
      * import type { DeepPartial, Theme } from 'stream-chat-react-native';
@@ -193,14 +150,10 @@ const ChatWithContext = (props: PropsWithChildren<ChatProps>) => {
   } = props;
   const { ChatLoadingIndicator } = useComponentsContext();
 
-  // Setup translators
   const translators = useStreami18n(i18nInstance);
 
-  /**
-   * Tracked rather than read inline: `client.user` is a plain field, so a `useMemo` over it only
-   * re-evaluates when something else re-renders `Chat`. A language changed server-side would
-   * otherwise never reach the components that read it.
-   */
+  // State rather than a memo: `client.user` is a plain field, so a memo would miss a language
+  // changed server-side until something else re-rendered `Chat`.
   const [userLanguage, setUserLanguage] = useState(
     () => client.user?.language || DEFAULT_USER_LANGUAGE,
   );
@@ -284,7 +237,7 @@ const ChatWithContext = (props: PropsWithChildren<ChatProps>) => {
   const chatContext = useCreateChatContext({ client, getAppSettings, isMessageAIGenerated });
 
   if (userId && enableOfflineSupport && !initialisedDatabase) {
-    // if user id has been set and offline support is enabled, we need to wait for database to be initialised
+    // Hold rendering until the offline database is initialized for this user.
     return ChatLoadingIndicator ? <ChatLoadingIndicator /> : null;
   }
 
@@ -298,17 +251,10 @@ const ChatWithContext = (props: PropsWithChildren<ChatProps>) => {
 };
 
 /**
- * Chat - Wrapper component for Chat. The needs to be placed around any other chat components.
- * This Chat component provides the ChatContext to all other components.
- *
- * The ChatContext provides the following props:
- *
- * - client - client connection
- * - getAppSettings - resolves the app's settings
- * - isMessageAIGenerated - decides whether a message renders as AI generated
+ * Root component that provides the chat, translation and theme contexts to the components below it.
  *
- * Connection status is NOT on this context. Read it with `useWSConnectionState()` (our socket)
- * or `useNetworkConnectionState()` (the device's network) — they are separate facts.
+ * Connection status is not on the chat context: read it with `useWSConnectionState()` (the socket)
+ * or `useNetworkConnectionState()` (the device network).
  */
 export const Chat = (props: PropsWithChildren<ChatProps>) => {
   const { theme } = useTheme();

package/src/components/Chat/hooks/useAppSettingsGetter.ts

@@ -13,12 +13,17 @@ type AppSettingsRequest = {
 
 /**
  * A stable `getAppSettings()` for the chat context. The first call for a user fetches the app
- * settings and later calls reuse them. With offline support, a successful fetch is copied to the offline
- * database and a failed one falls back to that copy. A failed fetch is not kept, so the next call
- * fetches again.
+ * settings and later calls reuse them. With offline support, a successful fetch is copied to the
+ * offline database and a failed one falls back to that copy. A failed fetch is not kept, so the
+ * next call fetches again.
  *
- * The settings are requested once `ready` and a user is connected, so they are usually loaded by
- * the time anything asks for them.
+ * The settings are requested once `ready` and a user is connected, so they are usually loaded when
+ * something asks for them.
+ *
+ * @param params.client The client to fetch the settings from.
+ * @param params.ready Whether the client is ready to be queried.
+ * @param params.userId The connected user's ID; no request is made without one.
+ * @returns A function that resolves to the app settings.
  */
 export const useAppSettingsGetter = ({
   client,

package/src/components/Chat/hooks/useClientUserId.ts

@@ -4,15 +4,14 @@ import type { StreamChat } from 'stream-chat';
 import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
 /**
- * The id of the user connected to `client`, kept current as users connect and disconnect.
+ * The ID of the user connected to `client`, kept current as users connect and disconnect.
  *
- * This hook is TEMPORARY. It goes away once the client keeps its state (the connected user and the
- * app settings) in a store of its own, which components can subscribe to directly.
+ * The client has no store for its own user, so this re-reads it whenever the WebSocket or network
+ * store publishes, which `connectUser()` and `disconnectUser()` cause. Re-renders only when the ID
+ * changes.
  *
- * The client has no store for its own user. `connectUser()` sets it right before opening the
- * socket and `disconnectUser()` clears it while closing it, so the socket and network stores
- * publishing around those calls are the signal to read it again. Re-renders only when the id
- * itself changes.
+ * @param client The client to read the user from.
+ * @returns The connected user's ID, or `undefined` when no user is connected.
  */
 export const useClientUserId = (client: StreamChat) => {
   const subscribe = useCallback(

package/src/components/Chat/hooks/useConnectionLifecycle.ts

@@ -9,16 +9,15 @@ import type { NetworkStatusReporter, StreamChat } from 'stream-chat';
 import { useAppStateListener } from '../../../hooks/useAppStateListener';
 
 /**
- * Reports the device's network status to the client, and owns the socket's app-state lifecycle.
+ * Installs the NetInfo network status reporter on the client and closes the WebSocket while the app
+ * is in the background, reopening it in the foreground (push notifications are only delivered while
+ * no socket is active).
  *
- * Two jobs, both side effects — this hook returns nothing. Read status with
- * `useNetworkConnectionState()` (the device) or `useWSConnectionState()` (our socket); both read the
- * client's own stores, so they are correct on mount rather than only after a transition.
+ * Read the results with `useNetworkConnectionState()` and `useWSConnectionState()`.
  *
- * 1. **The network reporter.** The client cannot detect device network status itself — every
- *    platform reports it differently — so it has to be told. On React Native that means NetInfo.
- * 2. **Background/foreground.** Close the socket when the app backgrounds and reopen it on
- *    foreground, because push notifications are only delivered while no socket is active.
+ * @param client The client to manage.
+ * @param closeConnectionOnBackground Whether to close the socket while in the background.
+ * Defaults to true.
  */
 export const useConnectionLifecycle = (client: StreamChat, closeConnectionOnBackground = true) => {
   const clientExists = !!client;
@@ -32,7 +31,7 @@ export const useConnectionLifecycle = (client: StreamChat, closeConnectionOnBack
   }, [closeConnectionOnBackground, client, clientExists]);
 
   const onForeground = useCallback(() => {
-    // If the user id is not set, we should not open the connection, as it will raise an unneeded error
+    // Without a user ID, opening the connection would raise an unneeded error.
     if (!clientExists || !client.userID) {
       return;
     }
@@ -42,8 +41,8 @@ export const useConnectionLifecycle = (client: StreamChat, closeConnectionOnBack
 
   useAppStateListener(onForeground, onBackground);
 
-  // A <Chat> mounted while the app is already active (Android recreating the activity in the same JS
-  // runtime) never sees the background→active change that reopens a socket its predecessor closed.
+  // A `<Chat>` mounted while the app is already active (Android recreating the activity) never sees
+  // the background-to-foreground change that reopens a socket its predecessor closed.
   useEffect(() => {
     if (!closeConnectionOnBackground || !clientExists || !client.userID) return;
     if (AppState.currentState === 'active' && client.wsConnection.connection?.isDisconnected) {
@@ -56,14 +55,9 @@ export const useConnectionLifecycle = (client: StreamChat, closeConnectionOnBack
       return;
     }
 
-    // Declarative config rather than `client.networkConnection.setStatusReporter(...)`. Both survive
-    // a configuration derivation now, but this one states the reporter as part of the client's
-    // configuration rather than as an edit applied to it, so a `client.config.get('client')` shows
-    // what is actually installed.
-    //
-    // Installing one at all is not optional on React Native. Left alone the client falls back to a
-    // reporter that mirrors its own WebSocket, which cannot report that the network came back before
-    // the socket noticed — the entire reason the network signal is worth having.
+    // Set through the client config so `client.config.get('client')` shows the installed reporter.
+    // Required on React Native: the client's fallback mirrors its own WebSocket and cannot report
+    // the network returning before the socket notices.
     client.config.set({
       client: {
         networkConnection: {
@@ -72,25 +66,17 @@ export const useConnectionLifecycle = (client: StreamChat, closeConnectionOnBack
       },
     });
 
-    // Deliberately no teardown. The reporter's lifetime is the CLIENT's, not this component's: the
-    // client outlives `<Chat>` (push handling, background work), and `isOnline` is supposed to stay
-    // true about the device for as long as the client exists. Tearing it down here would also leave a
-    // stale value rather than a cleared one — `setStatusReporter(null)` keeps the last known status by
-    // design — so consumers would read an authoritative-looking `isOnline` that nothing is updating
-    // any more.
-    //
-    // Re-running this is safe and cannot stack listeners: `netInfoStatusReporter` is a stable
-    // module-scope reference, so `ConfigController`'s no-op write check and the observer's own
-    // installed-reporter identity guard both short-circuit. A *different* client re-runs the effect
-    // through the dependency array and installs a fresh reporter for it.
+    // No teardown: the reporter lives as long as the client, which outlives `<Chat>`, and removing
+    // it would leave a stale `isOnline` because `setStatusReporter(null)` keeps the last known
+    // status. Re-running does not stack listeners: `netInfoStatusReporter` is a stable reference,
+    // so a repeated write is a no-op.
   }, [client, clientExists]);
 };
 
 /**
- * Subscribes to NetInfo and reports every change to the client. What `<Chat>` installs.
+ * Subscribes to NetInfo and reports every change to the client. `<Chat>` installs it in an effect.
  *
- * Exported so it can be installed **at client construction** instead, which is strictly better if
- * you build the client yourself:
+ * When you build the client yourself, install it at construction instead:
  *
  * ```ts
  * new StreamChat(apiKey, {
@@ -98,24 +84,16 @@ export const useConnectionLifecycle = (client: StreamChat, closeConnectionOnBack
  * });
  * ```
  *
- * `<Chat>` can only install it from an effect, so between the client being constructed and that
- * effect running, the client falls back to a reporter that mirrors its own WebSocket. In that window
- * a socket-only failure — an expired token, a server close — is recorded as the *device* having no
- * network, and the UI blames the network for it. Installing here closes the window; the fallback is
- * never reached.
+ * Until the effect runs, the client falls back to a reporter that mirrors its own WebSocket, which
+ * records a socket-only failure (expired token, server close) as the device being offline.
  *
- * Module scope, so the same reference is handed to the client on every derivation — re-installing an
- * identical reporter is a no-op there, and rebuilding it per render would tear the native listener
- * down and recreate it for nothing.
- *
- * `NetInfo.addEventListener` fires once with the current state on subscribe, which satisfies the
- * reporter contract's "report the current status as soon as it is known" requirement — so no
- * separate `NetInfo.fetch()` is needed.
+ * Defined at module scope so every install passes the same reference, which the client treats as a
+ * no-op. NetInfo reports the current state on subscribe, so no `NetInfo.fetch()` is needed.
  */
 export const netInfoStatusReporter: NetworkStatusReporter = (onStatusChange) =>
   NetInfo.addEventListener(({ isConnected, isInternetReachable }) => {
-    // `isInternetReachable` is the stronger signal but is `null` until NetInfo has probed, so fall
-    // back to `isConnected` until it resolves. Coerced because both are `boolean | null`.
+    // `isInternetReachable` is `null` until NetInfo has probed, so `isConnected` is used until
+    // then.
     onStatusChange(
       isInternetReachable !== null ? isInternetReachable && isConnected : !!isConnected,
     );

package/src/components/Chat/hooks/useCreateChatClient.ts

@@ -7,17 +7,10 @@ import type { ClientUser, DeepPartial, InstanceConfigTree, TokenOrProvider } fro
 import { netInfoStatusReporter } from './useConnectionLifecycle';
 
 /**
- * Names the NetInfo reporter in the client's own options, so the device's network status is reported
- * from the moment the client exists.
- *
- * `<Chat>` also installs it, but only from an effect — and until something reports, the client falls
- * back to a reporter that mirrors its own WebSocket. That fallback cannot distinguish "this device
- * has no network" from "this socket died", so a socket-only failure in that window (an expired
- * token, a server close, the `closeConnection()` that backgrounding uses) is recorded as the device
- * being offline, and the UI blames the network for it. Installing here means the fallback is never
- * reached.
- *
- * A `statusReporter` the caller passed themselves wins — it is spread last.
+ * Names the NetInfo reporter in the client options, so network status is reported from
+ * construction. `<Chat>` installs it only from an effect, and until then the client mirrors its own
+ * WebSocket, which records a socket-only failure (expired token, server close) as the device being
+ * offline. A `statusReporter` in `options` wins.
  */
 const withNetInfoReporter = (
   options?: DeepPartial<InstanceConfigTree>,
@@ -33,7 +26,14 @@ const withNetInfoReporter = (
 });
 
 /**
- * React hook to create, connect and return `StreamChat` client.
+ * Creates a `StreamChat` client and connects the user. Disconnects the user when the inputs change
+ * or the component unmounts.
+ *
+ * @param params.apiKey The Stream API key.
+ * @param params.options Client configuration. Only the first value is used.
+ * @param params.tokenOrProvider The user token or a function that provides it.
+ * @param params.userData The user to connect. A new connection is made only when its `id` changes.
+ * @returns The client once the user is connected, otherwise `null`.
  */
 export const useCreateChatClient = ({
   apiKey,
@@ -43,10 +43,7 @@ export const useCreateChatClient = ({
 }: {
   apiKey: string;
   tokenOrProvider: TokenOrProvider;
-  /**
-   * The user to connect, as `client.connectUser` accepts it: only `id` is required, so
-   * `{ id, name, image }` is enough. Server-owned fields (`role`, `created_at`, …) need not be set.
-   */
+  /** The user to connect, as `client.connectUser` accepts it. Only `id` is required. */
   userData: ClientUser;
   options?: DeepPartial<InstanceConfigTree>;
 }) => {

package/src/components/Chat/hooks/useInitializeOfflineDb.ts

@@ -8,23 +8,20 @@ import { SqliteClient, SqliteClientError } from '../../../store/SqliteClient';
 
 export type InitializeOfflineDbOptions = {
   /**
-   * Encrypts the offline database at rest with SQLCipher, using the key this resolves
-   * to. Leaving it unset opens the database unencrypted, which is the default. See
-   * `ChatProps.getOfflineDbEncryptionKey` for the build flag it requires, the stability
-   * requirement, and how failures are surfaced.
+   * Resolves the key that encrypts the offline database at rest with SQLCipher; when unset the
+   * database is unencrypted. See `ChatProps.getOfflineDbEncryptionKey` for the requirements.
    */
   getEncryptionKey?: () => Promise<string | undefined>;
   /**
-   * Optional positive cap on the number of events a single `/sync` response may
-   * contain before the offline sync manager skips replaying those events into local
-   * storage. `false` opts out entirely.
+   * Positive cap on the events of a single `/sync` response that the offline sync manager replays
+   * into local storage; above it the replay is skipped. `false` removes the cap.
    */
   maxSyncEventsLimit?: number | false;
 };
 
 export type UseInitializeOfflineDbParams = {
   client: StreamChat;
-  /** Whether offline support is enabled at all. */
+  /** Whether offline support is enabled. */
   enabled: boolean;
   options?: InitializeOfflineDbOptions;
   userID?: string;
@@ -32,12 +29,17 @@ export type UseInitializeOfflineDbParams = {
 
 /**
  * Attaches an offline database to the client and initializes it for a user. Returns the attached
- * database, so the caller can subscribe to its state: it is attached after the first render.
+ * database, which is set after the first render.
  *
- * **Raises** whatever prevented the database from opening, from render, so an error
- * boundary above the caller can decide what to do. The offline database is never
- * silently downgraded, because an integration that asked for encryption must not end
- * up with an unencrypted cache.
+ * Throws from render whatever prevented the database from opening, so an error boundary above the
+ * caller can handle it. The database is never silently downgraded to an unencrypted one.
+ *
+ * @param params.client The client to attach the database to.
+ * @param params.enabled Whether offline support is enabled.
+ * @param params.options Encryption key getter and sync event cap.
+ * @param params.userID The user to initialize the database for.
+ * @returns The attached database, or `undefined` when none is attached.
+ * @throws The error that prevented the database from opening.
  */
 export const useInitializeOfflineDb = ({
   client,
@@ -45,22 +47,16 @@ export const useInitializeOfflineDb = ({
   options,
   userID,
 }: UseInitializeOfflineDbParams) => {
-  /**
-   * Why this attempt could not open the offline database.
-   *
-   * Held per attempt rather than read from a longer-lived source: a value that outlived
-   * the attempt would be seen during the first render after a re-mount and raised
-   * before that mount's own attempt could run, so an error boundary that re-mounts to
-   * retry would loop forever.
-   */
+  // Why this attempt could not open the offline database. Held per attempt: a longer-lived error
+  // would be raised on the next mount before its own attempt runs, so an error boundary that
+  // re-mounts to retry would loop forever.
   const [initializationError, setInitializationError] = useState<SqliteClientError>();
   const [offlineDb, setOfflineDb] = useState(() => client.offlineDb);
 
   const { getEncryptionKey, maxSyncEventsLimit } = options ?? {};
 
-  // `getEncryptionKey` is overwhelmingly likely to be an inline arrow. Stabilising it
-  // keeps a new identity per render out of the dependencies below, while still calling
-  // whatever the latest prop is.
+  // Keeps an inline `getEncryptionKey` from changing the dependencies below every render, while
+  // still calling the latest prop.
   const resolveEncryptionKey = useStableCallback(
     () => getEncryptionKey?.() ?? Promise.resolve(undefined),
   );
@@ -75,9 +71,9 @@ export const useInitializeOfflineDb = ({
     if (!client.offlineDb) {
       const keyGetter = isEncryptionEnabled ? resolveEncryptionKey : undefined;
 
-      // Confirm the database can be opened before attaching it: the client writes
-      // through `client.offlineDb` without checking that it initialized, so one we
-      // cannot open turns those writes into rejections (and UI is affected directly).
+      // Confirm the database opens before attaching it: the client writes through
+      // `client.offlineDb` without checking it initialized, so an unopenable one rejects those
+      // writes.
       if (keyGetter) {
         SqliteClient.getEncryptionKey = keyGetter;
         try {
@@ -100,9 +96,7 @@ export const useInitializeOfflineDb = ({
     setOfflineDb(attachedOfflineDb);
     if (attachedOfflineDb) {
       await attachedOfflineDb.init(userID);
-      // Note: Since `init()` currently swallows errors by design, we have to rely
-      // on consuming the error later in order to be able to still rethrow without
-      // introducing a breaking change.
+      // `init()` swallows errors by design, so the failure is read back from `initializationError`.
       // TODO: The DB API should be changed in the next major to always throw upwards
       //       and let integrators handle it if necessary.
       setInitializationError(