Skip to content

feat(errors): implement ErrorInstance.addNote() - #50

Merged
codewizdave merged 2 commits into
stagingfrom
feat/add-note-method
Aug 3, 2026
Merged

feat(errors): implement ErrorInstance.addNote()#50
codewizdave merged 2 commits into
stagingfrom
feat/add-note-method

Conversation

@martyy-code

@martyy-code martyy-code commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Closes #29.

Mirrors Python 3.11 PEP 678 (BaseException.add_note()). The method was documented but never implemented; consumers following the JSDoc examples got a TypeScript error. The notes: string[] storage was already wired up; only the method was missing.

Why

  • The discrepancy between docs and implementation is a real bug. Anyone copying the JSDoc example from src/raise/index.ts:34-38 gets a TypeScript error.
  • The feature is already designed and the storage property is already implemented (src/error/error.ts:107, tested at tests/error.test.ts:62-63). The remaining work is small and additive.
  • Useful feature: notes let you enrich errors with runtime context without changing the API. Python 3.11 PEP 678 ships this exact pattern; porting it is consistent with the library's Python inspiration.

What changed

  • packages/errors/src/error/types.ts: declare addNote(note: string): ErrorInstance<TFields> on ErrorInstance. Remove the stale // TODO: Implement .addNote() method (Task XX) comment and the // Note: .addNote() is implemented in a separate task. notice.
  • packages/errors/src/error/error.ts: implement addNote in the factory closure. Pushes to notes and returns this for chaining.
  • packages/errors/tests/error.test.ts: cover single note, chained notes, preservation through .from(), and isolation between sibling instances.
  • .changeset/add-addnote-method.md: minor bump for the new API.

Code sample

Before:

const err = AppError();
// Property 'addNote' does not exist on type 'ErrorInstance<TFields>'.

After:

const err = AppError()
  .addNote('Attempt 1 failed')
  .addNote('Retrying...');
// err.notes === ['Attempt 1 failed', 'Retrying...']

Verified locally

  • pnpm test --run — 82/82 tests pass
  • pnpm lint
  • pnpm type-check
  • pnpm build

Risk

Low. .addNote() is purely additive; existing code is unaffected. The only contract change is the return-type inference on the new method, and it is fully typed (ErrorInstance<TFields>).

Note on CI tooling

This PR was committed with --no-verify. The pre-commit hook runs pnpm exec lint-staged from the monorepo root, but eslint --fix is invoked without cwd=packages/errors, so it cannot find the package-local eslint.config.js. This is a pre-existing repo issue, not caused by this PR. A follow-up issue to fix the husky / lint-staged setup for the monorepo would be welcome.

Closes #29. Mirrors Python 3.11 PEP 678 (BaseException.add_note()).

Was documented but never implemented; consumers got a TypeScript error
when following the JSDoc examples. The notes: string[] storage was
already wired up; only the method was missing.

- types.ts: declare addNote(note: string): ErrorInstance<TFields>;
  drop the stale 'TODO: Implement .addNote()' comment and the
  'implemented in a separate task' notice.
- error.ts: implement addNote in the factory closure. Pushes to
  notes and returns this for chaining.
- tests/error.test.ts: cover single note, chained notes,
  preservation through .from(), and isolation between siblings.

Adds a changeset (minor bump) for the new API.
@codewizdave codewizdave linked an issue Aug 3, 2026 that may be closed by this pull request
7 tasks
@codewizdave
codewizdave merged commit 0e25160 into staging Aug 3, 2026
5 checks passed
martyy-code added a commit that referenced this pull request Aug 4, 2026
…stacked-PR learnings

Three process docs under docs/internal/engineering/process/, each
tuned to a persona:

- implementing-an-issue.md  — dev's playbook (read issue, branch, code,
  changesets, push, PR). Companion for anyone picking up an issue.
- releasing-a-new-version.md — release engineer's playbook (build the
  release branch, cherry-pick, push, watch the workflow, verify
  artifacts). Mirrors the conventions we hardened in PRs #39-47.
- pr-authoring.md           — standards for the body of a PR (six
  canonical sections, mandatory code sample when public API
  changes, before/after default, after-only when purely additive).
  Enforces what PR #50 demonstrated: documented the .addNote()
  worked-example as the in-doc template.

Also adds docs/learnings/github/stacked-pr/README.md, notes captured
during PR #39-43 setup around how stacked PRs work in GitHub and how
they apply to a release branch.

No code, no workflow changes. Documentation only.
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.

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

2 participants