@kalutskii/foundation 0.2.3 → 0.3.1

package/dist/index.d.ts

@@ -1,5 +1,10 @@
+import * as hono from 'hono';
 import { ErrorHandler, MiddlewareHandler, Context, TypedResponse, ValidationTargets } from 'hono';
-import z$1, { z, ZodNumber } from 'zod';
+import * as zod from 'zod';
+import zod__default, { z, ZodNumber, ZodType } from 'zod';
+import * as hono_utils_types from 'hono/utils/types';
+import * as zod_v4_core from 'zod/v4/core';
+import * as zod_v3 from 'zod/v3';
 import { Locale } from 'date-fns';
 import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
 
@@ -87,19 +92,11 @@ declare function respond<T extends object = Record<string, never>, S extends Suc
     data?: T;
 }): Response & TypedResponse<APISuccess<SerializeDates<T>> | APIError, S, 'json'>;
 
-/** The subset of Hono validation targets supported for payload extraction. */
-type PayloadTarget = Extract<keyof ValidationTargets, 'json' | 'query' | 'param'>;
-/** Raw payload readers for each supported target, keyed by {@link PayloadTarget}. */
-declare const requestReaders: {
-    json: (c: Context) => Promise<unknown>;
-    query: (c: Context) => unknown;
-    param: (c: Context) => unknown;
-};
-/**
- * Reads the raw payload from the request and validates it against the provided Zod schema.
- * Throws an `HTTPException(400)` when validation fails or when the payload cannot be read.
- */
-declare function requirePayload<TSchema extends z.ZodTypeAny>(c: Context, target: PayloadTarget, schema: TSchema): Promise<z.infer<TSchema>>;
+/** Wrapper around the standard hono/zod-validator, throws HTTPException on validation failure. */
+declare const zQuery: <T extends ZodType, Target extends keyof ValidationTargets>(target: Target, schema: T) => hono.MiddlewareHandler<hono.Env, string, {
+    in: (undefined extends (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) ? true : false) extends true ? { [K in Target]?: ([T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never] extends [ValidationTargets[K]] ? ValidationTargets[K] & (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) : [Exclude<T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never, undefined>] extends [never] ? {} : [Exclude<T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never, undefined>] extends [object] ? undefined extends (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) ? ((T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) & undefined) | (((Exclude<T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never, (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) & undefined> extends infer T_3 ? { [K_4 in keyof T_3]: ([Exclude<T_3[K_4], undefined>] extends [string] ? [string & Exclude<T_3[K_4], undefined>] extends [hono_utils_types.UnionToIntersection<string & Exclude<T_3[K_4], undefined>>] ? false : true : false) extends true ? T_3[K_4] : ([unknown] extends [T_3[K_4]] ? false : undefined extends T_3[K_4] ? true : false) extends true ? T_3[K_4] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_2 ? { [K_3 in keyof T_2]: T_2[K_3]; } : never) extends infer T_1 ? { [K_2 in keyof T_1]: T_1[K_2]; } : never) : (((T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) extends infer T_6 ? { [K_7 in keyof T_6]: ([Exclude<T_6[K_7], undefined>] extends [string] ? [string & Exclude<T_6[K_7], undefined>] extends [hono_utils_types.UnionToIntersection<string & Exclude<T_6[K_7], undefined>>] ? false : true : false) extends true ? T_6[K_7] : ([unknown] extends [T_6[K_7]] ? false : undefined extends T_6[K_7] ? true : false) extends true ? T_6[K_7] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_5 ? { [K_6 in keyof T_5]: T_5[K_6]; } : never) extends infer T_4 ? { [K_5 in keyof T_4]: T_4[K_5]; } : never : {}) | undefined; } : { [K_1 in Target]: [T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never] extends [ValidationTargets[K_1]] ? ValidationTargets[K_1] & (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) : [Exclude<T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never, undefined>] extends [never] ? {} : [Exclude<T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never, undefined>] extends [object] ? undefined extends (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) ? ((T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) & undefined) | (((Exclude<T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never, (T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) & undefined> extends infer T_3 ? { [K_5 in keyof T_3]: ([Exclude<T_3[K_5], undefined>] extends [string] ? [string & Exclude<T_3[K_5], undefined>] extends [hono_utils_types.UnionToIntersection<string & Exclude<T_3[K_5], undefined>>] ? false : true : false) extends true ? T_3[K_5] : ([unknown] extends [T_3[K_5]] ? false : undefined extends T_3[K_5] ? true : false) extends true ? T_3[K_5] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_2 ? { [K_4 in keyof T_2]: T_2[K_4]; } : never) extends infer T_1 ? { [K_3 in keyof T_1]: T_1[K_3]; } : never) : (((T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.input<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.input<T> : never) extends infer T_6 ? { [K_8 in keyof T_6]: ([Exclude<T_6[K_8], undefined>] extends [string] ? [string & Exclude<T_6[K_8], undefined>] extends [hono_utils_types.UnionToIntersection<string & Exclude<T_6[K_8], undefined>>] ? false : true : false) extends true ? T_6[K_8] : ([unknown] extends [T_6[K_8]] ? false : undefined extends T_6[K_8] ? true : false) extends true ? T_6[K_8] : Target_1 extends "form" ? T$1 | T$1[] : Target_1 extends "query" ? string | string[] : Target_1 extends "param" ? string : Target_1 extends "header" ? string : Target_1 extends "cookie" ? string : unknown; } : never) extends infer T_5 ? { [K_7 in keyof T_5]: T_5[K_7]; } : never) extends infer T_4 ? { [K_6 in keyof T_4]: T_4[K_6]; } : never : {}; };
+    out: { [K_2 in Target]: T extends zod_v3.ZodType<any, zod_v3.ZodTypeDef, any> ? zod_v3.output<T> : T extends zod_v4_core.$ZodType<unknown, unknown, zod_v4_core.$ZodTypeInternals<unknown, unknown>> ? zod.infer<T> : never; };
+}, never>;
 
 /**
  * Returns the current time in the specified timezone.
@@ -178,7 +175,7 @@ type JWTSignOptions = {
     expiresInSeconds?: number;
 };
 
-declare class ZodJWTService<TSchema extends z$1.ZodObject<z$1.ZodRawShape>> {
+declare class ZodJWTService<TSchema extends zod__default.ZodObject<zod__default.ZodRawShape>> {
     readonly payloadSchema: TSchema;
     protected readonly algorithm: SymmetricAlgorithm;
     protected readonly defaultExpirationSeconds: number;
@@ -187,12 +184,17 @@ declare class ZodJWTService<TSchema extends z$1.ZodObject<z$1.ZodRawShape>> {
      * 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 });`
      */
-    sign(payload: z$1.infer<TSchema>, secret: string, options?: JWTSignOptions): Promise<string>;
+    sign(payload: zod__default.infer<TSchema>, secret: string, options?: JWTSignOptions): Promise<string>;
+    /**
+     * Decodes a JWT token, and validates the payload against the Zod schema.
+     * Note: This method does NOT verify the token's signature or check for expiration.
+     */
+    decode(token: string): Promise<zod__default.infer<TSchema> | null>;
     /**
      * Verifies and decodes a JWT token using the provided secret and configured algorithm,
      * then validates the payload against the Zod schema, also throws on expired tokens.
      */
-    verifyOrThrow(token: string, secret: string): Promise<z$1.infer<TSchema>>;
+    verifyOrThrow(token: string, secret: string): Promise<zod__default.infer<TSchema>>;
 }
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, onHandlerError, requestReaders, requirePayload, respond, safeExecute, success };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, onHandlerError, respond, safeExecute, success, zQuery };

package/dist/index.js

@@ -75,13 +75,13 @@ function getColoredHTTPStatus(status) {
     { range: [400, 499], colorFn: yellow },
     { range: [500, 599], colorFn: red }
   ];
-  const statusColor = colorMap.find(({ range: [min, max] }) => status >= (min || 0) && status <= (max || 600));
+  const statusColor = colorMap.find(({ range: [min, max] }) => status >= min && status <= max);
   return statusColor ? statusColor.colorFn : (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(18);
+  const serviceName = logColorMap[level](service.padEnd(12));
   const formattedMessage = white(message);
   console.log(`[${timestamp}] ${serviceName} | ${formattedMessage}`);
   if (stack)
@@ -96,7 +96,7 @@ var log = {
 // src/hono/hono.execution.ts
 function proceedUnhandledError(error) {
   const errorId = generateRandomString(6);
-  const errorMessage = error instanceof Error ? error.message + error.stack : JSON.stringify(error);
+  const errorMessage = error instanceof Error ? error.stack ?? error.message : JSON.stringify(error);
   log.error(`Unhandled error: ${red2(errorMessage)}`, errorId);
   return failure({ status: 500, error: `Internal server error | ${errorId}` });
 }
@@ -131,7 +131,15 @@ function respond(c, options) {
 }
 
 // src/hono/hono.validation.ts
+import { zValidator as zv } from "@hono/zod-validator";
 import { HTTPException as HTTPException2 } from "hono/http-exception";
+var zQuery = (target, schema) => {
+  return zv(target, schema, (result, _c) => {
+    if (result.success)
+      return;
+    throw new HTTPException2(400, { message: result.error.message });
+  });
+};
 
 // src/utilities/execution.utilities.ts
 async function safeExecute(fn, onError) {
@@ -144,23 +152,6 @@ async function safeExecute(fn, onError) {
   }
 }
 
-// src/hono/hono.validation.ts
-var FALLBACK_ERROR_MESSAGE = "Failed to decode request payload, please ensure it is correctly formatted.";
-var requestReaders = {
-  json: async (c) => safeExecute(() => c.req.json(), () => {
-    throw new HTTPException2(400, { message: FALLBACK_ERROR_MESSAGE });
-  }),
-  query: (c) => c.req.query(),
-  param: (c) => c.req.param()
-};
-async function requirePayload(c, target, schema) {
-  const rawPayload = await requestReaders[target](c);
-  const parsedPayload = await schema.safeParseAsync(rawPayload);
-  if (parsedPayload.success)
-    return parsedPayload.data;
-  throw new HTTPException2(400, { message: parsedPayload.error.message });
-}
-
 // src/utilities/serialization.utilities.ts
 import { z } from "zod";
 var asQueryNumber = (schema) => z.preprocess((v) => typeof v === "string" ? Number(v) : v, schema);
@@ -182,7 +173,7 @@ var asQueryBoolean = (schema) => {
 };
 
 // src/zod-jwt/zod-jwt.schemas.ts
-import { sign as signJWT, verify as verifyJWT } from "hono/jwt";
+import { decode as decodeJWT, sign as signJWT, verify as verifyJWT } from "hono/jwt";
 var ZodJWTService = class {
   payloadSchema;
   algorithm;
@@ -200,13 +191,22 @@ var ZodJWTService = class {
     const exp = Math.floor(Date.now() / 1e3) + (options?.expiresInSeconds ?? this.defaultExpirationSeconds);
     return signJWT({ ...payload, exp }, secret, this.algorithm);
   }
+  /**
+   * Decodes a JWT token, and validates the payload against the Zod schema.
+   * Note: This method does NOT verify the token's signature or check for expiration.
+   */
+  async decode(token) {
+    const { payload } = decodeJWT(token);
+    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, also throws on expired tokens.
    */
   async verifyOrThrow(token, secret) {
     const payload = await verifyJWT(token, secret, this.algorithm);
-    return this.payloadSchema.parse(payload);
+    return this.payloadSchema.parseAsync(payload);
   }
 };
 export {
@@ -228,9 +228,8 @@ export {
   honoLoggingHandler,
   log,
   onHandlerError,
-  requestReaders,
-  requirePayload,
   respond,
   safeExecute,
-  success
+  success,
+  zQuery
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "type": "module",
   "repository": {
@@ -25,6 +25,7 @@
     "dist"
   ],
   "peerDependencies": {
+    "@hono/zod-validator": "^0.8.0",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
     "hono": "^4.12.18",