@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.