interface HttpStatusHint
Since 0.4.0

How an error should be answered, as decided by the code that threw it.

It is an ErrorResponseInit — the same shape respondWithError takes — because it says the same thing: the status, title and disclosure of one error response. Reusing it is what lets @setu-ts/exceptions build the response body through ONE implementation, so a hinted throw and a respondWithError call carrying the same values answer byte-identically under every configured format.

detail is required, and that is the point. The brand does not serve the Error's own message: a message is written for an operator and may quote a statement, a bound parameter or a driver's own text, which is exactly the disclosure maskInternalErrors exists to stop (X12-3). Making the caller-facing sentence an explicit act at the brand site keeps caller-safety a decision rather than an inference, so a hinted response can be exempted from masking without widening what masking protects.

Examples

Example 1

import { withHttpStatusHint } from '@setu-ts/common';

throw withHttpStatusHint(
  new Error(`Adapter 'x' cannot order by 'status': ${internalDiagnostic}`),
  {
    status: 501,
    title: 'Not Implemented',
    detail: "Query feature 'orderBy' is not supported by the 'x' adapter.",
  },
);

Properties

readonly
status: number

The HTTP status to answer with. Must be an integer in 400–599; a hint outside that range is treated as ABSENT and the error takes the ordinary masked-500 path, because a hint says how an ERROR should be answered and a status the platform cannot serve would make the error handler itself throw.

readonly
detail: string

The caller-facing disclosure, served verbatim — required here, where ErrorResponseInit leaves it optional, because a hint that omitted it would fall back to the Error's own message.

It must contain nothing the thrower would not put in an unauthenticated response body.

Usage

import { type HttpStatusHint } from "common/src/index.ts";