@react-fabric/utilities 1.0.0-beta.9 → 1.0.2

package/src/index.ts

@@ -1,51 +1,71 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
 /* istanbul ignore file */
 
-export * from "./_ascii";
-export * from "./_boundingBox";
-export { getBoundingBox, getBox } from "./_boundingBox";
-export { default as Countries } from "./_countries";
-export type { Country } from "./_countries";
-export * from "./_debounce";
-export * from "./_dedupe";
-export { _fetch as fetch } from "./_fetch";
-export { default as FileUtil } from "./_fileType";
-export * from "./_format";
-export * from "./_getByPath";
-export * from "./_hash";
-export * from "./_interpolate";
-export * from "./_isEqual";
-export * from "./_isType";
-export * from "./_mergeRefs";
-export * from "./_tokenize";
-export { getImageColorset } from "./getImageColorset";
-export { useLogger } from "./useLogger";
-export * from "./yup";
+export const UTILITIES_PACKAGE = "@react-fabric/utilities";
+export const UTILITIES_VERSION = "1.0.0";
+
+export { getBoundingBox, getBox } from "./css/boundingBox";
+export { cn } from "./css/cn";
+export { getImageColorset } from "./css/imageColorset";
+
+export { dedupe } from "./lists/dedupe";
+export { flatten, flattenAndDedupe } from "./lists/flatten";
+export { getByPath, getValue } from "./lists/getByPath";
+export { groupBy } from "./lists/groupBy";
+
+export { default as Countries } from "./data/countries";
+export type { Country } from "./data/countries";
+export { default as FileUtil } from "./data/fileType";
+export { Format } from "./data/format";
+
+export { debounce } from "./helpers/debounce";
+export { getLogger } from "./helpers/getLogger";
+export { convertToLonLat, getLatitudeLongitude, getLocationAsText } from "./helpers/lonlat";
+export type { LngLatLike } from "./helpers/lonlat";
+
+export { compareValues } from "./matchers/compare";
+export { isEmpty } from "./matchers/isEmpty";
+export { isEqual } from "./matchers/isEqual";
+export { isDefined, isNil, isNull, isUndefined } from "./matchers/nullChecks";
+export { isArray, isBoolean, isColor, isFalse, isNumber, isObject, isString, isSvgPath, isTrue } from "./matchers/typeChecks";
+
+export { hash, shortHash, uuid } from "./strings/hash";
+export { interpolate } from "./strings/interpolate";
+export { matchString } from "./strings/matchString";
+export { renderTemplate } from "./strings/template";
+export { iconToken, tokenize } from "./strings/tokenize";
+
+export { mergeRefs } from "./utils/mergeRefs";
+export { yup } from "./utils/yup";
 
 export const EMPTY_ARRAY = [];
 Object.freeze(EMPTY_ARRAY);
 
 export const EMPTY_OBJECT = {};
 Object.freeze(EMPTY_OBJECT);
+
+export const EMPTY_FC = () => () => null;

package/src/lists/dedupe.ts

@@ -0,0 +1,46 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { isEmpty } from "../matchers/isEmpty";
+
+/**
+ * Remove duplicates from a list of objects based on a key or the entire object.
+ * If a key is provided, it will deduplicate based on the value of that key.
+ * If no key is provided, it will deduplicate based on the entire object.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ *
+ * @param list
+ * @param key
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A new array with duplicates removed.
+ */
+export function dedupe<T extends AnyObject>(list: T[], key?: keyof T) {
+  const filtered = list.filter((i) => !isEmpty(i));
+  if (!key) {
+    return Array.from(new Set(filtered).values());
+  }
+
+  return Array.from(new Map(filtered.map((obj) => [(obj as KeyValue)[key], obj])).values());
+}

package/src/lists/flatten.ts

@@ -0,0 +1,56 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { isEmpty } from "../matchers/isEmpty";
+import { dedupe } from "./dedupe";
+
+/**
+ * Flatten a list of objects, removing any empty objects.
+ * It will flatten up to 5 levels deep and filter out any empty objects.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ *
+ * @param list
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A flattened array of objects.
+ */
+export function flatten<T extends AnyObject>(list: T[]) {
+  return list.flat(5).filter((i) => !isEmpty(i));
+}
+
+/**
+ * Flatten a list of objects and remove duplicates based on a key or the entire object.
+ * If a key is provided, it will deduplicate based on the value of that key.
+ * If no key is provided, it will deduplicate based on the entire object.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ * Flattening is done first, followed by deduplication.
+ *
+ * @param list
+ * @param key
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A new array with duplicates removed.
+ */
+export function flattenAndDedupe<T extends AnyObject>(list: T[][] = [], key?: keyof T) {
+  return dedupe(flatten(list) as T[], key);
+}

package/src/lists/getByPath.ts

@@ -0,0 +1,122 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { isEmpty } from "../matchers/isEmpty";
+import { isNil } from "../matchers/nullChecks";
+import { isArray, isObject } from "../matchers/typeChecks";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+
+function _get(hit: any, field: string): any {
+  /** ***************** return if object is empty *******************/
+  /* istanbul ignore next */
+  if (isNil(hit)) {
+    return undefined;
+  }
+  /** ***************** return object if property is empty *******************/
+  /* istanbul ignore next */
+  if (isNil(field)) {
+    return hit;
+  }
+
+  if (isObject(hit) || isArray(hit)) {
+    /** ***************** return value if object.property is not empty *******************/
+    if (!isNil(hit[field as any])) {
+      return hit[field as any];
+    }
+
+    /** ***************** if property name contains `.` separator split to multiple property names *******************/
+    if (field.includes(".")) {
+      let currentValue: any = hit;
+
+      const path = field.split(".");
+      for (let i = path.length - 1; i >= 0; i--) {
+        /** ***************** when property name is `a.b.c` iterate until property found in object. eg. `a`, `a.b` *******************/
+        const outerPath = path.slice(0, i).join(".");
+
+        /** ***************** join rest of property list *******************/
+        const innerPath = path.slice(i).join(".");
+
+        /** ***************** if current outer path found in object *******************/
+        if (outerPath in currentValue) {
+          currentValue = currentValue[outerPath];
+
+          /** ***************** check for type array *******************/
+          if (isArray(currentValue)) {
+            /** ***************** return value if remaining path found *******************/
+            if (currentValue[innerPath as any]) {
+              return currentValue[innerPath as any];
+            }
+            /** ***************** return array map of inner propeties *******************/
+            return currentValue.map((val) => _get(val, innerPath)).filter((val) => !isEmpty(val));
+          } else {
+            /** ***************** return value of remaining path *******************/
+            return _get(currentValue, innerPath);
+          }
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Get a value from an object by a given path.
+ * This function allows you to retrieve a value from a nested object structure using a dot-separated path.
+ * If the path does not exist or the object is empty, it returns a default value.
+ * @param {KeyValue} obj - The object from which to retrieve the value.
+ * @param {string} path - The dot-separated path to the value within the object.
+ * @param {any} defaultValue - The value to return if the path does not exist or the object is empty.
+ * @typedef {T} AnyObject - The type of the value to be returned.
+ * @returns {T} The value at the specified path, or the default value if the path does not exist.
+ */
+export function getByPath<T = unknown>(obj: KeyValue, path: string, defaultValue: any = undefined): T {
+  /** ***************** if empty object/path return defaultValue *******************/
+  if (isEmpty(obj) || isEmpty(path)) {
+    return defaultValue;
+  }
+  const value = _get(obj, path);
+  if (!isNil(value)) {
+    return value;
+  }
+  return defaultValue;
+}
+
+/**
+ * Get the first non-empty value from the provided arguments.
+ * This function is useful for finding a default value or fallback when multiple values are provided.
+ * It checks each argument in order and returns the first one that is not empty.
+ * If all arguments are empty, it returns `undefined`.
+ *
+ * @param {...any} args - The values to check for non-emptiness.
+ * @returns {any} The first non-empty value, or `undefined` if all are empty.
+ */
+export function getValue<T = string>(...args: T[]) {
+  return args.find((a) => !isEmpty(a));
+}

package/src/lists/groupBy.ts

@@ -0,0 +1,47 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Group a list of objects by a specific property.
+ * If the property is not present in an object, it will use the `missingKey` value as the key.
+ * This is useful for organizing data into categories based on a specific property.
+ *
+ * @param list
+ * @param prop
+ * @param missingKey
+ * @typedef {T} KeyValue - A generic type representing list items with key-value pairs.
+ * @returns {KeyValue<T[]>} - An object mapping keys to arrays of items.
+ */
+export function groupBy<T extends KeyValue>(list: T[], prop: keyof T, missingKey?: string): KeyValue<T[]> {
+  return list.reduce<KeyValue<T[]>>(
+    (r, i) => {
+      const key = (i[prop] as string) ?? missingKey;
+      if (!r[key]) r[key] = [];
+      r[key].push(i);
+      return r;
+    },
+    {} as KeyValue<T[]>,
+  );
+}

package/src/matchers/compare.ts

@@ -0,0 +1,64 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { getByPath } from "../lists/getByPath";
+import { ascii } from "../strings/ascii";
+import { isBoolean, isNumber, isObject } from "./typeChecks";
+
+/**
+ * Compare two values for sorting.
+ * This function compares two values based on the specified order (ascending or descending).
+ * If a key is provided, it compares the values of that key in the objects.
+ * It handles various data types such as strings, numbers, booleans, and objects.
+ * It returns a comparison function that can be used with array sorting methods.
+ * * The comparison is done in a case-insensitive manner for strings,
+ *  treating special characters as their ASCII equivalents.
+ *
+ * @param {("asc" | "desc")} order - The order of comparison, either "asc" for ascending or "desc" for descending.
+ * @param {string} key - An optional key to compare values within objects.
+ * @returns {Function} A comparison function that can be used with array sorting methods.
+ */
+export function compareValues(order: "asc" | "desc" = "asc", key?: string) {
+  return (a: unknown, b: unknown) => {
+    const aValue: unknown = key && isObject(a) ? getByPath(a, key, "") : a;
+    const bValue: unknown = key && isObject(b) ? getByPath(b, key, "") : b;
+
+    const bigger = order === "asc" ? 1 : -1;
+    const smaller = order === "desc" ? 1 : -1;
+    // return 0 when equal, allowing for multiple sorting properties
+    if (aValue === bValue) return 0;
+    // if numbers check greater
+    if (isNumber(aValue) && isNumber(bValue)) {
+      return aValue > bValue ? bigger : smaller;
+    }
+    // if boolean sort true first
+    if (isBoolean(aValue) && isBoolean(bValue)) {
+      return aValue ? smaller : bigger;
+    }
+    const _a = ascii(aValue as string).toLowerCase();
+    const _b = ascii(bValue as string).toLowerCase();
+    return _a.localeCompare(_b) === 1 ? bigger : smaller;
+  };
+}

package/src/matchers/isEmpty.ts

@@ -0,0 +1,54 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { isDefined, isNil } from "./nullChecks";
+
+/**
+ * Check if a value is empty.
+ * A value is considered empty if it is:
+ * - undefined
+ * - null
+ * - an empty string
+ * - an empty array
+ * - an empty object
+ * - an empty Map or Set
+ * - a boolean, number, or bigint (not empty)
+ * @param val - The value to check.
+ * @returns true if the value is empty, false otherwise.
+ */
+export function isEmpty(val: AnyObject): val is undefined {
+  if (val instanceof Date) return false;
+  if (isNil(val) || val === "") {
+    return true;
+  }
+  if (Array.isArray(val) && val.filter(isDefined).length === 0) {
+    return true;
+  }
+  if (val instanceof Map || val instanceof Set) return val.size === 0;
+  if (["boolean", "number", "bigint", "function"].includes(typeof val)) {
+    return false;
+  }
+  return !!val && typeof val === "object" && Object.entries(val as object).length === 0;
+}

package/src/matchers/isEqual.ts

@@ -0,0 +1,71 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { isNil } from "./nullChecks";
+import { isBoolean, isNumber, isObject, isString } from "./typeChecks";
+
+/**
+ * Compare two objects or values for equality.
+ * This function checks if two values are equal, including nested objects and arrays.
+ * It handles various data types such as strings, numbers, booleans, arrays, and objects.
+ * If both values are `null` or `undefined`, they are considered equal.
+ * If both values are primitive types (string, number, boolean), they are compared directly.
+ * If both values are arrays, they are compared element by element.
+ * If both values are objects, they are compared by their keys and values.
+ * If the values are of different types or structures, they are considered not equal.
+ *
+ * @param {unknown} obj - The first value to compare.
+ * @param {unknown} test - The second value to compare against the first.
+ * @returns {boolean} - Returns true if the values are equal, false otherwise.
+ */
+export function isEqual(obj: unknown, test: unknown): boolean {
+  if (isNil(obj) && isNil(test)) {
+    return true;
+  }
+  if (isString(obj) || isNumber(obj) || isBoolean(obj)) {
+    return obj === test;
+  } else if (Array.isArray(obj) && Array.isArray(test)) {
+    // if length dont match return false
+    if (obj.length !== test.length) {
+      return false;
+    }
+    // check if some value is false
+    return !obj.some((o, i) => !isEqual(o, test[i]));
+  } else if (isObject(obj) && isObject(test)) {
+    const okeys = Object.keys(obj);
+    const tkeys = Object.keys(test);
+    // if keys length dont match return false
+    if (okeys.length !== tkeys.length) {
+      return false;
+    }
+    // if keys dont match return false
+    if (okeys.some((k) => !tkeys.includes(k))) {
+      return false;
+    }
+    // check if some value is false
+    return !Object.keys(obj).some((k) => !isEqual(obj[k], test[k]));
+  }
+  return false;
+}

package/src/matchers/nullChecks.ts

@@ -0,0 +1,55 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Check if a value is undefined.
+ * @param value - The value to check.
+ * @returns true if the value is undefined, false otherwise.
+ */
+export function isUndefined(value: AnyObject): value is undefined {
+  return value === undefined;
+}
+
+/**
+ * Check if a value is null.
+ * @param value - The value to check.
+ * @returns true if the value is null, false otherwise.
+ */
+export function isNull(value: AnyObject): value is null {
+  return value === null;
+}
+
+/**
+ * Check if a value is either null or undefined.
+ * @param val - The value to check.
+ * @returns true if the value is null or undefined, false otherwise.
+ */
+export function isNil(val: AnyObject): val is null | undefined {
+  return val === undefined || val === null;
+}
+
+export function isDefined(val: AnyObject): boolean {
+  return !isNil(val) && val !== "";
+}