@kalutskii/foundation 0.1.10 → 0.2.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { ErrorHandler, MiddlewareHandler, Context, TypedResponse } from 'hono';
-import { z, ZodNumber } from 'zod';
+import { ErrorHandler, MiddlewareHandler, Context, TypedResponse, ValidationTargets } from 'hono';
+import z$1, { z, ZodNumber } from 'zod';
 import { Locale } from 'date-fns';
+import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
 
 declare const SUCCESS_STATUS_CODES: readonly [200, 201, 202, 307];
 declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 500];
@@ -86,6 +87,20 @@ 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>>;
+
 /**
  * Returns the current time in the specified timezone.
  * Example: getZonedTime({ tz: 'America/New_York' }) = new Date('2026-03-15T12:00:00Z')
@@ -150,4 +165,34 @@ declare const log: {
     error: (message: string, service?: string, stack?: string) => void;
 };
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, onHandlerError, respond, safeExecute, success };
+/** Options for configuring the JWT service. */
+type JWTServiceOptions = {
+    /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
+    algorithm?: SymmetricAlgorithm;
+    /** The default number of seconds until a signed JWT expires. Defaults to 900 seconds (15 minutes). */
+    defaultExpirationSeconds?: number;
+};
+/** Options for signing a JWT. */
+type JWTSignOptions = {
+    /** The number of seconds until the JWT expires. */
+    expiresInSeconds?: number;
+};
+
+declare class ZodJWTService<TSchema extends z$1.ZodObject<z$1.ZodRawShape>> {
+    readonly payloadSchema: TSchema;
+    protected readonly algorithm: SymmetricAlgorithm;
+    protected readonly defaultExpirationSeconds: number;
+    constructor(payloadSchema: TSchema, options?: JWTServiceOptions);
+    /**
+     * 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>;
+    /**
+     * 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>>;
+}
+
+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 };

package/dist/index.js

@@ -130,6 +130,9 @@ function respond(c, options) {
   return c.json(success({ status: options.status, data: options.data ?? {} }), options.status);
 }
 
+// src/hono/hono.validation.ts
+import { HTTPException as HTTPException2 } from "hono/http-exception";
+
 // src/utilities/execution.utilities.ts
 async function safeExecute(fn, onError) {
   try {
@@ -141,6 +144,22 @@ async function safeExecute(fn, onError) {
   }
 }
 
+// src/hono/hono.validation.ts
+var requestReaders = {
+  json: async (c) => c.req.json(),
+  query: (c) => c.req.query(),
+  param: (c) => c.req.param()
+};
+async function requirePayload(c, target, schema) {
+  return safeExecute(async () => {
+    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);
@@ -160,9 +179,39 @@ var asQueryBoolean = (schema) => {
     return value;
   }, schema);
 };
+
+// src/zod-jwt/zod-jwt.schemas.ts
+import { sign as signJWT, verify as verifyJWT } from "hono/jwt";
+var ZodJWTService = class {
+  payloadSchema;
+  algorithm;
+  defaultExpirationSeconds;
+  constructor(payloadSchema, options) {
+    this.payloadSchema = payloadSchema;
+    this.algorithm = options?.algorithm ?? "HS256";
+    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 });`
+   */
+  async sign(payload, secret, options) {
+    const exp = Math.floor(Date.now() / 1e3) + (options?.expiresInSeconds ?? this.defaultExpirationSeconds);
+    return signJWT({ ...payload, exp }, secret, this.algorithm);
+  }
+  /**
+   * 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);
+  }
+};
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
+  ZodJWTService,
   asQueryBoolean,
   asQueryNumber,
   failure,
@@ -178,6 +227,8 @@ export {
   honoLoggingHandler,
   log,
   onHandlerError,
+  requestReaders,
+  requirePayload,
   respond,
   safeExecute,
   success

package/package.json

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