🎙️ task - fix(types): export HelpfulErrorMetadata from the package index — subclass authors cannot name the constraint

Start in src/index.ts, where HelpfulError and type HelpfulErrorCode are exported, and add HelpfulErrorMetadata beside them. Check the subclass pattern described in the issue to confirm the type is importable from the package entry point; a README note about subclassing is an optional follow-up.

🦫🎙️ dispatch to foreman

💧 task enqueued
   ├─ priority = ?
   ├─ yieldage = ?
   └─ leverage = ?

title
fix(types): export HelpfulErrorMetadata from the package index — subclass authors cannot name the constraint
description

what

add type HelpfulErrorMetadata to the package index export, beside HelpfulErrorCode.

why

HelpfulError and every subclass are generic over TMetadata extends HelpfulErrorMetadata. a consumer that declares its own subclass MUST name that constraint:

export class UnauthorizedRequestError<
  TMetadata extends HelpfulErrorMetadata = HelpfulErrorMetadata,   // <- unnameable
> extends BadRequestError<TMetadata> { ... }

but src/index.ts exports HelpfulError and type HelpfulErrorCode, and NOT HelpfulErrorMetadata. so the one type a subclass author needs is the one type they cannot import. the two workarounds are both poor: reach into helpful-errors/dist/HelpfulError (past the public entry into a build artifact), or redeclare Record<string, any> & { cause?: Error } locally (drifts). svc-gateway took a third route — type HelpfulErrorMetadata = NonNullable<HelpfulError["metadata"]> — which works but is a puzzle for a type the package already has.

why it bites

HelpfulError.throw binds this: T extends typeof HelpfulError, reading the constructor return type. a non-generic subclass returns HelpfulError<HelpfulErrorMetadata> where HelpfulError<TMetadata> is demanded, so .throw becomes unreachable (TS2684). the fix is to make the subclass generic — which needs the unexported constraint. so the gap blocks the documented subclass pattern.

ask

add type HelpfulErrorMetadata to the index export. one line. worth a readme note too, since subclasses are a first-class use of this package.

source

found during the declapract upgrade of ahbode/svc-gateway (branch vlad/bump-practs), item 8 of .dream/2026_08_12.upstream-sdk-zod-glossary-splits