feat(types): NaN

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

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

@@ -5,6 +5,7 @@
 
 import type EmptyValue from '../empty-value'
 import type TestSubject from '../falsy'
+import type NaN from '../nan'
 
 describe('unit-d:types/Falsy', () => {
   it('should extract 0', () => {
@@ -19,6 +20,10 @@ describe('unit-d:types/Falsy', () => {
     expectTypeOf<TestSubject>().extract<EmptyValue>().not.toBeNever()
   })
 
+  it('should extract NaN', () => {
+    expectTypeOf<TestSubject>().extract<NaN>().not.toBeNever()
+  })
+
   it('should extract false', () => {
     expectTypeOf<TestSubject>().extract<false>().not.toBeNever()
   })

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

@@ -0,0 +1,13 @@
+/**
+ * @file Type Tests - NaN
+ * @module tutils/types/tests/unit-d/NaN
+ */
+
+import type TestSubject from '../nan'
+import type Opaque from '../opaque'
+
+describe('unit-d:types/NaN', () => {
+  it('should equal Opaque<number, "NaN">', () => {
+    expectTypeOf<TestSubject>().toEqualTypeOf<Opaque<number, 'NaN'>>()
+  })
+})

src/types/falsy.ts

@@ -4,6 +4,7 @@
  */
 
 import type EmptyValue from './empty-value'
+import type NaN from './nan'
 
 /**
  * Falsy values union.
@@ -13,10 +14,14 @@ import type EmptyValue from './empty-value'
  * - `''`
  * - `0`
  * - `0n`
+ * - `NaN`
  * - `false`
  * - `null`
  * - `undefined`
+ *
+ * @see {@linkcode EmptyValue}
+ * @see {@linkcode NaN}
  */
-type Falsy = EmptyValue | 0 | 0n | false
+type Falsy = EmptyValue | NaN | 0 | 0n | false
 
 export type { Falsy as default }

src/types/index.ts

@@ -136,6 +136,7 @@ export type { default as Length } from './length'
 export type { default as LiteralUnion } from './literal-union'
 export type { default as Mapper } from './mapper'
 export type { default as Merge } from './merge'
+export type { default as NaN } from './nan'
 export type { default as NIL } from './nil'
 export type { default as Nilable } from './nilable'
 export type { default as Nullable } from './nullable'

src/types/nan.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Type Definitions - NaN
+ * @module tutils/types/NaN
+ */
+
+import type Opaque from './opaque'
+
+/**
+ * A value that is not a number.
+ *
+ * @see {@linkcode Number.NaN}.
+ */
+type NaN = Opaque<number, 'NaN'>
+
+export type { NaN as default }

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

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

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

@@ -5,12 +5,17 @@
 
 import FLOAT from '#fixtures/float'
 import INTEGER from '#fixtures/integer'
+import VEHICLE from '#fixtures/vehicle'
 import testSubject from '../is-nan'
 
 describe('unit:utils/isNaN', () => {
   it('should return false if value is not Number.NaN', () => {
     // Arrange
-    const cases: Parameters<typeof testSubject>[] = [[FLOAT], [INTEGER]]
+    const cases: Parameters<typeof testSubject>[] = [
+      [FLOAT],
+      [INTEGER],
+      [VEHICLE.vin]
+    ]
 
     // Act + Expect
     cases.forEach(([value]) => expect(testSubject(value)).to.be.false)

src/utils/is-nan.ts

@@ -3,6 +3,7 @@
  * @module tutils/utils/isNaN
  */
 
+import type { NaN } from '#src/types'
 import isNumber from './is-number'
 
 /**
@@ -11,8 +12,10 @@ import isNumber from './is-number'
  * @todo examples
  *
  * @param {unknown} value - Value to check
- * @return {boolean} `true` if `value` is `Number.NaN`
+ * @return {value is NaN} `true` if `value` is `Number.NaN`
  */
-const isNaN = (value: unknown): boolean => isNumber(value) && value !== +value
+const isNaN = (value: unknown): value is NaN => {
+  return isNumber(value) && value !== +value
+}
 
 export default isNaN