@kalutskii/foundation 0.7.7 → 0.7.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Kalutskii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # @kalutskii/foundation
 
 Shared TypeScript foundation for contracts, schemas, framework adapters, and reusable utilities.
-The package is designed for Bun, Node.js, Hono applications, and Cloudflare Workers environments.
+The package is designed for Bun, Node.js, and Hono applications.
 
 This repository is not intended to document every exported function through standalone usage snippets.
 Public JSDoc, generated declarations, colocated specifications, and editor inference are the API reference.
@@ -24,6 +24,7 @@ The package contains several deliberately isolated areas:
 | ---------------- | ----------------------------------------------------------------------------------------- |
 | `utilities`      | Framework-independent datetime, enum, execution, generation, logging, and type utilities. |
 | `http`           | Shared HTTP result contracts, factories, status constants, and result resolvers.          |
+| `upload`         | Shared file-format metadata, upload validation, and reusable Zod file schemas.            |
 | `zod-validation` | Generic Zod parsing, validation, refinement, and related type utilities.                  |
 | `zod-search`     | Reusable search and pagination contracts composed from lower-level Zod primitives.        |
 | `zod-bulk`       | Include/exclude selection contracts shared by frontend and backend bulk operations.       |
@@ -46,7 +47,7 @@ Framework adapters
             │
             ▼
 Contract composition
-  zod-search / zod-bulk
+  zod-search / zod-bulk / upload
             │
             ▼
 Contract primitives
@@ -88,6 +89,7 @@ src/
 ├── drizzle/
 ├── hono/
 ├── http/
+├── upload/
 ├── utilities/
 ├── zod-bulk/
 ├── zod-jwt/
@@ -111,20 +113,23 @@ single public API boundary and should export only symbols intentionally supporte
 
 ## File responsibilities
 
-| Suffix           | Expected content                                                              |
-| ---------------- | ----------------------------------------------------------------------------- |
-| `*.constants.ts` | Immutable values and literal collections without behavior.                    |
-| `*.schemas.ts`   | Runtime Zod schemas and factories whose result is a schema.                   |
-| `*.types.ts`     | Type aliases, interfaces, generic contracts, and schema-derived output types. |
-| `*.factory.ts`   | Functions whose primary responsibility is constructing non-schema values.     |
-| `*.resolvers.ts` | Functions that unwrap, normalize, or translate an existing result.            |
-| `*.utilities.ts` | Stateless reusable behavior that has no narrower architectural owner.         |
-| `*.parsing.ts`   | Input parsing and preprocessing before domain validation.                     |
-| `*.refiners.ts`  | Refinement logic that narrows or safely composes an existing value.           |
-| `*.execution.ts` | Framework lifecycle execution and error-boundary behavior.                    |
-| `*.logging.ts`   | Logging formatters, sinks, or middleware behavior.                            |
-| `*.respond.ts`   | Framework response construction and response-specific contracts.              |
-| `*.spec.ts`      | The single colocated runtime and compile-time specification for a module.     |
+| Suffix            | Expected content                                                          |
+| ----------------- | ------------------------------------------------------------------------- |
+| `*.constants.ts`  | Immutable configuration values and metadata without behavior.             |
+| `*.enums.ts`      | Literal collections, derived unions, ergonomic records, and aliases.      |
+| `*.schemas.ts`    | Runtime Zod schemas and factories whose result is a schema.               |
+| `*.types.ts`      | Type aliases, generic contracts, and schema-derived output types.         |
+| `*.services.ts`   | Stateful service classes that coordinate one external capability.         |
+| `*.validation.ts` | Ordered validation behavior returning stable domain error keys.           |
+| `*.factory.ts`    | Functions whose primary responsibility is constructing non-schema values. |
+| `*.resolvers.ts`  | Functions that unwrap, normalize, or translate an existing result.        |
+| `*.utilities.ts`  | Stateless reusable behavior that has no narrower architectural owner.     |
+| `*.parsing.ts`    | Input parsing and preprocessing before domain validation.                 |
+| `*.refiners.ts`   | Refinement logic that narrows or safely composes an existing value.       |
+| `*.execution.ts`  | Framework lifecycle execution and error-boundary behavior.                |
+| `*.logging.ts`    | Logging formatters, sinks, or middleware behavior.                        |
+| `*.respond.ts`    | Framework response construction and response-specific contracts.          |
+| `*.spec.ts`       | The single colocated runtime and compile-time specification for a module. |
 
 Do not place TypeScript-only contracts in a schema file when they can be separated without creating a circular
 responsibility. Do not split tiny files mechanically either: separation must communicate ownership, not line count.

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.
+ * Builds a Drizzle `WHERE` clause by combining defined object entries with `and`.
+ * Expects the supplied keys to be validated against the table beforehand.
  *
- * 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.
- *
- * ```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;
+};
+
+/**
+ * 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;
 
 /**
- * Factory for creating successful API responses with serializable data.
- * Example usage: `success({ status: 200, data: { message: 'Operation successful' } })`
+ * 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,369 @@ 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];
+/**
+ * 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;
+}>;
+
+/**
+ * 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;
+
+/**
+ * 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.
  *
- * 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 londonTime = getZonedTime({ tz: 'Europe/London' });
  */
-declare const getZonedTime: ({ tz }?: {
+declare function getZonedTime({ tz }?: {
     tz?: string;
-}) => Date;
+}): Date;
 /**
- * Returns the UTC offset for the specified timezone at the given date.
+ * Formats the UTC offset of a timezone at the supplied date.
+ * An explicit date preserves daylight-saving and historical offset rules.
  *
- * 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
+ * getUTCOffset(date, 'Europe/Moscow'); // `(+3 UTC)`
  */
-declare const getUTCOffset: (date: Date, tz: string) => string;
+declare function getUTCOffset(date: Date, tz: string): string;
 /**
- * Returns the current time formatted in the specified timezone.
- *
- * 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.
+ * 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 +485,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 +519,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 +567,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 +724,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 +737,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 +750,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 +758,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 +767,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, 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 UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, 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 };

package/dist/index.js

@@ -40,50 +40,64 @@ import { blue, dim, green, red, white, yellow } from "kleur/colors";
 import { format } from "date-fns";
 import { getTimezoneOffset, toZonedTime } from "date-fns-tz";
 import { ru } from "date-fns/locale";
-var getZonedTime = ({ tz = "Europe/London" } = {}) => {
+function getZonedTime({ tz = "Europe/London" } = {}) {
   return toZonedTime(/* @__PURE__ */ new Date(), tz);
-};
-var getUTCOffset = (date, tz) => {
+}
+function getUTCOffset(date, tz) {
   const offset = getTimezoneOffset(tz, date) / (60 * 60 * 1e3);
   return `(${offset >= 0 ? "+" : ""}${offset} UTC)`;
-};
-var getFormattedTime = ({ tz = "Europe/London" } = {}) => {
+}
+function getFormattedTime({ tz = "Europe/London" } = {}) {
   const zonedTime = getZonedTime({ tz });
   return `${format(zonedTime, "HH:mm:ss")} ${getUTCOffset(zonedTime, tz)}`;
-};
-var getFormattedDate = ({ tz = "Europe/London", withTime = true } = {}) => {
+}
+function getFormattedDate({ tz = "Europe/London", withTime = true } = {}) {
   const zonedTime = getZonedTime({ tz });
   const pattern = withTime ? "dd.MM.yyyy HH:mm:ss" : "dd.MM.yyyy";
   const formatted = format(zonedTime, pattern);
   return `${formatted}${withTime ? ` ${getUTCOffset(zonedTime, tz)}` : ""}`;
-};
-var formatTime = (time, { locale = ru, tz = "Europe/London" } = {}) => {
+}
+function formatTime(time, { locale = ru, tz = "Europe/London" } = {}) {
   const zonedTime = toZonedTime(time, tz);
   return `${format(zonedTime, "HH:mm:ss, d MMMM yyyy", { locale })} ${getUTCOffset(zonedTime, tz)}`;
-};
+}
 
 // src/utilities/logging.utilities.ts
+var HTTP_STATUS_COLORS = [
+  { range: [200, 299], color: green },
+  { range: [400, 499], color: yellow },
+  { range: [500, 599], color: red }
+];
+var LOG_LEVEL_COLORS = { info: blue, warn: yellow, error: red };
 function getColoredHTTPStatus(status) {
-  const colorMap = [
-    { range: [200, 299], colorFn: green },
-    { range: [400, 499], colorFn: yellow },
-    { range: [500, 599], colorFn: red }
-  ];
-  const statusColor = colorMap.find(({ range: [min, max] }) => status >= min && status <= max);
-  return statusColor ? statusColor.colorFn : (text) => text;
+  const statusColor = HTTP_STATUS_COLORS.find(({ range: [minimum, maximum] }) => {
+    return status >= minimum && status <= maximum;
+  });
+  return statusColor ? statusColor.color : (text) => text;
 }
 function writeLog(message, level, service = "log", stack) {
-  const logColorMap = { info: blue, warn: yellow, error: red };
   const timestamp = dim(getFormattedTime());
-  const serviceName = logColorMap[level](service.padEnd(12));
+  const serviceName = LOG_LEVEL_COLORS[level](service.padEnd(12));
   const formattedMessage = white(message);
   console.log(`[${timestamp}] ${serviceName} | ${formattedMessage}`);
   if (stack)
     console.log(`[${timestamp}] ${red("\u21B3 trace").padEnd(18)} | ${dim(stack)}`);
 }
 var log = {
+  /**
+   * Writes an informational message with an optional service label.
+   * Missing service names use the shared `log` fallback label.
+   */
   info: (message, service) => writeLog(message, "info", service),
+  /**
+   * Writes a warning message with an optional service label.
+   * Missing service names use the shared `log` fallback label.
+   */
   warn: (message, service) => writeLog(message, "warn", service),
+  /**
+   * Writes an error message with optional service and stack trace context.
+   * Stack traces are rendered beneath the primary error message when supplied.
+   */
   error: (message, service, stack) => writeLog(message, "error", service, stack)
 };
 
@@ -116,14 +130,14 @@ var honoLoggingHandler = async (c, next) => {
     // Otherwise, we read the request body as text and normalize whitespace.
     (await c.req.raw.clone().text()).replaceAll(/\s+/g, " ").trim()
   );
-  const bodyPreview = body.length > 50 ? `${body.slice(0, 25)}\u2026${body.slice(-25)}` : body;
+  const bodyPreview = body.length > 80 ? `${body.slice(0, 40)}\u2026${body.slice(-40)}` : body;
   const startTime = performance.now();
   await next();
   const duration = Math.round(performance.now() - startTime);
   const coloredMethod = bold(blue2(c.req.method.padEnd(4)));
   const coloredStatus = getColoredHTTPStatus(c.res.status)(String(c.res.status).padEnd(4));
   const coloredTime = dim2(`${duration}ms`.padStart(6));
-  const coloredPath = white2(c.req.path.padEnd(44));
+  const coloredPath = white2(c.req.path.padEnd(32));
   const coloredSearchParams = searchParams ? dim2(` (${searchParams})`) : "";
   const coloredBody = bodyPreview ? dim2(` ${bodyPreview}`) : "";
   log.info(`${coloredMethod} ${coloredStatus} ${coloredTime} ${coloredPath}${coloredSearchParams}${coloredBody}`, "hono");
@@ -162,14 +176,115 @@ function createStringEnumRecord(values) {
   return Object.freeze(Object.fromEntries(values.map((value) => [value.replace(/\./g, "_").toUpperCase(), value])));
 }
 
+// src/upload/upload.enums.ts
+var fileFormatsArray = [
+  ...["png", "jpg", "webp", "avif", "heic"],
+  // Image formats.
+  ...["pdf", "rtf", "txt"]
+  // Text and document formats.
+];
+var fileFormatsRecord = createStringEnumRecord(fileFormatsArray);
+var fileFormat = fileFormatsRecord;
+var uploadValidationErrorsArray = [
+  "empty_file",
+  "unsupported_file_format",
+  "file_size_exceeded",
+  "files_count_exceeded"
+];
+var uploadValidationErrorsRecord = createStringEnumRecord(uploadValidationErrorsArray);
+var uploadValidationError = uploadValidationErrorsRecord;
+
+// src/upload/upload.constants.ts
+var fileFormatsConfig = {
+  // Image formats.
+  [fileFormatsRecord.PNG]: { name: "PNG", mimeTypes: ["image/png"], extensions: [".png"] },
+  [fileFormatsRecord.JPG]: { name: "JPG", mimeTypes: ["image/jpeg"], extensions: [".jpg", ".jpeg"] },
+  [fileFormatsRecord.WEBP]: { name: "WEBP", mimeTypes: ["image/webp"], extensions: [".webp"] },
+  [fileFormatsRecord.AVIF]: { name: "AVIF", mimeTypes: ["image/avif"], extensions: [".avif"] },
+  [fileFormatsRecord.HEIC]: { name: "HEIC", mimeTypes: ["image/heic", "image/heif"], extensions: [".heic", ".heif"] },
+  // Text and document formats.
+  [fileFormatsRecord.PDF]: { name: "PDF", mimeTypes: ["application/pdf"], extensions: [".pdf"] },
+  [fileFormatsRecord.RTF]: { name: "RTF", mimeTypes: ["application/rtf"], extensions: [".rtf"] },
+  [fileFormatsRecord.TXT]: { name: "TXT", mimeTypes: ["text/plain"], extensions: [".txt"] }
+};
+
+// src/upload/upload.schemas.ts
+import { z } from "zod";
+
+// src/upload/upload.utilities.ts
+function getFileExtension(fileName) {
+  const extensionIndex = fileName.lastIndexOf(".");
+  return extensionIndex > 0 && extensionIndex < fileName.length - 1 ? fileName.slice(extensionIndex).toLowerCase() : "";
+}
+function normalizeFileExtension(extension) {
+  const normalizedExtension = extension.toLowerCase();
+  return normalizedExtension.startsWith(".") ? normalizedExtension : `.${normalizedExtension}`;
+}
+function matchesMimeType(fileMimeType, configuredMimeType) {
+  if (configuredMimeType.endsWith("/*"))
+    return fileMimeType.startsWith(configuredMimeType.slice(0, -1));
+  return fileMimeType === configuredMimeType;
+}
+function isFileMimeTypeSupported(file, formats) {
+  return formats.some((format2) => fileFormatsConfig[format2].mimeTypes.some((mimeType) => matchesMimeType(file.type, mimeType)));
+}
+function isFileExtensionSupported(file, formats) {
+  const fileExtension = getFileExtension(file.name);
+  return formats.some((format2) => fileFormatsConfig[format2].extensions.some((extension) => normalizeFileExtension(extension) === fileExtension));
+}
+function isFileFormatSupported(file, formats) {
+  return isFileMimeTypeSupported(file, formats) || isFileExtensionSupported(file, formats);
+}
+function createUploadAccept(formats) {
+  const acceptedValues = formats.flatMap((format2) => [
+    ...fileFormatsConfig[format2].mimeTypes,
+    ...fileFormatsConfig[format2].extensions
+  ]);
+  return [...new Set(acceptedValues)].join(",");
+}
+
+// src/upload/upload.schemas.ts
+function zodUploadFileSchema(options) {
+  const { formats, maxFileSize, extensionFallback = false } = options;
+  return z.file().min(1, uploadValidationError.EMPTY_FILE).max(maxFileSize, uploadValidationError.FILE_SIZE_EXCEEDED).refine((file) => extensionFallback ? isFileFormatSupported(file, formats) : isFileMimeTypeSupported(file, formats), uploadValidationError.UNSUPPORTED_FILE_FORMAT);
+}
+
+// src/upload/upload.validation.ts
+function validateUploadFile(file, formats, maxFileSize) {
+  if (file.size === 0)
+    return uploadValidationError.EMPTY_FILE;
+  if (isFileFormatSupported(file, formats) === false)
+    return uploadValidationError.UNSUPPORTED_FILE_FORMAT;
+  if (file.size > maxFileSize)
+    return uploadValidationError.FILE_SIZE_EXCEEDED;
+  return void 0;
+}
+function validateUploadFiles(incomingFiles, options) {
+  const { currentFilesCount, formats, maxFileSize, maxFilesCount } = options;
+  const availableFilesCount = maxFilesCount === void 0 ? Infinity : maxFilesCount - currentFilesCount;
+  const acceptedFiles = [];
+  let validationError;
+  for (const file of incomingFiles) {
+    const fileValidationError = validateUploadFile(file, formats, maxFileSize) ?? // Collection limits apply only after intrinsic file validation succeeds.
+    // This preserves remaining slots for supported files from the same batch.
+    (acceptedFiles.length >= availableFilesCount ? uploadValidationError.FILES_COUNT_EXCEEDED : void 0);
+    if (fileValidationError) {
+      validationError = fileValidationError;
+      continue;
+    }
+    acceptedFiles.push(file);
+  }
+  return { acceptedFiles, validationError };
+}
+
 // src/utilities/execution.utilities.ts
 async function safeExecute(fn, onError) {
   try {
     return await fn();
-  } catch (err) {
+  } catch (error) {
     if (onError)
-      return await onError(err);
-    throw err;
+      return await onError(error);
+    throw error;
   }
 }
 async function measureExecutionTime(execution) {
@@ -180,19 +295,19 @@ async function measureExecutionTime(execution) {
 }
 
 // src/zod-bulk/zod-bulk.schemas.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var DEFAULT_ERROR_MESSAGE = "Selection identifiers must be provided.";
-var zodBulkSelectionSchema = ({ identifierSchema }) => {
-  const identifiersSchema = z.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, {
+function zodBulkSelectionSchema({ identifierSchema }) {
+  const identifiersSchema = z2.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, {
     message: DEFAULT_ERROR_MESSAGE
   });
-  return z.discriminatedUnion("mode", [
-    z.object({ mode: z.literal("include"), identifiers: identifiersSchema }).strict(),
-    z.object({ mode: z.literal("exclude"), excludedIdentifiers: identifiersSchema }).strict()
+  return z2.discriminatedUnion("mode", [
+    z2.object({ mode: z2.literal("include"), identifiers: identifiersSchema }).strict(),
+    z2.object({ mode: z2.literal("exclude"), excludedIdentifiers: identifiersSchema }).strict()
   ]);
-};
+}
 
-// src/zod-jwt/zod-jwt.schemas.ts
+// src/zod-jwt/zod-jwt.services.ts
 import { decode as decodeJWT, sign as signJWT, verify as verifyJWT } from "hono/jwt";
 var ZodJWTService = class {
   payloadSchema;
@@ -204,37 +319,41 @@ var ZodJWTService = class {
     this.defaultExpirationSeconds = options?.defaultExpirationSeconds ?? 60 * 15;
   }
   /**
-   * 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 });
    */
   async sign(payload, secret, options) {
     const exp = Math.floor(Date.now() / 1e3) + (options?.expiresInSeconds ?? this.defaultExpirationSeconds);
     return signJWT({ ...payload, exp }, secret, this.algorithm);
   }
   /**
-   * 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);
    */
   async decode(token) {
     const { payload } = decodeJWT(token);
-    if (!this.payloadSchema) {
+    if (this.payloadSchema === void 0) {
       return payload;
     }
     const { success: success2, data } = await this.payloadSchema.safeParseAsync(payload);
     return success2 ? data : 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);
    */
   async verifyOrThrow(token, secret) {
     const payload = await verifyJWT(token, secret, this.algorithm);
-    if (!this.payloadSchema) {
+    if (this.payloadSchema === void 0) {
       return payload;
     }
     return this.payloadSchema.parseAsync(payload);
@@ -242,23 +361,23 @@ var ZodJWTService = class {
 };
 
 // src/zod-search/zod-search.pagination.schemas.ts
-import { z as z2 } from "zod";
-var zodPaginationSchema = z2.object({
+import { z as z3 } from "zod";
+var zodPaginationSchema = z3.object({
   /**
    * Zero-based number of records skipped before collecting a result page.
    * String values are coerced to support validation of URL query input.
    */
-  offset: z2.coerce.number().int().nonnegative().default(0),
+  offset: z3.coerce.number().int().nonnegative().default(0),
   /**
    * Positive maximum number of records returned in a single result page.
    * String values are coerced to support validation of URL query input.
    */
-  limit: z2.coerce.number().int().positive().default(10)
+  limit: z3.coerce.number().int().positive().default(10)
 });
 var zodPaginationShape = zodPaginationSchema.shape;
 
 // src/zod-search/zod-search.schemas.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/zod-validation/zod-validation.refiners.ts
 var DEFAULT_ERROR_MESSAGE2 = "Invalid input. At least one field must be provided.";
@@ -269,7 +388,7 @@ var zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
 }).transform((val) => val);
 
 // src/zod-search/zod-search.schemas.ts
-var zodSearchQuerySchema = z3.string().trim().min(1).optional();
+var zodSearchQuerySchema = z4.string().trim().min(1).optional();
 var createZodSearchWhereSchema = (filters) => zodAtLeastOne(filters.partial());
 var zodSearchSchema = (options) => {
   const whereSchema = options.filters !== void 0 ? createZodSearchWhereSchema(options.filters) : options.whereSchema;
@@ -278,11 +397,11 @@ var zodSearchSchema = (options) => {
     ...options.queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
     ...options.paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
   };
-  return z3.object(shape).strict();
+  return z4.object(shape).strict();
 };
 
 // src/zod-validation/zod-validation.parsing.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/zod-validation/zod-validation.utilities.ts
 var isPlainObject = (value) => {
@@ -309,37 +428,56 @@ var parseQueryValue = (value) => {
     return Number(normalized);
   return value;
 };
-var asQuery = (schema) => z4.preprocess(parseQueryValue, schema);
+var asQuery = (schema) => z5.preprocess(parseQueryValue, schema);
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
   asQuery,
   createStringEnumRecord,
+  createUploadAccept,
+  createZodSearchWhereSchema,
   failure,
   fetchAndThrow,
   fetchSafely,
+  fileFormat,
+  fileFormatsArray,
+  fileFormatsConfig,
+  fileFormatsRecord,
   fileRespond,
   formatTime,
   generateRandomString,
   getColoredHTTPStatus,
+  getFileExtension,
   getFormattedDate,
   getFormattedTime,
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
+  isFileExtensionSupported,
+  isFileFormatSupported,
+  isFileMimeTypeSupported,
   isPlainObject,
   log,
+  matchesMimeType,
   measureExecutionTime,
+  normalizeFileExtension,
   onHandlerError,
   parseQueryValue,
   respond,
   safeExecute,
   sqlWhere,
   success,
+  uploadValidationError,
+  uploadValidationErrorsArray,
+  uploadValidationErrorsRecord,
+  validateUploadFile,
+  validateUploadFiles,
   zodAtLeastOne,
   zodBulkSelectionSchema,
   zodPaginationSchema,
   zodPaginationShape,
-  zodSearchSchema
+  zodSearchQuerySchema,
+  zodSearchSchema,
+  zodUploadFileSchema
 };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
+  "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
@@ -12,10 +13,12 @@
   },
   "scripts": {
     "build": "tsup",
+    "test": "bun test",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --ext .ts --fix",
+    "lint:check": "eslint . --ext .ts",
     "format": "prettier --write .",
-    "test": "bun test"
+    "format:check": "prettier --check ."
   },
   "exports": {
     ".": {
@@ -27,7 +30,6 @@
     "dist"
   ],
   "peerDependencies": {
-    "@hono/zod-validator": "^0.8.0",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
     "drizzle-orm": "^1.0.0-beta.22",