## 4.2.1 (2026-07-17) ### Documentation - **http-common:** fix stale typescript-common version, add missing tslib row ([01b5109](https://github.com/PhillipAWells/workspace/commit/01b5109)) ### 🧱 Updated Dependencies - Updated @pawells/typescript-common to 3.1.1 ## 4.2.0 (2026-07-17) ### Features - add package sources for @pawells monorepo consolidation ([d5290a9](https://github.com/PhillipAWells/workspace/commit/d5290a9)) ### Bug Fixes - **http-common:** add JSDoc and improve type safety ([2819d7a](https://github.com/PhillipAWells/workspace/commit/2819d7a)) - correct TypeScript project references for consolidated workspace ([5e46113](https://github.com/PhillipAWells/workspace/commit/5e46113)) ### Documentation - **http-common:** enhance CLAUDE.md, README and package.json ([0a88655](https://github.com/PhillipAWells/workspace/commit/0a88655)) - **workspace:** add per-package CLAUDE.md files ([8a32184](https://github.com/PhillipAWells/workspace/commit/8a32184)) ### 🧱 Updated Dependencies - Updated @pawells/typescript-common to 3.1.0 # Changelog All notable changes to this package will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ## [4.1.0] - 2026-07-14 ### Changed - **BREAKING:** `GetHTTPErrorClass` now returns `undefined` instead of `null` for unmapped status codes — aligns with org convention of preferring `undefined` for absent values in APIs - **BREAKING:** `HTTPError` base class constructor now accepts `Partial` instead of `THTTPErrorMetadata` (required parameter) — enables consistent validation via `BuildMetadata` and removes unsafe type casts - HTTP status code validation range remains 100–599 per RFC 7231; out-of-range codes now consistently throw `HTTPMetadataValidationError` from the constructor's metadata validation instead of constructing successfully - `ThrowHTTPError` JSDoc now explicitly documents that it throws `HTTPMetadataValidationError` for out-of-range status codes, clarifying the contract ### Fixed - `HTTP_ERROR_CLASS_MAP` JSDoc now accurately describes the `Object.freeze()` implementation and confirms mutation attempts throw in strict mode - `AssertHTTPErrorMetadata` JSDoc now includes `@returns` tag describing the assertion function behavior - `HTTPError.HTTPStatusCode` getter documentation expanded with additional context and examples - README.md description section trimmed to conform to org standard (1–2 sentences) - `ToProblemDetails` JSDoc no longer carries a malformed `@throws` tag (the function never throws) ### Added - `ThrowHTTPError(statusCode: number, message: string, metadata?: Partial): never` — convenience wrapper that looks up the appropriate `HTTPError` subclass via `GetHTTPErrorClass`, instantiates and throws it with the provided message and metadata; for unmapped status codes throws a generic `HTTPError`; eliminates boilerplate of manual error class lookup and instantiation - `IsHTTPError(value: unknown): value is HTTPError` — type guard using `instanceof` to check if a value is an HTTPError instance - `IsClientError(value: unknown): value is HTTPError` — type guard that returns true for HTTPError with a 4xx (400–499) status code, enabling ergonomic client-error branching - `IsServerError(value: unknown): value is HTTPError` — type guard that returns true for HTTPError with a 5xx (500–599) status code, enabling ergonomic server-error branching - `ToProblemDetails(error: HTTPError)` — RFC 7807 Problem Details serializer that converts HTTPError instances to the standard `{type, title, status, detail, instance}` shape with org-standard extensions for `code` and safe `cause` representation (message only, no stack traces) - `TProblemDetails` interface — TypeScript interface for RFC 7807 Problem Details objects with org-standard extensions - `HTTPNotAcceptableError` (406), `HTTPPayloadTooLargeError` (413), `HTTPUnavailableForLegalReasonsError` (451) — new concrete error subclasses for commonly used HTTP status codes - Status code constants for 11 previously unmapped HTTP status codes: `HTTP_STATUS_NOT_ACCEPTABLE` (406), `HTTP_STATUS_LENGTH_REQUIRED` (411), `HTTP_STATUS_PRECONDITION_FAILED` (412), `HTTP_STATUS_PAYLOAD_TOO_LARGE` (413), `HTTP_STATUS_URI_TOO_LONG` (414), `HTTP_STATUS_UNAVAILABLE_FOR_LEGAL_REASONS` (451), `HTTP_STATUS_VARIANT_ALSO_NEGOTIATES` (506), `HTTP_STATUS_INSUFFICIENT_STORAGE` (507), `HTTP_STATUS_LOOP_DETECTED` (508), `HTTP_STATUS_NOT_EXTENDED` (510), `HTTP_STATUS_NETWORK_AUTHENTICATION_REQUIRED` (511) - `HTTPTooManyRequestsError` and `HTTPServiceUnavailableError` now accept optional `retryAfter?: number | Date` parameter (per RFC 7231 section 7.1.3) — exposed via typed `RetryAfter` getter for ergonomic retry-logic implementation; supports both delay-seconds (numeric) and HTTP-date (Date) forms without coercion ## [4.0.4] - 2026-07-11 ### Fixed - Documentation corrections: the README's documented `HTTPError` constructor signature incorrectly showed `metadata` as optional; it corrected `AssertHTTPErrorMetadata`'s documented throw type from `ZodError` to `HTTPMetadataValidationError`. ## [4.0.3] ### Added - `HTTPError` base class extending `BaseError` from `@pawells/typescript-common` with `HTTPStatusCode` getter for HTTP-aware error handling - `HTTPBadRequestError`, `HTTPUnauthorizedError`, `HTTPForbiddenError`, `HTTPNotFoundError`, `HTTPMethodNotAllowedError`, `HTTPRequestTimeoutError`, `HTTPConflictError`, `HTTPGoneError`, `HTTPUnsupportedMediaTypeError`, `HTTPUnprocessableEntityError`, `HTTPTooManyRequestsError`, `HTTPInternalServerError`, `HTTPNotImplementedError`, `HTTPBadGatewayError`, `HTTPServiceUnavailableError`, `HTTPGatewayTimeoutError` — concrete error subclasses for standard HTTP status codes (400–504) with automatic status code assignment - `HTTPMetadataValidationError` — domain-specific error class wrapping Zod validation failures during HTTP error metadata validation - `THTTPErrorMetadata` type — typed metadata with required `code: string`, optional `HTTPStatusCode: number`, and optional `cause: Error` - `THTTPErrorClasses` type — union of all 16 concrete error class constructors for type-safe dynamic error instantiation - `HTTP_ERROR_METADATA_SCHEMA` Zod schema for validating HTTP error metadata at construction time - `HTTP_ERROR_CLASS_MAP` — read-only map of HTTP status codes to error class constructors for dynamic error lookup - `GetHTTPErrorClass(statusCode: number)` — factory function to retrieve error class constructor by HTTP status code - `AssertHTTPErrorMetadata(metadata: unknown)` — type guard and assertion function that throws `HTTPMetadataValidationError` on invalid metadata - `ValidateHTTPErrorMetadata(metadata: unknown)` — validation function returning `true`/`false` without throwing - 31 named HTTP status code constants spanning 100–504 (`HTTP_STATUS_CONTINUE`, `HTTP_STATUS_OK`, `HTTP_STATUS_CREATED`, etc.) ### Details - All error subclass constructors accept an optional `metadata?: Partial` parameter, providing sensible defaults (status code and code string) - Metadata validation occurs at construction time via Zod schema — invalid metadata throws `HTTPMetadataValidationError` immediately - Cause-chain support: errors preserve and propagate the original error via `Cause` property - Standalone package with no NestJS peer dependencies — works in any Node.js environment [Unreleased]: https://github.com/PhillipAWells/workspace/compare/http-common@4.1.0...HEAD [4.1.0]: https://github.com/PhillipAWells/workspace/compare/http-common@4.0.4...http-common@4.1.0 [4.0.4]: https://github.com/PhillipAWells/workspace/compare/http-common@4.0.3...http-common@4.0.4 [4.0.3]: https://github.com/PhillipAWells/workspace/releases/tag/http-common@4.0.3