feat(contract): error factory

[dinwwwh]

Adds an error() factory to @orpc/contract that creates reusable ORPCError classes bound to a code, default message, and data schema. A factory class can be thrown anywhere, registered directly in .errors() under its code, and checked with instanceof with full type narrowing. The createORPCErrorConstructorMap utilities also move from @orpc/server into @orpc/contract so the whole error map machinery lives in one package.

Features

• const RateLimitedError = error('RATE_LIMITED', { message, data }) — throw new RateLimitedError({ data }) works in handlers, middleware, or plain utilities and still reconciles into the typesafe error flow via ORPCError compatibility. The signature mirrors new ORPCError(code, options), and the options are optional: error('UNAUTHORIZED') is enough for a bare code.
• instanceof matches any ORPCError with the same code whose data passes the schema, even instances the class did not create, and narrows to ORPCError<Code, Data>. Async data schemas throw a descriptive TypeError instead of silently misbehaving.
• Factories satisfy ErrorMapItem, so [RateLimitedError.code]: RateLimitedError in .errors() renders them in generated OpenAPI documents.
• error, ORPCErrorFactory, and ORPCErrorFactoryOptions are re-exported from @orpc/server.

Testing

• Unit and type tests for the factory reach 100% statement/branch/function coverage, including instanceof edge cases and optional-data constructor signatures.
• OpenAPI generator unit test covers factory items registered under their code; a new e2e test asserts the defined flag survives the full handler → wire → client round trip on both hono-fetch and node-http transports.

Docs

• New "Error Factory" section (with instanceof subsection) in the error handling guide; ErrorMapItem and the factory APIs gained JSDoc with links back to it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview	Aug 1, 2026 8:55am

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@1760

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@1760

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@1760

@orpc/client

npm i https://pkg.pr.new/@orpc/client@1760

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@1760

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@1760

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@1760

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@1760

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@1760

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@1760

@orpc/next

npm i https://pkg.pr.new/@orpc/next@1760

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@1760

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@1760

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@1760

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@1760

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@1760

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@1760

@orpc/server

npm i https://pkg.pr.new/@orpc/server@1760

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@1760

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@1760

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@1760

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@1760

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@1760

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@1760

commit: 2d9ad52

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 25 untouched benchmarks

---

_{Comparing dinwwwh:feat/contract/orpc-error-class-factory (2d9ad52) with main (7480727)¹}

Footnotes

1. No successful run was found on main (28d6003) during the generation of this report, so 7480727 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[pullfrog]

ℹ️ Minor suggestions and observations. No blocking issues.

Reviewed changes — a new error() factory in @orpc/contract, relocation of createORPCErrorConstructorMap from @orpc/server to @orpc/contract, and associated import/export updates, tests, and docs.

• error() factory — creates classes extending ORPCError with bound code, default message, and optional data schema. instanceof matches by code + data validation, not constructor identity. Async data schemas throw TypeError.
• ErrorMapItem simplified — dropped the generic parameter; ORPCErrorFromErrorMap and ORPCErrorConstructorMap now access .data directly.
• createORPCErrorConstructorMap relocated — moved from @orpc/server to @orpc/contract; server re-exports. Works correctly with factory items registered under their code.
• OpenAPI + e2e coverage — factory items render correctly in generated specs; defined: true propagates through the full handler → wire → client round trip.

ℹ️ ErrorMapItem generic removal

ErrorMapItem lost its generic type parameter (ErrorMapItem<TDataSchema> → ErrorMapItem). This is a breaking change for any external code that referenced ErrorMapItem<SomeSchema>. All internal usages are updated within this PR and no external callers are visible in the impact analysis, so the blast radius is minimal. Worth noting for the changelog.

---

Note: 1 inline comment(s) dropped because they did not anchor to lines inside the PR diff:

• packages/contract/src/error-factory.ts:523 (RIGHT) — line 523 (RIGHT) is not inside a diff hunk

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — the error() factory signature was refactored to take code as a positional argument instead of inside the options object.

• error(code, options?) signature — error('RATE_LIMITED', { data: ... }) replaces error({ code: 'RATE_LIMITED', data: ... }). error('SIMPLE') works for bare-code factories with no data schema. ORPCErrorFactoryOptions dropped its code field and the <TCode> generic parameter.
• Updated all call sites — tests, docs, and OpenAPI unit test use the new signature. JSDoc updated with separate @param code and @param options tags.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}