@kalutskii/foundation 0.7.11 → 0.7.12

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { SQL } from 'drizzle-orm';
-import { ErrorHandler, MiddlewareHandler, Context, TypedResponse } from 'hono';
+import { ErrorHandler, Context, TypedResponse, MiddlewareHandler } from 'hono';
+import * as kleur_colors from 'kleur/colors';
 import z$1, { z, ZodObject, ZodRawShape } from 'zod';
 import { Locale } from 'date-fns';
 import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
@@ -19,23 +20,6 @@ declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL;
  */
 declare const onHandlerError: ErrorHandler;
 
-/**
- * Options controlling which request details the Hono logger may expose.
- * Secure mode excludes query parameters and body content from log output.
- */
-type HonoLoggingOptions = {
-    /**
-     * Prevents query parameters and request bodies from being read or logged.
-     * Defaults to `false`, preserving detailed request logging.
-     */
-    secure?: boolean;
-};
-/**
- * Creates middleware that logs request metadata and an optional body preview.
- * Multipart bodies remain unread, while secure mode omits all sensitive input details.
- */
-declare function honoLoggingHandler(options?: HonoLoggingOptions): MiddlewareHandler;
-
 declare const SUCCESS_STATUS_CODES: readonly [200, 201, 202, 307];
 declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 500];
 
@@ -120,6 +104,98 @@ declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher
  */
 declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
 
+/**
+ * Terminal color configuration for every supported logging level.
+ * The `LogLevel` contract prevents missing or unsupported level entries.
+ */
+declare const logLevelColors: {
+    readonly info: typeof kleur_colors.print;
+    readonly warn: typeof kleur_colors.print;
+    readonly error: typeof kleur_colors.print;
+};
+/**
+ * Public placeholder written instead of sensitive query and JSON values.
+ * One stable marker keeps redacted output recognizable across log consumers.
+ */
+declare 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.
+ */
+declare const sensitiveLogKeyParts: readonly ["password", "passwd", "token", "secret", "authorization", "apikey", "credential"];
+/**
+ * Terminal colors assigned to the supported HTTP response status ranges.
+ * Unlisted ranges intentionally retain the terminal's default text appearance.
+ */
+declare const httpStatusColors: readonly [{
+    readonly range: readonly [200, 299];
+    readonly color: typeof kleur_colors.print;
+}, {
+    readonly range: readonly [400, 499];
+    readonly color: typeof kleur_colors.print;
+}, {
+    readonly range: readonly [500, 599];
+    readonly color: typeof kleur_colors.print;
+}];
+
+declare const logLevelsArray: readonly ["info", "warn", "error"];
+type LogLevel = (typeof logLevelsArray)[number];
+declare const logLevelsRecord: Readonly<{
+    ERROR: "error";
+    INFO: "info";
+    WARN: "warn";
+}>;
+declare const logLevel: Readonly<{
+    ERROR: "error";
+    INFO: "info";
+    WARN: "warn";
+}>;
+
+/**
+ * Logs Hono request metadata with query parameters and a normalized body preview.
+ * Sensitive values are redacted by partial key match before output is written.
+ */
+declare const loggingMiddleware: MiddlewareHandler;
+
+/**
+ * Replaces sensitive query values using partial, case-insensitive key matching.
+ * A new collection is returned so the caller's search parameters remain unchanged.
+ */
+declare function redactSensitiveSearchParams(searchParams: URLSearchParams): URLSearchParams;
+/**
+ * Replaces values under sensitive keys throughout a serialized JSON structure.
+ * Invalid JSON and payloads without matching keys are returned byte-for-byte unchanged.
+ */
+declare function redactSensitiveJSON(json: string): string;
+
+/**
+ * Writes timestamped and colorized messages using a stable service column.
+ * Error messages may include a stack trace on a subordinate second line.
+ */
+declare const log: {
+    /**
+     * Writes an informational message with an optional service label.
+     * Missing service names use the shared `log` fallback label.
+     */
+    info(message: string, service?: string): void;
+    /**
+     * Writes a warning message with an optional service label.
+     * Missing service names use the shared `log` fallback label.
+     */
+    warn(message: string, service?: string): void;
+    /**
+     * Writes an error message with optional service and stack trace context.
+     * Provided stack traces are rendered beneath the primary message.
+     */
+    error(message: string, service?: string, stack?: string): void;
+};
+
+/**
+ * Selects a terminal color function for one HTTP response status.
+ * Successes are green, client errors yellow, and server errors red.
+ */
+declare function getColoredHTTPStatus(status: number): (text: string) => string;
+
 /**
  * Canonical metadata shared by upload controls and runtime validation.
  * Every supported format defines display, MIME, and extension values.
@@ -511,36 +587,6 @@ declare function measureExecutionTime<T>(execution: () => Promise<T>): Promise<M
  */
 declare function generateRandomString(length?: number): string;
 
-/**
- * Selects a terminal color function for one HTTP response status.
- * Successes are green, client errors yellow, and server errors red.
- *
- * @example
- * getColoredHTTPStatus(404)('404');
- */
-declare function getColoredHTTPStatus(status: number): (text: string) => string;
-/**
- * Shared logging interface for informational, warning, and error messages.
- * Every level supports a service label while errors may include a stack trace.
- */
-declare const log: {
-    /**
-     * Writes an informational message with an optional service label.
-     * Missing service names use the shared `log` fallback label.
-     */
-    info: (message: string, service?: string) => void;
-    /**
-     * Writes a warning message with an optional service label.
-     * Missing service names use the shared `log` fallback label.
-     */
-    warn: (message: string, service?: string) => void;
-    /**
-     * Writes an error message with optional service and stack trace context.
-     * Stack traces are rendered beneath the primary error message when supplied.
-     */
-    error: (message: string, service?: string, stack?: string) => void;
-};
-
 /**
  * Utility type that simplifies a given type T by flattening its structure.
  * This is particularly useful for improving the readability of complex types.
@@ -843,4 +889,4 @@ declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FileFormat, type FileFormatConfig, type HonoFileRespondOptions, type HonoLoggingOptions, type HonoRespondOptions, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, type UploadFilesValidationOptions, type UploadFilesValidationResult, type UploadPreset, type UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, defineUploadPreset, documentUploadPreset, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FileFormat, type FileFormatConfig, type HonoFileRespondOptions, type HonoRespondOptions, type JWTServiceOptions, type JWTSignOptions, type LogLevel, type MeasuredExecution, type Payload, type PayloadSchema, REDACTED_LOG_VALUE, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, type UploadFilesValidationOptions, type UploadFilesValidationResult, type UploadPreset, type UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, defineUploadPreset, documentUploadPreset, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, httpStatusColors, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, success, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };

package/dist/index.js

@@ -12,7 +12,7 @@ function sqlWhere(table, where) {
 
 // src/hono/hono.execution.ts
 import { HTTPException } from "hono/http-exception";
-import { red as red2 } from "kleur/colors";
+import { red as red3 } from "kleur/colors";
 
 // src/http/http.factory.ts
 function success({ status, data }) {
@@ -22,19 +22,8 @@ function failure({ status, error }) {
   return { kind: "error", status, error };
 }
 
-// src/utilities/generation.utilities.ts
-var DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-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/utilities/logging.utilities.ts
-import { blue, dim, green, red, white, yellow } from "kleur/colors";
+// src/logging/logging.services.ts
+import { dim, red as red2, white } from "kleur/colors";
 
 // src/utilities/datetime.utilities.ts
 import { format } from "date-fns";
@@ -62,50 +51,90 @@ function formatTime(time, { locale = ru, tz = "Europe/London" } = {}) {
   return `${format(zonedTime, "HH:mm:ss, d MMMM yyyy", { locale })} ${getUTCOffset(zonedTime, tz)}`;
 }
 
-// src/utilities/logging.utilities.ts
-var HTTP_STATUS_COLORS = [
+// src/logging/logging.constants.ts
+import { blue, green, red, yellow } from "kleur/colors";
+
+// src/utilities/enums.utilities.ts
+function createStringEnumRecord(values) {
+  return Object.freeze(Object.fromEntries(values.map((value) => [value.replace(/\./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
+};
+var REDACTED_LOG_VALUE = "[redacted]";
+var 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 }
 ];
-var LOG_LEVEL_COLORS = { info: blue, warn: yellow, error: red };
-function getColoredHTTPStatus(status) {
-  const statusColor = HTTP_STATUS_COLORS.find(({ range: [minimum, maximum] }) => {
-    return status >= minimum && status <= maximum;
-  });
-  return statusColor ? statusColor.color : (text) => text;
-}
+
+// src/logging/logging.services.ts
 function writeLog(message, level, service = "log", stack) {
   const timestamp = dim(getFormattedTime());
-  const serviceName = LOG_LEVEL_COLORS[level](service.padEnd(12));
+  const serviceName = logLevelColors[level](service.padEnd(12));
   const formattedMessage = white(message);
   console.log(`[${timestamp}] ${serviceName} | ${formattedMessage}`);
   if (stack)
-    console.log(`[${timestamp}] ${red("\u21B3 trace").padEnd(18)} | ${dim(stack)}`);
+    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),
+  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),
+  warn(message, service) {
+    writeLog(message, "warn", service);
+  },
   /**
    * Writes an error message with optional service and stack trace context.
-   * Stack traces are rendered beneath the primary error message when supplied.
+   * Provided stack traces are rendered beneath the primary message.
    */
-  error: (message, service, stack) => writeLog(message, "error", service, stack)
+  error(message, service, stack) {
+    writeLog(message, "error", service, stack);
+  }
 };
 
+// src/utilities/generation.utilities.ts
+var DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+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
 function proceedUnhandledError(error) {
   const errorId = generateRandomString(6);
   const errorMessage = error instanceof Error ? error.stack ?? error.message : JSON.stringify(error);
-  log.error(`Unhandled error: ${red2(errorMessage)}`, errorId);
+  log.error(`Unhandled error: ${red3(errorMessage)}`, errorId);
   return failure({ status: 500, error: `Internal server error | ${errorId}` });
 }
 var onHandlerError = (error, c) => {
@@ -117,34 +146,6 @@ var onHandlerError = (error, c) => {
   return c.json(response, response.status);
 };
 
-// src/hono/hono.logging.ts
-import { blue as blue2, bold, dim as dim2, white as white2 } from "kleur/colors";
-function honoLoggingHandler(options = {}) {
-  return async (c, next) => {
-    const searchParams = new URL(c.req.url).searchParams.toString();
-    const body = c.req.header("content-type")?.includes("multipart/form-data") ? (
-      // Multipart content remains unread to avoid buffering uploaded files;
-      // The placeholder records its presence without exposing any fields;
-      "[multipart]"
-    ) : (
-      // Other bodies are read from a clone and normalized for one-line output;
-      // The original request stream remains available to downstream handlers;
-      (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 = options.secure ? "" : dim2(` (${searchParams})`);
-    const coloredBody = options.secure ? "" : dim2(` ${bodyPreview}`);
-    log.info(`${coloredMethod} ${coloredStatus} ${coloredTime} ${coloredPath}${coloredSearchParams}${coloredBody}`, "hono");
-  };
-}
-
 // src/hono/hono.respond.ts
 function respond(c, options) {
   return c.json(success({ status: options.status, data: options.data ?? {} }), options.status);
@@ -173,10 +174,81 @@ async function fetchAndThrow(fetcher) {
   return response.data;
 }
 
-// src/utilities/enums.utilities.ts
-function createStringEnumRecord(values) {
-  return Object.freeze(Object.fromEntries(values.map((value) => [value.replace(/\./g, "_").toUpperCase(), value])));
+// src/logging/logging.middleware.ts
+import { blue as blue2, bold, dim as dim2, white as white2 } from "kleur/colors";
+
+// src/logging/logging.security.ts
+function isSensitiveLogKey(key) {
+  const normalizedKey = key.toLowerCase().replaceAll(/[^a-z]/g, "");
+  return sensitiveLogKeyParts.some((sensitivePart) => normalizedKey.includes(sensitivePart));
+}
+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 };
+}
+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;
 }
+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
+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");
+};
 
 // src/upload/upload.enums.ts
 var fileFormatsArray = [
@@ -450,6 +522,7 @@ var asQuery = (schema) => z5.preprocess(parseQueryValue, schema);
 export {
   DEFAULT_UPLOAD_MAX_FILE_SIZE,
   EXCEPTION_STATUS_CODES,
+  REDACTED_LOG_VALUE,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
   asQuery,
@@ -474,20 +547,28 @@ export {
   getFormattedTime,
   getUTCOffset,
   getZonedTime,
-  honoLoggingHandler,
+  httpStatusColors,
   imageUploadPreset,
   isFileExtensionSupported,
   isFileFormatSupported,
   isFileMimeTypeSupported,
   isPlainObject,
   log,
+  logLevel,
+  logLevelColors,
+  logLevelsArray,
+  logLevelsRecord,
+  loggingMiddleware,
   matchesMimeType,
   measureExecutionTime,
   normalizeFileExtension,
   onHandlerError,
   parseQueryValue,
+  redactSensitiveJSON,
+  redactSensitiveSearchParams,
   respond,
   safeExecute,
+  sensitiveLogKeyParts,
   sqlWhere,
   success,
   uploadValidationError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.7.11",
+  "version": "0.7.12",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "license": "MIT",
   "type": "module",