Module deep

Deep operations on JSON-like objects and arrays.

Recursive Partial Views

Widen a JSON-like type into a subset view that accepts partial literals at every nesting level:

import type { DeepPartial } from '@metreeca/core/deep';

type Config = { server: { host: string; port: number }; tags: string[] };

const overlay: DeepPartial<Config> = { server: { port: 8080 } }; // missing keys allowed
Copy

Tuple arity, element labels, variadic segments, and index signatures are preserved while every record key is relaxed to readonly and optional.

Deep Equality

Compare nested structures for structural equality:

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

// 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/deep';

// 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

Stable Identity

Cloning is idempotent at every depth: each frozen object and array is branded, so re-freezing a clone, or any nested member extracted from it, returns the same reference rather than a fresh copy. A frozen member keeps its identity even when reached through another path or nested into a new structure:

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

const frozen = immutable({ inner: { p: 1 } });

immutable(frozen) === frozen;             // true (whole graph)
immutable(frozen.inner) === frozen.inner; // true (nested member)

immutable({ ref: frozen.inner }).ref === frozen.inner; // true (member nested into a new structure)
Copy

Type-Safe Freezing

Validate and freeze with optional type guards:

import { immutable } from '@metreeca/core/deep';
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