@geenius/errors

Framework-agnostic structured error handling for the Geenius ecosystem.

@geenius/errors publishes a single public entrypoint: the package root. It does not publish /shared, /react, /react-css, /solidjs, or other UI subpaths. UI error boundaries and visual error displays belong in downstream UI packages.

Install

pnpm add @geenius/errors

Usage

import {
  ErrorCode,
  GeeniusError,
  RateLimitError,
  catchError,
  formatError,
  isErrorCode,
  isGeeniusError,
  makeSafe,
  serializeError,
} from '@geenius/errors'

const error = new RateLimitError({
  message: 'Too many requests',
  context: { bucket: 'api' },
})

const payload = serializeError(error)

isGeeniusError(payload) // true
isErrorCode(payload, ErrorCode.RATE_LIMIT) // true
formatError(error).statusCode // 429

Go-style tuple helpers are available for async and sync code:

const [user, loadError] = await catchError(loadUser(userId), (cause) =>
  new GeeniusError({
    code: ErrorCode.INTERNAL_ERROR,
    message: 'Unable to load user',
    cause,
  }),
)

const safeParse = makeSafe(JSON.parse)
const [value, parseError] = safeParse(input)

API Reference

Error classes:

• GeeniusError
• ValidationError
• AuthError
• UnauthorizedError
• NotFoundError
• ConflictError
• RateLimitError
• InternalServerError

Core helpers:

• ErrorCode
• getStatusCodeForErrorCode
• getErrorCodesForStatusCode
• formatError
• serializeError
• deserializeError
• isGeeniusError
• isErrorCode
• catchError
• makeSafe

Framework-free display helpers:

• ERROR_DISPLAY_TONES
• ERROR_DISPLAY_DENSITIES
• normalizeErrorSummary
• formatValidationIssues
• createErrorReportEnvelope
• shouldExposeErrorDetails
• isErrorDisplayTone
• isErrorDisplayDensity

Public types:

• GeeniusErrorOptions
• GeeniusErrorKind
• SerializedGeeniusError
• GeeniusErrorLike
• KnownGeeniusError
• ErrorTuple
• ErrorHandler
• FormatErrorOptions
• FormattedError
• ErrorDisplayTone
• ErrorDisplayDensity
• ValidationIssue
• NormalizedErrorSummary
• ErrorReportEnvelope
• ErrorReportOptions

Public Surface

Only this import is supported:

import { GeeniusError } from '@geenius/errors'

Historical UI scaffold packages remain private and out of scope for this V1 surface. Do not import private package subpaths; the root export map rejects them.

Testing

pnpm build
pnpm type-check
pnpm lint
pnpm test
pnpm test:exports
pnpm test:dist-contract
pnpm test:packed-smoke
pnpm audit:supply-chain
pnpm test:license

License

FSL-1.1-Apache-2.0. See LICENSE.