@udibo/oauth2 0.14.1 → 0.15.1

package/esm/deps/jsr.io/@udibo/http-error/0.11.1/mod.d.ts

@@ -1,363 +0,0 @@
-/** Options for initializing an HttpError. */
-export interface HttpErrorOptions<Extensions extends object = Record<string, unknown>> extends ErrorOptions {
-    /** The name of the error. The default value is based on error status. This will be the default value for the `title` property in the response body. */
-    name?: string;
-    /** The message of the error. This will be the default value for the `detail` property in the response body. */
-    message?: string;
-    /** The HTTP status associated with the error. Defaults to 500. */
-    status?: number;
-    /** The HTTP status text associated with the error. */
-    statusText?: string;
-    /**
-     * Determines if the error detail should be exposed in the response.
-     * Defaults to true for client error statuses and false for server error statuses.
-     */
-    expose?: boolean;
-    /**
-     * The cause of the error. This is never exposed in the response.
-     */
-    cause?: unknown;
-    /**
-     * The type of the error is a URI reference that identifies the problem type.
-     */
-    type?: string;
-    /**
-     * The instance of the error is a URI reference that identifies the specific occurrence of the problem.
-     */
-    instance?: string;
-    /**
-     * Additional data to send in the response.
-     */
-    extensions?: Extensions;
-    /**
-     * The headers to send in the response. The content-type will default to application/problem+json unless otherwise specified in the headers.
-     */
-    headers?: Headers | Record<string, string>;
-    /**
-     * The message to expose in the response. This is used in toJSON() as the `detail` field.
-     * If not provided:
-     * - When expose is true and message exists, exposedMessage defaults to message
-     * - Otherwise, exposedMessage defaults to a generic message for the status code
-     * This allows you to have detailed internal error messages while showing safe, user-friendly messages to clients.
-     */
-    exposedMessage?: string;
-}
-interface ProblemDetailsBase {
-    type?: string;
-    status?: number;
-    title?: string;
-    detail?: string;
-    instance?: string;
-}
-export type ProblemDetails<Extensions extends object = Record<string, unknown>> = ProblemDetailsBase & Extensions;
-/**
- * An error for an HTTP request.
- *
- * This class can be used on its own to create any HttpError. It has a few
- * different call signatures you can use. The 4 examples below would throw the same
- * error.
- *
- * ```ts
- * import { HttpError } from "@udibo/http-error";
- *
- * throw new HttpError(404, "file not found");
- * throw new HttpError(404, { message: "file not found" });
- * throw new HttpError("file not found", { status: 404 });
- * throw new HttpError({ status: 404, message: "file not found" });
- * ```
- *
- * You can also include a cause in the optional options argument for it like you
- * can with regular errors.
- *
- * ```ts
- * import { HttpError } from "@udibo/http-error";
- *
- * throw new HttpError(404, "file not found", { cause: error });
- * ```
- *
- * All HttpError objects have a status associated with them. If a status is not
- * provided it will default to 500. The expose property will default to true for
- * client error status and false for server error status. You can override the
- * default behavior by setting the expose property on the options argument.
- *
- * For all known HTTP error status codes, a name will be generated for them. For
- * example, the name of an HttpError with the 404 status would be NotFoundError. If
- * the name is not known for an HTTP error status code, it will default to
- * UnknownClientError or UnknownServerError.
- *
- * ```ts
- * import { HttpError } from "@udibo/http-error";
- *
- * const error = new HttpError(404, "file not found");
- * console.log(error.toString()); // NotFoundError: file not found
- * ```
- *
- * If you would like to extend the HttpError class, you can pass your own error
- * name in the options.
- *
- * ```ts
- * import { HttpError, type HttpErrorOptions } from "@udibo/http-error";
- *
- * class CustomError extends HttpError {
- *   constructor(
- *     message?: string,
- *     options?: HttpErrorOptions,
- *   ) {
- *     super(message, { name: "CustomError", status: 420, ...options });
- *   }
- * }
- * ```
- *
- * If you'd like the arguments to match the parent HttpError classes call
- * signature, you can make use of the optionsFromArgs function. It will prioritize
- * the status / message arguments over status / message options.
- *
- * ```ts
- * import {
- *   HttpError,
- *   type HttpErrorOptions,
- *   optionsFromArgs,
- * } from "@udibo/http-error";
- *
- * class CustomError extends HttpError {
- *   constructor(
- *     status?: number,
- *     message?: string,
- *     options?: HttpErrorOptions,
- *   );
- *   constructor(status?: number, options?: HttpErrorOptions);
- *   constructor(message?: string, options?: HttpErrorOptions);
- *   constructor(options?: HttpErrorOptions);
- *   constructor(
- *     statusOrMessageOrOptions?: number | string | HttpErrorOptions,
- *     messageOrOptions?: string | HttpErrorOptions,
- *     options?: HttpErrorOptions,
- *   ) {
- *     const init = optionsFromArgs(
- *       statusOrMessageOrOptions,
- *       messageOrOptions,
- *       options,
- *     );
- *     super({ name: "CustomError", status: 420, ...init });
- *   }
- * }
- * ```
- *
- * The HttpError class also provides `toJSON()` and `getResponse()` methods to
- * convert errors into RFC 9457 Problem Details objects or Response objects,
- * respectively. This makes it easy to return standardized error responses from
- * your HTTP APIs.
- *
- * ```ts
- * import { HttpError } from "@udibo/http-error";
- *
- * const error = new HttpError(403, "Access denied", {
- *   type: "/errors/forbidden",
- *   instance: "/docs/123/edit",
- *   extensions: { accountId: "user-abc" },
- * });
- *
- * // Get Problem Details object
- * const problemDetails = error.toJSON();
- * console.log(problemDetails);
- * // Output:
- * // {
- * //   accountId: "user-abc",
- * //   status: 403,
- * //   title: "ForbiddenError",
- * //   detail: "Access denied",
- * //   type: "/errors/forbidden",
- * //   instance: "/docs/123/edit"
- * // }
- *
- * // Get a Response object
- * const response = error.getResponse();
- * console.log(response.status); // 403
- * response.json().then(body => console.log(body)); // Same as problemDetails
- * ```
- *
- * @typeparam Extensions - Other data associated with the error that will be included in the error response.
- * @param status - The HTTP status associated with the error.
- * @param message - The message associated with the error.
- * @param options - Other data associated with the error.
- * @returns An HttpError object.
- */
-export declare class HttpError<Extensions extends object = Record<string, unknown>> extends Error {
-    /**
-     * The HTTP status associated with the error.
-     * Must be a client or server error status. Defaults to 500.
-     */
-    status: number;
-    /** The HTTP status text associated with the error. */
-    statusText?: string;
-    /**
-     * Determines if the error detail should be exposed in the response.
-     * Defaults to true for client error statuses and false for server error statuses.
-     */
-    expose?: boolean;
-    /**
-     * The type of the error is a URI reference that identifies the problem type.
-     */
-    type?: string;
-    /**
-     * The instance of the error is a URI reference that identifies the specific occurrence of the problem.
-     */
-    instance?: string;
-    /**
-     * Other data associated with the error that will be included in the error response.
-     */
-    extensions: Extensions;
-    /**
-     * The headers to send in the response. The content-type will default to application/problem+json unless otherwise specified in the headers.
-     */
-    headers: Headers;
-    /**
-     * The message to expose in the response. Used as the `detail` field in toJSON().
-     * - If explicitly set in options, that value is used
-     * - If expose is true and message exists, defaults to message
-     * - Otherwise, defaults to a generic message for the status code
-     *
-     * Use this instead of `message` when rendering errors to prevent leaking internal details.
-     */
-    exposedMessage: string;
-    constructor(status?: number, message?: string, options?: HttpErrorOptions<Extensions>);
-    constructor(status?: number, options?: HttpErrorOptions<Extensions>);
-    constructor(message?: string, options?: HttpErrorOptions<Extensions>);
-    constructor(options?: HttpErrorOptions<Extensions>);
-    /**
-     * Converts any HttpError like objects into an HttpError.
-     * If the object is already an instance of HttpError, it will be returned as is.
-     *
-     * ```ts
-     * import { HttpError } from "@udibo/http-error";
-     *
-     * try {
-     *   throw new Error("something went wrong");
-     * } catch (cause) {
-     *   // Converts any non HttpError objects into an HttpError before re-throwing.
-     *   throw HttpError.from(cause);
-     * }
-     * ```
-     *
-     * @param error - The error to convert.
-     * @returns An HttpError object.
-     */
-    static from<Extensions extends object = Record<string, unknown>>(error: HttpError<Extensions> | ProblemDetails<Extensions>): HttpError<Extensions>;
-    static from<Extensions extends object = Record<string, unknown>>(error: Response): Promise<HttpError<Extensions>>;
-    static from(error: Error): HttpError;
-    static from<Extensions extends object = Record<string, unknown>>(error: unknown): HttpError<Extensions>;
-    /**
-     * Converts the HttpError to a ProblemDetails object that matches the RFC 9457
-     * Problem Details for HTTP APIs specification. This object is suitable for
-     * direct serialization into a JSON response body.
-     *
-     * @returns A ProblemDetails object representing the error, compliant with RFC 9457.
-     */
-    toJSON(): ProblemDetails<Extensions>;
-    /**
-     * Converts the HttpError to a Response object that matches the RFC 9457
-     * Problem Details for HTTP APIs specification. The body of the response will
-     * be a JSON string representing the ProblemDetails object.
-     *
-     * @returns A Response object suitable for returning from an HTTP handler, compliant with RFC 9457.
-     */
-    getResponse(): Response;
-}
-/**
- * Checks if a value is HttpError-like (an Error with a numeric status property).
- *
- * This function returns true for any Error object that has a numeric `status` property,
- * not just HttpError instances. This allows it to recognize HTTP errors from other
- * libraries or custom error classes that follow the same pattern.
- *
- * If you need to verify that an error is specifically an HttpError instance
- * (not just similar to one), use `error instanceof HttpError` instead.
- *
- * ```ts
- * import { HttpError, isHttpErrorLike } from "@udibo/http-error";
- *
- * let error = new Error("file not found");
- * console.log(isHttpErrorLike(error)); // false
- *
- * error = new HttpError(404, "file not found");
- * console.log(isHttpErrorLike(error)); // true
- * console.log(error instanceof HttpError); // true
- *
- * // Custom error class with status property
- * class CustomHttpError extends Error {
- *   status = 400;
- * }
- * const customError = new CustomHttpError("bad request");
- * console.log(isHttpErrorLike(customError)); // true
- * console.log(customError instanceof HttpError); // false
- * ```
- *
- * @param value - The value to check.
- * @returns True if the value is an HttpError or an Error with a numeric status property.
- */
-export declare function isHttpErrorLike<Extensions extends object = Record<string, unknown>>(value: unknown): value is HttpError<Extensions> | (Error & {
-    status: number;
-});
-/**
- * Creates a new class that extends HttpError, allowing for predefined default
- * options and a specific default type for extensions.
- *
- * This factory is useful for creating custom HttpError types tailored to specific
- * kinds of errors in an application, each with its own default status, name,
- * or custom extension fields.
- *
- * @example
- * ```ts
- * // Define a type for default extensions
- * interface MyApiErrorExtensions {
- *   errorCode: string;
- *   requestId?: string;
- * }
- *
- * // Create a custom error class with defaults
- * const MyApiError = createHttpErrorClass<MyApiErrorExtensions>({
- *   name: "MyApiError",
- *   status: 452, // Custom default status
- *   extensions: {
- *     errorCode: "API_GENERAL_FAILURE", // Default extension value
- *   },
- * });
- *
- * // Usage of the custom error class
- * try {
- *   // Simulate an error condition
- *   throw new MyApiError("A specific API operation failed.", {
- *     extensions: {
- *       errorCode: "API_OPERATION_X_FAILED", // Override default extension
- *       requestId: "req-12345", // Add instance-specific extension
- *     },
- *   });
- * } catch (e) {
- *   if (e instanceof MyApiError) {
- *     console.log(e.name);        // "MyApiError"
- *     console.log(e.status);      // 452
- *     console.log(e.message);     // "A specific API operation failed."
- *     console.log(e.extensions.errorCode); // "API_OPERATION_X_FAILED"
- *     console.log(e.extensions.requestId); // "req-12345"
- *     // console.log(e.toJSON());
- *   }
- * }
- *
- * // Example with a different status code at instantiation
- * const anotherError = new MyApiError(453, "Another failure");
- * console.log(anotherError.status) // 453
- * console.log(anotherError.extensions.errorCode) // "API_GENERAL_FAILURE"
- * ```
- *
- * @typeparam DefaultExtensions The type for the default `extensions` object. Defaults to `Record<string, unknown>`.
- * @param defaultOptionsForClass Optional default HttpErrorOptions to apply to the new error class.
- * @returns A new class that extends `HttpError`.
- */
-export declare function createHttpErrorClass<DefaultExtensions extends object = Record<string, unknown>>(defaultOptionsForClass?: HttpErrorOptions<DefaultExtensions>): {
-    new <Extensions extends DefaultExtensions = DefaultExtensions>(status?: number, message?: string, options?: HttpErrorOptions<Extensions>): HttpError<Extensions>;
-    new <Extensions extends DefaultExtensions = DefaultExtensions>(status?: number, options?: HttpErrorOptions<Extensions>): HttpError<Extensions>;
-    new <Extensions extends DefaultExtensions = DefaultExtensions>(message?: string, options?: HttpErrorOptions<Extensions>): HttpError<Extensions>;
-    new <Extensions extends DefaultExtensions = DefaultExtensions>(options?: HttpErrorOptions<Extensions>): HttpError<Extensions>;
-    prototype: HttpError<DefaultExtensions>;
-};
-export {};