@kalutskii/foundation 0.3.5 → 0.3.6

package/dist/index.d.ts

@@ -151,6 +151,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 +184,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 +199,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, log, onHandlerError, respond, safeExecute, success };

package/dist/index.js

@@ -181,8 +181,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 +195,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);

package/package.json

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