Mixed-in instance methods and properties

Instances of DefineList have all methods and properties from can-event-queue/map/map:

• addEventListener - Register an event handler to be called when an event is dispatched.

• @can.getWhatIChange - Return observables whose values are affected by attached event handlers

• @can.isBound - Return if the observable is bound to.

• @can.offKeyValue - Unregister an event handler to be called when an event is dispatched.

• @can.onKeyValue - Register an event handler to be called when a key value changes.

• dispatch - Dispatch event and key binding handlers.

• listenTo - Listen to an event and register the binding for simplified unbinding.

• off - A shorthand method for unbinding an event.

• on - A shorthand method for listening to event.

• one - Register an event handler that gets called only once.

• removeEventListener - Unregister an event handler to be called when an event is dispatched.

• stopListening - Stops listening for registered event handlers.

Example:

const MyList = DefineList.extend( { "#": "string" } );

const listInstance = new MyList( [ "a", "b" ] );

listInstance.on( "length", function( event, newLength, oldLength ) { /* ... */ } );

Mixed-in type methods and properties

Extended DefineList constructor functions have all methods and properties from can-event-queue/type/type:

• @can.offInstanceBoundChange - Stop listening to when an instance's bound status changes.

• @can.offInstancePatches - Stop listening to patch changes on any instance.

• @can.onInstanceBoundChange - Listen to when any instance is bound for the first time or all handlers are removed.

• @can.onInstancePatches - Listen to patch changes on any isntance.

Example:

const MyList = DefineList.extend( { "#": "string" } );

canReflect.onInstancePatches( MyList, function( instance, patches ) {

} );

Use

The can-define/list/list module exports a DefineList constructor function. It can be used with new to create observable lists that behave very similar to Arrays. For example:

const list = new DefineList( [ "a", "b", "c" ] );
list[ 0 ]; //-> "a";

list.push( "x" );
list.pop(); //-> "x"

It can also be extended to define custom observable list types with extend. For example, the following defines a StringList type where every item is converted to a string by specifying the items definition (#):

const StringList = DefineList.extend( {
    "#": "string"
} );

const strings = new StringList( [ 1, new Date( 1475370478173 ), false ] );

strings[ 0 ]; //-> "1"
strings[ 1 ]; //-> "Sat Oct 01 2016 20:07:58 GMT-0500 (CDT)"
strings[ 2 ]; //-> "false"

Non-numeric properties can also be defined on custom DefineList type. The following defines a completed property that returns the completed todos:

const TodoList = DefineList.extend( {
    "#": Todo,
    get completed() {
        return this.filter( { complete: true } );
    }
} );

const todos = new TodoList( [ { complete: true }, { complete: false } ] );
todos.completed.length; //-> 1

Finally, DefineList instances are observable, so you can use the can-event-queue/map/map methods to listen to its add, length, remove, and propertyName events:

const people = new DefineList( [ "alice", "bob", "eve" ] );

people.on( "add", function( ev, items, index ) {
    console.log( "add", items, index );
} ).on( "remove", function( ev, items, index ) {
    console.log( "remove", items, index );
} ).on( "length", function( ev, newVal, oldVal ) {
    console.log( "length", newVal, oldVal );
} );

people.pop(); // remove ["eve"] 2
// length 2 3

people.unshift( "Xerxes" ); // add ["Xerxes"] 1
// length 3 2

NOTE: Only changes made to indexed values using the list's set method will dispatch change events. 👍 defineList.set(0, 'newValue'); // will dispatch event 👎 defineList[0] = 'newValue'; // will NOT dispatch event