customutil

A zero-dependency functional utility library designed for absolute immutability and 100% type safety.

This library was built from the ground up to solve the type-inference loopholes present in traditional utility libraries, providing robust, generic-driven type definitions that prevent invalid deep-property references at the compilation level.

Installation

npm install customutil

Features

• Zero Dependencies: Lightweight and fast.
• Deep Path Type-Safety: Extraction and Optics modules strictly type-assert nested object paths using recursive TypeScript string literals (e.g., "user.profile.name").
• Immutability First: Operations never mutate the original collections, enforcing a purely functional, side-effect-free architecture.
• Strictly Typed: never-path failing schemas immediately flag invalid runtime lookups in your IDE before testing.

Modules

1. Foundation

Standard functional operations that enforce strict input assertions.

• map(transformFn, arr)
• filter(predicateFn, arr)
• reduce(reducerFn, initialValue, arr)
• reduceRight(reducerFn, initialValue, arr)
• some(predicateFn, arr)
• every(predicateFn, arr)

2. Search & Extraction

Type-safe array searching and deep data isolation.

• find(arr, matchFn): Search arrays by functional predicate, key-value match, or partial object matcher.
• pluck(path, arr): Extract single keys, an array of keys into tuples, or deeply nested properties.

3. Optics (Lenses)

Functional lenses for deep state access and immutable modification.

• lens<T, Path>(path): Creates a strictly-typed lens focused on a specific nested property.
• view(lens, object): Safely reads a deep value, gracefully returning undefined if intermediate structures are missing.
• set(lens, newValue, object): Immutably sets a deep value. It perfectly preserves unchanged sibling branches and correctly instantiates any missing intermediate path objects.

Usage Examples

Deep Path Plucking

import { pluck } from 'customutil/extraction/pluck';

const data = [
  { id: 1, user: { profile: { name: "Alice" } } },
  { id: 2, user: { profile: { name: "Bob" } } }
];

// Pluck nested arrays securely natively mapped to type arrays
const names = pluck("user.profile.name", data); 
// -> ['Alice', 'Bob']

Immutable Optics Manipulation

import { lens } from 'customutil/optics/lens';
import { set } from 'customutil/optics/set';

// Provide your parent Type parameter for precise compiler bounds.
const nameLens = lens<typeof data[0], "user.profile.name">("user.profile.name");

// Deep state update that returns entirely new nested refs 
// while keeping unrelated sibiling branches strictly equal (===).
const updatedData = set(nameLens, "Alicia", data[0]);

/* 
  updatedData: { id: 1, user: { profile: { name: "Alicia" } } }
  Notice: `data[0]` remains completely unmodified.
*/

License

ISC