@hyperfrontend/immutable-api-utils§

What is @hyperfrontend/immutable-api-utils?

@hyperfrontend/immutable-api-utils provides low-level utilities for locking object properties and methods to prevent modification. Using JavaScript's property descriptors (Object.defineProperty), it creates truly immutable APIs where neither values nor method bindings can be altered after definition.

The library offers three approaches: a TypeScript decorator (@locked()) for class methods, a functional API (lockedProps()) for bulk property locking, and descriptor builders (lockedPropertyDescriptors()) for granular control. All utilities enforce non-writable, non-configurable descriptors while maintaining correct this binding through per-instance caching.

Additionally, the library provides safe built-in copies: pre-captured references to JavaScript built-in methods that mitigate prototype pollution attacks when loaded early.

Key Features

Why Use @hyperfrontend/immutable-api-utils?

Prevents Accidental API Tampering in Shared Contexts

When exposing objects to third-party code, plugin systems, or sandboxed environments, you need guarantees that critical methods won't be overwritten. @locked() makes methods truly immutable: attempting reassignment throws a TypeError. This protects public APIs from accidental or malicious modification.

Eliminates this Binding Bugs Without Arrow Functions

Arrow functions in class fields break inheritance and bloat bundle sizes due to per-instance function creation. The @locked() decorator provides correct this binding (like arrow functions) while using efficient prototype methods. Methods are bound once per instance and cached with Symbol keys.

Simplifies Immutable Object Construction

Object.freeze() is all or nothing: every own property goes read-only, including the ones you meant to keep mutable. lockedProps() locks only the properties you name, non-writable and non-configurable, so they cannot be reassigned, redefined or deleted while the rest of the object stays ordinary. It is shallow, like Object.freeze(): a locked property holding an object still hands out an object you can mutate.

TypeScript-First with Runtime Enforcement

Unlike TypeScript readonly (compile-time only), these utilities enforce immutability at runtime. This catches bugs in JavaScript-land, during deserialization, or when interfacing with dynamically typed code. Type safety and runtime safety in one decorator.

Installation

npm install @hyperfrontend/immutable-api-utils

Quick Start

import { locked, lockedProps, lockedPropertyDescriptors } from '@hyperfrontend/immutable-api-utils'

// Decorator usage: lock methods in classes
class Counter {
  private count = 0

  @locked()
  increment() {
    this.count++
    return this.count
  }

  @locked()
  getValue() {
    return this.count
  }
}

const counter = new Counter()
counter.increment() // Works: 1
counter.increment = () => 0 // Throws: Cannot overwrite locked method

// Ensure correct `this` binding even when method is extracted
const { increment } = counter
increment() // Still works correctly, `this` remains bound

// Functional API: lock multiple properties
const config = {}
lockedProps(config, [
  ['apiKey', 'secret-key-12345'],
  ['timeout', 5000],
  ['retries', 3],
])

config.apiKey = 'hacked' // Silent fail in non-strict mode, throws in strict mode
// Throws: cannot redefine
Object.defineProperty(config, 'apiKey', { writable: true })

// Low-level descriptor creation
const obj = {}
Object.defineProperty(obj, 'version', lockedPropertyDescriptors('1.0.0', true))
// Property is non-writable, non-configurable, but enumerable

API Overview

Two jobs share one mechanism, the property descriptor. One half locks the properties of an object you own; the other half captures the built-ins before anything else can swap them. Every module under built-in-copy/ reads its global exactly once, while it is being evaluated, and re-exports what it found as a named binding: built-in-copy/object reads globalThis.Object, so its keys is the function value Object.keys held at that instant, and a later write to Object.keys lands on the global while the binding goes on answering correctly. parse does the same for JSON.parse.

The limit is worth stating plainly: this mitigates rather than prevents, and import order decides whether it works at all. A module graph evaluates in source order, so a copy is honest only when its import sits above the code that tampers. Put the untrusted import first and the capture reads an already poisoned global, returning exactly the wrong answer the global would. Treat these as entry-point imports:

// these two lines have to be evaluated first
import { keys, hasOwn } from '@hyperfrontend/immutable-api-utils/built-in-copy/object'
import { parse } from '@hyperfrontend/immutable-api-utils/built-in-copy/json'

import './vendor/analytics.js' // whatever this does to Object.keys, keys() is unaffected

There are 24 of these subpaths, each named after the global or family of globals it copies, so the one you want is spelled like the thing you were reaching for: built-in-copy/timers holds setTimeout and queueMicrotask, built-in-copy/console holds log and warn. Members that need a receiver come through as wrappers (hasOwn applies the captured Object.prototype.hasOwnProperty through a captured Reflect.apply), and constructors as create* factories such as createMap. The package root re-exports frozen namespace objects for many of these globals, which reads nicely but pulls in the whole namespace; named bindings from a subpath are what keep the rest out of your bundle.

Three entries do the locking, and they stack. lockedPropertyDescriptors is the primitive: hand it a value and it returns { value, writable: false, configurable: false, enumerable } for you to pass to Object.defineProperty. lockedProps applies that across a list, taking the target object and an array of [key, value] pairs, and returns nothing: it mutates the object you handed it. locked is the class-method decorator and the odd one out, installing an accessor whose getter binds the method to the instance once and caches it under a symbol, and whose setter throws a TypeError.

Every export, on every subpath, is in the API reference.

Use Cases

• Plugin APIs: Prevent plugins from modifying core library methods
• Sandboxed execution: Expose safe APIs to untrusted code
• Configuration objects: Lock critical config values after initialization
• Public library interfaces: Protect exported classes from mutation
• Event emitters: Prevent handler list manipulation
• Prototype pollution mitigation: Safe built-in copies reduce attack surface when loaded early
• Secure logging: Use safe console copies to prevent tampered log output
• Safe timers: Prevent timer functions from being hijacked
• Cross-origin messaging: Secure postMessage wrappers with captured references

Compatibility

CDN Usage

<!-- unpkg -->
<script src="https://unpkg.com/@hyperfrontend/immutable-api-utils"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@hyperfrontend/immutable-api-utils"></script>

<script>
  const { locked, lockedProps } = HyperfrontendImmutableApiUtils
  const { lockedPropertyDescriptors } = HyperfrontendImmutableApiUtils
</script>

Global variable: HyperfrontendImmutableApiUtils

Dependencies

None: zero external dependencies.