@kalutskii/foundation 0.7.9 → 0.7.11

package/README.md

@@ -24,7 +24,7 @@ The package contains several deliberately isolated areas:
 | ---------------- | ----------------------------------------------------------------------------------------- |
 | `utilities`      | Framework-independent datetime, enum, execution, generation, logging, and type utilities. |
 | `http`           | Shared HTTP result contracts, factories, status constants, and result resolvers.          |
-| `upload`         | Shared file-format metadata, upload validation, and reusable Zod file schemas.            |
+| `upload`         | Shared upload presets, file-format metadata, validation, and reusable Zod schemas.        |
 | `zod-validation` | Generic Zod parsing, validation, refinement, and related type utilities.                  |
 | `zod-search`     | Reusable search and pagination contracts composed from lower-level Zod primitives.        |
 | `zod-bulk`       | Include/exclude selection contracts shared by frontend and backend bulk operations.       |
@@ -122,6 +122,7 @@ single public API boundary and should export only symbols intentionally supporte
 | `*.services.ts`   | Stateful service classes that coordinate one external capability.         |
 | `*.validation.ts` | Ordered validation behavior returning stable domain error keys.           |
 | `*.factory.ts`    | Functions whose primary responsibility is constructing non-schema values. |
+| `*.presets.ts`    | Ready-to-use policies composed from public domain values.                 |
 | `*.resolvers.ts`  | Functions that unwrap, normalize, or translate an existing result.        |
 | `*.utilities.ts`  | Stateless reusable behavior that has no narrower architectural owner.     |
 | `*.parsing.ts`    | Input parsing and preprocessing before domain validation.                 |

package/dist/index.d.ts

@@ -20,10 +20,21 @@ declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL;
 declare const onHandlerError: ErrorHandler;
 
 /**
- * Logs request method, response status, duration, URL details, and a body preview.
- * Multipart bodies remain unread to avoid buffering uploaded file content into logs.
+ * Options controlling which request details the Hono logger may expose.
+ * Secure mode excludes query parameters and body content from log output.
  */
-declare const honoLoggingHandler: MiddlewareHandler;
+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];
@@ -194,6 +205,32 @@ declare const uploadValidationError: Readonly<{
 }>;
 
 type FileFormatConfig = (typeof fileFormatsConfig)[FileFormat];
+/**
+ * Shared upload policy consumed by browser controls and backend validation.
+ * One preset keeps format, size, capacity, and fallback rules synchronized.
+ */
+type UploadPreset<TFormats extends readonly FileFormat[] = readonly FileFormat[]> = Readonly<{
+    /**
+     * Supported formats accepted by every consumer of the preset.
+     * Const inference preserves the supplied format tuple without widening.
+     */
+    formats: TFormats;
+    /**
+     * Maximum accepted size of one uploaded file measured in bytes.
+     * Schema and client validation can share this exact numeric boundary.
+     */
+    maxFileSize: number;
+    /**
+     * Optional maximum number of files retained by one upload collection.
+     * Single-file controls can set this value to `1` for shared capacity rules.
+     */
+    maxFilesCount?: number;
+    /**
+     * Allows extensions to compensate for absent or unreliable MIME metadata.
+     * The fallback remains disabled when this option is omitted.
+     */
+    extensionFallback?: boolean;
+}>;
 /**
  * Constraints used to validate an incoming collection of browser files.
  * Existing and incoming counts are combined when enforcing capacity.
@@ -258,6 +295,45 @@ type ZodUploadFileSchemaOptions = Readonly<{
     extensionFallback?: boolean;
 }>;
 
+/**
+ * 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,
+ * });
+ */
+declare function defineUploadPreset<const TFormats extends readonly FileFormat[]>(preset: UploadPreset<TFormats>): UploadPreset<TFormats>;
+
+/**
+ * Default maximum size of one file accepted by the built-in upload presets.
+ * The 20 MiB boundary matches the existing upload component policy.
+ */
+declare const DEFAULT_UPLOAD_MAX_FILE_SIZE: number;
+/**
+ * Ready-to-use policy for every image format supported by the upload catalog.
+ * Each image may occupy up to 20 MiB while collection capacity remains unrestricted.
+ */
+declare const imageUploadPreset: Readonly<{
+    formats: readonly ["png", "jpg", "webp", "avif", "heic"];
+    maxFileSize: number;
+    maxFilesCount?: number;
+    extensionFallback?: boolean;
+}>;
+/**
+ * Ready-to-use policy for every document format supported by the upload catalog.
+ * Each document may occupy up to 20 MiB while collection capacity remains unrestricted.
+ */
+declare const documentUploadPreset: Readonly<{
+    formats: readonly ["pdf", "rtf", "txt"];
+    maxFileSize: number;
+    maxFilesCount?: number;
+    extensionFallback?: boolean;
+}>;
+
 /**
  * Builds a reusable Zod schema for one uploaded file with format and size.
  * MIME matching is strict unless extension fallback is explicitly enabled.
@@ -767,4 +843,4 @@ declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FileFormat, type FileFormatConfig, type HonoFileRespondOptions, type HonoRespondOptions, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, type UploadFilesValidationOptions, type UploadFilesValidationResult, type UploadValidationError, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, type ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+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 };

package/dist/index.js

@@ -119,29 +119,31 @@ var onHandlerError = (error, c) => {
 
 // src/hono/hono.logging.ts
 import { blue as blue2, bold, dim as dim2, white as white2 } from "kleur/colors";
-var honoLoggingHandler = async (c, next) => {
-  const requestUrl = new URL(c.req.url);
-  const searchParams = requestUrl.searchParams.toString();
-  const body = c.req.header("content-type")?.includes("multipart/form-data") ? (
-    // If the request is multipart/form-data, we avoid reading the body
-    // to prevent consuming the stream, and instead log a placeholder.
-    "[multipart]"
-  ) : (
-    // Otherwise, we read the request body as text and normalize whitespace.
-    (await c.req.raw.clone().text()).replaceAll(/\s+/g, " ").trim()
-  );
-  const bodyPreview = body.length > 80 ? `${body.slice(0, 40)}\u2026${body.slice(-40)}` : body;
-  const startTime = performance.now();
-  await next();
-  const duration = Math.round(performance.now() - startTime);
-  const coloredMethod = bold(blue2(c.req.method.padEnd(4)));
-  const coloredStatus = getColoredHTTPStatus(c.res.status)(String(c.res.status).padEnd(4));
-  const coloredTime = dim2(`${duration}ms`.padStart(6));
-  const coloredPath = white2(c.req.path.padEnd(32));
-  const coloredSearchParams = searchParams ? dim2(` (${searchParams})`) : "";
-  const coloredBody = bodyPreview ? dim2(` ${bodyPreview}`) : "";
-  log.info(`${coloredMethod} ${coloredStatus} ${coloredTime} ${coloredPath}${coloredSearchParams}${coloredBody}`, "hono");
-};
+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) {
@@ -208,6 +210,22 @@ var fileFormatsConfig = {
   [fileFormatsRecord.TXT]: { name: "TXT", mimeTypes: ["text/plain"], extensions: [".txt"] }
 };
 
+// src/upload/upload.factory.ts
+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
+});
+var documentUploadPreset = defineUploadPreset({
+  formats: [fileFormat.PDF, fileFormat.RTF, fileFormat.TXT],
+  maxFileSize: DEFAULT_UPLOAD_MAX_FILE_SIZE
+});
+
 // src/upload/upload.schemas.ts
 import { z } from "zod";
 
@@ -430,6 +448,7 @@ var parseQueryValue = (value) => {
 };
 var asQuery = (schema) => z5.preprocess(parseQueryValue, schema);
 export {
+  DEFAULT_UPLOAD_MAX_FILE_SIZE,
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
@@ -437,6 +456,8 @@ export {
   createStringEnumRecord,
   createUploadAccept,
   createZodSearchWhereSchema,
+  defineUploadPreset,
+  documentUploadPreset,
   failure,
   fetchAndThrow,
   fetchSafely,
@@ -454,6 +475,7 @@ export {
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
+  imageUploadPreset,
   isFileExtensionSupported,
   isFileFormatSupported,
   isFileMimeTypeSupported,

package/package.json

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