@kalutskii/foundation 0.7.22 → 0.7.25

package/dist/index.js

@@ -1,730 +1,1040 @@
-// src/drizzle/drizzle.refiners.ts
 import { and, eq } from "drizzle-orm";
-var AT_LEAST_ONE_DEFINED_CONDITION_ERROR = "sqlWhere requires at least one defined condition.";
-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);
-}
-
-// src/hono/hono.execution.ts
 import { HTTPException } from "hono/http-exception";
-import { red as red3 } from "kleur/colors";
-
-// src/http/http.factory.ts
+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 { 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.";
+/**
+* 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();
+*/
+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);
+}
+//#endregion
+//#region src/http/http.factory.ts
+/**
+* Creates a successful API envelope without cloning its data.
+* Generic inference preserves the exact supplied payload type.
+*/
 function success({ status, data }) {
-  return { kind: "data", status, data };
+	return {
+		kind: "data",
+		status,
+		data
+	};
 }
+/**
+* Creates a failed API envelope with one supported exception status.
+* The supplied message remains unchanged for downstream presentation.
+*/
 function failure({ status, error }) {
-  return { kind: "error", status, error };
+	return {
+		kind: "error",
+		status,
+		error
+	};
 }
-
-// src/logging/logging.services.ts
-import { dim, red as red2, white } from "kleur/colors";
-
-// src/utilities/datetime.utilities.ts
-import { format } from "date-fns";
-import { getTimezoneOffset, toZonedTime } from "date-fns-tz";
-import { ru } from "date-fns/locale";
+//#endregion
+//#region src/utilities/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.
+*
+* @example
+* const londonTime = getZonedTime({ tz: 'Europe/London' });
+*/
 function getZonedTime({ tz = "Europe/London" } = {}) {
-  return toZonedTime(/* @__PURE__ */ new Date(), tz);
+	return toZonedTime(/* @__PURE__ */ new Date(), tz);
 }
+/**
+* Formats the UTC offset of a timezone at the supplied date.
+* An explicit date preserves daylight-saving and historical offset rules.
+*
+* @example
+* getUTCOffset(date, 'Europe/Moscow'); // `(+3 UTC)`
+*/
 function getUTCOffset(date, tz) {
-  const offset = getTimezoneOffset(tz, date) / (60 * 60 * 1e3);
-  return `(${offset >= 0 ? "+" : ""}${offset} UTC)`;
+	const offset = getTimezoneOffset(tz, date) / 36e5;
+	return `(${offset >= 0 ? "+" : ""}${offset} UTC)`;
 }
+/**
+* Formats the current time and UTC offset in the selected timezone.
+* The timezone defaults to `Europe/London` when no option is provided.
+*
+* @example
+* getFormattedTime({ tz: 'Europe/Moscow' }); // `03:04:05 (+3 UTC)`
+*/
 function getFormattedTime({ tz = "Europe/London" } = {}) {
-  const zonedTime = getZonedTime({ tz });
-  return `${format(zonedTime, "HH:mm:ss")} ${getUTCOffset(zonedTime, tz)}`;
+	const zonedTime = getZonedTime({ tz });
+	return `${format(zonedTime, "HH:mm:ss")} ${getUTCOffset(zonedTime, tz)}`;
 }
+/**
+* Formats the current date with optional time and UTC offset components.
+* Time is included by default and uses the selected timezone for display.
+*
+* @example
+* getFormattedDate({ tz: 'UTC', withTime: false }); // `02.01.2024`
+*/
 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)}` : ""}`;
+	const zonedTime = getZonedTime({ tz });
+	return `${format(zonedTime, withTime ? "dd.MM.yyyy HH:mm:ss" : "dd.MM.yyyy")}${withTime ? ` ${getUTCOffset(zonedTime, tz)}` : ""}`;
 }
+/**
+* Formats an explicit instant in another timezone using the selected locale.
+* The result includes localized date text, wall-clock time, and UTC offset.
+*
+* @example
+* formatTime(date, { locale: ru, tz: 'Europe/Moscow' });
+*/
 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/logging/logging.constants.ts
-import { blue, green, red, yellow } from "kleur/colors";
-
-// src/utilities/enums.utilities.ts
+	const zonedTime = toZonedTime(time, tz);
+	return `${format(zonedTime, "HH:mm:ss, d MMMM yyyy", { locale })} ${getUTCOffset(zonedTime, tz)}`;
+}
+//#endregion
+//#region src/utilities/enums.utilities.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.
+*
+* @example
+* createStringEnumRecord(['foo-bar.s', 'baz'] as const); // `{ FOO_BAR_S: 'foo-bar.s', BAZ: 'baz' }`
+*/
 function createStringEnumRecord(values) {
-  return Object.freeze(Object.fromEntries(values.map((value) => [value.replaceAll(/[.-]/g, "_").toUpperCase(), value])));
-}
-
-// src/logging/logging.enums.ts
-var logLevelsArray = ["info", "warn", "error"];
-var logLevelsRecord = createStringEnumRecord(logLevelsArray);
-var logLevel = logLevelsRecord;
-
-// src/logging/logging.constants.ts
-var logLevelColors = {
-  [logLevel.INFO]: blue,
-  [logLevel.WARN]: yellow,
-  [logLevel.ERROR]: red
+	return Object.freeze(Object.fromEntries(values.map((value) => [value.replaceAll(/[.-]/g, "_").toUpperCase(), value])));
+}
+//#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
 };
-var REDACTED_LOG_VALUE = "[redacted]";
-var sensitiveLogKeyParts = [
-  "password",
-  "passwd",
-  "token",
-  "secret",
-  "authorization",
-  "apikey",
-  "credential"
+/**
+* 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]";
+/**
+* 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"
 ];
-var httpStatusColors = [
-  { range: [200, 299], color: green },
-  { range: [400, 499], color: yellow },
-  { range: [500, 599], color: red }
+/**
+* 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
+	}
 ];
-
-// src/logging/logging.services.ts
+//#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}] ${red2("\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.
-   * Provided stack traces are rendered beneath the primary message.
-   */
-  error(message, service, stack) {
-    writeLog(message, "error", service, 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)}`);
+}
+/**
+* Writes timestamped and colorized messages using a stable service column.
+* Error messages may include a stack trace on a subordinate second line.
+*/
+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);
+	}
 };
-
-// src/utilities/generation.utilities.ts
-var DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+//#endregion
+//#region src/utilities/generation.utilities.ts
+const DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+* Creates a cryptographically sourced string from the alphanumeric set.
+* Requested length defaults to `10` characters when omitted.
+*
+* @example
+* generateRandomString(5); // `aZ3fG`
+* generateRandomString(); // `G5kLm2P9sQ`
+*/
 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] % DEFAULT_CHARACTERS.length];
-  }
-  return result;
-}
-
-// src/hono/hono.execution.ts
+	const randomValues = crypto.getRandomValues(new Uint32Array(length));
+	let result = "";
+	for (let i = 0; i < length; i++) result += DEFAULT_CHARACTERS[randomValues[i] % 62];
+	return result;
+}
+//#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: ${red3(errorMessage)}`, errorId);
-  return failure({ status: 500, error: `Internal server error | ${errorId}` });
-}
-var 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);
+	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}`
+	});
+}
+/**
+* Converts expected `HTTPException` values into shared API error envelopes.
+* Unexpected failures are logged and represented by a traceable generic response.
+*/
+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);
 };
-
-// src/hono/hono.respond.ts
+//#endregion
+//#region src/hono/hono.respond.ts
+/**
+* Wraps `c.json` in the shared success envelope while preserving its literal status.
+* Missing response data is represented by an empty object for contract consistency.
+*/
 function respond(c, options) {
-  return c.json(success({ status: options.status, data: options.data ?? {} }), options.status);
+	return c.json(success({
+		status: options.status,
+		data: options.data ?? {}
+	}), options.status);
 }
+/**
+* Responds with downloadable binary content and its attachment headers.
+* Unknown/undefined content types default to `application/octet-stream`.
+*/
 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);
-}
-
-// src/hmac/hmac.enums.ts
-var hmacAlgorithmsArray = ["SHA-256", "SHA-384", "SHA-512"];
-var hmacAlgorithmsRecord = createStringEnumRecord(hmacAlgorithmsArray);
-var hmacAlgorithm = hmacAlgorithmsRecord;
-var hmacEncodingsArray = ["hex", "base64", "base64url"];
-var hmacEncodingsRecord = createStringEnumRecord(hmacEncodingsArray);
-var hmacEncoding = hmacEncodingsRecord;
-
-// src/hmac/hmac.constants.ts
-var DEFAULT_HMAC_ALGORITHM = hmacAlgorithm.SHA_256;
-var DEFAULT_HMAC_ENCODING = hmacEncoding.HEX;
-
-// src/utilities/encoding.utilities.ts
-var BASE64_BYTE_CHUNK_SIZE = 32768;
+	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/hmac/hmac.enums.ts
+const hmacAlgorithmsArray = [
+	"SHA-256",
+	"SHA-384",
+	"SHA-512"
+];
+const hmacAlgorithmsRecord = createStringEnumRecord(hmacAlgorithmsArray);
+const hmacAlgorithm = hmacAlgorithmsRecord;
+const hmacEncodingsArray = [
+	"hex",
+	"base64",
+	"base64url"
+];
+const hmacEncodingsRecord = createStringEnumRecord(hmacEncodingsArray);
+const hmacEncoding = hmacEncodingsRecord;
+//#endregion
+//#region src/hmac/hmac.constants.ts
+/**
+* Default digest algorithm used by `HMACService` when none is configured.
+* SHA-256 provides broad Web Crypto support and a 256-bit authentication tag.
+*/
+const DEFAULT_HMAC_ALGORITHM = hmacAlgorithm.SHA_256;
+/**
+* Default textual encoding used for signatures returned by `HMACService`.
+* Hex output remains deterministic, portable, and independent of padding rules.
+*/
+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);
+	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));
+	const binary = atob(value);
+	return Uint8Array.from(binary, (character) => character.charCodeAt(0));
 }
-
-// src/hmac/hmac.utilities.ts
-var textEncoder = new TextEncoder();
+//#endregion
+//#region src/hmac/hmac.utilities.ts
+const textEncoder = new TextEncoder();
+/**
+* Converts an HMAC payload or secret into an isolated byte array representation.
+* Strings use UTF-8 while supplied bytes are copied to prevent later mutation.
+*/
 function toHMACBytes(input) {
-  if (typeof input === "string")
-    return textEncoder.encode(input);
-  const bytes = new Uint8Array(input.length);
-  bytes.set(input);
-  return bytes;
+	if (typeof input === "string") return textEncoder.encode(input);
+	const bytes = new Uint8Array(input.length);
+	bytes.set(input);
+	return bytes;
 }
+/**
+* Encodes binary HMAC output with one supported transport-safe representation.
+* 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 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(/=+$/, "");
 }
+/**
+* Decodes a textual HMAC signature into bytes for cryptographic verification.
+* Malformed alphabets, lengths, or padding combinations reject with `TypeError`.
+*/
 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 (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_-]*$/.test(signature) || signature.length % 4 === 1) {
-    throw new TypeError("Invalid Base64 URL HMAC signature");
-  }
-  const base64 = signature.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(signature.length / 4) * 4, "=");
-  return decodeBase64(base64);
-}
-
-// src/hmac/hmac.services.ts
+	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 (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_-]*$/.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, "="));
+}
+//#endregion
+//#region src/hmac/hmac.services.ts
+/**
+* Creates and verifies keyed message authentication codes through Web Crypto.
+* Each instance preserves its digest algorithm and textual encoding configuration.
+*/
 var HMACService = class {
-  algorithm;
-  encoding;
-  constructor(options = {}) {
-    this.algorithm = options.algorithm ?? DEFAULT_HMAC_ALGORITHM;
-    this.encoding = options.encoding ?? DEFAULT_HMAC_ENCODING;
-  }
-  /**
-   * Authenticates a payload with a secret and returns the encoded signature.
-   * String inputs use UTF-8 while byte arrays preserve their exact byte sequence.
-   *
-   * @example
-   * const signature = await hmacService.sign('payload', 'shared-secret');
-   */
-  async sign(payload, secret) {
-    const key = await this.importSecret(secret);
-    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`.
-   *
-   * @example
-   * const verified = await hmacService.verify('payload', signature, 'shared-secret');
-   */
-  async verify(payload, signature, secret) {
-    let signatureBytes;
-    try {
-      signatureBytes = decodeHMACSignature(signature, this.encoding);
-    } catch {
-      return false;
-    }
-    const key = await this.importSecret(secret);
-    return crypto.subtle.verify("HMAC", key, signatureBytes, toHMACBytes(payload));
-  }
-  async importSecret(secret) {
-    const secretBytes = toHMACBytes(secret);
-    const algorithm = { name: "HMAC", hash: this.algorithm };
-    const keyUsages = ["sign", "verify"];
-    return crypto.subtle.importKey("raw", secretBytes, algorithm, false, keyUsages);
-  }
+	algorithm;
+	encoding;
+	constructor(options = {}) {
+		this.algorithm = options.algorithm ?? DEFAULT_HMAC_ALGORITHM;
+		this.encoding = options.encoding ?? DEFAULT_HMAC_ENCODING;
+	}
+	/**
+	* Authenticates a payload with a secret and returns the encoded signature.
+	* String inputs use UTF-8 while byte arrays preserve their exact byte sequence.
+	*
+	* @example
+	* const signature = await hmacService.sign('payload', 'shared-secret');
+	*/
+	async sign(payload, secret) {
+		const key = await this.importSecret(secret);
+		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`.
+	*
+	* @example
+	* const verified = await hmacService.verify('payload', signature, 'shared-secret');
+	*/
+	async verify(payload, signature, secret) {
+		let signatureBytes;
+		try {
+			signatureBytes = decodeHMACSignature(signature, this.encoding);
+		} catch {
+			return false;
+		}
+		const key = await this.importSecret(secret);
+		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"]);
+	}
 };
-
-// src/http/http.constants.ts
-var SUCCESS_STATUS_CODES = [200, 201, 202, 307];
-var EXCEPTION_STATUS_CODES = [400, 401, 403, 404, 405, 409, 500];
-
-// src/http/http.resolvers.ts
+//#endregion
+//#region src/http/http.constants.ts
+const SUCCESS_STATUS_CODES = [
+	200,
+	201,
+	202,
+	307
+];
+const EXCEPTION_STATUS_CODES = [
+	400,
+	401,
+	403,
+	404,
+	405,
+	409,
+	500
+];
+//#endregion
+//#region src/http/http.resolvers.ts
+/**
+* Converts an API contract envelope into a mutually exclusive safe result.
+* Only `APIError` values are normalized; rejected fetchers still reject.
+*/
 async function fetchSafely(fetcher) {
-  const response = await fetcher();
-  if (response.kind === "error")
-    return { error: response.error, data: null };
-  return { error: null, data: response.data };
+	const response = await fetcher();
+	if (response.kind === "error") return {
+		error: response.error,
+		data: null
+	};
+	return {
+		error: null,
+		data: response.data
+	};
 }
+/**
+* Returns successful API data and throws for an `APIError` envelope.
+* Rejected fetchers propagate their original error without replacement.
+*/
 async function fetchAndThrow(fetcher) {
-  const response = await fetcher();
-  if (response.kind === "error")
-    throw new Error(response.error);
-  return response.data;
-}
-
-// src/logging/logging.middleware.ts
-import { blue as blue2, bold, dim as dim2, white as white2 } from "kleur/colors";
-
-// src/logging/logging.security.ts
+	const response = await fetcher();
+	if (response.kind === "error") throw new Error(response.error);
+	return response.data;
+}
+//#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));
+	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 redactSensitiveValue(value) {
-  if (Array.isArray(value)) {
-    const entries2 = value.map(redactSensitiveValue);
-    return {
-      value: entries2.map((entry) => entry.value),
-      redacted: entries2.some((entry) => entry.redacted)
-    };
-  }
-  if (typeof value !== "object" || value === null)
-    return { value, redacted: false };
-  let redacted = false;
-  const entries = Object.entries(value).map(([key, entryValue]) => {
-    if (isSensitiveLogKey(key)) {
-      redacted = true;
-      return [key, REDACTED_LOG_VALUE];
-    }
-    const nestedEntry = redactSensitiveValue(entryValue);
-    redacted ||= nestedEntry.redacted;
-    return [key, nestedEntry.value];
-  });
-  return { value: Object.fromEntries(entries), redacted };
+	if (Array.isArray(value)) {
+		const entries = value.map(redactSensitiveValue);
+		return {
+			value: entries.map((entry) => entry.value),
+			redacted: entries.some((entry) => entry.redacted)
+		};
+	}
+	if (typeof value !== "object" || value === null) return {
+		value,
+		redacted: false
+	};
+	let redacted = false;
+	const entries = Object.entries(value).map(([key, entryValue]) => {
+		if (isSensitiveLogKey(key)) {
+			redacted = true;
+			return [key, REDACTED_LOG_VALUE];
+		}
+		const nestedEntry = redactSensitiveValue(entryValue);
+		redacted ||= nestedEntry.redacted;
+		return [key, nestedEntry.value];
+	});
+	return {
+		value: Object.fromEntries(entries),
+		redacted
+	};
 }
+/**
+* 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);
-  }
-  return redactedSearchParams;
+	const redactedSearchParams = new URLSearchParams(searchParams);
+	for (const key of new Set(redactedSearchParams.keys())) if (isSensitiveLogKey(key)) redactedSearchParams.set(key, REDACTED_LOG_VALUE);
+	return redactedSearchParams;
 }
+/**
+* Replaces values under sensitive keys throughout a serialized JSON structure.
+* 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 parsedValue = JSON.parse(json);
-    const result = redactSensitiveValue(parsedValue);
-    return result.redacted ? JSON.stringify(result.value) : json;
-  } catch {
-    return json;
-  }
-}
-
-// src/logging/logging.utilities.ts
+	if (json === void 0 || null) return json;
+	try {
+		const result = redactSensitiveValue(JSON.parse(json));
+		return result.redacted ? JSON.stringify(result.value) : json;
+	} catch {
+		return json;
+	}
+}
+//#endregion
+//#region src/logging/logging.utilities.ts
+/**
+* Selects a terminal color function for one HTTP response status.
+* Successes are green, client errors yellow, and server errors red.
+*/
 function getColoredHTTPStatus(status) {
-  const statusColor = httpStatusColors.find(({ range: [minimum, maximum] }) => {
-    return status >= minimum && status <= maximum;
-  });
-  return statusColor ? statusColor.color : (text) => text;
-}
-
-// src/logging/logging.middleware.ts
-var 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)}\u2026${body.slice(-30)}` : 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(32));
-  const coloredSearchParams = searchParams ? dim2(` (${searchParams})`) : "";
-  const coloredBody = bodyPreview ? dim2(` ${bodyPreview}`) : "";
-  log.info(`${coloredMethod} ${coloredStatus} ${coloredTime} ${coloredPath}${coloredSearchParams}${coloredBody}`, "hono");
+	const statusColor = httpStatusColors.find(({ range: [minimum, maximum] }) => {
+		return status >= minimum && status <= maximum;
+	});
+	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");
 };
-
-// src/upload/upload.enums.ts
-var fileFormatsArray = [
-  ...["png", "jpg", "webp", "avif", "heic", "svg"],
-  // Image formats.
-  ...["pdf", "rtf", "txt"]
-  // Text and document formats.
+//#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"
 ];
-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.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"] },
-  // 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"] }
+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.
+*/
+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"]
+	}
 };
-
-// src/upload/upload.factory.ts
+//#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;
-}
-
-// src/upload/upload.presets.ts
-var DEFAULT_UPLOAD_MAX_FILE_SIZE = 20 * 1024 * 1024;
-var imageUploadPreset = defineUploadPreset({
-  formats: [fileFormat.PNG, fileFormat.JPG, fileFormat.WEBP, fileFormat.AVIF, fileFormat.HEIC],
-  maxFileSize: DEFAULT_UPLOAD_MAX_FILE_SIZE
+	return preset;
+}
+//#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
 });
-var imageTransparentUploadPreset = defineUploadPreset({
-  formats: [fileFormat.PNG, fileFormat.WEBP, fileFormat.SVG],
-  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
 });
-var documentUploadPreset = defineUploadPreset({
-  formats: [fileFormat.PDF, fileFormat.RTF, fileFormat.TXT],
-  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
 });
-
-// src/upload/upload.schemas.ts
-import { z } from "zod";
-
-// src/upload/upload.utilities.ts
+//#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.
+*/
 function getFileExtension(fileName) {
-  const extensionIndex = fileName.lastIndexOf(".");
-  return extensionIndex > 0 && extensionIndex < fileName.length - 1 ? fileName.slice(extensionIndex).toLowerCase() : "";
+	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}`;
+	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;
+	if (configuredMimeType.endsWith("/*")) return fileMimeType.startsWith(configuredMimeType.slice(0, -1));
+	return fileMimeType === configuredMimeType;
 }
+/**
+* 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((format2) => fileFormatsConfig[format2].mimeTypes.some((mimeType) => matchesMimeType(file.type, mimeType)));
+	return formats.some((format) => fileFormatsConfig[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);
-  return formats.some((format2) => fileFormatsConfig[format2].extensions.some((extension) => normalizeFileExtension(extension) === fileExtension));
+	const fileExtension = getFileExtension(file.name);
+	return formats.some((format) => fileFormatsConfig[format].extensions.some((extension) => normalizeFileExtension(extension) === fileExtension));
 }
+/**
+* Checks whether a file matches one configured MIME type or extension.
+* This permissive predicate supports clients where MIME metadata is absent.
+*/
 function isFileFormatSupported(file, formats) {
-  return isFileMimeTypeSupported(file, formats) || isFileExtensionSupported(file, formats);
+	return isFileMimeTypeSupported(file, formats) || 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((format2) => [
-    ...fileFormatsConfig[format2].mimeTypes,
-    ...fileFormatsConfig[format2].extensions
-  ]);
-  return [...new Set(acceptedValues)].join(",");
-}
-
-// src/upload/upload.schemas.ts
+	const acceptedValues = formats.flatMap((format) => [...fileFormatsConfig[format].mimeTypes, ...fileFormatsConfig[format].extensions]);
+	return [...new Set(acceptedValues)].join(",");
+}
+//#endregion
+//#region src/upload/upload.schemas.ts
+/**
+* Builds a reusable Zod schema for one uploaded file with format and size.
+* MIME matching is strict unless extension fallback is explicitly enabled.
+*/
 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);
+	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);
 }
-
-// src/upload/upload.validation.ts
+//#endregion
+//#region src/upload/upload.validation.ts
+/**
+* Validates one file against configured format and size constraints.
+* Returns the first stable error key or nothing for a valid file.
+*/
 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;
+	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;
 }
+/**
+* Validates an incoming collection while preserving every accepted file.
+* Returns accepted entries and the final rejection key from the batch.
+*/
 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
+	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
+	};
+}
+//#endregion
+//#region src/utilities/execution.utilities.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));
+*/
 async function safeExecute(fn, onError) {
-  try {
-    return await fn();
-  } catch (error) {
-    if (onError)
-      return await onError(error);
-    throw error;
-  }
+	try {
+		return await fn();
+	} catch (error) {
+		if (onError) return await onError(error);
+		throw error;
+	}
 }
+/**
+* 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`);
+*/
 async function measureExecutionTime(execution) {
-  const startedAt = performance.now();
-  const result = await execution();
-  const executionTime = performance.now() - startedAt;
-  return { result, executionTime: Math.round(executionTime) };
-}
-
-// src/zod-bulk/zod-bulk.schemas.ts
-import { z as z2 } from "zod";
-var DEFAULT_ERROR_MESSAGE = "Selection identifiers must be provided.";
+	const startedAt = performance.now();
+	const result = await execution();
+	const executionTime = performance.now() - startedAt;
+	return {
+		result,
+		executionTime: Math.round(executionTime)
+	};
+}
+//#endregion
+//#region src/zod-bulk/zod-bulk.schemas.ts
+const DEFAULT_ERROR_MESSAGE$1 = "Selection identifiers must be provided.";
+/**
+* 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),
+* });
+*/
 function zodBulkSelectionSchema({ identifierSchema }) {
-  const identifiersSchema = z2.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, {
-    message: DEFAULT_ERROR_MESSAGE
-  });
-  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.services.ts
-import { decode as decodeJWT, sign as signJWT, verify as verifyJWT } from "hono/jwt";
+	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()]);
+}
+//#endregion
+//#region src/zod-jwt/zod-jwt.services.ts
+/**
+* Signs, decodes, and verifies JWTs with optional Zod payload validation.
+* A supplied schema parses payloads returned by decoding and verification.
+*/
 var ZodJWTService = class {
-  payloadSchema;
-  algorithm;
-  defaultExpirationSeconds;
-  constructor(payloadSchema, options) {
-    this.payloadSchema = payloadSchema;
-    this.algorithm = options?.algorithm ?? "HS256";
-    this.defaultExpirationSeconds = options?.defaultExpirationSeconds ?? 60 * 15;
-  }
-  /**
-   * 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 without authenticating it and parses its payload when a schema exists.
-   * Schema validation failures return `null`, while malformed tokens still reject.
-   *
-   * @example
-   * const payload = await jwtService.decode(token);
-   */
-  async decode(token) {
-    const { payload } = decodeJWT(token);
-    if (this.payloadSchema === void 0) {
-      return payload;
-    }
-    const { success: success2, data } = await this.payloadSchema.safeParseAsync(payload);
-    return success2 ? data : null;
-  }
-  /**
-   * Verifies a token using the configured algorithm and parses its payload.
-   * Signature, expiration, and schema validation failures reject the operation.
-   *
-   * @example
-   * const payload = await jwtService.verifyOrThrow(token, secret);
-   */
-  async verifyOrThrow(token, secret) {
-    const payload = await verifyJWT(token, secret, this.algorithm);
-    if (this.payloadSchema === void 0) {
-      return payload;
-    }
-    return this.payloadSchema.parseAsync(payload);
-  }
+	payloadSchema;
+	algorithm;
+	defaultExpirationSeconds;
+	constructor(payloadSchema, options) {
+		this.payloadSchema = payloadSchema;
+		this.algorithm = options?.algorithm ?? "HS256";
+		this.defaultExpirationSeconds = options?.defaultExpirationSeconds ?? 900;
+	}
+	/**
+	* 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 sign({
+			...payload,
+			exp
+		}, 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.
+	*
+	* @example
+	* const payload = await jwtService.decode(token);
+	*/
+	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;
+	}
+	/**
+	* Verifies a token using the configured algorithm and parses its payload.
+	* Signature, expiration, and schema validation failures reject the operation.
+	*
+	* @example
+	* const payload = await jwtService.verifyOrThrow(token, secret);
+	*/
+	async verifyOrThrow(token, secret) {
+		const payload = await verify(token, secret, this.algorithm);
+		if (this.payloadSchema === void 0) return payload;
+		return this.payloadSchema.parseAsync(payload);
+	}
 };
-
-// src/zod-search/zod-search.pagination.schemas.ts
-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: 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: z3.coerce.number().int().positive().max(256).default(10)
+//#endregion
+//#region src/zod-search/zod-search.pagination.schemas.ts
+/**
+* Validates offset-based pagination shared by search request contracts.
+* Missing fields inside the required object receive predictable defaults.
+*/
+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)
 });
-var zodPaginationShape = zodPaginationSchema.shape;
-
-// src/zod-search/zod-search.schemas.ts
-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.";
-var zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
-  const hasValue = Object.values(val).some((v) => v !== void 0);
-  if (!hasValue)
-    ctx.addIssue({ code: "custom", message: DEFAULT_ERROR_MESSAGE2 });
+/**
+* Exposes pagination fields for composition into other object schemas.
+* The shape stays derived from the schema to prevent contract divergence.
+*/
+const zodPaginationShape = zodPaginationSchema.shape;
+//#endregion
+//#region src/zod-validation/zod-validation.refiners.ts
+const DEFAULT_ERROR_MESSAGE = "Invalid input. At least one field must be provided.";
+/**
+* Wraps a partial Zod object schema with:
+* 1. A runtime check ensuring at least one field is non-undefined.
+* 2. A `.transform()` that narrows the output type to `AtLeastOne<T>`,
+*    making it directly assignable to domain `*Select` and `*Update` types without casting.
+*
+* @example
+* zQuery(zodAtLeastOne(userSelectSchema)) // result: UserSelect ✓
+*/
+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);
-
-// src/zod-search/zod-search.schemas.ts
-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;
-  const shape = {
-    where: whereSchema.optional(),
-    ...options.queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
-    ...options.paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
-  };
-  return z4.object(shape).strict();
+//#endregion
+//#region src/zod-search/zod-search.schemas.ts
+/**
+* Optional text query shared by search request contracts.
+* Provided values are trimmed and must contain visible text.
+*/
+const zodSearchQuerySchema = z$1.string().trim().min(1).optional();
+/**
+* Makes every supplied filter optional while requiring one defined value.
+* Top-level optionality is added later for both composition modes equally.
+*/
+const createZodSearchWhereSchema = (filters) => zodAtLeastOne(filters.partial());
+/**
+* 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()),
+* });
+*/
+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 } : {}
+	};
+	return z$1.object(shape).strict();
 };
-
-// src/zod-validation/zod-validation.parsing.ts
-import { z as z5 } from "zod";
-
-// src/zod-validation/zod-validation.utilities.ts
-var isPlainObject = (value) => {
-  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+//#endregion
+//#region src/zod-validation/zod-validation.utilities.ts
+/**
+* Checks whether a value is a plain record backed by `Object.prototype`.
+* Arrays, null, dates, collections, and custom class instances are rejected.
+*/
+const isPlainObject = (value) => {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 };
-
-// src/zod-validation/zod-validation.parsing.ts
-var 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;
+//#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;
 };
-var asQuery = (schema) => z5.preprocess(parseQueryValue, schema);
+/**
+* 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 }
+*/
+const asQuery = (schema) => z$1.preprocess(parseQueryValue, schema);
+/**
+* Recursively converts payload values to strings without changing container structure.
+* Objects and arrays are copied while `null` and `undefined` retain omission semantics.
+*
+* @example
+* stringifyPayloadValues({ page: 2, enabled: true });
+* // { page: '2', enabled: 'true' }
+*/
 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);
-}
-export {
-  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
-};
+	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);
+}
+//#endregion
+export { 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 };