feat(utils): isJoinable, isPromise

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

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

@@ -0,0 +1,13 @@
+/**
+ * @file Type Tests - isJoinable
+ * @module tutils/utils/tests/unit-d/isJoinable
+ */
+
+import type { Joinable } from '#src/types'
+import type testSubject from '../is-joinable'
+
+describe('unit-d:utils/isJoinable', () => {
+  it('should guard Joinable', () => {
+    expectTypeOf<typeof testSubject>().guards.toEqualTypeOf<Joinable>()
+  })
+})

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

@@ -0,0 +1,32 @@
+/**
+ * @file Unit Tests - isJoinable
+ * @module tutils/utils/tests/unit/isJoinable
+ */
+
+import VEHICLE from '#fixtures/vehicle'
+import testSubject from '../is-joinable'
+
+describe('unit:utils/isJoinable', () => {
+  it('should return false if value is not joinable', () => {
+    // Arrange
+    const cases: Parameters<typeof testSubject>[] = [[VEHICLE], [Symbol('.')]]
+
+    // Act + Expect
+    cases.forEach(([value]) => expect(testSubject(value)).to.be.false)
+  })
+
+  it('should return true if value is joinable', () => {
+    // Arrange
+    const cases: Parameters<typeof testSubject>[] = [
+      [faker.number.bigInt()],
+      [faker.datatype.boolean()],
+      [faker.number.int()],
+      [faker.string.nanoid()],
+      [null],
+      [undefined]
+    ]
+
+    // Act + Expect
+    cases.forEach(([value]) => expect(testSubject(value)).to.be.true)
+  })
+})

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

@@ -0,0 +1,12 @@
+/**
+ * @file Type Tests - isPromise
+ * @module tutils/utils/tests/unit-d/isPromise
+ */
+
+import type testSubject from '../is-promise'
+
+describe('unit-d:utils/isPromise', () => {
+  it('should guard Promise<T>', () => {
+    expectTypeOf<typeof testSubject>().guards.toEqualTypeOf<Promise<unknown>>()
+  })
+})

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

@@ -0,0 +1,17 @@
+/**
+ * @file Unit Tests - isPromise
+ * @module tutils/utils/tests/unit/isPromise
+ */
+
+import testSubject from '../is-promise'
+import tryit from '../tryit'
+
+describe('unit:utils/isPromise', () => {
+  it('should return false if value is not Promise instance', () => {
+    expect(testSubject(faker.string.nanoid())).to.be.false
+  })
+
+  it('should return true if value is Promise instance', () => {
+    expect(testSubject(tryit(vi.fn(() => faker.string.uuid()))())).to.be.true
+  })
+})

src/utils/index.ts

@@ -51,6 +51,7 @@ export { default as isInt16Array } from './is-int16-array'
 export { default as isInt32Array } from './is-int32-array'
 export { default as isInt8Array } from './is-int8-array'
 export { default as isInteger } from './is-integer'
+export { default as isJoinable } from './is-joinable'
 export { default as isJsonPrimitive } from './is-json-primitive'
 export { default as isLowercase } from './is-lowercase'
 export { default as isMap } from './is-map'
@@ -64,6 +65,7 @@ export { default as isObject } from './is-object'
 export { default as isObjectCurly } from './is-object-curly'
 export { default as isObjectPlain } from './is-object-plain'
 export { default as isPrimitive } from './is-primitive'
+export { default as isPromise } from './is-promise'
 export { default as isRegExp } from './is-reg-exp'
 export { default as isSet } from './is-set'
 export { default as isString } from './is-string'

src/utils/is-big-int.ts

@@ -9,8 +9,10 @@
  * [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigInt
  * [2]: https://developer.mozilla.org/docs/Glossary/Primitive
  *
+ * @todo examples
+ *
  * @param {unknown} value - Value to check
- * @return {value is bigint} `true` if `value` is `bigint`
+ * @return {value is bigint} `true` if `value` is `bigint` primitive
  */
 const isBigInt = (value: unknown): value is bigint => typeof value === 'bigint'
 

src/utils/is-joinable.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Utilities - isJoinable
+ * @module tutils/utils/isJoinable
+ */
+
+import type { Joinable } from '#src/types'
+import isBigInt from './is-big-int'
+import isJsonPrimitive from './is-json-primitive'
+import isUndefined from './is-undefined'
+
+/**
+ * Checks if `value` is joinable.
+ *
+ * @see {@linkcode Joinable}
+ *
+ * @todo examples
+ *
+ * @param {unknown} value - Value to check
+ * @return {value is Joinable} `true` if `value` is joinable
+ */
+const isJoinable = (value: unknown): value is Joinable => {
+  return isBigInt(value) || isJsonPrimitive(value) || isUndefined(value)
+}
+
+export default isJoinable

src/utils/is-json-primitive.ts

@@ -15,6 +15,10 @@ import isString from './is-string'
  * [1]: https://developer.mozilla.org/docs/Glossary/Primitive
  * [2]: https://restfulapi.net/json-data-types
  *
+ * @see {@linkcode JsonPrimitive}
+ *
+ * @todo examples
+ *
  * @param {unknown} value - Value to check
  * @return {value is JsonPrimitive} `true` if `value` is primitive JSON value
  */

src/utils/is-promise.ts

@@ -0,0 +1,25 @@
+/**
+ * @file Utilities - isPromise
+ * @module tutils/utils/isPromise
+ */
+
+import equal from './equal'
+import isObject from './is-object'
+
+/**
+ * Checks if `value` is a {@linkcode Promise}.
+ *
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+ *
+ * @todo examples
+ *
+ * @template T - Resolved promise type
+ *
+ * @param {unknown} value - Value to check
+ * @return {value is Promise<T>} `true` if `value` is a promise
+ */
+const isPromise = <T>(value: unknown): value is Promise<T> => {
+  return isObject(value) && equal(value.constructor, Promise)
+}
+
+export default isPromise

src/utils/is-undefined.ts

@@ -8,11 +8,13 @@ import equal from './equal'
 /**
  * Checks if `value` is `undefined`.
  *
+ * @todo examples
+ *
  * @param {unknown} value - Value to check
  * @return {value is undefined} `true` if `value` is `undefined`
  */
 const isUndefined = (value: unknown): value is undefined => {
-  return equal(value, undefined)
+  return equal(undefined, value)
 }
 
 export default isUndefined