feat(guards): isEmptyValue

.eslintrc.base.cjs

@@ -253,6 +253,21 @@ module.exports = {
       files: ['**/*.md/*.ts'],
       parser: require.resolve('@typescript-eslint/parser')
     },
+    {
+      files: ['**/*.spec.ts'],
+      env: {
+        jest: true
+      },
+      extends: ['plugin:jest/recommended'],
+      globals: {
+        'jest/globals': true
+      },
+      rules: {
+        'jest/no-disabled-tests': 0,
+        'jest/valid-title': 0,
+        'unicorn/consistent-function-scoping': 0
+      }
+    },
     {
       files: ['**/.eslintrc.*'],
       rules: {

src/guards/__tests__/is-empty-value.guard.functional.spec.ts

@@ -0,0 +1,62 @@
+import type { Testcase } from '@tests/utils/types'
+import * as isEmptyString from '../is-empty-string.guard'
+import testSubject from '../is-empty-value.guard'
+import * as isNIL from '../is-nil.guard'
+
+/**
+ * @file Unit Tests - isEmptyValue
+ * @module tutils/guards/tests/unit/isEmptyValue
+ */
+
+describe('unit:guards/isEmptyValue', () => {
+  const spyIsEmptyString = jest.spyOn(isEmptyString, 'default')
+  const spyIsNIL = jest.spyOn(isNIL, 'default')
+
+  type Case = Testcase<{ isEmptyString: number; isNIL: number }> & {
+    state: string
+    value: any
+  }
+
+  const cases: Case[] = [
+    {
+      expected: { isEmptyString: 1, isNIL: 1 },
+      state: 'undefined',
+      value: undefined
+    },
+    {
+      expected: { isEmptyString: 1, isNIL: 0 },
+      state: 'empty string (trimmed)',
+      value: ''
+    },
+    {
+      expected: { isEmptyString: 1, isNIL: 0 },
+      state: 'empty string (untrimmed)',
+      value: '   '
+    },
+    {
+      expected: { isEmptyString: 1, isNIL: 1 },
+      state: 'null',
+      value: null
+    },
+    {
+      expected: { isEmptyString: 1, isNIL: 1 },
+      state: 'undefined',
+      value: undefined
+    }
+  ]
+
+  for (const { expected, state, value } of cases) {
+    const times = (num: number) => `${num} time${num === 1 ? '' : 's'}`
+    const state1 = `isEmptyString ${times(expected.isEmptyString)}`
+    const state2 = `isNIL ${times(expected.isNIL)}`
+
+    it(`should call ${state1} and ${state2} given ${state}`, () => {
+      // Act
+      testSubject(value)
+
+      // Expect
+      expect(spyIsEmptyString).toBeCalledTimes(expected.isEmptyString)
+      expect(spyIsNIL).toBeCalledTimes(expected.isNIL)
+    })
+  }
+})

src/guards/index.ts

@@ -5,5 +5,6 @@
 
 export { default as isBooleanish } from './is-booleanish.guard'
 export { default as isEmptyString } from './is-empty-string.guard'
+export { default as isEmptyValue } from './is-empty-value.guard'
 export { default as isNIL } from './is-nil.guard'
 export { default as isNodeEnv } from './is-node-env.guard'

src/guards/is-empty-value.guard.ts

@@ -0,0 +1,20 @@
+import { EmptyValue } from '@tutils/types'
+import isEmptyString from './is-empty-string.guard'
+import isNIL from './is-nil.guard'
+
+/**
+ * @file Type Guards - isEmptyValue
+ * @module tutils/guards/isEmptyValue
+ */
+
+/**
+ * Checks if `value` is an empty string or `NIL`.
+ *
+ * @param {any} [value] - Value to check
+ * @return {boolean} `true` if `value` is an empty string or `NIL`
+ */
+const isEmptyValue = (value?: any): value is EmptyValue => {
+  return isEmptyString(value) || isNIL(value)
+}
+
+export default isEmptyValue

src/types/empty-value.type.ts

@@ -1,3 +1,4 @@
+import type EmptyString from './empty-string.type'
 import type NIL from './nil.type'
 
 /**
@@ -8,6 +9,6 @@ import type NIL from './nil.type'
 /**
  * Type representing `null`, `undefined`, and empty strings.
  */
-type EmptyValue = NIL | ''
+type EmptyValue = NIL | EmptyString
 
 export default EmptyValue