@kalutskii/foundation 0.3.4 → 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'. */
@@ -163,27 +179,37 @@ type JWTSignOptions = {
     /** The number of seconds until the JWT expires. */
     expiresInSeconds?: number;
 };
+/** Utility types for inferring payload types from Zod schemas. */
+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;
 
-declare class ZodJWTService<TSchema extends z$1.ZodObject<z$1.ZodRawShape>> {
-    readonly payloadSchema: TSchema | undefined;
+/**
+ * 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;
     protected readonly defaultExpirationSeconds: number;
-    constructor(payloadSchema?: TSchema, options?: JWTServiceOptions);
+    constructor(payloadSchema?: PayloadSchema<TPayloadOrSchema>, 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>;
+    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<z$1.infer<TSchema> | null>;
+    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<z$1.infer<TSchema>>;
+    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, 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,24 +181,28 @@ 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);
-    if (!this.payloadSchema)
+    if (!this.payloadSchema) {
       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, 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);
-    if (!this.payloadSchema)
+    if (!this.payloadSchema) {
       return payload;
+    }
     return this.payloadSchema.parseAsync(payload);
   }
 };

package/package.json

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