ConstConst

ConstConst is a JavaScript package that provides two functions, freeze and deepFreeze, which allow you to freeze objects and prevent any mutation. These functions return a proxy that throws an error when attempting to modify or delete any property. The deepFreeze function handles circular references properly, ensuring that all nested objects are frozen. Another set of function fakeFreeze and fakeDeepFreeze provide functionality to do updates via the original object reference.

These functions augment your toolkit for immutability-like behavior while allowing controlled modification access.

Motivation

The main motivation behind ConstConst is to simplify the usage of constant information within modules. For example, when working with game development, you may have modules that store constant stats for characters or other game entities. With ConstConst, you can export and use these constant objects without the need for deep cloning them every time.

By freezing the objects, you ensure that their values remain unchanged throughout the execution of your code. This provides immutability and prevents accidental modifications that could lead to bugs or unexpected behavior.

Beta

Since this lib is aimed towards performance, and accessing anything via proxies is comparitively slow, you can set env variable CONST_CONST_SKIP to 1 to turn off the proxying. Idea is to turn off the safety checks in production once it is thoroughly tested in development.

Installation

You can install ConstConst using npm:

npm install constconst

Usage

• freeze: returns a proxy which throws error when trying to mutate

const { freeze } = require('constconst');

const myObject = {
  prop1: 'value1',
  prop2: 'value2'
};

const myMap = new Map([
  "prop1", "value1",
  "prop2": "value2"
]);

const frozenObject = freeze(myObject);
const frozenMap = freeze(myMap);

frozenObject.prop1 = 'new value'; // ConstConstError: Cannot set property 'prop1' to value 'new value' since object is a constconst
frozenMap.set("prop1", "value3"); //ConstConstError: Cannot set property since map is a constconst
frozenMap.clear(); //ConstConstError: Cannot clear properties since map is a constconst
frozenMap.delete("prop1"); //ConstConstError: Cannot delete property since map is a constconst

• deepFreeze: similar to freeze but recursively freezes nested objects

const { deepFreeze } = require('constconst');

const obj1 = {
  prop1: 'value'
};

const obj2 = {
  prop2: obj1
};
const myMap = new Map([
  "prop1", "value1",
  "prop2": {
    "innerProp": "value2"
  }
]);

obj1.prop2 = obj2;

const frozenObject = deepFreeze(obj1);
const frozenMap = deepFreeze(myMap);
frozenObject.prop2.prop1 = 'new value'; // ConstConstError: Cannot set property 'prop1' to value 'new value' since object is a constconst
frozenMap.get("prop2").innerProp = "value3"; //// ConstConstError: Cannot set property 'prop1' to value 'new value' since object is a constconst

[!WARNING] deepFreeze function operates by modifying the fields of the passed object, replacing them with proxies to enforce immutability. To ensure the safest usage of this function, it's recommended to directly freeze the object without saving any reference to it in a variable.

[!NOTE]

• Any object which was frozen before passing to freeze or deepFreeze will be returned as is and will not be proxied either. Hence they will not produce any errors on mutation.
• freezing objects with setters and getters is not tested and is undefined behaviour.

• fakeFreeze: Modifications to the original object reflect in the returned proxy object. Modifications via the proxy trigger an error.

const { fakeFreeze } = require('constconst');

const myObject = {
  prop1: 'value1'
};

const frozenObject = fakeFreeze(myObject);

myObject.prop1 = 'value2';
console.log(frozenObject.prop1) // value2

frozenObject.prop1 = 'new value'; // ConstConstError: Cannot set property 'prop1' to value 'new value' since object is a constconst

• fakeDeepFreeze: Extends fakeFreeze capabilities to nested object also handles circular references.

const { fakeDeepFreeze } = require('constconst');

const obj1 = {
  prop1: {
    subProp1: 'value'
  }
};

const frozenObject = fakeDeepFreeze(obj1);

obj1.prop1.subProp1 = "value2";
console.log(frozenObject.prop1.subProp1); // value2

frozenObject.prop1.subProp1 = 'new value'; // ConstConstError: Cannot set property 'prop1' to value 'new value' since object is a constconst

[!NOTE] fakeFreeze and fakeDeepFreeze do not replace the fields of the original object via proxies. The proxies returned by these functions are configured such that while accessing a property, a proxy of the property is returned.

[!NOTE] Only simple Objects are frozen. Instances of any class is untouched. Best use is with simple POJOs.

Contribution Guidelines

To contribute to ConstConst, please follow these guidelines:

1. Fork and clone the repository.
2. Install project dependencies using npm install.
3. Create a new branch for your contribution.
4. Make your changes and ensure that tests pass (npm test).
5. Add new tests if applicable.
6. Use npx changeset to create a changeset:
   • Select an appropriate bump type.
   • Provide a summary (WHAT, WHY, HOW).
7. Commit the changeset file and your code changes.
8. Open a pull request against the main branch.

For more information on using Changesets, refer to the Changesets documentation.