@przeslijmi/is-empty

Modern, TypeScript-friendly utility for checking whether a value is empty — the spiritual successor to the old is-empty npm package. It includes configuration options, type safety, and helper aliases for common patterns.

Using all options set to their default values, this package behaves exactly like the original is-empty package — just modernized for today’s JavaScript and TypeScript environments.

🚀 Installation

npm install @przeslijmi/is-empty

🧩 Usage

Basic example

import { isEmpty } from '@przeslijmi/is-empty';

isEmpty(null);        // true
isEmpty(undefined);   // true
isEmpty('');          // true
isEmpty('text');      // false
isEmpty([]);          // true
isEmpty({});          // true
isEmpty([1]);         // false

⚙️ Options

You can globally or per-call control behavior through the IsEmptyOptions interface.

import { setIsEmptyOptions, isEmpty } from '@przeslijmi/is-empty';

setIsEmptyOptions({ treatSpacesAsEmpty: true });

isEmpty(' '); // true (because of global config)
isEmpty(' ', { treatSpacesAsEmpty: false }); // false (per-call override)

Available options

| Option | Type | Default | Description | |--------------------------------|-----------|---------|-------------| | treatBooleanAsNonEmpty | boolean | true | When true, boolean values (true / false) are always treated as non-empty. | | treatSpaceAsEmpty | boolean | false | When true, strings containing only whitespace (e.g. " ") are considered empty. | | treatZeroAsEmpty | boolean | false | When true, numeric 0 and string "0" are treated as empty. | | treatNumericStringsAsNumbers | boolean | false | When true, numeric-looking strings (e.g. "42", "3.14") are treated as numbers instead of strings. | | testArraysRecursively | boolean | true | When true, arrays are checked recursively — e.g. [[]] or [null] are considered empty. | | testFunctionsBody | boolean | true | When true, functions are analyzed to determine if their body is empty (e.g. function() {} or () => {}). |

You can also pass Partial<IsEmptyOptions> so only the options you specify are overridden.

🧠 Helper functions

import {
  isEmpty,
  isNotEmpty,
  empty,
  notEmpty,
  undefinedIfEmpty,
} from '@przeslijmi/is-empty';

isNotEmpty(value, options?)

Inverse of isEmpty.

isNotEmpty('abc'); // true

empty(value, options?) and notEmpty(value, options?)

Alias helpers — same logic, different naming preferences.

undefinedIfEmpty<T>(value, options?)

Returns undefined if value is empty, otherwise returns it typed as T.

undefinedIfEmpty('');     // undefined
undefinedIfEmpty('text'); // 'text'

That is especially usefull in chained calls:

const name = undefinedIfEmpty(formData.name) ?? 'Default Name';

🧪 Testing

This package is fully tested with Vitest.

Run tests:

npm test

Example coverage includes:

• Handling of null, undefined, empty strings, arrays, and objects
• Configurable behavior for whitespace strings
• Function detection (including empty functions)
• Aliases and numeric conversion helpers

🧾 Versioning

This project follows Semantic Versioning (SemVer):

• MAJOR version → breaking changes
• MINOR version → new features, backward compatible
• PATCH version → bug fixes and small improvements

All versions are published and tagged on npm and GitHub Releases.

📜 License

MIT © Karol Nowakowski

Visit my website: Let's create