Skip to content

[Feature]: Implement .addNote() method on ErrorInstance #29

Description

@martyy-code

Description

ErrorInstance is documented as having an .addNote() method, but the method has never been implemented. Anyone copying the JSDoc example from src/raise/index.ts:34-38 (or similar examples in the docs site) will get a TypeScript error:

Property 'addNote' does not exist on type 'ErrorInstance<TFields>'.

We should either implement the method or remove the misleading documentation. This issue proposes implementing it, since the Python 3.11-inspired add_note() is a useful feature and is documented elsewhere in the project (issues #9 and #10, internal task docs at docs/internal/tasks/v1.1.0/).

Proposed API

Mirrors Python 3.11's BaseException.add_note(note) semantics:

const AppError = error({ name: 'AppError' });

try {
  processData(input);
} catch (err) {
  raise(AppError().addNote('Processing failed at line 42'));
}

// Chainable
raise(
  AppError()
    .addNote('Attempt 1 failed')
    .addNote('Retrying...')
    .addNote('Attempt 2 failed')
);

Why

  • The docs already promise it. src/raise/index.ts:34-38, src/error/types.ts:40, and src/error/types.ts:46-47 all reference .addNote(). The discrepancy between docs and implementation is a real bug — anyone learning from the source gets a TypeScript error.
  • Useful feature. Notes let you enrich errors with runtime context without changing the API. Python's add_note() (PEP 678) is a well-loved pattern; porting it is consistent with the library's Python inspiration.
  • Already designed. docs/internal/tasks/v1.1.0/implementation/task-01-add-note-method.md has the design spec, including the type signature:
    addNote(note: string): ErrorInstance<TFields>;
  • notes: string[] is already implemented. The storage property is initialized in src/error/error.ts:107 and tested at tests/error.test.ts:62-63. The implementation is small.

Acceptance criteria

  • Declare addNote(note: string): ErrorInstance<TFields> on ErrorInstance in src/error/types.ts
  • Implement addNote in the factory in src/error/error.ts (push to notes, return this for chaining)
  • Remove the stale // TODO: Implement .addNote() and // Note: .addNote() is implemented in a separate task. comments in src/error/types.ts
  • Add unit tests covering: single note, multiple chained notes, notes preserved through .from() chaining
  • Add a type test for the return-type inference (see docs/internal/tasks/v1.1.0/testing/task-04-type-tests-add-note.md)
  • Verify pnpm lint, pnpm test, pnpm build, pnpm type-check all pass
  • Update CHANGELOG.md (via a .changeset/*.md file) describing the new API

Related

  • Issue [Feature]: Add .addNote() method to ErrorInstance #9[Feature]: Add .addNote() method to ErrorInstance (open, status: triage). This issue may be a duplicate — feel free to close one in favor of the other.
  • Issue [Feature]: Add notes property to ErrorInstance #10[Feature]: Add notes property to ErrorInstance. The notes property is already implemented; only .addNote() is missing.
  • docs/internal/tasks/v1.1.0/implementation/task-01-add-note-method.md — design spec (file paths in this doc are stale; correct paths are src/error/types.ts and src/error/error.ts)
  • docs/internal/tasks/v1.1.0/implementation/task-02-notes-property.md — already done
  • docs/internal/tasks/v1.1.0/testing/task-03-unit-tests-add-note.md — test spec
  • docs/internal/tasks/v1.1.0/testing/task-04-type-tests-add-note.md — type-test spec
  • docs/learnings/ — v1.1.0 feature drift memory

Risks

  • Low risk, additive. .addNote() is purely additive; existing code is unaffected.
  • Naming. .addNote() matches Python. Alternatives like .withNote() or .tag() were considered in issue [Feature]: Add .addNote() method to ErrorInstance #9.
  • Persistence through .from(). Need to decide whether a child's notes are preserved when .from() chains a cause. Default proposal: preserve own notes (the chained .from() returns the same instance, so this is automatic). Merging the cause's notes is an option but surprising.

Estimate

  • Effort: Small (S — half a day). Implementation is ~10 lines. Tests add another hour.
  • Priority: Medium (p2). It's been documented but not implemented for a long time; not urgent but the doc/code discrepancy should be resolved.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions