Values is a library for improving your application code by adding value semantics. Lots of concepts in our apps don't have a specific 'identity' - for instance every
thisx = x;thisy = y;var a = 00;var b = 00;assert a == b ; // fails - based on object identity
In contrast, Values ensures that we can compare two value objects based on their value:
var Point = vodefine"x""y";var a = 00;var b = 00;assert a == b ; // succeeds - follows value semantics
So values should be comparable by value.
valueOf is the method JS gives us to control how our objects are compared, but unfortunately it doesn't work for
===, only the inquality operators. Equality operations for objects are always based on identity. Values.js works around this by ensuring the same object is returned for the same arguments to a value object constructor.
var a = 110;var b = 110;assert a === b ;
If your value object can meaningfully use the inequality operators
> - for instance a set can be bigger than another set - then define a
valueOf method to return a comparable value (a String or Number). That'll cover all comparisons for your value object!
var Line = vodefine"x1""y1""x2""y2";// pythagoras' theoremreturn Mathsqrt Mathpowthisy2 - thisy12 + Mathpowthisx2 - thisx12 ;var a = 0 0 0 10;var b = 1919 2020;assert a > b ;
ValueObjects should be immutable. Like numbers, it doesn't make sense to 'change' (mutate) a value, you simply have a new one. Allowing values to change in place leads to confusing semantics:
var today = MutableDateLibrarytoday;var event = at: today text: "started using values" ;// `addDays()` is implemented mutably, changing the date in place and returning itvar remindAt = eventataddDays1;// fails! today has been changedassert today === MutableDateLibrarytoday ;
This really happens, and we've probably all made something that should be a value type mutable. The above is equally true for: intervals, ranges, dates and sets of any type.
Rather than requiring you to use a subclassing mechanism, Values.js exposes functions that allow you to compose your own value objects and setup their constructor and prototype as usual.
vo.memoizedConstructor is used fulfil the value equality semantics and
vo.set sets the field values immutably, also adding the
derive non-enumerable method.
varvar existing = vomemoizedConstructorPeriodarguments;ifexisting return existing;vosetthis"from""to"arguments;;vocreatePrototype;
A quick way to define VOs which don't require custom constructors (effectively just doing the above) is also provided.
var Period = vodefine"from""to";
To create a new version of a value object based on an old one, use the
derive method. This eases the creation of modified value objects, without losing the benfits of their immutability.
var periodA = 20122015;var periodB = periodAderivefrom:2013;assertperiodAfrom === 2012;assertperiodBfrom === 2013;var periodC = periodBderivefrom: 2012;assertperiodA === periodC;
The derive method takes a map of named arguments.
You'd use the
derive method to update references to values in variables or as object properties. Values are used in mutable systems, they're just immutable themselves.
If a value object of same type with the same fields exists, returns that value object. If not, will create and return a new instance.
You can supply a function as an optional third argument to specify how the paramters are hashed. This is useful if your value objects have fields that can be more quickly hashed than via JSON.stringify (the default hasher).
Sets immutable fields on instance. Also adds the
derive method as a non-enumerable property.
vo.define(fieldName1 [, fieldNameN ... ])
Defines a new value object constructor with the specified field names.
Instance method that returns a new value object with field values taken by preference from newValuesMap, with any missing fields taken from the existing value object
derive is called on.