Skip to content

refactor: one error base class, one problem document, one table of network codes - #740

Merged
eizedev merged 2 commits into
mainfrom
refactor/error-base
Nov 22, 2026
Merged

eizedev merged 2 commits into
mainfrom
refactor/error-base

Conversation

@eizedev

@eizedev eizedev commented Nov 22, 2026

Copy link
Copy Markdown
Owner

Step 4 of the layering rework: one error base class, one problem-document builder, and one table of network codes.

What changed

  • CodedError is the base of every error class of the packages: PivotkitError, CliError (and so RemoteError), OperationError, and in pivotkit-server AuthRefusal, CommandError, SecretError, OpenApiError, SignedTokenError, AnswerShapeError, SourceError, SecretFileError, UploadFailure, ConfigError and GuardedFetchError.
    • It lives in packages/pivotkit-core/src/errors.js and is exported only from pivotkit-core/internal, so it is not public API.
    • It holds code and details, and sets each only when it is given. A class adds only its own members and its name.
    • Its two template parameters type code and details per class (@extends {CodedError<C, D>}). The public types stay as they were: PivotkitError.code is PivotkitErrorCode, OperationError.details is OperationErrorDetails | undefined, CliError.code is string.
    • Three classes carry no code (AuthRefusal, OpenApiError, AnswerShapeError). They take undefined for it, and still have no code member.
  • problemDocument in rest/problem.js is the one shape of an RFC 9457 problem: type, title, status, code, detail, then further members.
    • problem() (REST) and the download links' answers (downloads.js answerOf) build it there.
    • typeOf is no longer exported, since only problemDocument uses it.
    • I read "the problem-document mapping" as these builders. problemOf was already the one mapping from an error to a problem.
  • NETWORK_FAILURES in pivotkit-node/net is the one table of a failed connection's codes, as you asked. It replaces:
    • TRANSIENT in sources/fetch.js, now the column retry
    • NETWORK_CODES in sources/run.js, now the column passes
    • NETWORK_TEXTS in the CLI's remote.js, now the column text

Behaviour: no change

  • Error members. I made one instance of every class on origin/main and on this branch, and compared them. Name, own members, code, details, message and cause are identical. test/errors.test.js pins them. The one difference is the enumeration order of own keys: code now comes first. Nothing in the code or tests reads that order, so it would show only in a consumer's JSON.stringify(error) or a crash printout.
  • Network table. Each column equals the old list exactly, and test/net.test.js pins the sets. The CLI's words are byte-identical; I compared them by script.
  • The two readings of "may work again" stay different, because each stays as its caller had it:
    • guardedFetch's retry includes EPIPE, EHOSTUNREACH, ENETUNREACH and ECONNABORTED.
    • A source's passes includes undici's three timeouts.
    • The table shows the difference in one place now. Whether it should be one rule is a question for an issue, not this pull request.
  • Problems. REST and download problems have the same members in the same order.

Release note

  • pivotkit-report, pivotkit-node and pivotkit-server import CodedError from pivotkit-core/internal. A published pivotkit-core 0.9.0 does not have it, so the release must raise their pivotkit-core ranges to the new core.
  • tests/ci.test.js already asks for that when core's version moves.

Not part of this change (say what does not fit)

  • An unreadable body on the download links gets a short { code, requestId } problem, not a full document. That was so before, and the code now says so in a comment.
  • sign-in.js keeps its own TRANSIENT set. It lists the CLI's RemoteError codes, not network codes.

Growth (scripts/growth.js measures, before → after)

before after
functions over 120 lines 47 47
functions over complexity 25 105 105
unused exports and files (knip) 222 222
jscpd clones / duplicated lines 218 / 1566 218 / 1566
docs lines 25820 25820

No baseline entry changed.

Checks

  • npm run lint, npm run types, npm test (all workspaces and tests/), npm run growth, npm run pack:check: green locally.
  • The server, CLI and MCP integration tests are part of npm test.
  • No browser tests: no UI is touched.
  • A neutral review compared old and new instances and the generated .d.ts. Its findings are fixed:
    • the generic types, which keep OperationError.details typed and give the classes without codes an honest type
    • frozen table entries
    • tests for CodedError and problemDocument
    • the net.js header and the changelogs

Places checked for docs:

  • the root AGENTS.md (one line)
  • the core, node and server AGENTS.md
  • the CHANGELOGs of core, report, node, server and cli

docs/reference/service-exports.md needs no change, because nothing public was added or removed.

🤖 Generated with Claude Code

eizedev and others added 2 commits November 22, 2026 22:09
…twork codes

Every error class of the packages extends CodedError (pivotkit-core/internal), which holds
code and details; each class keeps its name and members. REST problems and the download
links' problems are built by problemDocument. guardedFetch's transient codes, a source's
codes that may pass and the command line's words for a failed connection are one table,
NETWORK_FAILURES in pivotkit-node/net.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…twork table

Review follow-ups: CodedError takes the types of code and details as template
parameters, so each class keeps the types it had (OperationError's details) and a class
without codes says so; NETWORK_FAILURES' entries are frozen; tests for CodedError and
problemDocument; net.js header and changelogs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev merged commit c7ec822 into main Nov 22, 2026
25 checks passed
@eizedev
eizedev deleted the refactor/error-base branch November 22, 2026 21:31
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