@ripl/utilities

The typed helper functions every Ripl package is built from: type guards, numeric helpers, collection joins, comparators, caches and shared types.

This is an internal dependency. Every other @ripl/* package installs it, so you already have it transitively. Install it directly only if you want these helpers in your own code.

Features

• Category-prefixed names — every runtime export starts with its category (type*, number*, array*, object*, set*, string*, function*, comparitor*, predicate*, value*, time*), so related helpers group together in autocomplete.
• arrayJoin — the left/inner/right join Ripl's charts diff data with. A keyof predicate takes a Map-backed path, so a keyed join is linear rather than quadratic.
• Numeric helpers for axes and scales — numberExtent, numberNice (rounds to a 1/2/5/10 × power of ten), numberRoundTo, numberClamp, numberFormat.
• Eight type guards — typeIsArray, typeIsBoolean, typeIsDate, typeIsFunction, typeIsNil, typeIsNumber, typeIsObject, typeIsString.
• createLRUCache — a bounded Map subclass that evicts the least recently used entry when full. Iteration is least-recently-used first and does not itself affect recency.
• Function helpers — functionCache (holds a result until invalidated), functionMemoize (keyed by a resolver, first argument by default), functionProduce, functionIdentity, functionNoop.
• Shared types — OneOrMore<T>, AnyFunction, AnyObject, Disposable, Predicate<L, R>, Indexer<T>, Merge<A, B>, plus GetReadonlyKeys/GetMutableKeys.
• Zero dependencies, tree-shakable — no runtime dependencies at all, and each helper is a separate export.

Native array methods (forEach, map, filter, reduce, find, flatMap) and Math.min/Math.max are faster than wrappers, so this package has none. It ships only helpers that do something the platform does not.

Installation

# npm
npm install @ripl/utilities

# yarn
yarn add @ripl/utilities

# pnpm
pnpm add @ripl/utilities

Quick start

import {
    arrayJoin,
    numberExtent,
    numberNice,
} from '@ripl/utilities';

const {
    left: entries,
    inner: updates,
    right: exits,
} = arrayJoin(data, elements, (datum, element) => datum.id === element.data);

exits.forEach(element => element.destroy());

const [min, max] = numberExtent(data, datum => datum.value);
const axisMax = numberNice(max, true);

Key API

| Export | What it does | | --- | --- | | arrayJoin | Left/inner/right join for diffing data against drawn elements | | arrayGroup / arrayDedupe / arrayIntersection / arrayDifference | Grouping and set operations over arrays | | numberExtent / numberNice / numberClamp / numberFormat | The numeric helpers behind axes and scales | | typeIsArray … typeIsString | The eight type guards | | createLRUCache | Bounded, recency-ordered Map subclass | | functionCache / functionMemoize | Result caching and keyed memoization | | stringUniqueId | Cryptographically random hex id, 8 characters by default |

Related packages

• @ripl/core — the rendering core, this package's only direct consumer of note
• @ripl/web — the browser entry point, and what most projects should install
• @ripl/charts — where arrayJoin does its data diffing

Documentation

The full API reference is at ripl.run/docs/api/@ripl/utilities.

License

MIT