@inglorious/utils 3.8.0 → 4.0.0

package/src/physics/velocity.js

@@ -1,9 +1,8 @@
 /**
- * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math/vectors").Vector3} Vector3
  */
 
-import { clamp, multiply, zero } from "../math/vector.js"
-import { sum } from "../math/vectors.js"
+import { clamp, multiply, sum, zero } from "../math/vectors.js"
 
 const DEFAULT_DT = 1 // Default time delta for the applyVelocity function.
 const DEFAULT_MAX_SPEED = 0 // Default maximum speed for velocity clamping.

package/src/v.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import("../types/math").Vector} Vector
+ * @typedef {import("../types/math/vectors").Vector} Vector
  */
 
 import { isArray } from "./data-structures/array.js"

package/types/algorithms/decision-tree.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents the input conditions evaluated by a decision tree.
+ */
+export type Conditions = unknown
+
+/**
+ * Represents the value returned by a decision tree node's test function.
+ */
+export type Outcome = string | boolean
+
+/**
+ * Represents a node in a decision tree.
+ */
+export interface DecisionTree<C = Conditions> {
+  /** Evaluates conditions and returns the key of the branch to follow. */
+  test?: (conditions: C) => Outcome
+  /** Resolves the branch associated with a test outcome. */
+  [outcome: string]: ((conditions: C) => Outcome | DecisionTree<C>) | undefined
+}
+
+/**
+ * Traverses a decision tree based on the provided conditions.
+ */
+export function decide<C>(
+  tree: DecisionTree<C>,
+  conditions: NoInfer<C>,
+): Outcome | DecisionTree<C> | undefined

package/types/algorithms/index.d.ts

@@ -0,0 +1,2 @@
+export * as decisionTree from "./decision-tree"
+export * as pathfinding from "./path-finding"

package/types/algorithms/path-finding.d.ts

@@ -0,0 +1,69 @@
+import type { Vector2 } from "../math/vectors"
+
+/**
+ * A map where keys are node identifiers and values are their [x, y] coordinates.
+ */
+export interface NodeMap {
+  [id: string]: [x: number, y: number]
+}
+
+/**
+ * Represents a node in a graph.
+ */
+export interface Node {
+  /** A unique identifier for the node. */
+  id: string
+  /** The [x, y] coordinates of the node. */
+  position: [x: number, y: number]
+  /** An optional cost associated with traversing to this node. */
+  cost?: number
+}
+
+/**
+ * Represents a directed edge between two nodes in a graph.
+ */
+export interface Arc {
+  /** The ID of the starting node. */
+  from: string
+  /** The ID of the ending node. */
+  to: string
+  /** An optional cost associated with traversing this arc. */
+  cost?: number
+}
+
+/**
+ * Represents a graph structure consisting of nodes and arcs.
+ */
+export interface Graph {
+  /** The graph nodes, as either an array or a map for efficient lookups. */
+  nodes: NodeMap | Node[]
+  /** The arcs connecting the nodes. */
+  arcs: Arc[]
+}
+
+export type Heuristic = (a: Node, b: Node) => number
+
+/**
+ * Calculates the cost of a path using Dijkstra's algorithm.
+ */
+export function dijkstra(): number
+
+/**
+ * Calculates the Euclidean distance between two nodes.
+ */
+export function eucledianDistance(a: Node, b: Node): number
+
+/**
+ * Calculates the Manhattan distance between two nodes.
+ */
+export function manhattanDistance(a: Node, b: Node): Vector2
+
+/**
+ * Finds the shortest path between two nodes in a graph.
+ */
+export function findPath(
+  graph: Graph,
+  start: string,
+  end: string,
+  heuristic?: Heuristic,
+): string[] | undefined

package/types/data-structures/array.d.ts

@@ -0,0 +1,56 @@
+export type Comparator<T> = (left: T, right: T) => number
+
+/**
+ * Checks whether an array contains a specific item.
+ */
+export function contains<T>(arr: readonly T[], item: T): boolean
+
+/**
+ * Ensures that a value is an array.
+ */
+export function ensureArray<T>(value: T): T extends readonly unknown[] ? T : T[]
+
+/**
+ * Checks whether a value is an array.
+ */
+export function isArray(value: unknown): value is readonly unknown[]
+
+/**
+ * Finds the maximum item in an array using a comparator.
+ */
+export function max<T extends number>(
+  arr: readonly T[],
+  comparator?: Comparator<T>,
+): T
+
+export function max<T>(arr: readonly T[], comparator: Comparator<T>): T
+
+/**
+ * Finds the minimum item in an array using a comparator.
+ */
+export function min<T extends number>(
+  arr: readonly T[],
+  comparator?: Comparator<T>,
+): T
+
+export function min<T>(arr: readonly T[], comparator: Comparator<T>): T
+
+/**
+ * Removes the smallest item from an array using a comparator.
+ */
+export function pop<T extends number>(
+  arr: readonly T[],
+  comparator?: Comparator<T>,
+): T[]
+
+export function pop<T>(arr: readonly T[], comparator: Comparator<T>): T[]
+
+/**
+ * Adds an item to an array immutably.
+ */
+export function push<T, U>(arr: readonly T[], item: U): Array<T | U>
+
+/**
+ * Removes an item from an array immutably.
+ */
+export function remove<T>(arr: readonly T[], item: T): T[]

package/types/data-structures/board.d.ts

@@ -0,0 +1,121 @@
+export type Coordinates = readonly [row: number, column: number]
+
+export type CoordinatesResult = [row: number, column: number]
+
+export type BoardSize = readonly [rows: number, columns: number]
+
+export type VerticalBoardSize = readonly [rows: number, columns?: number]
+
+export type Board<T> = T[]
+
+export type BoardFiller<T> = (row: number, column: number) => T
+
+export type CellToString<T> = (cell: T, row: number, column: number) => string
+
+export type NeighborPredicate<T> = (cell: T) => boolean
+
+/**
+ * The axes that wrap around board edges. "horizontal" wraps the column axis,
+ * "vertical" wraps the row axis, and "both" wraps each axis independently.
+ */
+export type Wrap = "horizontal" | "vertical" | "both"
+
+export interface NeighborOptions {
+  wrap?: Wrap
+}
+
+export interface CountNeighborsOptions<T> extends NeighborOptions {
+  predicate?: NeighborPredicate<T>
+}
+
+/**
+ * Counts the neighboring cells that satisfy a predicate.
+ */
+export function countNeighbors<T>(
+  cells: readonly T[],
+  coords: Coordinates,
+  size: BoardSize,
+  options?: CountNeighborsOptions<T>,
+): number
+
+/**
+ * Returns the flat-board index for a row and column.
+ */
+export function getIndex(row: number, column: number, columns: number): number
+
+/**
+ * Creates a one-dimensional board and fills each cell using the given function.
+ */
+export function createBoard(dimensions: BoardSize, filler?: undefined): null[]
+
+export function createBoard<T>(
+  dimensions: BoardSize,
+  filler: BoardFiller<T>,
+): T[]
+
+/**
+ * Moves coordinates one step down.
+ */
+export function down(
+  coords: Coordinates,
+  size: VerticalBoardSize,
+): CoordinatesResult
+
+/**
+ * Moves coordinates one step down and left.
+ */
+export function downLeft(
+  coords: Coordinates,
+  size: BoardSize,
+): CoordinatesResult
+
+/**
+ * Moves coordinates one step down and right.
+ */
+export function downRight(
+  coords: Coordinates,
+  size: BoardSize,
+): CoordinatesResult
+
+/**
+ * Moves coordinates one step left.
+ */
+export function left(coords: Coordinates, size?: BoardSize): CoordinatesResult
+
+/**
+ * Returns the coordinates neighboring a cell that fall within the board.
+ */
+export function neighbors(
+  coords: Coordinates,
+  size: BoardSize,
+  options?: NeighborOptions,
+): CoordinatesResult[]
+
+/**
+ * Moves coordinates one step right.
+ */
+export function right(coords: Coordinates, size: BoardSize): CoordinatesResult
+
+/**
+ * Converts a board to a string representation.
+ */
+export function toString<T>(
+  board: Readonly<Board<T>>,
+  dimensions: BoardSize,
+  cellToString?: CellToString<T>,
+): string
+
+/**
+ * Moves coordinates one step up.
+ */
+export function up(coords: Coordinates, size?: BoardSize): CoordinatesResult
+
+/**
+ * Moves coordinates one step up and left.
+ */
+export function upLeft(coords: Coordinates, size: BoardSize): CoordinatesResult
+
+/**
+ * Moves coordinates one step up and right.
+ */
+export function upRight(coords: Coordinates, size: BoardSize): CoordinatesResult

package/types/data-structures/boolean.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Converts a boolean to its string representation.
+ */
+export function toString(bool: boolean): "true" | "false"

package/types/data-structures/heap.d.ts

@@ -0,0 +1,69 @@
+export type HeapComparator<T> = (a: T, b: T) => number
+
+/**
+ * Checks whether a heap contains a specific item.
+ */
+export function contains<T>(heap: readonly T[], item: T): boolean
+
+/**
+ * Converts an array into a heap.
+ */
+export function heapify<T extends number>(
+  arr: readonly T[],
+  comparator?: HeapComparator<T>,
+): T[]
+
+export function heapify<T>(
+  arr: readonly T[],
+  comparator: HeapComparator<T>,
+): T[]
+
+/**
+ * Adds an item to a heap.
+ */
+export function push<T extends number>(
+  heap: readonly T[],
+  item: T,
+  comparator?: HeapComparator<T>,
+): T[]
+
+export function push<T>(
+  heap: readonly T[],
+  item: T,
+  comparator: HeapComparator<T>,
+): T[]
+
+/**
+ * Returns the index of a node's left child.
+ */
+export function left(index: number): number
+
+/**
+ * Returns the index of a node's parent.
+ */
+export function parent(index: number): number
+
+/**
+ * Removes the root item from a heap.
+ */
+export function pop<T extends number>(
+  heap: readonly T[],
+  comparator?: HeapComparator<T>,
+): T[]
+
+export function pop<T>(heap: readonly T[], comparator: HeapComparator<T>): T[]
+
+/**
+ * Removes the root item and reorders the heap.
+ */
+export function remove<T extends number>(heap: readonly T[]): T[]
+
+/**
+ * Returns the index of a node's right child.
+ */
+export function right(index: number): number
+
+/**
+ * Returns a heap's root item.
+ */
+export function root<T>(heap: readonly T[]): T | undefined

package/types/data-structures/index.d.ts

@@ -0,0 +1,8 @@
+export * as array from "./array"
+export * as board from "./board"
+export * as boolean from "./boolean"
+export * as heap from "./heap"
+export * as objects from "./objects"
+export * as set from "./set"
+export * as string from "./string"
+export * as tree from "./tree"

package/types/data-structures/objects.d.ts

@@ -0,0 +1,237 @@
+import type { Vector } from "../math/vectors"
+
+export type ObjectValue<T> = T extends object ? T[keyof T] : never
+
+export type PathKey<T, Key extends string> = T extends object
+  ? Key extends keyof T
+    ? Key
+    : Key extends `${infer Index extends number}`
+      ? Index extends keyof T
+        ? Index
+        : never
+      : never
+  : never
+
+export type PathValue<T, Path extends string> = T extends object
+  ? Path extends `${infer Key}.${infer Rest}`
+    ? PathKey<T, Key> extends never
+      ? unknown
+      : PathValue<T[PathKey<T, Key>], Rest>
+    : PathKey<T, Path> extends never
+      ? unknown
+      : T[PathKey<T, Path>]
+  : unknown
+
+export type DeserializedValue =
+  | null
+  | boolean
+  | number
+  | string
+  | Vector
+  | DeserializedValue[]
+  | { [key: string]: DeserializedValue }
+
+export type Recipe<T, Args extends unknown[] = []> = (
+  draft: T,
+  ...args: Args
+) => T | void
+
+export type ToStringResult<T> = T extends Function
+  ? T
+  : T extends string | readonly unknown[] | object
+    ? string
+    : T
+
+export type Merger = (targetValue: unknown, sourceValue: unknown) => unknown
+
+export type ObjectSource = object | null | undefined
+
+export type MergeObject<T extends object, S extends object> = Omit<T, keyof S> &
+  S
+
+export type MergeSources<
+  T extends object,
+  Sources extends readonly unknown[],
+> = Sources extends readonly [
+  infer Source,
+  ...infer Rest extends readonly unknown[],
+]
+  ? Source extends object
+    ? MergeSources<MergeObject<T, Source>, Rest>
+    : MergeSources<T, Rest>
+  : T
+
+export type DefaultsResult<T extends object, D extends object> = Omit<
+  T,
+  keyof D
+> & {
+  [K in keyof D]: K extends keyof T
+    ? Exclude<T[K], null | undefined> | D[K]
+    : D[K]
+}
+
+/**
+ * Creates a deep clone of a value.
+ */
+export function clone<T>(obj: T): T
+
+/**
+ * Assigns default properties to a target in place.
+ */
+export function defaults<T extends object, D extends object>(
+  target: T,
+  defaultProps: D,
+): DefaultsResult<T, D>
+
+/**
+ * Deserializes a value, restoring vector representations.
+ */
+export function deserialize(str: string): DeserializedValue
+
+/**
+ * Creates a new object by deeply merging source objects into a target.
+ */
+export function extend<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(target: T, ...sources: Sources): MergeSources<T, Sources>
+
+/**
+ * Creates a new deeply merged object using a custom merger.
+ */
+export function extendWith<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(
+  merger: null | undefined,
+  target: T,
+  ...sources: Sources
+): MergeSources<T, Sources>
+
+export function extendWith<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(merger: Merger, target: T, ...sources: Sources): Record<string, unknown>
+
+export function extendWith<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(
+  merger: Merger | null | undefined,
+  target: T,
+  ...sources: Sources
+): Record<string, unknown>
+
+/**
+ * Filters the properties of an object using a callback.
+ */
+export function filter<T extends object>(
+  obj: T,
+  callback: (key: string, value: ObjectValue<T>, index: number) => boolean,
+): Partial<T>
+
+/**
+ * Finds the first property of an object that matches a callback.
+ */
+export function find<T extends object>(
+  obj: T,
+  callback: (key: string, value: ObjectValue<T>, index: number) => boolean,
+): Partial<T>
+
+/**
+ * Gets the value at a path in an object.
+ */
+export function get<T, Path extends string | null | undefined, D>(
+  obj: T,
+  path: Path,
+  defaultValue: D,
+): Path extends null | undefined ? D : PathValue<T, Extract<Path, string>> | D
+
+export function get<T, Path extends string | null | undefined = string>(
+  obj: T,
+  path: Path,
+): Path extends null | undefined
+  ? undefined
+  : PathValue<T, Extract<Path, string>> | undefined
+
+/**
+ * Checks whether a value is a plain object.
+ */
+export function isObject(value: unknown): value is Record<string, unknown>
+
+/**
+ * Maps the properties of an object using a callback.
+ */
+export function map<T extends object, R>(
+  obj: T,
+  callback: (key: string, value: ObjectValue<T>, obj: T) => R,
+): Record<string, R>
+
+/**
+ * Merges source objects into a target in place.
+ */
+export function merge<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(target: T, ...sources: Sources): MergeSources<T, Sources>
+
+/**
+ * Deeply merges into a target in place using a custom merger.
+ */
+export function mergeWith<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(
+  merger: null | undefined,
+  target: T,
+  ...sources: Sources
+): MergeSources<T, Sources>
+
+export function mergeWith<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(merger: Merger, target: T, ...sources: Sources): Record<string, unknown>
+
+export function mergeWith<
+  T extends object,
+  Sources extends readonly ObjectSource[],
+>(
+  merger: Merger | null | undefined,
+  target: T,
+  ...sources: Sources
+): Record<string, unknown>
+
+/**
+ * Creates the next immutable state using a recipe.
+ */
+export function produce<T, Args extends unknown[] = []>(
+  recipe: Recipe<T, Args>,
+): (state: T, ...args: Args) => T
+
+export function produce<T, Args extends unknown[] = []>(
+  baseState: T,
+  recipe: Recipe<T, Args>,
+  ...args: Args
+): T
+
+/**
+ * Serializes a value, converting vectors to plain objects.
+ */
+export function serialize(obj: unknown): string | undefined
+
+/**
+ * Sets the value at a path in an object and returns the object.
+ */
+export function set<T extends object>(
+  obj: T,
+  path: string | null | undefined,
+  value: unknown,
+): T
+
+/**
+ * Converts an object or array to a formatted string representation.
+ */
+export function toString<T>(
+  obj: T,
+  indentationLevel?: number,
+): ToStringResult<T>

package/types/data-structures/set.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Ensures that a value is a Set.
+ */
+export function ensureSet<T = unknown>(value?: Iterable<T> | null): Set<T>

package/types/data-structures/tree.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Represents a generic tree data structure.
+ * Each node in the tree has a value and an optional array of child nodes.
+ * @template T - The type of the value stored in the tree nodes. Defaults to `any`.
+ */
+export interface Tree<T = any> {
+  /** The value of the current node. */
+  value: T
+  /** An optional array of child `Tree` nodes. */
+  children?: readonly Tree<T>[]
+}
+
+/**
+ * Traverses a tree breadth-first.
+ */
+export function bfs<T>(tree: Tree<T>): T[]
+
+/**
+ * Traverses a tree depth-first.
+ */
+export function dfs<T>(tree: Tree<T>): T[]

package/types/functions/functions.d.ts

@@ -0,0 +1,57 @@
+type AnyFunction = (...args: any[]) => any
+
+export type DebouncedFunction<T extends AnyFunction> = ((
+  ...args: Parameters<T>
+) => ReturnType<T> | undefined) & {
+  cancel: () => void
+  flush: () => ReturnType<T> | undefined
+  pending: () => boolean
+}
+
+export type ThrottledFunction<T extends AnyFunction> = ((
+  ...args: Parameters<T>
+) => ReturnType<T> | undefined) & {
+  cancel: () => void
+  pending: () => boolean
+}
+
+/**
+ * Composes multiple functions from right to left.
+ */
+export function compose<TArgs extends any[], TResult>(
+  ...fns: [(...args: TArgs) => any, ...Array<(value: any) => any>]
+): (...args: TArgs) => TResult
+
+export function compose(): <T>(value: T) => T
+
+/**
+ * Creates a debounced function that delays invoking `fn` until after `wait`
+ * milliseconds have elapsed since the last call.
+ */
+export function debounce<T extends AnyFunction>(
+  fn: T,
+  wait?: number,
+): DebouncedFunction<T>
+
+/**
+ * Checks whether a value is a function.
+ */
+export function isFunction(func: unknown): func is Function
+
+/**
+ * Pipes multiple functions from left to right.
+ */
+export function pipe<TArgs extends any[], TResult>(
+  ...fns: [(...args: TArgs) => any, ...Array<(value: any) => any>]
+): (...args: TArgs) => TResult
+
+export function pipe(): <T>(value: T) => T
+
+/**
+ * Creates a throttled function that invokes `fn` immediately, then ignores
+ * calls until `wait` milliseconds have elapsed.
+ */
+export function throttle<T extends AnyFunction>(
+  fn: T,
+  wait?: number,
+): ThrottledFunction<T>