@kalutskii/foundation 2.0.5 → 2.0.6

package/dist/index.d.ts

@@ -1,86 +1,284 @@
-import { SQL } from "drizzle-orm";
 import { Locale } from "date-fns";
-import z, { ZodObject, ZodRawShape, z as z$1 } from "zod";
+import { InferSelectModel, SQL, Table } from "drizzle-orm";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
 import { Context, ErrorHandler, MiddlewareHandler, TypedResponse } from "hono";
 import { SymmetricAlgorithm } from "hono/utils/jwt/jwa";
+import { JWTPayload, JWTPayload as JWTPayload$1 } from "hono/utils/jwt/types";
+//#region src/base64/base64.utilities.d.ts
+/**
+ * Encodes arbitrary binary bytes into their canonical Base64 representation.
+ * Chunked conversion avoids the argument limit imposed by `String.fromCharCode`.
+ */
+declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Decodes Base64 text accepted by native `atob` into its original binary bytes.
+ * Unsupported input preserves the platform failure instead of returning partial data.
+ */
+declare function decodeBase64(value: string): Uint8Array<ArrayBuffer>;
+//#endregion
+//#region src/datetime/datetime.types.d.ts
+/**
+ * Options selecting the timezone used by current-time datetime operations.
+ * An omitted timezone preserves the shared London-based default behavior.
+ */
+type DateTimeZoneOptions = {
+  /**
+   * IANA timezone used to project and format the current instant.
+   * The shared London timezone applies when this option is omitted.
+   */
+  tz?: string;
+};
+/**
+ * Options controlling current-date formatting and optional time inclusion.
+ * Time output includes its UTC offset and remains enabled unless explicitly disabled.
+ */
+type FormattedDateOptions = DateTimeZoneOptions & {
+  /**
+   * Controls whether wall-clock time and its UTC offset are included.
+   * Time information remains enabled unless this option is explicitly `false`.
+   */
+  withTime?: boolean;
+};
+/**
+ * Options controlling localized formatting for one explicit instant.
+ * Russian localization and the shared timezone default apply when omitted.
+ */
+type FormatTimeOptions = DateTimeZoneOptions & {
+  /**
+   * date-fns locale used for the textual calendar representation.
+   * The Russian locale remains the default when this option is omitted.
+   */
+  locale?: Locale;
+};
+//#endregion
+//#region src/datetime/datetime.utilities.d.ts
+/**
+ * Projects the current instant onto the wall-clock fields of another timezone.
+ * The timezone defaults to `Europe/London` when no option is provided.
+ *
+ * @example
+ * const londonTime = getZonedTime({ tz: 'Europe/London' });
+ */
+declare function getZonedTime({ tz }?: DateTimeZoneOptions): Date;
+/**
+ * Formats the UTC offset of a timezone at the supplied date.
+ * An explicit date preserves daylight-saving and historical offset rules.
+ *
+ * @example
+ * getUTCOffset(date, 'Europe/Moscow'); // `(+3 UTC)`
+ */
+declare function getUTCOffset(date: Date, tz: string): string;
+/**
+ * Formats the current time and UTC offset in the selected timezone.
+ * The timezone defaults to `Europe/London` when no option is provided.
+ *
+ * @example
+ * getFormattedTime({ tz: 'Europe/Moscow' }); // `03:04:05 (+3 UTC)`
+ */
+declare function getFormattedTime({ tz }?: DateTimeZoneOptions): string;
+/**
+ * Formats the current date with optional time and UTC offset components.
+ * Time is included by default and uses the selected timezone for display.
+ *
+ * @example
+ * getFormattedDate({ tz: 'UTC', withTime: false }); // `02.01.2024`
+ */
+declare function getFormattedDate({ tz, withTime }?: FormattedDateOptions): string;
+/**
+ * Formats an explicit instant in another timezone using the selected locale.
+ * The result includes localized date text, wall-clock time, and UTC offset.
+ *
+ * @example
+ * formatTime(date, { locale: ru, tz: 'Europe/Moscow' });
+ */
+declare function formatTime(time: Date, options?: FormatTimeOptions): string;
+//#endregion
+//#region src/datetime/datetime.constants.d.ts
+/**
+ * Default timezone applied by datetime utilities when no explicit zone is provided.
+ * The value preserves the package's historical London-based formatting behavior.
+ */
+declare const DEFAULT_DATETIME_TIMEZONE = "Europe/London";
+//#endregion
+//#region src/drizzle/drizzle.errors.d.ts
+declare const drizzleErrors: {
+  whereConditionsRequired: () => Error;
+  whereColumnNotFound: () => Error;
+};
+type DrizzleErrorCode = keyof typeof drizzleErrors;
+//#endregion
+//#region src/drizzle/drizzle.types.d.ts
+/**
+ * Defined equality conditions accepted by `sqlWhere` for one Drizzle table.
+ * Keys and values remain aligned with the table's inferred selected row model.
+ */
+type SQLWhereConditions<TTable extends Table> = Partial<InferSelectModel<TTable>>;
+//#endregion
 //#region src/drizzle/drizzle.refiners.d.ts
 /**
  * Builds a Drizzle `WHERE` clause by combining defined object entries with `and`.
- * Expects the supplied keys to be validated against the table beforehand.
+ * Keys and values follow the table model while empty conditions remain forbidden.
  *
  * @example
  * await db.update(usersTable).set(values).where(sqlWhere(usersTable, { id: 1 })).returning();
  */
-declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL;
+declare function sqlWhere<TTable extends Table>(table: TTable, where: SQLWhereConditions<NoInfer<TTable>>): SQL;
 //#endregion
-//#region src/hono/hono.execution.d.ts
+//#region src/execution/execution.constants.d.ts
 /**
- * Converts expected `HTTPException` values into shared API error envelopes.
- * Unexpected failures are logged and represented by a traceable generic response.
+ * Default total attempt count applied when `retryExecution` receives no override.
+ * The value includes the initial operation and every subsequent retry attempt.
  */
-declare const onHandlerError: ErrorHandler;
+declare const DEFAULT_RETRY_MAX_ATTEMPTS = 3;
 //#endregion
-//#region src/http/http.constants.d.ts
-declare const SUCCESS_STATUS_CODES: readonly [200, 201, 202, 307];
-declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 413, 500];
-//#endregion
-//#region src/http/http.types.d.ts
-type SuccessStatusCode = (typeof SUCCESS_STATUS_CODES)[number];
-type ExceptionStatusCode = (typeof EXCEPTION_STATUS_CODES)[number];
-type APISuccess<TData = void> = {
-  kind: 'data';
-  status: SuccessStatusCode;
-  data: TData;
+//#region src/execution/execution.errors.d.ts
+declare const executionErrors: {
+  invalidMaxAttempts: () => RangeError;
+  invalidRetryDelay: () => RangeError;
+  invalidTimeout: () => RangeError;
+  executionTimedOut: () => DOMException;
 };
-type APIError<TErrorCode extends string = string> = {
-  kind: 'error';
-  status: ExceptionStatusCode;
-  error: TErrorCode;
-};
-type APIContractResult<TData = void, TErrorCode extends string = string> = APISuccess<TData> | APIError<TErrorCode>;
-type APIContractData<TResult extends APIContractResult<unknown>> = TResult extends APISuccess<infer TData> ? TData : never;
-type APIContractError<TResult extends APIContractResult<unknown>> = Extract<TResult, APIError>;
-type APIContractErrorCode<TResult extends APIContractResult<unknown>> = APIContractError<TResult>['error'];
-type ErrorCodeOf<TErrorFactories extends Record<string, unknown>> = keyof TErrorFactories & string;
-type FetchResult<TData, TErrorCode extends string = string> = {
-  error: null;
+type ExecutionErrorCode = keyof typeof executionErrors;
+//#endregion
+//#region src/execution/execution.types.d.ts
+/**
+ * Synchronous or asynchronous operation consumed by execution utilities.
+ * The resolved value remains inferred from its callback without widening.
+ */
+type Execution<TData> = () => TData | Promise<TData>;
+/**
+ * Mutually exclusive result produced after capturing an operation outcome.
+ * Successful data and unknown failures are distinguished by `success`.
+ */
+type ExecutionResult<TData> = {
+  success: true;
   data: TData;
 } | {
-  error: TErrorCode;
-  data: null;
+  success: false;
+  error: unknown;
 };
+/**
+ * Context supplied to every operation attempt executed by `retryExecution`.
+ * Attempts are one-based and share an optional caller cancellation signal.
+ */
+type RetryExecutionContext = Readonly<{
+  /**
+   * One-based number of the attempt currently being executed.
+   * The initial operation always receives the `attempt` value `1`.
+   */
+  attempt: number;
+  /**
+   * Optional signal allowing the operation to observe caller cancellation.
+   * The same signal remains available across every execution attempt.
+   */
+  signal?: AbortSignal;
+}>;
+/**
+ * Configuration controlling retry limits, delays, filtering, and cancellation.
+ * Three immediate attempts run by default when every failure remains retryable.
+ */
+type RetryExecutionOptions = Readonly<{
+  /**
+   * Positive total attempt count including the initial execution.
+   * Omitting this option applies the default of three attempts.
+   */
+  maxAttempts?: number;
+  /**
+   * Delay before the next attempt, or a resolver returning it in milliseconds.
+   * The resolver receives the failure and completed one-based attempt number.
+   */
+  delayMilliseconds?: number | ((error: unknown, attempt: number) => number | Promise<number>);
+  /**
+   * Decides whether another attempt may follow the latest operation failure.
+   * Returning `false` preserves and immediately rethrows the original failure.
+   */
+  shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+  /**
+   * Cancels pending delays and prevents subsequent attempts when aborted.
+   * Active operations must observe the signal to stop their own work.
+   */
+  signal?: AbortSignal;
+}>;
+/**
+ * Configuration for one cooperatively cancellable time-bounded execution.
+ * Caller cancellation and timeout expiration retain their original reasons.
+ */
+type ExecuteWithTimeoutOptions = Readonly<{
+  /**
+   * Non-negative finite execution duration expressed in milliseconds.
+   * Expiration aborts with a standard `TimeoutError` DOM exception.
+   */
+  timeoutMilliseconds: number;
+  /**
+   * Optional caller signal combined with the internally managed timeout signal.
+   * Its cancellation reason takes precedence when the signal is already aborted.
+   */
+  signal?: AbortSignal;
+}>;
 //#endregion
-//#region src/hono/hono.types.d.ts
+//#region src/execution/execution.measurements.d.ts
 /**
- * Options for a typed JSON response wrapped in the shared API success envelope.
- * The status generic preserves the literal code inferred by the route contract.
+ * Result returned after measuring a successful synchronous or asynchronous execution.
+ * The resolved value remains available beside its rounded millisecond duration.
  */
-type HonoRespondOptions<TData extends object, TStatus extends SuccessStatusCode> = {
-  status: TStatus;
-  data?: TData;
+type MeasuredExecution<TData> = {
+  /**
+   * Value resolved by the measured execution without cloning or transformation.
+   * Its generic type remains identical to the original operation result.
+   */
+  result: TData;
+  /**
+   * Rounded wall-clock duration of the measured execution in milliseconds.
+   * The value is collected only after the supplied operation resolves.
+   */
+  executionTime: number;
 };
 /**
- * Options for a downloadable binary response with attachment metadata.
- * The content type remains optional and falls back to a generic binary type.
+ * Measures a synchronous or asynchronous execution while preserving its resolved result.
+ * Rejected operations propagate unchanged and never produce a measurement result.
+ *
+ * @example
+ * const { result, executionTime } = await measureExecutionTime(async () => {
+ *    return await fetchData();
+ * });
+ * console.log(`Execution time: ${executionTime}ms`);
  */
-type HonoFileRespondOptions<TStatus extends SuccessStatusCode> = {
-  status: TStatus;
-  content: Uint8Array<ArrayBuffer>;
-  filename: string;
-  contentType?: string;
-};
+declare function measureExecutionTime<TData>(execution: Execution<TData>): Promise<MeasuredExecution<TData>>;
 //#endregion
-//#region src/hono/hono.respond.d.ts
+//#region src/execution/execution.retry.d.ts
 /**
- * Wraps `c.json` in the shared success envelope while preserving its literal status.
- * Missing response data is represented by an empty object for contract consistency.
+ * Waits for a retry delay while preserving cooperative caller cancellation.
+ * Zero-duration delays resolve immediately without allocating a timer.
  */
-declare function respond<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: HonoRespondOptions<T, S>): Response & TypedResponse<APISuccess<T> | APIError, S, 'json'>;
+declare function waitForRetry(delayMilliseconds: number, signal?: AbortSignal): Promise<void>;
 /**
- * Responds with downloadable binary content and its attachment headers.
- * Unknown/undefined content types default to `application/octet-stream`.
+ * Repeats a failed operation under explicit attempt, delay, and filtering policies.
+ * Exhaustion, rejected filtering, and cancellation preserve the original failure.
+ */
+declare function retryExecution<TData>(execution: (context: RetryExecutionContext) => TData | Promise<TData>, options?: RetryExecutionOptions): Promise<TData>;
+//#endregion
+//#region src/execution/execution.timeout.d.ts
+/**
+ * Runs an operation with a signal controlled by timeout and caller cancellation.
+ * The promise rejects promptly even when the operation ignores its abort signal.
  */
-declare function fileRespond<S extends SuccessStatusCode>(c: Context, options: HonoFileRespondOptions<S>): Response;
+declare function executeWithTimeout<TData>(execution: (signal: AbortSignal) => TData | Promise<TData>, options: ExecuteWithTimeoutOptions): Promise<TData>;
+//#endregion
+//#region src/execution/execution.utilities.d.ts
+/**
+ * Resolves synchronous and asynchronous operations through one promise-based contract.
+ * Failures use the supplied fallback or propagate unchanged when none is available.
+ *
+ * @example
+ * await safeExecute(() => fetchData(), (error) => console.error(error));
+ */
+declare function safeExecute<TData, TErrorResult = never>(fn: Execution<TData>, onError?: (error: unknown) => TErrorResult | Promise<TErrorResult>): Promise<TData | TErrorResult>;
+/**
+ * Captures a synchronous or asynchronous operation in a discriminated result.
+ * Successful values and original unknown failures remain available unchanged.
+ */
+declare function captureExecution<TData>(execution: Execution<TData>): Promise<ExecutionResult<TData>>;
 //#endregion
 //#region src/hmac/hmac.constants.d.ts
 /**
@@ -120,12 +318,26 @@ declare const hmacEncoding: Readonly<{
   HEX: "hex";
 }>;
 //#endregion
+//#region src/hmac/hmac.errors.d.ts
+declare const hmacErrors: {
+  invalidHexSignature: () => TypeError;
+  invalidBase64Signature: () => TypeError;
+  invalidBase64UrlSignature: () => TypeError;
+  incompatibleCryptoKey: () => TypeError;
+};
+type HMACErrorCode = keyof typeof hmacErrors;
+//#endregion
 //#region src/hmac/hmac.types.d.ts
 /**
  * Binary-safe input accepted as either an HMAC payload or a secret key.
  * Strings use UTF-8 encoding while byte arrays preserve their exact contents.
  */
 type HMACInput = string | Uint8Array;
+/**
+ * Secret material accepted directly or as a previously imported Web Crypto key.
+ * Imported keys avoid repeated key imports across high-frequency operations.
+ */
+type HMACSecret = HMACInput | CryptoKey;
 /**
  * Configures the digest algorithm and textual signature encoding for one service.
  * Omitted values select SHA-256 and lowercase hexadecimal output by default.
@@ -152,23 +364,28 @@ declare class HMACService {
   readonly algorithm: HMACAlgorithm;
   readonly encoding: HMACEncoding;
   constructor(options?: HMACServiceOptions);
+  /**
+   * Imports raw secret material as a non-extractable Web Crypto HMAC key.
+   * The resulting key supports repeated signing and verification without reimporting.
+   */
+  importKey(secret: HMACInput): Promise<CryptoKey>;
   /**
    * Authenticates a payload with a secret and returns the encoded signature.
-   * String inputs use UTF-8 while byte arrays preserve their exact byte sequence.
+   * Imported keys bypass repeated key creation while preserving service policy.
    *
    * @example
    * const signature = await hmacService.sign('payload', 'shared-secret');
    */
-  sign(payload: HMACInput, secret: HMACInput): Promise<string>;
+  sign(payload: HMACInput, secret: HMACSecret): Promise<string>;
   /**
    * Verifies an encoded signature without requiring a manual equality comparison.
-   * Invalid encodings, incorrect secrets, and altered payloads all resolve to `false`.
+   * Invalid signatures resolve to `false`; incompatible imported keys reject explicitly.
    *
    * @example
    * const verified = await hmacService.verify('payload', signature, 'shared-secret');
    */
-  verify(payload: HMACInput, signature: string, secret: HMACInput): Promise<boolean>;
-  private importSecret;
+  verify(payload: HMACInput, signature: string, secret: HMACSecret): Promise<boolean>;
+  private resolveKey;
 }
 //#endregion
 //#region src/hmac/hmac.utilities.d.ts
@@ -188,502 +405,612 @@ declare function encodeHMACSignature(signature: Uint8Array, encoding: HMACEncodi
  */
 declare function decodeHMACSignature(signature: string, encoding: HMACEncoding): Uint8Array<ArrayBuffer>;
 //#endregion
-//#region src/http/http.errors.d.ts
+//#region src/hono/hono.constants.d.ts
 /**
- * Represents an error envelope rejected by an API request resolver.
- * The original status and typed code remain available for client handling.
+ * Default HTTP header carrying one request identifier across service boundaries.
+ * Incoming non-empty values are preserved while missing identifiers are generated.
  */
-declare class APIRequestError<TErrorCode extends string = string> extends Error {
-  readonly code: TErrorCode;
-  readonly status: ExceptionStatusCode;
-  constructor(status: ExceptionStatusCode, code: TErrorCode);
-}
-//#endregion
-//#region src/http/http.factory.d.ts
+declare const HONO_REQUEST_ID_HEADER = "X-Request-ID";
 /**
- * Creates a successful API envelope without cloning its data.
- * Generic inference preserves the exact supplied payload type.
+ * Default service label applied to request lines emitted by Hono logging middleware.
+ * Configured middleware may replace the label without changing message formatting.
  */
-declare function success<T = unknown>({ status, data }: {
-  status: SuccessStatusCode;
-  data: T;
-}): APISuccess<T>;
+declare const HONO_LOGGING_SERVICE = "hono";
+//#endregion
+//#region src/hono/hono.errors.d.ts
+declare const honoErrors: {
+  internalServerError: () => HTTPException;
+  invalidRequestId: () => TypeError;
+};
+type HonoErrorCode = keyof typeof honoErrors;
+//#endregion
+//#region src/response/response.enums.d.ts
+declare const responseKindsArray: readonly ['success', 'error'];
+type ResponseKind = (typeof responseKindsArray)[number];
+declare const responseKindsRecord: Readonly<{
+  ERROR: "error";
+  SUCCESS: "success";
+}>;
+declare const responseKind: Readonly<{
+  ERROR: "error";
+  SUCCESS: "success";
+}>;
+declare const SUCCESS_RESPONSE_STATUSES: readonly [200, 201, 202, 206];
+type SuccessResponseStatus = (typeof SUCCESS_RESPONSE_STATUSES)[number];
+declare const ERROR_RESPONSE_STATUSES: readonly [400, 401, 403, 404, 405, 406, 408, 409, 410, 413, 414, 415, 422, 425, 429, 440, 498, 500, 501, 502, 503, 504];
+type ErrorResponseStatus = (typeof ERROR_RESPONSE_STATUSES)[number];
+//#endregion
+//#region src/response/response.errors.d.ts
+declare const responseErrors: {
+  invalidResponseErrorCode: () => TypeError;
+  invalidSuccessResponseStatus: () => RangeError;
+  invalidErrorResponseStatus: () => RangeError;
+};
+type ResponseErrorCode = keyof typeof responseErrors;
 /**
- * Creates a failed API envelope with one supported exception status.
- * The supplied error code remains unchanged for downstream resolution.
+ * Represents a failed response rejected while unwrapping a remote operation.
+ * The original machine-readable code and response status remain available.
  */
-declare function failure<const TErrorCode extends string>({ status, error }: {
-  status: ExceptionStatusCode;
+declare class ResponseError<TErrorCode extends string = string> extends Error {
+  readonly code: TErrorCode;
+  readonly status: ErrorResponseStatus;
+  constructor(status: ErrorResponseStatus, code: TErrorCode);
+}
+//#endregion
+//#region src/response/response.types.d.ts
+type SuccessResponse<TData = void> = {
+  kind: typeof responseKind.SUCCESS;
+  status: SuccessResponseStatus;
+  data: TData;
+};
+type ErrorResponse<TErrorCode extends string = string> = {
+  kind: typeof responseKind.ERROR;
+  status: ErrorResponseStatus;
   error: TErrorCode;
-}): APIError<TErrorCode>;
+};
+type ResponseResult<TData = void, TErrorCode extends string = string> = SuccessResponse<TData> | ErrorResponse<TErrorCode>;
+type ResponseData<TResult extends ResponseResult<unknown>> = TResult extends SuccessResponse<infer TData> ? TData : never;
+type ResponseFailure<TResult extends ResponseResult<unknown>> = Extract<TResult, ErrorResponse>;
+type ResponseFailureCode<TResult extends ResponseResult<unknown>> = ResponseFailure<TResult>['error'];
+type ErrorCodeOf<TErrorFactories extends Record<string, unknown>> = keyof TErrorFactories & string;
+type ResolvedResponse<TData, TErrorCode extends string = string> = {
+  success: true;
+  status: SuccessResponseStatus;
+  data: TData;
+  error: null;
+} | {
+  success: false;
+  status: ErrorResponseStatus;
+  data: null;
+  error: TErrorCode;
+};
 //#endregion
-//#region src/http/http.resolvers.d.ts
+//#region src/response/response.factories.d.ts
 /**
- * Converts an API contract envelope into a mutually exclusive safe result.
- * Only `APIError` values are normalized; rejected fetchers still reject.
+ * Creates a successful response envelope without cloning its supplied data.
+ * Generic inference preserves the exact payload type for downstream contracts.
  */
-declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>, APIContractErrorCode<TResult>>>;
+declare function createSuccessResponse<TData>(status: SuccessResponseStatus, data: TData): SuccessResponse<TData>;
 /**
- * Returns successful API data and throws `APIRequestError` for a failed envelope.
- * Transport and programming rejections propagate without replacement.
+ * Creates a failed response envelope from one stable machine-readable error code.
+ * Human-readable or malformed values reject before crossing the response boundary.
  */
-declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
+declare function createErrorResponse<const TErrorCode extends string>(status: ErrorResponseStatus, error: TErrorCode): ErrorResponse<TErrorCode>;
 //#endregion
-//#region src/logging/logging.constants.d.ts
+//#region src/response/response.resolvers.d.ts
 /**
- * Terminal color configuration for every supported logging level.
- * The `LogLevel` contract prevents missing or unsupported level entries.
+ * Resolves a response envelope into a status-preserving discriminated result.
+ * Transport and programming failures remain observable promise rejections.
  */
-declare const logLevelColors: {
-  readonly info: typeof import("kleur/colors").print;
-  readonly warn: typeof import("kleur/colors").print;
-  readonly error: typeof import("kleur/colors").print;
-};
+declare function resolveResponse<TResult extends ResponseResult<unknown>>(operation: () => Promise<TResult>): Promise<ResolvedResponse<ResponseData<TResult>, ResponseFailureCode<TResult>>>;
 /**
- * Public placeholder written instead of sensitive query and JSON values.
- * One stable marker keeps redacted output recognizable across log consumers.
+ * Unwraps successful response data and throws `ResponseError` for a failed envelope.
+ * Transport and programming failures propagate without replacement or normalization.
  */
-declare const REDACTED_LOG_VALUE = "[redacted]";
+declare function unwrapResponse<TResult extends ResponseResult<unknown>>(operation: () => Promise<TResult>): Promise<ResponseData<TResult>>;
+//#endregion
+//#region src/response/response.validation.d.ts
 /**
- * Normalized key fragments treated as sensitive by logging redaction.
- * Matching ignores case and separators so compound field names remain covered.
+ * Determines whether a value is a stable camelCase response error code.
+ * Human-readable text and punctuation remain excluded from public envelopes.
  */
-declare const sensitiveLogKeyParts: readonly ['password', 'passwd', 'token', 'secret', 'authorization', 'apikey', 'credential'];
+declare function isResponseErrorCode(value: unknown): value is string;
 /**
- * Terminal colors assigned to the supported HTTP response status ranges.
- * Unlisted ranges intentionally retain the terminal's default text appearance.
+ * Determines whether a value belongs to the supported success-status catalog.
+ * Runtime membership mirrors the exact union exposed by `SuccessResponseStatus`.
  */
-declare const httpStatusColors: readonly [{
-  readonly range: readonly [200, 299];
-  readonly color: typeof import("kleur/colors").print;
-}, {
-  readonly range: readonly [400, 499];
-  readonly color: typeof import("kleur/colors").print;
-}, {
-  readonly range: readonly [500, 599];
-  readonly color: typeof import("kleur/colors").print;
-}];
-//#endregion
-//#region src/logging/logging.enums.d.ts
-declare const logLevelsArray: readonly ['info', 'warn', 'error'];
-type LogLevel = (typeof logLevelsArray)[number];
-declare const logLevelsRecord: Readonly<{
-  ERROR: "error";
-  INFO: "info";
-  WARN: "warn";
-}>;
-declare const logLevel: Readonly<{
-  ERROR: "error";
-  INFO: "info";
-  WARN: "warn";
-}>;
-//#endregion
-//#region src/logging/logging.middleware.d.ts
+declare function isSuccessResponseStatus(value: unknown): value is SuccessResponseStatus;
 /**
- * Logs Hono request metadata with query parameters and a normalized body preview.
- * Sensitive values are redacted by partial key match before output is written.
+ * Determines whether a value belongs to the supported error-status catalog.
+ * Runtime membership mirrors the exact union exposed by `ErrorResponseStatus`.
  */
-declare const loggingMiddleware: MiddlewareHandler;
-//#endregion
-//#region src/logging/logging.security.d.ts
+declare function isErrorResponseStatus(value: unknown): value is ErrorResponseStatus;
 /**
- * Replaces sensitive query values using partial, case-insensitive key matching.
- * A new collection is returned so the caller's search parameters remain unchanged.
+ * Narrows a response result to its successful branch through the shared discriminator.
+ * Payload and error-code generics remain unchanged for downstream control-flow analysis.
  */
-declare function redactSensitiveSearchParams(searchParams: URLSearchParams): URLSearchParams;
+declare function isSuccessResponse<TData, TErrorCode extends string>(response: ResponseResult<TData, TErrorCode>): response is SuccessResponse<TData>;
 /**
- * Replaces values under sensitive keys throughout a serialized JSON structure.
- * Invalid JSON and payloads without matching keys are returned byte-for-byte unchanged.
+ * Narrows a response result to its failed branch through the shared discriminator.
+ * Payload and error-code generics remain unchanged for downstream control-flow analysis.
  */
-declare function redactSensitiveJSON(json: string): string;
+declare function isErrorResponse<TData, TErrorCode extends string>(response: ResponseResult<TData, TErrorCode>): response is ErrorResponse<TErrorCode>;
 //#endregion
-//#region src/logging/logging.services.d.ts
+//#region src/hono/hono.types.d.ts
 /**
- * Writes timestamped and colorized messages using a stable service column.
- * Error messages may include a stack trace on a subordinate second line.
+ * Options controlling the application-owned side effect for unexpected Hono failures.
+ * Expected client exceptions bypass the callback and retain their machine-readable code.
  */
-declare const log: {
+type HonoErrorHandlerOptions = {
   /**
-   * Writes an informational message with an optional service label.
-   * Missing service names use the shared `log` fallback label.
+   * Receives an unexpected failure, request context, and optional correlation identifier.
+   * Applications may report original context without changing the public response envelope.
    */
-  info(message: string, service?: string): void;
+  onUnexpectedError: (error: unknown, context: Context, requestId?: string) => void;
+};
+/**
+ * Options controlling request metadata and body previews emitted by Hono middleware.
+ * Defaults preserve the existing service label, body capture, and shared preview limit.
+ */
+type HonoLoggingMiddlewareOptions = {
   /**
-   * Writes a warning message with an optional service label.
-   * Missing service names use the shared `log` fallback label.
+   * Service label passed to the configured writer beside every completed request.
+   * Omission uses the stable `hono` label shared by the default middleware.
    */
-  warn(message: string, service?: string): void;
+  service?: string;
+  /**
+   * Destination receiving each formatted request line and its resolved service label.
+   * Omission delegates output to the shared logging service at informational level.
+   */
+  write?: (message: string, service: string) => void;
+  /**
+   * Determines whether request bodies are cloned, normalized, and included in logs.
+   * Omission enables previews to preserve the established middleware behavior.
+   */
+  includeBody?: boolean;
+  /**
+   * Number of characters retained from each edge of an oversized body preview.
+   * Omission uses the shared logging limit and invalid values reject immediately.
+   */
+  bodyPreviewEdgeLength?: number;
   /**
-   * Writes an error message with optional service and stack trace context.
-   * Provided stack traces are rendered beneath the primary message.
+   * Header inspected for request correlation after downstream middleware completes.
+   * Omission uses the same default header as request identifier middleware.
    */
-  error(message: string, service?: string, stack?: string): void;
+  requestIdHeader?: string;
 };
-//#endregion
-//#region src/logging/logging.utilities.d.ts
 /**
- * Selects a terminal color function for one HTTP response status.
- * Successes are green, client errors yellow, and server errors red.
+ * Options controlling acceptance and creation of request identifiers in Hono.
+ * Existing non-empty identifiers take precedence over locally generated values.
  */
-declare function getColoredHTTPStatus(status: number): (text: string) => string;
-//#endregion
-//#region src/upload/upload.constants.d.ts
+type HonoRequestIdMiddlewareOptions = {
+  /**
+   * Header read from incoming requests and written to every outgoing response.
+   * Omission uses the shared `X-Request-ID` header name.
+   */
+  header?: string;
+  /**
+   * Factory invoked only when the incoming request does not carry an identifier.
+   * Omission generates a standards-based random UUID through the Web Crypto API.
+   */
+  createRequestId?: () => string;
+};
 /**
- * Canonical metadata shared by upload controls and runtime validation.
- * Every supported format defines display, MIME, and extension values.
+ * Options for a typed JSON response wrapped in the shared success envelope.
+ * The status generic preserves the literal code inferred by the route contract.
  */
-declare const fileFormatsConfig: {
-  readonly png: {
-    readonly name: 'PNG';
-    readonly mimeTypes: readonly ["image/png"];
-    readonly extensions: readonly [".png"];
-  };
-  readonly jpg: {
-    readonly name: 'JPG';
-    readonly mimeTypes: readonly ["image/jpeg"];
-    readonly extensions: readonly [".jpg", ".jpeg"];
-  };
-  readonly svg: {
-    readonly name: 'SVG';
-    readonly mimeTypes: readonly ["image/svg+xml"];
-    readonly extensions: readonly [".svg"];
-  };
-  readonly webp: {
-    readonly name: 'WEBP';
-    readonly mimeTypes: readonly ["image/webp"];
-    readonly extensions: readonly [".webp"];
-  };
-  readonly avif: {
-    readonly name: 'AVIF';
-    readonly mimeTypes: readonly ["image/avif"];
-    readonly extensions: readonly [".avif"];
-  };
-  readonly heic: {
-    readonly name: 'HEIC';
-    readonly mimeTypes: readonly ["image/heic", "image/heif"];
-    readonly extensions: readonly [".heic", ".heif"];
-  };
-  readonly pdf: {
-    readonly name: 'PDF';
-    readonly mimeTypes: readonly ["application/pdf"];
-    readonly extensions: readonly [".pdf"];
-  };
-  readonly rtf: {
-    readonly name: 'RTF';
-    readonly mimeTypes: readonly ["application/rtf"];
-    readonly extensions: readonly [".rtf"];
-  };
-  readonly txt: {
-    readonly name: 'TXT';
-    readonly mimeTypes: readonly ["text/plain"];
-    readonly extensions: readonly [".txt"];
-  };
+type HonoRespondOptions<TData extends object, TStatus extends SuccessResponseStatus> = {
+  status: TStatus;
+  data?: TData;
+};
+/**
+ * Options for a downloadable binary response with attachment metadata.
+ * The content type remains optional and falls back to a generic binary type.
+ */
+type HonoFileRespondOptions<TStatus extends SuccessResponseStatus> = {
+  status: TStatus;
+  content: Uint8Array<ArrayBuffer>;
+  filename: string;
+  contentType?: string;
 };
 //#endregion
-//#region src/upload/upload.enums.d.ts
-declare const fileFormatsArray: readonly ["png", "jpg", "webp", "avif", "heic", "svg", "pdf", "rtf", "txt"];
-type FileFormat = (typeof fileFormatsArray)[number];
-declare const fileFormatsRecord: Readonly<{
-  AVIF: "avif";
-  HEIC: "heic";
-  JPG: "jpg";
-  PDF: "pdf";
-  PNG: "png";
-  RTF: "rtf";
-  SVG: "svg";
-  TXT: "txt";
-  WEBP: "webp";
-}>;
-declare const fileFormat: Readonly<{
-  AVIF: "avif";
-  HEIC: "heic";
-  JPG: "jpg";
-  PDF: "pdf";
-  PNG: "png";
-  RTF: "rtf";
-  SVG: "svg";
-  TXT: "txt";
-  WEBP: "webp";
-}>;
-declare const uploadValidationErrorsArray: readonly ['empty_file', 'unsupported_file_format', 'file_size_exceeded', 'files_count_exceeded'];
-type UploadValidationError = (typeof uploadValidationErrorsArray)[number];
-declare const uploadValidationErrorsRecord: Readonly<{
-  EMPTY_FILE: "empty_file";
-  FILES_COUNT_EXCEEDED: "files_count_exceeded";
-  FILE_SIZE_EXCEEDED: "file_size_exceeded";
-  UNSUPPORTED_FILE_FORMAT: "unsupported_file_format";
-}>;
-declare const uploadValidationError: Readonly<{
-  EMPTY_FILE: "empty_file";
-  FILES_COUNT_EXCEEDED: "files_count_exceeded";
-  FILE_SIZE_EXCEEDED: "file_size_exceeded";
-  UNSUPPORTED_FILE_FORMAT: "unsupported_file_format";
-}>;
+//#region src/hono/hono.execution.d.ts
+/**
+ * Creates a Hono error handler that preserves expected machine-readable exceptions.
+ * Unexpected failures invoke application reporting before returning a stable fallback.
+ */
+declare function createHonoErrorHandler(options: HonoErrorHandlerOptions): ErrorHandler;
 //#endregion
-//#region src/upload/upload.types.d.ts
-type FileFormatConfig = (typeof fileFormatsConfig)[FileFormat];
+//#region src/hono/hono.logging.d.ts
 /**
- * Shared upload policy consumed by browser controls and backend validation.
- * One preset keeps format, size, capacity, and fallback rules synchronized.
+ * Creates Hono middleware with configurable body capture, correlation, and output.
+ * Sensitive values are redacted before the completed request line reaches its writer.
  */
-type UploadPreset<TFormats extends readonly FileFormat[] = readonly FileFormat[]> = Readonly<{
-  /**
-   * Supported formats accepted by every consumer of the preset.
-   * Const inference preserves the supplied format tuple without widening.
-   */
-  formats: TFormats;
-  /**
-   * Maximum accepted size of one uploaded file measured in bytes.
-   * Schema and client validation can share this exact numeric boundary.
-   */
-  maxFileSize: number;
-  /**
-   * Optional maximum number of files retained by one upload collection.
-   * Single-file controls can set this value to `1` for shared capacity rules.
-   */
-  maxFilesCount?: number;
-  /**
-   * Allows extensions to compensate for absent or unreliable MIME metadata.
-   * The fallback remains disabled when this option is omitted.
-   */
-  extensionFallback?: boolean;
-}>;
+declare function createLoggingMiddleware(options?: HonoLoggingMiddlewareOptions): MiddlewareHandler;
 /**
- * Constraints used to validate an incoming collection of browser files.
- * Existing and incoming counts are combined when enforcing capacity.
+ * Ready-to-use Hono request logger backed by the shared default logging policy.
+ * Applications may use the factory when request capture or output needs configuration.
  */
-type UploadFilesValidationOptions = Readonly<{
-  /**
-   * Number of files already retained before the incoming batch is validated.
-   * Existing entries reduce the remaining capacity without being revalidated.
-   */
-  currentFilesCount: number;
-  /**
-   * Supported formats used to validate every file in the incoming batch.
-   * MIME and extension metadata are resolved through the canonical catalog.
-   */
-  formats: readonly FileFormat[];
+declare const loggingMiddleware: MiddlewareHandler;
+//#endregion
+//#region src/hono/hono.request-id.d.ts
+/**
+ * Resolves a request identifier from response metadata before its incoming header.
+ * This ordering exposes identifiers generated by the request middleware downstream.
+ */
+declare function getHonoRequestId(context: Context, header?: string): string | undefined;
+/**
+ * Creates middleware that preserves or generates one request correlation identifier.
+ * The resolved value is returned on the response and remains available to Hono adapters.
+ */
+declare function createRequestIdMiddleware(options?: HonoRequestIdMiddlewareOptions): MiddlewareHandler;
+/**
+ * Ready-to-use request identifier middleware backed by the shared default policy.
+ * Applications may use the factory when a custom header or generator is required.
+ */
+declare const requestIdMiddleware: MiddlewareHandler;
+//#endregion
+//#region src/hono/hono.respond.d.ts
+/**
+ * Wraps `c.json` in the shared success envelope while preserving its literal status.
+ * Missing response data is represented by an empty object for contract consistency.
+ */
+declare function respond<TData extends object = Record<string, never>, TStatus extends SuccessResponseStatus = SuccessResponseStatus>(c: Context, options: HonoRespondOptions<TData, TStatus>): Response & TypedResponse<SuccessResponse<TData>, TStatus, 'json'>;
+/**
+ * Responds with downloadable binary content and its attachment headers.
+ * Unknown/undefined content types default to `application/octet-stream`.
+ */
+declare function fileRespond<TStatus extends SuccessResponseStatus>(c: Context, options: HonoFileRespondOptions<TStatus>): Response;
+//#endregion
+//#region src/jwt/jwt.constants.d.ts
+/**
+ * Default symmetric algorithm applied to JWT signing and verification operations.
+ * The policy uses `HS256` unless a service instance explicitly selects another value.
+ */
+declare const DEFAULT_JWT_ALGORITHM: SymmetricAlgorithm;
+/**
+ * Default token lifetime applied when a signing operation supplies no override.
+ * The duration is expressed in seconds and represents exactly fifteen minutes.
+ */
+declare const DEFAULT_JWT_EXPIRATION_SECONDS: number;
+//#endregion
+//#region src/jwt/jwt.errors.d.ts
+declare const jwtErrors: {
+  invalidExpirationSeconds: () => RangeError;
+};
+type JWTErrorCode = keyof typeof jwtErrors;
+//#endregion
+//#region src/jwt/jwt.types.d.ts
+/**
+ * Configures the algorithm and default expiration used by `JWTService`.
+ * Omitted values fall back to `HS256` and fifteen minutes respectively.
+ */
+type JWTServiceOptions = {
   /**
-   * Maximum accepted size of one uploaded file measured in bytes.
-   * Files exceeding this boundary receive the stable size error key.
+   * Symmetric algorithm used to sign and verify every token handled by the service.
+   * Defaults to `HS256` when the configuration does not provide another value.
    */
-  maxFileSize: number;
+  algorithm?: SymmetricAlgorithm;
   /**
-   * Optional maximum number of retained files after accepting the batch.
-   * Omitting this value leaves collection capacity unrestricted.
+   * Default lifetime assigned to signed tokens, expressed in whole seconds.
+   * Negative values intentionally create tokens that are already expired.
    */
-  maxFilesCount?: number;
-}>;
+  defaultExpirationSeconds?: number;
+};
 /**
- * Accepted files and the final rejection encountered in one batch.
- * Valid entries remain available when another entry fails validation.
+ * Configures one JWT signing operation without changing service defaults.
+ * A supplied expiration takes precedence over `defaultExpirationSeconds`.
  */
-type UploadFilesValidationResult = Readonly<{
-  /**
-   * Valid incoming files that fit the remaining collection capacity.
-   * Accepted file objects preserve their original identity and ordering.
-   */
-  acceptedFiles: File[];
+type JWTSignOptions = {
   /**
-   * Final stable rejection encountered while processing the incoming batch.
-   * The field remains absent when every supplied file is accepted.
+   * Lifetime assigned to the token created by this signing operation.
+   * The value overrides the service default and uses whole seconds.
    */
-  validationError?: UploadValidationError;
-}>;
+  expiresInSeconds?: number;
+};
 /**
- * Options used to construct one reusable Zod file schema.
- * Extension fallback is disabled by default to preserve strict MIME checks.
+ * Parses an untrusted JWT payload into the payload returned by `JWTService`.
+ * Zod transformations and asynchronous refinements remain part of the contract.
  */
-type ZodUploadFileSchemaOptions = Readonly<{
+type JWTPayloadSchema<TPayload extends JWTPayload> = z.ZodType<TPayload>;
+//#endregion
+//#region src/jwt/jwt.services.d.ts
+/**
+ * Signs, decodes, and verifies JWTs with optional payload schema validation.
+ * A supplied schema parses payloads returned by decoding and verification.
+ */
+declare class JWTService<TPayload extends JWTPayload$1 = JWTPayload$1> {
+  readonly payloadSchema: JWTPayloadSchema<TPayload> | undefined;
+  protected readonly algorithm: SymmetricAlgorithm;
+  protected readonly defaultExpirationSeconds: number;
+  constructor(payloadSchema?: JWTPayloadSchema<TPayload>, options?: JWTServiceOptions);
   /**
-   * Supported formats accepted by the generated file schema.
-   * Strict MIME validation uses metadata from the canonical format catalog.
+   * Signs a payload using the configured algorithm and expiration settings.
+   * Per-operation expiration overrides the default configured by the service.
+   *
+   * @example
+   * const token = await jwtService.sign({ userId: '123' }, secret, { expiresInSeconds: 300 });
    */
-  formats: readonly FileFormat[];
+  sign(payload: TPayload, secret: string, options?: JWTSignOptions): Promise<string>;
   /**
-   * Maximum accepted file size measured in bytes for the generated file schema.
-   * Empty files remain invalid independently of this configured boundary.
+   * Decodes a token without authentication and parses its payload when configured.
+   * Schema failures return `null`, while malformed token failures remain unchanged.
+   *
+   * @example
+   * const payload = await jwtService.decode(token);
    */
-  maxFileSize: number;
+  decode(token: string): Promise<TPayload | null>;
   /**
-   * Allows a supported extension to compensate for missing MIME metadata.
-   * The fallback remains disabled by default to preserve strict validation.
+   * Verifies a token using the configured algorithm and parses its payload.
+   * Authentication, expiration, and schema failures reject the operation.
+   *
+   * @example
+   * const payload = await jwtService.verifyOrThrow(token, secret);
    */
-  extensionFallback?: boolean;
-}>;
+  verifyOrThrow(token: string, secret: string): Promise<TPayload>;
+}
 //#endregion
-//#region src/upload/upload.factory.d.ts
+//#region src/jwt/jwt.validation.d.ts
 /**
- * Defines one shared upload policy while preserving its literal format tuple.
- * The resulting preset can drive schemas, picker hints, and batch validation.
- *
- * @example
- * const imageUploadPreset = defineUploadPreset({
- *   formats: [fileFormat.JPG, fileFormat.PNG, fileFormat.WEBP],
- *   maxFileSize: 8 * 1024 * 1024,
- *   maxFilesCount: 1,
- * });
+ * Validates a JWT lifetime before it participates in expiration calculation.
+ * Whole positive, zero, and negative seconds are accepted within the safe range.
  */
-declare function defineUploadPreset<const TFormats extends readonly FileFormat[]>(preset: UploadPreset<TFormats>): UploadPreset<TFormats>;
+declare function validateJWTExpirationSeconds(expirationSeconds: number): void;
 //#endregion
-//#region src/upload/upload.presets.d.ts
+//#region src/logging/logging.constants.d.ts
 /**
- * Default maximum size of one file accepted by the built-in upload presets.
- * The 20 MiB boundary matches the existing upload component policy.
+ * Terminal color configuration for every supported logging level.
+ * The `LogLevel` contract prevents missing or unsupported level entries.
  */
-declare const DEFAULT_UPLOAD_MAX_FILE_SIZE: number;
+declare const logLevelColors: {
+  readonly info: typeof import("kleur/colors").print;
+  readonly warn: typeof import("kleur/colors").print;
+  readonly error: typeof import("kleur/colors").print;
+};
 /**
- * Ready-to-use policy for every image format supported by the upload catalog.
- * Each image may occupy up to 20 MiB while collection capacity remains unrestricted.
+ * Public placeholder written instead of sensitive query and JSON values.
+ * One stable marker keeps redacted output recognizable across log consumers.
  */
-declare const imageUploadPreset: Readonly<{
-  formats: readonly ["png", "jpg", "webp", "avif", "heic"];
-  maxFileSize: number;
-  maxFilesCount?: number;
-  extensionFallback?: boolean;
-}>;
+declare const REDACTED_LOG_VALUE = "[redacted]";
 /**
- * Ready-to-use policy for every image format supporting transparency (alpha channel).
- * Each image may occupy up to 20 MiB while collection capacity remains unrestricted.
+ * Number of characters retained from each edge of an oversized request body.
+ * The complete preview includes both edges separated by one explicit ellipsis.
  */
-declare const imageTransparentUploadPreset: Readonly<{
-  formats: readonly ["png", "webp", "svg"];
-  maxFileSize: number;
-  maxFilesCount?: number;
-  extensionFallback?: boolean;
-}>;
+declare const LOG_BODY_PREVIEW_EDGE_LENGTH = 30;
 /**
- * Ready-to-use policy for every document format supported by the upload catalog.
- * Each document may occupy up to 20 MiB while collection capacity remains unrestricted.
+ * Safe request-body placeholder emitted instead of reading multipart content.
+ * Avoiding multipart reads prevents file payloads from entering logs or memory copies.
  */
-declare const documentUploadPreset: Readonly<{
-  formats: readonly ["pdf", "rtf", "txt"];
-  maxFileSize: number;
-  maxFilesCount?: number;
-  extensionFallback?: boolean;
-}>;
-//#endregion
-//#region src/upload/upload.schemas.d.ts
+declare const MULTIPART_LOG_BODY = "[multipart]";
 /**
- * Builds a reusable Zod schema for one uploaded file with format and size.
- * MIME matching is strict unless extension fallback is explicitly enabled.
+ * Normalized key fragments treated as sensitive by logging redaction.
+ * Matching ignores case and separators so compound field names remain covered.
  */
-declare function zodUploadFileSchema(options: ZodUploadFileSchemaOptions): z$1.ZodFile;
+declare const sensitiveLogKeyParts: readonly ['password', 'passwd', 'token', 'secret', 'authorization', 'apikey', 'credential'];
+/**
+ * Terminal colors assigned to the supported HTTP response status ranges.
+ * Unlisted ranges intentionally retain the terminal's default text appearance.
+ */
+declare const httpStatusColors: readonly [{
+  readonly range: readonly [200, 299];
+  readonly color: typeof import("kleur/colors").print;
+}, {
+  readonly range: readonly [400, 499];
+  readonly color: typeof import("kleur/colors").print;
+}, {
+  readonly range: readonly [500, 599];
+  readonly color: typeof import("kleur/colors").print;
+}];
 //#endregion
-//#region src/upload/upload.utilities.d.ts
+//#region src/logging/logging.enums.d.ts
+declare const logLevelsArray: readonly ['info', 'warn', 'error'];
+type LogLevel = (typeof logLevelsArray)[number];
+declare const logLevelsRecord: Readonly<{
+  ERROR: "error";
+  INFO: "info";
+  WARN: "warn";
+}>;
+declare const logLevel: Readonly<{
+  ERROR: "error";
+  INFO: "info";
+  WARN: "warn";
+}>;
+//#endregion
+//#region src/logging/logging.errors.d.ts
+declare const loggingErrors: {
+  invalidBodyPreviewEdgeLength: () => RangeError;
+};
+type LoggingErrorCode = keyof typeof loggingErrors;
+//#endregion
+//#region src/logging/logging.security.d.ts
 /**
- * Extracts a normalized trailing extension from a complete file name.
- * Returns an empty string when no valid dot-delimited suffix exists.
+ * Recursively replaces values owned by sensitive keys in an arbitrary structure.
+ * Arrays and safe values retain their original ordering and primitive identity.
  */
-declare function getFileExtension(fileName: string): string;
+declare function redactSensitiveValue(value: unknown): unknown;
 /**
- * Normalizes a configured extension to a lowercase dot-prefixed value.
- * Existing prefixes remain intact so repeated normalization is stable.
+ * Replaces sensitive query values using partial, case-insensitive key matching.
+ * A new collection is returned so the caller's search parameters remain unchanged.
  */
-declare function normalizeFileExtension(extension: string): string;
+declare function redactSensitiveSearchParams(searchParams: URLSearchParams): URLSearchParams;
 /**
- * Compares a concrete MIME type with an exact or wildcard configuration.
- * Wildcards match every subtype belonging to the configured media group.
+ * Replaces values under sensitive keys throughout a serialized JSON structure.
+ * Invalid JSON and payloads without matching keys are returned byte-for-byte unchanged.
  */
-declare function matchesMimeType(fileMimeType: string, configuredMimeType: string): boolean;
+declare function redactSensitiveJSON(json: string): string;
+//#endregion
+//#region src/logging/logging.types.d.ts
 /**
- * Checks whether a file MIME type belongs to one selected format.
- * File names and extensions cannot make an unsupported MIME type valid.
+ * Receives one completely formatted logging line for final output or collection.
+ * Implementations control the destination without changing formatting behavior.
  */
-declare function isFileMimeTypeSupported(file: File, formats: readonly FileFormat[]): boolean;
+type LogSink = (line: string) => void;
 /**
- * Checks whether a file extension belongs to one selected format.
- * The comparison is case-insensitive and requires a complete suffix.
+ * Logger bound to one service label and one configured output destination.
+ * Every method preserves the shared timestamp, level, and trace formatting.
  */
-declare function isFileExtensionSupported(file: File, formats: readonly FileFormat[]): boolean;
+type ScopedLogger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string, error?: unknown) => void;
+};
 /**
- * Checks whether a file matches one configured MIME type or extension.
- * This permissive predicate supports clients where MIME metadata is absent.
+ * Options used to bind a logger to one service and output destination.
+ * The default sink writes every fully formatted line through `console.log`.
  */
-declare function isFileFormatSupported(file: File, formats: readonly FileFormat[]): boolean;
+type CreateLoggerOptions = {
+  /**
+   * Stable service label displayed beside every message from the logger.
+   * Short labels retain the shared terminal column alignment automatically.
+   */
+  service: string;
+  /**
+   * Optional destination receiving each completely formatted output line.
+   * Omission preserves the standard console-backed logging behavior.
+   */
+  sink?: LogSink;
+};
 /**
- * Builds a native file-picker hint from configured MIME types and extensions.
- * Duplicate values are removed while their configuration order is retained.
+ * Structured values required to format one completed HTTP request log entry.
+ * Optional query and body previews disappear when their normalized values are empty.
  */
-declare function createUploadAccept(formats: readonly FileFormat[]): string;
+type HTTPRequestLogOptions = {
+  /**
+   * HTTP method associated with the completed request.
+   * Formatting reserves a stable terminal column for its value.
+   */
+  method: string;
+  /**
+   * Final HTTP status observed after downstream request handling.
+   * Its numeric range determines the terminal color applied to the value.
+   */
+  status: number;
+  /**
+   * Completed request-processing duration expressed in milliseconds.
+   * Formatting expects the value to be rounded before it reaches this boundary.
+   */
+  duration: number;
+  /**
+   * Request pathname displayed without serialized query parameters.
+   * Formatting reserves a stable terminal column for its value.
+   */
+  path: string;
+  /**
+   * Optional redacted query representation without the leading question mark.
+   * Empty and omitted values do not produce a suffix in the formatted line.
+   */
+  searchParams?: string;
+  /**
+   * Optional normalized, redacted, and length-limited request body preview.
+   * Empty and omitted values do not produce a suffix in the formatted line.
+   */
+  bodyPreview?: string;
+  /**
+   * Optional identifier correlating this request with downstream logs and reports.
+   * Empty and omitted values do not produce a suffix in the formatted line.
+   */
+  requestId?: string;
+};
 //#endregion
-//#region src/upload/upload.validation.d.ts
+//#region src/logging/logging.services.d.ts
 /**
- * Validates one file against configured format and size constraints.
- * Returns the first stable error key or nothing for a valid file.
+ * Creates a logger permanently bound to one service label and output destination.
+ * Calls retain the shared formatting while avoiding repeated service arguments.
  */
-declare function validateUploadFile(file: File, formats: readonly FileFormat[], maxFileSize: number): UploadValidationError | undefined;
+declare function createLogger(options: CreateLoggerOptions): ScopedLogger;
 /**
- * Validates an incoming collection while preserving every accepted file.
- * Returns accepted entries and the final rejection key from the batch.
+ * Writes timestamped and colorized messages using a stable service column.
+ * Error messages may include a stack trace on a subordinate second line.
  */
-declare function validateUploadFiles(incomingFiles: readonly File[], options: UploadFilesValidationOptions): UploadFilesValidationResult;
+declare const log: {
+  /**
+   * Writes an informational message with an optional service label.
+   * Missing service names use the shared `log` fallback label.
+   */
+  info(message: string, service?: string): void;
+  /**
+   * Writes a warning message with an optional service label.
+   * Missing service names use the shared `log` fallback label.
+   */
+  warn(message: string, service?: string): void;
+  /**
+   * Writes an error message with optional service and unknown failure context.
+   * Native errors and strings render a normalized subordinate trace line.
+   */
+  error(message: string, service?: string, error?: unknown): void;
+};
 //#endregion
-//#region src/utilities/datetime.utilities.d.ts
+//#region src/logging/logging.utilities.d.ts
 /**
- * Projects the current instant onto the wall-clock fields of another timezone.
- * The timezone defaults to `Europe/London` when no option is provided.
- *
- * @example
- * const londonTime = getZonedTime({ tz: 'Europe/London' });
+ * Extracts useful trace context from an unknown failure without inventing a message.
+ * Strings pass through directly, while native errors prefer their complete stack.
  */
-declare function getZonedTime({ tz }?: {
-  tz?: string;
-}): Date;
+declare function normalizeLogError(error: unknown): string | undefined;
 /**
- * Formats the UTC offset of a timezone at the supplied date.
- * An explicit date preserves daylight-saving and historical offset rules.
- *
- * @example
- * getUTCOffset(date, 'Europe/Moscow'); // `(+3 UTC)`
+ * Selects a terminal color function for one HTTP response status.
+ * Successes are green, client errors yellow, and server errors red.
  */
-declare function getUTCOffset(date: Date, tz: string): string;
+declare function getColoredHTTPStatus(status: number): (text: string) => string;
 /**
- * Formats the current time and UTC offset in the selected timezone.
- * The timezone defaults to `Europe/London` when no option is provided.
- *
- * @example
- * getFormattedTime({ tz: 'Europe/Moscow' }); // `03:04:05 (+3 UTC)`
+ * Formats one completed HTTP request as a compact colorized terminal line.
+ * Empty query and body values are omitted without disturbing column alignment.
  */
-declare function getFormattedTime({ tz }?: {
-  tz?: string;
-}): string;
+declare function formatHTTPRequestLog(options: HTTPRequestLogOptions): string;
 /**
- * Formats the current date with optional time and UTC offset components.
- * Time is included by default and uses the selected timezone for display.
- *
- * @example
- * getFormattedDate({ tz: 'UTC', withTime: false }); // `02.01.2024`
+ * Reads one request clone and returns a normalized, redacted, and bounded body preview.
+ * Multipart requests return a safe marker without reading or retaining uploaded content.
  */
-declare function getFormattedDate({ tz, withTime }?: {
-  tz?: string;
-  withTime?: boolean;
-}): string;
+declare function createHTTPRequestBodyPreview(request: Request, contentType?: string, edgeLength?: number): Promise<string>;
+//#endregion
+//#region src/object/object.utilities.d.ts
 /**
- * Formats an explicit instant in another timezone using the selected locale.
- * The result includes localized date text, wall-clock time, and UTC offset.
+ * Recognizes ordinary records whose direct prototype is `Object.prototype`.
+ * Arrays, null, native objects, and custom class instances remain excluded.
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+//#endregion
+//#region src/random/random.errors.d.ts
+declare const randomErrors: {
+  invalidRandomStringLength: () => RangeError;
+};
+type RandomErrorCode = keyof typeof randomErrors;
+//#endregion
+//#region src/random/random.utilities.d.ts
+/**
+ * Creates a cryptographically sourced string from the alphanumeric collection.
+ * Rejection sampling prevents modulo bias while bounded batches support long output.
  *
  * @example
- * formatTime(date, { locale: ru, tz: 'Europe/Moscow' });
+ * generateRandomString(5); // `aZ3fG`
+ * generateRandomString(); // `G5kLm2P9sQ`
  */
-declare function formatTime(time: Date, { locale, tz }?: {
-  locale?: Locale;
-  tz?: string;
-}): string;
+declare function generateRandomString(length?: number): string;
 //#endregion
-//#region src/utilities/encoding.utilities.d.ts
+//#region src/random/random.validation.d.ts
 /**
- * Encodes arbitrary binary bytes into their canonical Base64 representation.
- * Chunked conversion avoids the argument limit imposed by `String.fromCharCode`.
+ * Validates the requested random-string length before allocating random bytes.
+ * Only non-negative safe integers can represent a complete output character count.
  */
-declare function encodeBase64(bytes: Uint8Array): string;
+declare function assertRandomStringLength(length: number): void;
+//#endregion
+//#region src/random/random.constants.d.ts
 /**
- * Decodes a canonical or padded Base64 string into its original binary bytes.
- * Invalid input preserves the native `atob` failure instead of returning partial data.
+ * Alphanumeric character collection used by the default random-string generator.
+ * Its fixed ordering keeps byte-to-character translation stable across runtimes.
  */
-declare function decodeBase64(value: string): Uint8Array<ArrayBuffer>;
+declare const RANDOM_ALPHANUMERIC_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+ * Default output length used when `generateRandomString` receives no override.
+ * Ten characters preserve the historical package contract for existing consumers.
+ */
+declare const DEFAULT_RANDOM_STRING_LENGTH = 10;
+/**
+ * Maximum random-byte count requested from Web Crypto in one operation.
+ * The boundary follows the platform limit enforced by `crypto.getRandomValues`.
+ */
+declare const RANDOM_BYTE_BATCH_SIZE = 65536;
 //#endregion
-//#region src/utilities/enums.utilities.d.ts
+//#region src/string-enum/string-enum.types.d.ts
 /**
  * Recursively replaces dots in a string literal with underscores.
  * Every other character remains unchanged in the resulting literal type.
@@ -691,7 +1018,7 @@ declare function decodeBase64(value: string): Uint8Array<ArrayBuffer>;
  * @example
  * type Key = ReplaceDotsWithUnderscores<'foo.bar.baz'>; // `foo_bar_baz`
  */
-type ReplaceDotsWithUnderscores<TValue extends string> = TValue extends `${infer Head}.${infer Tail}` ? `${ReplaceDotsWithUnderscores<Head>}_${ReplaceDotsWithUnderscores<Tail>}` : TValue;
+type ReplaceDotsWithUnderscores<TValue extends string> = TValue extends `${infer THead}.${infer TTail}` ? `${ReplaceDotsWithUnderscores<THead>}_${ReplaceDotsWithUnderscores<TTail>}` : TValue;
 /**
  * Recursively replaces hyphens in a string literal with underscores.
  * Every other character remains unchanged in the resulting literal type.
@@ -699,387 +1026,262 @@ type ReplaceDotsWithUnderscores<TValue extends string> = TValue extends `${infer
  * @example
  * type Key = ReplaceHyphensWithUnderscores<'foo-bar-baz'>; // `foo_bar_baz`
  */
-type ReplaceHyphensWithUnderscores<TValue extends string> = TValue extends `${infer Head}-${infer Tail}` ? `${ReplaceHyphensWithUnderscores<Head>}_${ReplaceHyphensWithUnderscores<Tail>}` : TValue;
+type ReplaceHyphensWithUnderscores<TValue extends string> = TValue extends `${infer THead}-${infer TTail}` ? `${ReplaceHyphensWithUnderscores<THead>}_${ReplaceHyphensWithUnderscores<TTail>}` : TValue;
+/**
+ * Inserts underscores at lowercase-to-uppercase boundaries in a string literal.
+ * Existing separators reset boundary tracking while consecutive capitals remain grouped.
+ */
+type SeparateCamelCase<TValue extends string, TPreviousWasLowercase extends boolean = false> = TValue extends `${infer TCharacter}${infer TRest}` ? TCharacter extends '.' | '-' ? `${TCharacter}${SeparateCamelCase<TRest>}` : TCharacter extends Lowercase<TCharacter> ? `${TCharacter}${SeparateCamelCase<TRest, true>}` : TPreviousWasLowercase extends true ? `_${TCharacter}${SeparateCamelCase<TRest>}` : `${TCharacter}${SeparateCamelCase<TRest>}` : TValue;
+/**
+ * Converts one supported string literal into its uppercase enum-record key.
+ * CamelCase boundaries, dots, and hyphens consistently become underscores.
+ */
+type StringEnumKey<TValue extends string> = Uppercase<ReplaceHyphensWithUnderscores<ReplaceDotsWithUnderscores<SeparateCamelCase<TValue>>>>;
 /**
- * Maps string literals to immutable uppercase enum-like keys.
- * Dots and hyphens become underscores while values preserve their original literals.
+ * Maps a readonly string-literal collection into an immutable enum-like record.
+ * Normalized uppercase keys retain their original source literals as record values.
  *
  * @example
  * type Statuses = StringEnumRecord<readonly ['review.pending', 'published']>;
  */
-type StringEnumRecord<TValues extends readonly string[]> = Readonly<{ [Value in TValues[number] as Uppercase<ReplaceHyphensWithUnderscores<ReplaceDotsWithUnderscores<Value>>>]: Value; }>;
+type StringEnumRecord<TValues extends readonly string[]> = Readonly<{ [TValue in TValues[number] as StringEnumKey<TValue>]: TValue; }>;
+//#endregion
+//#region src/string-enum/string-enum.utilities.d.ts
 /**
  * Creates an immutable enum-like record from a readonly string array.
- * Keys are uppercased and every dot or hyphen is replaced with an underscore.
+ * Keys become upper snake case across camelCase, dotted, and hyphenated values.
  *
  * @example
  * createStringEnumRecord(['foo-bar.s', 'baz'] as const); // `{ FOO_BAR_S: 'foo-bar.s', BAZ: 'baz' }`
  */
-declare function createStringEnumRecord<const T extends readonly string[]>(values: T): StringEnumRecord<T>;
+declare function createStringEnumRecord<const TValues extends readonly string[]>(values: TValues): StringEnumRecord<TValues>;
 //#endregion
-//#region src/utilities/execution.utilities.d.ts
+//#region src/type/type.utilities.d.ts
 /**
- * Resolves synchronous and asynchronous executions through one promise-based contract.
- * Failures use the supplied fallback or propagate unchanged when none is available.
+ * Flattens an intersection or mapped type into one readable object shape.
+ * Property modifiers remain unchanged while editor output becomes easier to inspect.
  *
  * @example
- * await safeExecute(() => fetchData(), (error) => console.error(error));
+ * type User = Simplify<{ id: string } & { email: string }>;
  */
-declare function safeExecute<T, E = never>(fn: () => Promise<T> | T, onError?: (error: unknown) => E | Promise<E>): Promise<T | E>;
-/**
- * Result returned after measuring one successful asynchronous execution.
- * The original value is preserved beside its rounded millisecond duration.
- */
-type MeasuredExecution<T> = {
-  /**
-   * Value resolved by the measured execution without cloning or transformation.
-   * Its generic type remains identical to the original asynchronous result.
-   */
-  result: T;
-  /**
-   * Rounded wall-clock duration of the measured execution in milliseconds.
-   * The value is always collected after the supplied promise resolves.
-   */
-  executionTime: number;
-};
+type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey]; } & {};
 /**
- * Measures an asynchronous execution while preserving its resolved result.
- * Rejected executions propagate unchanged and do not produce a measurement.
+ * Builds a union whose branches retain one selected property and forbid every other selected key.
+ * Each flattened branch preserves the selected property's original value type and optionality.
  *
  * @example
- * const { result, executionTime } = await measureExecutionTime(async () => {
- *    return await fetchData();
- * });
- * console.log(`Execution time: ${executionTime}ms`);
+ * type UserSelector = ExactlyOne<{ id: string; email: string }, 'id' | 'email'>;
  */
-declare function measureExecutionTime<T>(execution: () => Promise<T>): Promise<MeasuredExecution<T>>;
-//#endregion
-//#region src/utilities/generation.utilities.d.ts
+type ExactlyOne<TEntity, TKeys extends keyof TEntity> = { [TKey in TKeys]: Simplify<Pick<TEntity, TKey> & Partial<Record<Exclude<TKeys, TKey>, never>>>; }[TKeys];
 /**
- * Creates a cryptographically sourced string from the alphanumeric set.
- * Requested length defaults to `10` characters when omitted.
+ * Builds a union whose branches require one selected property while preserving every remaining property.
+ * Additional selected properties may coexist, but at least one must hold its concrete declared value.
  *
  * @example
- * generateRandomString(5); // `aZ3fG`
- * generateRandomString(); // `G5kLm2P9sQ`
+ * type UserPatch = AtLeastOne<{ email?: string; fullName?: string }>;
  */
-declare function generateRandomString(length?: number): string;
+type AtLeastOne<TEntity, TKeys extends keyof TEntity = keyof TEntity> = TKeys extends keyof TEntity ? Simplify<Required<Pick<TEntity, TKeys>> & Partial<Omit<TEntity, TKeys>>> : never;
 //#endregion
-//#region src/utilities/type.utilities.d.ts
-/**
- * Utility type that simplifies a given type T by flattening its structure.
- * This is particularly useful for improving the readability of complex types.
- */
-type Simplify<T> = { [K in keyof T]: T[K]; } & {};
+//#region src/upload/upload.enums.d.ts
+declare const uploadValidationErrorsArray: readonly ['emptyFile', 'unsupportedFileFormat', 'fileSizeExceeded', 'filesCountExceeded'];
+type UploadValidationError = (typeof uploadValidationErrorsArray)[number];
+declare const uploadValidationErrorsRecord: Readonly<{
+  EMPTY_FILE: "emptyFile";
+  FILES_COUNT_EXCEEDED: "filesCountExceeded";
+  FILE_SIZE_EXCEEDED: "fileSizeExceeded";
+  UNSUPPORTED_FILE_FORMAT: "unsupportedFileFormat";
+}>;
+declare const uploadValidationError: Readonly<{
+  EMPTY_FILE: "emptyFile";
+  FILES_COUNT_EXCEEDED: "filesCountExceeded";
+  FILE_SIZE_EXCEEDED: "fileSizeExceeded";
+  UNSUPPORTED_FILE_FORMAT: "unsupportedFileFormat";
+}>;
+//#endregion
+//#region src/upload/upload.errors.d.ts
+declare const uploadErrors: {
+  uploadFormatRequired: () => TypeError;
+  invalidMimeType: () => TypeError;
+  invalidFileExtension: () => TypeError;
+  invalidMaxFileSize: () => RangeError;
+  invalidMaxFilesCount: () => RangeError;
+  invalidCurrentFilesCount: () => RangeError;
+};
+type UploadErrorCode = keyof typeof uploadErrors;
 //#endregion
-//#region src/zod-bulk/zod-bulk.schemas.d.ts
+//#region src/upload/upload.types.d.ts
 /**
- * Builds a strict selection contract for bulk operations across paginated data.
- * The identifier schema is shared by explicit and all-matching selection modes.
- *
- * `include` targets only identifiers listed by the client. `exclude` targets every
- * item matching the accompanying search snapshot except excluded identifiers.
- *
- * @example
- * const assetBulkSelectionSchema = zodBulkSelectionSchema({
- *   identifierSchema: z.string().min(1),
- * });
+ * Transport metadata describing one file format accepted by an upload policy.
+ * MIME types and extension collections remain application-owned literal values.
  */
-declare function zodBulkSelectionSchema<const TIdentifierSchema extends z$1.ZodType<string | number>>({ identifierSchema }: {
+type UploadFormat = Readonly<{
   /**
-   * Schema used to validate every included or excluded entity identifier.
-   * Its transforms and exact inferred output are preserved in both branches.
+   * MIME types accepted for files belonging to this format.
+   * Exact values and complete media wildcards such as `image/*` are supported.
    */
-  identifierSchema: TIdentifierSchema;
-}): z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
-  mode: z$1.ZodLiteral<"include">;
-  identifiers: z$1.ZodArray<TIdentifierSchema>;
-}, z$1.core.$strict>, z$1.ZodObject<{
-  mode: z$1.ZodLiteral<"exclude">;
-  excludedIdentifiers: z$1.ZodArray<TIdentifierSchema>;
-}, z$1.core.$strict>], "mode">;
-//#endregion
-//#region src/zod-bulk/zod-bulk.types.d.ts
-/**
- * Shared bulk-selection payload produced by `zodBulkSelectionSchema`.
- * String identifiers are used by default for frontend table integrations.
- */
-type ZodBulkSelection<TIdentifier extends string | number = string> = z.infer<ReturnType<typeof zodBulkSelectionSchema<z.ZodType<TIdentifier>>>>;
-/**
- * Explicit bulk selection containing only identifiers chosen by the client.
- * This branch does not require resolving an all-matching search snapshot.
- */
-type ZodBulkIncludeSelection<TIdentifier extends string | number = string> = Extract<ZodBulkSelection<TIdentifier>, {
-  mode: 'include';
+  mimeTypes: readonly string[];
+  /**
+   * File extensions accepted when an upload policy enables extension fallback.
+   * Values may include or omit their dot prefix and are matched case-insensitively.
+   */
+  extensions: readonly string[];
 }>;
 /**
- * All-matching bulk selection containing identifiers excluded by the client.
- * Backend handlers must resolve targets from the same search snapshot.
+ * Format matching policy shared by predicates and complete file validation.
+ * Extension fallback remains disabled so MIME metadata is authoritative by default.
  */
-type ZodBulkExcludeSelection<TIdentifier extends string | number = string> = Extract<ZodBulkSelection<TIdentifier>, {
-  mode: 'exclude';
-}>;
-//#endregion
-//#region src/zod-jwt/zod-jwt.types.d.ts
-/**
- * Configures the algorithm and default expiration used by `ZodJWTService`.
- * Omitted values fall back to `HS256` and fifteen minutes respectively.
- */
-type JWTServiceOptions = {
+type UploadFormatValidationOptions<TFormats extends readonly UploadFormat[] = readonly UploadFormat[]> = Readonly<{
   /**
-   * Symmetric algorithm used to sign and verify every token handled by the service.
-   * Defaults to `HS256` when the configuration does not provide another value.
+   * Format definitions accepted by this validation boundary.
+   * Literal tuples remain available to consumers that define narrower policies.
    */
-  algorithm?: SymmetricAlgorithm;
+  formats: TFormats;
   /**
-   * Default lifetime assigned to signed tokens, expressed in seconds.
-   * Defaults to `900` seconds, which is equivalent to fifteen minutes.
+   * Allows extensions to compensate for absent or unreliable MIME metadata.
+   * Omission preserves strict MIME validation across every adapter.
    */
-  defaultExpirationSeconds?: number;
-};
+  extensionFallback?: boolean;
+}>;
 /**
- * Configures one JWT signing operation without changing service defaults.
- * A supplied expiration takes precedence over `defaultExpirationSeconds`.
+ * Constraints used to validate one browser file independently of collection capacity.
+ * Empty files remain invalid independently of the configured maximum size boundary.
  */
-type JWTSignOptions = {
+type UploadFileValidationOptions<TFormats extends readonly UploadFormat[] = readonly UploadFormat[]> = Simplify<UploadFormatValidationOptions<TFormats> & Readonly<{
   /**
-   * Lifetime assigned to the token created by this signing operation.
-   * Overrides the service default and remains expressed in seconds.
+   * Maximum accepted size of one uploaded file measured in bytes.
+   * The boundary must be a non-negative integer number of bytes.
    */
-  expiresInSeconds?: number;
-};
-/**
- * Resolves the parsed payload of a Zod schema or preserves a direct payload type.
- * Schema transforms are reflected in the resulting inferred payload.
- */
-type Payload<T> = T extends z.ZodType ? z.infer<T> : T;
+  maxFileSize: number;
+}>>;
 /**
- * Preserves a Zod payload schema and rejects direct payload types with `never`.
- * The result controls whether runtime payload validation is available.
+ * Shared upload policy consumed by browser controls and backend validation.
+ * One preset keeps format, size, capacity, and fallback rules synchronized.
  */
-type PayloadSchema<T> = T extends z.ZodType ? T : never;
-//#endregion
-//#region src/zod-jwt/zod-jwt.services.d.ts
+type UploadPreset<TFormats extends readonly UploadFormat[] = readonly UploadFormat[]> = Simplify<UploadFileValidationOptions<TFormats> & Readonly<{
+  /**
+   * Optional maximum number of files retained by one upload collection.
+   * Single-file controls can set this value to `1` for shared capacity rules.
+   */
+  maxFilesCount?: number;
+}>>;
 /**
- * Signs, decodes, and verifies JWTs with optional Zod payload validation.
- * A supplied schema parses payloads returned by decoding and verification.
+ * Constraints used to validate an incoming collection of browser files.
+ * Existing and incoming counts are combined when enforcing capacity.
  */
-declare class ZodJWTService<TPayloadOrSchema> {
-  readonly payloadSchema: PayloadSchema<TPayloadOrSchema> | undefined;
-  protected readonly algorithm: SymmetricAlgorithm;
-  protected readonly defaultExpirationSeconds: number;
-  constructor(payloadSchema?: PayloadSchema<TPayloadOrSchema>, options?: JWTServiceOptions);
+type UploadFilesValidationOptions = Simplify<UploadPreset & Readonly<{
   /**
-   * Signs a payload using the configured algorithm and expiration settings.
-   * Per-call expiration overrides the default configured by the service.
-   *
-   * @example
-   * const token = await jwtService.sign({ userId: '123' }, secret, { expiresInSeconds: 300 });
+   * Number of files already retained before the incoming batch is validated.
+   * Existing entries reduce the remaining capacity without being revalidated.
    */
-  sign(payload: Payload<TPayloadOrSchema>, secret: string, options?: JWTSignOptions): Promise<string>;
+  currentFilesCount: number;
+}>>;
+/**
+ * Accepted files and the first rejection encountered in one batch.
+ * Valid entries remain available when another entry fails validation.
+ */
+type UploadFilesValidationResult = Readonly<{
   /**
-   * Decodes without authenticating it and parses its payload when a schema exists.
-   * Schema validation failures return `null`, while malformed tokens still reject.
-   *
-   * @example
-   * const payload = await jwtService.decode(token);
+   * Valid incoming files that fit the remaining collection capacity.
+   * File objects preserve their identity and ordering through a readonly view.
    */
-  decode(token: string): Promise<Payload<TPayloadOrSchema> | null>;
+  acceptedFiles: readonly File[];
   /**
-   * Verifies a token using the configured algorithm and parses its payload.
-   * Signature, expiration, and schema validation failures reject the operation.
-   *
-   * @example
-   * const payload = await jwtService.verifyOrThrow(token, secret);
+   * First stable rejection encountered while processing the incoming batch.
+   * The field remains absent when every supplied file is accepted.
    */
-  verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
-}
+  validationError?: UploadValidationError;
+}>;
 //#endregion
-//#region src/zod-search/zod-search.pagination.schemas.d.ts
+//#region src/upload/upload.factory.d.ts
 /**
- * Validates offset-based pagination shared by search request contracts.
- * Missing fields inside the required object receive predictable defaults.
+ * Validates one upload format before it becomes part of a reusable policy.
+ * Accepts MIME-only and extension-only definitions while rejecting malformed values.
  */
-declare const zodPaginationSchema: z$1.ZodObject<{
-  offset: z$1.ZodDefault<z$1.ZodCoercedNumber<unknown>>;
-  limit: z$1.ZodDefault<z$1.ZodCoercedNumber<unknown>>;
-}, z$1.core.$strip>;
+declare function assertUploadFormat(format: UploadFormat): void;
 /**
- * Exposes pagination fields for composition into other object schemas.
- * The shape stays derived from the schema to prevent contract divergence.
+ * Defines one upload format while preserving its literal MIME and extension tuples.
+ * Applications may enrich the returned object with their own display metadata.
  */
-declare const zodPaginationShape: {
-  offset: z$1.ZodDefault<z$1.ZodCoercedNumber<unknown>>;
-  limit: z$1.ZodDefault<z$1.ZodCoercedNumber<unknown>>;
-};
-//#endregion
-//#region src/zod-search/zod-search.types.d.ts
+declare function defineUploadFormat<const TFormat extends UploadFormat>(format: TFormat): TFormat;
 /**
- * TypeScript output produced after successful pagination validation.
- * Defaulted fields are represented as required numeric properties.
+ * Defines one shared upload policy while preserving its literal format tuple.
+ * The resulting preset can drive schemas, picker hints, and batch validation.
  */
-type ZodPaginationOptions = z.infer<typeof zodPaginationSchema>;
+declare function defineUploadPreset<const TFormats extends readonly UploadFormat[]>(preset: UploadPreset<TFormats>): UploadPreset<TFormats>;
+//#endregion
+//#region src/upload/upload.schemas.d.ts
 /**
- * Feature flags shared by both supported search schema composition modes.
- * Literal values are preserved in the resulting runtime and static shapes.
+ * Builds a reusable Zod schema for one uploaded file with format and size.
+ * MIME matching is strict unless extension fallback is explicitly enabled.
  */
-type ZodSearchFeatureOptions<TQueryEnabled extends boolean, TPaginationEnabled extends boolean> = {
-  /**
-   * Controls whether an optional non-empty `query` field is generated.
-   * The field is enabled when this option is omitted from the call.
-   */
-  queryEnabled?: TQueryEnabled;
-  /**
-   * Controls whether a required `pagination` object is generated.
-   * The field is enabled when this option is omitted from the call.
-   */
-  paginationEnabled?: TPaginationEnabled;
-};
+declare function zodUploadFileSchema(options: UploadFileValidationOptions): z.ZodFile;
+//#endregion
+//#region src/upload/upload.utilities.d.ts
 /**
- * Configuration used to compose a reusable search request schema.
- * Exactly one source must be provided for the resulting `where` field.
- *
- * `filters` is the concise mode that applies partial and non-empty rules.
- * `whereSchema` accepts a fully prepared schema with custom Zod effects.
+ * Extracts a normalized trailing extension from a complete file name.
+ * Returns an empty string when no valid dot-delimited suffix exists.
  */
-type ZodSearchSchemaOptions<TShape extends z.ZodRawShape = never, TWhereSchema extends z.ZodType<Record<string, unknown>> = never, TQueryEnabled extends boolean = true, TPaginationEnabled extends boolean = true> = ZodSearchFeatureOptions<TQueryEnabled, TPaginationEnabled> & ({
-  /**
-   * Object schema whose fields become optional filters inside `where`.
-   * The factory requires one defined value whenever `where` is present.
-   */
-  filters: z.ZodObject<TShape>;
-  /** Prevents combining automatic filters with a prepared schema. */
-  whereSchema?: never;
-} | {
-  /** Prevents combining a prepared schema with automatic filters. */
-  filters?: never;
-  /**
-   * Prepared schema used directly to validate the `where` object.
-   * Its refinements, transforms, and inferred output are preserved.
-   */
-  whereSchema: TWhereSchema;
-});
-//#endregion
-//#region src/zod-search/zod-search.schemas.d.ts
+declare function getFileExtension(fileName: string): string;
 /**
- * Optional text query shared by search request contracts.
- * Provided values are trimmed and must contain visible text.
+ * Normalizes a configured extension to a lowercase dot-prefixed value.
+ * Existing prefixes remain intact so repeated normalization is stable.
  */
-declare const zodSearchQuerySchema: z$1.ZodOptional<z$1.ZodString>;
+declare function normalizeFileExtension(extension: string): string;
 /**
- * Makes every supplied filter optional while requiring one defined value.
- * Top-level optionality is added later for both composition modes equally.
+ * Compares a concrete MIME type with an exact or wildcard configuration.
+ * Wildcards match every subtype belonging to the configured media group.
  */
-declare const createZodSearchWhereSchema: <TShape extends z$1.ZodRawShape>(filters: z$1.ZodObject<TShape>) => z$1.ZodPipe<z$1.ZodObject<{ -readonly [k in keyof TShape]: z$1.ZodOptional<TShape[k]>; }, z$1.core.$strip>, z$1.ZodTransform<Awaited<AtLeastOne<z$1.core.$InferObjectOutput<{ -readonly [k in keyof TShape]: z$1.ZodOptional<TShape[k]>; }, {}>, keyof z$1.core.$InferObjectOutput<{ -readonly [k in keyof TShape]: z$1.ZodOptional<TShape[k]>; }, {}>>>, z$1.core.$InferObjectOutput<{ -readonly [k in keyof TShape]: z$1.ZodOptional<TShape[k]>; }, {}>>>;
+declare function matchesMimeType(fileMimeType: string, configuredMimeType: string): boolean;
 /**
- * Empty schema shape used when a search feature is explicitly disabled.
- * Intersections remove disabled fields without widening enabled branches.
+ * Checks whether a file MIME type belongs to one selected format.
+ * File names and extensions cannot make an unsupported MIME type valid.
  */
-type ZodDisabledSearchShape = Record<never, never>;
+declare function isFileMimeTypeSupported(file: File, formats: readonly UploadFormat[]): boolean;
 /**
- * Resolves the schema used by `where` from the selected composition mode.
- * Prepared schemas remain untouched, including their effects and output.
+ * Checks whether a file extension belongs to one selected format.
+ * The comparison is case-insensitive and requires a complete suffix.
  */
-type ZodSearchWhereSchema<TShape extends z$1.ZodRawShape, TWhereSchema extends z$1.ZodType<Record<string, unknown>>> = [TWhereSchema] extends [never] ? ReturnType<typeof createZodSearchWhereSchema<TShape>> : TWhereSchema;
+declare function isFileExtensionSupported(file: File, formats: readonly UploadFormat[]): boolean;
 /**
- * Schema-level shape assembled from the selected source and feature flags.
- * Keeping Zod schemas here makes runtime composition the contract source.
+ * Checks whether a file satisfies the format policy selected by one validation boundary.
+ * MIME matching remains strict unless the caller explicitly enables extension fallback.
  */
-type ZodSearchShape<TShape extends z$1.ZodRawShape, TWhereSchema extends z$1.ZodType<Record<string, unknown>>, TQueryEnabled extends boolean, TPaginationEnabled extends boolean> = {
-  where: z$1.ZodOptional<ZodSearchWhereSchema<TShape, TWhereSchema>>;
-} & (TQueryEnabled extends false ? ZodDisabledSearchShape : {
-  query: typeof zodSearchQuerySchema;
-}) & (TPaginationEnabled extends false ? ZodDisabledSearchShape : {
-  pagination: typeof zodPaginationSchema;
-});
+declare function isFileFormatSupported(file: File, options: UploadFormatValidationOptions): boolean;
 /**
- * Builds a strict schema for reusable search request contracts.
- * The optional `where` object must contain one defined filter.
- *
- * Query is optional and non-empty; pagination is required by default.
- * Literal feature flags update both runtime and inferred static shapes.
- *
- * Pass `filters` for automatic partial and non-empty validation, or use
- * `whereSchema` to preserve a prepared schema with custom Zod effects.
- *
- * @example
- * const assetSearchSchema = zodSearchSchema({
- *   filters: assetSchema.pick({ status: true }),
- * });
- *
- * const refinedAssetSearchSchema = zodSearchSchema({
- *   whereSchema: zodAtLeastOne(assetSchema.pick({ status: true }).partial()),
- * });
+ * Builds a native file-picker hint from configured MIME types and extensions.
+ * Duplicate values are removed while their configuration order is retained.
  */
-declare const zodSearchSchema: <const TShape extends z$1.ZodRawShape = never, const TWhereSchema extends z$1.ZodType<Record<string, unknown>> = never, const TQueryEnabled extends boolean = true, const TPaginationEnabled extends boolean = true>(options: ZodSearchSchemaOptions<TShape, TWhereSchema, TQueryEnabled, TPaginationEnabled>) => z$1.ZodObject<ZodSearchShape<TShape, TWhereSchema, TQueryEnabled, TPaginationEnabled> extends (infer T) ? { -readonly [P in keyof T]: T[P]; } : never, z$1.core.$strict>;
+declare function createUploadAccept(formats: readonly UploadFormat[]): string;
 //#endregion
-//#region src/zod-validation/zod-validation.types.d.ts
-type StringifiablePayloadValue = string | number | boolean | bigint | Date;
+//#region src/upload/upload.validation.d.ts
 /**
- * Recursively transforms payload values to strings while preserving container structure.
- * Nullable and omitted members remain unchanged for transport-layer omission handling.
+ * Validates one file against configured format and size constraints.
+ * Returns the first stable error key or nothing for a valid file.
  */
-type StringifiedPayload<TValue> = TValue extends null | undefined ? TValue : TValue extends StringifiablePayloadValue ? string : TValue extends readonly (infer TItem)[] ? StringifiedPayload<TItem>[] : TValue extends object ? { [TKey in keyof TValue]: StringifiedPayload<TValue[TKey]>; } : string;
+declare function validateUploadFile(file: File, options: UploadFileValidationOptions): UploadValidationError | undefined;
 /**
- * Utility type that ensures at least one property from the specified
- * keys of a given type T is required, while the rest remain optional.
- *
- * This is useful for scenarios where you want to enforce that at least one
- * of several optional (nullable) properties must be provided in an object.
- *
- * @example
- * type Example = AtLeastOne<{ a?: string; b?: number; c?: boolean }>;
- * // Valid: { a: "hello" }, { b: 42 }, { c: true }, { a: "hello", b: 42 }
- * // Invalid: {}, { a: undefined, b: undefined, c: undefined }
+ * Validates an incoming collection while preserving every accepted file.
+ * Returns accepted entries and the first rejection key from the batch.
  */
-type AtLeastOne<T, Keys extends keyof T = keyof T> = Keys extends keyof T ? Simplify<Required<Pick<T, Keys>> & Partial<Omit<T, Keys>>> : never;
+declare function validateUploadFiles(incomingFiles: readonly File[], options: UploadFilesValidationOptions): UploadFilesValidationResult;
 //#endregion
-//#region src/zod-validation/zod-validation.refiners.d.ts
-/**
- * Wraps a partial Zod object schema with:
- * 1. A runtime check ensuring at least one field is non-undefined.
- * 2. A `.transform()` that narrows the output type to `AtLeastOne<T>`,
- *    making it directly assignable to domain `*Select` and `*Update` types without casting.
- *
- * @example
- * zQuery(zodAtLeastOne(userSelectSchema)) // result: UserSelect ✓
- */
-declare const zodAtLeastOne: <T extends ZodObject<ZodRawShape>>(schema: T) => z$1.ZodPipe<T, z$1.ZodTransform<Awaited<AtLeastOne<z$1.TypeOf<T>>>, z$1.TypeOf<T>>>;
+//#region src/zod/zod.errors.d.ts
+declare const zodErrors: {
+  atLeastOneRequired: () => {
+    code: 'custom';
+    message: string;
+  };
+};
+type ZodErrorCode = keyof typeof zodErrors;
 //#endregion
-//#region src/zod-validation/zod-validation.parsing.d.ts
-declare const parseQueryValue: (value: unknown) => unknown;
+//#region src/zod/zod.refiners.d.ts
 /**
- * Preprocesses query-like values before Zod validation.
- *
- * Query parameters are string-based by nature, even when they semantically represent
- * numbers or booleans. This helper converts only clear primitive values, allowing
- * regular schemas like `z.number()` and `z.boolean()` to validate query input directly.
+ * Requires one defined property while preserving the supplied Zod object validation.
+ * The output type reflects semantic presence and retains valid falsy or nullable values.
  *
  * @example
- * const schema = asQuery(z.object({
- *   page: z.number().int().positive(),
- *   isActive: z.boolean(),
- * }));
- *
- * schema.parse({ page: '2', isActive: 'true' });
- * // { page: 2, isActive: true }
- */
-declare const asQuery: <T extends z$1.ZodTypeAny>(schema: T) => z$1.ZodPreprocess<T>;
-/**
- * Recursively converts payload values to strings without changing container structure.
- * Objects and arrays are copied while `null` and `undefined` retain omission semantics.
- *
- * @example
- * stringifyPayloadValues({ page: 2, enabled: true });
- * // { page: '2', enabled: 'true' }
- */
-declare function stringifyPayloadValues<TValue>(value: TValue): StringifiedPayload<TValue>;
-//#endregion
-//#region src/zod-validation/zod-validation.utilities.d.ts
-/**
- * Checks whether a value is a plain record backed by `Object.prototype`.
- * Arrays, null, dates, collections, and custom class instances are rejected.
+ * const patchSchema = zodAtLeastOne(z.object({ name: z.string().optional() }));
  */
-declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+declare function zodAtLeastOne<TSchema extends z.ZodObject<z.ZodRawShape>>(schema: TSchema): z.ZodPipe<TSchema, z.ZodTransform<Awaited<AtLeastOne<z.TypeOf<TSchema>>>, z.TypeOf<TSchema>>>;
 //#endregion
-export { APIContractData, APIContractError, APIContractErrorCode, APIContractResult, APIError, APIRequestError, APISuccess, AtLeastOne, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, ErrorCodeOf, ExceptionStatusCode, FetchResult, FileFormat, FileFormatConfig, HMACAlgorithm, HMACEncoding, HMACInput, HMACService, HMACServiceOptions, HonoFileRespondOptions, HonoRespondOptions, JWTServiceOptions, JWTSignOptions, LogLevel, MeasuredExecution, Payload, PayloadSchema, REDACTED_LOG_VALUE, ReplaceDotsWithUnderscores, ReplaceHyphensWithUnderscores, SUCCESS_STATUS_CODES, Simplify, StringEnumRecord, StringifiedPayload, SuccessStatusCode, UploadFilesValidationOptions, UploadFilesValidationResult, UploadPreset, UploadValidationError, ZodBulkExcludeSelection, ZodBulkIncludeSelection, ZodBulkSelection, ZodJWTService, ZodPaginationOptions, ZodSearchSchemaOptions, ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+export { AtLeastOne, CreateLoggerOptions, DEFAULT_DATETIME_TIMEZONE, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_JWT_ALGORITHM, DEFAULT_JWT_EXPIRATION_SECONDS, DEFAULT_RANDOM_STRING_LENGTH, DEFAULT_RETRY_MAX_ATTEMPTS, DateTimeZoneOptions, DrizzleErrorCode, ERROR_RESPONSE_STATUSES, ErrorCodeOf, ErrorResponse, ErrorResponseStatus, ExactlyOne, ExecuteWithTimeoutOptions, Execution, ExecutionErrorCode, ExecutionResult, FormatTimeOptions, FormattedDateOptions, HMACAlgorithm, HMACEncoding, HMACErrorCode, HMACInput, HMACSecret, HMACService, HMACServiceOptions, HONO_LOGGING_SERVICE, HONO_REQUEST_ID_HEADER, HTTPRequestLogOptions, HonoErrorCode, HonoErrorHandlerOptions, HonoFileRespondOptions, HonoLoggingMiddlewareOptions, HonoRequestIdMiddlewareOptions, HonoRespondOptions, JWTErrorCode, type JWTPayload, JWTPayloadSchema, JWTService, JWTServiceOptions, JWTSignOptions, LOG_BODY_PREVIEW_EDGE_LENGTH, LogLevel, LogSink, LoggingErrorCode, MULTIPART_LOG_BODY, MeasuredExecution, RANDOM_ALPHANUMERIC_CHARACTERS, RANDOM_BYTE_BATCH_SIZE, REDACTED_LOG_VALUE, RandomErrorCode, ReplaceDotsWithUnderscores, ReplaceHyphensWithUnderscores, ResolvedResponse, ResponseData, ResponseError, ResponseErrorCode, ResponseFailure, ResponseFailureCode, ResponseKind, ResponseResult, RetryExecutionContext, RetryExecutionOptions, SQLWhereConditions, SUCCESS_RESPONSE_STATUSES, ScopedLogger, SeparateCamelCase, Simplify, StringEnumKey, StringEnumRecord, SuccessResponse, SuccessResponseStatus, UploadErrorCode, UploadFileValidationOptions, UploadFilesValidationOptions, UploadFilesValidationResult, UploadFormat, UploadFormatValidationOptions, UploadPreset, UploadValidationError, ZodErrorCode, assertRandomStringLength, assertUploadFormat, captureExecution, createErrorResponse, createHTTPRequestBodyPreview, createHonoErrorHandler, createLogger, createLoggingMiddleware, createRequestIdMiddleware, createStringEnumRecord, createSuccessResponse, createUploadAccept, decodeBase64, decodeHMACSignature, defineUploadFormat, defineUploadPreset, drizzleErrors, encodeBase64, encodeHMACSignature, executeWithTimeout, executionErrors, fileRespond, formatHTTPRequestLog, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getHonoRequestId, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, hmacErrors, honoErrors, httpStatusColors, isErrorResponse, isErrorResponseStatus, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, isResponseErrorCode, isSuccessResponse, isSuccessResponseStatus, jwtErrors, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingErrors, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, normalizeLogError, randomErrors, redactSensitiveJSON, redactSensitiveSearchParams, redactSensitiveValue, requestIdMiddleware, resolveResponse, respond, responseErrors, responseKind, responseKindsArray, responseKindsRecord, retryExecution, safeExecute, sensitiveLogKeyParts, sqlWhere, toHMACBytes, unwrapResponse, uploadErrors, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateJWTExpirationSeconds, validateUploadFile, validateUploadFiles, waitForRetry, zodAtLeastOne, zodErrors, zodUploadFileSchema };