feat: add isNullish function (#277)

.github/next-minor.md

@@ -8,6 +8,10 @@ The `####` headline should be short and descriptive of the new functionality. In
 
 https://github.com/radashi-org/radashi/pull/239
 
+#### isNullish
+
+https://github.com/radashi-org/radashi/pull/277
+
 ## New Features
 
 #### Add `signal` option to `retry`

benchmarks/typed/isNullish.bench.ts

@@ -0,0 +1,23 @@
+import * as _ from 'radashi'
+
+describe('isNullish', () => {
+  bench('with null', () => {
+    _.isNullish(null)
+  })
+
+  bench('with undefined', () => {
+    _.isNullish(undefined)
+  })
+
+  bench('with number', () => {
+    _.isNullish(0)
+  })
+
+  bench('with string', () => {
+    _.isNullish('')
+  })
+
+  bench('with array', () => {
+    _.isNullish([])
+  })
+})

docs/typed/isNullish.mdx

@@ -0,0 +1,19 @@
+---
+title: isNullish
+description: Determine if a value is null or undefined
+since: 12.2.0
+---
+
+### Usage
+
+Pass in a value and get a boolean telling you if the value is null or undefined.
+
+```ts
+import * as _ from 'radashi'
+
+_.isNullish(null) // => true
+_.isNullish(undefined) // => true
+_.isNullish('') // => false
+_.isNullish([]) // => false
+_.isNullish(0) // => false
+```

src/mod.ts

@@ -120,6 +120,7 @@ export * from './typed/isInt.ts'
 export * from './typed/isIntString.ts'
 export * from './typed/isIterable.ts'
 export * from './typed/isMap.ts'
+export * from './typed/isNullish.ts'
 export * from './typed/isNumber.ts'
 export * from './typed/isObject.ts'
 export * from './typed/isPlainObject.ts'

src/typed/isNullish.ts

@@ -0,0 +1,16 @@
+/**
+ * Return true if the given value is null or undefined.
+ *
+ * @see https://radashi.js.org/reference/typed/isNullish
+ * @example
+ * ```ts
+ * isNullish(null) // => true
+ * isNullish(undefined) // => true
+ * isNullish('') // => false
+ * isNullish(0) // => false
+ * ```
+ * @version 12.2.0
+ */
+export function isNullish(value: unknown): value is null | undefined {
+  return value === null || value === undefined
+}

tests/typed/isNullish.test-d.ts

@@ -0,0 +1,52 @@
+import * as _ from 'radashi'
+
+describe('isNullish return type', () => {
+  test('value is any', () => {
+    const value = {} as any
+    if (_.isNullish(value)) {
+      expectTypeOf(value).toEqualTypeOf<null | undefined>()
+    } else {
+      expectTypeOf(value).toEqualTypeOf<any>()
+    }
+  })
+  test('value is unknown', () => {
+    const value = {} as unknown
+    if (_.isNullish(value)) {
+      expectTypeOf(value).toEqualTypeOf<null | undefined>()
+    } else {
+      expectTypeOf(value).toEqualTypeOf<unknown>()
+    }
+  })
+  test('value is never', () => {
+    const value = {} as never
+    if (_.isNullish(value)) {
+      expectTypeOf(value).toEqualTypeOf<never>()
+    } else {
+      expectTypeOf(value).toEqualTypeOf<never>()
+    }
+  })
+  test('value is string', () => {
+    const value = {} as string
+    if (_.isNullish(value)) {
+      expectTypeOf(value).toEqualTypeOf<never>()
+    } else {
+      expectTypeOf(value).toEqualTypeOf<string>()
+    }
+  })
+  test('value is number', () => {
+    const value = {} as number
+    if (_.isNullish(value)) {
+      expectTypeOf(value).toEqualTypeOf<never>()
+    } else {
+      expectTypeOf(value).toEqualTypeOf<number>()
+    }
+  })
+  test('value is any[]', () => {
+    const value = {} as any[]
+    if (_.isNullish(value)) {
+      expectTypeOf(value).toEqualTypeOf<never>()
+    } else {
+      expectTypeOf(value).toEqualTypeOf<any[]>()
+    }
+  })
+})

tests/typed/isNullish.test.ts

@@ -0,0 +1,36 @@
+import * as _ from 'radashi'
+
+describe('isNullish', () => {
+  test('returns true for null', () => {
+    const result = _.isNullish(null)
+    expect(result).toBeTruthy()
+  })
+  test('returns true for undefined', () => {
+    const result = _.isNullish(undefined)
+    expect(result).toBeTruthy()
+  })
+  test('returns false for boolean', () => {
+    const result = _.isNullish(false)
+    expect(result).toBeFalsy()
+  })
+  test('returns false for number', () => {
+    const result = _.isNullish(0)
+    expect(result).toBeFalsy()
+  })
+  test('returns false for NaN', () => {
+    const result = _.isNullish(Number.NaN)
+    expect(result).toBeFalsy()
+  })
+  test('returns false for array', () => {
+    const result = _.isNullish([])
+    expect(result).toBeFalsy()
+  })
+  test('returns false for object', () => {
+    const result = _.isNullish({})
+    expect(result).toBeFalsy()
+  })
+  test('returns false for string', () => {
+    const result = _.isNullish('')
+    expect(result).toBeFalsy()
+  })
+})