jsonapi-err 0.0.1

package/.oxfmtrc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "ignorePatterns": [],
+  "semi": false,
+  "singleQuote": true,
+  "quoteProps": "consistent"
+}

package/.oxlintrc.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": null,
+  "categories": {},
+  "rules": {},
+  "settings": {
+    "jsx-a11y": {
+      "polymorphicPropName": null,
+      "components": {},
+      "attributes": {}
+    },
+    "next": {
+      "rootDir": []
+    },
+    "react": {
+      "formComponents": [],
+      "linkComponents": [],
+      "version": null,
+      "componentWrapperFunctions": []
+    },
+    "jsdoc": {
+      "ignorePrivate": false,
+      "ignoreInternal": false,
+      "ignoreReplacesDocs": true,
+      "overrideReplacesDocs": true,
+      "augmentsExtendsReplacesDocs": false,
+      "implementsReplacesDocs": false,
+      "exemptDestructuredRootsFromChecks": false,
+      "tagNamePreference": {}
+    },
+    "vitest": {
+      "typecheck": false
+    }
+  },
+  "env": {
+    "builtin": true
+  },
+  "globals": {},
+  "ignorePatterns": []
+}

package/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["oxc.oxc-vscode"]
+}

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "oxc.fmt.configPath": ".oxfmtrc.json",
+  "editor.defaultFormatter": "oxc.oxc-vscode",
+  "editor.formatOnSave": true
+}

package/AGENTS.md

@@ -0,0 +1,208 @@
+# AGENTS.md
+
+This file provides guidance for coding agents working in this repository.
+
+## Project Snapshot
+
+- Project name: `jsonapi-errors`
+- Runtime/tooling: Bun
+- Language: TypeScript (ESNext modules)
+- Primary domain: structured application/API error types for JSON:API style responses
+- Package type: ESM (`"type": "module"`)
+
+## Repository Layout
+
+- `index.ts` - current entry point
+- `src/core/` - core error abstractions and mappings
+  - `app-error.ts`
+  - `api-error.ts`
+  - `mapper.ts`
+- `src/http/` - HTTP-focused helpers
+  - `http-errors.ts`
+  - `type-guards.ts` (currently empty)
+- `src/types.ts` - shared types (currently empty)
+- Config:
+  - `package.json`
+  - `tsconfig.json`
+  - `.oxlintrc.json`
+  - `.oxfmtrc.json`
+  - `.vscode/settings.json`
+
+## Install / Setup
+
+- Install dependencies:
+  - `bun install`
+
+- Recommended editor behavior (already configured in VS Code):
+  - OXC formatter as default
+  - format on save enabled
+
+## Build / Lint / Test Commands
+
+This repo currently has formatter and linter scripts, but no explicit build/test scripts.
+
+### Formatting
+
+- Format all files:
+  - `bun run format`
+- Check formatting only:
+  - `bun run format:check`
+
+Formatting is controlled by `.oxfmtrc.json`:
+
+- no semicolons (`"semi": false`)
+- single quotes (`"singleQuote": true`)
+- consistent quoting for object keys (`"quoteProps": "consistent"`)
+
+### Linting
+
+- Run linter:
+  - `bun run lint`
+- Auto-fix lint issues:
+  - `bun run lint:fix`
+
+Lint config is intentionally minimal in `.oxlintrc.json` (few enforced custom rules).
+
+### Type Checking (No dedicated script yet)
+
+Because this is TypeScript with `noEmit: true`, use:
+
+- `bunx tsc --noEmit`
+
+If you add a script in `package.json`, prefer:
+
+- `"typecheck": "tsc --noEmit"`
+
+### Build
+
+- No dedicated build pipeline currently configured.
+- Treat this as source-first TypeScript library code unless a build tool is introduced.
+
+### Tests
+
+There are currently no test files in the repository. Bun test runner is available.
+
+- Run all tests:
+  - `bun test`
+- Run a single test file:
+  - `bun test path/to/file.test.ts`
+- Run tests matching file name pattern:
+  - `bun test error`
+  - (matches test files whose path/name includes `error`)
+- Run a single test by test name pattern:
+  - `bun test -t "returns jsonapi payload"`
+- Combine single file + single test case:
+  - `bun test src/core/api-error.test.ts -t "toJsonApi"`
+- Coverage:
+  - `bun test --coverage`
+
+Agent guidance:
+
+- Prefer targeted test runs first (`bun test <file>` or `-t`) before full suite.
+- If no tests exist for changed code, consider adding minimal focused tests.
+
+## TypeScript Configuration Expectations
+
+`tsconfig.json` highlights:
+
+- `strict: true` (required)
+- `noUncheckedIndexedAccess: true` (important safety signal)
+- `moduleResolution: "bundler"`
+- `allowImportingTsExtensions: true`
+- `verbatimModuleSyntax: true`
+- `noEmit: true`
+
+Implications:
+
+- Maintain strict typing; do not introduce `any` unless unavoidable and documented.
+- Preserve ESM import/export style.
+- Keep types explicit when inference harms readability or safety.
+
+## Code Style Guidelines
+
+### Imports and Exports
+
+- Prefer `import type` for type-only imports.
+- Keep imports minimal and local to module needs.
+- Use named exports over default exports.
+- Preserve existing relative import style.
+- Follow existing pattern of exporting at bottom when already used in file.
+
+### Formatting
+
+- Do not add semicolons.
+- Use single quotes.
+- Keep object/array literals readable with trailing commas where formatter applies.
+- Let `oxfmt` decide final spacing/wrapping.
+
+### Types
+
+- Prefer precise types and generics over `any`.
+- Use `unknown` for external/untrusted values, then narrow.
+- Use `readonly` properties for immutable class state where appropriate.
+- Keep public type contracts small and explicit (`type` aliases are common here).
+
+### Naming Conventions
+
+- Files: kebab-case (`api-error.ts`, `http-errors.ts`)
+- Classes/types/interfaces: PascalCase (`ApiError`, `AppError`, `Mapping`)
+- Variables/functions/methods: camelCase
+- Error factory objects may use PascalCase namespace-like constants (`HttpErrors`).
+- Error codes should be stable strings; avoid ad hoc changes once published.
+
+### Error Handling and Domain Patterns
+
+When implementing custom errors, follow existing patterns:
+
+- Extend `Error` for custom classes.
+- Call `Object.setPrototypeOf(this, new.target.prototype)` in constructor.
+- Preserve operational vs programmer error distinction (`isOperational` flag).
+- Keep machine-readable fields explicit:
+  - `status`, `title`, `detail`, `code`, optional `source`, `meta`, `id`
+- Prefer safe defaults:
+  - `isOperational: true`
+  - `expose: true` only when suitable for client-facing details
+- Preserve optional `cause` and headers metadata if applicable.
+- Ensure JSON:API serialization shape remains stable (`{ errors: [...] }`).
+
+### JSON:API Response Shape
+
+For API-facing errors, maintain compatibility with this structure:
+
+- Top level object with `errors` array
+- Each error object generally includes:
+  - `status` (string in payload)
+  - `title`
+  - `detail`
+  - `code`
+- Optional fields included conditionally:
+  - `id`, `source`, `meta`
+
+Do not add fields casually; treat shape changes as contract changes.
+
+## Agent Workflow Expectations
+
+- Before editing: read related modules fully.
+- After editing:
+  1. `bun run format`
+  2. `bun run lint`
+  3. `bunx tsc --noEmit`
+  4. `bun test` (or targeted test command)
+- Prefer small, focused changes over broad refactors.
+- Avoid introducing new dependencies unless justified.
+
+## Cursor / Copilot Rule Status
+
+Checked and not found at time of writing:
+
+- `.cursor/rules/` (not present)
+- `.cursorrules` (not present)
+- `.github/copilot-instructions.md` (not present)
+
+If these files are added later, update this document to incorporate them.
+
+## Notes for Future Contributors
+
+- `src/types.ts` and `src/http/type-guards.ts` are currently empty; align new additions with strict typing and existing naming.
+- If adding scripts (build/test/typecheck), update this AGENTS file immediately.
+- If introducing tests, prefer colocated or clearly named `*.test.ts` files and document single-test invocation examples.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Sala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# jsonapi-errors
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.2.9. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "jsonapi-err",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "build": "tsup",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
+    "tsup": "^8.5.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "lint-staged": {
+    "*": "oxfmt --no-error-on-unmatched-pattern"
+  }
+}

package/src/core/api-error.ts

@@ -0,0 +1,66 @@
+import type { JsonApiErrorDocument, JsonApiSource, Meta } from '../types'
+
+export type ApiErrorOptions<M = Meta, S extends JsonApiSource = JsonApiSource> = {
+  status: number
+  title: string
+  detail: string
+  code: string
+  source?: S
+  meta?: M
+  id?: string
+
+  headers?: Record<string, string>
+  expose?: boolean
+  isOperational?: boolean
+  cause?: unknown
+}
+
+export class ApiError<M = Meta, S extends JsonApiSource = JsonApiSource> extends Error {
+  readonly status: number
+  readonly title: string
+  readonly detail: string
+  readonly code: string
+  readonly source?: ApiErrorOptions<M, S>['source']
+  readonly meta?: M
+  readonly id?: string
+  readonly isOperational: boolean
+  readonly headers: Record<string, string>
+  readonly expose: boolean
+
+  constructor(options: ApiErrorOptions<M, S>) {
+    super(options.detail, { cause: options.cause })
+    Object.setPrototypeOf(this, new.target.prototype)
+
+    this.status = options.status
+    this.title = options.title
+    this.detail = options.detail
+    this.code = options.code
+    this.source = options.source
+    this.meta = options.meta
+    this.id = options.id
+    this.isOperational = options.isOperational ?? true
+    this.headers = options.headers ?? {}
+    this.expose = options.expose ?? options.status < 500
+  }
+
+  toJsonApi(opts?: { sanitize?: boolean }): JsonApiErrorDocument<M, S> {
+    const sanitize = opts?.sanitize ?? (!this.expose || this.status >= 500)
+    const title = sanitize ? 'Internal Server Error' : this.title
+    const detail = sanitize ? 'An unexpected error occurred on the server.' : this.detail
+    const code = sanitize ? 'INTERNAL_SERVER_ERROR' : this.code
+
+    return {
+      errors: [
+        {
+          status: String(this.status),
+          title,
+          detail,
+          code,
+          ...(this.id ? { id: this.id } : {}),
+          ...(!sanitize && this.source ? { source: this.source } : {}),
+          ...(!sanitize && this.meta ? { meta: this.meta } : {}),
+        },
+      ],
+    }
+  }
+}

package/src/core/app-error.ts

@@ -0,0 +1,14 @@
+import type { Meta } from '../types'
+
+export abstract class AppError<Code extends string = string, M = Meta> extends Error {
+  abstract readonly code: Code
+  readonly isOperational: boolean = true
+
+  readonly meta?: M
+
+  constructor(message: string, meta?: M) {
+    super(message)
+    Object.setPrototypeOf(this, new.target.prototype)
+    this.meta = meta
+  }
+}

package/src/core/format-jsonapi.ts

@@ -0,0 +1,15 @@
+import { ApiError } from './api-error'
+import type { JsonApiErrorDocument, JsonApiErrorObject, JsonApiSource, Meta } from '../types'
+
+export type { JsonApiErrorObject }
+
+export function formatJsonApiErrors<M = Meta, S extends JsonApiSource = JsonApiSource>(
+  input: ApiError<M, S> | ApiError<M, S>[],
+  opts?: { sanitize?: boolean },
+): JsonApiErrorDocument<M, S> {
+  const errors = Array.isArray(input) ? input : [input]
+
+  return {
+    errors: errors.flatMap((error) => error.toJsonApi(opts).errors),
+  }
+}

package/src/core/mapper.ts

@@ -0,0 +1,79 @@
+import { ApiError, type ApiErrorOptions } from './api-error'
+import { AppError } from './app-error'
+import type { JsonApiSource, Meta } from '../types'
+
+type AnyAppError = AppError<string, Meta>
+type MetaOf<E extends AnyAppError> = E extends AppError<string, infer M> ? M : Meta
+
+export type Mapping<E extends AnyAppError = AnyAppError> = {
+  status: number
+  title: string
+  expose?: boolean
+  build?: (err: E) => Partial<ApiErrorOptions<MetaOf<E>, JsonApiSource>>
+}
+
+export type ErrorMap<E extends AnyAppError = AnyAppError> = Partial<{
+  [Code in E['code']]: Mapping<Extract<E, { code: Code }>>
+}>
+
+export type ErrorAdapter = (err: unknown) => ApiError | undefined
+
+export const defineErrorMap = <E extends AnyAppError>(map: ErrorMap<E>): ErrorMap<E> => map
+
+export function createApiErrorMapper<E extends AnyAppError = AnyAppError>(
+  map: ErrorMap<E>,
+  opts?: {
+    defaultMapping?: Mapping<AnyAppError>
+    adapters?: readonly ErrorAdapter[]
+    unknownHandler?: (err: unknown) => ApiError
+  },
+) {
+  const defaultMapping: Mapping<AnyAppError> = opts?.defaultMapping ?? {
+    status: 400,
+    title: 'Application error',
+  }
+
+  return function toApiError(err: unknown): ApiError {
+    if (err instanceof ApiError) return err
+
+    if (err instanceof AppError) {
+      const appError = err as AnyAppError
+      const mapping =
+        (map[appError.code as E['code']] as Mapping<AnyAppError> | undefined) ?? defaultMapping
+      const extra = mapping.build?.(appError)
+
+      return new ApiError({
+        status: mapping.status,
+        title: mapping.title,
+        detail: appError.message,
+        code: appError.code,
+        meta: extra?.meta ?? appError.meta,
+        source: extra?.source,
+        headers: extra?.headers,
+        id: extra?.id,
+        expose: extra?.expose ?? mapping.expose,
+        isOperational: appError.isOperational,
+        cause: extra?.cause,
+      })
+    }
+
+    if (opts?.adapters) {
+      for (const adapter of opts.adapters) {
+        const adapted = adapter(err)
+        if (adapted) return adapted
+      }
+    }
+
+    if (opts?.unknownHandler) return opts.unknownHandler(err)
+
+    return new ApiError({
+      status: 500,
+      title: 'Internal Server Error',
+      detail: 'An unexpected error occurred on the server.',
+      code: 'INTERNAL_SERVER_ERROR',
+      expose: false,
+      isOperational: false,
+      cause: err,
+    })
+  }
+}

package/src/http/http-errors.ts

@@ -0,0 +1,111 @@
+import { ApiError, type ApiErrorOptions } from '../core/api-error'
+
+type HttpErrorSpec = readonly [status: number, title: string, defaultCode: string]
+
+const HTTP_ERROR_SPECS = {
+  badRequest: [400, 'Bad Request', 'BAD_REQUEST'],
+  unauthorized: [401, 'Unauthorized', 'UNAUTHORIZED'],
+  paymentRequired: [402, 'Payment Required', 'PAYMENT_REQUIRED'],
+  forbidden: [403, 'Forbidden', 'FORBIDDEN'],
+  notFound: [404, 'Not Found', 'NOT_FOUND'],
+  methodNotAllowed: [405, 'Method Not Allowed', 'METHOD_NOT_ALLOWED'],
+  notAcceptable: [406, 'Not Acceptable', 'NOT_ACCEPTABLE'],
+  proxyAuthenticationRequired: [
+    407,
+    'Proxy Authentication Required',
+    'PROXY_AUTHENTICATION_REQUIRED',
+  ],
+  requestTimeout: [408, 'Request Timeout', 'REQUEST_TIMEOUT'],
+  conflict: [409, 'Conflict', 'CONFLICT'],
+  gone: [410, 'Gone', 'GONE'],
+  lengthRequired: [411, 'Length Required', 'LENGTH_REQUIRED'],
+  preconditionFailed: [412, 'Precondition Failed', 'PRECONDITION_FAILED'],
+  payloadTooLarge: [413, 'Payload Too Large', 'PAYLOAD_TOO_LARGE'],
+  uriTooLong: [414, 'URI Too Long', 'URI_TOO_LONG'],
+  unsupportedMediaType: [415, 'Unsupported Media Type', 'UNSUPPORTED_MEDIA_TYPE'],
+  rangeNotSatisfiable: [416, 'Range Not Satisfiable', 'RANGE_NOT_SATISFIABLE'],
+  expectationFailed: [417, 'Expectation Failed', 'EXPECTATION_FAILED'],
+  imATeapot: [418, "I'm a teapot", 'IM_A_TEAPOT'],
+  misdirectedRequest: [421, 'Misdirected Request', 'MISDIRECTED_REQUEST'],
+  unprocessableEntity: [422, 'Unprocessable Entity', 'UNPROCESSABLE_ENTITY'],
+  locked: [423, 'Locked', 'LOCKED'],
+  failedDependency: [424, 'Failed Dependency', 'FAILED_DEPENDENCY'],
+  tooEarly: [425, 'Too Early', 'TOO_EARLY'],
+  upgradeRequired: [426, 'Upgrade Required', 'UPGRADE_REQUIRED'],
+  preconditionRequired: [428, 'Precondition Required', 'PRECONDITION_REQUIRED'],
+  tooManyRequests: [429, 'Too Many Requests', 'TOO_MANY_REQUESTS'],
+  requestHeaderFieldsTooLarge: [
+    431,
+    'Request Header Fields Too Large',
+    'REQUEST_HEADER_FIELDS_TOO_LARGE',
+  ],
+  unavailableForLegalReasons: [
+    451,
+    'Unavailable For Legal Reasons',
+    'UNAVAILABLE_FOR_LEGAL_REASONS',
+  ],
+  internalServerError: [500, 'Internal Server Error', 'INTERNAL_SERVER_ERROR'],
+  notImplemented: [501, 'Not Implemented', 'NOT_IMPLEMENTED'],
+  badGateway: [502, 'Bad Gateway', 'BAD_GATEWAY'],
+  serviceUnavailable: [503, 'Service Unavailable', 'SERVICE_UNAVAILABLE'],
+  gatewayTimeout: [504, 'Gateway Timeout', 'GATEWAY_TIMEOUT'],
+  httpVersionNotSupported: [505, 'HTTP Version Not Supported', 'HTTP_VERSION_NOT_SUPPORTED'],
+  variantAlsoNegotiates: [506, 'Variant Also Negotiates', 'VARIANT_ALSO_NEGOTIATES'],
+  insufficientStorage: [507, 'Insufficient Storage', 'INSUFFICIENT_STORAGE'],
+  loopDetected: [508, 'Loop Detected', 'LOOP_DETECTED'],
+  notExtended: [510, 'Not Extended', 'NOT_EXTENDED'],
+  networkAuthenticationRequired: [
+    511,
+    'Network Authentication Required',
+    'NETWORK_AUTHENTICATION_REQUIRED',
+  ],
+} as const satisfies Record<string, HttpErrorSpec>
+
+export type HttpErrorName = keyof typeof HTTP_ERROR_SPECS
+export type HttpErrorOptions = Partial<Omit<ApiErrorOptions, 'status' | 'title'>>
+
+export type HttpErrorFactories = {
+  [Name in HttpErrorName]: (options?: HttpErrorOptions) => ApiError
+}
+
+export const createHttpError = (
+  status: number,
+  title: string,
+  defaultCode: string,
+  options: HttpErrorOptions = {},
+): ApiError => {
+  return new ApiError({
+    status,
+    title,
+    detail: options.detail ?? title,
+    code: options.code ?? defaultCode,
+    source: options.source,
+    meta: options.meta,
+    id: options.id,
+    headers: options.headers,
+    expose: options.expose,
+    isOperational: options.isOperational,
+    cause: options.cause,
+  })
+}
+
+export const createHttpErrorByName = (
+  name: HttpErrorName,
+  options?: HttpErrorOptions,
+): ApiError => {
+  const [status, title, defaultCode] = HTTP_ERROR_SPECS[name]
+  return createHttpError(status, title, defaultCode, options)
+}
+
+const factories = Object.entries(HTTP_ERROR_SPECS).map(([name, [status, title, defaultCode]]) => {
+  return [
+    name,
+    (options?: HttpErrorOptions) => createHttpError(status, title, defaultCode, options),
+  ] as const
+})
+
+export const HttpErrors = Object.fromEntries(factories) as HttpErrorFactories
+
+export const NotFound = (options?: HttpErrorOptions): ApiError => HttpErrors.notFound(options)
+export const InternalServerError = (options?: HttpErrorOptions): ApiError =>
+  HttpErrors.internalServerError(options)

package/src/http/type-guards.ts

@@ -0,0 +1,45 @@
+import { ApiError } from '../core/api-error'
+import { AppError } from '../core/app-error'
+import type { JsonApiErrorDocument, JsonApiErrorObject } from '../types'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+const isOptionalString = (value: unknown): value is string | undefined =>
+  value === undefined || typeof value === 'string'
+
+const isOptionalRecord = (value: unknown): value is Record<string, unknown> | undefined =>
+  value === undefined || isRecord(value)
+
+export const isApiError = (e: unknown): e is ApiError => e instanceof ApiError
+export const isAppError = (e: unknown): e is AppError => e instanceof AppError
+
+export const isOperationalError = (e: unknown): e is { isOperational: boolean } =>
+  isRecord(e) && 'isOperational' in e && typeof e.isOperational === 'boolean'
+
+export const isErrorLike = (e: unknown): e is { name: string; message: string; stack?: string } =>
+  isRecord(e) &&
+  typeof e.name === 'string' &&
+  typeof e.message === 'string' &&
+  isOptionalString(e.stack)
+
+export const isJsonApiErrorObject = (input: unknown): input is JsonApiErrorObject => {
+  if (!isRecord(input)) return false
+
+  return (
+    isOptionalString(input.id) &&
+    isOptionalString(input.status) &&
+    isOptionalString(input.code) &&
+    isOptionalString(input.title) &&
+    isOptionalString(input.detail) &&
+    isOptionalRecord(input.source) &&
+    isOptionalRecord(input.meta) &&
+    isOptionalRecord(input.links)
+  )
+}
+
+export const isJsonApiErrorDocument = (input: unknown): input is JsonApiErrorDocument => {
+  if (!isRecord(input) || !Array.isArray(input.errors)) return false
+
+  return input.errors.every(isJsonApiErrorObject)
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './core/app-error'
+export * from './core/api-error'
+export * from './core/format-jsonapi'
+export * from './core/mapper'
+
+export * from './http/http-errors'
+export * from './http/type-guards'
+
+export type * from './types'

package/src/types.ts

@@ -0,0 +1,27 @@
+export type Meta = Record<string, unknown>
+
+export type JsonApiSource = {
+  pointer?: string
+  parameter?: string
+  header?: string
+} & Record<string, unknown>
+
+export type JsonApiLinks = {
+  about?: string
+  type?: string
+}
+
+export type JsonApiErrorObject<M = Meta, S extends JsonApiSource = JsonApiSource> = {
+  id?: string
+  links?: JsonApiLinks
+  status?: string
+  code?: string
+  title?: string
+  detail?: string
+  source?: S
+  meta?: M
+}
+
+export type JsonApiErrorDocument<M = Meta, S extends JsonApiSource = JsonApiSource> = {
+  errors: JsonApiErrorObject<M, S>[]
+}

package/tests/api-error.test.ts

@@ -0,0 +1,117 @@
+import { expect, test, describe } from 'bun:test'
+import { ApiError } from '../src/core/api-error'
+
+describe('ApiError', () => {
+  test('should create an ApiError with basic options', () => {
+    const error = new ApiError({
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Invalid input',
+      code: 'BAD_REQUEST',
+    })
+
+    expect(error.status).toBe(400)
+    expect(error.title).toBe('Bad Request')
+    expect(error.detail).toBe('Invalid input')
+    expect(error.code).toBe('BAD_REQUEST')
+    expect(error.isOperational).toBe(true)
+    expect(error.expose).toBe(true)
+  })
+
+  test('should expose: false for 500 errors by default', () => {
+    const error = new ApiError({
+      status: 500,
+      title: 'Internal Error',
+      detail: 'Something went wrong',
+      code: 'INTERNAL_ERROR',
+    })
+
+    expect(error.expose).toBe(false)
+  })
+
+  test('should allow overriding expose and isOperational', () => {
+    const error = new ApiError({
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Invalid input',
+      code: 'BAD_REQUEST',
+      expose: false,
+      isOperational: false,
+    })
+
+    expect(error.expose).toBe(false)
+    expect(error.isOperational).toBe(false)
+  })
+
+  test('should store meta and source', () => {
+    const meta = { userId: 123 }
+    const source = { pointer: '/data/attributes/name' }
+    const error = new ApiError({
+      status: 422,
+      title: 'Validation Error',
+      detail: 'Invalid name',
+      code: 'VALIDATION_ERROR',
+      meta,
+      source,
+    })
+
+    expect(error.meta).toEqual(meta)
+    expect(error.source).toEqual(source)
+  })
+
+  test('toJsonApi should return JSON:API compliant structure', () => {
+    const error = new ApiError({
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Invalid input',
+      code: 'BAD_REQUEST',
+      id: 'error-id',
+      meta: { foo: 'bar' },
+      source: { parameter: 'query' },
+    })
+
+    const json = error.toJsonApi()
+
+    expect(json).toEqual({
+      errors: [
+        {
+          status: '400',
+          title: 'Bad Request',
+          detail: 'Invalid input',
+          code: 'BAD_REQUEST',
+          id: 'error-id',
+          meta: { foo: 'bar' },
+          source: { parameter: 'query' },
+        },
+      ],
+    })
+  })
+
+  test('toJsonApi should sanitize internal errors when status >= 500', () => {
+    const error = new ApiError({
+      status: 500,
+      title: 'Database Crash',
+      detail: 'SQL logic error at line 42',
+      code: 'DB_CRASH',
+    })
+
+    const json = error.toJsonApi()
+
+    expect(json.errors[0]!.title).toBe('Internal Server Error')
+    expect(json.errors[0]!.detail).toBe('An unexpected error occurred on the server.')
+    expect(json.errors[0]!.code).toBe('INTERNAL_SERVER_ERROR')
+  })
+
+  test('toJsonApi should allow forcing sanitize', () => {
+    const error = new ApiError({
+      status: 400,
+      title: 'Visible Error',
+      detail: 'Detailed message',
+      code: 'VISIBLE',
+    })
+
+    const json = error.toJsonApi({ sanitize: true })
+
+    expect(json.errors[0]!.title).toBe('Internal Server Error')
+  })
+})

package/tests/app-error.test.ts

@@ -0,0 +1,31 @@
+import { expect, test, describe } from 'bun:test'
+import { AppError } from '../src/core/app-error'
+
+describe('AppError', () => {
+  class TestError extends AppError<'TEST_CODE', { foo: string }> {
+    readonly code = 'TEST_CODE'
+  }
+
+  test('should create and store code and meta with full type inference', () => {
+    const meta = { foo: 'bar' }
+    const error = new TestError('message', meta)
+
+    expect(error.message).toBe('message')
+    expect(error.code).toBe('TEST_CODE')
+    expect(error.meta).toBe(meta)
+    expect(error.meta?.foo).toBe('bar') // Verify autocomplete-like access
+    expect(error.isOperational).toBe(true)
+  })
+
+  test('should work with interfaces for meta', () => {
+    interface MyMeta {
+      count: number
+    }
+    class InterfaceError extends AppError<'INT_CODE', MyMeta> {
+      readonly code = 'INT_CODE'
+    }
+
+    const error = new InterfaceError('msg', { count: 42 })
+    expect(error.meta?.count).toBe(42)
+  })
+})

package/tests/format-jsonapi.test.ts

@@ -0,0 +1,37 @@
+import { expect, test, describe } from 'bun:test'
+import { ApiError } from '../src/core/api-error'
+import { formatJsonApiErrors } from '../src/core/format-jsonapi'
+
+describe('formatJsonApiErrors', () => {
+  const err1 = new ApiError({
+    status: 400,
+    title: 'Error 1',
+    detail: 'Detail 1',
+    code: 'CODE1',
+  })
+
+  const err2 = new ApiError({
+    status: 404,
+    title: 'Error 2',
+    detail: 'Detail 2',
+    code: 'CODE2',
+  })
+
+  test('should format a single error', () => {
+    const result = formatJsonApiErrors(err1)
+    expect(result.errors).toHaveLength(1)
+    expect(result.errors[0]!.status).toBe('400')
+  })
+
+  test('should format an array of errors', () => {
+    const result = formatJsonApiErrors([err1, err2])
+    expect(result.errors).toHaveLength(2)
+    expect(result.errors[0]!.code).toBe('CODE1')
+    expect(result.errors[1]!.code).toBe('CODE2')
+  })
+
+  test('should sanitize errors globally', () => {
+    const result = formatJsonApiErrors(err1, { sanitize: true })
+    expect(result.errors[0]!.title).toBe('Internal Server Error')
+  })
+})

package/tests/http-errors.test.ts

@@ -0,0 +1,36 @@
+import { expect, test, describe } from 'bun:test'
+import { HttpErrors, NotFound, InternalServerError } from '../src/http/http-errors'
+import { ApiError } from '../src/core/api-error'
+
+describe('HttpErrors', () => {
+  test('NotFound should create a 404 error', () => {
+    const err = NotFound({ detail: 'Where?' })
+    expect(err instanceof ApiError).toBe(true)
+    expect(err.status).toBe(404)
+    expect(err.title).toBe('Not Found')
+    expect(err.detail).toBe('Where?')
+    expect(err.code).toBe('NOT_FOUND')
+  })
+
+  test('InternalServerError should create a 500 error and not expose it', () => {
+    const err = InternalServerError()
+    expect(err.status).toBe(500)
+    expect(err.expose).toBe(false)
+  })
+
+  test('should allow custom code and meta in HTTP errors', () => {
+    const err = HttpErrors.badRequest({
+      code: 'CUSTOM_BAD_REQUEST',
+      meta: { foo: 'bar' },
+    })
+    expect(err.code).toBe('CUSTOM_BAD_REQUEST')
+    expect(err.meta).toEqual({ foo: 'bar' })
+  })
+
+  test('factory should have multiple status codes', () => {
+    expect(HttpErrors.forbidden().status).toBe(403)
+    expect(HttpErrors.unauthorized().status).toBe(401)
+    expect(HttpErrors.conflict().status).toBe(409)
+    expect(HttpErrors.unprocessableEntity().status).toBe(422)
+  })
+})

package/tests/mapper.test.ts

@@ -0,0 +1,83 @@
+import { expect, test, describe } from 'bun:test'
+import { AppError } from '../src/core/app-error'
+import { createApiErrorMapper } from '../src/core/mapper'
+import { ApiError } from '../src/core/api-error'
+
+describe('createApiErrorMapper', () => {
+  class UserNotFound extends AppError<'USER_NOT_FOUND'> {
+    readonly code = 'USER_NOT_FOUND'
+  }
+
+  const mapper = createApiErrorMapper({
+    USER_NOT_FOUND: {
+      status: 404,
+      title: 'User not found',
+    },
+  })
+
+  test('should map an AppError to an ApiError based on code', () => {
+    const appError = new UserNotFound('The user does not exist')
+    const apiError = mapper(appError)
+
+    expect(apiError instanceof ApiError).toBe(true)
+    expect(apiError.status).toBe(404)
+    expect(apiError.title).toBe('User not found')
+    expect(apiError.detail).toBe('The user does not exist')
+    expect(apiError.code).toBe('USER_NOT_FOUND')
+  })
+
+  test('should use default mapping for unknown AppErrors', () => {
+    class UnknownError extends AppError<'UNKNOWN'> {
+      readonly code = 'UNKNOWN'
+    }
+    const error = mapper(new UnknownError('msg'))
+    expect(error.status).toBe(400)
+    expect(error.title).toBe('Application error')
+  })
+
+  test('should handle completely unknown errors with 500', () => {
+    const error = mapper(new Error('Boom'))
+    expect(error.status).toBe(500)
+    expect(error.code).toBe('INTERNAL_SERVER_ERROR')
+    expect(error.expose).toBe(false)
+  })
+
+  test('should use custom unknownHandler if provided', () => {
+    const customMapper = createApiErrorMapper(
+      {},
+      {
+        unknownHandler: (err) =>
+          new ApiError({
+            status: 418,
+            title: 'Teapot',
+            detail: 'Indeed',
+            code: 'TEAPOT',
+          }),
+      },
+    )
+
+    const error = customMapper(new Error('Whoops'))
+    expect(error.status).toBe(418)
+  })
+
+  test('should use mapping.build for complex errors', () => {
+    class ValidationError extends AppError<'VAL_ERR', { field: string }> {
+      readonly code = 'VAL_ERR'
+    }
+
+    const complexMapper = createApiErrorMapper({
+      VAL_ERR: {
+        status: 422,
+        title: 'Validation Failed',
+        build: (err: ValidationError) => ({
+          source: { pointer: `/data/attributes/${err.meta?.field}` },
+        }),
+      },
+    })
+
+    const err = new ValidationError('Bad email', { field: 'email' })
+    const apiErr = complexMapper(err)
+
+    expect(apiErr.source?.pointer).toBe('/data/attributes/email')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  outDir: 'dist',
+  outExtension({ format }) {
+    return {
+      js: format === 'esm' ? '.mjs' : '.cjs',
+    }
+  },
+})