@uxf/core 11.80.0 → 11.85.0

package/README.md

@@ -125,6 +125,63 @@ useIsomorphicLayoutEffect(() => {
 
 > **Note**: Requires valid `line-height` and `font-size` styles for accurate sizing.
 
+### assertNever
+
+Checks that value is always type "never".
+```ts
+switch(value) {
+    case "a":
+        return "A";
+    case "b":
+        return "B";
+    default:
+        return assertNever(value);
+}
+```
+
+## assertNotNil
+
+```tsx
+import { assertNotNil } from "@uxf/core/utils/assert-not-nil";
+
+const testObject: { value: number | null } = { value: 10 };
+
+assertNotNil(testObject.value);
+
+// is the same as
+
+if (isNil(testObject.value)) {
+    throw new Error("Value is null");
+}
+```
+
+## camelCaseToDash
+
+```tsx
+import { camelCaseToDash } from "@uxf/core/utils/camelCaseToDash";
+
+const example = camelCaseToDash("fooBar"); /* returns "foo-bar" */
+```
+
+## capitalize
+
+```tsx
+import { capitalize } from "@uxf/core/utils/capitalize";
+
+const example = capitalize("hello world"); /* returns "Hello world" */
+```
+
+## composeRefs
+
+```tsx
+import { composeRefs } from "@uxf/core/utils/composeRefs";
+
+const firstRef = useRef<HTMLDivElement>(null);
+const secondRef = useRef<HTMLDivElement>(null);
+
+const example = <div ref={composeRefs(firstRef, secondRef)} />;
+```
+
 ### cx, cxa
 It is our fork of `clsx` library https://github.com/lukeed/clsx
 
@@ -175,9 +232,30 @@ cxa("foo", [1 && "bar", { baz:false, bat:null }, ["hello", ["world"]]], "cya");
 //=> "foo bar hello world cya"
 ```
 
+### deepEqualIgnoringKeyOrder
+
+deepEqualIgnoringKeyOrder compares two values for deep equality while ignoring the order of object keys. It serializes values in a stable way, ensuring that objects with the same data but different key orders are treated as equal. Arrays remain order-sensitive, circular references are handled safely, and primitives are compared by value.
+
+Use this helper for equality checks in tests, memoization, caching, or change detection scenarios where object key order shouldn’t matter. It’s especially useful when comparing payloads, configs, or API responses that may have non-deterministic key ordering.
+
+```typescript
+import { deepEqualIgnoringKeyOrder } from "./deep-equal-ingoring-key-order";
+
+const a = { b: 2, a: 1, nested: { y: 2, x: 1 } };
+const b = { nested: { x: 1, y: 2 }, a: 1, b: 2 };
+console.log(deepEqualIgnoringKeyOrder(a, b)); // true
+
+const arr1 = [{ a: 1, b: 2 }, { c: 3, d: 4 }];
+const arr2 = [{ b: 2, a: 1 }, { d: 4, c: 3 }];
+console.log(deepEqualIgnoringKeyOrder(arr1, arr2)); // true (objects equal, same array order)
+
+const arr3 = [{ d: 4, c: 3 }, { b: 2, a: 1 }];
+console.log(deepEqualIgnoringKeyOrder(arr1, arr3)); // false (array order differs)
+```
+
 ### downloadFile
 
-Intended as only way to programmatically download file if there is no option to use native anchor with `download` html attribute (eg. in form submit events). 
+Intended as only way to programmatically download file if there is no option to use native anchor with `download` html attribute (eg. in form submit events).
 
 ```ts
 import { downloadFile } from "@uxf/core/utils/download-file";
@@ -199,6 +277,14 @@ escapeQuotes('The "quick" fox');
 // Output: The \"quick\" fox
 ```
 
+## filterNullish
+
+```tsx
+import { filterNullish } from "@uxf/core/utils/filter-nullish";
+
+filterNullish([0, "text", null, undefined, [], {}]); /* returns [0, "text", [], {}]  */
+```
+
 ### formatBytes
 
 Appends suitable unit to the byte value of data size.
@@ -207,18 +293,102 @@ formatBytes(17.5 * 1024);
 //=> "17.5 kB"
 ```
 
-### assertNever
+## isEmpty
 
-Checks that value is always type "never".
-```ts
-switch(value) {
-    case "a":
-        return "A";
-    case "b":
-        return "B";
-    default:
-        return assertNever(value);
-}
+```tsx
+import { isEmpty } from "@uxf/core/utils/is-empty";
+
+isEmpty("not-empty"); /* returns false */
+isEmpty(""); /* returns true */
+isEmpty(["1"]); /* returns false */
+isEmpty([]); /* returns true */
+```
+
+## isBrowser / isServer
+
+```tsx
+import { isBrowser } from "@uxf/core/utils/isBrowser";
+import { isServer } from "@uxf/core/utils/isServer";
+
+const browserExample = isBrowser; /* returns true if DOM is available */
+const serverExample = isServer; /* returns true if DOM is NOT available */
+```
+
+## isNil
+
+```tsx
+import { isNil } from "@uxf/core/utils/is-nil";
+
+isNil(null);      /* returns true */
+isNil(undefined); /* returns true */
+isNil(true);      /* returns false */
+isNil(1);         /* returns false */
+isNil(0);         /* returns false */
+isNil([]);        /* returns false */
+isNil("string");  /* returns false */
+```
+
+## isNotNil
+
+```tsx
+import { isNotNil } from "@uxf/core/utils/is-not-nil";
+
+isNotNil(null);      /* returns false */
+isNotNil(undefined); /* returns false */
+isNotNil(true);      /* returns true */
+isNotNil(1);         /* returns true */
+isNotNil(0);         /* returns true */
+isNotNil([]);        /* returns true */
+isNotNil("string");  /* returns true */
+```
+
+```tsx
+import { last } from "@uxf/core/utils/last";
+
+last([1, 2]); /* returns 2 */
+last([]);     /* returns undefined */
+```
+
+## slugify
+
+```tsx
+import { slugify } from "@uxf/core/utils/slugify";
+
+const example = slugify("Jak se dnes máte?"); /* returns "jak-se-dnes-mate" */
+```
+
+### stableStringify
+
+Deterministically converts any JavaScript value into a JSON string by recursively sorting object keys while preserving array order. It safely handles circular references by replacing them with the string "[Circular]" and never mutates the input. This makes it ideal for creating stable cache keys, hashing inputs, logging, or equality checks that should ignore object key order.
+
+```typescript
+// Example usage
+import { stableStringify } from "./stable-stringify";
+
+// Key order does not affect the output
+const a = { b: 2, a: 1, nested: { y: 2, x: 1 } };
+const b = { nested: { x: 1, y: 2 }, a: 1, b: 2 };
+
+console.log(stableStringify(a));
+// -> {"a":1,"b":2,"nested":{"x":1,"y":2}}
+
+console.log(stableStringify(b));
+// -> {"a":1,"b":2,"nested":{"x":1,"y":2}}  // same as above
+
+// Circular references are handled
+const obj: any = { name: "root" };
+obj.self = obj;
+
+console.log(stableStringify(obj));
+// -> {"name":"root","self":"[Circular]"}
+```
+
+## trimTrailingZeros
+
+```tsx
+import { trimTrailingZeros } from "@uxf/core/utils/trimTrailingZeros";
+
+const example = trimTrailingZeros("120,450"); /* returns "120,45" */
 ```
 
 ## Validators
@@ -228,3 +398,4 @@ import { Validator } from "@uxf/core";
 Validator.isEmail("...");
 Validator.isPhone("...");
 ```
+

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/core",
-    "version": "11.80.0",
+    "version": "11.85.0",
     "description": "UXF Core",
     "author": "Petr Vejvoda <vejvoda@uxf.cz>",
     "homepage": "https://gitlab.com/uxf-npm/core#readme",

package/utils/deep-equal-ingoring-key-order.d.ts

@@ -0,0 +1 @@
+export declare function deepEqualIgnoringKeyOrder(a: unknown, b: unknown): boolean;

package/utils/deep-equal-ingoring-key-order.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqualIgnoringKeyOrder = deepEqualIgnoringKeyOrder;
+const stable_stringify_1 = require("./stable-stringify");
+function deepEqualIgnoringKeyOrder(a, b) {
+    return (0, stable_stringify_1.stableStringify)(a) === (0, stable_stringify_1.stableStringify)(b);
+}

package/utils/deep-equal-ingoring-key-order.test.d.ts

@@ -0,0 +1 @@
+export {};

package/utils/deep-equal-ingoring-key-order.test.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// packages/core/utils/deep-equal-ingoring-key-order.test.ts
+const deep_equal_ingoring_key_order_1 = require("./deep-equal-ingoring-key-order");
+describe("deepEqualIgnoringKeyOrder", () => {
+    it("returns true for objects with same keys in different orders", () => {
+        const a = { b: 2, a: 1, c: 3 };
+        const b = { c: 3, b: 2, a: 1 };
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("returns true for nested objects with different key orders", () => {
+        const a = { z: 0, nested: { b: 2, a: 1 }, another: { y: 2, x: 1 } };
+        const b = { another: { x: 1, y: 2 }, nested: { a: 1, b: 2 }, z: 0 };
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("returns true for arrays where items are objects with different key orders", () => {
+        const a = [
+            { b: 2, a: 1 },
+            { d: 4, c: 3 },
+        ];
+        const b = [
+            { a: 1, b: 2 },
+            { c: 3, d: 4 },
+        ];
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("returns false when array order differs", () => {
+        const a = [
+            { a: 1, b: 2 },
+            { c: 3, d: 4 },
+        ];
+        const b = [
+            { c: 3, d: 4 },
+            { a: 1, b: 2 },
+        ];
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(false);
+    });
+    it("returns false when values differ", () => {
+        const a = { a: 1, b: 2 };
+        const b = { a: 1, b: 3 };
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(false);
+    });
+    it("returns false for different types", () => {
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(1, "1")).toBe(false);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(true, "true")).toBe(false);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(null, {})).toBe(false);
+    });
+    it("returns true for identical primitives", () => {
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(null, null)).toBe(true);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(42, 42)).toBe(true);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(true, true)).toBe(true);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)("hello", "hello")).toBe(true);
+    });
+    it("handles equal circular object references as equal", () => {
+        const a = { name: "root" };
+        a.self = a;
+        const b = { name: "root" };
+        b.self = b;
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("distinguishes different circular shapes", () => {
+        const x = { a: 1 };
+        x.self = x; // self points to parent
+        const y = { a: 1, self: {} };
+        y.self.self = y.self; // self points to itself (nested circular)
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(x, y)).toBe(false);
+    });
+    it("works with nested circular structures", () => {
+        const a = { id: 1, child: { id: 2 } };
+        a.child.parent = a;
+        const b = { child: { id: 2 }, id: 1 };
+        b.child.parent = b;
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+});

package/utils/stable-stringify.d.ts

@@ -0,0 +1 @@
+export declare function stableStringify(value: unknown): string;

package/utils/stable-stringify.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableStringify = stableStringify;
+function stableStringify(value) {
+    const seen = new WeakSet();
+    function normalize(val) {
+        if (val && typeof val === "object") {
+            if (seen.has(val)) {
+                return "[Circular]";
+            }
+            seen.add(val);
+            if (Array.isArray(val)) {
+                return val.map(normalize);
+            }
+            // plain object: sort keys
+            const out = {};
+            for (const key of Object.keys(val).sort()) {
+                out[key] = normalize(val[key]);
+            }
+            return out;
+        }
+        return val;
+    }
+    return JSON.stringify(normalize(value));
+}

package/utils/stable-stringify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/utils/stable-stringify.test.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stable_stringify_1 = require("./stable-stringify");
+describe("stableStringify", () => {
+    it("produces identical strings for objects with the same keys in different orders", () => {
+        const a = { b: 2, a: 1, c: 3 };
+        const b = { c: 3, b: 2, a: 1 };
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe((0, stable_stringify_1.stableStringify)(b));
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe('{"a":1,"b":2,"c":3}');
+    });
+    it("sorts keys recursively in nested objects", () => {
+        const a = { z: 0, nested: { b: 2, a: 1 }, another: { y: 2, x: 1 } };
+        const b = { another: { x: 1, y: 2 }, nested: { a: 1, b: 2 }, z: 0 };
+        const sa = (0, stable_stringify_1.stableStringify)(a);
+        const sb = (0, stable_stringify_1.stableStringify)(b);
+        expect(sa).toBe(sb);
+        expect(sa).toBe('{"another":{"x":1,"y":2},"nested":{"a":1,"b":2},"z":0}');
+    });
+    it("normalizes arrays while preserving array order", () => {
+        const a = [
+            { b: 2, a: 1 },
+            { d: 4, c: 3 },
+        ];
+        const b = [
+            { a: 1, b: 2 },
+            { c: 3, d: 4 },
+        ];
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe((0, stable_stringify_1.stableStringify)(b));
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe('[{"a":1,"b":2},{"c":3,"d":4}]');
+    });
+    it("handles circular references in objects", () => {
+        const obj = { name: "root" };
+        obj.self = obj;
+        expect((0, stable_stringify_1.stableStringify)(obj)).toBe('{"name":"root","self":"[Circular]"}');
+    });
+    it("handles circular references in arrays", () => {
+        const arr = [];
+        arr.push(arr);
+        expect((0, stable_stringify_1.stableStringify)(arr)).toBe('["[Circular]"]');
+    });
+    it("handles mixed nested circular structures", () => {
+        const a = { id: 1, child: { id: 2 } };
+        a.child.parent = a;
+        const str = (0, stable_stringify_1.stableStringify)(a);
+        expect(str).toBe('{"child":{"id":2,"parent":"[Circular]"},"id":1}');
+    });
+    it("handles primitives", () => {
+        expect((0, stable_stringify_1.stableStringify)(null)).toBe("null");
+        expect((0, stable_stringify_1.stableStringify)(42)).toBe("42");
+        expect((0, stable_stringify_1.stableStringify)(true)).toBe("true");
+        expect((0, stable_stringify_1.stableStringify)("hello")).toBe('"hello"');
+    });
+    it("does not mutate the input object", () => {
+        const input = { b: 2, a: 1, nested: { y: 2, x: 1 } };
+        const snapshot = JSON.parse(JSON.stringify(input));
+        void (0, stable_stringify_1.stableStringify)(input);
+        expect(input).toEqual(snapshot);
+    });
+});