jwidget/collection/ArrayFilterer

Consumption

import ArrayFilterer, {startFilteringArray} from "jwidget/collection/ArrayFilterer";

Default export#

Hierarchy#

Description#

T
Value type.

ArrayFilterer binds one array to another, filling it with items of the source array a function returns a truthy value for in the same order.

const source = new BindableArray([1, 2, 3]);
const filterer = new ArrayFilterer(source, x => x % 2 === 1);
const target = filterer.target;
expect(target.native).eql([1, 3]);

// Target collection is automatically synchronized with the original collection.
source.addAll([4, 7, 1, 6]);
expect(target.native).eql([1, 3, 7, 1]);

source.move(2, 6); // move "3" item to the end
expect(target.native).eql([1, 7, 1, 3]);

// Destroy the filterer to stop synchronization.
filterer.destroy();

Features and examples

You can pass target array in a config option:

const source = new BindableArray([1, 2, 3]);
const target = new BindableArray<number>();
const filterer = new ArrayFilterer(source, x => x % 2 === 1, {target});

If you want to filter the values into a new array, use shorthand function startFilteringArray instead:

const source = new BindableArray([1, 2, 3]);
const target = startFilteringArray(source, x => x % 2 === 1);

// Destroy the target array to stop synchronization.
target.destroy();

Synchronizer rules

  • Target array must be empty before initialization.
  • Filtered items of the source array get added to target immediately on the synchronizer initialization.
  • The target array is cleared on the synchronizer destruction.
  • Target array gets synchronized with source array continuously until the synchronizer is destroyed.
  • The synchronizer requires exclusive access to the target array, i.e. you can't change its contents manually or create other synchronizers with the same target array.

Constructor#

new ArrayFilterer<T>(source: ReadonlyBindableArray<T>, test: (value: T) => boolean, config?: ArrayFilterer.Config<T>)

source
Source array.
test
Filtering criteria.
config
Filterer configuration.

Fields#

source#

readonly source: ReadonlyBindableArray<T>

Source array.
target#

readonly target: ReadonlyBindableArray<T>

Target array.

Methods#

reconfigure#

(config: ArrayFilterer.Reconfig<T>)

config
Options to modify.

Changes filterer configuration and refilters the target array.

refilterAt#

(sourceIndex: number)

sourceIndex
Index of source collection item to refilter.

Refilters an item at specified position in the source array. Call this method when the item properties change in such a way that it must be refiltered.

refilter#

()

Refilters the target array. Call this method when properties of arbitrary array items change in such a way that they must be refiltered.

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);

ArrayFilterer.Config#

T
Value type.

Configuration of ArrayFilterer.

target#

readonly target?: IBindableArray<T>

Target array.

ArrayFilterer.Reconfig#

T
Value type.

Configuration of ArrayFilterer.reconfigure method. All options are optional. If skipped, an option stays the same.

test#

readonly test?: (value: T) => boolean

New filtering criteria.

startFilteringArray#

<T>(source: ReadonlyBindableArray<T>, test: (value: T) => boolean): DestroyableReadonlyBindableArray<T>

source
Source array.
test
Filtering criteria.
returns
Target array.
Creates a new array bound to another array with ArrayFilterer.