Repository navigation
chore: tidy source comments - #1921
Merged
Merged
Conversation
oliverlaz
requested review from
MartinCupela,
isekovanic and
szuperaz
as code owners
October 20, 2026 06:48
isekovanic
approved these changes
Oct 20, 2026
MartinCupela
approved these changes
Oct 20, 2026
Rewrite the comments and JSDoc in src (excluding the generated src/gen) so they describe the code as it is now and only where it is not obvious. History of past behavior, review ids, restatements of signatures and per-class boilerplate are gone, and comments that no longer matched the code were corrected. Comment-only: the compiled output is identical apart from comments. The one non-comment change is whitespace, where prettier re-laid out the MessagePaginator super() call after an inner comment was removed.
Fix comments that did not match the code, restore lost reasons where they prevent likely mistakes, and restore @param/@returns on exported public API. Prose now uses ID casing and "Defaults to X." consistently. JSDOC.md gains a public API vs internals section (tags on public API, prose only for internals) and the content rules the cleanup follows. Comment-only: compiled code is unchanged.
Add the missing @param/@returns on public API (EntityStore, on/off overloads, config methods and others), correct comments that did not match the code, and mark SDK-only members @internal. JSDOC.md now says the public API rule applies to docs that are added or edited. Comment-only: compiled code is unchanged.
Make base-class docs generic (no subclass names or message/channel/thread examples in BasePaginator, StoreBackedItemIndex, ConfigController and the pagination utils), and correct comments that did not match the code: silent loading, markRead candidate drop, userMuteStatus throws, the offline pending-task and new-message channel guard behaviour, and which inputs initializeConfig rebuilds from. Also restores the nanosecond note on reminder timestamps, documents getMemberUserId, and fixes the publishTypingEvents shape description, which claimed typing events are off for threads and edits (the default is true). That description string is the only non-comment change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
isekovanic
force-pushed
the
chore/tidy-source-comments
branch
from
October 20, 2026 11:43
3900ac1 to
18a268d
Compare
isekovanic
pushed a commit
that referenced
this pull request
Oct 20, 2026
…1922) Stacked on #1921. While tidying the source comments, the reviewers noted 11 possible code issues. This PR checks each one and fixes the confirmed ones. Each behavior fix has a unit test that fails without it. ### Fixed - **`UploadManager.upload`**: `resolveAttachmentManager` ran outside the `try`, so an invalid channel cid left the returned promise pending forever and the `inFlightUploads` entry stuck (retries got the dead promise back). It now rejects and cleans up. - **`BasePaginator.intervalComparator`**: `if (!aEdges || !bEdges) return 0` made the "unbounded intervals go last" lines unreachable and the comparator inconsistent, so bounded intervals could be mis-ordered around an empty one. Changed to `&&`. - **`FixedSizeQueueCache`**: a falsy key (for example `0`) was dropped from the queue but stayed in the map forever, and a falsy value was never disposed or promoted on `get`. `get` also compared against `size - 1` instead of the queue length. - **`StableWSConnection`**: `_connect` re-published the connection id after `onmessage` had already done it, which could revive an id invalidated in between (for example by a synchronous health listener). Only the hello frame publishes it now. `clearInterval` on timeout refs is now `clearTimeout` (cosmetic). - **`MessageIntervalPaginator.truncate`**: when the active window was the logical head (live messages, no page loaded), truncation blanked the list even though newer messages survived. The surviving logical window is re-emitted now. - **`channel.ts`**: removed the dead `userReadState` bindings and a redundant `!overrideCurrentState`. The `mute()` / `unmute()` examples passed `{ user_id }`, which the generated request types do not have, so those examples are removed. - **`mentions.ts`**: collapsed the dead first `sort` assignment in `prepareQueryMembersParams`. - **`configuration/shape.ts`**: the `description` strings are public (`INSTANCE_CONFIG_TREE_SHAPE` is exported for settings UIs), so the "Was `StreamChatOptions.X`" history and the em-dashes were removed. A test guards against both. ### Dismissed - `offline_sync_manager`: `client.wsConnection` is a non-optional field set in the constructor, so the bare access is safe. `Date#toString()` round-trips through `new Date()` by spec, and the precision lost is irrelevant for the 30-day check. Switching to ISO would change what RN's offline DB stores, so that would need coordinating with RN. - `sortCompiler.binarySearch`: the unbounded plateau scan is needed. `locateByItemInIntervals` relies on it to find items whose sort key was changed in place, which no longer sit in their plateau. - `truncate` only setting `isTail` on anchored intervals: `LogicalInterval` has no pagination flags, so this is by design. ### Needs a decision (not changed here) - `ChannelStateOptions.skipHydration` and `client.preventThreadCleanup` are unused. They are already tracked in `ai-docs/v10-followups.md`. `skipHydration` is v9 API, so removing it is a breaking change. - `ConnectionIdManager.reset()` is public (via `src/connection`) and has no caller in `src`. We can remove it before 10.0.0 or keep it. - `FixedSizeQueueCache.add` does not dispose the old value when an existing key is overwritten. Changing that changes the behavior of a public utility. - `truncate`: when the active anchored window is removed and only logical windows survive, the list is still emptied rather than switching to a logical survivor. - Server-side `mute` / `unmute` on behalf of a user: the generated request types have no `user_id`, so this cannot be expressed with types.
|
🎉 This PR is included in version 10.0.0-rc.23 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
CLA
Description of the changes, What, Why and How?
Stacked on #1920: this PR targets
fix/v10-hotfixesand should merge after #1920. Against that base it is comment-only; againstrelease-v10its diff also shows #1920's changes until #1920 lands.What: Rewrites the comments and JSDoc in
src(excluding the generatedsrc/gen) and updatesJSDOC.md. 134.tsfiles change, and comment lines drop from about 11.4k to 6.3k.Why: The v10 refactorings left long, partly outdated comment prose: how things used to behave, review ids, method lists that restate signatures, and boilerplate repeated per class. Comments now describe the code as it is, only where it is not obvious. Comments that no longer matched the code were corrected, several of them predating this PR.
How: Comment-only. Compiled output is identical for every file apart from comments (each file was transpiled with comments removed, before and after, and compared). Exported public API keeps a summary plus
@param/@returns; internals are documented in prose. Prose usesIDcasing andDefaults to X..JSDOC.mdgains a public API vs internals section and the content rules this PR follows.TODO/FIXMElines, lint directives and commented-out code are untouched.yarn lint,yarn typesandyarn testpass.Reviewing: The diff is large and mostly deletions. The useful feedback is any comment that is still wrong, and any "why" that should have stayed.
Changelog
src. No behaviour change.