A minimalistic javascript constant object library. It utilises Object.freeze to prevent
mutations, however it does deep-freeze objects making them truly constant.
The constant object is identical (obj === constant(obj)), so it does in fact freeze the original
objects. Accessing properties can therefore be done in the standard JS way (obj.prop or obj[propname]).
There are also convenience access methods and mutation methods supported making handling of
constant object hierarchies easy.
In general this library shares common tree branches in hierarchies. This goes so far as to return the
same object from alteration methods that do not actually modify the object where this is easily detected.
Installation
npm install --save constant.jsnpm test
This library has 100% test coverage. Pull requests are always welcome, however they will only be accepted if the test-coverage remains at 100%.
Static Functions
constant(object)
Converts an object to an constant version.
constant.parse(string)
Parses a JSON string into an constant object.
constant.is(object)
Tests if an object has been made constant.
constant.isArray(object)
Tests if an object is an Array and has been made constant.
constant.isObject(object)
Tests if an object is a plain Object and has been made constant.
constant.isDate(object)
Tests if an object is a Date and has been made constant.
constant.isRegExp(object)
Tests if an object is a RegExp and has been made constant.
Common Methods
These methods a available on all constant objects whether they be plain Objects, Arrays or Dates. All prototype methods remain available, but using modifying methods (if they have not been implemented here) will throw in strict mode or not have an effect in non-strict mode.
constantObject.mutate(path, method[, arg, ...])
This method performs a deep mutation on an object by calling one of its child's methods.
This method sets a value deep inside an object hierarchy and returns a new constant object
containing the change. The original constant remains unchanged. This method ensures that all
values that remain unchanged will be reused. If the "change" isn't actually a change the return
value will be the same object.
Creates a deep mutable version of the object. This means that the entire hierarchy will be mutable.
It will retain cyclical integrity provided there is the global Map builtin.
If that is not the case, then a call on a cyclical constant object will loop indefinitely!
Only use cyclical structures if you have a modern environment!
Similar to Object.assign in that it merges object into a constant object. It then returns a new constant object where
the properties of the argument objects have been merged in.
Works just like Array.prototype.map except on an object and that it returns a new constant object and
allows removal of an element by returning undefined.
All methods available trough Array.prototype are available on constant Array objects as well except that
modifying methods have been replaced with ones returning a new constant Array object instead.
constantArray.splice(idx, delcnt, insitem)
Just like the regular Array.prototype.splice method except that rather than returning the
deleted elements, It returns a new constant Array with the changes applied. Also inserted
elements will become constant.
All methods available trough Date.prototype are available on constant Date objects as well except that
modifying methods have been replaced with ones returning a new constant Date object instead.
constantDate.setDate()
Works just like Date.prototype.setDate except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setFullYear()
Works just like Date.prototype.setFullYear except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setHours()
Works just like Date.prototype.setHours except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setMilliseconds()
Works just like Date.prototype.setMilliseconds except that rather than modifying the date, it returns
a new constant date with the change applied.
constantDate.setMinutes()
Works just like Date.prototype.setMinutes except that rather than modifying the date, it returns a new constant
date with the change applied.
constantDate.setMonth()
Works just like Date.prototype.setMonth except that rather than modifying the date, it returns a new constant
date with the change applied.
constantDate.setSeconds()
Works just like Date.prototype.setSeconds except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setTime()
Works just like Date.prototype.setTime except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setUTCDate()
Works just like Date.prototype.setUTCDate except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setUTCFullYear()
Works just like Date.prototype.setUTCFullYear except that rather than modifying the date, it returns a new
constant date with the change applied.
constantDate.setUTCHours()
Works just like Date.prototype.setUTCHours except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setUTCMilliseconds()
Works just like Date.prototype.setUTCMilliseconds except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setUTCMinutes()
Works just like Date.prototype.setUTCMinutes except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setUTCMonth()
Works just like Date.prototype.setUTCMonth except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setUTCSeconds()
Works just like Date.prototype.setUTCSeconds except that rather than modifying the date, it returns a new constant date with the change applied.
constantDate.setYear()
Works just like Date.prototype.setYear except that rather than modifying the date, it returns a new constant date with the change applied.
Map Methods
constantMap.set(key, val)
Works just like Map.prototype.set except it returns a contant Map instance that is the altered map.
constantMap.delete(key)
Works just like Map.prototype.delete except it returns a constant Map instance that is the altered map.
constantMap.clear()
Works just like Map.prototype.clear except it returns a constant Map instance that is empty.
Set Methods
constantSet.add(val)
Works just like Set.prototype.add except it returns a constant Map instance that is empty.
constantSet.delete(val)
Works just like Set.prototype.delete except it returns a constant Map instance that is empty.
constantSet.get(idx)
Gets the value of an element of a Set by its index. This utilizes the @@iterator so for large sets this will be expensive depending on the value of idx.
constantSet.clear()
Works just like Set.prototype.clear except it returns a constant Map instance that is empty.
Custom Object Types
Some object types require more information to properly handle. This can be done by placing a property on the prototype.
function MyClass() {}MyClass.prototype[constant.COPY] = function() { var copy = new MyClass(); copy.setValue(this.getValue()); return copy;};MyClass.prototype[constant.COPY].proto = {};MyClass.prototype[constant.COPY].proto.setValue = function(val) { var mut = this.mutable(); mut.setValue(val); return constant(mut);};MyClass.isConstant = function(obj) { return constant.is(obj) && (obj[constant.COPY] === MyClass.prototype[constant.COPY]);};
In this fashion it is possible to support any arbitrary object as a constant object and add custom methods for getting
mutated versions of them.