Mixed-in instance methods and properties

Instances of ObservableArray 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:

class MyArray extends ObservableArray {
  static items = String;
}

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

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

Mixed-in type methods and properties

Extended ObservableArray classes 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:

class MyArray extends ObservableArray {
  static items = String;
}

canReflect.onInstancePatches( MyList, ( instance, patches ) => {

} );

Using

The can-observable-array package exports a ObservableArray class. It can be used with new to create observable lists. For example:

import { ObservableArray } from "can/everything";
const list = new ObservableArray([ "a", "b", "c" ]);
console.log(list[ 0 ]); //-> "a";

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

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

import { ObservableArray, type } from "can/everything";

class StringList extends ObservableArray {
  static items = {
    type: type.convert(String)
  }
}

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

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

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

import { ObservableArray, ObservableObject, type } from "can/everything";

class Todo extends ObservableObject {
  static props = {
    complete: false
  };
}

class TodoList extends ObservableArray {
  static items = type.convert(Todo);
  get completed() {
    return this.filter( { complete: true } );
  }
}

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

Finally, ObservableArray instances are observable, so you can use the can-event-queue/map/map methods to listen to its [can-observable-array/AddEvent], [can-observable-array/LengthEvent], [can-observable-array/RemoveEvent], and [can-observable-array/PropertyNameEvent] events:

import { ObservableArray } from "can/everything";
const people = new ObservableArray([ "alice", "bob", "eve" ]);

people.on( "add", ( ev, items, index ) => {
    console.log( "add", items, index );
} ).on( "remove", ( ev, items, index ) => {
    console.log( "remove", items, index );
} ).on( "length", ( 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