Errors

Error handling utilities with structured error hierarchy and error chaining.

import { Errors } from '@sceneinfrastructure/sdk'

Based on ox error patterns.

Types

GlobalErrorType

Catch-all error type for function error type unions.

import { Errors } from '@sceneinfrastructure/sdk'
 
// Define a custom error type for your function
type SpecificError = Error & { code: 'SPECIFIC_ERROR' }
 
export declare namespace myFunction {
  type ErrorType = SpecificError | Errors.GlobalErrorType
}

Classes

BaseError

Base error class for all Gatekeeper SDK errors. Provides structured error handling with:

Short message for quick identification
Detailed information for debugging
Error chaining via cause property

import { Errors } from '@sceneinfrastructure/sdk'
 
throw new Errors.BaseError('Something went wrong.', {
  details: 'The operation failed due to invalid input.',
})

Constructor

new Errors.BaseError(shortMessage: string, options?: BaseError.Options)

Parameter	Type	Description
`shortMessage`	`string`	Primary error message
`options.cause`	`Error`	Underlying error that caused this error
`options.details`	`string`	Extended debugging information

Properties

Property	Type	Description
`name`	`string`	Error name (`'BaseError'` by default)
`shortMessage`	`string`	The primary error message
`details`	`string`	Extended error information
`cause`	`Error \| undefined`	The underlying error

Methods

walk

Traverses the error chain, calling the provided function for each error.

import { Errors } from '@sceneinfrastructure/sdk'
 
const error = new Errors.BaseError('Outer error', {
  cause: new Errors.BaseError('Inner error', {
    cause: new TypeError('Root cause'),
  }),
})
 
// Find a specific error type in the chain
const typeError = error.walk((err) => err instanceof TypeError)

Usage Patterns

Creating Custom Errors

import { Errors } from '@sceneinfrastructure/sdk'
 
class InvalidSaleKeyError extends Errors.BaseError {
  override name = 'InvalidSaleKeyError'
 
  constructor(options: Errors.BaseError.Options = {}) {
    super('Invalid sale key configuration.', options)
  }
}

Error Chaining

Wrap lower-level errors with context:

import { Errors } from '@sceneinfrastructure/sdk'
 
async function sendTransaction(): Promise<void> {
  // Example function that might fail
  throw new Error('Network error')
}
 
async function processTransaction() {
  try {
    await sendTransaction()
  } catch (error) {
    throw new Errors.BaseError('Failed to process transaction.', {
      cause: error as Error,
      details: 'Transaction was rejected by the network.',
    })
  }
}

Error Inspection

Walk the error chain to find root causes:

import { Errors } from '@sceneinfrastructure/sdk'
 
function getRootCause(error: Error): Error {
  if (error instanceof Errors.BaseError) {
    return error.walk() ?? error
  }
  return error
}
 
function hasSpecificCause(error: Error, predicate: (e: Error) => boolean): boolean {
  if (error instanceof Errors.BaseError) {
    return error.walk(predicate) !== undefined
  }
  return predicate(error)
}