can't find information on creating observables, particularly for array changes

[dkent600]

I am looking for information on how to observe array changes (that is, changes to the membership of arrays). The Aurelia docs contain almost nothing on this subject.

There is one section on @observable, buried under the Cheat Sheet under Custom Elements (??), but this doesn't say anything about watching for array changes.

One can find the CollectionObserver interface in the API, but only if you know to look for it, and even if you find it gives you very little useful information. For example, the argument to the subscribe method is defined with type any, which tells you nothing about how to handle the subscription.

I can't find anything beside that. Out there in internet land there isn't much more that I've so far been able to find.

Can we please have some documentation on observing arrays (and creating observables in general would be gravy)? Or am I missing something? Thanks.

[EisenbergEffect]

@jdanyow Can you expand some of our documentation on the binding engine to include using these APIs?

[dkent600]

What I figured out by running in the debugger, translated into a bit of Typescript:

Given your array: myArray: Array<T> then:

BindingEngine.collectionObserver(myArray).subscribe expects you to pass it a function that might look like this:

selectedItemsChanged(splices: Array<CollectionChangeSplice<T>>)

Where each splice represents a single array change described by CollectionChangeSplice, which is defined as:

export interface CollectionChangeSplice<T> {
    // if elements were added, how many
    addedCount: number;
    // the index at which elements were added
    index: number;
    // if elements were removed, these are them
    removed?: Array<T> 
}

The whole thing:

this.bindingEngine.collectionObserver(myArray).subscribe(selectedItemsChanged);

selectedItemsChanged(splices: Array<CollectionChangeSplice<T>>) {
    for (let splice of splices) {
         // do something...
    }
}

[EisenbergEffect]

Looks correct to me. One other detail is that the subscribe method returns a subscription object, with a dispose method you can call to clean things up when you are done. @jdanyow Can you confirm the correctness of all the above and provide any other relevant comentary?

[Vheissu]

As part of the documentation efforts I've started leading, the binding story is one of the next priorities after I am done documenting the Webpack aspect. Specifically how to observe things (arrays, objects, maps), working with binding behaviours, best practices and plenty of functional examples of how the binding system works (examples of binding modes, binding behaviours and more). If you have any suggestions based on your own experiences in regards to binding @dkent600 I'd love to receive them and add them into my list.

[Alexander-Taran]

maybe can be closed

[freshcutdevelopment]

@Vheissu just wondering if you have thoughts on how we proceed with documentation issues like this one now that vNext is underway. I'd like to start helping out with issues like this but want to make sure the efforts are spent on the highest value area.