moderator-toolbox-nxg-for-reddit / modules/shared/usernotes/moduleapi
modules/shared/usernotes/moduleapi¶
Functions¶
activeNotes()¶
activeNotes(
notes):UserNoteEntry[]
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:63
Returns only the active (non-archived) notes from a list.
Parameters¶
notes¶
Returns¶
autoArchiveOldNotes()¶
autoArchiveOldNotes(
data,types):number
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:78
Archives active notes that have outlived their type’s configured
auto-archive window (autoArchiveDays; 0 archives every note of the type
on each save). Archived notes are attributed to the AUTO_ARCHIVER
sentinel. Notes whose type has no window configured, or with an empty or
unknown type key, are left untouched. Mutates data in place.
Parameters¶
data¶
types¶
Returns¶
number
The number of notes archived.
createLatestModNoteFetcher()¶
createLatestModNoteFetcher(): (
subreddit,user) =>Promise<ModNote|null>
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:439
Creates a debounced fetcher for the most recent mod note on a user in a subreddit. Batches up to 500 concurrent requests into a single API call. Does not return AI-generated user summary “notes.”
Returns¶
(subreddit, user) => Promise<ModNote | null>
findSubredditColor()¶
findSubredditColor(
colors,key):UserNoteColor
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:427
Finds the color definition for a note type key within a subreddit’s color list.
Parameters¶
colors¶
key¶
string
Returns¶
The matching color entry, or a blank sentinel {key: 'none', color: '', text: ''} if not found.
getSubredditColors()¶
getSubredditColors(
subreddit):Promise<UserNoteColor[]>
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:414
Returns the usernote type colors for a subreddit from the usernotes manifest, falling back to the built-in defaults when the subreddit has no notes page.
Parameters¶
subreddit¶
string
Returns¶
Promise<UserNoteColor[]>
getUser()¶
getUser(
users,name):FoundUser|undefined
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:57
Looks up a user in the notes map, merging notes from both a lowercase and the canonical-cased key when both exist. Delegates to resolveDualKeyUser (the same routine the mutation path uses) with the read-path policy, so indexes shown in the UI stay addressable by a subsequent mutation.
Parameters¶
users¶
Record<string, UsernotesUser>
name¶
string
Returns¶
FoundUser | undefined
The merged user object with notes sorted newest-first, or undefined if no notes exist.
getUserNotes()¶
getUserNotes(
subreddit,forceSkipCache?):Promise<UserNotesData>
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:112
Loads and inflates usernotes for a subreddit, using an in-extension cache to avoid redundant wiki reads.
Parameters¶
subreddit¶
string
The subreddit to load usernotes for.
forceSkipCache?¶
boolean
When true, bypasses the cache and re-fetches from the wiki.
Returns¶
Promise<UserNotesData>
Throws¶
If the wiki page does not exist, the schema is unrecognized, or network/API errors occur.
saveUserNotes()¶
saveUserNotes(
subreddit,notes,reason):Promise<void>
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:223
Encodes and saves usernotes to the subreddit wiki, then updates the cache.
The canonical NXG sharded layout is written first; compat-on subs then
refresh the legacy usernotes mirror as a single v6 blob (its literal path
has a special 1MB allowance from Reddit, and 6.x parses it directly). A
mirror failure is non-fatal - the canonical save already succeeded and the
next save refreshes the mirror. Legacy-fallback subs write the legacy page
only.
Concurrent saves for the same subreddit are serialized so a later write can’t race an earlier in-flight one and silently discard its changes.
Parameters¶
subreddit¶
string
The subreddit to save usernotes for.
notes¶
The usernotes data to persist.
reason¶
string
Wiki revision note describing the change.
Returns¶
Promise<void>
Throws¶
On codec or network errors, or when notes outgrow a page limit.
updateNoteCache()¶
updateNoteCache(
subreddit,notes):Promise<void>
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:44
Updates the in-extension note cache for a subreddit after a load or save.
Parameters¶
subreddit¶
string
notes¶
Returns¶
Promise<void>
updateUserNotes()¶
updateUserNotes(
subreddit,transform):Promise<UserNotesData|undefined>
Defined in: extension/data/modules/shared/usernotes/moduleapi.ts:352
Serialized read-merge-write for a subreddit’s usernotes: re-reads the
current stored dataset from the wiki inside the per-subreddit save queue,
hands it to transform to mutate in place, then persists the merged result.
Reading inside the queue is what makes this safe against concurrent editors:
a snapshot loaded when a popup opened can be stale by save time (another mod
may have added a note since), and writing that snapshot back would silently
drop their note. By re-reading the live state and applying only the caller’s
change to it, notes added elsewhere survive. transform must therefore
express the change (add/edit/delete this note, prune these users) rather
than assume the dataset it receives matches what the UI last showed.
A subreddit with no usernotes page yet reads as an empty dataset so an add
transform can create the first note. When transform returns undefined
(a no-op, e.g. an edit whose target note no longer exists) nothing is
written.
Parameters¶
subreddit¶
string
The subreddit whose notes to update.
transform¶
(notes) => string | undefined
Mutates the freshly-read dataset in place and returns a wiki
revision reason, or undefined to abort the write.
Returns¶
Promise<UserNotesData | undefined>
The merged dataset (written when a reason was returned), or
undefined when the fresh read failed for a reason other than a missing page.