nhb-toolbox 4.28.0 → 4.28.4

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.28.4] - 2025-12-02
+
+- **Updated** *implementation* and *tsdoc* for:
+  - `cloneObject`: used `structuredClone` and `stableStringify` (optionally force to use *deterministic serialization*) internally and falls back to *shallow cloning* if serialization fails.
+  - `stableStringify`: stringified value of *Date-like objects* (`Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, `Temporal`) is converted to string representation (in the same way that `JSON.stringify` would serialize them).
+- **Updated** `convertObjectValues` behaviour: *fields* configured for *number conversion* now return `NaN` when *parsing fails*.
+- **Updated** *reference links* in *tsdoc* of some *hash* utilities.
+
+## [4.28.1] - 2025-12-02
+
+- **Updated** *type* names `TokenHeader` to `SignetHeader` and `TokenPayload` to `SignetPayload` and both are available to import.
+
 ## [4.28.0] - 2025-12-01
 
 - **Added** *new* class `Cipher` to *encrypt/decrypt* string with *secret key*.

package/dist/cjs/array/basics.js

@@ -34,7 +34,7 @@ exports.isInvalidOrEmptyArray = isInvalidOrEmptyArray;
 const shuffleArray = (array) => {
     if ((0, exports.isInvalidOrEmptyArray)(array))
         return array;
-    const shuffled = structuredClone(array);
+    const shuffled = [...array];
     for (let i = shuffled?.length - 1; i > 0; i--) {
         const j = Math.floor(Math.random() * (i + 1));
         [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];

package/dist/cjs/hash/core.js

@@ -15,9 +15,9 @@ function md5(str) {
     const $str = str.substring(i - 64);
     const tail = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
     for (i = 0; i < $str.length; i++) {
-        tail[i >> 2] |= $str.charCodeAt(i) << (i % 4 << 3);
+        tail[i >> 2] |= $str.charCodeAt(i) << ((i % 4) << 3);
     }
-    tail[i >> 2] |= 0x80 << (i % 4 << 3);
+    tail[i >> 2] |= 0x80 << ((i % 4) << 3);
     if (i > 55) {
         (0, helpers_1._md5cycle)(state, tail);
         for (let j = 0; j < 16; j++) {

package/dist/cjs/object/basics.js

@@ -1,19 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.countObjectFields = exports.cloneObject = void 0;
+exports.cloneObject = cloneObject;
+exports.countObjectFields = countObjectFields;
 exports.extractObjectKeys = extractObjectKeys;
 exports.extractObjectKeysDeep = extractObjectKeysDeep;
 const non_primitives_1 = require("../guards/non-primitives");
-const cloneObject = (obj) => {
-    return JSON.parse(JSON.stringify(obj));
-};
-exports.cloneObject = cloneObject;
-const countObjectFields = (obj) => {
+const index_1 = require("../utils/index");
+function cloneObject(obj, serialize = false) {
+    try {
+        if (!serialize && typeof structuredClone === 'function') {
+            return structuredClone(obj);
+        }
+        return JSON.parse((0, index_1.stableStringify)(obj));
+    }
+    catch {
+        return { ...obj };
+    }
+}
+function countObjectFields(obj) {
     if (obj != null)
         return Object.keys(obj)?.length;
     return 0;
-};
-exports.countObjectFields = countObjectFields;
+}
 function extractObjectKeys(obj, tuple) {
     const keys = (0, non_primitives_1.isNotEmptyObject)(obj) ? Object.keys(obj) : [];
     return tuple ? keys : keys;

package/dist/cjs/object/convert.js

@@ -5,29 +5,25 @@ exports.pickFields = pickFields;
 exports.deleteFields = deleteFields;
 exports.pickObjectFieldsByCondition = pickObjectFieldsByCondition;
 exports.remapFields = remapFields;
+const non_primitives_1 = require("../guards/non-primitives");
+const primitives_1 = require("../guards/primitives");
 function convertObjectValues(data, options) {
-    const { keys, convertTo } = options;
-    const _shouldPreserveValue = (value) => convertTo === 'number' && (typeof value !== 'string' || isNaN(Number(value)));
+    const { keys, convertTo } = options || {};
     const _setValueAtPath = (obj, path, convertTo) => {
         const segments = path.split('.');
         let current = obj;
         segments?.forEach((key, index) => {
             if (index === segments?.length - 1) {
                 const value = current?.[key];
-                if (_shouldPreserveValue(value)) {
-                    return;
-                }
-                if (convertTo === 'string' && typeof value !== 'string') {
+                if (convertTo === 'string' && !(0, primitives_1.isString)(value)) {
                     current[key] = String(value);
                 }
-                else if (convertTo === 'number' &&
-                    typeof value !== 'number' &&
-                    !isNaN(Number(value))) {
+                else if (convertTo === 'number' && !(0, primitives_1.isNumber)(value)) {
                     current[key] = Number(value);
                 }
             }
             else {
-                if (typeof current?.[key] === 'object' && current?.[key] !== null) {
+                if ((0, non_primitives_1.isObject)(current?.[key])) {
                     current = current?.[key];
                 }
                 else {
@@ -39,7 +35,7 @@ function convertObjectValues(data, options) {
         return obj;
     };
     const _convertValue = (obj) => {
-        let newObj = structuredClone(obj);
+        let newObj = { ...obj };
         keys?.forEach((key) => {
             newObj = _setValueAtPath(newObj, key, convertTo);
         });

package/dist/cjs/utils/index.js

@@ -17,6 +17,7 @@ exports.deepParsePrimitives = deepParsePrimitives;
 exports.definePrototypeMethod = definePrototypeMethod;
 const helpers_1 = require("../array/helpers");
 const sort_1 = require("../array/sort");
+const guards_1 = require("../date/guards");
 const non_primitives_1 = require("../guards/non-primitives");
 const primitives_1 = require("../guards/primitives");
 const specials_1 = require("../guards/specials");
@@ -137,7 +138,9 @@ function stableStringify(obj) {
         const keys = Object.keys(obj).sort();
         return ('{' +
             keys
-                .map((k) => JSON.stringify(k, _replacer) + ':' + stableStringify(obj[k]))
+                .map((k) => JSON.stringify(k, _replacer) +
+                ':' +
+                ((0, guards_1.isDateLike)(obj[k]) ? JSON.stringify(obj[k]) : stableStringify(obj[k])))
                 .join(',') +
             '}');
     }

package/dist/dts/hash/Signet.d.ts

@@ -1,5 +1,5 @@
 import type { GenericObject } from '../object/types';
-import type { DecodedToken, SignOptions, TokenPayload, TokenString, VerifiedToken, VerifyOptions } from './types';
+import type { DecodedToken, SignetPayload, SignOptions, TokenString, VerifiedToken, VerifyOptions } from './types';
 /**
  * * A lightweight, secure implementation of JWT-like tokens using `HMAC-SHA256` signatures.
  *   - This class provides methods to create, verify, and decode tokens with a simple API similar to JSON Web Tokens (`JWT`) but with a smaller footprint and zero dependencies.
@@ -166,7 +166,7 @@ export declare class Signet {
      *
      * @remarks
      * - Tokens without `exp` claim are considered non-expiring (returns `false`)
-     * - Uses current system time for comparison
+     * - Uses current system time for comparison ({@link Date.now()})
      * - Does not verify the signature (use only with trusted tokens or after verification)
      *
      * @example
@@ -192,7 +192,10 @@ export declare class Signet {
      *
      * @throws If the token is malformed or cannot be decoded.
      *
-     * @remarks Useful for implementing time-based access control, like activation links that shouldn't be used until a certain time.
+     * @remarks
+     * - Useful for implementing time-based access control, like activation links that shouldn't be used until a certain time.
+     * - Uses current system time for comparison ({@link Date.now()})
+     * - Does not verify the signature (use only with trusted tokens or after verification)
      *
      * @example
      * ```typescript
@@ -310,7 +313,7 @@ export declare class Signet {
      * @param options - Optional validation criteria for token claims.
      *
      * @returns A {@link VerifiedToken} object indicating success or failure.
-     *          - If valid: `{ isValid: true, payload: TokenPayload<T> }`
+     *          - If valid: `{ isValid: true, payload: SignetPayload<T> }`
      *          - If invalid: `{ isValid: false, error: string }`
      *
      * @remarks
@@ -440,5 +443,5 @@ export declare class Signet {
      * const canDelete = payload.permissions.includes('delete');
      * ```
      */
-    decodePayload<T extends GenericObject = GenericObject>(token: string): TokenPayload<T>;
+    decodePayload<T extends GenericObject = GenericObject>(token: string): SignetPayload<T>;
 }

package/dist/dts/hash/core.d.ts

@@ -59,8 +59,8 @@ export declare function sha1(msg: string): string;
  * // Returns: '7037e204b825b83553ba336a6ec35b796d505599286ae864729ed6cb33ae9fe1'
  * ```
  *
- * @see {@link sha256Bytes} for hashing raw bytes
- * @see {@link utf8ToBytes} for converting string to `UTF-8` bytes
- * @see {@link bytesToHex} for converting bytes to a hexadecimal string
+ * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/sha256Bytes sha256Bytes} for hashing raw bytes
+ * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/encoding#utf8tobytes utf8ToBytes} for converting string to bytes
+ * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/encoding#bytestotex bytesToHex} for converting bytes to a hexadecimal string
  */
 export declare function sha256(msg: string): string;

package/dist/dts/hash/types.d.ts

@@ -45,7 +45,7 @@ export interface DecodedUUID {
     node?: string;
 }
 /** Header for `Signet` */
-export type TokenHeader = {
+export type SignetHeader = {
     /** Algorithm used. Currently supports `'HS256'` only */
     alg: 'HS256';
     /** Type of token. Fixed `'SIGNET+JWT'` */
@@ -79,14 +79,14 @@ export interface SignOptions extends VerifyOptions {
      */
     notBefore?: TimeWithUnit | Numeric;
 }
-/** Pattern of a valid 3-parts token */
+/** 3-parts dot separated token string */
 export type TokenString = `${string}.${string}.${string}`;
 /** Interface of token verification result if token is valid */
 export type $ValidToken<T extends GenericObject = GenericObject> = {
     /** Whether the token is valid */
     isValid: true;
-    /** Decoded payload after successful verification with common {@link TokenPayload} properties */
-    payload: TokenPayload<T>;
+    /** Decoded payload after successful verification with common {@link SignetPayload} properties */
+    payload: SignetPayload<T>;
 };
 /** Interface of token verification result if token is invalid */
 export type $InvalidToken = {
@@ -97,7 +97,7 @@ export type $InvalidToken = {
 };
 /** Result of token verification */
 export type VerifiedToken<T extends GenericObject = GenericObject> = $ValidToken<T> | $InvalidToken;
-export type TokenPayload<T extends GenericObject = GenericObject> = {
+export type SignetPayload<T extends GenericObject = GenericObject> = {
     /** When the token was created (unix timestamp in seconds) */
     iat: number;
     /** When the token was created (as JavaScript {@link Date}) */
@@ -120,9 +120,9 @@ export type TokenPayload<T extends GenericObject = GenericObject> = {
 /** Interface of a decoded token */
 export type DecodedToken<T extends GenericObject = GenericObject> = {
     /** Token header info, algorithm, type etc. */
-    header: TokenHeader;
-    /** Decoded payload after with common {@link TokenPayload} properties */
-    payload: TokenPayload<T>;
+    header: SignetHeader;
+    /** Decoded payload after with common {@link SignetPayload} properties */
+    payload: SignetPayload<T>;
     /**
      * The `Base64`-encoded signature from the token.
      * This is the third part of the token string.
@@ -131,3 +131,4 @@ export type DecodedToken<T extends GenericObject = GenericObject> = {
     /** The header and payload in encrypted `Base64` format.*/
     signingInput: `${string}.${string}`;
 };
+export type { SignetPayload as TokenPayload, SignetHeader as TokenHeader };

package/dist/dts/hash/uuid.d.ts

@@ -43,7 +43,7 @@ import type { DecodedUUID, SupportedVersion, UUID, UUIDOptions } from './types';
  *   - `v7`: Millisecond precision; extremely high throughput may still cause rare collisions.
  *   - `v8`: Uses a simple timestamp + randomness layout; custom layouts are not supported here.
  *
- * - Use {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/generateRandomID generateRandomID} for customized id generation or {@link randomHex} for hex-only string with custom length.
+ * - Use {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/generateRandomID generateRandomID} for customized id generation or {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex randomHex} for hex-only random string with custom length.
  */
 export declare function uuid<V extends SupportedVersion = 'v4'>(options?: UUIDOptions<V>): UUID<V>;
 /**

package/dist/dts/object/basics.d.ts

@@ -1,19 +1,56 @@
 import type { Tuple } from '../utils/types';
 import type { DeepKeys, GenericObject } from './types';
 /**
- * * Deep clone an object.
+ * * Deep clone an object using `structuredClone` or deterministic *JSON serialization*.
  *
  * @param obj Object to clone.
+ * @param serialize Whether to force deterministic JSON serialization instead of using `structuredClone`. Defaults to `false`.
  * @returns Deep cloned object.
+ *
+ * @remarks
+ * **Primary behavior**
+ * - By default (`serialize = false`), the function uses {@link https://developer.mozilla.org/docs/Web/API/Window/structuredClone structuredClone} when available. This supports:
+ *   - Circular references
+ *   - `Date` objects
+ *   - `Map` / `Set`
+ *   - `RegExp`
+ *   - Typed arrays
+ *   - Most built-in JavaScript types
+ *   - Preserves `undefined` values
+ *
+ * - **Note:** `structuredClone` **does not preserve class prototypes**, even though it preserves data types like `Date`, `Map`, and `Set`.
+ *
+ * **Deterministic serialization mode**
+ * - When `serialize = true`, or when `structuredClone` is unavailable, the function falls back to **stable JSON serialization** via `stableStringify`. This guarantees:
+ *   - All object keys are sorted alphabetically.
+ *   - Consistent output across environments (deterministic).
+ *   - All `undefined` values are converted to `null`.
+ *   - Converting date-like objects (`Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, `Temporal`) **in the same way that {@link JSON.stringify} would serialize them**, ensuring predictable and JSON-compliant output.
+ *
+ * - This mode is ideal for:
+ *   - Hashing
+ *   - Signature generation
+ *   - Deep equality checks
+ *   - Anything requiring deterministic, environment-neutral output
+ *
+ * **Deterministic mode limitations**
+ * - JSON serialization will:
+ *   - Drop functions and `Symbol` values.
+ *   - Lose prototype and class instance information.
+ *   - Convert all date-like objects into strings.
+ *   - Fail on circular references.
+ *
+ * **Final safety fallback**
+ * - If JSON serialization fails (e.g., due to circular references), the function returns a **shallow clone** (`{ ...obj }`) to ensure the cloning never throws.
  */
-export declare const cloneObject: <T extends GenericObject>(obj: T) => T;
+export declare function cloneObject<T extends GenericObject>(obj: T, serialize?: boolean): T;
 /**
  * * Count the number of fields in an object.
  *
  * @param obj Object to check.
  * @returns Number of fields in the object.
  */
-export declare const countObjectFields: <T extends GenericObject>(obj: T) => number;
+export declare function countObjectFields<T extends GenericObject>(obj: T): number;
 /**
  * * Extracts all the top-level keys of an object as an array.
  *

package/dist/dts/utils/index.d.ts

@@ -129,14 +129,16 @@ export declare function getClassDetails(cls: Constructor): ClassDetails;
  * - This function guarantees **stable, repeatable output** by:
  * 	 - Sorting all object keys alphabetically.
  * 	 - Recursively stabilizing nested objects and arrays.
- * 	 - Automatically converting all `undefined` values into `null` so the output remains valid JSON.
+ * 	 - Converting all `undefined` values into `null` so the output remains valid JSON.
+ *   - Converting date-like objects (`Date`, `Chronos`, `Moment.js`, `Day.js`, `Luxon`, `JS-Joda`, `Temporal`) **in the same way that {@link JSON.stringify} would serialize them**, ensuring predictable and JSON-compliant output.
  * 	 - Falling back to native JSON serialization for primitives.
- * - Useful for:
+ *
+ * - **Useful for:**
  *   - Hash generation (e.g., signatures, cache keys)
  *   - Deep equality checks
  *   - Producing predictable output across environments
  *
- * @param obj - The value to stringify into a deterministic JSON-like string.
+ * @param obj - The value to stringify into a deterministic JSON string.
  * @returns A stable, deterministic string representation of the input.
  */
 export declare function stableStringify(obj: unknown): string;
@@ -155,12 +157,12 @@ export declare function stripJsonEdgeGarbage(str: string): string;
  * @returns The parsed JSON value typed as `T`, or the original parsed value with optional primitive conversion.
  * - Returns `{}` if parsing fails, such as when the input is malformed or invalid JSON or passing single quoted string.
  *
- * - *Unlike `parseJsonToObject`, which ensures the root value is an object,
+ * - *Unlike {@link https://toolbox.nazmul-nhb.dev/docs/utilities/object/parseJsonToObject parseJsonToObject}, which ensures the root value is an object,
  * this function returns any valid JSON structure such as arrays, strings, numbers, or objects.*
  *
  * This is useful when you're not sure of the root structure of the JSON, or when you expect something other than an object.
  *
- * @see `parseJsonToObject` for strict object-only parsing.
+ * @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/object/parseJsonToObject parseJsonToObject} for strict object-only parsing.
  */
 export declare const parseJSON: <T = unknown>(value: string, parsePrimitives?: boolean) => T;
 /**

package/dist/esm/array/basics.js

@@ -28,7 +28,7 @@ export const isInvalidOrEmptyArray = (value) => {
 export const shuffleArray = (array) => {
     if (isInvalidOrEmptyArray(array))
         return array;
-    const shuffled = structuredClone(array);
+    const shuffled = [...array];
     for (let i = shuffled?.length - 1; i > 0; i--) {
         const j = Math.floor(Math.random() * (i + 1));
         [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];

package/dist/esm/hash/core.js

@@ -10,9 +10,9 @@ export function md5(str) {
     const $str = str.substring(i - 64);
     const tail = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
     for (i = 0; i < $str.length; i++) {
-        tail[i >> 2] |= $str.charCodeAt(i) << (i % 4 << 3);
+        tail[i >> 2] |= $str.charCodeAt(i) << ((i % 4) << 3);
     }
-    tail[i >> 2] |= 0x80 << (i % 4 << 3);
+    tail[i >> 2] |= 0x80 << ((i % 4) << 3);
     if (i > 55) {
         _md5cycle(state, tail);
         for (let j = 0; j < 16; j++) {

package/dist/esm/object/basics.js

@@ -1,12 +1,21 @@
 import { isNotEmptyObject } from '../guards/non-primitives.js';
-export const cloneObject = (obj) => {
-    return JSON.parse(JSON.stringify(obj));
-};
-export const countObjectFields = (obj) => {
+import { stableStringify } from '../utils/index.js';
+export function cloneObject(obj, serialize = false) {
+    try {
+        if (!serialize && typeof structuredClone === 'function') {
+            return structuredClone(obj);
+        }
+        return JSON.parse(stableStringify(obj));
+    }
+    catch {
+        return { ...obj };
+    }
+}
+export function countObjectFields(obj) {
     if (obj != null)
         return Object.keys(obj)?.length;
     return 0;
-};
+}
 export function extractObjectKeys(obj, tuple) {
     const keys = isNotEmptyObject(obj) ? Object.keys(obj) : [];
     return tuple ? keys : keys;

package/dist/esm/object/convert.js

@@ -1,26 +1,22 @@
+import { isObject } from '../guards/non-primitives.js';
+import { isNumber, isString } from '../guards/primitives.js';
 export function convertObjectValues(data, options) {
-    const { keys, convertTo } = options;
-    const _shouldPreserveValue = (value) => convertTo === 'number' && (typeof value !== 'string' || isNaN(Number(value)));
+    const { keys, convertTo } = options || {};
     const _setValueAtPath = (obj, path, convertTo) => {
         const segments = path.split('.');
         let current = obj;
         segments?.forEach((key, index) => {
             if (index === segments?.length - 1) {
                 const value = current?.[key];
-                if (_shouldPreserveValue(value)) {
-                    return;
-                }
-                if (convertTo === 'string' && typeof value !== 'string') {
+                if (convertTo === 'string' && !isString(value)) {
                     current[key] = String(value);
                 }
-                else if (convertTo === 'number' &&
-                    typeof value !== 'number' &&
-                    !isNaN(Number(value))) {
+                else if (convertTo === 'number' && !isNumber(value)) {
                     current[key] = Number(value);
                 }
             }
             else {
-                if (typeof current?.[key] === 'object' && current?.[key] !== null) {
+                if (isObject(current?.[key])) {
                     current = current?.[key];
                 }
                 else {
@@ -32,7 +28,7 @@ export function convertObjectValues(data, options) {
         return obj;
     };
     const _convertValue = (obj) => {
-        let newObj = structuredClone(obj);
+        let newObj = { ...obj };
         keys?.forEach((key) => {
             newObj = _setValueAtPath(newObj, key, convertTo);
         });

package/dist/esm/utils/index.js

@@ -1,5 +1,6 @@
 import { _resolveNestedKey } from '../array/helpers.js';
 import { sortAnArray } from '../array/sort.js';
+import { isDateLike } from '../date/guards.js';
 import { isArray, isArrayOfType, isMethodDescriptor, isNotEmptyObject, isObject, isValidArray, } from '../guards/non-primitives.js';
 import { isNonEmptyString, isPrimitive, isString } from '../guards/primitives.js';
 import { isNumericString } from '../guards/specials.js';
@@ -119,7 +120,9 @@ export function stableStringify(obj) {
         const keys = Object.keys(obj).sort();
         return ('{' +
             keys
-                .map((k) => JSON.stringify(k, _replacer) + ':' + stableStringify(obj[k]))
+                .map((k) => JSON.stringify(k, _replacer) +
+                ':' +
+                (isDateLike(obj[k]) ? JSON.stringify(obj[k]) : stableStringify(obj[k])))
                 .join(',') +
             '}');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.28.0",
+  "version": "4.28.4",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -42,8 +42,8 @@
     "@eslint/js": "^9.39.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.47.0",
-    "@typescript-eslint/parser": "^8.47.0",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
@@ -52,10 +52,10 @@
     "jest": "^30.2.0",
     "lint-staged": "^16.2.7",
     "nhb-scripts": "^1.8.88",
-    "prettier": "^3.6.2",
-    "ts-jest": "^29.4.5",
+    "prettier": "^3.7.3",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.47.0"
+    "typescript-eslint": "^8.48.0"
   },
   "keywords": [
     "toolbox",