v_is_empty_value

v_is_empty_value

Simple checker for Empty/NotEmpty values. Checking Numbers, Null, NaN, Strings, Objects, Arrays, Maps, Sets, Symbols, Functions, BigInt, and more. Will also detect instances of Date, Promise, Error, RegExp, typed arrays, and return "not-empty" value for them.

General Information

It provides 4 core functions to check if a value is empty or not, plus a powerful configuration system.

Core Functions

• isEmpty(v, options?) : Checks if a value is empty. Returns true if empty, false otherwise.
• isNotEmpty(v, options?) : Checks if a value is not empty. Returns true if not empty, false otherwise.
• isEmptyNested(v, options?) : Checks if a nested value is empty (recursively checks Objects, Arrays, Maps, Sets). Handles circular references automatically.
• isNotEmptyNested(v, options?) : Checks if a nested value is not empty.

Configuration System

Customize behavior globally or per-call:

• config.get() - Get current configuration
• config.set(newConfig) - Update global configuration
• config.reset() - Reset to defaults
• createCustomChecker(config) - Create isolated checker with custom config

Configuration Options

Option	Default	Description
treatNaNAsEmpty	true	Treat NaN as empty
treatFunctionAsEmpty	true	Treat functions as empty
treatSymbolAsEmpty	true	Treat symbols as empty
treatZeroBigIntAsEmpty	false	Treat 0n as empty
checkCircular	true	Enable circular reference detection
maxNestedDepth	0	Max recursion depth (0 = unlimited)

Base Example

// import { isEmpty, isNotEmpty, isEmptyNested, isNotEmptyNested } from 'v_is_empty_value'
const { isEmpty, isNotEmpty, isEmptyNested, isNotEmptyNested } = require('v_is_empty_value')

isEmpty(v) // Checks if a value is empty.

isNotEmpty(v) // Checks if a value is not empty.

isEmptyNested(v) // Checks if a nested value is empty.

isNotEmptyNested(v) // Checks if a nested value is not empty.

Things it confirms Empty

• Undefined / Empty

console.log(isEmpty()) // prints "true"
console.log(isNotEmpty()) // prints "false"

• Empty String

console.log(isEmpty('')) // prints "true"
console.log(isNotEmpty('')) // prints "false"

• null

console.log(isEmpty(null)) // prints "true"
console.log(isNotEmpty(null)) // prints "false"

• Undefined

console.log(isEmpty(undefined)) // prints "true"
console.log(isNotEmpty(undefined)) // prints "false"

• Empty Object

console.log(isEmpty({})) // prints "true"
console.log(isNotEmpty({})) // prints "false"

• Empty Array

console.log(isEmpty([])) // prints "true"
console.log(isNotEmpty([])) // prints "false"

Few things it confirms NOT Empty

• String with some length/value.

isEmpty('demo_password_123456') // prints "false"
isNotEmpty('demo_password_123456') // prints "true"

• Date instance.

isEmpty(new Date()) // prints "false"
isNotEmpty(new Date()) // prints "true"

• Error instance.

isEmpty(new Error()) // prints "false"
isNotEmpty(new Error()) // prints "true"

• Promise instance.

isEmpty(new Promise((resolve, reject) => resolve(true))) // prints "false"
isNotEmpty(new Promise((resolve, reject) => resolve(true))) // prints "true"

• RegExp instance.

isEmpty(/test/) // prints "false"
isEmpty(new RegExp('test')) // prints "false"

• Number (including 0 and -0).

isEmpty(0) // prints "false"
isEmpty(-0) // prints "false"
isEmpty(42) // prints "false"
isEmpty(Number()) // prints "false" (Number() returns 0)

• Boolean (both true and false).

isEmpty(true) // prints "false"
isEmpty(false) // prints "false"

• BigInt (any value including 0n by default).

isEmpty(BigInt(0)) // prints "false"
isEmpty(BigInt(1)) // prints "false"

• Map/Set with entries.

isEmpty(new Map([['key', 'value']])) // prints "false"
isEmpty(new Set([1, 2, 3])) // prints "false"

• Typed Arrays.

isEmpty(new Uint8Array([1, 2, 3])) // prints "false"

• Nested Object : confirms not empty even though it has empty values (surface check only).

const nestedEmptyObject = {
  demo: null,
  yea: undefined,
  iKnowMan: {
    wtf: null,
    moreNull: null
  }
}

// NOTE: isEmpty() returns "false" because the object has keys.
console.log(isEmpty(nestedEmptyObject)) // prints "false"
console.log(isNotEmpty(nestedEmptyObject)) // prints "true"

// NOTE: Use "isEmptyNested(v)" to recursively check nested values.
console.log(isEmptyNested(nestedEmptyObject)) // prints "true"
console.log(isNotEmptyNested(nestedEmptyObject)) // prints "false"

More Info:
Check the test cases for more examples.

---

Configuration Examples

Global Configuration

Change behavior globally for all subsequent checks:

import { isEmpty, config } from 'v_is_empty_value'

// By default, NaN is treated as empty
isEmpty(NaN) // prints "true"

// Change global config to treat NaN as non-empty
config.set({ treatNaNAsEmpty: false })
isEmpty(NaN) // prints "false"

// Reset to defaults
config.reset()
isEmpty(NaN) // prints "true" again

Per-Call Options

Override configuration for a single call:

import { isEmpty } from 'v_is_empty_value'

// Global default: functions are empty
isEmpty(() => 'test') // prints "true"

// Override for this call only
isEmpty(() => 'test', { treatFunctionAsEmpty: false }) // prints "false"

Custom Checker

Create isolated checkers with different configs:

import { createCustomChecker } from 'v_is_empty_value'

const strictChecker = createCustomChecker({
  treatNaNAsEmpty: false,
  treatFunctionAsEmpty: false,
  treatSymbolAsEmpty: false
})

const looseChecker = createCustomChecker({
  treatZeroBigIntAsEmpty: true
})

// Strict checker
strictChecker.isEmpty(NaN) // false
strictChecker.isEmpty(() => {}) // false

// Loose checker
looseChecker.isEmpty(BigInt(0)) // true

---

� Lodash Drop-in Replacement

While v_is_empty_value defaults to semantically correct behavior, you can configure it to match Lodash's isEmpty() for drop-in compatibility:

import { isEmpty, config } from 'v_is_empty_value'

// Configure to match Lodash behavior
config.set({
  treatNaNAsEmpty: true,           // NaN is empty (same default)
  treatFunctionAsEmpty: false,     // Functions are NOT empty (Lodash style)
  treatSymbolAsEmpty: false,       // Symbols are NOT empty (Lodash style)
  treatZeroBigIntAsEmpty: false,   // 0n is NOT empty (same default)
  nonEmptyTypes: []                // Disable Date/Promise/Error detection
})

// Now behaves like Lodash:
isEmpty(() => {})      // false (Lodash: false)
isEmpty(Symbol())      // false (Lodash: false)
isEmpty(new Date())    // true  (Lodash: true - just checks Object.keys())
isEmpty(new Error())   // true  (Lodash: true)
isEmpty(0)             // false (Lodash: true ⚠️ STILL DIFFERENT!)
isEmpty(false)         // false (Lodash: true ⚠️ STILL DIFFERENT!)

Why We Differ From Lodash

We intentionally differ from Lodash on these cases because we believe they are semantically incorrect:

Value	Lodash	v_is_empty_value	Rationale
0	empty	non-empty	0 is a valid numeric value, not "nothing"
false	empty	non-empty	false is a valid boolean state, not "no data"
new Date()	empty	non-empty	A Date instance represents a timestamp (has value)
new Error()	empty	non-empty	An Error represents an error condition (has value)
new Promise()	empty	non-empty	A Promise represents async state (has internal slots)

Lodash uses Object.keys(value).length for objects, which returns 0 for class instances because their data is stored in internal slots, not enumerable properties. We detect these types via constructor.name and treat them as non-empty because they represent values even without enumerable properties.

Note: You cannot make 0 and false return true with configuration - these are hardcoded as non-empty because treating them as empty is considered a design flaw.

---

� Special Types Reference

Type	Empty Behavior	Configurable
undefined	Empty (true)	No
null	Empty (true)	No
'' (empty string)	Empty (true)	No
NaN	Empty (true)	treatNaNAsEmpty
Symbol	Empty (true)	treatSymbolAsEmpty
Function	Empty (true)	treatFunctionAsEmpty
0	Not empty (false)	No
BigInt(0)	Not empty (false)	treatZeroBigIntAsEmpty
BigInt(n)	Not empty (false)	No
true/false	Not empty (false)	No
Date	Not empty (false)	No
Promise	Not empty (false)	No
Error	Not empty (false)	No
RegExp	Not empty (false)	No
Map (empty)	Empty (true)	No
Map (entries)	Not empty (false)	No
Set (empty)	Empty (true)	No
Set (values)	Not empty (false)	No
WeakMap/WeakSet	Not empty (false)	No
ArrayBuffer	Not empty (false)	No
Typed Arrays	Not empty (false)	No
{} (empty object)	Empty (true)	No
[] (empty array)	Empty (true)	No

---

Circular Reference Handling

isEmptyNested() automatically handles circular references without infinite loops:

import { isEmptyNested } from 'v_is_empty_value'

const obj = { a: null, b: undefined }
obj.self = obj // Circular reference

// This works without hanging!
isEmptyNested(obj) // prints "true" (all values are empty)

const obj2 = { a: 'value' }
obj2.self = obj2 // Circular reference

isEmptyNested(obj2) // prints "false" (has non-empty value)

---

Performance Benchmark

This will basically run the functions mentioned for 25mil. times and will print the time taken for each function to complete.

Test setup

• AMD Ryzen 7 2700X Eight-Core Processor 3.70 GHz
• 16 GB 3000 MHz DDR4
• Patriot P300 256GB M.2 NVMe
• Windows 10 Pro 64-bit
• Node.js v20.10.0

Current performance (vs lodash.isEmpty)

Metric	v_is_empty_value	lodash	Faster
Throughput	23,978,672 ops/sec	3,758,432 ops/sec	6.4x
null	0.89ms	1.27ms	1.4x
empty string	0.72ms	1.88ms	2.6x
number 0	1.63ms	6.75ms	4.1x
NaN	1.86ms	5.34ms	2.9x
empty Map	5.98ms	65.51ms	11.0x
Map with entries	3.36ms	63.26ms	18.8x
empty Set	7.09ms	73.90ms	10.4x
Uint8Array	4.01ms	79.65ms	19.9x
Promise	4.08ms	68.40ms	16.7x
TOTAL	91.75ms	585.35ms	6.4x

Run npm run benchmark to see full comparison.

---

Release Process

For maintainers - steps to publish a new version:

1. Version Bump

   npm version minor  # or patch/major

2. Pre-publish Check (runs lint, build, tests)

   npm run prepack

3. Git Commit & Tag

   git add package.json
   git commit -m "chore: bump version to X.X.X"
   git tag vX.X.X
   git push origin main --tags

4. NPM Publish

   npm publish

5. GitHub Release (Recommended)

   • Go to GitHub repository → Releases → "Draft a new release"

   • Click "Choose a tag" and select vX.X.X

   • Release title: vX.X.X - Brief description

   • Release notes:

     ## Changes
     - Feature/fix description
     - Performance improvements
     - Bug fixes
     
     ## Breaking Changes (if any)
     - Migration notes

   • Attach build artifacts from dist/ folder (optional)

   • Click "Publish release"

---

Related links :

• v_to_md5 MD5 hash generator
• v_to_sha256 sha256 hash generator
• v_file_system simple and safe fs module with sync and promises
• v_execute Exec cli commands
• v_scrolls Readme Generator
• v_database single database solution
• v_database_cli v_database cli tool