@kalutskii/foundation 0.7.8 → 0.7.10

package/dist/index.d.ts

@@ -1,30 +1,27 @@
 import { SQL } from 'drizzle-orm';
 import { ErrorHandler, MiddlewareHandler, Context, TypedResponse } from 'hono';
-import { Locale } from 'date-fns';
 import z$1, { z, ZodObject, ZodRawShape } from 'zod';
+import { Locale } from 'date-fns';
 import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
 
 /**
- * Builds a Drizzle SQL `where` condition from a plain object.
- *
- * Maps each `where` entry to `eq(table[key], value)` and combines them with `and`.
- * Assumes that `where` was already validated and contains only existing table fields.
+ * Builds a Drizzle `WHERE` clause by combining defined object entries with `and`.
+ * Expects the supplied keys to be validated against the table beforehand.
  *
- * ```typescript
+ * @example
  * await db.update(usersTable).set(values).where(sqlWhere(usersTable, { id: 1 })).returning();
- * ```
  */
 declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL;
 
 /**
- * Global error handler for Hono framework. Catches all exceptions thrown in route handlers and middlewares.
- * Distinguishes between expected HTTPExceptions (mapped to their status codes) and unexpected errors (500).
+ * Converts expected `HTTPException` values into shared API error envelopes.
+ * Unexpected failures are logged and represented by a traceable generic response.
  */
 declare const onHandlerError: ErrorHandler;
 
 /**
- * Request logging middleware for Hono, providing deeply detailed logs for each incoming request.
- * Example log output: [12:12:12 (+4 UTC)] hono     | POST 200  123ms /api/v1/users (search=term)
+ * Logs request method, response status, duration, URL details, and a body preview.
+ * Multipart bodies remain unread to avoid buffering uploaded file content into logs.
  */
 declare const honoLoggingHandler: MiddlewareHandler;
 
@@ -33,10 +30,10 @@ declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 50
 
 type SuccessStatusCode = (typeof SUCCESS_STATUS_CODES)[number];
 type ExceptionStatusCode = (typeof EXCEPTION_STATUS_CODES)[number];
-type APISuccess<T = void> = {
+type APISuccess<TData = void> = {
     kind: 'data';
     status: SuccessStatusCode;
-    data: T;
+    data: TData;
 };
 type APIError = {
     kind: 'error';
@@ -46,48 +43,55 @@ type APIError = {
 type APIContractResult<TData = void> = APISuccess<TData> | APIError;
 type APIContractData<TResult extends APIContractResult<unknown>> = TResult extends APISuccess<infer TData> ? TData : never;
 type APIContractError<TResult extends APIContractResult<unknown>> = Extract<TResult, APIError>;
-/**
- * Discriminated union result of a fetch operation.
- * If `error` is set, `data` is null and vice versa.
- */
-type FetchResult<T> = {
+type FetchResult<TData> = {
     error: null;
-    data: T;
+    data: TData;
 } | {
     error: string;
     data: null;
 };
 
 /**
- * Wraps c.json with a typed success payload / (or void data) & possible APIError response.
- * When no data is provided, responds with an empty object {} (purely for type consistency).
+ * 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.
  */
-declare function respond<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: {
-    status: S;
-    data?: T;
-}): Response & TypedResponse<APISuccess<T> | APIError, S, 'json'>;
+type HonoRespondOptions<TData extends object, TStatus extends SuccessStatusCode> = {
+    status: TStatus;
+    data?: TData;
+};
 /**
- * Responds with a file download, setting the appropriate headers for content disposition and type.
- * Supports specifying a filename and optional content type, defaulting to 'application/octet-stream'.
+ * Options for a downloadable binary response with attachment metadata.
+ * The content type remains optional and falls back to a generic binary type.
  */
-declare function fileRespond<S extends SuccessStatusCode>(c: Context, options: {
-    status: S;
+type HonoFileRespondOptions<TStatus extends SuccessStatusCode> = {
+    status: TStatus;
     content: Uint8Array<ArrayBuffer>;
     filename: string;
     contentType?: string;
-}): Response;
+};
 
 /**
- * Factory for creating successful API responses with serializable data.
- * Example usage: `success({ status: 200, data: { message: 'Operation successful' } })`
+ * 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<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: HonoRespondOptions<T, S>): Response & TypedResponse<APISuccess<T> | APIError, S, 'json'>;
+/**
+ * Responds with downloadable binary content and its attachment headers.
+ * Unknown/undefined content types default to `application/octet-stream`.
+ */
+declare function fileRespond<S extends SuccessStatusCode>(c: Context, options: HonoFileRespondOptions<S>): Response;
+
+/**
+ * Creates a successful API envelope without cloning its data.
+ * Generic inference preserves the exact supplied payload type.
  */
 declare function success<T = unknown>({ status, data }: {
     status: SuccessStatusCode;
     data: T;
 }): APISuccess<T>;
 /**
- * Factory for creating API error responses, including the error message.
- * Example usage: `failure({ status: 404, error: 'User not found' })`
+ * Creates a failed API envelope with one supported exception status.
+ * The supplied message remains unchanged for downstream presentation.
  */
 declare function failure({ status, error }: {
     status: ExceptionStatusCode;
@@ -95,132 +99,434 @@ declare function failure({ status, error }: {
 }): APIError;
 
 /**
- * Resolves an APIContractResult fetcher into a FetchResult discriminated union.
- * Does not throw errors, instead returning them as property of the FetchResult.
- * Example usage: const result = await fetchSafely(() => api.fetchUser(userId));
+ * Converts an API contract envelope into a mutually exclusive safe result.
+ * Only `APIError` values are normalized; rejected fetchers still reject.
  */
 declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>>>;
 /**
- * Resolves an APIContractResult, throwing an error if the result is an APIError.
- * Example usage: const data = await fetchAndThrow(() => api.fetchUser(userId));
+ * Returns successful API data and throws for an `APIError` envelope.
+ * Rejected fetchers propagate their original error without replacement.
  */
 declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
 
 /**
- * Returns the current date and time shifted to the specified timezone.
+ * Canonical metadata shared by upload controls and runtime validation.
+ * Every supported format defines display, MIME, and extension values.
+ */
+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 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"];
+    };
+};
+
+declare const fileFormatsArray: readonly ["png", "jpg", "webp", "avif", "heic", "pdf", "rtf", "txt"];
+type FileFormat = (typeof fileFormatsArray)[number];
+declare const fileFormatsRecord: Readonly<{
+    AVIF: "avif";
+    JPG: "jpg";
+    PDF: "pdf";
+    PNG: "png";
+    RTF: "rtf";
+    TXT: "txt";
+    WEBP: "webp";
+    HEIC: "heic";
+}>;
+declare const fileFormat: Readonly<{
+    AVIF: "avif";
+    JPG: "jpg";
+    PDF: "pdf";
+    PNG: "png";
+    RTF: "rtf";
+    TXT: "txt";
+    WEBP: "webp";
+    HEIC: "heic";
+}>;
+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";
+    UNSUPPORTED_FILE_FORMAT: "unsupported_file_format";
+    FILE_SIZE_EXCEEDED: "file_size_exceeded";
+    FILES_COUNT_EXCEEDED: "files_count_exceeded";
+}>;
+declare const uploadValidationError: Readonly<{
+    EMPTY_FILE: "empty_file";
+    UNSUPPORTED_FILE_FORMAT: "unsupported_file_format";
+    FILE_SIZE_EXCEEDED: "file_size_exceeded";
+    FILES_COUNT_EXCEEDED: "files_count_exceeded";
+}>;
+
+type FileFormatConfig = (typeof fileFormatsConfig)[FileFormat];
+/**
+ * Shared upload policy consumed by browser controls and backend validation.
+ * One preset keeps format, size, capacity, and fallback rules synchronized.
+ */
+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;
+}>;
+/**
+ * Constraints used to validate an incoming collection of browser files.
+ * Existing and incoming counts are combined when enforcing capacity.
+ */
+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[];
+    /**
+     * Maximum accepted size of one uploaded file measured in bytes.
+     * Files exceeding this boundary receive the stable size error key.
+     */
+    maxFileSize: number;
+    /**
+     * Optional maximum number of retained files after accepting the batch.
+     * Omitting this value leaves collection capacity unrestricted.
+     */
+    maxFilesCount?: number;
+}>;
+/**
+ * Accepted files and the final rejection encountered in one batch.
+ * Valid entries remain available when another entry fails validation.
+ */
+type UploadFilesValidationResult = Readonly<{
+    /**
+     * Valid incoming files that fit the remaining collection capacity.
+     * Accepted file objects preserve their original identity and ordering.
+     */
+    acceptedFiles: File[];
+    /**
+     * Final stable rejection encountered while processing the incoming batch.
+     * The field remains absent when every supplied file is accepted.
+     */
+    validationError?: UploadValidationError;
+}>;
+/**
+ * Options used to construct one reusable Zod file schema.
+ * Extension fallback is disabled by default to preserve strict MIME checks.
+ */
+type ZodUploadFileSchemaOptions = Readonly<{
+    /**
+     * Supported formats accepted by the generated file schema.
+     * Strict MIME validation uses metadata from the canonical format catalog.
+     */
+    formats: readonly FileFormat[];
+    /**
+     * Maximum accepted file size measured in bytes for the generated file schema.
+     * Empty files remain invalid independently of this configured boundary.
+     */
+    maxFileSize: number;
+    /**
+     * Allows a supported extension to compensate for missing MIME metadata.
+     * The fallback remains disabled by default to preserve strict validation.
+     */
+    extensionFallback?: boolean;
+}>;
+
+/**
+ * Defines one shared upload policy while preserving its literal format tuple.
+ * The resulting preset can drive schemas, picker hints, and batch validation.
  *
- * This is useful when the application needs to display "now" from another
- * region's point of view instead of relying on the server's local timezone.
+ * @example
+ * const imageUploadPreset = defineUploadPreset({
+ *   formats: [fileFormat.JPG, fileFormat.PNG, fileFormat.WEBP],
+ *   maxFileSize: 8 * 1024 * 1024,
+ *   maxFilesCount: 1,
+ * });
  */
-declare const getZonedTime: ({ tz }?: {
-    tz?: string;
-}) => Date;
+declare function defineUploadPreset<const TFormats extends readonly FileFormat[]>(preset: UploadPreset<TFormats>): UploadPreset<TFormats>;
+
+/**
+ * Default maximum size of one file accepted by the built-in upload presets.
+ * The 20 MiB boundary matches the existing upload component policy.
+ */
+declare const DEFAULT_UPLOAD_MAX_FILE_SIZE: number;
+/**
+ * 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.
+ */
+declare const imageUploadPreset: Readonly<{
+    formats: readonly ["png", "jpg", "webp", "avif", "heic"];
+    maxFileSize: number;
+    maxFilesCount?: number;
+    extensionFallback?: boolean;
+}>;
+/**
+ * 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.
+ */
+declare const documentUploadPreset: Readonly<{
+    formats: readonly ["pdf", "rtf", "txt"];
+    maxFileSize: number;
+    maxFilesCount?: number;
+    extensionFallback?: boolean;
+}>;
+
+/**
+ * Builds a reusable Zod schema for one uploaded file with format and size.
+ * MIME matching is strict unless extension fallback is explicitly enabled.
+ */
+declare function zodUploadFileSchema(options: ZodUploadFileSchemaOptions): z.ZodFile;
+
+/**
+ * Extracts a normalized trailing extension from a complete file name.
+ * Returns an empty string when no valid dot-delimited suffix exists.
+ */
+declare function getFileExtension(fileName: string): string;
+/**
+ * Normalizes a configured extension to a lowercase dot-prefixed value.
+ * Existing prefixes remain intact so repeated normalization is stable.
+ */
+declare function normalizeFileExtension(extension: string): string;
+/**
+ * Compares a concrete MIME type with an exact or wildcard configuration.
+ * Wildcards match every subtype belonging to the configured media group.
+ */
+declare function matchesMimeType(fileMimeType: string, configuredMimeType: string): boolean;
+/**
+ * Checks whether a file MIME type belongs to one selected format.
+ * File names and extensions cannot make an unsupported MIME type valid.
+ */
+declare function isFileMimeTypeSupported(file: File, formats: readonly FileFormat[]): boolean;
+/**
+ * Checks whether a file extension belongs to one selected format.
+ * The comparison is case-insensitive and requires a complete suffix.
+ */
+declare function isFileExtensionSupported(file: File, formats: readonly FileFormat[]): boolean;
+/**
+ * Checks whether a file matches one configured MIME type or extension.
+ * This permissive predicate supports clients where MIME metadata is absent.
+ */
+declare function isFileFormatSupported(file: File, formats: readonly FileFormat[]): boolean;
+/**
+ * Builds a native file-picker hint from configured MIME types and extensions.
+ * Duplicate values are removed while their configuration order is retained.
+ */
+declare function createUploadAccept(formats: readonly FileFormat[]): string;
+
 /**
- * Returns the UTC offset for the specified timezone at the given date.
+ * Validates one file against configured format and size constraints.
+ * Returns the first stable error key or nothing for a valid file.
+ */
+declare function validateUploadFile(file: File, formats: readonly FileFormat[], maxFileSize: number): UploadValidationError | undefined;
+/**
+ * Validates an incoming collection while preserving every accepted file.
+ * Returns accepted entries and the final rejection key from the batch.
+ */
+declare function validateUploadFiles(incomingFiles: readonly File[], options: UploadFilesValidationOptions): UploadFilesValidationResult;
+
+/**
+ * Projects the current instant onto the wall-clock fields of another timezone.
+ * The timezone defaults to `Europe/London` when no option is provided.
  *
- * The offset is formatted for display next to dates and times, for example
- * `(+4 UTC)`, `(0 UTC)`, or `(-5 UTC)`. The date is required because timezone
- * offsets may change depending on daylight saving time or historical rules.
+ * @example
+ * const londonTime = getZonedTime({ tz: 'Europe/London' });
  */
-declare const getUTCOffset: (date: Date, tz: string) => string;
+declare function getZonedTime({ tz }?: {
+    tz?: string;
+}): Date;
 /**
- * Returns the current time formatted in the specified timezone.
+ * Formats the UTC offset of a timezone at the supplied date.
+ * An explicit date preserves daylight-saving and historical offset rules.
  *
- * The result includes both the local time and its UTC offset, making it suitable
- * for UI labels, logs, bot messages, and other places where the user should see
- * not only the time itself, but also the timezone context behind that value.
+ * @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.
  *
- * Format: `HH:mm:ss (+X UTC)`.
+ * @example
+ * getFormattedTime({ tz: 'Europe/Moscow' }); // `03:04:05 (+3 UTC)`
  */
-declare const getFormattedTime: ({ tz }?: {
+declare function getFormattedTime({ tz }?: {
     tz?: string;
-}) => string;
+}): string;
 /**
- * Returns the current date formatted in the specified timezone.
- *
- * By default, the result includes date, time, and UTC offset. This is useful for
- * complete timestamps displayed in UI, bot messages, reports, or diagnostics.
+ * Formats the current date with optional time and UTC offset components.
+ * Time is included by default and uses the selected timezone for display.
  *
- * Format with time: `dd.MM.yyyy HH:mm:ss (+X UTC)`.
- * Format without time: `dd.MM.yyyy`.
+ * @example
+ * getFormattedDate({ tz: 'UTC', withTime: false }); // `02.01.2024`
  */
-declare const getFormattedDate: ({ tz, withTime, }?: {
+declare function getFormattedDate({ tz, withTime, }?: {
     tz?: string;
     withTime?: boolean;
-}) => string;
+}): string;
 /**
- * Formats the provided date and time in the specified timezone.
- *
- * Unlike helpers that always use the current moment, this function accepts an
- * explicit Date value and formats that exact point in time for another timezone.
+ * Formats an explicit instant in another timezone using the selected locale.
+ * The result includes localized date text, wall-clock time, and UTC offset.
  *
- * Format: `HH:mm:ss, d MMMM yyyy (+X UTC)`.
+ * @example
+ * formatTime(date, { locale: ru, tz: 'Europe/Moscow' });
  */
-declare const formatTime: (time: Date, { locale, tz }?: {
+declare function formatTime(time: Date, { locale, tz }?: {
     locale?: Locale;
     tz?: string;
-}) => string;
+}): string;
 
 /**
- * Recursively replaces dots in a string with underscores in a type-safe manner.
- * Example: `ReplaceDotsWithUnderscores<'foo.bar.baz.ok'>` → `'foo_bar_baz_ok'`.
+ * Recursively replaces dots in a string literal with underscores.
+ * Every other character remains unchanged in the resulting type.
+ *
+ * @example
+ * type Key = ReplaceDotsWithUnderscores<'foo.bar.baz'>; // `foo_bar_baz`
  */
-type ReplaceDotsWithUnderscores<T extends string> = T extends `${infer A}.${infer B}` ? `${A}_${ReplaceDotsWithUnderscores<B>}` : T;
+type ReplaceDotsWithUnderscores<TValue extends string> = TValue extends `${infer Head}.${infer Tail}` ? `${Head}_${ReplaceDotsWithUnderscores<Tail>}` : TValue;
 /**
- * Type-safe record mapping string values to ergonomic enum-like keys.
- * Keys are uppercased and dots are replaced with underscores.
+ * Maps string literals to immutable uppercase enum-like keys.
+ * Dots become underscores while every value preserves its original literal.
+ *
+ * @example
+ * type Statuses = StringEnumRecord<readonly ['review.pending', 'published']>;
  */
-type StringEnumRecord<T extends readonly string[]> = Readonly<{
-    [Value in T[number] as Uppercase<ReplaceDotsWithUnderscores<Value>>]: Value;
+type StringEnumRecord<TValues extends readonly string[]> = Readonly<{
+    [Value in TValues[number] as Uppercase<ReplaceDotsWithUnderscores<Value>>]: Value;
 }>;
 /**
  * Creates an immutable enum-like record from a readonly string array.
- * Example: `['foo.s', 'baz'] as const` → `{ FOO_S: 'foo.s', BAZ: 'baz' }`.
+ * Keys are uppercased and every dot is replaced with an underscore.
+ *
+ * @example
+ * createStringEnumRecord(['foo.s', 'baz'] as const); // `{ FOO_S: 'foo.s', BAZ: 'baz' }`
  */
 declare function createStringEnumRecord<const T extends readonly string[]>(values: T): StringEnumRecord<T>;
 
 /**
- * Safely executes functions and handles errors without using try/catch in the calling code.
- * Example usage: `safeExecute(() => fetchData(), (error) => console.error(error))`
+ * Resolves synchronous and asynchronous executions 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<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.
  */
-declare function safeExecute<T, E = never>(fn: () => Promise<T> | T, onError?: (error?: unknown) => E | Promise<E>): Promise<T | E>;
 type MeasuredExecution<T> = {
-    /** The result of the executed function. */
+    /**
+     * Value resolved by the measured execution without cloning or transformation.
+     * Its generic type remains identical to the original asynchronous result.
+     */
     result: T;
-    /** The time taken to execute the function, in milliseconds. */
+    /**
+     * Rounded wall-clock duration of the measured execution in milliseconds.
+     * The value is always collected after the supplied promise resolves.
+     */
     executionTime: number;
 };
 /**
- * Utility function to measure the execution time of an asynchronous function.
- * @returns An object containing the result of the execution and the time taken in milliseconds.
+ * Measures an asynchronous execution while preserving its resolved result.
+ * Rejected executions propagate unchanged and do not produce a measurement.
  *
- * ```typescript
+ * @example
  * const { result, executionTime } = await measureExecutionTime(async () => {
  *    return await fetchData();
  * });
  * console.log(`Execution time: ${executionTime}ms`);
- * ```
  */
 declare function measureExecutionTime<T>(execution: () => Promise<T>): Promise<MeasuredExecution<T>>;
 
 /**
- * Creates a random string of the specified length using characters from DEFAULT_CHARACTERS.
- * Example usage: `generateRandomString(5) = 'aZ3fG' / generateRandomString() = 'G5kLm2P9sQ'`
+ * Creates a cryptographically sourced string from the alphanumeric set.
+ * Requested length defaults to `10` characters when omitted.
+ *
+ * @example
+ * generateRandomString(5); // `aZ3fG`
+ * generateRandomString(); // `G5kLm2P9sQ`
  */
 declare function generateRandomString(length?: number): string;
 
 /**
- * HTTP status colors for better visual parsing in logs:
- * 2xx - green, 4xx - yellow, 5xx - red, others - default color.
+ * Selects a terminal color function for one HTTP response status.
+ * Successes are green, client errors yellow, and server errors red.
+ *
+ * @example
+ * getColoredHTTPStatus(404)('404');
  */
 declare function getColoredHTTPStatus(status: number): (text: string) => string;
 /**
- * Unified logging interface for different levels (info, warn, error)
- * with optional service name and stack trace for errors (error level).
+ * Shared logging interface for informational, warning, and error messages.
+ * Every level supports a service label while errors may include a stack trace.
  */
 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 stack trace context.
+     * Stack traces are rendered beneath the primary error message when supplied.
+     */
     error: (message: string, service?: string, stack?: string) => void;
 };
 
@@ -244,13 +550,13 @@ type Simplify<T> = {
  *   identifierSchema: z.string().min(1),
  * });
  */
-declare const zodBulkSelectionSchema: <const TIdentifierSchema extends z.ZodType<string | number>>({ identifierSchema, }: {
+declare function zodBulkSelectionSchema<const TIdentifierSchema extends z.ZodType<string | number>>({ identifierSchema, }: {
     /**
      * Schema used to validate every included or excluded entity identifier.
      * Its transforms and exact inferred output are preserved in both branches.
      */
     identifierSchema: TIdentifierSchema;
-}) => z.ZodDiscriminatedUnion<[z.ZodObject<{
+}): z.ZodDiscriminatedUnion<[z.ZodObject<{
     mode: z.ZodLiteral<"include">;
     identifiers: z.ZodArray<TIdentifierSchema>;
 }, z.core.$strict>, z.ZodObject<{
@@ -278,30 +584,47 @@ type ZodBulkExcludeSelection<TIdentifier extends string | number = string> = Ext
     mode: 'exclude';
 }>;
 
-/** Options for configuring the JWT service. */
+/**
+ * Configures the algorithm and default expiration used by `ZodJWTService`.
+ * Omitted values fall back to `HS256` and fifteen minutes respectively.
+ */
 type JWTServiceOptions = {
-    /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
+    /**
+     * Symmetric algorithm used to sign and verify every token handled by the service.
+     * Defaults to `HS256` when the configuration does not provide another value.
+     */
     algorithm?: SymmetricAlgorithm;
-    /** The default number of seconds until a signed JWT expires. Defaults to 900 seconds (15 minutes). */
+    /**
+     * Default lifetime assigned to signed tokens, expressed in seconds.
+     * Defaults to `900` seconds, which is equivalent to fifteen minutes.
+     */
     defaultExpirationSeconds?: number;
 };
-/** Options for signing a JWT. */
+/**
+ * Configures one JWT signing operation without changing service defaults.
+ * A supplied expiration takes precedence over `defaultExpirationSeconds`.
+ */
 type JWTSignOptions = {
-    /** The number of seconds until the JWT expires. */
+    /**
+     * Lifetime assigned to the token created by this signing operation.
+     * Overrides the service default and remains expressed in seconds.
+     */
     expiresInSeconds?: number;
 };
 /**
- * Utility types for inferring payload types from Zod schemas.
+ * 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$1.ZodType ? z$1.infer<T> : T;
 /**
- * Utility type to extract the payload schema type from a Zod schema.
- * */
+ * Preserves a Zod payload schema and rejects direct payload types with `never`.
+ * The result controls whether runtime payload validation is available.
+ */
 type PayloadSchema<T> = T extends z$1.ZodType ? T : never;
 
 /**
- * A service class for handling JWT operations with optional Zod schema validation for the payload.
- * The class is generic, allowing you to specify the type of the payload or a schema for validation.
+ * Signs, decodes, and verifies JWTs with optional Zod payload validation.
+ * A supplied schema parses payloads returned by decoding and verification.
  */
 declare class ZodJWTService<TPayloadOrSchema> {
     readonly payloadSchema: PayloadSchema<TPayloadOrSchema> | undefined;
@@ -309,23 +632,27 @@ declare class ZodJWTService<TPayloadOrSchema> {
     protected readonly defaultExpirationSeconds: number;
     constructor(payloadSchema?: PayloadSchema<TPayloadOrSchema>, options?: JWTServiceOptions);
     /**
-     * Signs a JWT token with the provided payload and secret, using the configured algorithm and expiration settings.
-     * Example usage: `const accessToken = await JWTServiceInstance.sign({ userId: 123 }, 'my-secret', { expiresInSeconds: 300 });`
+     * 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 });
      */
     sign(payload: Payload<TPayloadOrSchema>, secret: string, options?: JWTSignOptions): Promise<string>;
     /**
-     * Decodes a JWT token, and if a Zod schema is provided, validates the payload against it.
-     * Returns the decoded payload if valid, or null if invalid or if the token cannot be decoded.
+     * Decodes without authenticating it and parses its payload when a schema exists.
+     * Schema validation failures return `null`, while malformed tokens still reject.
      *
-     * Example usage: `const payload = await JWTServiceInstance.decode(token);`
+     * @example
+     * const payload = await jwtService.decode(token);
      */
     decode(token: string): Promise<Payload<TPayloadOrSchema> | null>;
     /**
-     * Verifies and decodes a JWT token using the provided secret and configured algorithm,
-     * then validates the payload against the Zod schema if one is provided.
+     * Verifies a token using the configured algorithm and parses its payload.
+     * Signature, expiration, and schema validation failures reject the operation.
      *
-     * Throws an error if verification fails or if the payload is invalid according to the schema.
-     * Example usage: `const payload = await JWTServiceInstance.verifyOrThrow(token, 'my-secret');`
+     * @example
+     * const payload = await jwtService.verifyOrThrow(token, secret);
      */
     verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
 }
@@ -462,11 +789,10 @@ type AsQuery<T> = T extends null | undefined ? T : T extends QueryPrimitive ? st
  * 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.
  *
- * ```typescript
+ * @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 }
- * ```
  */
 type AtLeastOne<T, Keys extends keyof T = keyof T> = Keys extends keyof T ? Simplify<Required<Pick<T, Keys>> & Partial<Omit<T, Keys>>> : never;
 
@@ -476,9 +802,8 @@ type AtLeastOne<T, Keys extends keyof T = keyof T> = Keys extends keyof T ? Simp
  * 2. A `.transform()` that narrows the output type to `AtLeastOne<T>`,
  *    making it directly assignable to domain `*Select` and `*Update` types without casting.
  *
- * ```typescript
+ * @example
  * zQuery(zodAtLeastOne(userSelectSchema)) // result: UserSelect ✓
- * ```
  */
 declare const zodAtLeastOne: <T extends ZodObject<ZodRawShape>>(schema: T) => z.ZodPipe<T, z.ZodTransform<Awaited<AtLeastOne<z.core.output<T>>>, z.core.output<T>>>;
 
@@ -490,7 +815,7 @@ declare const parseQueryValue: (value: unknown) => unknown;
  * numbers or booleans. This helper converts only clear primitive values, allowing
  * regular schemas like `z.number()` and `z.boolean()` to validate query input directly.
  *
- * ```typescript
+ * @example
  * const schema = asQuery(z.object({
  *   page: z.number().int().positive(),
  *   isActive: z.boolean(),
@@ -498,7 +823,6 @@ declare const parseQueryValue: (value: unknown) => unknown;
  *
  * schema.parse({ page: '2', isActive: 'true' });
  * // { page: 2, isActive: true }
- * ```
  */
 declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>;
 
@@ -508,4 +832,4 @@ declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, asQuery, createStringEnumRecord, failure, fetchAndThrow, fetchSafely, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isPlainObject, log, measureExecutionTime, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchSchema };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FileFormat, type FileFormatConfig, type HonoFileRespondOptions, type HonoRespondOptions, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, type UploadFilesValidationOptions, type UploadFilesValidationResult, type UploadPreset, type UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, defineUploadPreset, documentUploadPreset, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };