is.js

Extremely lightweight, zero dependency variable checks missing in nodeJS but common in other languages.

is.nullOrEmpty(input: any): boolean
is.string(input: any): boolean;

Install @kj4ezj/is from NPM with your preferred package manager!

1. Background
2. Usage
   1. is.nullOrEmpty()
   2. is.string()
3. Development
   1. Prerequisites
   2. Initialization
   3. Lint
   4. Test
   5. Build
   6. Upgrade
   7. Reset
   8. CI
4. See Also

Background

In the old days™, nodeJS lacked most utilities developers take for granted in other languages. The community created libraries like lodash (commonly imported and used as _ in projects) to fill this void. However, modern node includes intrinsics that provide almost all of the functionality these large libraries were built to provide. It seems silly to import a 1.4 MB library just to test if a variable is empty.

The is.js library provides the most fundamental utilities remaining absent in modern node that I expect to have in any language, and nothing more. At the time of writing, is.js weighs in at just 461 bytes, five orders of magnitude smaller than lodash!

Usage

Install @kj4ezj/is from NPM with your preferred package manager...

bun add @kj4ezj/is
cnpm install @kj4ezj/is
npm install @kj4ezj/is
pnpm add @kj4ezj/is
yarn add @kj4ezj/is

...then import it into your source code.

const is = require('@kj4ezj/is');

Two utilities are provided.

is.nullOrEmpty(input: any): boolean
is.string(input: any): boolean;

These are documented in the sections below, but the test cases written against expectations should be considered authoritative.

is.nullOrEmpty()

This is a simple variable emptiness check. Pass it literally anything and it will return true if it is undefined, null, or empty; and false otherwise.

is.nullOrEmpty(input: any): boolean

Emptiness is considered in a practical sense, and may be slightly different than implementations in other languages.

// literals
undefined
null
[]          // zero-length arrays
[[]]        // zero-length multi-dimension arrays
{}          // empty objects
''          // equivalent to "" or ``
' '         // strings containing only whitespace
'    \n\t'

// primitive objects
Array([])
Object({})
String(' \n ')

// constructed objects
new Array([])
new Array([[]])
new Object({})
new String(' \n ')

// literals
true
false
-1
0
123
0xFFFF00
0b00101010
'yeet'
[[],[]]  // non-zero array length
['one', 'two', 'three']
{key: 'value'}

// primitive types
Boolean(false)
Number(0)
BigInt(81129638414606663681390495662081)

// constructed types
new Boolean(false)
new Number(0)
new String('yeet')
new Array([[],[]])
new Object({key: 'value'})

// functions, no matter the return type or contents
() => undefined
() => null
() => false
() => 0
() => ''
() => []
() => {}
() => new Number(0)
() => new String('')

See the test cases written against expectations for more info, or try it in an interactive shell.

is.string()

JavaScript has two different types of strings:

1. String primitives - '', "", ``, String(), and String('')
2. String objects - new String()

These are two different types, even though JavaScript pretends not to have types. String primitives are fundamentally immutable literals of type string, while string objects are fundamentally type Object of class String.

[!TIP]
JavaScript hides this from you using autoboxing. When you access a property or method on a string primitive, JavaScript temporarily converts (or "boxes") the string primitive into a String object. This allows the string primitive to access the properties and methods available on String.prototype. Once the property or method is accessed, the temporary String object is discarded, and the original string primitive remains unchanged.

This makes it complicated for programmers to determine if a variable is a string because String objects are not strings.

Most of the time we do not care about the internal mechanics of the language, we just want to know if a variable contains a string in a practical sense.

is.string()             // false
is.string(undefined)    // false
is.string(null)         // false
is.string('')           // TRUE
is.string(' ')          // TRUE
is.string('yeet')       // TRUE
is.string('    \n\t')   // TRUE
is.string([])           // false
is.string({})           // false

is.string(String(''))                   // TRUE
is.string(Array([]))                    // false
is.string(Array(['yeet']))              // false
is.string(Object({}))                   // false
is.string(Object({key: 'value'}))       // false

is.string(new String(''))               // TRUE
is.string(new Array([]))                // false
is.string(new Array(['yeet']))          // false
is.string(new Object({}))               // false
is.string(new Object({key: 'value'}))   // false

is.string(() => undefined)              // false
is.string(() => null)                   // false
is.string(() => '')                     // false
is.string(() => new String(''))         // false
is.string(() => new String('yeet'))     // false

See the test cases written against expectations for more info, or try it in an interactive shell.

Development

Start here to contribute to this repo.

[!NOTE]
The source of truth for the version of nodeJS this project uses is the .nvmrc file. As a utility, as many versions of node are supported as possible on a best-effort basis. Check out the node-version key in the ci.yml to see which versions are being tested.

Prerequisites

Contributors will need the following tools:

• act
  • docker - required by act
    • Docker Desktop is not required, you only need the free Docker Engine.
• nvm
• nodeJS
  Install node using nvm. In the root of this repo:

  nvm install

  This will automagically install and use the correct version of node for this project, as defined in the .nvmrc file.
• yarn version 1
  The easiest way to install this is using npm, which is installed with node by nvm.

  npm install --global yarn

These tools are all you need to get started!

Initialization

Once you have the prerequisites installed, you can get going by navigating to the root of this repo, making sure nvm is using the correct version of nodeJS...

nvm install

...then downloading all project dependencies.

yarn

Easy.

Lint

This project uses eslint with customizations on top of the airbnb-base config to perform static code analysis.

yarn lint

The purpose of linting is to catch bugs early, not to create unnecessary friction, so many rules which will not realistically catch bugs are disabled.

Test

This project uses the jest test framework.

yarn test

The goal is full test coverage, not to chase a number but to exhaustively test all expectations.

Build

This is how release artifacts are generated and, in CI, published.

yarn build

The "build" command calls scripts/build.sh, which packs build metadata into the package.json under the top-level git key and calls npm pack to generate a *.tgz file for distribution. If this script is called in a CI environment then it will continue on to install the newly generated package to validate it can be installed, per NPM's instructions. In a tagged build, it will verify that the tag matches the version string in the package.json and publish it to NPM with provenance.

Upgrade

[!CAUTION] ESLint 9 introduced numerous breaking changes including dropping support for node 14, 16, breaking eslint-config-airbnb-base, and breaking my configuration.

Upgrade dependencies in the yarn.lock only.

yarn upgrade

Upgrade both the yarn.lock and the package.json.

yarn upgrade --latest

Run yarn act after either to verify the upgraded dependencies work with the project on all supported nodeJS versions.

Reset

This project contains a script to sanitize the project's node environment.

[!WARNING]
This will delete build artifacts!

yarn reset

This makes it easy to switch between node major versions cleanly.

CI

This project uses GitHub Actions for CI.

• is.js CICD - initialize, lint, and test, and publish the is.js project.
  • Pipeline
  • Documentation

You can run the GitHub Actions workflow(s) locally using act.

yarn act

Please make sure your changes do not break act compatibility.

See Also

• CI
  • Pipeline
  • Documentation
• Tooling
  • act - run GitHub Actions locally
  • docker
  • eslint
    • airbnb-base
  • jest
  • nvm
  • nodeJS
  • yarn

Legal Notice
This repo contains assets created in collaboration with a large language model, machine learning algorithm, or weak artificial intelligence (AI). This notice is required in some countries.