Essentials

Error handling

A handler should state the happy path and throw when the world disagrees. Turning those throws into the right response is the boundary's job, not something you scatter through your logic as try/catch. Errors carry their own meaning; the framework maps it.

#Throw, do not branch

The principle

Error handling tangled into business logic obscures both. Let the domain throw a meaningful error and stop; let a single place decide how each kind of error becomes a response. The happy path stays legible.

In Stone.js

The framework ships error types that carry a status (RuntimeError, IntegrationError, and the like). Throw one and the kernel maps it to the response. Register an @ErrorHandler to customise how a specific error type is rendered.

app/Tasks.tsts

import { RuntimeError } from '@stone-js/core'

show (event: IncomingHttpEvent) {
  const task = this.tasks.find(event.get('id'))
  if (task === undefined) throw new RuntimeError('Task not found')  // -> mapped to a 4xx
  return task
}

#Custom error handlers

Map a specific error type to a specific response by registering a handler. It receives the error and the event and returns whatever the response should be.

app/errors.tsdeclarativeimperative

import { ErrorHandler } from '@stone-js/core'

@ErrorHandler({ error: 'TaskNotFoundError' })
export class TaskNotFoundHandler {
  handle (error: TaskNotFoundError, event: IncomingHttpEvent) {
    return jsonHttpResponse({ error: 'not_found', id: error.id }, 404)
  }
}
import { defineErrorHandler } from '@stone-js/core'

const TaskNotFoundHandler = () => (error, event) =>
  jsonHttpResponse({ error: 'not_found', id: error.id }, 404)

export const errorHandlers = [
  defineErrorHandler(TaskNotFoundHandler, { error: 'TaskNotFoundError' }, true)
]

#Status from the error

Error	Type	Description
RuntimeError	`domain`	A general runtime failure in your logic.
IntegrationError	`boundary`	A failure at the integration edge; carries a statusCode (e.g. 401/403 for auth).
SetupError	`build`	A problem while assembling the Blueprint.
InitializationError	`kernel`	A problem while initialising for an event.