feat: add isTruthy, isFalsy, and isEmpty utils

.changeset/fruity-feet-taste.md

@@ -0,0 +1,11 @@
+---
+'@js-utils-kit/valid': minor
+---
+
+Add `isTruthy`, `isFalsy`, and `isEmpty` utility functions.
+
+### Added
+
+- `isTruthy` – Checks whether a value is truthy, with explicit handling for `NaN`.
+- `isFalsy` – Checks whether a value is falsy, including `NaN`.
+- `isEmpty` – Checks for empty values across common data types (strings, arrays, objects, Maps, and Sets).

packages/valid/src/index.ts

@@ -8,7 +8,9 @@ export * from './isCamelCase';
 export * from './isDefined';
 export * from './isDev';
 export * from './isEmail';
+export * from './isEmpty';
 export * from './isEmptyObject';
+export * from './isFalsy';
 export * from './isKebabCase';
 export * from './isLowerCase';
 export * from './isNode';
@@ -21,6 +23,7 @@ export * from './isProd';
 export * from './isSnakeCase';
 export * from './isString';
 export * from './isTest';
+export * from './isTruthy';
 export * from './isUndefinedOrNull';
 export * from './isUpperCase';
 export * from './isURL';

packages/valid/src/isEmpty.ts

@@ -0,0 +1,55 @@
+/**
+ * Checks whether a value is empty.
+ *
+ * Empty values include:
+ * - `null` or `undefined`
+ * - Empty strings (including whitespace-only strings)
+ * - Arrays with length `0`
+ * - Objects with no own enumerable properties
+ * - Maps and Sets with size `0`
+ *
+ * @returns `true` if the value is empty, otherwise `false`
+ *
+ * @example
+ * ```ts
+ * isEmpty(null);        // true
+ * isEmpty('');          // true
+ * isEmpty('   ');       // true
+ * isEmpty([]);          // true
+ * isEmpty({});          // true
+ * isEmpty(new Map());  // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * isEmpty('hello');    // false
+ * isEmpty([1]);        // false
+ * isEmpty({ a: 1 });   // false
+ * ```
+ */
+export function isEmpty<T>(
+  /**
+   * The value to check.
+   */
+  value: T,
+): boolean {
+  if (value == null) return true;
+
+  if (typeof value === 'string') {
+    return value.trim().length === 0;
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+
+  if (value instanceof Map || value instanceof Set) {
+    return value.size === 0;
+  }
+
+  if (Object.prototype.toString.call(value) === '[object Object]') {
+    return Object.keys(value).length === 0;
+  }
+
+  return false;
+}

packages/valid/src/isFalsy.ts

@@ -0,0 +1,38 @@
+/**
+ * Checks whether a value is falsy.
+ *
+ * Falsy values include:
+ * - `false`
+ * - `0`
+ * - `""`
+ * - `null`
+ * - `undefined`
+ * - `NaN`
+ *
+ * @returns `true` if the value is falsy, otherwise `false`
+ *
+ * @example
+ * ```ts
+ * isFalsy(0);        // true
+ * isFalsy('');       // true
+ * isFalsy(null);     // true
+ * isFalsy(undefined);// true
+ * isFalsy(NaN);      // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * isFalsy(1);        // false
+ * isFalsy('hello');  // false
+ * isFalsy([]);  // false
+ * isFalsy({});  // false
+ * ```
+ */
+export function isFalsy<T>(
+  /**
+   * The value to check.
+   */
+  value: T,
+): boolean {
+  return !value;
+}

packages/valid/src/isTruthy.ts

@@ -0,0 +1,38 @@
+/**
+ * Checks whether a value is truthy.
+ *
+ * Falsy values include:
+ * - `false`
+ * - `0`
+ * - `""` (empty string)
+ * - `null`
+ * - `undefined`
+ * - `NaN`
+ *
+ * @returns `true` if the value is truthy, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * isTruthy(0);         // false
+ * isTruthy('');        // false
+ * isTruthy(null);      // false
+ * isTruthy(undefined); // false
+ * isTruthy(NaN);       // false
+ * ```
+ *
+ * @example
+ * ```ts
+ * isTruthy(1);         // true
+ * isTruthy('hello');   // true
+ * isTruthy([]);        // true
+ * isTruthy({});        // true
+ * ```
+ */
+export function isTruthy<T>(
+  /**
+   * The value to check.
+   */
+  value: T,
+): boolean {
+  return Boolean(value);
+}

packages/valid/test/isEmpty.test.ts

@@ -0,0 +1,72 @@
+import { it, expect } from 'vitest';
+import { isEmpty } from '../src';
+
+it('returns true for null and undefined', () => {
+  expect(isEmpty(null)).toBe(true);
+  expect(isEmpty(undefined)).toBe(true);
+});
+
+it('returns true for empty strings', () => {
+  expect(isEmpty('')).toBe(true);
+});
+
+it('returns true for whitespace-only strings', () => {
+  expect(isEmpty(' ')).toBe(true);
+  expect(isEmpty('   ')).toBe(true);
+  expect(isEmpty('\n\t')).toBe(true);
+});
+
+it('returns false for non-empty strings', () => {
+  expect(isEmpty('hello')).toBe(false);
+  expect(isEmpty('  hello  ')).toBe(false);
+});
+
+it('returns true for empty arrays', () => {
+  expect(isEmpty([])).toBe(true);
+});
+
+it('returns false for non-empty arrays', () => {
+  expect(isEmpty([1])).toBe(false);
+  expect(isEmpty([0])).toBe(false);
+  expect(isEmpty([''])).toBe(false);
+});
+
+it('returns true for empty objects', () => {
+  expect(isEmpty({})).toBe(true);
+});
+
+it('returns false for objects with properties', () => {
+  expect(isEmpty({ a: 1 })).toBe(false);
+  expect(isEmpty({ a: undefined })).toBe(false);
+});
+
+it('returns true for empty Map and Set', () => {
+  expect(isEmpty(new Map())).toBe(true);
+  expect(isEmpty(new Set())).toBe(true);
+});
+
+it('returns false for non-empty Map and Set', () => {
+  const map = new Map();
+  map.set('key', 'value');
+
+  const set = new Set();
+  set.add(1);
+
+  expect(isEmpty(map)).toBe(false);
+  expect(isEmpty(set)).toBe(false);
+});
+
+it('returns false for numbers and booleans', () => {
+  expect(isEmpty(0)).toBe(false);
+  expect(isEmpty(1)).toBe(false);
+  expect(isEmpty(false)).toBe(false);
+  expect(isEmpty(true)).toBe(false);
+});
+
+it('returns false for functions', () => {
+  expect(isEmpty(() => {})).toBe(false);
+});
+
+it('returns false for dates', () => {
+  expect(isEmpty(new Date())).toBe(false);
+});

packages/valid/test/isFalsy.test.ts

@@ -0,0 +1,60 @@
+import { it, expect } from 'vitest';
+import { isFalsy } from '../src';
+
+it('returns true for false', () => {
+  expect(isFalsy(false)).toBe(true);
+});
+
+it('returns true for zero', () => {
+  expect(isFalsy(0)).toBe(true);
+  expect(isFalsy(-0)).toBe(true);
+  expect(isFalsy(0n)).toBe(true);
+});
+
+it('returns true for empty string', () => {
+  expect(isFalsy('')).toBe(true);
+});
+
+it('returns true for null and undefined', () => {
+  expect(isFalsy(null)).toBe(true);
+  expect(isFalsy(undefined)).toBe(true);
+});
+
+it('returns true for NaN', () => {
+  expect(isFalsy(NaN)).toBe(true);
+  // sanity check
+  expect(Number.isNaN(NaN)).toBe(true);
+});
+
+it('returns false for truthy numbers', () => {
+  expect(isFalsy(1)).toBe(false);
+  expect(isFalsy(-1)).toBe(false);
+  expect(isFalsy(42)).toBe(false);
+});
+
+it('returns false for non-empty strings', () => {
+  expect(isFalsy('hello')).toBe(false);
+  expect(isFalsy(' ')).toBe(false); // whitespace is truthy
+});
+
+it('returns false for arrays', () => {
+  expect(isFalsy([])).toBe(false);
+  expect(isFalsy([0])).toBe(false);
+});
+
+it('returns false for objects', () => {
+  expect(isFalsy({})).toBe(false);
+  expect(isFalsy({ a: 1 })).toBe(false);
+});
+
+it('returns false for functions', () => {
+  expect(isFalsy(() => {})).toBe(false);
+});
+
+it('returns false for symbols', () => {
+  expect(isFalsy(Symbol('test'))).toBe(false);
+});
+
+it('returns false for BigInt values', () => {
+  expect(isFalsy(1n)).toBe(false);
+});

packages/valid/test/isTruthy.test.ts

@@ -0,0 +1,55 @@
+import { it, expect } from 'vitest';
+import { isTruthy } from '../src';
+
+it('returns false for falsy primitives', () => {
+  expect(isTruthy(false)).toBe(false);
+  expect(isTruthy(0)).toBe(false);
+  expect(isTruthy(0n)).toBe(false);
+  expect(isTruthy('')).toBe(false);
+  expect(isTruthy(null)).toBe(false);
+  expect(isTruthy(undefined)).toBe(false);
+});
+
+it('returns false for NaN', () => {
+  expect(isTruthy(NaN)).toBe(false);
+  expect(Number.isNaN(NaN)).toBe(true);
+});
+
+it('returns true for truthy numbers', () => {
+  expect(isTruthy(1)).toBe(true);
+  expect(isTruthy(-1)).toBe(true);
+  expect(isTruthy(42)).toBe(true);
+});
+
+it('returns true for non-empty strings', () => {
+  expect(isTruthy('hello')).toBe(true);
+  expect(isTruthy(' ')).toBe(true);
+});
+
+it('returns true for arrays', () => {
+  expect(isTruthy([])).toBe(true);
+  expect(isTruthy([0])).toBe(true);
+});
+
+it('returns true for objects', () => {
+  expect(isTruthy({})).toBe(true);
+  expect(isTruthy({ a: 1 })).toBe(true);
+});
+
+it('returns true for functions', () => {
+  expect(isTruthy(() => {})).toBe(true);
+});
+
+it('returns true for symbols', () => {
+  expect(isTruthy(Symbol('test'))).toBe(true);
+});
+
+it('returns true for BigInt values', () => {
+  expect(isTruthy(1n)).toBe(true);
+});
+
+it('returns true for truthy exotic objects', () => {
+  expect(isTruthy(new Date())).toBe(true);
+  expect(isTruthy(new Map())).toBe(true);
+  expect(isTruthy(new Set())).toBe(true);
+});