import type { ExtensionKey, HttpRequest } from "../http/index.js";
/**
 * Extractor that extracts a raw extension from the request.
 *
 * If the `required` flag is not set or false, returns either the extension or
 * undefined.
 *
 * Otherwise, it throws an error if the extension is missing.
 *
 * @example
 * ```ts
 * import { extension } from "@taxum/core/extract";
 * import { ExtensionKey } from "@taxum/core/http";
 * import { m, Router } from "@taxum/core/routing";
 *
 * const MY_EXTENSION = new ExtensionKey<string>("My extension");
 *
 * const handler = handler([extension(MY_EXTENSION)], (extension) => {
 *     // ...
 * });
 *
 * const router = new Router()
 *     .route("/users", m.get(handler));
 * ```
 *
 * @throws {@link !Error} if the extension is missing and `required` is true.
 */
export declare const extension: <T, B extends boolean = false>(key: ExtensionKey<T>, required?: B) => (req: HttpRequest) => Promise<B extends true ? T : T | undefined>;