jwidget/collection/ArrayInserter

Consumption

import ArrayInserter from "jwidget/collection/ArrayInserter";

Default export#

Hierarchy#

Description#

T
Value type.

ArrayInserter handles all messages of ReadonlyBindableArray with a combination of three callbacks:

add
An item has been added.
remove
An item has been removed.
clear
The array has been cleared.

For example, this synchronizer can be used to smoothly integrate an application with a third party API:

// External library API
declare class Chart {
    constructor(el: HTMLElement);
    addPlot(plot: Plot, at: number): void;
    removePlot(at: number): void;
    clearPlots(): void;
    terminate(): void;
}

// Our wrapper around it
class PlotChart extends Component {
    private chart: Chart;
    private inserter: ArrayInserter;

    constructor(private plots: ReadonlyBindableArray<Plot>) {
        super();
    }

    protected afterAppend() {
        super.afterAppend();
        this.chart = new Chart(this.el[0]);
        this.inserter = new ArrayInserter(this.plots, {
            add    : (plot, at) => this.chart.addPlot(plot, at),
            remove : (plot, at) => this.chart.removePlot(at),
            clear  : () => this.chart.clearPlots()
        });
    }

    protected releaseDom() {
        // Destroy the inserter to stop synchronization
        this.inserter.destroy();
        this.chart.terminate();
        super.releaseDom();
    }
}

It is easier than handling all messages of ReadonlyBindableArray, but not always as efficient.

Synchronizer rules

  • Function add is called for all items of source array on synchronizer initialization.
  • Function clear (if present) or remove is called for all items of source array on synchronizer destruction.
  • Functions are called on any collection modification.

Constructor#

new ArrayInserter<T>(source: ReadonlyBindableArray<T>, config?: ArrayInserter.Config<T>)

source
Source array.
config
Inserter configuration.

Fields#

source#

readonly source: ReadonlyBindableArray<T>

Source array.

Methods#

destroy (inherited from Class)#

(): void

Class destructor invocation method. Destroys all aggregated objects and calls destroyObject method. You must call this method explicitly from outside, because JavaScript doesn't support automatic class destructor calling.

const object = new MyClass();

// ...

// When the object is not needed anymore, destroy it.
object.destroy();

Alternatively (and optimally), you should use own method to aggregate this object inside another one.

destroyObject (inherited from Class)#

protected (): void

Class destructor implementation. Called in destroy method after destruction of all aggregated objects. The logic of class instance destruction should usually be implemented here. If you override this method, remember to call super.destroyObject() at the end of the method:

destroyObject() {
    // Release resources
    ...

    // Call superclass destructor
    super.destroyObject();
}
own (inherited from IClass)#

<T extends Destroyable>(obj: T): T

obj
Object to aggregate.
returns
obj

Aggregates the object. It means that the specified object is automatically destroyed on this object destruction. The aggregated objects are destroyed in reverse order. Returns obj object, which makes it easy to use in field definition:

private selected = this.own(new Property(false));
owning (inherited from IClass)#

(obj: Destroyable): this

obj
Object to aggregate.
returns
this

The same as own, but returns this, which makes it easy to use in object instantiation:

const items = new BindableArray().ownValues();
return new Panel(items).owning(items);

ArrayInserter.Config#

T
Value type.

Configuration of ArrayInserter.

add#

readonly add?: (item: T, index: number) => void

Callback to call when an item is added to the array or moved in the array.

remove#

readonly remove?: (item: T, index: number) => void

Callback to call when an item is removed from the array or moved in the array.

clear#

readonly clear?: (items: readonly T[]) => void

Callback to call when the array is cleared. By default, calls remove for all array items.