@kalutskii/foundation 0.7.9 → 0.7.10

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

@@ -194,6 +194,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 +284,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 +832,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 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

@@ -208,6 +208,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 +446,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 +454,8 @@ export {
   createStringEnumRecord,
   createUploadAccept,
   createZodSearchWhereSchema,
+  defineUploadPreset,
+  documentUploadPreset,
   failure,
   fetchAndThrow,
   fetchSafely,
@@ -454,6 +473,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.10",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "license": "MIT",
   "type": "module",