nhb-toolbox 4.28.1 → 4.28.4

package/CHANGELOG.md

@@ -6,6 +6,14 @@ 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.

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/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/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.1",
+  "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",