Module nested

Deep operations on nested objects and arrays.

Deep Equality

Compare nested structures for structural equality:

import { equals } from '@metreeca/core/nested';

// Objects and arrays
equals({ a: [1, 2] }, { a: [1, 2] }); // true
equals({ a: 1, b: 2 }, { b: 2, a: 1 }); // true (order-independent)
equals([1, [2, 3]], [1, [2, 3]]); // true (nested arrays)

// Primitives and functions
equals(42, 42); // true
equals(-0, +0); // false (distinguishes -0 from +0)

const fn = () => {};
equals(fn, fn); // true (same reference)
Copy

Deep Freezing

Create deeply frozen structures that prevent all mutations:

import { immutable } from '@metreeca/core/nested';

// Objects and arrays
const original = { a: [1, 2, 3], b: { c: 4 } };
const frozen = immutable(original);

frozen.a[0] = 999; // throws Error
frozen.b.c = 999; // throws Error

// Primitives and functions
immutable(42); // 42
immutable("hello"); // "hello"

const fn = () => "hello";
fn.config = { port: 3000 };
const frozenFn = immutable(fn);

frozenFn(); // "hello" (function still works)
frozenFn.config.port = 8080; // throws Error
Copy

Type-Safe Freezing

Validate and freeze with optional type guards:

import { immutable } from '@metreeca/core/nested';
import { isObject, isString, isNumber } from '@metreeca/core';

// Define a type guard
const isUser = (v: unknown): v is { name: string; age: number } =>
  isObject(v, { name: isString, age: isNumber });

// Validate and freeze in one step
const user = immutable(data, isUser);

// Memoized: repeated calls with same guard return same reference
immutable(user, isUser) === user; // true (no re-validation)

// Different guard triggers revalidation
const isAdmin = (v: unknown): v is { name: string; age: number } =>
  isUser(v) && v.age >= 18;

immutable(user, isAdmin); // revalidates
Copy