Skip to content

docs(reference/sdk): align error-handling emphasis between the reference page and package JSDoc #1690

Description

@rickylabs

Context

PR #1671 (#1350, sdk-typed-error-channel) rewrites the golden-path example in
docs/site/services-sdk/sdk.md and docs/site/services-sdk/how-to/discover-services.md from tuple
destructuring plus isDefinedError narrowing to the discriminant form (result.isSuccess first,
then result.isDefined), and drops the isDefinedError import from the example.

docs/site/reference/sdk/index.md is the third page documenting this API and was deliberately left
out of #1671's six-path ceiling. It still presents the API around the tuple ergonomic:

  • :40isDefinedError | function | "Narrow an unknown error to an oRPC defined error."
  • :58SafeResult | type alias | "Tuple/object result returned by safe."
  • :60SafeFailure | type alias | "Failure branch returned by safe."

These rows are not wrong

Verified against source at #1671's head: packages/sdk/src/client/errors.ts keeps both SafeFailure
arms as tuple-and-object intersections, so const [error, result] = await safe(...) still
destructures and "Tuple/object result returned by safe" remains accurate. isDefinedError is still
exported and still narrows. This is cross-page emphasis debt — the guide stopped showcasing the
tuple form while the reference still frames around it — not two contradictory contracts, and not
a #1350 acceptance failure.

Why it is ungated

  • docs:exports-drift is silent: no exported symbol name changes, and sdk runs in
    entrypoints-only coverage mode, so its reference-page symbol rows are never checked at all.
  • docs:snippets compiles fenced code, not table rows.

Why this is not a 3-row edit

Those row descriptions are verbatim the package's own JSDocerrors.ts:68-70 reads "Failure
branch returned by {@link safe}." and :75-77 reads "Tuple/object result returned by {@link safe}."
Editing the rows without editing the JSDoc would create source-to-reference drift where none exists
today. Any fix is rows plus JSDoc.

Scope

Non-blocking. Align emphasis across the reference page and the package JSDoc so both lead with the
discriminant form while still documenting the tuple ergonomic as supported. Precedent: #1670.

Refs #1350. Found by the 0.0.7 docs topic supervisor during a read-only audit of #1671; confirmed and
scoped by the fixes topic supervisor.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions