@kalutskii/foundation 0.7.8 → 0.7.10

package/dist/index.js

@@ -40,50 +40,64 @@ import { blue, 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";
-var getZonedTime = ({ tz = "Europe/London" } = {}) => {
+function getZonedTime({ tz = "Europe/London" } = {}) {
   return toZonedTime(/* @__PURE__ */ new Date(), tz);
-};
-var getUTCOffset = (date, tz) => {
+}
+function getUTCOffset(date, tz) {
   const offset = getTimezoneOffset(tz, date) / (60 * 60 * 1e3);
   return `(${offset >= 0 ? "+" : ""}${offset} UTC)`;
-};
-var getFormattedTime = ({ tz = "Europe/London" } = {}) => {
+}
+function getFormattedTime({ tz = "Europe/London" } = {}) {
   const zonedTime = getZonedTime({ tz });
   return `${format(zonedTime, "HH:mm:ss")} ${getUTCOffset(zonedTime, tz)}`;
-};
-var getFormattedDate = ({ tz = "Europe/London", withTime = true } = {}) => {
+}
+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)}` : ""}`;
-};
-var formatTime = (time, { locale = ru, tz = "Europe/London" } = {}) => {
+}
+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/utilities/logging.utilities.ts
+var HTTP_STATUS_COLORS = [
+  { 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 colorMap = [
-    { range: [200, 299], colorFn: green },
-    { range: [400, 499], colorFn: yellow },
-    { range: [500, 599], colorFn: red }
-  ];
-  const statusColor = colorMap.find(({ range: [min, max] }) => status >= min && status <= max);
-  return statusColor ? statusColor.colorFn : (text) => text;
+  const statusColor = HTTP_STATUS_COLORS.find(({ range: [minimum, maximum] }) => {
+    return status >= minimum && status <= maximum;
+  });
+  return statusColor ? statusColor.color : (text) => text;
 }
 function writeLog(message, level, service = "log", stack) {
-  const logColorMap = { info: blue, warn: yellow, error: red };
   const timestamp = dim(getFormattedTime());
-  const serviceName = logColorMap[level](service.padEnd(12));
+  const serviceName = LOG_LEVEL_COLORS[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)}`);
 }
 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.
+   * Stack traces are rendered beneath the primary error message when supplied.
+   */
   error: (message, service, stack) => writeLog(message, "error", service, stack)
 };
 
@@ -123,7 +137,7 @@ var honoLoggingHandler = async (c, next) => {
   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(44));
+  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");
@@ -162,14 +176,131 @@ function createStringEnumRecord(values) {
   return Object.freeze(Object.fromEntries(values.map((value) => [value.replace(/\./g, "_").toUpperCase(), value])));
 }
 
+// src/upload/upload.enums.ts
+var fileFormatsArray = [
+  ...["png", "jpg", "webp", "avif", "heic"],
+  // Image formats.
+  ...["pdf", "rtf", "txt"]
+  // Text and document formats.
+];
+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.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"] }
+};
+
+// 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";
+
+// src/upload/upload.utilities.ts
+function getFileExtension(fileName) {
+  const extensionIndex = fileName.lastIndexOf(".");
+  return extensionIndex > 0 && extensionIndex < fileName.length - 1 ? fileName.slice(extensionIndex).toLowerCase() : "";
+}
+function normalizeFileExtension(extension) {
+  const normalizedExtension = extension.toLowerCase();
+  return normalizedExtension.startsWith(".") ? normalizedExtension : `.${normalizedExtension}`;
+}
+function matchesMimeType(fileMimeType, configuredMimeType) {
+  if (configuredMimeType.endsWith("/*"))
+    return fileMimeType.startsWith(configuredMimeType.slice(0, -1));
+  return fileMimeType === configuredMimeType;
+}
+function isFileMimeTypeSupported(file, formats) {
+  return formats.some((format2) => fileFormatsConfig[format2].mimeTypes.some((mimeType) => matchesMimeType(file.type, mimeType)));
+}
+function isFileExtensionSupported(file, formats) {
+  const fileExtension = getFileExtension(file.name);
+  return formats.some((format2) => fileFormatsConfig[format2].extensions.some((extension) => normalizeFileExtension(extension) === fileExtension));
+}
+function isFileFormatSupported(file, formats) {
+  return isFileMimeTypeSupported(file, formats) || isFileExtensionSupported(file, formats);
+}
+function createUploadAccept(formats) {
+  const acceptedValues = formats.flatMap((format2) => [
+    ...fileFormatsConfig[format2].mimeTypes,
+    ...fileFormatsConfig[format2].extensions
+  ]);
+  return [...new Set(acceptedValues)].join(",");
+}
+
+// src/upload/upload.schemas.ts
+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);
+}
+
+// src/upload/upload.validation.ts
+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;
+}
+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
 async function safeExecute(fn, onError) {
   try {
     return await fn();
-  } catch (err) {
+  } catch (error) {
     if (onError)
-      return await onError(err);
-    throw err;
+      return await onError(error);
+    throw error;
   }
 }
 async function measureExecutionTime(execution) {
@@ -180,19 +311,19 @@ async function measureExecutionTime(execution) {
 }
 
 // src/zod-bulk/zod-bulk.schemas.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var DEFAULT_ERROR_MESSAGE = "Selection identifiers must be provided.";
-var zodBulkSelectionSchema = ({ identifierSchema }) => {
-  const identifiersSchema = z.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, {
+function zodBulkSelectionSchema({ identifierSchema }) {
+  const identifiersSchema = z2.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, {
     message: DEFAULT_ERROR_MESSAGE
   });
-  return z.discriminatedUnion("mode", [
-    z.object({ mode: z.literal("include"), identifiers: identifiersSchema }).strict(),
-    z.object({ mode: z.literal("exclude"), excludedIdentifiers: identifiersSchema }).strict()
+  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.schemas.ts
+// src/zod-jwt/zod-jwt.services.ts
 import { decode as decodeJWT, sign as signJWT, verify as verifyJWT } from "hono/jwt";
 var ZodJWTService = class {
   payloadSchema;
@@ -204,37 +335,41 @@ var ZodJWTService = class {
     this.defaultExpirationSeconds = options?.defaultExpirationSeconds ?? 60 * 15;
   }
   /**
-   * Signs a JWT token with the provided payload and secret, using the configured algorithm and expiration settings.
-   * Example usage: `const accessToken = await JWTServiceInstance.sign({ userId: 123 }, 'my-secret', { expiresInSeconds: 300 });`
+   * 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 a JWT token, and if a Zod schema is provided, validates the payload against it.
-   * Returns the decoded payload if valid, or null if invalid or if the token cannot be decoded.
+   * Decodes without authenticating it and parses its payload when a schema exists.
+   * Schema validation failures return `null`, while malformed tokens still reject.
    *
-   * Example usage: `const payload = await JWTServiceInstance.decode(token);`
+   * @example
+   * const payload = await jwtService.decode(token);
    */
   async decode(token) {
     const { payload } = decodeJWT(token);
-    if (!this.payloadSchema) {
+    if (this.payloadSchema === void 0) {
       return payload;
     }
     const { success: success2, data } = await this.payloadSchema.safeParseAsync(payload);
     return success2 ? data : null;
   }
   /**
-   * Verifies and decodes a JWT token using the provided secret and configured algorithm,
-   * then validates the payload against the Zod schema if one is provided.
+   * Verifies a token using the configured algorithm and parses its payload.
+   * Signature, expiration, and schema validation failures reject the operation.
    *
-   * Throws an error if verification fails or if the payload is invalid according to the schema.
-   * Example usage: `const payload = await JWTServiceInstance.verifyOrThrow(token, 'my-secret');`
+   * @example
+   * const payload = await jwtService.verifyOrThrow(token, secret);
    */
   async verifyOrThrow(token, secret) {
     const payload = await verifyJWT(token, secret, this.algorithm);
-    if (!this.payloadSchema) {
+    if (this.payloadSchema === void 0) {
       return payload;
     }
     return this.payloadSchema.parseAsync(payload);
@@ -242,23 +377,23 @@ var ZodJWTService = class {
 };
 
 // src/zod-search/zod-search.pagination.schemas.ts
-import { z as z2 } from "zod";
-var zodPaginationSchema = z2.object({
+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: z2.coerce.number().int().nonnegative().default(0),
+  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: z2.coerce.number().int().positive().default(10)
+  limit: z3.coerce.number().int().positive().default(10)
 });
 var zodPaginationShape = zodPaginationSchema.shape;
 
 // src/zod-search/zod-search.schemas.ts
-import { z as z3 } from "zod";
+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.";
@@ -269,7 +404,7 @@ var zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
 }).transform((val) => val);
 
 // src/zod-search/zod-search.schemas.ts
-var zodSearchQuerySchema = z3.string().trim().min(1).optional();
+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;
@@ -278,11 +413,11 @@ var zodSearchSchema = (options) => {
     ...options.queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
     ...options.paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
   };
-  return z3.object(shape).strict();
+  return z4.object(shape).strict();
 };
 
 // src/zod-validation/zod-validation.parsing.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/zod-validation/zod-validation.utilities.ts
 var isPlainObject = (value) => {
@@ -309,37 +444,60 @@ var parseQueryValue = (value) => {
     return Number(normalized);
   return value;
 };
-var asQuery = (schema) => z4.preprocess(parseQueryValue, schema);
+var asQuery = (schema) => z5.preprocess(parseQueryValue, schema);
 export {
+  DEFAULT_UPLOAD_MAX_FILE_SIZE,
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
   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,
-  zodSearchSchema
+  zodSearchQuerySchema,
+  zodSearchSchema,
+  zodUploadFileSchema
 };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
+  "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
@@ -12,10 +13,12 @@
   },
   "scripts": {
     "build": "tsup",
+    "test": "bun test",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --ext .ts --fix",
+    "lint:check": "eslint . --ext .ts",
     "format": "prettier --write .",
-    "test": "bun test"
+    "format:check": "prettier --check ."
   },
   "exports": {
     ".": {
@@ -27,7 +30,6 @@
     "dist"
   ],
   "peerDependencies": {
-    "@hono/zod-validator": "^0.8.0",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
     "drizzle-orm": "^1.0.0-beta.22",