This package contains some useful utilities to help you write JavaScript better. It is a great place where to add these small helpers (without 3rd party dependencies) to share them everywhere.

yarn add @adeira/js

Optionally, install TS types (Flow types are included by default):

yarn add --dev @types/adeira__js

Note for ReScript users:

@module("@adeira/js") external invariant: (bool, string) => unit = "invariant"

invariant(false, "It works!")

invariant, warning

Use these functions instead of traditional error throwing or console.warn. Compare these two examples:

import { invariant } from '@adeira/js';

invariant(isWorkspaceDirectory === true, 'This is not a workspace directory.');

// vs:

if (isWorkspaceDirectory !== true) {
  throw new Error('This is not a workspace directory.');
}

It is a common idiom to use invariant() or invariant(false, ...) to throw in code that should be unreachable. The rules apply to warning (except it doesn't throw but log to stdout instead):

import { warning } from '@adeira/js';

warning(isWorkspaceDirectory === true, 'This is not a workspace directory.');

// vs:

if (isWorkspaceDirectory !== true) {
  if (process.env.NODE_ENV !== 'production') {
    console.warn('This is not a workspace directory.');
  }
}

First it's more readable this way - you don't have to use conditions at all. But more importantly we can now work with these errors/warnings a bit better. The idea is to transpile these functions so they do not contain sensitive error messages in production. These functions are therefore perfect fit for your production applications.

Invariant has also great native support in Flow. Just add this to your Flow config file:

[lints]
unnecessary-invariant=error

It can detect unreachable code after this invariant as well as unnecessary usage of this function:

Error ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ src/packages/js/src/invariant.js:32:3

This use of `invariant` is unnecessary because boolean [1] is always truthy. (unnecessary-invariant)

     29│ ): void {
     30│   validateFormat(format);
     31│
 [1] 32│   invariant(true, 'What is the point?');
     33│
     34│   if (!condition) {
     35│     let error;

These both functions use sprintf behind the scenes.

sprintf

This function allows you to replace string placeholders similar to how console.log or util.format work. However, this function is system independent and works in browsers, Node.js and RN. Only %s (String) and %j (JSON) is supported:

import { sprintf } from '@adeira/js';

sprintf('Oh, %s', 'yeah!'); // Oh, yeah!
sprintf('Oh, %j', 'yeah!'); // Oh, "yeah!"

sprintf('Tada: %s', '{ aaa: 111 }'); // Tada: [object Object]
sprintf('Tada: %j', '{ aaa: 111 }'); // Tada: {"aaa":111}

It can handle circular references gracefully:

import { sprintf } from '@adeira/js';

const obj = {
  a: 'foo',
};
obj.b = obj;

sprintf('%s', obj); // '[object Object]'
sprintf('%j', obj); // '{"a":"foo","b":"[Circular]"}'

It is also possible to escape the percentage sign with %%.

isObject

This function ignores internal JS implementation and returns true only for real objects (not arrays or nulls and similar).

import { isObject } from '@adeira/js';

isObject({}); // true
isObject(new Date()); // true

isObject(null); // false
isObject([]); // false

isObjectEmpty

import { isObjectEmpty } from '@adeira/js';

isObjectEmpty({}); // true (the only case)

isObjectEmpty({ a: 1 }); // false
isObjectEmpty(null); // false
isObjectEmpty(new Date()); // false

isNumeric

Correctly determines whether the value is numeric or not.

import { isNumeric } from '@adeira/js';

isNumeric('42'); // true
isNumeric(42); // true
isNumeric(0xfff); // true

isNumeric(null); // false
isNumeric([]); // false
isNumeric(Infinity); // false

nullthrows

This function allows you to reduce necessary boilerplate when checking for null and throwing an exception.

function abc() {
  const x = dataloader.load(1);
  if (x == null) {
    throw new Error('Got unexpected null or undefined.');
  }
  return x;
}

Becomes:

import { nullthrows } from '@adeira/js';

function abc() {
  return nullthrows(dataloader.load(1));
}

Alternatively, you can supply a custom error message:

import { nullthrows } from '@adeira/js';

function abc() {
  return nullthrows(dataloader.load(1), 'UPS, this is an error!');
}

As you can see, it's very similar to invariant function. Tip: this function can be also handy in tests where you want to guard against nullable values.

isBrowser

This function checks if you are running in the browser.

import { isBrowser } from '@adeira/js';

if (isBrowser()) {
  // Safely access window
  window.location.href = 'https://www.github.com/adeira';
} else {
  // Do server logic for redirect
}

rangeMap

This function is useful when you want to quickly iterate specified number of elements. For example, printing a grid of product placeholders while loading the actual products:

import { rangeMap } from '@adeira/js';

<div className={styles('productsGrid')}>
  {rangeMap(12, (i) => (
    <Skeleton key={i} />
  ))}
</div>;