@kalutskii/foundation 2.0.0 → 2.0.6

package/dist/index.js

@@ -1,52 +1,48 @@
-import { and, eq } from "drizzle-orm";
-import { HTTPException } from "hono/http-exception";
-import { blue, bold, 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";
-import { z as z$1 } from "zod";
+import { and, eq, getTableColumns, isNull } from "drizzle-orm";
+import { HTTPException } from "hono/http-exception";
+import { blue, bold, dim, green, red, white, yellow } from "kleur/colors";
 import { decode, sign, verify } from "hono/jwt";
-//#region src/drizzle/drizzle.refiners.ts
-const AT_LEAST_ONE_DEFINED_CONDITION_ERROR = "sqlWhere requires at least one defined condition.";
+import { z } from "zod";
+//#region src/base64/base64.constants.ts
 /**
-* Builds a Drizzle `WHERE` clause by combining defined object entries with `and`.
-* Expects the supplied keys to be validated against the table beforehand.
-*
-* @example
-* await db.update(usersTable).set(values).where(sqlWhere(usersTable, { id: 1 })).returning();
+* Maximum byte count converted by one `String.fromCharCode` invocation.
+* Chunking keeps large payloads below engine-specific argument-count limits.
 */
-function sqlWhere(table, where) {
-	const columns = table;
-	const conditions = Object.entries(where).filter(([, value]) => value !== void 0).map(([key, value]) => eq(columns[key], value));
-	if (conditions.length === 0) throw new Error(AT_LEAST_ONE_DEFINED_CONDITION_ERROR);
-	return and(...conditions);
-}
+const BASE64_BYTE_CHUNK_SIZE = 32768;
 //#endregion
-//#region src/http/http.factory.ts
+//#region src/base64/base64.utilities.ts
 /**
-* Creates a successful API envelope without cloning its data.
-* Generic inference preserves the exact supplied payload type.
+* Encodes arbitrary binary bytes into their canonical Base64 representation.
+* Chunked conversion avoids the argument limit imposed by `String.fromCharCode`.
 */
-function success({ status, data }) {
-	return {
-		kind: "data",
-		status,
-		data
-	};
+function encodeBase64(bytes) {
+	let binary = "";
+	for (let offset = 0; offset < bytes.length; offset += BASE64_BYTE_CHUNK_SIZE) binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_BYTE_CHUNK_SIZE));
+	return btoa(binary);
 }
 /**
-* Creates a failed API envelope with one supported exception status.
-* The supplied error code remains unchanged for downstream resolution.
+* Decodes Base64 text accepted by native `atob` into its original binary bytes.
+* Unsupported input preserves the platform failure instead of returning partial data.
 */
-function failure({ status, error }) {
-	return {
-		kind: "error",
-		status,
-		error
-	};
+function decodeBase64(value) {
+	const binary = atob(value);
+	return Uint8Array.from(binary, (character) => character.charCodeAt(0));
 }
 //#endregion
-//#region src/utilities/datetime.utilities.ts
+//#region src/datetime/datetime.constants.ts
+/**
+* Default timezone applied by datetime utilities when no explicit zone is provided.
+* The value preserves the package's historical London-based formatting behavior.
+*/
+const DEFAULT_DATETIME_TIMEZONE = "Europe/London";
+const DATETIME_DATE_PATTERN = "dd.MM.yyyy";
+const DATETIME_TIME_PATTERN = "HH:mm:ss";
+const DATETIME_LOCALIZED_PATTERN = "HH:mm:ss, d MMMM yyyy";
+//#endregion
+//#region src/datetime/datetime.utilities.ts
 /**
 * Projects the current instant onto the wall-clock fields of another timezone.
 * The timezone defaults to `Europe/London` when no option is provided.
@@ -54,7 +50,7 @@ function failure({ status, error }) {
 * @example
 * const londonTime = getZonedTime({ tz: 'Europe/London' });
 */
-function getZonedTime({ tz = "Europe/London" } = {}) {
+function getZonedTime({ tz = DEFAULT_DATETIME_TIMEZONE } = {}) {
 	return toZonedTime(/* @__PURE__ */ new Date(), tz);
 }
 /**
@@ -75,9 +71,10 @@ function getUTCOffset(date, tz) {
 * @example
 * getFormattedTime({ tz: 'Europe/Moscow' }); // `03:04:05 (+3 UTC)`
 */
-function getFormattedTime({ tz = "Europe/London" } = {}) {
-	const zonedTime = getZonedTime({ tz });
-	return `${format(zonedTime, "HH:mm:ss")} ${getUTCOffset(zonedTime, tz)}`;
+function getFormattedTime({ tz = DEFAULT_DATETIME_TIMEZONE } = {}) {
+	const currentTime = /* @__PURE__ */ new Date();
+	const zonedTime = toZonedTime(currentTime, tz);
+	return `${format(zonedTime, DATETIME_TIME_PATTERN)} ${getUTCOffset(currentTime, tz)}`;
 }
 /**
 * Formats the current date with optional time and UTC offset components.
@@ -86,9 +83,10 @@ function getFormattedTime({ tz = "Europe/London" } = {}) {
 * @example
 * getFormattedDate({ tz: 'UTC', withTime: false }); // `02.01.2024`
 */
-function getFormattedDate({ tz = "Europe/London", withTime = true } = {}) {
-	const zonedTime = getZonedTime({ tz });
-	return `${format(zonedTime, withTime ? "dd.MM.yyyy HH:mm:ss" : "dd.MM.yyyy")}${withTime ? ` ${getUTCOffset(zonedTime, tz)}` : ""}`;
+function getFormattedDate({ tz = DEFAULT_DATETIME_TIMEZONE, withTime = true } = {}) {
+	const currentTime = /* @__PURE__ */ new Date();
+	const zonedTime = toZonedTime(currentTime, tz);
+	return `${format(zonedTime, withTime ? `${DATETIME_DATE_PATTERN} ${DATETIME_TIME_PATTERN}` : DATETIME_DATE_PATTERN)}${withTime ? ` ${getUTCOffset(currentTime, tz)}` : ""}`;
 }
 /**
 * Formats an explicit instant in another timezone using the selected locale.
@@ -97,175 +95,221 @@ function getFormattedDate({ tz = "Europe/London", withTime = true } = {}) {
 * @example
 * formatTime(date, { locale: ru, tz: 'Europe/Moscow' });
 */
-function formatTime(time, { locale = ru, tz = "Europe/London" } = {}) {
+function formatTime(time, options = {}) {
+	const { locale = ru, tz = DEFAULT_DATETIME_TIMEZONE } = options;
 	const zonedTime = toZonedTime(time, tz);
-	return `${format(zonedTime, "HH:mm:ss, d MMMM yyyy", { locale })} ${getUTCOffset(zonedTime, tz)}`;
+	return `${format(zonedTime, DATETIME_LOCALIZED_PATTERN, { locale })} ${getUTCOffset(time, tz)}`;
 }
 //#endregion
-//#region src/utilities/enums.utilities.ts
+//#region src/drizzle/drizzle.errors.ts
+const drizzleErrors = {
+	whereConditionsRequired: () => /* @__PURE__ */ new Error("whereConditionsRequired"),
+	whereColumnNotFound: () => /* @__PURE__ */ new Error("whereColumnNotFound")
+};
+//#endregion
+//#region src/drizzle/drizzle.refiners.ts
 /**
-* Creates an immutable enum-like record from a readonly string array.
-* Keys are uppercased and every dot or hyphen is replaced with an underscore.
+* Builds a Drizzle `WHERE` clause by combining defined object entries with `and`.
+* Keys and values follow the table model while empty conditions remain forbidden.
 *
 * @example
-* createStringEnumRecord(['foo-bar.s', 'baz'] as const); // `{ FOO_BAR_S: 'foo-bar.s', BAZ: 'baz' }`
+* await db.update(usersTable).set(values).where(sqlWhere(usersTable, { id: 1 })).returning();
 */
-function createStringEnumRecord(values) {
-	return Object.freeze(Object.fromEntries(values.map((value) => [value.replaceAll(/[.-]/g, "_").toUpperCase(), value])));
+function sqlWhere(table, where) {
+	const columns = getTableColumns(table);
+	const conditions = Object.entries(where).filter(([, value]) => value !== void 0).map(([key, value]) => {
+		const column = columns[key];
+		if (column === void 0) throw drizzleErrors.whereColumnNotFound();
+		return value === null ? isNull(column) : eq(column, value);
+	});
+	const condition = and(...conditions);
+	if (condition === void 0) throw drizzleErrors.whereConditionsRequired();
+	return condition;
 }
 //#endregion
-//#region src/logging/logging.enums.ts
-const logLevelsArray = [
-	"info",
-	"warn",
-	"error"
-];
-const logLevelsRecord = createStringEnumRecord(logLevelsArray);
-const logLevel = logLevelsRecord;
-//#endregion
-//#region src/logging/logging.constants.ts
+//#region src/execution/execution.constants.ts
 /**
-* Terminal color configuration for every supported logging level.
-* The `LogLevel` contract prevents missing or unsupported level entries.
+* Default total attempt count applied when `retryExecution` receives no override.
+* The value includes the initial operation and every subsequent retry attempt.
 */
-const logLevelColors = {
-	[logLevel.INFO]: blue,
-	[logLevel.WARN]: yellow,
-	[logLevel.ERROR]: red
+const DEFAULT_RETRY_MAX_ATTEMPTS = 3;
+//#endregion
+//#region src/execution/execution.errors.ts
+const executionErrors = {
+	invalidMaxAttempts: () => /* @__PURE__ */ new RangeError("invalidMaxAttempts"),
+	invalidRetryDelay: () => /* @__PURE__ */ new RangeError("invalidRetryDelay"),
+	invalidTimeout: () => /* @__PURE__ */ new RangeError("invalidTimeout"),
+	executionTimedOut: () => new DOMException("executionTimedOut", "TimeoutError")
 };
+//#endregion
+//#region src/execution/execution.measurements.ts
 /**
-* Public placeholder written instead of sensitive query and JSON values.
-* One stable marker keeps redacted output recognizable across log consumers.
+* Measures a synchronous or asynchronous execution while preserving its resolved result.
+* Rejected operations propagate unchanged and never produce a measurement result.
+*
+* @example
+* const { result, executionTime } = await measureExecutionTime(async () => {
+*    return await fetchData();
+* });
+* console.log(`Execution time: ${executionTime}ms`);
 */
-const REDACTED_LOG_VALUE = "[redacted]";
+async function measureExecutionTime(execution) {
+	const startedAt = performance.now();
+	const result = await execution();
+	const executionTime = performance.now() - startedAt;
+	return {
+		result,
+		executionTime: Math.round(executionTime)
+	};
+}
+//#endregion
+//#region src/execution/execution.validation.ts
 /**
-* Normalized key fragments treated as sensitive by logging redaction.
-* Matching ignores case and separators so compound field names remain covered.
+* Validates one resolved delay before a retry timer is allocated.
+* Only finite non-negative millisecond durations are accepted.
 */
-const sensitiveLogKeyParts = [
-	"password",
-	"passwd",
-	"token",
-	"secret",
-	"authorization",
-	"apikey",
-	"credential"
-];
+function validateRetryDelay(delayMilliseconds) {
+	if (Number.isFinite(delayMilliseconds) === false || delayMilliseconds < 0) throw executionErrors.invalidRetryDelay();
+}
 /**
-* Terminal colors assigned to the supported HTTP response status ranges.
-* Unlisted ranges intentionally retain the terminal's default text appearance.
+* Validates static retry policy values before the first operation attempt.
+* Dynamic delay values remain validated after their resolver completes.
 */
-const httpStatusColors = [
-	{
-		range: [200, 299],
-		color: green
-	},
-	{
-		range: [400, 499],
-		color: yellow
-	},
-	{
-		range: [500, 599],
-		color: red
-	}
-];
-//#endregion
-//#region src/logging/logging.services.ts
-function writeLog(message, level, service = "log", stack) {
-	const timestamp = dim(getFormattedTime());
-	const serviceName = logLevelColors[level](service.padEnd(12));
-	const formattedMessage = white(message);
-	console.log(`[${timestamp}] ${serviceName} | ${formattedMessage}`);
-	if (stack) console.log(`[${timestamp}] ${red("↳ trace").padEnd(18)} | ${dim(stack)}`);
+function validateRetryExecutionOptions(options, maxAttempts) {
+	if (Number.isInteger(maxAttempts) === false || maxAttempts < 1) throw executionErrors.invalidMaxAttempts();
+	if (typeof options.delayMilliseconds === "number") validateRetryDelay(options.delayMilliseconds);
 }
 /**
-* Writes timestamped and colorized messages using a stable service column.
-* Error messages may include a stack trace on a subordinate second line.
+* Validates the duration used to bound an execution with a timeout.
+* Only finite non-negative millisecond durations are accepted.
 */
-const 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.
-	* Provided stack traces are rendered beneath the primary message.
-	*/
-	error(message, service, stack) {
-		writeLog(message, "error", service, stack);
-	}
-};
+function validateExecutionTimeout(timeoutMilliseconds) {
+	if (Number.isFinite(timeoutMilliseconds) === false || timeoutMilliseconds < 0) throw executionErrors.invalidTimeout();
+}
 //#endregion
-//#region src/utilities/generation.utilities.ts
-const DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+//#region src/execution/execution.retry.ts
+/**
+* Waits for a retry delay while preserving cooperative caller cancellation.
+* Zero-duration delays resolve immediately without allocating a timer.
+*/
+async function waitForRetry(delayMilliseconds, signal) {
+	validateRetryDelay(delayMilliseconds);
+	signal?.throwIfAborted();
+	if (delayMilliseconds === 0) return;
+	await new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timeout);
+			reject(signal?.reason);
+		};
+		const timeout = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, delayMilliseconds);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
 /**
-* Creates a cryptographically sourced string from the alphanumeric set.
-* Requested length defaults to `10` characters when omitted.
-*
-* @example
-* generateRandomString(5); // `aZ3fG`
-* generateRandomString(); // `G5kLm2P9sQ`
+* Repeats a failed operation under explicit attempt, delay, and filtering policies.
+* Exhaustion, rejected filtering, and cancellation preserve the original failure.
 */
-function generateRandomString(length = 10) {
-	const randomValues = crypto.getRandomValues(new Uint32Array(length));
-	let result = "";
-	for (let i = 0; i < length; i++) result += DEFAULT_CHARACTERS[randomValues[i] % 62];
-	return result;
+async function retryExecution(execution, options = {}) {
+	const { shouldRetry, signal } = options;
+	const { maxAttempts = 3, delayMilliseconds = 0 } = options;
+	validateRetryExecutionOptions(options, maxAttempts);
+	for (let attempt = 1;; attempt += 1) {
+		signal?.throwIfAborted();
+		try {
+			return await execution({
+				attempt,
+				signal
+			});
+		} catch (error) {
+			const isMaxAttempts = attempt === maxAttempts;
+			const isRetryRejected = isMaxAttempts === false && shouldRetry ? await shouldRetry(error, attempt) === false : false;
+			if (isMaxAttempts || isRetryRejected) throw error;
+			signal?.throwIfAborted();
+			await waitForRetry(typeof delayMilliseconds === "function" ? await delayMilliseconds(error, attempt) : delayMilliseconds, signal);
+		}
+	}
 }
 //#endregion
-//#region src/hono/hono.execution.ts
-function proceedUnhandledError(error) {
-	const errorId = generateRandomString(6);
-	const errorMessage = error instanceof Error ? error.stack ?? error.message : JSON.stringify(error);
-	log.error(`Unhandled error: ${red(errorMessage)}`, errorId);
-	return failure({
-		status: 500,
-		error: `Internal server error | ${errorId}`
+//#region src/execution/execution.timeout.ts
+/**
+* Runs an operation with a signal controlled by timeout and caller cancellation.
+* The promise rejects promptly even when the operation ignores its abort signal.
+*/
+async function executeWithTimeout(execution, options) {
+	const { timeoutMilliseconds, signal: callerSignal } = options;
+	validateExecutionTimeout(timeoutMilliseconds);
+	const controller = new AbortController();
+	const forwardCallerAbort = () => controller.abort(callerSignal?.reason);
+	const rejectOnAbort = () => rejectAbortedExecution?.(controller.signal.reason);
+	let rejectAbortedExecution;
+	if (callerSignal?.aborted) controller.abort(callerSignal.reason);
+	else callerSignal?.addEventListener("abort", forwardCallerAbort, { once: true });
+	controller.signal.throwIfAborted();
+	const timeout = setTimeout(() => {
+		controller.abort(executionErrors.executionTimedOut());
+	}, timeoutMilliseconds);
+	const abortedExecution = new Promise((_, reject) => {
+		rejectAbortedExecution = reject;
+		if (controller.signal.aborted) reject(controller.signal.reason);
+		else controller.signal.addEventListener("abort", rejectOnAbort, { once: true });
 	});
+	try {
+		const executionPromise = Promise.resolve(execution(controller.signal));
+		return await Promise.race([executionPromise, abortedExecution]);
+	} finally {
+		clearTimeout(timeout);
+		callerSignal?.removeEventListener("abort", forwardCallerAbort);
+		controller.signal.removeEventListener("abort", rejectOnAbort);
+	}
 }
+//#endregion
+//#region src/execution/execution.utilities.ts
 /**
-* Converts expected `HTTPException` values into shared API error envelopes.
-* Unexpected failures are logged and represented by a traceable generic response.
+* Resolves synchronous and asynchronous operations through one promise-based contract.
+* Failures use the supplied fallback or propagate unchanged when none is available.
+*
+* @example
+* await safeExecute(() => fetchData(), (error) => console.error(error));
 */
-const onHandlerError = (error, c) => {
-	let response;
-	if (error instanceof HTTPException && error.status < 500) response = failure({
-		status: error.status,
-		error: error.message
-	});
-	else response = proceedUnhandledError(error);
-	return c.json(response, response.status);
-};
-//#endregion
-//#region src/hono/hono.respond.ts
+async function safeExecute(fn, onError) {
+	try {
+		return await fn();
+	} catch (error) {
+		if (onError) return await onError(error);
+		throw error;
+	}
+}
 /**
-* 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.
+* Captures a synchronous or asynchronous operation in a discriminated result.
+* Successful values and original unknown failures remain available unchanged.
 */
-function respond(c, options) {
-	return c.json(success({
-		status: options.status,
-		data: options.data ?? {}
-	}), options.status);
+async function captureExecution(execution) {
+	try {
+		return {
+			success: true,
+			data: await execution()
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error
+		};
+	}
 }
+//#endregion
+//#region src/string-enum/string-enum.utilities.ts
 /**
-* Responds with downloadable binary content and its attachment headers.
-* Unknown/undefined content types default to `application/octet-stream`.
+* Creates an immutable enum-like record from a readonly string array.
+* Keys become upper snake case across camelCase, dotted, and hyphenated values.
+*
+* @example
+* createStringEnumRecord(['foo-bar.s', 'baz'] as const); // `{ FOO_BAR_S: 'foo-bar.s', BAZ: 'baz' }`
 */
-function fileRespond(c, options) {
-	c.header("Content-Disposition", `attachment; filename="${options.filename}"`);
-	c.header("Content-Type", options.contentType ?? "application/octet-stream");
-	return c.body(options.content, options.status);
+function createStringEnumRecord(values) {
+	return Object.freeze(Object.fromEntries(values.map((value) => [value.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").replaceAll(/[.-]/g, "_").toUpperCase(), value])));
 }
 //#endregion
 //#region src/hmac/hmac.enums.ts
@@ -296,25 +340,13 @@ const DEFAULT_HMAC_ALGORITHM = hmacAlgorithm.SHA_256;
 */
 const DEFAULT_HMAC_ENCODING = hmacEncoding.HEX;
 //#endregion
-//#region src/utilities/encoding.utilities.ts
-const BASE64_BYTE_CHUNK_SIZE = 32768;
-/**
-* Encodes arbitrary binary bytes into their canonical Base64 representation.
-* Chunked conversion avoids the argument limit imposed by `String.fromCharCode`.
-*/
-function encodeBase64(bytes) {
-	let binary = "";
-	for (let offset = 0; offset < bytes.length; offset += BASE64_BYTE_CHUNK_SIZE) binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_BYTE_CHUNK_SIZE));
-	return btoa(binary);
-}
-/**
-* Decodes a canonical or padded Base64 string into its original binary bytes.
-* Invalid input preserves the native `atob` failure instead of returning partial data.
-*/
-function decodeBase64(value) {
-	const binary = atob(value);
-	return Uint8Array.from(binary, (character) => character.charCodeAt(0));
-}
+//#region src/hmac/hmac.errors.ts
+const hmacErrors = {
+	invalidHexSignature: () => /* @__PURE__ */ new TypeError("invalidHexSignature"),
+	invalidBase64Signature: () => /* @__PURE__ */ new TypeError("invalidBase64Signature"),
+	invalidBase64UrlSignature: () => /* @__PURE__ */ new TypeError("invalidBase64UrlSignature"),
+	incompatibleCryptoKey: () => /* @__PURE__ */ new TypeError("incompatibleCryptoKey")
+};
 //#endregion
 //#region src/hmac/hmac.utilities.ts
 const textEncoder = new TextEncoder();
@@ -333,10 +365,12 @@ function toHMACBytes(input) {
 * Hex output remains lowercase while Base64 URL output omits conventional padding.
 */
 function encodeHMACSignature(signature, encoding) {
-	if (encoding === "hex") return Array.from(signature, (byte) => byte.toString(16).padStart(2, "0")).join("");
-	const base64 = encodeBase64(signature);
-	if (encoding === "base64") return base64;
-	return base64.replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+	if (encoding === "hex") return signature.toHex();
+	if (encoding === "base64") return signature.toBase64();
+	return signature.toBase64({
+		alphabet: "base64url",
+		omitPadding: true
+	});
 }
 /**
 * Decodes a textual HMAC signature into bytes for cryptographic verification.
@@ -344,15 +378,15 @@ function encodeHMACSignature(signature, encoding) {
 */
 function decodeHMACSignature(signature, encoding) {
 	if (encoding === "hex") {
-		if (signature.length % 2 !== 0 || !/^[0-9a-f]*$/i.test(signature)) throw new TypeError("Invalid hexadecimal HMAC signature");
-		return Uint8Array.from(signature.match(/.{2}/g) ?? [], (byte) => Number.parseInt(byte, 16));
+		if (signature.length % 2 !== 0 || /^[0-9a-f]*$/i.test(signature) === false) throw hmacErrors.invalidHexSignature();
+		return Uint8Array.fromHex(signature);
 	}
 	if (encoding === "base64") {
-		if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(signature)) throw new TypeError("Invalid Base64 HMAC signature");
-		return decodeBase64(signature);
+		if (/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(signature) === false) throw hmacErrors.invalidBase64Signature();
+		return Uint8Array.fromBase64(signature, { lastChunkHandling: "strict" });
 	}
-	if (!/^[A-Za-z0-9_-]*$/.test(signature) || signature.length % 4 === 1) throw new TypeError("Invalid Base64 URL HMAC signature");
-	return decodeBase64(signature.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(signature.length / 4) * 4, "="));
+	if (/^[A-Za-z0-9_-]*$/.test(signature) === false || signature.length % 4 === 1) throw hmacErrors.invalidBase64UrlSignature();
+	return Uint8Array.fromBase64(signature, { alphabet: "base64url" });
 }
 //#endregion
 //#region src/hmac/hmac.services.ts
@@ -368,20 +402,32 @@ var HMACService = class {
 		this.encoding = options.encoding ?? DEFAULT_HMAC_ENCODING;
 	}
 	/**
+	* Imports raw secret material as a non-extractable Web Crypto HMAC key.
+	* The resulting key supports repeated signing and verification without reimporting.
+	*/
+	async importKey(secret) {
+		const secretBytes = toHMACBytes(secret);
+		const algorithm = {
+			name: "HMAC",
+			hash: this.algorithm
+		};
+		return crypto.subtle.importKey("raw", secretBytes, algorithm, false, ["sign", "verify"]);
+	}
+	/**
 	* Authenticates a payload with a secret and returns the encoded signature.
-	* String inputs use UTF-8 while byte arrays preserve their exact byte sequence.
+	* Imported keys bypass repeated key creation while preserving service policy.
 	*
 	* @example
 	* const signature = await hmacService.sign('payload', 'shared-secret');
 	*/
 	async sign(payload, secret) {
-		const key = await this.importSecret(secret);
+		const key = await this.resolveKey(secret, "sign");
 		const signature = await crypto.subtle.sign("HMAC", key, toHMACBytes(payload));
 		return encodeHMACSignature(new Uint8Array(signature), this.encoding);
 	}
 	/**
 	* Verifies an encoded signature without requiring a manual equality comparison.
-	* Invalid encodings, incorrect secrets, and altered payloads all resolve to `false`.
+	* Invalid signatures resolve to `false`; incompatible imported keys reject explicitly.
 	*
 	* @example
 	* const verified = await hmacService.verify('payload', signature, 'shared-secret');
@@ -393,96 +439,342 @@ var HMACService = class {
 		} catch {
 			return false;
 		}
-		const key = await this.importSecret(secret);
+		const key = await this.resolveKey(secret, "verify");
 		return crypto.subtle.verify("HMAC", key, signatureBytes, toHMACBytes(payload));
 	}
-	async importSecret(secret) {
-		const secretBytes = toHMACBytes(secret);
-		const algorithm = {
-			name: "HMAC",
-			hash: this.algorithm
-		};
-		return crypto.subtle.importKey("raw", secretBytes, algorithm, false, ["sign", "verify"]);
+	async resolveKey(secret, usage) {
+		if (typeof secret === "string" || secret instanceof Uint8Array) return this.importKey(secret);
+		const hash = Reflect.get(secret.algorithm, "hash");
+		const hashName = typeof hash === "object" && hash !== null && "name" in hash ? hash.name : void 0;
+		if ((secret.type === "secret" && secret.algorithm.name === "HMAC" && hashName === this.algorithm && secret.usages.includes(usage)) === false) throw hmacErrors.incompatibleCryptoKey();
+		return secret;
 	}
 };
 //#endregion
-//#region src/http/http.constants.ts
-const SUCCESS_STATUS_CODES = [
+//#region src/hono/hono.constants.ts
+/**
+* Default HTTP header carrying one request identifier across service boundaries.
+* Incoming non-empty values are preserved while missing identifiers are generated.
+*/
+const HONO_REQUEST_ID_HEADER = "X-Request-ID";
+/**
+* Default service label applied to request lines emitted by Hono logging middleware.
+* Configured middleware may replace the label without changing message formatting.
+*/
+const HONO_LOGGING_SERVICE = "hono";
+//#endregion
+//#region src/hono/hono.errors.ts
+const honoErrors = {
+	internalServerError: () => new HTTPException(500, { message: "internalServerError" }),
+	invalidRequestId: () => /* @__PURE__ */ new TypeError("invalidRequestId")
+};
+//#endregion
+//#region src/response/response.enums.ts
+const responseKindsArray = ["success", "error"];
+const responseKindsRecord = createStringEnumRecord(responseKindsArray);
+const responseKind = responseKindsRecord;
+const SUCCESS_RESPONSE_STATUSES = [
 	200,
 	201,
 	202,
-	307
+	206
 ];
-const EXCEPTION_STATUS_CODES = [
+const ERROR_RESPONSE_STATUSES = [
 	400,
 	401,
 	403,
 	404,
 	405,
+	406,
+	408,
 	409,
-	500
+	410,
+	413,
+	414,
+	415,
+	422,
+	425,
+	429,
+	440,
+	498,
+	500,
+	501,
+	502,
+	503,
+	504
 ];
 //#endregion
-//#region src/http/http.errors.ts
+//#region src/response/response.errors.ts
+const responseErrors = {
+	invalidResponseErrorCode: () => /* @__PURE__ */ new TypeError("invalidResponseErrorCode"),
+	invalidSuccessResponseStatus: () => /* @__PURE__ */ new RangeError("invalidSuccessResponseStatus"),
+	invalidErrorResponseStatus: () => /* @__PURE__ */ new RangeError("invalidErrorResponseStatus")
+};
 /**
-* Represents an error envelope rejected by an API request resolver.
-* The original status and typed code remain available for client handling.
+* Represents a failed response rejected while unwrapping a remote operation.
+* The original machine-readable code and response status remain available.
 */
-var APIRequestError = class extends Error {
+var ResponseError = class extends Error {
 	code;
 	status;
 	constructor(status, code) {
 		super(code);
-		this.name = "APIRequestError";
+		this.name = "ResponseError";
 		this.code = code;
 		this.status = status;
 	}
 };
 //#endregion
-//#region src/http/http.resolvers.ts
+//#region src/response/response.validation.ts
 /**
-* Converts an API contract envelope into a mutually exclusive safe result.
-* Only `APIError` values are normalized; rejected fetchers still reject.
+* Determines whether a value is a stable camelCase response error code.
+* Human-readable text and punctuation remain excluded from public envelopes.
 */
-async function fetchSafely(fetcher) {
-	const response = await fetcher();
-	if (response.kind === "error") return {
-		error: response.error,
-		data: null
-	};
-	return {
-		error: null,
-		data: response.data
-	};
+function isResponseErrorCode(value) {
+	return typeof value === "string" && /^[a-z][A-Za-z0-9]*$/.test(value);
 }
 /**
-* Returns successful API data and throws `APIRequestError` for a failed envelope.
-* Transport and programming rejections propagate without replacement.
+* Determines whether a value belongs to the supported success-status catalog.
+* Runtime membership mirrors the exact union exposed by `SuccessResponseStatus`.
 */
-async function fetchAndThrow(fetcher) {
-	const response = await fetcher();
-	if (response.kind === "error") throw new APIRequestError(response.status, response.error);
-	return response.data;
+function isSuccessResponseStatus(value) {
+	return SUCCESS_RESPONSE_STATUSES.some((status) => status === value);
+}
+/**
+* Determines whether a value belongs to the supported error-status catalog.
+* Runtime membership mirrors the exact union exposed by `ErrorResponseStatus`.
+*/
+function isErrorResponseStatus(value) {
+	return ERROR_RESPONSE_STATUSES.some((status) => status === value);
+}
+/**
+* Narrows a response result to its successful branch through the shared discriminator.
+* Payload and error-code generics remain unchanged for downstream control-flow analysis.
+*/
+function isSuccessResponse(response) {
+	return response.kind === responseKind.SUCCESS;
+}
+/**
+* Narrows a response result to its failed branch through the shared discriminator.
+* Payload and error-code generics remain unchanged for downstream control-flow analysis.
+*/
+function isErrorResponse(response) {
+	return response.kind === responseKind.ERROR;
 }
 //#endregion
-//#region src/logging/logging.security.ts
+//#region src/response/response.factories.ts
 /**
-* Checks whether a logging field name contains a configured sensitive fragment.
-* Matching ignores casing and separators to cover compound naming conventions.
+* Creates a successful response envelope without cloning its supplied data.
+* Generic inference preserves the exact payload type for downstream contracts.
 */
-function isSensitiveLogKey(key) {
-	const normalizedKey = key.toLowerCase().replaceAll(/[^a-z]/g, "");
-	return sensitiveLogKeyParts.some((sensitivePart) => normalizedKey.includes(sensitivePart));
+function createSuccessResponse(status, data) {
+	if (isSuccessResponseStatus(status) === false) throw responseErrors.invalidSuccessResponseStatus();
+	return {
+		kind: responseKind.SUCCESS,
+		status,
+		data
+	};
 }
 /**
-* Recursively replaces values owned by sensitive object keys with the public marker.
-* The result reports whether any replacement occurred to avoid needless serialization.
+* Creates a failed response envelope from one stable machine-readable error code.
+* Human-readable or malformed values reject before crossing the response boundary.
 */
-function redactSensitiveValue(value) {
-	if (Array.isArray(value)) {
-		const entries = value.map(redactSensitiveValue);
-		return {
-			value: entries.map((entry) => entry.value),
+function createErrorResponse(status, error) {
+	if (isErrorResponseStatus(status) === false) throw responseErrors.invalidErrorResponseStatus();
+	if (isResponseErrorCode(error) === false) throw responseErrors.invalidResponseErrorCode();
+	return {
+		kind: responseKind.ERROR,
+		status,
+		error
+	};
+}
+//#endregion
+//#region src/response/response.resolvers.ts
+/**
+* Resolves a response envelope into a status-preserving discriminated result.
+* Transport and programming failures remain observable promise rejections.
+*/
+async function resolveResponse(operation) {
+	const response = await operation();
+	if (isErrorResponse(response)) return {
+		success: false,
+		status: response.status,
+		data: null,
+		error: response.error
+	};
+	return {
+		success: true,
+		status: response.status,
+		data: response.data,
+		error: null
+	};
+}
+/**
+* Unwraps successful response data and throws `ResponseError` for a failed envelope.
+* Transport and programming failures propagate without replacement or normalization.
+*/
+async function unwrapResponse(operation) {
+	const response = await operation();
+	if (isErrorResponse(response)) throw new ResponseError(response.status, response.error);
+	return response.data;
+}
+//#endregion
+//#region src/hono/hono.request-id.ts
+/**
+* Resolves a request identifier from response metadata before its incoming header.
+* This ordering exposes identifiers generated by the request middleware downstream.
+*/
+function getHonoRequestId(context, header = HONO_REQUEST_ID_HEADER) {
+	return (context.res.headers.get(header) ?? context.req.header(header))?.trim() || void 0;
+}
+/**
+* Creates middleware that preserves or generates one request correlation identifier.
+* The resolved value is returned on the response and remains available to Hono adapters.
+*/
+function createRequestIdMiddleware(options = {}) {
+	const header = options.header ?? "X-Request-ID";
+	const createRequestId = options.createRequestId ?? (() => crypto.randomUUID());
+	return async (context, next) => {
+		const incomingRequestId = context.req.header(header)?.trim();
+		const generatedRequestId = incomingRequestId ? void 0 : createRequestId();
+		const requestId = typeof generatedRequestId === "string" ? generatedRequestId.trim() : incomingRequestId;
+		if (requestId === void 0 || requestId.length === 0) throw honoErrors.invalidRequestId();
+		context.header(header, requestId);
+		await next();
+		context.header(header, requestId);
+	};
+}
+/**
+* Ready-to-use request identifier middleware backed by the shared default policy.
+* Applications may use the factory when a custom header or generator is required.
+*/
+const requestIdMiddleware = createRequestIdMiddleware();
+//#endregion
+//#region src/hono/hono.execution.ts
+/**
+* Identifies client HTTP exceptions safe to expose through the shared response envelope.
+* Both status membership and camelCase error-code syntax must satisfy the contract.
+*/
+function isExpectedHTTPException(error) {
+	if (error instanceof HTTPException === false) return false;
+	if (error.status >= 500) return false;
+	const isSupportedStatus = isErrorResponseStatus(error.status);
+	const isMachineReadableCode = isResponseErrorCode(error.message);
+	return isSupportedStatus && isMachineReadableCode;
+}
+/**
+* Creates a Hono error handler that preserves expected machine-readable exceptions.
+* Unexpected failures invoke application reporting before returning a stable fallback.
+*/
+function createHonoErrorHandler(options) {
+	return (error, context) => {
+		if (isExpectedHTTPException(error)) {
+			const response = createErrorResponse(error.status, error.message);
+			return context.json(response, response.status);
+		}
+		options.onUnexpectedError(error, context, getHonoRequestId(context));
+		const fallback = honoErrors.internalServerError();
+		const status = fallback.status;
+		const response = createErrorResponse(status, fallback.message);
+		return context.json(response, status);
+	};
+}
+//#endregion
+//#region src/logging/logging.enums.ts
+const logLevelsArray = [
+	"info",
+	"warn",
+	"error"
+];
+const logLevelsRecord = createStringEnumRecord(logLevelsArray);
+const logLevel = logLevelsRecord;
+//#endregion
+//#region src/logging/logging.constants.ts
+/**
+* Terminal color configuration for every supported logging level.
+* The `LogLevel` contract prevents missing or unsupported level entries.
+*/
+const logLevelColors = {
+	[logLevel.INFO]: blue,
+	[logLevel.WARN]: yellow,
+	[logLevel.ERROR]: red
+};
+/**
+* Public placeholder written instead of sensitive query and JSON values.
+* One stable marker keeps redacted output recognizable across log consumers.
+*/
+const REDACTED_LOG_VALUE = "[redacted]";
+/**
+* Number of characters retained from each edge of an oversized request body.
+* The complete preview includes both edges separated by one explicit ellipsis.
+*/
+const LOG_BODY_PREVIEW_EDGE_LENGTH = 30;
+/**
+* Safe request-body placeholder emitted instead of reading multipart content.
+* Avoiding multipart reads prevents file payloads from entering logs or memory copies.
+*/
+const MULTIPART_LOG_BODY = "[multipart]";
+/**
+* Normalized key fragments treated as sensitive by logging redaction.
+* Matching ignores case and separators so compound field names remain covered.
+*/
+const sensitiveLogKeyParts = [
+	"password",
+	"passwd",
+	"token",
+	"secret",
+	"authorization",
+	"apikey",
+	"credential"
+];
+/**
+* Terminal colors assigned to the supported HTTP response status ranges.
+* Unlisted ranges intentionally retain the terminal's default text appearance.
+*/
+const httpStatusColors = [
+	{
+		range: [200, 299],
+		color: green
+	},
+	{
+		range: [400, 499],
+		color: yellow
+	},
+	{
+		range: [500, 599],
+		color: red
+	}
+];
+//#endregion
+//#region src/logging/logging.errors.ts
+const loggingErrors = { invalidBodyPreviewEdgeLength: () => /* @__PURE__ */ new RangeError("invalidBodyPreviewEdgeLength") };
+//#endregion
+//#region src/logging/logging.security.ts
+/**
+* Checks whether a logging field name contains a configured sensitive fragment.
+* Matching ignores casing and separators to cover compound naming conventions.
+*/
+function isSensitiveLogKey(key) {
+	const normalizedKey = key.toLowerCase().replaceAll(/[^a-z]/g, "");
+	return sensitiveLogKeyParts.some((sensitivePart) => normalizedKey.includes(sensitivePart));
+}
+/**
+* Recursively replaces values owned by sensitive object keys with the public marker.
+* The result reports whether any replacement occurred to avoid needless serialization.
+*/
+function redactSensitiveValueResult(value, seenValues = /* @__PURE__ */ new WeakMap()) {
+	if (Array.isArray(value)) {
+		const existingValue = seenValues.get(value);
+		if (existingValue) return {
+			value: existingValue,
+			redacted: false
+		};
+		const redactedValue = [];
+		seenValues.set(value, redactedValue);
+		const entries = value.map((entry) => redactSensitiveValueResult(entry, seenValues));
+		redactedValue.push(...entries.map((entry) => entry.value));
+		return {
+			value: redactedValue,
 			redacted: entries.some((entry) => entry.redacted)
 		};
 	}
@@ -490,28 +782,48 @@ function redactSensitiveValue(value) {
 		value,
 		redacted: false
 	};
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return {
+		value,
+		redacted: false
+	};
+	const existingValue = seenValues.get(value);
+	if (existingValue) return {
+		value: existingValue,
+		redacted: false
+	};
 	let redacted = false;
-	const entries = Object.entries(value).map(([key, entryValue]) => {
+	const redactedValue = Object.create(prototype);
+	seenValues.set(value, redactedValue);
+	for (const [key, entryValue] of Object.entries(value)) {
 		if (isSensitiveLogKey(key)) {
 			redacted = true;
-			return [key, REDACTED_LOG_VALUE];
+			redactedValue[key] = REDACTED_LOG_VALUE;
+			continue;
 		}
-		const nestedEntry = redactSensitiveValue(entryValue);
+		const nestedEntry = redactSensitiveValueResult(entryValue, seenValues);
 		redacted ||= nestedEntry.redacted;
-		return [key, nestedEntry.value];
-	});
+		redactedValue[key] = nestedEntry.value;
+	}
 	return {
-		value: Object.fromEntries(entries),
+		value: redactedValue,
 		redacted
 	};
 }
 /**
+* Recursively replaces values owned by sensitive keys in an arbitrary structure.
+* Arrays and safe values retain their original ordering and primitive identity.
+*/
+function redactSensitiveValue(value) {
+	return redactSensitiveValueResult(value).value;
+}
+/**
 * Replaces sensitive query values using partial, case-insensitive key matching.
 * A new collection is returned so the caller's search parameters remain unchanged.
 */
 function redactSensitiveSearchParams(searchParams) {
-	const redactedSearchParams = new URLSearchParams(searchParams);
-	for (const key of new Set(redactedSearchParams.keys())) if (isSensitiveLogKey(key)) redactedSearchParams.set(key, REDACTED_LOG_VALUE);
+	const redactedSearchParams = new URLSearchParams();
+	for (const [key, value] of searchParams) redactedSearchParams.append(key, isSensitiveLogKey(key) ? REDACTED_LOG_VALUE : value);
 	return redactedSearchParams;
 }
 /**
@@ -519,9 +831,8 @@ function redactSensitiveSearchParams(searchParams) {
 * Invalid JSON and payloads without matching keys are returned byte-for-byte unchanged.
 */
 function redactSensitiveJSON(json) {
-	if (json === void 0 || null) return json;
 	try {
-		const result = redactSensitiveValue(JSON.parse(json));
+		const result = redactSensitiveValueResult(JSON.parse(json));
 		return result.redacted ? JSON.stringify(result.value) : json;
 	} catch {
 		return json;
@@ -530,6 +841,15 @@ function redactSensitiveJSON(json) {
 //#endregion
 //#region src/logging/logging.utilities.ts
 /**
+* Extracts useful trace context from an unknown failure without inventing a message.
+* Strings pass through directly, while native errors prefer their complete stack.
+*/
+function normalizeLogError(error) {
+	if (typeof error === "string") return error;
+	if (error instanceof Error === false) return void 0;
+	return error.stack ?? error.message;
+}
+/**
 * Selects a terminal color function for one HTTP response status.
 * Successes are green, client errors yellow, and server errors red.
 */
@@ -539,358 +859,205 @@ function getColoredHTTPStatus(status) {
 	});
 	return statusColor ? statusColor.color : (text) => text;
 }
-//#endregion
-//#region src/logging/logging.middleware.ts
-/**
-* Logs Hono request metadata with query parameters and a normalized body preview.
-* Sensitive values are redacted by partial key match before output is written.
-*/
-const loggingMiddleware = async (c, next) => {
-	const contentType = c.req.header("content-type");
-	const searchParams = redactSensitiveSearchParams(new URL(c.req.url).searchParams).toString();
-	const body = contentType?.includes("multipart/form-data") ? "[multipart]" : redactSensitiveJSON((await c.req.raw.clone().text()).replaceAll(/\s+/g, " ").trim());
-	const bodyPreview = body.length > 60 ? `${body.slice(0, 30)}…${body.slice(-30)}` : body;
-	const startTime = performance.now();
-	await next();
-	const duration = Math.round(performance.now() - startTime);
-	const coloredMethod = bold(blue(c.req.method.padEnd(4)));
-	const coloredStatus = getColoredHTTPStatus(c.res.status)(String(c.res.status).padEnd(4));
-	const coloredTime = dim(`${duration}ms`.padStart(6));
-	const coloredPath = white(c.req.path.padEnd(32));
-	const coloredSearchParams = searchParams ? dim(` (${searchParams})`) : "";
-	const coloredBody = bodyPreview ? dim(` ${bodyPreview}`) : "";
-	log.info(`${coloredMethod} ${coloredStatus} ${coloredTime} ${coloredPath}${coloredSearchParams}${coloredBody}`, "hono");
-};
-//#endregion
-//#region src/upload/upload.enums.ts
-const fileFormatsArray = [...[
-	"png",
-	"jpg",
-	"webp",
-	"avif",
-	"heic",
-	"svg"
-], ...[
-	"pdf",
-	"rtf",
-	"txt"
-]];
-const fileFormatsRecord = createStringEnumRecord(fileFormatsArray);
-const fileFormat = fileFormatsRecord;
-const uploadValidationErrorsArray = [
-	"empty_file",
-	"unsupported_file_format",
-	"file_size_exceeded",
-	"files_count_exceeded"
-];
-const uploadValidationErrorsRecord = createStringEnumRecord(uploadValidationErrorsArray);
-const uploadValidationError = uploadValidationErrorsRecord;
-//#endregion
-//#region src/upload/upload.constants.ts
 /**
-* Canonical metadata shared by upload controls and runtime validation.
-* Every supported format defines display, MIME, and extension values.
+* Formats one completed HTTP request as a compact colorized terminal line.
+* Empty query and body values are omitted without disturbing column alignment.
 */
-const fileFormatsConfig = {
-	[fileFormatsRecord.PNG]: {
-		name: "PNG",
-		mimeTypes: ["image/png"],
-		extensions: [".png"]
-	},
-	[fileFormatsRecord.JPG]: {
-		name: "JPG",
-		mimeTypes: ["image/jpeg"],
-		extensions: [".jpg", ".jpeg"]
-	},
-	[fileFormatsRecord.SVG]: {
-		name: "SVG",
-		mimeTypes: ["image/svg+xml"],
-		extensions: [".svg"]
-	},
-	[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"]
-	},
-	[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"]
-	}
-};
-//#endregion
-//#region src/upload/upload.factory.ts
-/**
-* Defines one shared upload policy while preserving its literal format tuple.
-* The resulting preset can drive schemas, picker hints, and batch validation.
-*
-* @example
-* const imageUploadPreset = defineUploadPreset({
-*   formats: [fileFormat.JPG, fileFormat.PNG, fileFormat.WEBP],
-*   maxFileSize: 8 * 1024 * 1024,
-*   maxFilesCount: 1,
-* });
-*/
-function defineUploadPreset(preset) {
-	return preset;
+function formatHTTPRequestLog(options) {
+	return `${bold(blue(options.method.padEnd(4)))} ${getColoredHTTPStatus(options.status)(String(options.status).padEnd(4))} ${dim(`${options.duration}ms`.padStart(6))} ${white(options.path.padEnd(32))}${options.searchParams ? dim(` (${options.searchParams})`) : ""}${options.bodyPreview ? dim(` ${options.bodyPreview}`) : ""}${options.requestId ? dim(` [${options.requestId}]`) : ""}`;
 }
-//#endregion
-//#region src/upload/upload.presets.ts
-/**
-* Default maximum size of one file accepted by the built-in upload presets.
-* The 20 MiB boundary matches the existing upload component policy.
-*/
-const DEFAULT_UPLOAD_MAX_FILE_SIZE = 20971520;
-/**
-* 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.
-*/
-const imageUploadPreset = defineUploadPreset({
-	formats: [
-		fileFormat.PNG,
-		fileFormat.JPG,
-		fileFormat.WEBP,
-		fileFormat.AVIF,
-		fileFormat.HEIC
-	],
-	maxFileSize: DEFAULT_UPLOAD_MAX_FILE_SIZE
-});
-/**
-* Ready-to-use policy for every image format supporting transparency (alpha channel).
-* Each image may occupy up to 20 MiB while collection capacity remains unrestricted.
-*/
-const imageTransparentUploadPreset = defineUploadPreset({
-	formats: [
-		fileFormat.PNG,
-		fileFormat.WEBP,
-		fileFormat.SVG
-	],
-	maxFileSize: DEFAULT_UPLOAD_MAX_FILE_SIZE
-});
-/**
-* 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.
-*/
-const documentUploadPreset = defineUploadPreset({
-	formats: [
-		fileFormat.PDF,
-		fileFormat.RTF,
-		fileFormat.TXT
-	],
-	maxFileSize: DEFAULT_UPLOAD_MAX_FILE_SIZE
-});
-//#endregion
-//#region src/upload/upload.utilities.ts
 /**
-* Extracts a normalized trailing extension from a complete file name.
-* Returns an empty string when no valid dot-delimited suffix exists.
+* Reads one request clone and returns a normalized, redacted, and bounded body preview.
+* Multipart requests return a safe marker without reading or retaining uploaded content.
 */
-function getFileExtension(fileName) {
-	const extensionIndex = fileName.lastIndexOf(".");
-	return extensionIndex > 0 && extensionIndex < fileName.length - 1 ? fileName.slice(extensionIndex).toLowerCase() : "";
-}
-/**
-* Normalizes a configured extension to a lowercase dot-prefixed value.
-* Existing prefixes remain intact so repeated normalization is stable.
-*/
-function normalizeFileExtension(extension) {
-	const normalizedExtension = extension.toLowerCase();
-	return normalizedExtension.startsWith(".") ? normalizedExtension : `.${normalizedExtension}`;
-}
-/**
-* Compares a concrete MIME type with an exact or wildcard configuration.
-* Wildcards match every subtype belonging to the configured media group.
-*/
-function matchesMimeType(fileMimeType, configuredMimeType) {
-	if (configuredMimeType.endsWith("/*")) return fileMimeType.startsWith(configuredMimeType.slice(0, -1));
-	return fileMimeType === configuredMimeType;
+async function createHTTPRequestBodyPreview(request, contentType, edgeLength = 30) {
+	if (Number.isInteger(edgeLength) === false || edgeLength < 1) throw loggingErrors.invalidBodyPreviewEdgeLength();
+	if (contentType?.includes("multipart/form-data")) return MULTIPART_LOG_BODY;
+	const redactedBody = redactSensitiveJSON((await request.clone().text()).replaceAll(/\s+/g, " ").trim());
+	if (redactedBody.length <= edgeLength * 2) return redactedBody;
+	return `${redactedBody.slice(0, edgeLength)}…${redactedBody.slice(-edgeLength)}`;
 }
+//#endregion
+//#region src/logging/logging.services.ts
 /**
-* Checks whether a file MIME type belongs to one selected format.
-* File names and extensions cannot make an unsupported MIME type valid.
+* Writes one fully formatted logging line through the standard console destination.
+* Keeping the sink explicit allows configured loggers to replace output independently.
 */
-function isFileMimeTypeSupported(file, formats) {
-	return formats.some((format) => fileFormatsConfig[format].mimeTypes.some((mimeType) => matchesMimeType(file.type, mimeType)));
+function writeConsoleLog(line) {
+	console.log(line);
 }
 /**
-* Checks whether a file extension belongs to one selected format.
-* The comparison is case-insensitive and requires a complete suffix.
+* Writes one normalized terminal message for the requested logging level and service.
+* Recognized error context retains the primary timestamp on a subordinate aligned line.
 */
-function isFileExtensionSupported(file, formats) {
-	const fileExtension = getFileExtension(file.name);
-	return formats.some((format) => fileFormatsConfig[format].extensions.some((extension) => normalizeFileExtension(extension) === fileExtension));
+function writeLog(message, level, service = "log", error, sink = writeConsoleLog) {
+	const timestamp = dim(getFormattedTime());
+	const serviceName = logLevelColors[level](service.padEnd(12));
+	const formattedMessage = white(message);
+	const trace = normalizeLogError(error);
+	sink(`[${timestamp}] ${serviceName} | ${formattedMessage}`);
+	if (trace) sink(`[${timestamp}] ${red("↳ trace").padEnd(18)} | ${dim(trace)}`);
 }
 /**
-* Checks whether a file matches one configured MIME type or extension.
-* This permissive predicate supports clients where MIME metadata is absent.
+* Creates a logger permanently bound to one service label and output destination.
+* Calls retain the shared formatting while avoiding repeated service arguments.
 */
-function isFileFormatSupported(file, formats) {
-	return isFileMimeTypeSupported(file, formats) || isFileExtensionSupported(file, formats);
+function createLogger(options) {
+	return {
+		info(message) {
+			writeLog(message, logLevel.INFO, options.service, void 0, options.sink);
+		},
+		warn(message) {
+			writeLog(message, logLevel.WARN, options.service, void 0, options.sink);
+		},
+		error(message, error) {
+			writeLog(message, logLevel.ERROR, options.service, error, options.sink);
+		}
+	};
 }
 /**
-* Builds a native file-picker hint from configured MIME types and extensions.
-* Duplicate values are removed while their configuration order is retained.
+* Writes timestamped and colorized messages using a stable service column.
+* Error messages may include a stack trace on a subordinate second line.
 */
-function createUploadAccept(formats) {
-	const acceptedValues = formats.flatMap((format) => [...fileFormatsConfig[format].mimeTypes, ...fileFormatsConfig[format].extensions]);
-	return [...new Set(acceptedValues)].join(",");
-}
+const log = {
+	/**
+	* Writes an informational message with an optional service label.
+	* Missing service names use the shared `log` fallback label.
+	*/
+	info(message, service) {
+		writeLog(message, logLevel.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, logLevel.WARN, service);
+	},
+	/**
+	* Writes an error message with optional service and unknown failure context.
+	* Native errors and strings render a normalized subordinate trace line.
+	*/
+	error(message, service, error) {
+		writeLog(message, logLevel.ERROR, service, error);
+	}
+};
 //#endregion
-//#region src/upload/upload.schemas.ts
+//#region src/hono/hono.logging.ts
+/**
+* Creates Hono middleware with configurable body capture, correlation, and output.
+* Sensitive values are redacted before the completed request line reaches its writer.
+*/
+function createLoggingMiddleware(options = {}) {
+	const { bodyPreviewEdgeLength } = options;
+	if (bodyPreviewEdgeLength !== void 0 && (Number.isInteger(bodyPreviewEdgeLength) === false || bodyPreviewEdgeLength < 1)) throw loggingErrors.invalidBodyPreviewEdgeLength();
+	const service = options.service ?? "hono";
+	const includeBody = options.includeBody ?? true;
+	const requestIdHeader = options.requestIdHeader ?? "X-Request-ID";
+	const write = options.write ?? ((message, serviceName) => log.info(message, serviceName));
+	return async (context, next) => {
+		const contentType = context.req.header("content-type");
+		const searchParams = redactSensitiveSearchParams(new URL(context.req.url).searchParams).toString();
+		const bodyPreview = includeBody ? await createHTTPRequestBodyPreview(context.req.raw, contentType, bodyPreviewEdgeLength) : void 0;
+		const startTime = performance.now();
+		await next();
+		const duration = Math.round(performance.now() - startTime);
+		const message = formatHTTPRequestLog({
+			method: context.req.method,
+			status: context.res.status,
+			duration,
+			path: context.req.path,
+			searchParams,
+			bodyPreview,
+			requestId: getHonoRequestId(context, requestIdHeader)
+		});
+		write(message, service);
+	};
+}
 /**
-* Builds a reusable Zod schema for one uploaded file with format and size.
-* MIME matching is strict unless extension fallback is explicitly enabled.
+* Ready-to-use Hono request logger backed by the shared default logging policy.
+* Applications may use the factory when request capture or output needs configuration.
 */
-function zodUploadFileSchema(options) {
-	const { formats, maxFileSize, extensionFallback = false } = options;
-	return z$1.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);
-}
+const loggingMiddleware = createLoggingMiddleware();
 //#endregion
-//#region src/upload/upload.validation.ts
+//#region src/hono/hono.respond.ts
 /**
-* Validates one file against configured format and size constraints.
-* Returns the first stable error key or nothing for a valid file.
+* 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.
 */
-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;
+function respond(c, options) {
+	const response = createSuccessResponse(options.status, options.data ?? {});
+	return c.json(response, options.status);
 }
 /**
-* Validates an incoming collection while preserving every accepted file.
-* Returns accepted entries and the final rejection key from the batch.
+* Responds with downloadable binary content and its attachment headers.
+* Unknown/undefined content types default to `application/octet-stream`.
 */
-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) ?? (acceptedFiles.length >= availableFilesCount ? uploadValidationError.FILES_COUNT_EXCEEDED : void 0);
-		if (fileValidationError) {
-			validationError = fileValidationError;
-			continue;
-		}
-		acceptedFiles.push(file);
-	}
-	return {
-		acceptedFiles,
-		validationError
-	};
+function fileRespond(c, options) {
+	c.header("Content-Disposition", `attachment; filename="${options.filename}"`);
+	c.header("Content-Type", options.contentType ?? "application/octet-stream");
+	return c.body(options.content, options.status);
 }
 //#endregion
-//#region src/utilities/execution.utilities.ts
+//#region src/jwt/jwt.constants.ts
 /**
-* 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));
+* Default symmetric algorithm applied to JWT signing and verification operations.
+* The policy uses `HS256` unless a service instance explicitly selects another value.
 */
-async function safeExecute(fn, onError) {
-	try {
-		return await fn();
-	} catch (error) {
-		if (onError) return await onError(error);
-		throw error;
-	}
-}
+const DEFAULT_JWT_ALGORITHM = "HS256";
 /**
-* Measures an asynchronous execution while preserving its resolved result.
-* Rejected executions propagate unchanged and do not produce a measurement.
-*
-* @example
-* const { result, executionTime } = await measureExecutionTime(async () => {
-*    return await fetchData();
-* });
-* console.log(`Execution time: ${executionTime}ms`);
+* Default token lifetime applied when a signing operation supplies no override.
+* The duration is expressed in seconds and represents exactly fifteen minutes.
 */
-async function measureExecutionTime(execution) {
-	const startedAt = performance.now();
-	const result = await execution();
-	const executionTime = performance.now() - startedAt;
-	return {
-		result,
-		executionTime: Math.round(executionTime)
-	};
-}
+const DEFAULT_JWT_EXPIRATION_SECONDS = 900;
 //#endregion
-//#region src/zod-bulk/zod-bulk.schemas.ts
-const DEFAULT_ERROR_MESSAGE$1 = "Selection identifiers must be provided.";
+//#region src/jwt/jwt.errors.ts
+const jwtErrors = { invalidExpirationSeconds: () => /* @__PURE__ */ new RangeError("invalidExpirationSeconds") };
+//#endregion
+//#region src/jwt/jwt.validation.ts
 /**
-* Builds a strict selection contract for bulk operations across paginated data.
-* The identifier schema is shared by explicit and all-matching selection modes.
-*
-* `include` targets only identifiers listed by the client. `exclude` targets every
-* item matching the accompanying search snapshot except excluded identifiers.
-*
-* @example
-* const assetBulkSelectionSchema = zodBulkSelectionSchema({
-*   identifierSchema: z.string().min(1),
-* });
+* Validates a JWT lifetime before it participates in expiration calculation.
+* Whole positive, zero, and negative seconds are accepted within the safe range.
 */
-function zodBulkSelectionSchema({ identifierSchema }) {
-	const identifiersSchema = z$1.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, { message: DEFAULT_ERROR_MESSAGE$1 });
-	return z$1.discriminatedUnion("mode", [z$1.object({
-		mode: z$1.literal("include"),
-		identifiers: identifiersSchema
-	}).strict(), z$1.object({
-		mode: z$1.literal("exclude"),
-		excludedIdentifiers: identifiersSchema
-	}).strict()]);
+function validateJWTExpirationSeconds(expirationSeconds) {
+	if (Number.isSafeInteger(expirationSeconds) === false) throw jwtErrors.invalidExpirationSeconds();
 }
 //#endregion
-//#region src/zod-jwt/zod-jwt.services.ts
+//#region src/jwt/jwt.services.ts
 /**
-* Signs, decodes, and verifies JWTs with optional Zod payload validation.
+* Signs, decodes, and verifies JWTs with optional payload schema validation.
 * A supplied schema parses payloads returned by decoding and verification.
 */
-var ZodJWTService = class {
+var JWTService = class {
 	payloadSchema;
 	algorithm;
 	defaultExpirationSeconds;
-	constructor(payloadSchema, options) {
+	constructor(payloadSchema, options = {}) {
+		const { algorithm = DEFAULT_JWT_ALGORITHM, defaultExpirationSeconds = 900 } = options;
+		validateJWTExpirationSeconds(defaultExpirationSeconds);
 		this.payloadSchema = payloadSchema;
-		this.algorithm = options?.algorithm ?? "HS256";
-		this.defaultExpirationSeconds = options?.defaultExpirationSeconds ?? 900;
+		this.algorithm = algorithm;
+		this.defaultExpirationSeconds = defaultExpirationSeconds;
 	}
 	/**
 	* Signs a payload using the configured algorithm and expiration settings.
-	* Per-call expiration overrides the default configured by the service.
+	* Per-operation 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);
+	async sign(payload, secret, options = {}) {
+		const { expiresInSeconds = this.defaultExpirationSeconds } = options;
+		validateJWTExpirationSeconds(expiresInSeconds);
+		const expirationTimestamp = Math.floor(Date.now() / 1e3) + expiresInSeconds;
 		return sign({
 			...payload,
-			exp
+			exp: expirationTimestamp
 		}, secret, this.algorithm);
 	}
 	/**
-	* Decodes without authenticating it and parses its payload when a schema exists.
-	* Schema validation failures return `null`, while malformed tokens still reject.
+	* Decodes a token without authentication and parses its payload when configured.
+	* Schema failures return `null`, while malformed token failures remain unchanged.
 	*
 	* @example
 	* const payload = await jwtService.decode(token);
@@ -898,12 +1065,12 @@ var ZodJWTService = class {
 	async decode(token) {
 		const { payload } = decode(token);
 		if (this.payloadSchema === void 0) return payload;
-		const { success, data } = await this.payloadSchema.safeParseAsync(payload);
-		return success ? data : null;
+		const result = await this.payloadSchema.safeParseAsync(payload);
+		return result.success ? result.data : null;
 	}
 	/**
 	* Verifies a token using the configured algorithm and parses its payload.
-	* Signature, expiration, and schema validation failures reject the operation.
+	* Authentication, expiration, and schema failures reject the operation.
 	*
 	* @example
 	* const payload = await jwtService.verifyOrThrow(token, secret);
@@ -915,142 +1082,306 @@ var ZodJWTService = class {
 	}
 };
 //#endregion
-//#region src/zod-search/zod-search.pagination.schemas.ts
+//#region src/object/object.utilities.ts
 /**
-* Validates offset-based pagination shared by search request contracts.
-* Missing fields inside the required object receive predictable defaults.
+* Recognizes ordinary records whose direct prototype is `Object.prototype`.
+* Arrays, null, native objects, and custom class instances remain excluded.
 */
-const zodPaginationSchema = z$1.object({
-	/**
-	* Zero-based number of records skipped before collecting a result page.
-	* String values are coerced to support validation of URL query input.
-	*/
-	offset: z$1.coerce.number().int().nonnegative().max(1048576).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: z$1.coerce.number().int().positive().max(256).default(10)
-});
+function isPlainObject(value) {
+	if ((typeof value === "object" && value !== null) === false || Array.isArray(value)) return false;
+	return Object.getPrototypeOf(value) === Object.prototype;
+}
+//#endregion
+//#region src/random/random.errors.ts
+const randomErrors = { invalidRandomStringLength: () => /* @__PURE__ */ new RangeError("invalidRandomStringLength") };
+//#endregion
+//#region src/random/random.constants.ts
+/**
+* Alphanumeric character collection used by the default random-string generator.
+* Its fixed ordering keeps byte-to-character translation stable across runtimes.
+*/
+const RANDOM_ALPHANUMERIC_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+* Default output length used when `generateRandomString` receives no override.
+* Ten characters preserve the historical package contract for existing consumers.
+*/
+const DEFAULT_RANDOM_STRING_LENGTH = 10;
+/**
+* Maximum random-byte count requested from Web Crypto in one operation.
+* The boundary follows the platform limit enforced by `crypto.getRandomValues`.
+*/
+const RANDOM_BYTE_BATCH_SIZE = 65536;
+Math.floor(256 / 62) * 62;
+//#endregion
+//#region src/random/random.validation.ts
 /**
-* Exposes pagination fields for composition into other object schemas.
-* The shape stays derived from the schema to prevent contract divergence.
+* Validates the requested random-string length before allocating random bytes.
+* Only non-negative safe integers can represent a complete output character count.
 */
-const zodPaginationShape = zodPaginationSchema.shape;
+function assertRandomStringLength(length) {
+	if ((Number.isSafeInteger(length) && length >= 0) === false) throw randomErrors.invalidRandomStringLength();
+}
 //#endregion
-//#region src/zod-validation/zod-validation.refiners.ts
-const DEFAULT_ERROR_MESSAGE = "Invalid input. At least one field must be provided.";
+//#region src/random/random.utilities.ts
 /**
-* Wraps a partial Zod object schema with:
-* 1. A runtime check ensuring at least one field is non-undefined.
-* 2. A `.transform()` that narrows the output type to `AtLeastOne<T>`,
-*    making it directly assignable to domain `*Select` and `*Update` types without casting.
+* Creates a cryptographically sourced string from the alphanumeric collection.
+* Rejection sampling prevents modulo bias while bounded batches support long output.
 *
 * @example
-* zQuery(zodAtLeastOne(userSelectSchema)) // result: UserSelect ✓
+* generateRandomString(5); // `aZ3fG`
+* generateRandomString(); // `G5kLm2P9sQ`
 */
-const zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
-	if (!Object.values(val).some((v) => v !== void 0)) ctx.addIssue({
-		code: "custom",
-		message: DEFAULT_ERROR_MESSAGE
-	});
-}).transform((val) => val);
+function generateRandomString(length = 10) {
+	assertRandomStringLength(length);
+	let result = "";
+	while (result.length < length) {
+		const remainingLength = length - result.length;
+		const batchSize = Math.min(Math.max(remainingLength * 2, 1), RANDOM_BYTE_BATCH_SIZE);
+		const randomBytes = crypto.getRandomValues(new Uint8Array(batchSize));
+		for (const randomByte of randomBytes) {
+			if (randomByte >= 248) continue;
+			result += RANDOM_ALPHANUMERIC_CHARACTERS.charAt(randomByte % 62);
+			if (result.length === length) break;
+		}
+	}
+	return result;
+}
 //#endregion
-//#region src/zod-search/zod-search.schemas.ts
+//#region src/upload/upload.enums.ts
+const uploadValidationErrorsArray = [
+	"emptyFile",
+	"unsupportedFileFormat",
+	"fileSizeExceeded",
+	"filesCountExceeded"
+];
+const uploadValidationErrorsRecord = createStringEnumRecord(uploadValidationErrorsArray);
+const uploadValidationError = uploadValidationErrorsRecord;
+//#endregion
+//#region src/upload/upload.errors.ts
+const uploadErrors = {
+	uploadFormatRequired: () => /* @__PURE__ */ new TypeError("uploadFormatRequired"),
+	invalidMimeType: () => /* @__PURE__ */ new TypeError("invalidMimeType"),
+	invalidFileExtension: () => /* @__PURE__ */ new TypeError("invalidFileExtension"),
+	invalidMaxFileSize: () => /* @__PURE__ */ new RangeError("invalidMaxFileSize"),
+	invalidMaxFilesCount: () => /* @__PURE__ */ new RangeError("invalidMaxFilesCount"),
+	invalidCurrentFilesCount: () => /* @__PURE__ */ new RangeError("invalidCurrentFilesCount")
+};
+//#endregion
+//#region src/upload/upload.constants.ts
 /**
-* Optional text query shared by search request contracts.
-* Provided values are trimmed and must contain visible text.
+* Matches concrete MIME types, one media wildcard, or the complete wildcard.
+* Tokens follow the transport-safe characters accepted by standard metadata.
 */
-const zodSearchQuerySchema = z$1.string().trim().min(1).optional();
+const UPLOAD_MIME_TYPE_PATTERN = /^(?:\*\/\*|[A-Za-z0-9!#$&^_.+-]+\/(?:\*|[A-Za-z0-9!#$&^_.+-]+))$/;
 /**
-* Makes every supplied filter optional while requiring one defined value.
-* Top-level optionality is added later for both composition modes equally.
+* Matches one alphanumeric file extension with an optional leading dot.
+* Compound and path-like values remain invalid format declarations.
 */
-const createZodSearchWhereSchema = (filters) => zodAtLeastOne(filters.partial());
+const UPLOAD_FILE_EXTENSION_PATTERN = /^\.?[A-Za-z0-9]+$/;
+//#endregion
+//#region src/upload/upload.utilities.ts
 /**
-* Builds a strict schema for reusable search request contracts.
-* The optional `where` object must contain one defined filter.
-*
-* Query is optional and non-empty; pagination is required by default.
-* Literal feature flags update both runtime and inferred static shapes.
-*
-* Pass `filters` for automatic partial and non-empty validation, or use
-* `whereSchema` to preserve a prepared schema with custom Zod effects.
-*
-* @example
-* const assetSearchSchema = zodSearchSchema({
-*   filters: assetSchema.pick({ status: true }),
-* });
-*
-* const refinedAssetSearchSchema = zodSearchSchema({
-*   whereSchema: zodAtLeastOne(assetSchema.pick({ status: true }).partial()),
-* });
+* Extracts a normalized trailing extension from a complete file name.
+* Returns an empty string when no valid dot-delimited suffix exists.
+*/
+function getFileExtension(fileName) {
+	const normalizedFileName = fileName.trim();
+	const extensionIndex = normalizedFileName.lastIndexOf(".");
+	return extensionIndex > 0 && extensionIndex < normalizedFileName.length - 1 ? normalizedFileName.slice(extensionIndex).toLowerCase() : "";
+}
+/**
+* Normalizes a configured extension to a lowercase dot-prefixed value.
+* Existing prefixes remain intact so repeated normalization is stable.
+*/
+function normalizeFileExtension(extension) {
+	const normalizedExtension = extension.trim().toLowerCase();
+	if (normalizedExtension.length === 0 || normalizedExtension === ".") return "";
+	return normalizedExtension.startsWith(".") ? normalizedExtension : `.${normalizedExtension}`;
+}
+/**
+* Compares a concrete MIME type with an exact or wildcard configuration.
+* Wildcards match every subtype belonging to the configured media group.
+*/
+function matchesMimeType(fileMimeType, configuredMimeType) {
+	const normalizedFileMimeType = fileMimeType.trim().toLowerCase();
+	const normalizedConfiguredMimeType = configuredMimeType.trim().toLowerCase();
+	const hasMimeType = /^[^/\s]+\/[^/\s]+$/.test(normalizedFileMimeType);
+	const hasConfiguredMimeType = normalizedConfiguredMimeType.length > 0;
+	if (hasMimeType === false || hasConfiguredMimeType === false) return false;
+	if (normalizedConfiguredMimeType === "*/*") return true;
+	if (normalizedConfiguredMimeType.endsWith("/*")) {
+		const mediaTypePrefix = normalizedConfiguredMimeType.slice(0, -1);
+		const mimeTypeLengthValid = normalizedFileMimeType.length > mediaTypePrefix.length;
+		return normalizedFileMimeType.startsWith(mediaTypePrefix) && mimeTypeLengthValid;
+	}
+	return normalizedFileMimeType === normalizedConfiguredMimeType;
+}
+/**
+* Checks whether a file MIME type belongs to one selected format.
+* File names and extensions cannot make an unsupported MIME type valid.
+*/
+function isFileMimeTypeSupported(file, formats) {
+	return formats.some((format) => format.mimeTypes.some((mimeType) => matchesMimeType(file.type, mimeType)));
+}
+/**
+* Checks whether a file extension belongs to one selected format.
+* The comparison is case-insensitive and requires a complete suffix.
+*/
+function isFileExtensionSupported(file, formats) {
+	const fileExtension = getFileExtension(file.name);
+	if (fileExtension.length === 0) return false;
+	return formats.some((format) => format.extensions.some((extension) => normalizeFileExtension(extension) === fileExtension));
+}
+/**
+* Checks whether a file satisfies the format policy selected by one validation boundary.
+* MIME matching remains strict unless the caller explicitly enables extension fallback.
+*/
+function isFileFormatSupported(file, options) {
+	const { formats, extensionFallback = false } = options;
+	if (isFileMimeTypeSupported(file, formats)) return true;
+	return extensionFallback && isFileExtensionSupported(file, formats);
+}
+/**
+* Builds a native file-picker hint from configured MIME types and extensions.
+* Duplicate values are removed while their configuration order is retained.
+*/
+function createUploadAccept(formats) {
+	const acceptedValues = formats.flatMap((format) => [...format.mimeTypes.map((mimeType) => mimeType.trim().toLowerCase()), ...format.extensions.map(normalizeFileExtension)]);
+	return [...new Set(acceptedValues.filter((value) => value.length > 0))].join(",");
+}
+//#endregion
+//#region src/upload/upload.validation.ts
+function resolveUploadFileValidationError(file, options) {
+	if (file.size === 0) return uploadValidationError.EMPTY_FILE;
+	if (isFileFormatSupported(file, options) === false) return uploadValidationError.UNSUPPORTED_FILE_FORMAT;
+	if (file.size > options.maxFileSize) return uploadValidationError.FILE_SIZE_EXCEEDED;
+}
+/**
+* Asserts that one file validation policy contains a usable size boundary.
+* Invalid configuration rejects before any externally owned file is inspected.
+*/
+function assertUploadFileValidationOptions(options) {
+	if (Number.isInteger(options.maxFileSize) === false || options.maxFileSize < 0) throw uploadErrors.invalidMaxFileSize();
+}
+/**
+* Asserts that one reusable upload preset contains a usable collection capacity.
+* Optional capacity remains unrestricted while supplied values require whole counts.
+*/
+function assertUploadPreset(preset) {
+	assertUploadFileValidationOptions(preset);
+	if (preset.maxFilesCount !== void 0 && (Number.isInteger(preset.maxFilesCount) === false || preset.maxFilesCount < 0)) throw uploadErrors.invalidMaxFilesCount();
+}
+/**
+* Asserts that one collection policy contains usable integer capacity values.
+* Optional collection capacity remains unrestricted when it is omitted.
 */
-const zodSearchSchema = (options) => {
-	const shape = {
-		where: (options.filters !== void 0 ? createZodSearchWhereSchema(options.filters) : options.whereSchema).optional(),
-		...options.queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
-		...options.paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
+function assertUploadFilesValidationOptions(options) {
+	assertUploadPreset(options);
+	if (Number.isInteger(options.currentFilesCount) === false || options.currentFilesCount < 0) throw uploadErrors.invalidCurrentFilesCount();
+}
+/**
+* Validates one file against configured format and size constraints.
+* Returns the first stable error key or nothing for a valid file.
+*/
+function validateUploadFile(file, options) {
+	assertUploadFileValidationOptions(options);
+	return resolveUploadFileValidationError(file, options);
+}
+/**
+* Validates an incoming collection while preserving every accepted file.
+* Returns accepted entries and the first rejection key from the batch.
+*/
+function validateUploadFiles(incomingFiles, options) {
+	assertUploadFilesValidationOptions(options);
+	const { currentFilesCount, maxFilesCount } = options;
+	const availableFilesCount = maxFilesCount === void 0 ? Infinity : maxFilesCount - currentFilesCount;
+	const acceptedFiles = [];
+	let validationError;
+	for (const file of incomingFiles) {
+		const fileValidationError = resolveUploadFileValidationError(file, options) ?? (acceptedFiles.length >= availableFilesCount ? uploadValidationError.FILES_COUNT_EXCEEDED : void 0);
+		if (fileValidationError) {
+			validationError ??= fileValidationError;
+			continue;
+		}
+		acceptedFiles.push(file);
+	}
+	return {
+		acceptedFiles,
+		validationError
 	};
-	return z$1.object(shape).strict();
-};
+}
 //#endregion
-//#region src/zod-validation/zod-validation.utilities.ts
+//#region src/upload/upload.factory.ts
+/**
+* Validates one upload format before it becomes part of a reusable policy.
+* Accepts MIME-only and extension-only definitions while rejecting malformed values.
+*/
+function assertUploadFormat(format) {
+	const hasMimeTypes = format.mimeTypes.length > 0;
+	const hasExtensions = format.extensions.length > 0;
+	if (hasMimeTypes === false && hasExtensions === false) throw uploadErrors.uploadFormatRequired();
+	if (format.mimeTypes.some((mimeType) => {
+		return UPLOAD_MIME_TYPE_PATTERN.test(mimeType.trim()) === false;
+	})) throw uploadErrors.invalidMimeType();
+	if (format.extensions.some((extension) => {
+		return UPLOAD_FILE_EXTENSION_PATTERN.test(extension.trim()) === false;
+	})) throw uploadErrors.invalidFileExtension();
+}
 /**
-* Checks whether a value is a plain record backed by `Object.prototype`.
-* Arrays, null, dates, collections, and custom class instances are rejected.
+* Defines one upload format while preserving its literal MIME and extension tuples.
+* Applications may enrich the returned object with their own display metadata.
 */
-const isPlainObject = (value) => {
-	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
-};
+function defineUploadFormat(format) {
+	assertUploadFormat(format);
+	return format;
+}
+/**
+* Defines one shared upload policy while preserving its literal format tuple.
+* The resulting preset can drive schemas, picker hints, and batch validation.
+*/
+function defineUploadPreset(preset) {
+	assertUploadPreset(preset);
+	return preset;
+}
 //#endregion
-//#region src/zod-validation/zod-validation.parsing.ts
-const parseQueryValue = (value) => {
-	if (Array.isArray(value)) return value.map(parseQueryValue);
-	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [key, parseQueryValue(entryValue)]));
-	if (typeof value !== "string") return value;
-	const normalized = value.trim().toLowerCase();
-	if (normalized === "") return value;
-	if (normalized === "true") return true;
-	if (normalized === "false") return false;
-	if (/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(normalized)) return Number(normalized);
-	return value;
-};
+//#region src/upload/upload.schemas.ts
 /**
-* Preprocesses query-like values before Zod validation.
-*
-* Query parameters are string-based by nature, even when they semantically represent
-* numbers or booleans. This helper converts only clear primitive values, allowing
-* regular schemas like `z.number()` and `z.boolean()` to validate query input directly.
-*
-* @example
-* const schema = asQuery(z.object({
-*   page: z.number().int().positive(),
-*   isActive: z.boolean(),
-* }));
-*
-* schema.parse({ page: '2', isActive: 'true' });
-* // { page: 2, isActive: true }
+* Builds a reusable Zod schema for one uploaded file with format and size.
+* MIME matching is strict unless extension fallback is explicitly enabled.
 */
-const asQuery = (schema) => z$1.preprocess(parseQueryValue, schema);
+function zodUploadFileSchema(options) {
+	assertUploadFileValidationOptions(options);
+	return z.file().superRefine((file, context) => {
+		const validationError = validateUploadFile(file, options);
+		if (validationError === void 0) return;
+		context.addIssue({
+			code: "custom",
+			message: validationError
+		});
+	});
+}
+//#endregion
+//#region src/zod/zod.errors.ts
+const zodErrors = { atLeastOneRequired: () => ({
+	code: "custom",
+	message: "atLeastOneRequired"
+}) };
+//#endregion
+//#region src/zod/zod.refiners.ts
 /**
-* Recursively converts payload values to strings without changing container structure.
-* Objects and arrays are copied while `null` and `undefined` retain omission semantics.
+* Requires one defined property while preserving the supplied Zod object validation.
+* The output type reflects semantic presence and retains valid falsy or nullable values.
 *
 * @example
-* stringifyPayloadValues({ page: 2, enabled: true });
-* // { page: '2', enabled: 'true' }
-*/
-function stringifyPayloadValues(value) {
-	if (Array.isArray(value)) return value.map(stringifyPayloadValues);
-	if (isPlainObject(value)) {
-		const entries = Object.entries(value).map(([key, entryValue]) => {
-			return [key, stringifyPayloadValues(entryValue)];
-		});
-		return Object.fromEntries(entries);
-	}
-	if (value === null || value === void 0) return value;
-	return String(value);
+* const patchSchema = zodAtLeastOne(z.object({ name: z.string().optional() }));
+*/
+function zodAtLeastOne(schema) {
+	return schema.superRefine((value, context) => {
+		if (Object.values(value).some((property) => property !== void 0)) return;
+		context.addIssue(zodErrors.atLeastOneRequired());
+	}).transform((value) => {
+		return value;
+	});
 }
 //#endregion
-export { APIRequestError, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, HMACService, REDACTED_LOG_VALUE, SUCCESS_STATUS_CODES, ZodJWTService, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+export { DEFAULT_DATETIME_TIMEZONE, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_JWT_ALGORITHM, DEFAULT_JWT_EXPIRATION_SECONDS, DEFAULT_RANDOM_STRING_LENGTH, DEFAULT_RETRY_MAX_ATTEMPTS, ERROR_RESPONSE_STATUSES, HMACService, HONO_LOGGING_SERVICE, HONO_REQUEST_ID_HEADER, JWTService, LOG_BODY_PREVIEW_EDGE_LENGTH, MULTIPART_LOG_BODY, RANDOM_ALPHANUMERIC_CHARACTERS, RANDOM_BYTE_BATCH_SIZE, REDACTED_LOG_VALUE, ResponseError, SUCCESS_RESPONSE_STATUSES, assertRandomStringLength, assertUploadFormat, captureExecution, createErrorResponse, createHTTPRequestBodyPreview, createHonoErrorHandler, createLogger, createLoggingMiddleware, createRequestIdMiddleware, createStringEnumRecord, createSuccessResponse, createUploadAccept, decodeBase64, decodeHMACSignature, defineUploadFormat, defineUploadPreset, drizzleErrors, encodeBase64, encodeHMACSignature, executeWithTimeout, executionErrors, fileRespond, formatHTTPRequestLog, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getHonoRequestId, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, hmacErrors, honoErrors, httpStatusColors, isErrorResponse, isErrorResponseStatus, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, isResponseErrorCode, isSuccessResponse, isSuccessResponseStatus, jwtErrors, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingErrors, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, normalizeLogError, randomErrors, redactSensitiveJSON, redactSensitiveSearchParams, redactSensitiveValue, requestIdMiddleware, resolveResponse, respond, responseErrors, responseKind, responseKindsArray, responseKindsRecord, retryExecution, safeExecute, sensitiveLogKeyParts, sqlWhere, toHMACBytes, unwrapResponse, uploadErrors, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateJWTExpirationSeconds, validateUploadFile, validateUploadFiles, waitForRetry, zodAtLeastOne, zodErrors, zodUploadFileSchema };