ngxs-synchronizers API Reference

June 19, 2021 · View on GitHub

`NgxsSyncModule`

The Angular module for this library.

class NgxsSyncModule {}

`@SyncState`

The class decorator used to create state definitions. Wraps the @State decorator from NGXS.

See the NGXS documentation for more information about @State.

function SyncState<T>(options: SyncStoreOptions<T>): ClassDecorator

options - The SyncStoreOptions used to define this state.

`SyncStoreOptions`

Interface for defining a state via @SyncState.

interface SyncStoreOptions<T> {
    name: string;
    defaults?: T;
    children?: any[];
    synchronizers?: SynchronizerDictionary<T>;
}

name - See NGXS docs.

defaults - See NGXS docs.

children - See NGXS docs.

synchronizers - The synchronizers for this state, declared as a SynchronizerDictionary.

`SynchronizerDictionary`

A dictionary of synchronizers for a given state, which is either a record of property synchronizers or a single collection synchronizer.

type SynchronizerDictionary<T> = {
    [P in keyof T]?: Type<PropertySynchronizer<T, P>>;
} | Type<CollectionSynchronizer<T>>;

namespace SynchronizerDictionary {

    function keys<T>(dict: SynchronizerDictionary<T>): Array<keyof T>;

    function isCollectionSynchronizer<T>(
        dict: SynchronizerDictionary<T>
    ): dict is Type<CollectionSynchronizer<T>>;

    function resolveSynchronizer<T>(
        dict: SynchronizerDictionary<T>,
        propKey: keyof T
    ): Type<Synchronizer<T, keyof T, unknown, unknown>>;

    function resolveSynchronizerInstance<T>(
        injector: Injector,
        dict: SynchronizerDictionary<T>,
        propKey: keyof T
    ): Synchronizer<T, keyof T, unknown, unknown>;
}

Namespace functions

`SynchronizerDictionary.keys`

function keys<T>(dict: SynchronizerDictionary<T>): Array<keyof T>

Returns the list of keys in the dictionary.

dict - The synchronizer dictionary.

`SynchronizerDictionary.isCollectionSynchronizer`

function isCollectionSynchronizer<T>(
    dict: SynchronizerDictionary<T>
): dict is Type<CollectionSynchronizer<T>>

Returns whether or not the given dictionary is a CollectionSynchronizer.

dict - The synchronizer dictionary.

`SynchronizerDictionary.resolveSynchronizer`

function resolveSynchronizer<T>(
    dict: SynchronizerDictionary<T>,
    propKey: keyof T
): Type<Synchronizer<T, keyof T, unknown, unknown>>

Resolves the synchronizer associated with the property propKey from the dictionary (or the CollectionSynchronizer).

dict - The synchronizer dictionary.

propKey - The property to resolve the synchronizer of.

`SynchronizerDictionary.resolveSynchronizerInstance`

function resolveSynchronizerInstance<T>(
    injector: Injector,
    dict: SynchronizerDictionary<T>,
    propKey: keyof T
): Synchronizer<T, keyof T, unknown, unknown>

Resolves a synchronizer instance associated with the property propKey from the dictionary (or the CollectionSynchronizer).

injector - The Angular injector.

dict - The synchronizer dictionary.

propKey - The property to resolve the synchronizer instance of.

`SyncStore`

A global state manager for interacting with synchronizers. Extends the Store class from NGXS.

See the NGXS documentation for more information about Store.

class SyncStore extends Store {

    public state<T>(syncState: SyncClass<T>): StateSelector<T>;
}

Methods

`SyncStore.state`

function state<T>(syncState: SyncClass<T>): StateSelector<T>

Method used for obtaining a StateSelector instance for a given SyncClass. StateSelector instances are cached so that the same instance will be used for each SyncClass type. If the given syncState is not a known state, the method will return null.

syncState - The state class to obtain a StateSelector for.

`SyncClass`

import { Type } from '@angular/core';

type SyncClass<T> = Type<T>;

`StateSelector`

Used to manage synchronizers and synchronization state. StateSelector objects are unique to a specific state class.

class StateSelector<T> {

    public dispatch<PropT extends keyof T>(propertyName: PropT, value: T[PropT]): Observable<T>;

    public property<PropT extends keyof T>(propertyName: PropT): Observable<T[PropT]>;
    public properties(): Observable<T>;
    public definedProperty<PropT extends keyof T>(propertyName: PropT): Observable<T[PropT]>;

    public isSyncingProperty(propertyName: keyof T): Observable<boolean>;
    public onPropertySyncing<PropT extends keyof T>(propertyName: PropT): Observable<PropT>;
    public onPropertySynced<PropT extends keyof T>(propertyName: PropT): Observable<PropT>;
    public onEveryPropertySyncing(...propertyNames: Array<keyof T>): Observable<Array<keyof T>>;
    public onEveryPropertySynced(...propertyNames: Array<keyof T>): Observable<Array<keyof T>>;
    public onSomePropertySyncing(...propertyNames: Array<keyof T>): Observable<keyof T>;
    public onSomePropertySynced(...propertyNames: Array<keyof T>): Observable<keyof T>;

    public require<RequestParamsT = never>(
        propertyNames: keyof T | Array<keyof T>,
        options?: Synchronizer.ReadOptions<RequestParamsT>
    ): Observable<T>;

    public requireProperty<PropT extends keyof T, RequestParamsT = never>(
        propertyName: PropT,
        options?: Synchronizer.ReadOptions<RequestParamsT>
    ): Observable<T[PropT]>;

    public sync<RequestParamsT = never>(
        propertyNames: keyof T | Array<keyof T>,
        options?: Synchronizer.ReadOptions<RequestParamsT>
    ): Observable<T>;

    public syncProperty<PropT extends keyof T, RequestParamsT = never>(
        propertyName: PropT,
        options?: Synchronizer.ReadOptions<RequestParamsT>
    ): Observable<T[PropT]>;

    public export<RequestParamsT = never>(
        propertyNames: keyof T | Array<keyof T>,
        options?: Synchronizer.WriteOptions<RequestParamsT>
    ): Observable<any>;
}

Methods

`StateSelector.dispatch`

function dispatch<PropT extends keyof T>(propertyName: PropT, value: T[PropT]): Observable<T>

Dispatches an action that updates the property propertyName to the given value. Returns an observable that emits after all actions have completed.

propertyName - The name of the property to update.

value - The value to set the property to.

`StateSelector.property`

function property<PropT extends keyof T>(propertyName: PropT): Observable<T[PropT]>

Returns an observable that emits the value of the property propertyName. This observable will emit every time the property's value changes.

propertyName - The name of the property to observe.

`StateSelector.properties`

function properties(): Observable<T>

Returns an observable that emits the current state value. This observable will emit every time the state is updated.

`StateSelector.definedProperty`

function definedProperty<PropT extends keyof T>(propertyName: PropT): Observable<T[PropT]>

Returns an observable that emits the value of the property propertyName only if the value is not null or undefined. This observable will emit every time the property's value changes and is not null or undefined.

propertyName - The name of the property to observe.

`StateSelector.isSyncingProperty`

function isSyncingProperty(propertyName: keyof T): Observable<boolean>

Returns an observable that emits whether or not the property propertyName is being synchronized. This observable will emit every time the property's synchronization state changes.

propertyName - The name of the property to observe the synchronization state of.

`StateSelector.onPropertySyncing`

function onPropertySyncing<PropT extends keyof T>(propertyName: PropT): Observable<PropT>

Returns an observable that emits whenever the property propertyName is starting to be synchronized. This observable will emit every time the property is starting to be synchronized. The returned observable will emit propertyName.

propertyName - The name of the property to observe the synchronization state of.

`StateSelector.onPropertySynced`

function onPropertySynced<PropT extends keyof T>(propertyName: PropT): Observable<PropT>

Returns an observable that emits whenever the property propertyName is completed being synchronized. This observable will emit every time the property is completed being synchronized. The returned observable will emit propertyName.

propertyName - The name of the property to observe the synchronization state of.

`StateSelector.onEveryPropertySyncing`

function onEveryPropertySyncing(...propertyNames: Array<keyof T>): Observable<Array<keyof T>>

Returns an observable that emits whenever all of the given properties in propertyNames are starting to be synchronized. This observable will emit every time all of the given properties are starting to be synchronized. The returned observable will emit an array of property names that are being synchronized.

propertyNames - The names of the properties to observe the synchronization states of.

`StateSelector.onEveryPropertySynced`

function onEveryPropertySynced(...propertyNames: Array<keyof T>): Observable<Array<keyof T>>

Returns an observable that emits whenever all of the given properties in propertyNames are completed being synchronized. This observable will emit every time all of the given properties are completed being synchronized. The returned observable will emit an array of property names that are completed being synchronized.

propertyNames - The names of the properties to observe the synchronization states of.

`StateSelector.onSomePropertySyncing`

function onSomePropertySyncing(...propertyNames: Array<keyof T>): Observable<Array<keyof T>>

Returns an observable that emits whenever any of the given properties in propertyNames is starting to be synchronized. This observable will emit every time any of the given properties is starting to be synchronized. The returned observable will emit an array of property names that are being synchronized.

propertyNames - The names of the properties to observe the synchronization states of.

`StateSelector.onSomePropertySynced`

function onSomePropertySynced(...propertyNames: Array<keyof T>): Observable<Array<keyof T>>

Returns an observable that emits whenever any of the given properties in propertyNames is completed being synchronized. This observable will emit every time any of the given properties is completed being synchronized. The returned observable will emit an array of property names that are completed being synchronized.

propertyNames - The names of the properties to observe the synchronization states of.

`StateSelector.require`

function require<RequestParamsT = never>(
    propertyNames: keyof T | Array<keyof T>,
    options?: Synchronizer.ReadOptions<RequestParamsT>
): Observable<T>

Conditionally invokes the read operation for the synchronizers of the given properties in propertyNames only if the property value is not yet defined. Returns an observable that emits the value of the state after the invoked synchronizer operations are completed, or the current property value if it was defined.

propertyNames - The names of the properties (or single property) to conditionally invoke the read operation of their synchronizer(s) on.

options - (Optional) The Synchronizer.ReadOptions to pass to each synchronizer's read operation when invoked.

See Synchronizer.read for more information.

`StateSelector.requireProperty`

function requireProperty<PropT extends keyof T, RequestParamsT = never>(
    propertyName: PropT,
    options?: Synchronizer.ReadOptions<RequestParamsT>
): Observable<T[PropT]>

Conditionally invokes the read operation for the synchronizer of the given property propertyName only if the property value is not yet defined. Returns an observable that emits the value of the property after the invoked synchronizer operation is completed, or the current property value if it was defined.

propertyName - The name of the property to conditionally invoke the read operation of its synchronizer on.

options - (Optional) The Synchronizer.ReadOptions to pass to the synchronizer's read operation when invoked.

See Synchronizer.read for more information.

`StateSelector.sync`

function sync<RequestParamsT = never>(
    propertyNames: keyof T | Array<keyof T>,
    options?: Synchronizer.ReadOptions<RequestParamsT>
): Observable<T>

Invokes the read operation for the synchronizers of the given properties in propertyNames. Returns an observable that emits the value of the state after the invoked synchronizer operations are completed.

propertyNames - The names of the properties (or single property) to invoke the read operation of their synchronizer(s) on.

options - (Optional) The Synchronizer.ReadOptions to pass to each synchronizer's read operation when invoked.

See Synchronizer.read for more information.

`StateSelector.syncProperty`

function syncProperty<PropT extends keyof T, RequestParamsT = never>(
    propertyName: PropT,
    options?: Synchronizer.ReadOptions<RequestParamsT>
): Observable<T[PropT]>

Invokes the read operation for the synchronizer of the given property propertyName. Returns an observable that emits the value of the property after the invoked synchronizer operation is completed.

propertyName - The name of the property to invoke the read operation of its synchronizer on.

options - (Optional) The Synchronizer.ReadOptions to pass to the synchronizer's read operation when invoked.

See Synchronizer.read for more information.

`StateSelector.export`

function export<RequestParamsT = never>(
    propertyNames: keyof T | Array<keyof T>,
    options?: Synchronizer.WriteOptions<RequestParamsT>
): Observable<any>

Invokes the write operation for the synchronizers of the given properties in propertyNames. Returns an observable that emits the combined response value after the invoked synchronizer operations are completed.

propertyNames - The names of the properties (or single property) to invoke the write operation of their synchronizer(s) on.

options - (Optional) The Synchronizer.WriteOptions to pass to each synchronizer's write operation when invoked.

See Synchronizer.write for more information.

`Synchronizer`

Base interface for all synchronizers.

interface Synchronizer<
    T,
    PropKey extends keyof T,
    ReadParamsT,
    WriteParamsT
> {
    requiredProperties?: Array<keyof T>;
    proxy?: boolean;

    read(
        requiredDetails: Partial<T>,
        options: Synchronizer.BaseOptions<T, PropKey, ReadParamsT> & Synchronizer.ReadOptions<ReadParamsT>
    ): Observable<T[PropKey]>;

    write?(
        value: T[PropKey],
        options: Synchronizer.BaseOptions<T, PropKey, WriteParamsT> & Synchronizer.WriteOptions<WriteParamsT>
    ): Observable<any>;
}

namespace Synchronizer {

    interface BaseOptions<
        T,
        PropKey extends keyof T,
        ParamsT
    > {
        propertyName: PropKey;
        requestParams?: ParamsT;
    }

    interface ReadOptions<ParamsT> {
        clearStore?: boolean;
        requestParams?: ParamsT;
    }

    interface WriteOptions<ParamsT> {
        requestParams?: ParamsT;
    }
}

Interface properties

requiredProperties - (Optional) The list of properties that are required to be defined before this synchronizer's read operation is invoked. If any of the given properties has its own synchronizer, it's read operation will be completed before invoking this synchronizer if its value is not yet defined (or if this is a proxy synchronizer).

proxy - (Optional) Whether or not this is a proxy synchronizer. A proxy synchronizer is a synchronizer that does not make its own requests, but simply transforms the state of other synchronized values. A proxy synchronizer's requiredProperties will always have their synchronizer's invoked when the proxy synchronizer itself is invoked. Defaults to false.

Interface methods

`Synchronizer.read`

function read(
    requiredDetails: Partial<T>,
    options: Synchronizer.BaseOptions<T, PropKey, ReadParamsT> & Synchronizer.ReadOptions<ReadParamsT>
): Observable<T[PropKey]>

The read operation of the synchronizer, used to retrieve a value from a remote data store. Returns an observable that emits the value retrieved from the remote data store.

requiredDetails - A partial list of state values corresponding to the properties defined in requiredProperties. Empty if no requiredProperties were defined.

options - The Synchronizer.ReadOptions to use for this operation.

`Synchronizer.write`

function write(
    value: T[PropKey],
    options: Synchronizer.BaseOptions<T, PropKey, WriteParamsT> & Synchronizer.WriteOptions<WriteParamsT>
): Observable<any>

(Optional) The write operation of the synchronizer, used to send a value to a remote data store. Returns an observable that emits the response (if any) from the remote data store after the write operation is complete.

value - The value to write to the remote data store.

options - The Synchronizer.WriteOptions to use for this operation.

Namespace functions

`Synchronizer.BaseOptions`

interface BaseOptions<
    T,
    PropKey extends keyof T,
    ParamsT
> {
    propertyName: PropKey;
    requestParams?: ParamsT;
}

The base interface for all Synchronizer operations.

propertyName - The name of the state property involved in the current operation.

requestParams - (Optional) Any request params to be passed to the remote data store.

`Synchronizer.ReadOptions`

interface ReadOptions<ParamsT> {
    clearStore?: boolean;
    requestParams?: ParamsT;
}

The interface for all Synchronizer read operations.

clearStore - (Optional) Whether or not the current property value should be cleared before invoking the read operation.

requestParams - (Optional) Any request params to be passed to the remote data store.

`Synchronizer.WriteOptions`

interface WriteOptions<ParamsT> {
    requestParams?: ParamsT;
}

The interface for all Synchronizer write operations.

requestParams - (Optional) Any request params to be passed to the remote data store.

`PropertySynchronizer`

Interface for declaring property synchronizers, which are linked to a specific state property.

interface PropertySynchronizer<
    T,
    PropKey extends keyof T,
    ReadParamsT = never,
    WriteParamsT = never
> extends Synchronizer<T, PropKey, ReadParamsT, WriteParamsT> {

    read(
        requiredDetails: Partial<T>,
        options: PropertySynchronizer.ReadOptions<T, PropKey, ReadParamsT>
    ): Observable<T[PropKey]>;

    write?(
        value: T[PropKey],
        options: PropertySynchronizer.WriteOptions<T, PropKey, WriteParamsT>
    ): Observable<any>;
}

Interface methods

`PropertySynchronizer.read`

function read(
    requiredDetails: Partial<T>,
    options: PropertySynchronizer.ReadOptions<T, PropKey, ReadParamsT>
): Observable<T[PropKey]>

See Synchronizer.read.

`PropertySynchronizer.write`

function write(
    value: T[PropKey],
    options: PropertySynchronizer.WriteOptions<T, PropKey, WriteParamsT>
): Observable<any>

See Synchronizer.write.

`CollectionSynchronizer`

Interface for declaring collection synchronizers, which manage all properties dynamically in a given state.

interface CollectionSynchronizer<
    T,
    ReadParamsT = never,
    WriteParamsT = never
> extends Synchronizer<T, keyof T, ReadParamsT, WriteParamsT> {

    read(
        requiredDetails: Partial<T>,
        options: CollectionSynchronizer.ReadOptions<T, ReadParamsT>
    ): Observable<T[keyof T]>;

    write?(
        value: T[keyof T],
        options: CollectionSynchronizer.WriteOptions<T, WriteParamsT>
    ): Observable<any>;
}

Interface methods

`CollectionSynchronizer.read`

function read(
    requiredDetails: Partial<T>,
    options: CollectionSynchronizer.ReadOptions<T, PropKey, ReadParamsT>
): Observable<T[PropKey]>

See Synchronizer.read.

`CollectionSynchronizer.write`

function write(
    value: T[PropKey],
    options: CollectionSynchronizer.WriteOptions<T, PropKey, WriteParamsT>
): Observable<any>

See Synchronizer.write.

`StateSynchronizer`

Abstract class for declaring state synchronizers, which are a special kind of aggregate PropertySynchronizer that by default invoke all of the synchronizers defined for the given state.

abstract class StateSynchronizer<
    T,
    PropKey extends keyof T,
    ReadParamsT = never,
    WriteParamsT = never
> implements PropertySynchronizer<T, PropKey, ReadParamsT, WriteParamsT> {

    constructor(
        private readonly injector: Injector,
        private readonly propertyState: SyncClass<T[PropKey]>
    );

    public read(
        _requiredDetails: Partial<T>,
        _options: PropertySynchronizer.ReadOptions<T, PropKey, ReadParamsT>
    ): Observable<T[PropKey]>;

    protected readSubset(properties: Array<keyof T[PropKey]>): Observable<T[PropKey]>;
}

Methods

`StateSynchronizer.constructor`

constructor(
    private readonly injector: Injector,
    private readonly propertyState: SyncClass<T[PropKey]>
)

injector - The Angular injector used to resolve state dependencies.

propertyState - The state class definition to invoke its synchronizer operations on.

`StateSynchronizer.read`

function read(
    _requiredDetails: Partial<T>,
    _options: PropertySynchronizer.ReadOptions<T, PropKey, ReadParamsT>
): Observable<T[PropKey]>

By default, invokes all of the synchronizers read operations defined for the given state.

_requiredDetails - Unused.

_options - Unused.

`StateSynchronizer.readSubset`

function readSubset(properties: Array<keyof T[PropKey]>): Observable<T[PropKey]>

Helper method for invoking the read synchronizer operation on a specific subset of properties. Can be used in conjunction with overriding read to override the default behavior of the state synchronizer. Returns an observable that emits when all read operations have completed.

properties - The list of properties that will have their read synchronizer operation invoked.