Skip to content

docs(node): document that sync config readers require initializeGT - #471

Open
moss-bryophyta wants to merge 1 commit into
mainfrom
docs/node-sync-accessors-require-init
Open

docs(node): document that sync config readers require initializeGT#471
moss-bryophyta wants to merge 1 commit into
mainfrom
docs/node-sync-accessors-require-init

Conversation

@moss-bryophyta

Copy link
Copy Markdown
Contributor

Problem

Four gt-node reference pages describe synchronous configuration readers without mentioning that they throw when called before initializeGT. initialize-gt.mdx already documents this precondition, but names only the translation functions (withGT, getGT, getMessages), so these four look exempt.

get-version-id.mdx had the sharper problem: it stated getVersionId "returns undefined when no version ID is configured." That is true only after initialization. Before it, the call throws — so a reader following the documented ?? null example on a cold path gets an exception instead of a null.

Verification

Runtime-checked against installed gt-node@1.0.15 (current published version), not the changelog:

getVersionId     -> THROWS: Cannot read I18nCache before it has been initialized
getDefaultLocale -> THROWS: Cannot read I18nConfig before it has been initialized
getLocales       -> THROWS: Cannot read I18nConfig before it has been initialized
getRequestLocale -> THROWS: Cannot read I18nConfig before it has been initialized

And after initializeGT({ defaultLocale: 'en', locales: ['en','fr'] }) with no version ID set:

getVersionId() -> undefined

So the documented string | undefined return is correct, and the missing piece is the precondition.

getLocale is intentionally not changed — it throws for a different reason (the request-scoped condition store) and its page already documents the withGT scope requirement accurately.

Changes

  • Added a Requires initialization bullet to get-default-locale, get-locales, get-request-locale, and get-version-id, matching the existing house phrasing in with-gt.mdx ("must be called before X is used, or an error is thrown").
  • Reworded get-request-locale's note, which softened a hard throw into "so it knows which locales are supported."
  • Scoped get-version-id's undefined claim to post-initialization.
  • Extended the initialize-gt.mdx note to name the four readers.

Checks

All 5 validators pass: unsafe-html 450, callouts 450, reference-links 404/256 aliases, structure valid, links all valid.

Found during a routine audit of the node docs against the published package.

getDefaultLocale, getLocales, getRequestLocale, and getVersionId all throw
when called before initializeGT, but their reference pages described them
only as synchronous config readers. getVersionId's page went further and
said it returns undefined when no version ID is configured, which is true
only after initialization.

Verified against installed gt-node@1.0.15.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant