@beignet/core/dist/errors/catalog.d.ts

Core framework primitives for Beignet

/**
 * Error catalog and AppError definitions for Beignet
 */
import type { StandardSchemaV1 } from "@standard-schema/spec";
type ErrorDetailsSchema = StandardSchemaV1<unknown, unknown>;
declare const APP_ERROR_BRAND: unique symbol;
/**
 * Definition for one application error catalog entry.
 */
export interface ErrorDef<TDetails extends ErrorDetailsSchema | undefined = ErrorDetailsSchema | undefined> {
    /** Unique, stable code used across layers, such as `"POST_NOT_FOUND"`. */
    code: string;
    /** HTTP status code returned when this error crosses the HTTP boundary. */
    status: number;
    /** Default human-readable message. */
    message: string;
    /**
     * Optional schema for the structured details value.
     *
     * Beignet uses this for TypeScript inference. Details are not runtime
     * validated by `AppError`; validate before constructing errors when needed.
     * Details become public response data when the error crosses the HTTP
     * boundary, so use app-owned safe fields instead of raw diagnostics.
     */
    details?: TDetails;
}
/**
 * App error catalog keyed by developer-friendly names.
 *
 * Keys are local identifiers used by `createAppError(...)`; the public stable
 * error code lives on each `ErrorDef.code`.
 */
export type ErrorCatalog = Record<string, ErrorDef>;
/**
 * Infer the details input type for an error definition.
 */
export type InferErrorDetails<TDef extends ErrorDef> = TDef extends {
    details: ErrorDetailsSchema;
} ? StandardSchemaV1.InferInput<TDef["details"]> : unknown;
/**
 * Define an application error catalog without losing literal key and code types.
 */
export declare function defineErrors<const T extends ErrorCatalog>(defs: T): T;
/**
 * Application error thrown from use cases, policies, and route handlers.
 *
 * The server maps `AppError` instances to Beignet's standard error envelope and
 * marks them as route-owned errors when the contract declares the catalog entry.
 */
export declare class AppError<TDef extends ErrorDef = ErrorDef> extends Error {
    readonly [APP_ERROR_BRAND] = true;
    /** Error definition from the catalog. */
    readonly def: TDef;
    /**
     * Optional structured details for clients or UI.
     *
     * Beignet does not automatically redact route-owned error details. Keep
     * provider errors, stack traces, secrets, and private content in `cause`,
     * logs, or error reporting instead.
     */
    readonly details?: InferErrorDetails<TDef>;
    /**
     * Optional HTTP response headers set when this error crosses the HTTP
     * boundary, such as `Retry-After` on a 429. Headers are public response
     * data; only include values that are safe to expose.
     */
    readonly headers?: Record<string, string>;
    constructor(def: TDef, details?: InferErrorDetails<TDef>, overrideMessage?: string, options?: {
        cause?: unknown;
        headers?: Record<string, string>;
    });
    /**
     * Stable public error code.
     */
    get code(): string;
    /**
     * HTTP status code associated with this error.
     */
    get status(): number;
}
/**
 * Callable helper for creating `AppError` instances from a catalog.
 */
export type AppErrorCreator<TCatalog extends ErrorCatalog> = {
    /**
     * Original catalog bound to this creator.
     */
    catalog: TCatalog;
    /**
     * Create an `AppError` from a catalog key.
     */
    <Key extends keyof TCatalog>(key: Key, options?: {
        cause?: unknown;
        details?: InferErrorDetails<TCatalog[Key]>;
        headers?: Record<string, string>;
        message?: string;
    }): AppError<TCatalog[Key]>;
};
/**
 * Create a callable `AppError` helper bound to a specific catalog.
 *
 * The returned function validates the catalog key and preserves each entry's
 * details type for `options.details`.
 */
export declare function createAppError<const T extends ErrorCatalog>(catalog: T): AppErrorCreator<T>;
/**
 * Check whether an unknown value is a Beignet `AppError`.
 */
export declare function isAppError(err: unknown): err is AppError<ErrorDef>;
export {};
//# sourceMappingURL=catalog.d.ts.map