diff --git a/src/isUndefined.bench.ts b/src/isUndefined.bench.ts new file mode 100644 index 0000000..206a3cc --- /dev/null +++ b/src/isUndefined.bench.ts @@ -0,0 +1,26 @@ +import _isUndefined from 'lodash/isUndefined' +import {bench, describe} from 'vitest' + +import {isUndefined} from './isUndefined' + +const testCases = [null, 0, '', false, {}, [], 'undefined', NaN] + +const ITERATIONS = 1000 + +describe('isUndefined performance', () => { + bench('hidash', () => { + for (let i = 0; i < ITERATIONS; i++) { + testCases.forEach((testCase) => { + isUndefined(testCase) + }) + } + }) + + bench('lodash', () => { + for (let i = 0; i < ITERATIONS; i++) { + testCases.forEach((testCase) => { + _isUndefined(testCase) + }) + } + }) +}) diff --git a/src/isUndefined.test.ts b/src/isUndefined.test.ts new file mode 100644 index 0000000..4b218c2 --- /dev/null +++ b/src/isUndefined.test.ts @@ -0,0 +1,51 @@ +import _isUndefined from 'lodash/isUndefined' +import {expect, describe, it} from 'vitest' + +import {isUndefined} from './isUndefined' + +describe('isUndefined - direct behavior', () => { + it('returns true for undefined', () => { + expect(isUndefined(undefined)).toBe(true) + }) + + it('returns false for null', () => { + expect(isUndefined(null)).toBe(false) + }) + + it('returns false for 0', () => { + expect(isUndefined(0)).toBe(false) + }) + + it('returns false for empty string', () => { + expect(isUndefined('')).toBe(false) + }) + + it('returns false for false', () => { + expect(isUndefined(false)).toBe(false) + }) + + it('returns false for empty object', () => { + expect(isUndefined({})).toBe(false) + }) + + it('returns false for empty array', () => { + expect(isUndefined([])).toBe(false) + }) + + it('returns false for "undefined" string', () => { + expect(isUndefined('undefined')).toBe(false) + }) + + it('returns false for NaN', () => { + expect(isUndefined(NaN)).toBe(false) + }) +}) + +describe('isUndefined - lodash parity', () => { + it('matches lodash for various defined values', () => { + const testCases = [null, 0, '', false, {}, [], 'undefined', NaN] + testCases.forEach((value) => { + expect(isUndefined(value)).toBe(_isUndefined(value)) + }) + }) +}) diff --git a/src/isUndefined.ts b/src/isUndefined.ts index f404885..8aa8088 100644 --- a/src/isUndefined.ts +++ b/src/isUndefined.ts @@ -1,3 +1,23 @@ +/** + * Checks whether the given value is strictly `undefined`. + * + * This function returns `true` only if the input is exactly `undefined`, and `false` for all other values, + * including `null`, `0`, `false`, empty strings, and other falsy values. + * + * It also serves as a TypeScript type guard, narrowing the type of the input to `undefined` when true. + * + * @param value - The value to check. + * @returns Whether the value is `undefined`. + * + * @example + * const a = undefined; + * const b = null; + * const c = 0; + * + * console.log(isUndefined(a)); // true + * console.log(isUndefined(b)); // false + * console.log(isUndefined(c)); // false + */ export function isUndefined(value: unknown): value is undefined { return value === undefined }