feat(utils): equal

Signed-off-by: Lexus Drumgold <[email protected]>

.dictionary.txt

@@ -5,6 +5,7 @@ cefc
 codecov
 commitlintrc
 dedupe
+dequal
 dessant
 dohm
 fbca

package.json

@@ -81,6 +81,9 @@
     "typecheck": "vitest typecheck --run",
     "typecheck:watch": "vitest typecheck"
   },
+  "dependencies": {
+    "dequal": "2.0.3"
+  },
   "devDependencies": {
     "@commitlint/cli": "17.6.3",
     "@faker-js/faker": "8.0.1",

src/types/__tests__/fn.spec-d.ts

@@ -6,13 +6,15 @@
 import type TestSubject from '../fn'
 
 describe('unit-d:types/Fn', () => {
+  type A = [string, RegExp | string | undefined, (number | undefined)?]
+  type R = string[]
+  type Subject = TestSubject<A, R>
+
   it('should be callable with A', () => {
-    expectTypeOf<TestSubject>().parameters.toEqualTypeOf<any[]>()
-    expectTypeOf<TestSubject<[string]>>().parameters.toEqualTypeOf<[string]>()
+    expectTypeOf<Subject>().parameters.toEqualTypeOf<A>()
   })
 
   it('should return R', () => {
-    expectTypeOf<TestSubject>().returns.toBeAny()
-    expectTypeOf<TestSubject<any, string>>().returns.toBeString()
+    expectTypeOf<Subject>().returns.toEqualTypeOf<R>()
   })
 })

src/types/fn.ts

@@ -6,8 +6,8 @@
 /**
  * A function.
  *
- * @template A - Arguments type
- * @template R - Return type
+ * @template A - Function arguments type
+ * @template R - Function return type
  */
 type Fn<A extends any[] = any[], R = any> = Function & ((...args: A) => R)
 

src/types/nilable.ts

@@ -6,7 +6,7 @@
 import type NIL from './nil'
 
 /**
- * Type representing a value that also be `NIL`.
+ * Constructs a union type of {@linkcode NIL} and `T`.
  *
  * @template T - Value type
  */

src/types/nullable.ts

@@ -4,7 +4,7 @@
  */
 
 /**
- * Constructs a type where the value can be any type, or `null`.
+ * Constructs a union type of `T` and `null`.
  *
  * @template T - Value type
  */

src/utils/__tests__/equal.spec.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Unit Tests - equal
+ * @module tutils/utils/tests/unit/equal
+ */
+
+import INTEGER from '#fixtures/integer'
+import testSubject from '../equal'
+
+describe('unit:utils/equal', () => {
+  it('should return false if a and b are not deeply equal', () => {
+    // Arrange
+    const cases: Parameters<typeof testSubject>[] = [
+      [{}, { value: faker.number.int() }],
+      [[], [faker.number.int(), faker.number.int(), faker.number.int()]],
+      [INTEGER, INTEGER * -1],
+      [faker.date.future(), faker.date.past()]
+    ]
+
+    // Act + Expect
+    cases.forEach(([a, b]) => expect(testSubject(a, b)).to.be.false)
+  })
+
+  it('should return true if a and b are deeply equal', () => {
+    // Arrange
+    const cases: Parameters<typeof testSubject>[] = [
+      [{ value: INTEGER }, { value: INTEGER }],
+      [[INTEGER], [INTEGER]],
+      [INTEGER, INTEGER],
+      [new Date(), new Date()],
+      [new Date(), new Date(), value => (value as Date).getTime()]
+    ]
+
+    // Act + Expect
+    cases.forEach(([a, b, identity]) => {
+      expect(testSubject(a, b, identity)).to.be.true
+    })
+  })
+})

src/utils/__tests__/is-function.spec-d.ts

@@ -7,7 +7,12 @@ import type { Fn } from '#src/types'
 import type testSubject from '../is-function'
 
 describe('unit-d:utils/isFunction', () => {
-  it('should guard Fn', () => {
-    expectTypeOf<typeof testSubject>().guards.toEqualTypeOf<Fn>()
+  it('should guard Fn<A, R>', () => {
+    // Arrange
+    type A = any[]
+    type R = any
+
+    // Expect
+    expectTypeOf<typeof testSubject<A, R>>().guards.toEqualTypeOf<Fn>()
   })
 })

src/utils/__tests__/is-null.spec.ts

@@ -7,7 +7,7 @@ import testSubject from '../is-null'
 
 describe('unit:utils/isNull', () => {
   it('should return false if value is not null', () => {
-    expect(testSubject(faker.datatype.datetime())).to.be.false
+    expect(testSubject(faker.date.anytime())).to.be.false
   })
 
   it('should return true if value is null', () => {

src/utils/__tests__/is-object-plain.spec.ts

@@ -9,8 +9,8 @@ describe('unit:utils/isObjectPlain', () => {
   it('should return false if value is not plain object', () => {
     // Arrange
     const cases: Parameters<typeof testSubject>[] = [
-      [faker.datatype.array()],
-      [new Date()],
+      [[]],
+      [faker.date.anytime()],
       [null]
     ]
 
@@ -21,7 +21,7 @@ describe('unit:utils/isObjectPlain', () => {
   it('should return true if value is plain object', () => {
     // Arrange
     const cases: Parameters<typeof testSubject>[] = [
-      [{ x: 0, y: 0 }],
+      [{ zodiac: faker.person.zodiacSign() }],
       [Object.create(null)]
     ]
 

src/utils/__tests__/is-undefined.spec.ts

@@ -7,7 +7,7 @@ import testSubject from '../is-undefined'
 
 describe('unit:utils/isUndefined', () => {
   it('should return false if value is not undefined', () => {
-    expect(testSubject(faker.datatype.array())).to.be.false
+    expect(testSubject(faker.date.anytime())).to.be.false
   })
 
   it('should return true if value is undefined', () => {

src/utils/equal.ts

@@ -0,0 +1,35 @@
+/**
+ * @file Utilities - equal
+ * @module tutils/utils/equal
+ */
+
+import type { Fn, IndexSignature, Nilable, NumberString } from '#src/types'
+import { dequal } from 'dequal'
+import isFunction from './is-function'
+
+/**
+ * Returns a boolean indicating if values `a` and `b` are deeply equal.
+ *
+ * An `identity` function can be used to convert either value to a unique key.
+ * If provided, items with the same identity key will be considered equal.
+ *
+ * @see https://github.com/lukeed/dequal
+ *
+ * @template A - First comparison value type
+ * @template B - Second comparison value type
+ * @template K - Identity key type
+ *
+ * @param {unknown} a - First comparison value
+ * @param {unknown} b - Second comparison value
+ * @param {Nilable<Fn<[A | B], K>>} [identity] - Identity key function
+ * @return {boolean} `true` if `a` and `b` are deeply equal
+ */
+function equal<A, B, K extends IndexSignature = NumberString>(
+  a: A,
+  b: B,
+  identity?: Nilable<Fn<[A | B], K>>
+): boolean {
+  return isFunction(identity) ? dequal(identity(a), identity(b)) : dequal(a, b)
+}
+
+export default equal

src/utils/index.ts

@@ -4,6 +4,7 @@
  */
 
 export { default as capitalize } from './capitalize'
+export { default as equal } from './equal'
 export { default as isAppEnv } from './is-app-env'
 export { default as isArray } from './is-array'
 export { default as isBigInt } from './is-big-int'

src/utils/is-array.ts

@@ -3,6 +3,7 @@
  * @module tutils/utils/isArray
  */
 
+import equal from './equal'
 import isObject from './is-object'
 
 /**
@@ -14,7 +15,7 @@ import isObject from './is-object'
  * @return {value is ReadonlyArray<T> | T[]} `true` if `value` is an array
  */
 function isArray<T>(value: unknown): value is T[] | readonly T[] {
-  return isObject(value) && Reflect.get(value, 'constructor') === Array
+  return isObject(value) && equal(Reflect.get(value, 'constructor'), Array)
 }
 
 export default isArray

src/utils/is-date.ts

@@ -3,6 +3,7 @@
  * @module tutils/utils/isDate
  */
 
+import equal from './equal'
 import isObject from './is-object'
 
 /**
@@ -12,7 +13,7 @@ import isObject from './is-object'
  * @return {value is Date} `true` if `value` is {@linkcode Date} instance
  */
 function isDate(value: unknown): value is Date {
-  return isObject(value) && Reflect.get(value, 'constructor') === Date
+  return isObject(value) && equal(Reflect.get(value, 'constructor'), Date)
 }
 
 export default isDate

src/utils/is-empty-string.ts

@@ -4,16 +4,18 @@
  */
 
 import type { EmptyString } from '#src/types'
+import equal from './equal'
 import isString from './is-string'
+import trim from './trim'
 
 /**
- * Checks if the given `value` is an empty string.
+ * Checks if `value` is an empty string.
  *
- * @param {unknown} value - Value to evaluate
+ * @param {unknown} value - Value to check
  * @return {value is EmptyString} `true` if `value` is empty string
  */
 const isEmptyString = (value: unknown): value is EmptyString => {
-  return isString(value) ? value.trim() === '' : false
+  return isString(value) && equal(trim(value), '')
 }
 
 export default isEmptyString

src/utils/is-float.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Float } from '#src/types'
+import equal from './equal'
 import isNumber from './is-number'
 
 /**
@@ -15,7 +16,7 @@ import isNumber from './is-number'
  * @return {value is Float} `true` if `value` is a float
  */
 function isFloat(value: unknown): value is Float {
-  return isNumber(value) && value % 1 !== 0
+  return isNumber(value) && !equal(value % 1, 0)
 }
 
 export default isFloat

src/utils/is-function.ts

@@ -6,11 +6,16 @@
 import type { Fn } from '#src/types'
 
 /**
- * Checks if the given `value` is a function.
+ * Checks if `value` is a function.
  *
- * @param {unknown} value - Value to evaluate
- * @return {value is Fn} `true` if `value` is a function
+ * @template A - Function arguments type
+ * @template R - Function return type
+ *
+ * @param {unknown} value - Value to check
+ * @return {value is Fn<A, R>} `true` if `value` is a function
  */
-const isFunction = (value: unknown): value is Fn => typeof value === 'function'
+function isFunction<A extends any[], R>(value: unknown): value is Fn<A, R> {
+  return typeof value === 'function'
+}
 
 export default isFunction

src/utils/is-integer.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Integer } from '#src/types'
+import equal from './equal'
 import isNumber from './is-number'
 
 /**
@@ -15,7 +16,7 @@ import isNumber from './is-number'
  * @return {value is Integer} `true` if `value` is an integer
  */
 function isInteger(value: unknown): value is Integer {
-  return isNumber(value) && value % 1 === 0
+  return isNumber(value) && equal(value % 1, 0)
 }
 
 export default isInteger

src/utils/is-lowercase.ts

@@ -3,6 +3,7 @@
  * @module tutils/utils/isLowercase
  */
 
+import equal from './equal'
 import isString from './is-string'
 import lowercase from './lowercase'
 
@@ -15,7 +16,7 @@ import lowercase from './lowercase'
  * @return {value is Lowercase<T>} `true` if `value` is lowercase string
  */
 function isLowercase<T extends string>(value: unknown): value is Lowercase<T> {
-  return isString(value) && value === lowercase(value)
+  return isString(value) && equal(value, lowercase(value))
 }
 
 export default isLowercase

src/utils/is-map.ts

@@ -3,6 +3,7 @@
  * @module tutils/utils/isMap
  */
 
+import equal from './equal'
 import isObject from './is-object'
 
 /**
@@ -15,7 +16,7 @@ import isObject from './is-object'
  * @return {value is Map<K, V>} `true` if `value` is {@linkcode Map} instance
  */
 function isMap<K, V>(value: unknown): value is Map<K, V> {
-  return isObject(value) && Reflect.get(value, 'constructor') === Map
+  return isObject(value) && equal(Reflect.get(value, 'constructor'), Map)
 }
 
 export default isMap

src/utils/is-null.ts

@@ -3,12 +3,14 @@
  * @module tutils/utils/isNull
  */
 
+import equal from './equal'
+
 /**
- * Checks if the given `value` is `null`.
+ * Checks if `value` is `null`.
  *
- * @param {unknown} value - Value to evaluate
+ * @param {unknown} value - Value to check
  * @return {value is null} `true` if `value` is `null`
  */
-const isNull = (value: unknown): value is null => value === null
+const isNull = (value: unknown): value is null => equal(value, null)
 
 export default isNull

src/utils/is-object-plain.ts

@@ -4,10 +4,11 @@
  */
 
 import type { ObjectPlain } from '#src/types'
+import equal from './equal'
 import isNull from './is-null'
 
 /**
- * Checks if the given `value` is a plain object (i.e. [POJO][1]).
+ * Checks if `value` is a plain object (i.e. [POJO][1]).
  *
  * A plain object is an object created by the [`Object`][2] constructor or an
  * object with a `[[Prototype]]` of `null`.
@@ -17,7 +18,7 @@ import isNull from './is-null'
  *
  * @see {@linkcode ObjectPlain}
  *
- * @param {unknown} value - Value to evaluate
+ * @param {unknown} value - Value to check
  * @return {value is ObjectPlain} `true` if `value` is plain object
  */
 const isObjectPlain = (value: unknown): value is ObjectPlain => {
@@ -51,7 +52,7 @@ const isObjectPlain = (value: unknown): value is ObjectPlain => {
       }
 
       // prototypes are equal => value is plain object
-      plain = Object.getPrototypeOf(value) === proto
+      plain = equal(Object.getPrototypeOf(value), proto)
 
       break
   }