value-object

value-object.js

Value Object - objects that matter only as the combination of their properties. Two value objects with the same values for all their properties are considered equal.

This library provides a convenient way to define strict, immutable value objects.

Install

npm install value-object

Defining value objects

Use subclasses to define value objects with type constraints:

const ValueObject = require('value-object')

class Currency extends ValueObject.define({
  code: 'string',
  name: 'string'
}) {}

class Money extends ValueObject.define({
  currency: Currency,
  amount: 'number'
}) {}

...or don't use classes, if you prefer:

var Money = ValueObject.define({
  amount: 'number',
  currency: { code: 'string' }
})

Instantiating value objects

Use the new keyword:

const gbp = new Currency({ code: 'GBP', name: 'British Pounds' })
const price = new Money({ currency: gbp, amount: 12.34 })
const other = new Money({ currency: { code: 'USD', name: 'US Dollars' }, amount: 14.56 })

The type constraints prevent value objects from being instantiated with incorrect arguments:

new Currency({ code: 'USD', name: 123 })
// => TypeError: Currency({code:string, name:string}) called with wrong types {code:string, name:number}

new Currency({ code: 'NZD', name: 'New Zealand Dollars', colour: 'All black' })
// => TypeError: Currency({code:string, name:string}) called with {code, name, colour}

new Money({ amount: 123 })
// => TypeError: Money({currency:Currency, amount:number}) called with {amount}

Equality

Value objects are considered to be equal if their properties are equal:

gbp.isEqualTo(new Currency({ code: 'GBP', name: 'British Pounds' }))
// => true

gbp.isEqualTo(new Currency({ code: 'EUR', name: 'Euros' }))
// => false

const gbpPrice = new Money({ amount: 123, currency: gbp })
const eurPrice = new Money({ amount: 123, currency: eur })
gbpPrice.isEqualTo(eurPrice)
// => false

eurPrice.isEqualTo(new Money({ amount: 123, currency: eur }))
// => true

Array values

To specify array values wrap the type definition (e.g. 'number', Date) in []

class Point extends ValueObject.define({
  x: 'number',
  y: 'number'
}) {}

class Polygon extends ValueObject.define({
  vertices: [Point] // instances of Point
}) {}

Creating new value objects from existing value objects

Use with(newAttributes) to create new value objects

var salePrice = price.with({ amount: 12.00 })
salePrice.currency.code
// => 'GBP'

Converting value objects to JSON

Use toJSON() to create an object that can be passed to JSON.stringify()

JSON.stringify(gbp.toJSON())
// => '{"__type__":"Currency","code":"GBP","name":"British Pounds"}'

Converting value objects from JSON

Use ValueObject.deserializeForNamespaces() to create a deserialize function that can turn the resulting JSON string back into objects

const deserialize = ValueObject.deserializeForNamespaces([{ Currency }])
const gbp2 = deserialize('{"__type__":"Currency","code":"GBP","name":"British Pounds"}')
gbp2.isEqualTo(gbp)
// => true

Immutability

Value objects cannot be updated. Use strict mode to throw errors when attempts to set property values are made.

gbp.code = 'USD'
// TypeError:Cannot assign to read only property 'amount' of object '#<Currency>