moderator-toolbox-nxg-for-reddit / util/wiki/schemas/usernotes/codec

codec¶

Functions¶

buildShardPayload()¶

buildShardPayload(users): NxgShardPayload

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:364

Builds the human-readable NXG shard payload from a slice of users. Pure, synchronous, and deterministic - users sorted by name, fixed note key order - so the serialized payload doubles as the dirty-shard fingerprint.

Notes missing an index (data straight from a legacy decode, or older in-memory state) are assigned one here in array order, starting from the user’s nextIndex (or past the highest existing index); assignment is order-stable, so repeated builds of the same data agree.

Parameters¶

users¶

Record<string, UsernotesUser>

The user slice to serialize.

Returns¶

NxgShardPayload

buildUsernotesV6Payload()¶

buildUsernotesV6Payload(data): UsernotesV6Payload

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:136

Builds the deflated v6 payload from inflated usernotes. Pure, synchronous, and deterministic - users are sorted by name, so the same logical data always produces the same payload regardless of object key order.

Only active (non-archived) notes survive: archiving is an NXG concept the v6 format can’t carry, and archived notes’ absence from the legacy page is what lets reconciliation treat any deviation of that page as a 6.x edit. Note indexes are likewise dropped (v6 is position-addressed). Users left with no active notes are omitted entirely.

Parameters¶

data¶

UserNotesData

The inflated usernotes to deflate.

Returns¶

UsernotesV6Payload

decodeNotesShard()¶

decodeNotesShard(page, cacheKey): Promise<{ corrupted: boolean; users: Record<string, UsernotesUser>; }>

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:415

Decodes an NXG shard page into the inflated user map. The blob is decompressed in the background service worker.

Tolerant of damage: malformed note entries are dropped (flagged via corrupted), malformed archived objects are ignored (note treated as active), and missing or duplicate indexes are repaired by reassigning from the user’s nextIndex (also flagged).

Parameters¶

page¶

NxgUsernotesShardPage

The parsed shard page envelope.

cacheKey¶

string

Key for the background decompression cache; sharded reads pass a per-shard key so parallel decodes don’t evict each other.

Returns¶

Promise<{ corrupted: boolean; users: Record<string, UsernotesUser>; }>

decodeUsernotesV6()¶

decodeUsernotesV6(raw, subreddit, cacheKey?): Promise<UserNotesData | null>

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:182

Decodes a parsed v6 wiki page into the inflated app shape. The zlib blob is decompressed in the background service worker.

Parameters¶

raw¶

RawUsernotesBlob

The parsed v6 page JSON.

subreddit¶

string

The owning subreddit, used to expand squashed links.

cacheKey?¶

string = subreddit

Key for the background decompression cache. Defaults to the subreddit; sharded reads pass a per-shard key so parallel shard decodes don’t evict each other.

Returns¶

Promise<UserNotesData | null>

The inflated data, or null when the schema version is not v6.

encodeNotesShard()¶

encodeNotesShard(users): NxgUsernotesShardPage

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:395

Encodes a slice of users as a complete NXG shard page: payload JSON -> zlib -> base64, wrapped in the nxg-usernotes envelope.

Parameters¶

users¶

Record<string, UsernotesUser>

The user slice to encode.

Returns¶

NxgUsernotesShardPage

encodeUsernotesV6()¶

encodeUsernotesV6(data): RawUsernotesBlob

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:163

Encodes inflated usernotes into the v6 on-page shape: constants pooled, users deflated, blob zlib-compressed and base64-encoded.

Parameters¶

data¶

UserNotesData

The inflated usernotes to encode.

Returns¶

RawUsernotesBlob

isNxgUsernotesShardPage()¶

isNxgUsernotesShardPage(value): value is NxgUsernotesShardPage

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:336

Returns true when a parsed page object is an NXG usernotes shard envelope.

Parameters¶

value¶

unknown

Returns¶

value is NxgUsernotesShardPage

isPlaceholderType()¶

isPlaceholderType(type): boolean

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:254

Returns true for a placeholder type definition - the {key, text: key, color: ''} entry seedV6Types invents for a key it has no definition for.

Parameters¶

type¶

UserNoteColor

Returns¶

boolean

isSeededDefaultType()¶

isSeededDefaultType(type): boolean

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:263

Returns true for a type definition identical (name and color) to the built-in default for its key - what seedV6Types copies in when it has no subreddit config to seed from.

Parameters¶

type¶

UserNoteColor

Returns¶

boolean

isSeededType()¶

isSeededType(type): boolean

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:272

Returns true for a type definition a migration may have invented rather than taken from the subreddit: a placeholder or an untouched built-in default.

Parameters¶

type¶

UserNoteColor

Returns¶

boolean

needsSeededTypesRepair()¶

needsSeededTypesRepair(notes): boolean

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:281

Returns true when a dataset still needs the seededTypesRepair: it has seeded types (see isSeededType) and the repair has not already run.

Parameters¶

notes¶

UserNotesData

Returns¶

boolean

noteIdentityKey()¶

noteIdentityKey(user, note): string

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:112

The identity key of a note for deduplication and legacy-page reconciliation: (username, time, note text, mod). Timestamps are epoch seconds both in memory and on every wire format, so a note compares equal to itself across a legacy round-trip without any normalization.

Parameters¶

user¶

string

note¶

UserNoteEntry

Returns¶

string

repairSeededTypes()¶

repairSeededTypes(types, recovered, usage): UserNoteColor[]

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:312

Replaces seeded type definitions (see isSeededType) with the subreddit’s own, recovered from its legacy config history. Only exact seeded entries are touched, so names and colors a mod has since edited are kept.

On a customized subreddit the built-in defaults were never its types, so a seeded default no note uses is dropped; one still in use is kept, as its notes would otherwise lose their label. A never-customized subreddit keeps its defaults: 6.x offered them too.

Parameters¶

types¶

UserNoteColor[]

The current type definitions (not mutated).

recovered¶

RecoveredTypes

The definitions recovered from the config history.

usage¶

ReadonlyMap<string, number>

Notes per type key, archived notes included.

Returns¶

UserNoteColor[]

The repaired list.

seedV6Types()¶

seedV6Types(data, configColors?): UserNoteColor[]

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:234

Seeds usernote type definitions for v6 data: the subreddit’s configured usernoteColors when present, otherwise the built-in defaults, plus an entry for any note type key not covered by either. Used to populate the self-contained types carried by the NXG usernotes manifest.

Parameters¶

data¶

UserNotesData

The inflated v6 data to scan for unknown type keys.

configColors?¶

UserNoteColor[]

The subreddit’s usernoteColors config, if any.

Returns¶

UserNoteColor[]

squashPermalink()¶

squashPermalink(permalink): string

Defined in: extension/data/util/wiki/schemas/usernotes/codec.ts:51

Squashes a full reddit permalink into the compact stored form: l,<postId>[,<commentId>] for comments/submissions, m,<id> for modmail, or '' when the link isn’t recognized.