Documentation / @ripl/utilities

@ripl/utilities

Shared typed utility functions for Ripl — a unified API for 2D graphics rendering in the browser.

Installation

npm install @ripl/utilities

Overview

A collection of strictly-typed utility functions used across the Ripl ecosystem. Zero dependencies, fully tree-shakable.

API

Type Guards

typeIsArray(value); // value is unknown[]
typeIsFunction(value); // value is AnyFunction
typeIsNil(value); // value is null | undefined
typeIsNumber(value); // value is number
typeIsString(value); // value is string
typeIsObject(value); // value is object
typeIsDate(value); // value is Date
typeIsBoolean(value); // value is boolean

Collection Helpers

arrayJoin(left, right, predicate); // left/inner/right join for data diffing (Map-optimized for key predicates)
arrayMapRange(length, callback); // map over a numeric range
arrayGroup(array, key); // group array items by key or function
arrayIntersection(left, right, predicate); // intersection of two arrays
arrayDifference(left, right, predicate); // difference of two arrays

Note: Generic array wrappers (arrayForEach, arrayMap, arrayFilter, arrayReduce, arrayFind, arrayFlatMap) have been removed in favour of native array methods for better performance.

Object Helpers

objectForEach(object, callback);
objectMap(object, callback);
objectMerge(target, ...sources);

Common Types

OneOrMore<T>; // T | T[]
AnyFunction; // (...args: any[]) => any
AnyObject; // { [key: PropertyKey]: unknown }
Disposable; // { dispose: () => void }
Predicate<L, R>; // (left: L, right: R) => boolean

Value Helpers

valueOr(value, fallback); // value ?? fallback with type narrowing
valueOrDefault(value, fallback); // nullish coalescing with defaults

Documentation

Full documentation is available at ripl.rocks.

License

MIT

Interfaces

Interface	Description
ArrayJoin	Result of an array join containing unmatched left items, matched pairs, and unmatched right items.
Disposable	A resource that can be disposed to release underlying subscriptions or handles.

Type Aliases

Type Alias	Description
AnyAsyncFunction	A loosely-typed async function signature.
AnyFunction	A loosely-typed function signature that accepts and returns anything.
AnyObject	A loosely-typed object with string, number, or symbol keys.
ArrayGroupIdentity	A property key or indexer function used to derive group identity from array items.
ArrayJoinPredicate	A shared key or predicate function used to match items between two arrays in a join.
CachedFunction	A function wrapper that caches its result after the first invocation until explicitly invalidated.
CollectionIteratee	Callback invoked for each item in a collection, receiving the value and its index.
GetMutableKeys	Extracts the mutable (non-readonly) property keys from an object type.
GetReadonlyKeys	Extracts the readonly property keys from an object type.
IfEquals	Conditional type that resolves to A if X and Y are identical, otherwise B.
Indexer	Derives a grouping key from a value.
IterableObject	An object whose values are unknown, suitable for generic iteration.
MemoizedFunction	A function wrapper that caches results per unique key, exposing the underlying cache Map.
MemoizeResolver	Derives a cache key from the arguments of a memoized function.
Merge	Merges two types, with properties in TB overriding those in TA.
ObjectIteratee	Callback invoked for each entry in an object, receiving the key and value.
ObjectReducer	Reducer callback for folding over object entries into an accumulated result.
OneOrMore	Represents a single value or an array of values.
Predicate	A comparison function that tests whether two values match.
UnionToIntersection	Converts a union type to an intersection type.

Functions

Function	Description
arrayDifference	Returns items from the left array that have no matching counterpart in the right array.
arrayGroup	Groups array items by a property key or indexer function into a keyed record.
arrayIntersection	Returns items from the left array that have a matching counterpart in the right array.
arrayJoin	Performs a full join between two arrays, returning entries (left-only), updates (matched), and exits (right-only).
arrayMapRange	Creates an array of the given length by mapping each index through the iteratee.
comparitorDate	Date comparator suitable for sorting dates in ascending chronological order.
comparitorNumeric	Numeric comparator suitable for sorting numbers in ascending order.
comparitorString	Locale-aware string comparator suitable for alphabetical sorting.
functionCache	Wraps a function so its result is computed once and then returned from cache on subsequent calls until invalidate() is called.
functionIdentity	Returns the value it receives unchanged — useful as a default transform or placeholder.
functionMemoize	Memoizes a function by caching results keyed by the resolver (defaults to the first argument).
functionProduce	Wraps a value or factory function into a consistent factory that always returns the value.
noop	-
numberGCD	Computes the greatest common divisor of two integers using the Euclidean algorithm.
numberNice	Rounds a value to a "nice" human-readable number (1, 2, 5, or 10 scaled by the appropriate power of ten).
numberSum	Computes the sum of an array of numbers, or of values mapped through an optional iteratee.
objectForEach	Iterates over the enumerable properties of an object, invoking the iteratee for each key-value pair.
objectFreeze	Creates a shallow frozen copy of the given object.
objectMap	Maps over the enumerable properties of an object, producing a new object with transformed values.
objectReduce	Reduces the enumerable properties of an object into a single accumulated value.
predicateIdentity	Tests strict reference equality between two values.
predicateKey	Tests whether two objects share the same value at a given key.
setFilter	Filters a Set, returning a new Set containing only values that satisfy the predicate.
setFind	Searches a Set for the first value that satisfies the predicate.
setFlatMap	Flat-maps over a Set, concatenating the arrays returned by the iteratee into a new Set.
setForEach	Iterates over each value in a Set, invoking the iteratee with the value and a running index.
setMap	Maps over a Set, producing a new Set with each value transformed by the iteratee.
stringEquals	Case-insensitive string equality check.
stringUniqueId	Generates a cryptographically random hexadecimal string of the specified length.
typeIsArray	Checks whether a value is an array.
typeIsBoolean	Checks whether a value is a boolean.
typeIsDate	Checks whether a value is a Date instance.
typeIsFunction	Checks whether a value is a function.
typeIsNil	Checks whether a value is null or undefined.
typeIsNumber	Checks whether a value is a number.
typeIsObject	Checks whether a value is a non-null object.
typeIsString	Checks whether a value is a string.
valueOneOrMore	Normalises a single value or array into a guaranteed array.