constancy

Constancy

The most security-hardened immutability library for JavaScript and TypeScript.

Zero-dependency, TypeScript-first immutability toolkit with multi-layered defense against tampering. Deep freeze, immutable views, snapshots, vaults, and structural hashing — all under 6KB.

Why constancy? Most "freeze" libraries stop at Object.freeze. Constancy gives you 7 levels of protection — from shallow freeze to tamper-evident vaults with hash verification — and defends against prototype pollution, builtin override attacks, and reference extraction. Supply-chain safe: zero dependencies, SLSA 3 provenance, fuzz-tested, 228+ tests at 98% coverage.

Critical Distinction: VIEW vs SNAPSHOT

This is the most important concept in constancy.

API	Model	Data frozen?	Reference severed?	Use
immutableView()	VIEW — Proxy blocks mutations through this reference	No — original still mutable	No — if you keep original ref, you can mutate	When you want to prevent access through this specific reference
snapshot()	SNAPSHOT — Clone + freeze creates true immutability	Yes — data itself is frozen	Yes — clone is independent	When you need true data immutability

Example:

const original = { count: 0 };

// immutableView() is a VIEW — blocks mutations through proxy, but original still mutable
const view = immutableView(original);
view.count = 1;        // TypeError: object is immutable
original.count = 1;    // Works! original is still mutable

// snapshot() is a SNAPSHOT — independent frozen clone
const snapshot = snapshot(original);
snapshot.count = 1;    // TypeError: frozen
original.count = 1;    // Doesn't affect snapshot

Choose immutableView() for: Runtime mutation prevention when you control the original reference. Choose snapshot() for: True data immutability, or when untrusted code could retain the original reference.

Installation

npm install constancy
# or
yarn add constancy
# or
pnpm add constancy

Requires Node.js >= 20. Zero dependencies. ESM + CommonJS.

Quick Start

import { freezeShallow, deepFreeze, immutableView, snapshot, vault, tamperEvident } from 'constancy';

// Freeze: Shallow freeze
const config = freezeShallow({ host: 'localhost', port: 3000 });
config.port = 8080; // Ignored (non-strict), throws in strict mode

// Freeze: Deep freeze — recursive
const state = deepFreeze({ user: { name: 'Alice', roles: ['admin'] } });
state.user.roles.push('user'); // Throws in strict mode

// View: Immutable proxy — throws, but original still mutable if retained
const data = immutableView({ count: 0, items: [] });
data.count = 1; // TypeError: object is immutable
// ⚠️ Original reference is still mutable if you kept it!

// Snapshot: snapshot() — clone + freeze, true immutability
const locked = snapshot({ count: 0, items: [] });
locked.count = 1; // TypeError: frozen
// Original unaffected, reference severed

// Isolation: Vault — closure isolation + copy-on-read
const secret = vault({ apiKey: 'sk-123456' });
const copy = secret.get(); // Fresh frozen copy each call
secret.get() === secret.get(); // false — always new copy

// Snapshot: Tamper-evident — hash verification vault
const protected = tamperEvident({ version: '1.0.0', data: [1, 2, 3] });
protected.assertIntact(); // Throws if hash mismatch
const fingerprint = protected.fingerprint; // Original hash

API Reference

Freeze (In-Place)

freezeShallow<T>(val: T) — Shallow Freeze

Freezes only top-level properties using native Object.freeze().

const obj = freezeShallow({ a: 1, b: { c: 2 } });
obj.a = 2;      // Ignored
obj.b.c = 3;    // Works — nested not frozen

deepFreeze<T>(val: T, options?) — Recursive Freeze

Recursively freezes all nested objects. Handles circular refs, Symbol keys, TypedArrays, and accessor descriptors.

Options:

• freezePrototypeChain?: boolean (default false) — Freeze prototype chain to defend against post-freeze poisoning

const obj = deepFreeze({ nested: { count: 0 }, tags: ['a'] });
obj.nested.count = 1; // Ignored
obj.tags.push('b');   // Ignored

// Opt-in: freeze prototype chain
const hardened = deepFreeze(MyClass.prototype, { freezePrototypeChain: true });

View (Proxy, No Clone)

immutableView<T>(obj: T, options?) — Proxy-Based VIEW

Wraps object in a Proxy that throws TypeError on ANY mutation through this reference. Does NOT freeze or clone the original.

This is a VIEW, not a snapshot. Original is still mutable if you retain the reference. Use snapshot() for true immutability.

Options:

• blockToJSON?: boolean (default false) — Prevent JSON.stringify(view) from invoking target's toJSON()

const data = immutableView({ items: [], config: { theme: 'dark' } });
data.items.push(1);              // TypeError: object is immutable
data.config.theme = 'light';     // TypeError: object is immutable

const m = immutableView(new Map([['a', 1]]), { blockToJSON: true });
m.set('b', 2);                   // TypeError: Cannot set: object is immutable
m.get('a');                      // Works — read access allowed
JSON.stringify(m);               // Blocks toJSON() invocation

isImmutableView<T>(val: any) — Check Immutable View

Returns true if value is an immutable proxy.

isImmutableView(immutableView({}));  // true
isImmutableView({});                 // false
isImmutableView(deepFreeze({}));     // false

assertImmutableView<T>(val: T) — Assert Immutable View

Throws if value is not an immutable proxy.

assertImmutableView(immutableView({}));  // OK
assertImmutableView({});                 // TypeError

immutableMapView<K, V>(map: Map<K, V>) — Read-Only Map

Wraps Map in a Proxy. All mutator methods throw.

const m = immutableMapView(new Map([['a', 1], ['b', 2]]));
m.get('a');  // 1
m.set('c', 3); // TypeError
m.delete('a'); // TypeError

immutableSetView<T>(set: Set<T>) — Read-Only Set

Wraps Set in a Proxy. All mutator methods throw.

const s = immutableSetView(new Set([1, 2, 3]));
s.has(1);    // true
s.add(4);    // TypeError
s.delete(1); // TypeError

Snapshot (Clone + Freeze)

snapshot<T>(value: T) — Clone + Deep Freeze

Creates a deep clone and recursively freezes every object. True immutability — original unaffected.

const original = { user: { isVip: false } };
const snap = snapshot(original);

original.user.isVip = true;    // original mutated
snap.user.isVip;               // false — snapshot unaffected
snap.user.isVip = true;        // TypeError — frozen

lock<T>(value: T) — Alias for snapshot()

Alternate name for snapshot(). Both are identical.

const snap = lock({ count: 0 });  // Same as snapshot()

secureSnapshot<T>(obj: T) — Hardened Snapshot

Vault with null prototype + getter-only descriptors. Max protection for critical data. Throws on accessor properties to prevent silent data loss.

const cfg = secureSnapshot({ db: { host: 'localhost', port: 5432 } });
cfg.db.host;                              // 'localhost'
cfg.db.host = 'evil';                     // TypeError (strict)
Object.defineProperty(cfg, 'db', {value: null}); // TypeError — non-configurable

// Throws if object contains accessor properties
secureSnapshot({ get x() { return 1; } }); // TypeError

tamperEvident<T>(val: T) — Hash-Verified Snapshot

Stores value in vault + computes 64-bit structural hash (djb2+sdbm). Detects any internal corruption by reaching into Map/Set/Date/RegExp internal slots.

const protected = tamperEvident({ version: '1.0', data: [1, 2, 3] });
const fingerprint = protected.fingerprint; // Original hash (base-36)

// Safe access with automatic verification
const copy = protected.get(); // Fresh frozen copy

// Detect corruption
protected.verify();           // true if intact
protected.assertIntact();     // Throws TypeError if corrupted

Isolation (Closure + Copy-on-Read)

vault<T>(val: T) — Copy-on-Read Vault

Stores a value in a sealed closure. Each get() call returns a fresh frozen copy. Reference extraction impossible.

const secret = vault({ password: 'xyz', tokens: ['token1'] });
const copy1 = secret.get();
const copy2 = secret.get();
copy1 === copy2; // false — new copy each time
copy1.tokens.push('token2'); // Copy mutated, vault unchanged
secret.get().tokens; // ['token1'] — original preserved

Verification

isDeepFrozen<T>(val: T) — Check if Deep Frozen

Verifies object and all nested objects are frozen.

const obj = deepFreeze({ nested: { count: 0 } });
isDeepFrozen(obj);                          // true
isDeepFrozen(freezeShallow({}));            // false (shallow only)
const partial = { nested: deepFreeze({}) };
isDeepFrozen(partial);                      // false (root not frozen)

assertDeepFrozen<T>(val: T) — Assert Deep Frozen

Throws if value is not deeply frozen.

assertDeepFrozen(deepFreeze({}));  // OK
assertDeepFrozen({});              // TypeError

checkRuntimeIntegrity() — Detect Post-Import Tampering

Verifies that Object.freeze and other builtins haven't been overridden post-import.

const { intact, compromised } = checkRuntimeIntegrity();
if (!intact) console.error('Environment compromised:', compromised);

Types

DeepReadonly<T>

Recursively readonly type for objects, arrays, Maps, Sets.

Freezable

Union type: object | Function.

Vault<T>

Interface for vault values: { readonly get: () => DeepReadonly<T> }.

TamperProofVault<T>

Interface for tamper-proof vaults: { readonly get, verify, assertIntact, fingerprint }.

Security: Defense Levels

Level	API	Type	Mechanism	Original Mutable?	Use Case
0	freezeShallow()	Freeze	Shallow Object.freeze()	If nested	Top-level freeze only
0	deepFreeze()	Freeze	Recursive freeze + cached builtins	Only with retained ref	Full graph immutability
1	immutableView()	View	Proxy traps	Yes, if you keep original	Runtime mutation blocking
1.5	snapshot()	Snapshot	Clone + deep freeze	No — independent copy	True immutability
1.5	immutableMapView/SetView()	View	Proxy mutator blocking	If you keep original	Collection safety
2	vault()	Snapshot	Closure isolation + copy-on-read	No — sealed	Absolute reference isolation
2.5	secureSnapshot()	Snapshot	Null proto + getter-only + non-configurable	No — sealed	Prototype pollution defense
3	tamperEvident()	Snapshot	Vault + djb2 hash verification	No — sealed	Data tampering detection

Attack Vectors Defended

• ✅ Object.freeze override → cached builtins captured at module load
• ✅ Prototype pollution → null proto in secureSnapshot(), own-property precedence
• ✅ Internal slot mutations → Proxy method blocking in immutableView()
• ✅ Array mutations → blocked via Proxy in immutableView()
• ✅ Property descriptor manipulation → non-configurable in secureSnapshot()
• ✅ Reference extraction → vault copy isolation in vault() / tamperEvident()
• ✅ Data tampering → hash verification in tamperEvident()
• ✅ Silent mutations → Proxy throws in strict + non-strict in immutableView()

TypeScript Usage

import { freezeShallow, deepFreeze, immutableView, snapshot, vault, tamperEvident } from 'constancy';
import type { DeepReadonly, Vault, TamperProofVault } from 'constancy';

CommonJS:

const { freezeShallow, deepFreeze, immutableView, snapshot, vault, tamperEvident } = require('constancy');

Performance

All operations run in sub-microsecond to single-digit microsecond range. No runtime overhead from dependencies — everything is native JS.

Operation	Object size	Throughput	Latency
deepFreeze()	3 keys	2.2M ops/s	< 1 us
snapshot()	3 keys	900K ops/s	~1 us
immutableView()	3 keys	800K ops/s	~1 us
tamperEvident()	3 keys	400K ops/s	~2 us
deepFreeze()	nested (3 levels)	300K ops/s	~3 us
immutableView()	nested (3 levels)	300K ops/s	~3 us

Benchmarked on Node.js v20, Windows 11. immutableView() is near-zero cost on creation — Proxy wrapping is lazy on property access.

Why Constancy?

Capability	Details
Zero dependencies	Eliminates supply chain risk. SLSA 3 provenance on every release.
Tiny footprint	< 6KB minified (ESM + CJS). Fully tree-shakeable.
Type-safe	Readonly<T>, DeepReadonly<T>, strict TypeScript with advanced conditional types.
7 defense levels	Ranges from shallow freeze to tamper-evident vaults with hash verification.
Battle-tested	228+ tests, 98% coverage, fuzz-tested with Jazzer.js.
Tamper-resistant	Builtins cached at module load to mitigate post-import prototype poisoning.
Clear mental model	Explicit VIEW vs SNAPSHOT semantics — no ambiguity in mutation guarantees.
Dual format	Native ESM + CJS via conditional exports. Broad runtime compatibility.

Compared to Alternatives

Feature	Object.freeze	immer	immutable.js	constancy
Deep freeze	No	No	N/A	Yes
Proxy views	No	Drafts only	No	Yes
Clone + freeze	No	No	No	Yes
Vault isolation	No	No	No	Yes
Hash verification	No	No	No	Yes
Runtime integrity	No	No	No	Yes
Zero dependencies	Yes	No	No	Yes
Bundle size	0KB	~16KB	~63KB	< 6KB

Development

npm run build       # ESM + CJS bundles
npm test            # Run tests (228+ tests)
npm run test:watch  # Watch mode
npm run test:coverage # Coverage report (98%+ lines)
npm run typecheck   # Type check
npm run fuzz        # Fuzz testing with Jazzer.js

License

MIT — DungGramer