PropDefinition

Defines the type, initial value, and get, set, and serialize behavior for an observable property. These behaviors can be specified with as an Object, String, Constructor function, Array, a getter expression, or setter expression.

`Object`

Defines multiple behaviors for a single property.

{
    propertyName: {
        default: function() { /* ... */ },
        Default: Constructor,
        type: function() { /* ... */ },
        Type: Constructor,
        get: function() { /* ... */ },
        value: function() { /* ... */ },
        set: function() { /* ... */ },
        serialize: function() { /* ... */ },
        identity: Boolean
    }
}

Options

default {default()}:

Specifies the initial value of the property or a function that returns the initial value.

// A default age of `0`:
const Person = DefineMap.extend( {
    age: {
        value: 0
    },
    address: {
        value: function() {
            return { city: "Chicago", state: "IL" };
        }
    }
} );

Default {Default()}:

Specifies a function that will be called with new whose result is set as the initial value of the attribute.

// A default empty DefineList of hobbies:
const Person = DefineMap.extend( {
    hobbies: { Default: DefineList }
} );

new Person().hobbies; //-> []

type {type()}:

Specifies the type of the property. The type can be specified as either a function that returns the type coerced value or one of the types names.

const Person = DefineMap.extend( {
    age: { type: "number" },
    hobbies: {
        type: function( newValue ) {
            if ( typeof newValue === "string" ) {
                return newValue.split( "," );
            } else if ( Array.isArray( newValue ) ) {
                return newValue;
            }
        }
    }
} );

Type {Type()}:
A constructor function that takes the assigned property value as the first argument and called with new. For example, the following will call new Address(newValue) with whatever non null, undefined, or address type is set as a Person's address property.
```
const Address = DefineMap.extend( {
    street: "string",
    state: "string"
} );

const Person = DefineMap.extend( {
    address: { Type: Address }
} );
```
get {get(lastSetValue)}:
A function that specifies how the value is retrieved. The get function is converted to an async compute. It should derive its value from other values on the object. The following defines a page getter that reads from a map's offset and limit:
```
DefineMap.extend( {
    page: {
        get: function( newVal ) {
            return Math.floor( this.offset / this.limit ) + 1;
        }
    }
} );
```
A get definition makes the property computed which means it will not be enumerable by default.
value {value()}:
A function that listens to events and resolves the value of the property. This should be used when get is unable to model the right behavior. The following counts the number of times the page property changes:
```
DefineMap.extend( {
    pageChangeCount: function( prop ) {
        let count = 0;

        // When page changes, update the count.
        prop.listenTo( "page", function() {
            prop.resolve( ++count );
        } );

        // Set initial count.
        prop.resolve( count );
    }
} );
```
A value definition makes the property computed which means it will not be enumerable by default.
set {set(newVal, resolve)}:
A set function that specifies what should happen when a property is set. set is called with the result of type or Type. The following defines a page setter that updates the map's offset:
```
DefineMap.extend( {
    page: {
        set: function( newVal ) {
            this.offset = ( parseInt( newVal ) - 1 ) * this.limit;
        }
    }
} );
```
serialize {serialize()}:
Specifies the behavior of the property when serialize is called.

By default, serialize does not include computed values. Properties with a get definition are computed and therefore are not added to the result. Non-computed properties values are serialized if possible and added to the result.
```
const Todo = DefineMap.extend( {
    date: {
        type: "date",
        serialize: function( value ) {
            return value.getTime();
        }
    }
} );
```

identity {identity}:

Specifies the property that uniquely identifies instances of the type.

const Grade = DefineMap.extend("Grade",{
    classId: {type: "number", identity: true},
    studentId: {type: "number", identity: true},
    grade: "string"
});

`String`

Defines a type converter as one of the named types in types.

{
    propertyName: "typeName"
}

`function()`

Either creates a method or Defines a Type setting with a constructor function. Constructor functions are identified with isConstructorLike.

{
    propertyName: Constructor
}

{
    propertyName: function() {}
}

For example:

{
    subMap: DefineMap // <- sets Type to DefineMap
}

{
    increment: function() {
        ++this.count;
    } // <- sets method prop
}

`Array`

Defines an inline can-define/list/list Type setting. This is used as a shorthand for creating a property that is an can-define/list/list of another type.

{
    propertyName: [Constructor | propDefinitions]
}

For example:

{
    users: [ User ],
    todos: [ { complete: "boolean", name: "string" } ]
}

`GETTER`

Defines a property's get behavior with the syntax.

{
    get propertyName() { /* ... */ }
}

For example:

{
    get fullName() {
        return this.first + " " + this.last;
    }
}

This is a shorthand for providing an object with a get property like:

{
    fullName: {
        get: function() {
            return this.first + " " + this.last;
        }
    }
}

You must use an object with a get property if you want your get to take the lastSetValue or resolve arguments.

`SETTER`

Defines a property's set behavior with the set syntax.

{
    set propertyName( newValue ) { /* ... */ }
}

For example:

{
    set fullName( newValue ) {
        const parts = newVal.split( " " );
        this.first = parts[ 0 ];
        this.last = parts[ 1 ];
    }
}

This is a shorthand for providing an object with a set property like:

{
    fullName: {
        set: function(newValue){
            var parts = newVal.split(" ");
            this.first = parts[0];
            this.last = parts[1];
        }
    }
}

You must use an object with a set property if you want your set to take the resolve argument.

Use

A property definition can be defined in several ways. The Object form is the most literal and directly represents a PropDefinition object. The other forms get converted to a PropDefinition as follows:

DefineMap.extend( {
    propertyA: Object,      // -> PropertyDefinition
    propertyB: String,      // -> {type: String}
    propertyC: Constructor, // -> {Type: Constructor}
    propertyD: [ PropDefs ],  // -> {Type: DefineList.extend({"#": PropDefs})>}
    get propertyE() { /* ... */ },   // -> {get: propertyE(){ /* ... */ }}
    set propertyF( value ) { /* ... */ },   // -> {set: propertyF(value){ /* ... */ }}
    method: Function
} );

Within a property definition, the available properties and their signatures look like:

DefineMap.extend({
  property: {
    get: function(lastSetValue, resolve){...},
    set: function(newValue, resolve){...},

    type: function(newValue, prop){...}| Array<PropertyDefinition> | PropertyDefinition,
    Type: Constructor | Array<PropertyDefinition> | PropertyDefinition,

    default: function(){...},
    Default: Constructor,

    serialize: Boolean | function(){...}
  }
})

For example:

const Person = DefineMap.extend( "Person", {

    // a `DefineList` of `Address`
    addresses: [ Address ],

    // A `DefineMap` with a `first` and `last` property
    name: { type: { first: "string", last: "string" } },

    // A `DefineList of a ``DefineMap` with a `make` and `year` property.
    cars: { Type: [ { make: "string", year: "number" } ] }
} );

const person = new Person( {
    addresses: [ { street: "1134 Pinetree" } ],
    name: { first: "Kath", last: "Iann" },
    cars: [ { make: "Nissan", year: 2010 } ]
} );

PropDefinition

Object

Options

String

function()

Array

GETTER

SETTER

Use

Get help

`Object`

`String`

`function()`

`Array`

`GETTER`

`SETTER`