TypeScript library to ensure objects are immutable in development-time, compile-time, and runtime.
The highest level of protection that a JavaScript engine provides against improper and unexpected changes is in runtime: the ability to freeze objects. Any assignment to a frozen object's property will result in an error being thrown during execution of the script, but only when the script is running in 'strict mode.'
Meanwhile, TypeScript prevents improper assignments through (careful and precise) type declarations. TypeScript-based IDE (integrated development environment) tooling will flag up incorrect assignments during development, and your TypeScript transpiler of choice will fail to transpile code if a variable or property assignment is contrary to its type declaration.
This small library aims to reconcile runtime protection provided by JavaScript's Object.freeze(...)
with the development-time and transpile-time protection provided by TypeScript's type declarations.
Simply add the package to your 'npm' project using an import statement:
npm install @parkour-ops/freeze-thaw
Simply import the functions you would like to use as follows:
This is the Node.js default.
const { makeCopy, makeFrozenCopy, freeze, thaw } = require("@parkour-ops/freeze-thaw");
import { makeCopy, makeFrozenCopy, freeze, thaw } from "@parkour-ops/freeze-thaw";
This package provides the following functions:
// start with some object, array, or function, (or anything)
const someObject = { /*...*/ };
// *** deep copy the object ***
const myCopy = makeCopy(someObject);
// test: check if both variables reference the same thing:
console.log(myCopy === someObject);
// => false
// start with some object, array, or function, (or anything)
const someObject = {
errorCode: "!!!## ERRORRRRRRR ##!!!"
};
// *** freeze the object to make it read-only ***
const sameObjectWithReadOnlyTyping = freeze(someObject);
// test: check if both variables reference the same thing:
console.log(sameObjectWithReadOnlyTyping === someObject);
// => true
// start with some object, array, or function, (or anything)
const someObject = {
errorCode: "!!!## ERRORRRRRRR ##!!!"
};
// *** deep copy the object as read-only ***
const myReadOnlyCopy = makeFrozenCopy(someObject);
// test: check if both variables reference the same thing:
console.log(myReadOnlyCopy === someObject);
// => false
Note: since JavaScript runtime does not allow objects 'frozen' with Object.freeze(...)
to be 'unfrozen`, this is actually just a deep copy!
The difference between thaw(input)
and makeCopy(input)
is that thaw(input)
actually removes the readonly
marker from the properties' type declarations.
// start with some frozen/read-only object:
const someReadOnlyObject = freeze({
errorCode: "!!!## ERRORRRRRRR ##!!!"
});
// make a writeable copy
const myWriteableCopy = thaw(someReadOnlyObject);
// test: check if both variables reference the same thing:
console.log(myWriteableCopy === someObject);
// => false
lodash.clonedeep
, used for deep cloning objects.