feat: ✨ Add isEmpty helper

Author: baxyz

helpers/type/isEmpty.test.ts

@@ -0,0 +1,57 @@
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { describe, expect, it } from 'vitest';
+import { isEmpty } from './isEmpty';
+
+describe('isEmpty', () => {
+  it('should treat null and undefined as empty', () => {
+    expect(isEmpty(null)).toBe(true);
+    expect(isEmpty(undefined)).toBe(true);
+  });
+
+  it('should handle strings', () => {
+    expect(isEmpty('')).toBe(true);
+    expect(isEmpty(' ')).toBe(false);
+    expect(isEmpty('text')).toBe(false);
+  });
+
+  it('should handle arrays', () => {
+    expect(isEmpty([])).toBe(true);
+    expect(isEmpty([1])).toBe(false);
+  });
+
+  it('should handle plain objects', () => {
+    expect(isEmpty({})).toBe(true);
+    expect(isEmpty({ a: 1 })).toBe(false);
+  });
+
+  it('should handle objects with null prototype', () => {
+    const obj = Object.create(null) as Record<string, unknown>;
+    expect(isEmpty(obj)).toBe(true);
+    obj.key = 'value';
+    expect(isEmpty(obj)).toBe(false);
+  });
+
+  it('should handle Map and Set', () => {
+    expect(isEmpty(new Map())).toBe(true);
+    expect(isEmpty(new Set())).toBe(true);
+    expect(isEmpty(new Map([['key', 'value']]))).toBe(false);
+    expect(isEmpty(new Set([1]))).toBe(false);
+  });
+
+  it('should return false for special objects', () => {
+    expect(isEmpty(new Date())).toBe(false);
+    class Example {}
+    expect(isEmpty(new Example())).toBe(false);
+  });
+
+  it('should return false for numbers, booleans and functions', () => {
+    expect(isEmpty(0)).toBe(false);
+    expect(isEmpty(false)).toBe(false);
+    expect(isEmpty(() => undefined)).toBe(false);
+  });
+});

helpers/type/isEmpty.ts

@@ -0,0 +1,59 @@
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { isSpecialObject } from './isSpecialObject';
+
+/**
+ * Checks if a value is empty.
+ *
+ * Supported types:
+ * - `null` / `undefined` → empty
+ * - `string` → length === 0
+ * - `array` → length === 0
+ * - `Map` / `Set` → size === 0
+ * - plain object → no own enumerable properties
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is considered empty, `false` otherwise
+ *
+ * @example
+ * isEmpty('') // true
+ * isEmpty([]) // true
+ * isEmpty({}) // true
+ * isEmpty('foo') // false
+ */
+export function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  if (typeof value === 'string') {
+    return value.length === 0;
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+
+  if (value instanceof Map || value instanceof Set) {
+    return value.size === 0;
+  }
+
+  if (typeof value === 'object') {
+    if (isSpecialObject(value)) {
+      return false;
+    }
+
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      return false;
+    }
+
+    return Object.keys(value as Record<string, unknown>).length === 0;
+  }
+
+  return false;
+}