@kalutskii/foundation 0.3.5 → 0.4.0

package/dist/index.d.ts

@@ -45,6 +45,8 @@ declare function failure({ status, error }: {
 declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>>>;
 /** Resolves an APIContractResult fetcher, throwing an error if the result is an APIError. */
 declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
+/** Pure type guard for APIError responses, used to narrow the type of a response object. */
+declare function isErrorResponse<TResponse>(response: TResponse): response is TResponse & APIError;
 
 /**
  * Global error handler for Hono framework. Catches all exceptions thrown in route handlers and middlewares.
@@ -151,6 +153,22 @@ declare const log: {
     error: (message: string, service?: string, stack?: string) => void;
 };
 
+/**
+ * A utility type that represents a value that can be of type T or null.
+ * Commonly used for optional fields in data models or function return types.
+ *
+ * ```
+ * export type ObjectSelect = XOR<
+ *   Pick<Object, 'id'>,
+ *   Pick<Object, 'anotherUniqueField'>
+ * >;
+ */
+type XOR<T, U> = (T & {
+    [K in keyof U]?: never;
+}) | (U & {
+    [K in keyof T]?: never;
+});
+
 /** Options for configuring the JWT service. */
 type JWTServiceOptions = {
     /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
@@ -168,6 +186,10 @@ type Payload<T> = T extends z$1.ZodType ? z$1.infer<T> : T;
 /** Utility type to extract the payload schema type from a Zod schema. */
 type PayloadSchema<T> = T extends z$1.ZodType ? T : never;
 
+/**
+ * A service class for handling JWT operations with optional Zod schema validation for the payload.
+ * The class is generic, allowing you to specify the type of the payload or a schema for validation.
+ */
 declare class ZodJWTService<TPayloadOrSchema> {
     readonly payloadSchema: PayloadSchema<TPayloadOrSchema> | undefined;
     protected readonly algorithm: SymmetricAlgorithm;
@@ -179,15 +201,17 @@ declare class ZodJWTService<TPayloadOrSchema> {
      */
     sign(payload: Payload<TPayloadOrSchema>, 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.
+     * 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.
+     * Example usage: `const payload = await JWTServiceInstance.decode(token);`
      */
     decode(token: string): Promise<Payload<TPayloadOrSchema> | 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.
+     * then validates the payload against the Zod schema if one is provided. Throws an error if verification fails or if the payload is invalid.
+     * Example usage: `const payload = await JWTServiceInstance.verifyOrThrow(token, 'my-secret');`
      */
     verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
 }
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type Payload, type PayloadSchema, 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 };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, type XOR, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isErrorResponse, log, onHandlerError, respond, safeExecute, success };

package/dist/index.js

@@ -23,6 +23,14 @@ async function fetchAndThrow(fetcher) {
     throw new Error(response.error);
   return response.data;
 }
+function isErrorResponse(response) {
+  if (typeof response !== "object" || response === null)
+    return false;
+  if (!("kind" in response) || !("status" in response))
+    return false;
+  const { kind, status } = response;
+  return kind === "error" && (typeof status === "number" || typeof status === "string");
+}
 
 // src/hono/hono.execution.ts
 import { HTTPException } from "hono/http-exception";
@@ -181,8 +189,9 @@ var ZodJWTService = class {
     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.
+   * 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.
+   * Example usage: `const payload = await JWTServiceInstance.decode(token);`
    */
   async decode(token) {
     const { payload } = decodeJWT(token);
@@ -194,7 +203,8 @@ var ZodJWTService = class {
   }
   /**
    * 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.
+   * then validates the payload against the Zod schema if one is provided. Throws an error if verification fails or if the payload is invalid.
+   * Example usage: `const payload = await JWTServiceInstance.verifyOrThrow(token, 'my-secret');`
    */
   async verifyOrThrow(token, secret) {
     const payload = await verifyJWT(token, secret, this.algorithm);
@@ -221,6 +231,7 @@ export {
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
+  isErrorResponse,
   log,
   onHandlerError,
   respond,

package/package.json

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