Module structures

General-purpose structural operations.

Deep Equality

Compare nested structures for structural equality:

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

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

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

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

Sealed Content

Attach hidden content to a frozen clone under a symbol key, retrievable only through the same symbol:

import { immutable, seal } from '@metreeca/core/structures';

const Meta = Symbol("meta");

const sealed = seal({ id: 1 }, Meta, { source: "cache" });

seal(sealed, Meta); // { source: "cache" }
seal({ id: 1 }, Meta); // undefined (nothing sealed under Meta)

Object.keys(sealed); // ["id"] (sealed content is not enumerable)

seal(42, Meta, "content"); // 42 (primitives are returned as-is)
Copy

Both the sealed clone and its content are deep-frozen and branded, so immutable returns them unchanged:

immutable(sealed) === sealed; // true
Copy