🛠️ Utilities for Node.js and the browser

$ npm install @radically-straightforward/utilities

import * as utilities from "@radically-straightforward/utilities";

export function sleep(duration: number): Promise<void>;

A promisified version of setTimeout(). Bare-bones: It doesn’t even offer a way to clearTimeout(). Useful in JavaScript that may run in the browser—if you’re only targeting Node.js then you’re better served by timersPromises.setTimeout().

export function randomString(): string;

A fast random string generator. The generated strings vary in length, but are generally around 10 characters. The generated strings include the characters [a-z0-9]. The generated strings are not cryptographically secure—if you need that, then use crypto-random-string.

export function log(...messageParts: string[]): void;

Tab-separated logging.

export class JSONLinesTransformStream extends TransformStream;

A TransformStream to convert a stream of a string with JSON lines into a stream of JSON objects.

Example

const reader = new Blob([
  `\n\n${JSON.stringify("hi")}\n${JSON.stringify({ hello: "world" })}\n`,
])
  .stream()
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(new utilities.JSONLinesTransformStream())
  .getReader();
(await reader.read()).value; // => "hi"
(await reader.read()).value; // => { hello: "world" }
(await reader.read()).value; // => undefined

export function capitalize(string: string): string;

Capitalizes the first letter of a string. It’s different from Lodash’s capitalize() in that it doesn’t lowercase the rest of the string.

export function isDate(string: string): boolean;

Determine whether the given string is a valid Date, that is, it’s in ISO format and corresponds to an existing date, for example, it is not April 32nd.

export const emailRegExp: RegExp;

A regular expression that matches valid email addresses. This regular expression is more restrictive than the RFC—it doesn’t match some email addresses that technically are valid, for example, example@localhost. But it strikes a good tradeoff for practical purposes, for example, signing up in a web application.

export const ISODateRegExp: RegExp;

A regular expression that matches ISO dates, for example, 2024-04-01T14:19:48.162Z.

export type Intern<Type> = Readonly<
  Type & {
    [internSymbol]: true;
  }
>;

Utility type for intern().

export type InternInnerValue =
  | string
  | number
  | bigint
  | boolean
  | symbol
  | undefined
  | null
  | Intern<unknown>;

Utility type for intern().

export function intern<
  Type extends
    | Array<InternInnerValue>
    | {
        [key: string]: InternInnerValue;
      },
>(value: Type): Intern<Type>;

Interning a value makes it unique across the program, which is useful for checking equality with === (reference equality), using it as a key in a Map, adding it to a Set, and so forth:

import { intern as $ } from "@radically-straightforward/utilities";

[1] === [1]; // => false
$([1]) === $([1]); // => true

{
  const map = new Map<number[], number>();
  map.set([1], 1);
  map.set([1], 2);
  map.size; // => 2
  map.get([1]); // => undefined
}

{
  const map = new Map<utilities.Intern<number[]>, number>();
  map.set($([1]), 1);
  map.set($([1]), 2);
  map.size; // => 1
  map.get($([1])); // => 2
}

{
  const set = new Set<number[]>();
  set.add([1]);
  set.add([1]);
  set.size; // => 2
  set.has([1]); // => false
}

{
  const set = new Set<utilities.Intern<number[]>>();
  set.add($([1]));
  set.add($([1]));
  set.size; // => 1
  set.has($([1])); // => true
}

Note: We recommend that you alias intern as $ when importing it to make your code less noisy.

Node: Inner values must be either primitives or interned values themselves, for example, $([1, $({})]) is valid, but $([1, {}]) is not.

Node: Currently only arrays (tuples) and objects (records) may be interned. In the future we may support more types, for example, Map, Set, regular expressions, and so forth.

Note: You must not mutate an interned value. Interned values are frozen to prevent mutation.

Note: Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.

Note: Interned objects do not preserve the order of the attributes: $({ a: 1, b: 2 }) === $({ b: 2, a: 1 }).

Note: The pool of interned values is available as intern.pool. The interned values are kept with WeakRefs to allow them to be garbage collected when they aren’t referenced anywhere else anymore. There’s a FinalizationRegistry at intern.finalizationRegistry that cleans up interned values that have been garbage collected.

Related Work

JavaScript Records & Tuples Proposal

A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for intern().

It includes a polyfill which works very similarly to intern() but requires different functions for different data types.

collections-deep-equal

A previous solution to this problem which took a different approach: Instead of interning the values and allowing you to use JavaScript’s Maps and Sets, collections-deep-equal extends Maps and Sets with a different notion of equality.

collections-deep-equal doesn’t address the issue of comparing values with === (reference equality).

collections-deep-equal does more work on every manipulation of the data structure, for example, when looking up a key in a Map, so it may be slower.

collections-deep-equal has different intern pools for each Map and Set instead of intern()’s single global intern pool, which may be advantageous because smaller pools may be faster to traverse.

Immutable.js, collections, mori, TypeScript Collections, prelude-ts, collectable, and so forth

Similar to collections-deep-equal, these libraries implement their own data structures instead of relying on JavaScript’s Maps and Sets. Some of them go a step further and add their own notions of objects and arrays, which requires you to convert your values back and forth, may not show up nicely in the JavaScript inspector, may be less ergonomic to use with TypeScript, and so forth.

The advantage of these libraries over interning is that they may be faster.

immer and icepick

Introduce a new way to create values based on existing values.

seamless-immutable

Modifies existing values more profoundly than freezing.

es6-array-map, valuecollection, @strong-roots-capital/map-objects, and so forth

Similar to collections-deep-equal but either incomplete, or lacking type definitions, and so forth.

Other

• https://2ality.com/2015/01/es6-maps-sets.html#why-can’t-i-configure-how-maps-and-sets-compare-keys-and-values%3F
• https://stackoverflow.com/questions/21838436/map-using-tuples-or-objects
• https://esdiscuss.org/topic/maps-with-object-keys
• https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723
• https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723
• https://twitter.com/swannodette/status/1067962983924539392
• https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43

export function backgroundJob(
  {
    interval,
    onStop = () => {},
  }: {
    interval: number;
    onStop?: () => void | Promise<void>;
  },
  job: () => void | Promise<void>,
): {
  run: () => Promise<void>;
  stop: () => Promise<void>;
};

Note: This is a lower level utility. See @radically-straightforward/node’s and @radically-straightforward/javascript’s extensions to backgroundJob() that are better suited for their specific environments.

Start a background job that runs every interval.

backgroundJob() is different from setInterval() in the following ways:

1. The interval counts between jobs, so slow background jobs don’t get called concurrently:

   setInterval()
   | SLOW BACKGROUND JOB |
   | INTERVAL | SLOW BACKGROUND JOB |
              | INTERVAL | ...
   
   backgroundJob()
   | SLOW BACKGROUND JOB | INTERVAL | SLOW BACKGROUND JOB | INTERVAL | ...
   

2. You may use backgroundJob.run() to force the background job to run right away. If the background job is already running, calling backgroundJob.run() schedules it to run again as soon as possible (with a wait interval of 0).

3. You may use backgroundJob.stop() to stop the background job. If the background job is in the middle of running, it will finish but it will not be scheduled to run again. This is similar to how an HTTP server may terminate gracefully by stopping accepting new requests but finishing responding to existing requests. After a job has been stopped, you may not backgroundJob.run() it again (calling backgroundJob.run() has no effect).

4. We introduce a random interval variance of 10% on top of the given interval to avoid many background jobs from starting at the same time and overloading the machine.

Note: If the job throws an exception, the exception is logged and the background job continues.

export async function timeout<Type>(
  duration: number,
  function_: () => Promise<Type>,
): Promise<Type>;

Run the given function_ up to the timeout. If the timeout is reached, the returned promise rejects, but there is no way to guarantee that the function_ execution will stop.