Inglorious Utils

A set of general-purpose utility functions designed with functional programming principles in mind. This package is part of the Inglorious Forge monorepo.

Overview

This package provides a collection of pure, composable helper functions to streamline development in any JavaScript or TypeScript project. It embraces a data-oriented and functional approach, operating on plain data structures like objects and arrays.

Installation

npm install @inglorious/utils

Usage

Here are a few examples of how you can use the utilities in this package.

compose

Compose functions together from right to left.

import { compose } from "@inglorious/utils/functions"

const add = (a) => (b) => a + b
const multiply = (a) => (b) => a * b

const calculate = compose(
  add(10), // 30 + 10 = 40
  multiply(2), // 15 * 2 = 30
  add(5), // 10 + 5 = 15
)

const result = calculate(10) // 40

debounce

Delay a function until calls stop for a given amount of time.

import { debounce } from "@inglorious/utils/functions"

const debouncedSave = debounce(() => {
  save()
}, 300)

pipe

Compose functions together in a readable, left-to-right sequence.

import { pipe } from "@inglorious/utils/functions"

const add = (a) => (b) => a + b
const multiply = (a) => (b) => a * b

const calculate = pipe(
  add(5), // 10 + 5 = 15
  multiply(2), // 15 * 2 = 30
  add(10), // 30 + 10 = 40
)

const result = calculate(10) // 40

throttle

Run a function immediately, then suppress repeated calls until the wait time has elapsed.

import { throttle } from "@inglorious/utils/functions"

const throttledSave = throttle(() => {
  save()
}, 300)

Vector Math

Perform vector operations on plain objects.

import { add } from "@inglorious/utils/vector.js"

const position = [10, 20]
const velocity = [2, -1]

const newPosition = add(position, velocity)
// => [12, 19]

Two vectors are worth knowing by name: ZERO_VECTOR, with every component at zero, and UNIT_VECTOR, one unit long along the x axis. The zero one is handy for naming the components you care about, or for building a vector up from scratch:

import { ZERO_VECTOR } from "@inglorious/utils/math/vector.js"
import { v } from "@inglorious/utils/v.js"

const [, NO_RISE, NO_DEPTH] = ZERO_VECTOR

const position = v(10, 20, NO_DEPTH)

Vectors are mutable arrays, so copy a shared vector rather than storing it where something writes to one, such as an entity position. Copy it with v(...ZERO_VECTOR): a plain spread ([...ZERO_VECTOR]) gives you a new array but drops the tag that isVector looks for.

API

This package is designed to be used with subpath imports, which helps with tree-shaking.

Most modules are grouped by category:

• @inglorious/utils/algorithms: Utilities for AI algorithms, like decision trees and A*.
• @inglorious/utils/data-structures: Utilities for arrays, boards, heaps, objects, sets, strings, and trees.
• @inglorious/utils/math: Utilities for math operations.
• @inglorious/utils/physics: Utilities for calculations on friction, acceleration, and gravity.

The four largest modules are also available as top-level subpaths, so you don't need to know whether a helper lives under data-structures or math:

• @inglorious/utils/functions: compose, debounce, isFunction, pipe, throttle.
• @inglorious/utils/object: Single-object helpers (clone, get, set, produce, ...) alongside multi-object helpers (merge, extend, defaults, ...).
• @inglorious/utils/quaternion: quaternion and combine.
• @inglorious/utils/vector: Single-vector helpers (magnitude, normalize, rotate, ...) alongside multi-vector helpers (cross, dot, sum, ...).

divide, mod, multiply and power accept either a scalar or one or more vectors: a scalar is applied to every component, while vectors are combined component-wise.

import { multiply } from "@inglorious/utils/vector.js"

multiply([1, 2, 3], 2) // => [2, 4, 6]
multiply([1, 2, 3], [4, 5, 6]) // => [4, 10, 18]

License

MIT License - Free and open source

Created by Matteo Antony Mistretta

You're free to use, modify, and distribute this software. See LICENSE for details.

Contributing

We welcome contributions! Please see the root CONTRIBUTING.md file for more details.