@knsdev330/node-utils 1.0.1

package/dist/HMACUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HMAC utilities for use across projects.
+ * Import via: @sajjat/utils/HMACUtils
+ */
+declare class hMACUtils {
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     */
+    readonly hash: (secret: string, token: string) => {
+        data: string;
+        error: null;
+    } | {
+        data: null;
+        error: Error;
+    };
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     *
+     * @throws {Error} If the hashing fails.
+     */
+    readonly hashOrThrow: (secret: string, token: string) => string;
+    /**
+     * Timing-safe comparison of two strings or buffers.
+     * Prevents timing attacks by comparing the full length of the values.
+     * @param a - First value.
+     * @param b - Second value.
+     * @returns True if values match, false otherwise.
+     */
+    readonly compare: (a: string | Buffer, b: string | Buffer) => boolean;
+}
+export declare const HMACUtils: hMACUtils;
+export {};
+//# sourceMappingURL=HMACUtils.d.ts.map

package/dist/HMACUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HMACUtils.d.ts","sourceRoot":"","sources":["../src/HMACUtils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,cAAM,SAAS;IAEd;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAa5G;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,MAAM,CAE7D;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,GAAI,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,MAAM,KAAG,OAAO,CAcnE;CACD;AAED,eAAO,MAAM,SAAS,WAAkB,CAAC"}

package/dist/HMACUtils.js

@@ -0,0 +1,61 @@
+import { createHmac, timingSafeEqual } from "crypto";
+/**
+ * HMAC utilities for use across projects.
+ * Import via: @sajjat/utils/HMACUtils
+ */
+class hMACUtils {
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     */
+    hash = (secret, token) => {
+        try {
+            return {
+                data: this.hashOrThrow(secret, token),
+                error: null
+            };
+        }
+        catch (error) {
+            return {
+                data: null,
+                error: error
+            };
+        }
+    };
+    /**
+     * Hash a token using a secret key.
+     * @param secret - The secret key to use for hashing.
+     * @param token - The token to hash.
+     * @returns The hashed token.
+     *
+     * @throws {Error} If the hashing fails.
+     */
+    hashOrThrow = (secret, token) => {
+        return createHmac("sha256", secret).update(token, "utf8").digest("hex");
+    };
+    /**
+     * Timing-safe comparison of two strings or buffers.
+     * Prevents timing attacks by comparing the full length of the values.
+     * @param a - First value.
+     * @param b - Second value.
+     * @returns True if values match, false otherwise.
+     */
+    compare = (a, b) => {
+        try {
+            const aBuf = Buffer.isBuffer(a) ? a : Buffer.from(a, 'utf8');
+            const bBuf = Buffer.isBuffer(b) ? b : Buffer.from(b, 'utf8');
+            // timingSafeEqual throws if lengths do not match
+            if (aBuf.length !== bBuf.length) {
+                return false;
+            }
+            return timingSafeEqual(aBuf, bBuf);
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export const HMACUtils = new hMACUtils();
+//# sourceMappingURL=HMACUtils.js.map

package/dist/HMACUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HMACUtils.js","sourceRoot":"","sources":["../src/HMACUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAGrD;;;GAGG;AACH,MAAM,SAAS;IAEd;;;;;OAKG;IACM,IAAI,GAAG,CAAC,MAAc,EAAE,KAAa,EAAgE,EAAE;QAC/G,IAAI,CAAC;YACJ,OAAO;gBACN,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC;gBACrC,KAAK,EAAE,IAAI;aACX,CAAC;QACH,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACd,OAAO;gBACN,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,KAAc;aACrB,CAAC;QACH,CAAC;IACF,CAAC,CAAA;IAED;;;;;;;OAOG;IACM,WAAW,GAAG,CAAC,MAAc,EAAE,KAAa,EAAU,EAAE;QAChE,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzE,CAAC,CAAA;IAED;;;;;;OAMG;IACM,OAAO,GAAG,CAAC,CAAkB,EAAE,CAAkB,EAAW,EAAE;QACtE,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC7D,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAE7D,iDAAiD;YACjD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjC,OAAO,KAAK,CAAC;YACd,CAAC;YAED,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC,CAAA;CACD;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC"}

package/dist/HttpCodes.d.ts

@@ -0,0 +1,26 @@
+export declare const HttpCodes: {
+    readonly UNKNOWN_ERROR: 0;
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly BAD_GATEWAY: 502;
+    readonly TIMEOUT: 504;
+    readonly ACCEPTED: 202;
+    readonly PARTIAL_CONTENT: 206;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly SEE_OTHER: 303;
+    readonly NOT_MODIFIED: 304;
+    readonly USE_PROXY: 305;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly TOO_MANY_REQUESTS: 429;
+};
+export type THttpCodes = typeof HttpCodes;
+//# sourceMappingURL=HttpCodes.d.ts.map

package/dist/HttpCodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpCodes.d.ts","sourceRoot":"","sources":["../src/HttpCodes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;CAuBZ,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,SAAS,CAAC"}

package/dist/HttpCodes.js

@@ -0,0 +1,25 @@
+export const HttpCodes = {
+    UNKNOWN_ERROR: 0,
+    OK: 200,
+    CREATED: 201,
+    NO_CONTENT: 204,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    INTERNAL_SERVER_ERROR: 500,
+    SERVICE_UNAVAILABLE: 503,
+    BAD_GATEWAY: 502,
+    TIMEOUT: 504,
+    ACCEPTED: 202,
+    PARTIAL_CONTENT: 206,
+    MOVED_PERMANENTLY: 301,
+    FOUND: 302,
+    SEE_OTHER: 303,
+    NOT_MODIFIED: 304,
+    USE_PROXY: 305,
+    TEMPORARY_REDIRECT: 307,
+    PERMANENT_REDIRECT: 308,
+    TOO_MANY_REQUESTS: 429,
+};
+//# sourceMappingURL=HttpCodes.js.map

package/dist/HttpCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpCodes.js","sourceRoot":"","sources":["../src/HttpCodes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;IACxB,aAAa,EAAE,CAAC;IAChB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,GAAG;IAChB,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,qBAAqB,EAAE,GAAG;IAC1B,mBAAmB,EAAE,GAAG;IACxB,WAAW,EAAE,GAAG;IAChB,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,eAAe,EAAE,GAAG;IACpB,iBAAiB,EAAE,GAAG;IACtB,KAAK,EAAE,GAAG;IACV,SAAS,EAAE,GAAG;IACd,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,kBAAkB,EAAE,GAAG;IACvB,kBAAkB,EAAE,GAAG;IACvB,iBAAiB,EAAE,GAAG;CACb,CAAC"}

package/dist/IDUtils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Utilities for generating and validating IDs.
+ */
+declare class idUtils {
+    /**
+     * Generates a crypto-random RFC4122 v4 UUID.
+     * @returns A UUID string (e.g. `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`).
+     */
+    readonly gen: () => string;
+    /**
+     * Validates a UUID.
+     * @param id - The UUID to validate.
+     * @returns True if the UUID is valid, false otherwise.
+     */
+    readonly validateOrThrow: (id: unknown) => id is string;
+    /**
+     * Validates that the provided value is a UUID string.
+     * @param id - Value to validate.
+     * @returns `true` when `id` is a valid UUID string.
+     */
+    readonly validate: (id: unknown) => id is string;
+}
+/**
+ * Singleton instance of ID utilities.
+ */
+export declare const IDUtils: idUtils;
+export {};
+//# sourceMappingURL=IDUtils.d.ts.map

package/dist/IDUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IDUtils.d.ts","sourceRoot":"","sources":["../src/IDUtils.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,cAAM,OAAO;IAEZ;;;OAGG;IACH,SAAgB,GAAG,eAElB;IAED;;;;OAIG;IACH,SAAgB,eAAe,GAAI,IAAI,OAAO,KAAG,EAAE,IAAI,MAAM,CAO5D;IAED;;;;OAIG;IACH,SAAgB,QAAQ,GAAI,IAAI,OAAO,KAAG,EAAE,IAAI,MAAM,CAUrD;CACD;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,SAAgB,CAAC"}

package/dist/IDUtils.js

@@ -0,0 +1,47 @@
+import { BadRequest } from "./ErrorClasses.js";
+import { randUuid } from "./Rand.js";
+import { validateUUID } from "./validators.js";
+/**
+ * Utilities for generating and validating IDs.
+ */
+class idUtils {
+    /**
+     * Generates a crypto-random RFC4122 v4 UUID.
+     * @returns A UUID string (e.g. `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`).
+     */
+    gen = () => {
+        return randUuid();
+    };
+    /**
+     * Validates a UUID.
+     * @param id - The UUID to validate.
+     * @returns True if the UUID is valid, false otherwise.
+     */
+    validateOrThrow = (id) => {
+        if (this.validate(id)) {
+            return true;
+        }
+        else {
+            throw new BadRequest('ID__INVALID');
+        }
+    };
+    /**
+     * Validates that the provided value is a UUID string.
+     * @param id - Value to validate.
+     * @returns `true` when `id` is a valid UUID string.
+     */
+    validate = (id) => {
+        if (typeof id === 'string' &&
+            validateUUID(id)) {
+            return true;
+        }
+        else {
+            return false;
+        }
+    };
+}
+/**
+ * Singleton instance of ID utilities.
+ */
+export const IDUtils = new idUtils();
+//# sourceMappingURL=IDUtils.js.map

package/dist/IDUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IDUtils.js","sourceRoot":"","sources":["../src/IDUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;GAEG;AACH,MAAM,OAAO;IAEZ;;;OAGG;IACa,GAAG,GAAG,GAAG,EAAE;QAC1B,OAAO,QAAQ,EAAE,CAAC;IACnB,CAAC,CAAA;IAED;;;;OAIG;IACa,eAAe,GAAG,CAAC,EAAW,EAAgB,EAAE;QAC/D,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;aACI,CAAC;YACL,MAAM,IAAI,UAAU,CAAC,aAAa,CAAC,CAAC;QACrC,CAAC;IACF,CAAC,CAAA;IAED;;;;OAIG;IACa,QAAQ,GAAG,CAAC,EAAW,EAAgB,EAAE;QACxD,IACC,OAAO,EAAE,KAAK,QAAQ;YACtB,YAAY,CAAC,EAAE,CAAC,EACf,CAAC;YACF,OAAO,IAAI,CAAC;QACb,CAAC;aACI,CAAC;YACL,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC,CAAA;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC"}

package/dist/JwtUtils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * JWT utilities for use across projects.
+ * Import via: @sajjat/utils/JwtUtils
+ */
+declare class jwtUtils {
+    /**
+     * Signs a JWT (HS256) and returns the compact token.
+     * @template PayloadType - The type of the payload to sign.
+     * @param secret - Symmetric signing secret.
+     * @param data - Payload (object, string, or Buffer).
+     * @param expiresMs - Milliseconds until expiry (ignored if payload already sets `exp`).
+     * @returns Compact JWT string.
+     * @throws {InternalServerError} If signing fails.
+     */
+    readonly signOrThrow: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, data: NoInfer<PayloadType>, expiresMs: number) => string;
+    /**
+     * @deprecated Use `signOrThrow` — this is JWT signing, not encryption.
+     */
+    readonly encryptOrThrow: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, data: NoInfer<PayloadType>, expiresMs: number) => string;
+    /**
+     * Signs a JWT (HS256); returns result or error object.
+     * @template PayloadType - The type of the payload to sign.
+     */
+    readonly sign: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, data: NoInfer<PayloadType>, expiresMs: number) => {
+        data: PayloadType;
+        error: null;
+    } | {
+        data: null;
+        error: Error;
+    };
+    /**
+     * @deprecated Use `sign`.
+     */
+    readonly encrypt: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, data: NoInfer<PayloadType>, expiresMs: number) => {
+        data: PayloadType;
+        error: null;
+    } | {
+        data: null;
+        error: Error;
+    };
+    /**
+     * Verifies a JWT (HS256) and returns the payload.
+     * @template PayloadType - Expected payload shape after verification.
+     * @param secret - Symmetric signing secret.
+     * @param token - Compact JWT string.
+     * @returns Decoded payload.
+     * @throws {BadRequest} If `token` is not a string.
+     * @throws {Unauthorized} If the token is invalid or expired.
+     */
+    readonly verifyOrThrow: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, token: unknown) => PayloadType;
+    /**
+     * @deprecated Use `verifyOrThrow` — this is JWT verification, not decryption.
+     */
+    readonly decryptOrThrow: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, token: unknown) => PayloadType;
+    /**
+     * Verifies a JWT (HS256); returns payload or error object.
+     * @template PayloadType - Expected payload shape after verification.
+     */
+    readonly verify: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, token: unknown) => {
+        data: PayloadType;
+        error: null;
+    } | {
+        data: null;
+        error: Error;
+    };
+    /**
+     * @deprecated Use `verify`.
+     */
+    readonly decrypt: <PayloadType extends object | string | Buffer = "Error: a type template is required">(secret: string, token: unknown) => {
+        data: PayloadType;
+        error: null;
+    } | {
+        data: null;
+        error: Error;
+    };
+}
+export declare const JwtUtils: jwtUtils;
+export {};
+//# sourceMappingURL=JwtUtils.d.ts.map

package/dist/JwtUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtUtils.d.ts","sourceRoot":"","sources":["../src/JwtUtils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,cAAM,QAAQ;IAEb;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EAC1G,QAAQ,MAAM,EACd,MAAM,OAAO,CAAC,WAAW,CAAC,EAC1B,WAAW,MAAM,KACf,MAAM,CAaR;IAED;;OAEG;IACH,QAAQ,CAAC,cAAc,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EAC7G,QAAQ,MAAM,EACd,MAAM,OAAO,CAAC,WAAW,CAAC,EAC1B,WAAW,MAAM,KACf,MAAM,CAA2D;IAEpE;;;OAGG;IACH,QAAQ,CAAC,IAAI,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EACnG,QAAQ,MAAM,EACd,MAAM,OAAO,CAAC,WAAW,CAAC,EAC1B,WAAW,MAAM,KACf;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAOnE;IAED;;OAEG;IACH,QAAQ,CAAC,OAAO,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EACtG,QAAQ,MAAM,EACd,MAAM,OAAO,CAAC,WAAW,CAAC,EAC1B,WAAW,MAAM,KACf;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAChC;IAEpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EAAE,QAAQ,MAAM,EAAE,OAAO,OAAO,KAC1I,WAAW,CAWb;IAED;;OAEG;IACH,QAAQ,CAAC,cAAc,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EAAE,QAAQ,MAAM,EAAE,OAAO,OAAO,KAC3I,WAAW,CAAmD;IAEjE;;;OAGG;IACH,QAAQ,CAAC,MAAM,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EAAE,QAAQ,MAAM,EAAE,OAAO,OAAO,KACnI;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAOnE;IAED;;OAEG;IACH,QAAQ,CAAC,OAAO,GAAI,WAAW,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,oCAAoC,EAAE,QAAQ,MAAM,EAAE,OAAO,OAAO,KACpI;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAC3B;CACzC;AAED,eAAO,MAAM,QAAQ,UAAiB,CAAC"}

package/dist/JwtUtils.js

@@ -0,0 +1,94 @@
+import { BadRequest, InternalServerError, Unauthorized } from "./ErrorClasses.js";
+import JWT from "jsonwebtoken";
+/**
+ * JWT utilities for use across projects.
+ * Import via: @sajjat/utils/JwtUtils
+ */
+class jwtUtils {
+    /**
+     * Signs a JWT (HS256) and returns the compact token.
+     * @template PayloadType - The type of the payload to sign.
+     * @param secret - Symmetric signing secret.
+     * @param data - Payload (object, string, or Buffer).
+     * @param expiresMs - Milliseconds until expiry (ignored if payload already sets `exp`).
+     * @returns Compact JWT string.
+     * @throws {InternalServerError} If signing fails.
+     */
+    signOrThrow = (secret, data, expiresMs) => {
+        try {
+            const payload = data;
+            const options = { algorithm: 'HS256' };
+            // Do not pass expiresIn when payload already has exp (jsonwebtoken v9 throws otherwise)
+            if (payload.exp === undefined) {
+                options.expiresIn = `${expiresMs}ms`;
+            }
+            return JWT.sign(data, secret, options);
+        }
+        catch {
+            throw new InternalServerError('JWT__ENCRYPTION_FAILED');
+        }
+    };
+    /**
+     * @deprecated Use `signOrThrow` — this is JWT signing, not encryption.
+     */
+    encryptOrThrow = (secret, data, expiresMs) => this.signOrThrow(secret, data, expiresMs);
+    /**
+     * Signs a JWT (HS256); returns result or error object.
+     * @template PayloadType - The type of the payload to sign.
+     */
+    sign = (secret, data, expiresMs) => {
+        try {
+            return { data: this.signOrThrow(secret, data, expiresMs), error: null };
+        }
+        catch (error) {
+            return { data: null, error: error };
+        }
+    };
+    /**
+     * @deprecated Use `sign`.
+     */
+    encrypt = (secret, data, expiresMs) => this.sign(secret, data, expiresMs);
+    /**
+     * Verifies a JWT (HS256) and returns the payload.
+     * @template PayloadType - Expected payload shape after verification.
+     * @param secret - Symmetric signing secret.
+     * @param token - Compact JWT string.
+     * @returns Decoded payload.
+     * @throws {BadRequest} If `token` is not a string.
+     * @throws {Unauthorized} If the token is invalid or expired.
+     */
+    verifyOrThrow = (secret, token) => {
+        if (typeof token !== 'string')
+            throw new BadRequest('JWT__INVALID_OR_EXPIRED');
+        try {
+            return JWT.verify(token, secret, {
+                algorithms: ['HS256'],
+            });
+        }
+        catch {
+            throw new Unauthorized('JWT__INVALID_OR_EXPIRED');
+        }
+    };
+    /**
+     * @deprecated Use `verifyOrThrow` — this is JWT verification, not decryption.
+     */
+    decryptOrThrow = (secret, token) => this.verifyOrThrow(secret, token);
+    /**
+     * Verifies a JWT (HS256); returns payload or error object.
+     * @template PayloadType - Expected payload shape after verification.
+     */
+    verify = (secret, token) => {
+        try {
+            return { data: this.verifyOrThrow(secret, token), error: null };
+        }
+        catch (error) {
+            return { data: null, error: error };
+        }
+    };
+    /**
+     * @deprecated Use `verify`.
+     */
+    decrypt = (secret, token) => this.verify(secret, token);
+}
+export const JwtUtils = new jwtUtils();
+//# sourceMappingURL=JwtUtils.js.map

package/dist/JwtUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtUtils.js","sourceRoot":"","sources":["../src/JwtUtils.ts"],"names":[],"mappings":"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"}

package/dist/Nums.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Clamp a number to an inclusive range.
+ * @param value - Input number.
+ * @param min - Inclusive lower bound.
+ * @param max - Inclusive upper bound.
+ * @returns `value` constrained to `[min, max]`.
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Check whether a number falls within an inclusive range.
+ * @param value - Number to test.
+ * @param min - Inclusive lower bound.
+ * @param max - Inclusive upper bound.
+ * @returns `true` when `min <= value <= max`; otherwise `false`.
+ */
+export declare const isBetween: (value: number, min: number, max: number) => boolean;
+/**
+ * Round a number to a fixed number of decimal places.
+ * @param value - Number to round.
+ * @param decimals - Decimal places to keep.
+ * @returns Rounded number.
+ */
+export declare const roundTo: (value: number, decimals: number) => number;
+/**
+ * Round a number down to a fixed number of decimal places.
+ * @param value - Number to floor.
+ * @param decimals - Decimal places to keep.
+ * @returns Floored number.
+ */
+export declare const floorTo: (value: number, decimals: number) => number;
+/**
+ * Round a number up to a fixed number of decimal places.
+ * @param value - Number to ceil.
+ * @param decimals - Decimal places to keep.
+ * @returns Ceiled number.
+ */
+export declare const ceilTo: (value: number, decimals: number) => number;
+/**
+ * Parse a value into an integer safely.
+ * @param value - Value to parse.
+ * @param radix - Numeric base for parsing string inputs.
+ * @returns Parsed integer, or `null` for `null`/`undefined`/`NaN`.
+ */
+export declare const parseIntSafe: (value: string | number | null | undefined, radix?: number) => number | null;
+/**
+ * Parse a value into a floating-point number safely.
+ * @param value - Value to parse.
+ * @returns Parsed number, or `null` for `null`/`undefined`/`NaN`.
+ */
+export declare const parseFloatSafe: (value: string | number | null | undefined) => number | null;
+/**
+ * Type guard for finite numbers.
+ * @param value - Unknown input.
+ * @returns `true` when `value` is a finite `number`.
+ */
+export declare const isFiniteNumber: (value: unknown) => value is number;
+/**
+ * Type guard for integer numbers.
+ * @param value - Unknown input.
+ * @returns `true` when `value` is an integer `number`.
+ */
+export declare const isInteger: (value: unknown) => value is number;
+/**
+ * Format a number using `Intl.NumberFormat`.
+ * @param value - Number to format.
+ * @param locale - BCP47 locale string.
+ * @param options - Number format options.
+ * @returns Formatted number string.
+ */
+export declare const formatNumber: (value: number, locale?: string, options?: Intl.NumberFormatOptions) => string;
+/**
+ * Format a number with group separators.
+ * @param value - Number to format.
+ * @param locale - BCP47 locale string. (default: 'en')
+ * @param decimals - Optional fixed fraction digits.
+ * @returns Formatted string with commas/grouping.
+ */
+export declare const formatWithCommas: (value: number, locale?: string, decimals?: number) => string;
+/**
+ * Calculate percentage of `part` out of `total`.
+ * @param part - Numerator.
+ * @param total - Denominator.
+ * @param decimals - Decimal places in the result.
+ * @returns Percentage value. Returns `0` if `total` is `0`.
+ */
+export declare const percentage: (part: number, total: number, decimals?: number) => number;
+/**
+ * Convert unknown input to a finite number with fallback.
+ * @param value - Value to convert.
+ * @param fallback - Value used when conversion is not finite.
+ * @returns Finite number from input, or `fallback`.
+ */
+export declare const toNumber: (value: unknown, fallback: number) => number;
+/**
+ * Convert unknown input to an integer with fallback.
+ * @param value - Value to convert.
+ * @param fallback - Value used when conversion is not an integer.
+ * @returns Integer from input, or `fallback`.
+ */
+export declare const toInt: (value: unknown, fallback: number) => number;
+//# sourceMappingURL=Nums.d.ts.map

package/dist/Nums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Nums.d.ts","sourceRoot":"","sources":["../src/Nums.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,MAC5B,CAAC;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,OACvC,CAAC;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,MAGzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,MAGzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,MAGxD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACxB,OAAO,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,cAAU,KACR,MAAM,GAAG,IAIX,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IAInF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACL,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACC,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GACxB,OAAO,MAAM,EACb,eAAa,EACb,UAAU,IAAI,CAAC,mBAAmB,KAChC,MAKc,CAAC;AAElB;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,EAAE,eAAa,EAAE,WAAW,MAAM,KAAG,MAOlF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,iBAAY,KAAG,MAGtE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAG3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAGxD,CAAC"}