BFF

Module: bff/record

A Record is the basic entity of the data layer. In difference to regular JS objects, it has a predefined set of properties. The properties are specified by "subclassing" the abstract Record constructor by calling Record.withProperties(...) and providing a properties schema. For more details, see module:bff/record.withProperties.

The major advantages of using a predefined (i.e. known and finite) set of properties are:

  • Each property gets a custom setter, that emits a change event whenever the property value changes. The setter can also do types checks on the assigned value (which it does in dev. mode).
  • The record instances can be locked using Object.preventExtensions, with the nice effect that trying to assign a value to an undeclared property will throw an error.

new (require("bff/record"))( [values])

Creates a new Record (subclass) with an optional set of initial values.

Parameters:
Name Type Argument Description
values Object | module:bff/record <optional>

An object containing initial values for the Record to be created.
Mixes In:
Source:

Methods

<static> withProperties(schema, dontPreventExtensions)

Creates a new Record constructor function, that will create Record instances with the property schema provided to this function. The various aspects of the property schema are described in detail below, but let's start with an example.

var Person = Record.withProperties({
  firstName: 'string',
  lastName: 'string',
  fullName: {
    setter: false,
    getter: function () { return this.firstName + ' ' + this.lastName; },
    dependencies: [ 'firstName', 'lastName' ],
  },
  age: {
    type: [ Number, undefined ],
    defaultValue: 0,
  },
  someData: {},
})

Here we see a schema with five properties. The first two (firstName and lastName) use a shorthand syntax to declare string properties. The fullName property is a calculated property that depends on firstName and lastName. The age property is either a number or undefined (properties can't be undefined by default), with a default value of 0. Finally, the someData property can be of any type.

Parameters:
Name Type Description
schema Object

An object describing the properties that will be part of all new instances created by the returned constructor function. Each key/value pair describes a single property. Property descriptor objects can have the following properties:

  • type: A string or array of strings specifying the type of the property. If omitted, no type checking will be performed, otherwise types are checked by applying the typeof operator to the assigned value and then checking to see if the returned type string is part of the schema types.
  • defaultValue: An initial value that will be assigned to all new instances of this property upon creation.
  • setter: A function that will be called to transform the assigned value before it is stored on the property. Shouldn't have any side effects, as it might be called internally to determine when events should be triggered.
  • getter: A function that will be run to transform the read value before it is returned. Shouldn't have any side effects, as it might be called internally to determine when events should be triggered.

All schema descriptor properties are optional. An empty schema descriptor can be replaced with any falsy value for the same effect, which means that:
someData: {}, someData: undefined, someData: null and someData: false all declares a property named someData, which can hold any type of data.

There is also a shorthand syntax for specifying typed properties, because it is such a common use case, e.g.:
aProp: String is equal to aProp: { type: String } and e.g.
aProp: [ String, undefined ] is equal to aProp: { type: [ String, undefined ] }
dontPreventExtensions boolean

All extensions of records are prevented by default (using Object.preventExtensions), but that behavior can be toggled using this flag.
Source:
Returns:

New constructor function based on the provided schema.

Type
function

toJSON()

Returns a newly created Object containing the Records's deep copied properties. The fact that this function returns an Object and not a strin is a bit misleading, but this naming convension is used for conformity reasons, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior

Source:
Returns:
Type
Object

toString()

Source:
Returns:

A human readable string representation of the Record.

Type
string

Events

change:[property name]

Emitted when the value of the property with name [property name] has changed. This event is only emitted if the assigned value actually differs from the previous one, compared using strict equality.

Parameters:
Name Type Description
newValue any

The new property value
oldValue any

The previous property value
self module:bff/record

The record that triggered the event
Source:

change

Emitted when some property value has changed. This event is only emitted if the assigned value actually differs from the previous one, compared using strict equality.

Parameters:
Name Type Description
propertyName string

The name of the record property that has changed
newValue any

The new property value
oldValue any

The previous property value
self module:bff/record

The record that triggered the event
Source:

prechange

Emitted when some property value is about to be assigned a new value. This event is always emitted upon assignment, even is the value to be assigned is the same as the current value.

Parameters:
Name Type Description
propertyName string

The name of the record property that is about to be assigned to
currentValue any

The current property value
self module:bff/record

The record that triggered the event
Source:

prechange:[property name]

Emitted when the property with name [property name] is about to be assigned a new value. This event is always emitted upon assignment, even is the value to be assigned is the same as the current value.

Parameters:
Name Type Description
currentValue any

The current property value
self module:bff/record

The record that triggered the event
Source: