Options
Menu

Class GenericUnit<T, K, V>

GenericUnit is a reactive storage Unit that doesn't pertain to any specific data type.

GenericUnit accepts all data types as its value.

Learn more about Units here.
Learn more about GenericUnit here.

Just like every other Non-Primitive ActiveJS Unit:

Hierarchy

Constructors

constructor

Properties

Readonly cacheSize

cacheSize: number

Size of the cache, dictating how many values can be cached at a given time.

default

2

minimum

1

maximum

Infinity

Readonly config

config: Readonly<UnitConfig<T>>

Configured options. Combination of global-options GlobalUnitConfig and the options passed on instantiation.

Readonly events$

events$: Observable<UnitEvents<T>>

On-demand observable events.

Readonly future$

future$: Observable<T> = this.futureSubject.asObservable()

An Observable to observe future values, unlike the default Observable it doesn't replay when subscribed to, rather it waits for the next value.

Accessors

cacheIndex

  • get cacheIndex(): number

cachedValuesCount

  • get cachedValuesCount(): number

emitCount

  • get emitCount(): number

isEmpty

  • get isEmpty(): boolean

isFrozen

  • get isFrozen(): boolean

isMuted

  • get isMuted(): boolean

Access Value Methods

cachedValues

  • cachedValues(): T[]

initialValue

  • initialValue(): T

rawValue

  • rawValue(): T
  • If the Unit has a non-primitive value, use it to get access to the current value, without creating a deep-copy.

    This can come in handy if the Unit is configured to be immutable, and you want to perform a non-mutating action without creating a deep-copy of the value.

    Returns T

value

  • value(): T

Cache Navigation Methods

goBack

  • goBack(skipNilValues?: boolean): boolean

goForward

  • goForward(skipNilValues?: boolean): boolean

jump

  • jump(steps: number): boolean
  • Use this method to re-emit a value from the cache, by jumping specific steps backwards or forwards,
    without creating a new entry in the cache.

    It doesn't work if the Unit is frozen isFrozen or steps is not a number. It only works if the new calculated index is in the bounds of cachedValues,
    ie: the new-index is >= 0, and less than cachedValuesCount, but
    not equal to current cacheIndex.

    triggers

    EventUnitJump

    Parameters

    • steps: number

      Number of steps to jump in the cache, negative to jump backwards, positive to jump forwards

    Returns boolean

    true if the cache-navigation was successful, otherwise false.

jumpToEnd

  • jumpToEnd(): boolean

jumpToStart

  • jumpToStart(): boolean

Common Methods

asObservable

  • asObservable(): Observable<T>
  • Creates a new Observable using the default Observable as source. Use this to conceal other aspects of a Unit, System, Action or Cluster except the Observable part.

    Returns Observable<T>

    An Observable with the value of a Unit, System, Action or Cluster.

createStream

  • A helper method that creates a stream by subscribing to the Observable returned by the param observableProducer callback.

    Ideally the callback function creates an Observable by applying Observable.pipe.

    Just know that you should catch the error in a sub-pipe (ie: do not let it propagate to the main-pipe), otherwise as usual the stream will stop working, and will not react on any further emissions.

    Type parameters

    • R

    Parameters

    Returns Stream

replay

  • replay(): boolean

toJsonString

  • toJsonString(): string

Common Action/Units Methods

dispatch

  • Method to dispatch new value by passing the value directly, or
    by passing a value-producer-function that produces the value using the current value.

    Given a value, it either gets dispatched if it's allowed by wouldDispatch,
    or it gets ignored if not allowed.

    If the Unit is not configured to be immutable, then
    the value-producer-function (param valueOrProducer) should not mutate the current value,
    which is provided as an argument to the function.

    If you mutate the value, then the cached-value might also get mutated,
    as the cached-value is saved by reference, which can result in unpredictable state.

    triggers

    EventUnitDispatch, or EventUnitDispatchFail, depending on the success of dispatch.

    Parameters

    Returns boolean | undefined

    true if value got dispatched, otherwise false. If UnitConfig.dispatchDebounce is enabled, then it'll return undefined.

  • Method to dispatch new value by passing the value directly, or
    by passing a value-producer-function that produces the value using the current value.

    Given a value, it either gets dispatched if it's allowed by wouldDispatch,
    or it gets ignored if not allowed.

    If the Unit is not configured to be immutable, then
    the value-producer-function (param valueOrProducer) should not mutate the current value,
    which is provided as an argument to the function.

    If you mutate the value, then the cached-value might also get mutated,
    as the cached-value is saved by reference, which can result in unpredictable state.

    triggers

    EventUnitDispatch, or EventUnitDispatchFail, depending on the success of dispatch.

    Parameters

    Returns boolean | undefined

    true if value got dispatched, otherwise false. If UnitConfig.dispatchDebounce is enabled, then it'll return undefined.

Common List/Dict/Generic Units Methods

objectEntries

  • objectEntries(): [string, T[K]][]

objectKeys

  • objectKeys(): string[]

objectValues

  • objectValues(): T[K][]

select

  • select<K1>(k1: K1): Selection<T[K1], this>
  • select<K1, K2>(k1: K1, k2: K2): Selection<T[K1][K2], this>
  • select<K1, K2, K3>(k1: K1, k2: K2, k3: K3): Selection<T[K1][K2][K3], this>
  • select<K1, K2, K3, K4>(k1: K1, k2: K2, k3: K3, k4: K4): Selection<T[K1][K2][K3][K4], this>
  • select<K1, K2, K3, K4, K5>(k1: K1, k2: K2, k3: K3, k4: K4, k5: K5): Selection<T[K1][K2][K3][K4][K5], this>
  • select<K1, K2, K3, K4, K5>(k1: K1, k2: K2, k3: K3, k4: K4, k5: K5, ...path: (string | number)[]): Selection<any, this>
  • Select a nested property at a certain path in the Unit's value. It doesn't fail even if a value in middle of the path is undefined.

    It can be used to create an Observable to listen to changes in a nested property using Selection.asObservable method.

    It provides static value access through the Selection.value method. It can be helpful when the Unit is configured to be immutable, as you only clone the nested property instead of the whole value.

    example
    // create a Unit
    const unit = new DictUnit();
    
    // create a selection
    const selection = unit.select('a', 'b', 0);
    // create an Observable
    const selection$ = selection.asObservable();
    // subscribe to the selector
    selection.subscribe(value => console.log(value)) // logs undefined immediately
    
    // dispatch a value
    unit.dispatch({a: {b: ['hi', 'there']}});
    // 'hi' will get logged to the console
    
    // update a value on a different path
    unit.set('c', 'other');
    // the selector won't be triggered by this

    Type parameters

    • K1: KOf<T>

    Parameters

    • k1: K1

    Returns Selection<T[K1], this>

    A Selection object of the selected property or path.

  • Select a nested property at a certain path in the Unit's value. It doesn't fail even if a value in middle of the path is undefined.

    It can be used to create an Observable to listen to changes in a nested property using Selection.asObservable method.

    It provides static value access through the Selection.value method. It can be helpful when the Unit is configured to be immutable, as you only clone the nested property instead of the whole value.

    example
    // create a Unit
    const unit = new DictUnit();
    
    // create a selection
    const selection = unit.select('a', 'b', 0);
    // create an Observable
    const selection$ = selection.asObservable();
    // subscribe to the selector
    selection.subscribe(value => console.log(value)) // logs undefined immediately
    
    // dispatch a value
    unit.dispatch({a: {b: ['hi', 'there']}});
    // 'hi' will get logged to the console
    
    // update a value on a different path
    unit.set('c', 'other');
    // the selector won't be triggered by this

    Type parameters

    • K1: KOf<T>

    • K2: KOf<T[K1]>

    Parameters

    • k1: K1
    • k2: K2

    Returns Selection<T[K1][K2], this>

    A Selection object of the selected property or path.

  • Select a nested property at a certain path in the Unit's value. It doesn't fail even if a value in middle of the path is undefined.

    It can be used to create an Observable to listen to changes in a nested property using Selection.asObservable method.

    It provides static value access through the Selection.value method. It can be helpful when the Unit is configured to be immutable, as you only clone the nested property instead of the whole value.

    example
    // create a Unit
    const unit = new DictUnit();
    
    // create a selection
    const selection = unit.select('a', 'b', 0);
    // create an Observable
    const selection$ = selection.asObservable();
    // subscribe to the selector
    selection.subscribe(value => console.log(value)) // logs undefined immediately
    
    // dispatch a value
    unit.dispatch({a: {b: ['hi', 'there']}});
    // 'hi' will get logged to the console
    
    // update a value on a different path
    unit.set('c', 'other');
    // the selector won't be triggered by this

    Type parameters

    • K1: KOf<T>

    • K2: KOf<T[K1]>

    • K3: KOf<T[K1][K2]>

    Parameters

    • k1: K1
    • k2: K2
    • k3: K3

    Returns Selection<T[K1][K2][K3], this>

    A Selection object of the selected property or path.

  • Select a nested property at a certain path in the Unit's value. It doesn't fail even if a value in middle of the path is undefined.

    It can be used to create an Observable to listen to changes in a nested property using Selection.asObservable method.

    It provides static value access through the Selection.value method. It can be helpful when the Unit is configured to be immutable, as you only clone the nested property instead of the whole value.

    example
    // create a Unit
    const unit = new DictUnit();
    
    // create a selection
    const selection = unit.select('a', 'b', 0);
    // create an Observable
    const selection$ = selection.asObservable();
    // subscribe to the selector
    selection.subscribe(value => console.log(value)) // logs undefined immediately
    
    // dispatch a value
    unit.dispatch({a: {b: ['hi', 'there']}});
    // 'hi' will get logged to the console
    
    // update a value on a different path
    unit.set('c', 'other');
    // the selector won't be triggered by this

    Type parameters

    • K1: KOf<T>

    • K2: KOf<T[K1]>

    • K3: KOf<T[K1][K2]>

    • K4: keyof T[K1][K2][K3]

    Parameters

    • k1: K1
    • k2: K2
    • k3: K3
    • k4: K4

    Returns Selection<T[K1][K2][K3][K4], this>

    A Selection object of the selected property or path.

  • Select a nested property at a certain path in the Unit's value. It doesn't fail even if a value in middle of the path is undefined.

    It can be used to create an Observable to listen to changes in a nested property using Selection.asObservable method.

    It provides static value access through the Selection.value method. It can be helpful when the Unit is configured to be immutable, as you only clone the nested property instead of the whole value.

    example
    // create a Unit
    const unit = new DictUnit();
    
    // create a selection
    const selection = unit.select('a', 'b', 0);
    // create an Observable
    const selection$ = selection.asObservable();
    // subscribe to the selector
    selection.subscribe(value => console.log(value)) // logs undefined immediately
    
    // dispatch a value
    unit.dispatch({a: {b: ['hi', 'there']}});
    // 'hi' will get logged to the console
    
    // update a value on a different path
    unit.set('c', 'other');
    // the selector won't be triggered by this

    Type parameters

    • K1: KOf<T>

    • K2: KOf<T[K1]>

    • K3: KOf<T[K1][K2]>

    • K4: keyof T[K1][K2][K3]

    • K5: keyof T[K1][K2][K3][K4]

    Parameters

    • k1: K1
    • k2: K2
    • k3: K3
    • k4: K4
    • k5: K5

    Returns Selection<T[K1][K2][K3][K4][K5], this>

    A Selection object of the selected property or path.

  • Select a nested property at a certain path in the Unit's value. It doesn't fail even if a value in middle of the path is undefined.

    It can be used to create an Observable to listen to changes in a nested property using Selection.asObservable method.

    It provides static value access through the Selection.value method. It can be helpful when the Unit is configured to be immutable, as you only clone the nested property instead of the whole value.

    example
    // create a Unit
    const unit = new DictUnit();
    
    // create a selection
    const selection = unit.select('a', 'b', 0);
    // create an Observable
    const selection$ = selection.asObservable();
    // subscribe to the selector
    selection.subscribe(value => console.log(value)) // logs undefined immediately
    
    // dispatch a value
    unit.dispatch({a: {b: ['hi', 'there']}});
    // 'hi' will get logged to the console
    
    // update a value on a different path
    unit.set('c', 'other');
    // the selector won't be triggered by this

    Type parameters

    • K1: KOf<T>

    • K2: KOf<T[K1]>

    • K3: KOf<T[K1][K2]>

    • K4: keyof T[K1][K2][K3]

    • K5: keyof T[K1][K2][K3][K4]

    Parameters

    • k1: K1
    • k2: K2
    • k3: K3
    • k4: K4
    • k5: K5
    • Rest ...path: (string | number)[]

    Returns Selection<any, this>

    A Selection object of the selected property or path.

Common Units Methods

clear

clearCache

  • Clears the cached values, current value stays intact, but it gets removed from the cache.
    Meaning, if you dispatch a new value you can't goBack.
    To keep the last value in the cache, pass {leaveLast: true} in the param options.

    It only works if the Unit is not frozen and there's something left to clear after evaluating the param options.

    Similar to preserving the last value, you can preserve the first value by passing {leaveFirst: true}. Or preserve both first and last value by passing both options together.

    triggers

    EventUnitClearCache

    Parameters

    Returns boolean

    true if the cache was cleared, otherwise false

clearPersistedValue

  • clearPersistedValue(): boolean

clearValue

  • clearValue(): boolean

freeze

  • freeze(): void

getCachedValue

  • getCachedValue(index: number): T | undefined

mute

  • mute(): void
  • Mute the Unit, to stop emitting values as well as events, so that the subscribers are not triggered.
    All other functionalities stay unaffected. ie: cache it still updated, value is still updated.

    Note: If you subscribe to the default Observable while the Unit is muted,
    it will replay the last value emitted before muting the Unit,
    because new values are not being emitted.

    Returns void

reset

resetValue

  • resetValue(): boolean

unfreeze

  • unfreeze(): void

unmute

  • unmute(): void
  • Unmute the Unit, to resume emitting values, and events.
    If a value was dispatched while the Unit was muted, the most recent value immediately gets emitted,
    so that subscribers can be in sync again.
    However, other events$ are lost, and they will only emit on the next event.

    It only works if the Unit is muted.
    Moreover, it works even if the Unit is frozen,
    but no value will be emitted because no values would have been dispatched while the Unit was frozen.

    triggers

    EventUnitUnmute

    Returns void

wouldDispatch

  • wouldDispatch(value: T, force?: boolean): boolean
  • Given a value, this function determines whether it should be dispatched or not.
    The dispatch is denied in following circumstances:

    If the Unit is not frozen, you can bypass other dispatch-checks by passing param force = true.

    This function is used internally, when a value is dispatched dispatch.
    Even initialValue UnitConfig.initialValue dispatch has to pass this check.

    You can also use it to check if the value will be dispatched or not before dispatching it.

    Parameters

    • value: T

      The value to be dispatched.

    • Default value force: boolean = false

      Whether dispatch-checks should be bypassed or not.

    Returns boolean

    A boolean indicating whether the param value would pass the dispatch-checks if dispatched.

Other Methods

pipe

  • pipe(): Observable<T>
  • pipe<A>(op1: OperatorFunction<T, A>): Observable<A>
  • pipe<A, B>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>): Observable<B>
  • pipe<A, B, C>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>): Observable<C>
  • pipe<A, B, C, D>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>): Observable<D>
  • pipe<A, B, C, D, E>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>, op5: OperatorFunction<D, E>): Observable<E>
  • pipe<A, B, C, D, E, F>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>, op5: OperatorFunction<D, E>, op6: OperatorFunction<E, F>): Observable<F>
  • pipe<A, B, C, D, E, F, G>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>, op5: OperatorFunction<D, E>, op6: OperatorFunction<E, F>, op7: OperatorFunction<F, G>): Observable<G>
  • pipe<A, B, C, D, E, F, G, H>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>, op5: OperatorFunction<D, E>, op6: OperatorFunction<E, F>, op7: OperatorFunction<F, G>, op8: OperatorFunction<G, H>): Observable<H>
  • pipe<A, B, C, D, E, F, G, H, I>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>, op5: OperatorFunction<D, E>, op6: OperatorFunction<E, F>, op7: OperatorFunction<F, G>, op8: OperatorFunction<G, H>, op9: OperatorFunction<H, I>): Observable<I>
  • pipe<A, B, C, D, E, F, G, H, I>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>, op4: OperatorFunction<C, D>, op5: OperatorFunction<D, E>, op6: OperatorFunction<E, F>, op7: OperatorFunction<F, G>, op8: OperatorFunction<G, H>, op9: OperatorFunction<H, I>, ...operations: OperatorFunction<any, any>[]): Observable<{}>
  • Returns Observable<T>

  • Type parameters

    • A

    Parameters

    • op1: OperatorFunction<T, A>

    Returns Observable<A>

  • Type parameters

    • A

    • B

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>

    Returns Observable<B>

  • Type parameters

    • A

    • B

    • C

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>

    Returns Observable<C>

  • Type parameters

    • A

    • B

    • C

    • D

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>

    Returns Observable<D>

  • Type parameters

    • A

    • B

    • C

    • D

    • E

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>
    • op5: OperatorFunction<D, E>

    Returns Observable<E>

  • Type parameters

    • A

    • B

    • C

    • D

    • E

    • F

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>
    • op5: OperatorFunction<D, E>
    • op6: OperatorFunction<E, F>

    Returns Observable<F>

  • Type parameters

    • A

    • B

    • C

    • D

    • E

    • F

    • G

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>
    • op5: OperatorFunction<D, E>
    • op6: OperatorFunction<E, F>
    • op7: OperatorFunction<F, G>

    Returns Observable<G>

  • Type parameters

    • A

    • B

    • C

    • D

    • E

    • F

    • G

    • H

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>
    • op5: OperatorFunction<D, E>
    • op6: OperatorFunction<E, F>
    • op7: OperatorFunction<F, G>
    • op8: OperatorFunction<G, H>

    Returns Observable<H>

  • Type parameters

    • A

    • B

    • C

    • D

    • E

    • F

    • G

    • H

    • I

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>
    • op5: OperatorFunction<D, E>
    • op6: OperatorFunction<E, F>
    • op7: OperatorFunction<F, G>
    • op8: OperatorFunction<G, H>
    • op9: OperatorFunction<H, I>

    Returns Observable<I>

  • Type parameters

    • A

    • B

    • C

    • D

    • E

    • F

    • G

    • H

    • I

    Parameters

    • op1: OperatorFunction<T, A>
    • op2: OperatorFunction<A, B>
    • op3: OperatorFunction<B, C>
    • op4: OperatorFunction<C, D>
    • op5: OperatorFunction<D, E>
    • op6: OperatorFunction<E, F>
    • op7: OperatorFunction<F, G>
    • op8: OperatorFunction<G, H>
    • op9: OperatorFunction<H, I>
    • Rest ...operations: OperatorFunction<any, any>[]

    Returns Observable<{}>

subscribe

  • subscribe(observer?: PartialObserver<T>): Subscription
  • subscribe(next: null | undefined, error: null | undefined, complete: () => void): Subscription
  • subscribe(next: null | undefined, error: (error: any) => void, complete?: () => void): Subscription
  • subscribe(next: (value: T) => void, error: null | undefined, complete: () => void): Subscription
  • subscribe(next?: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription
  • Parameters

    • Optional observer: PartialObserver<T>

    Returns Subscription

  • deprecated

    Use an observer instead of a complete callback

    Parameters

    • next: null | undefined
    • error: null | undefined
    • complete: () => void
        • (): void
        • Returns void

    Returns Subscription

  • deprecated

    Use an observer instead of an error callback

    Parameters

    • next: null | undefined
    • error: (error: any) => void
        • (error: any): void
        • Parameters

          • error: any

          Returns void

    • Optional complete: () => void
        • (): void
        • Returns void

    Returns Subscription

  • deprecated

    Use an observer instead of a complete callback

    Parameters

    • next: (value: T) => void
        • (value: T): void
        • Parameters

          • value: T

          Returns void

    • error: null | undefined
    • complete: () => void
        • (): void
        • Returns void

    Returns Subscription

  • Parameters

    • Optional next: (value: T) => void
        • (value: T): void
        • Parameters

          • value: T

          Returns void

    • Optional error: (error: any) => void
        • (error: any): void
        • Parameters

          • error: any

          Returns void

    • Optional complete: () => void
        • (): void
        • Returns void

    Returns Subscription

toPromise

  • toPromise<T>(this: Observable<T>): Promise<T>
  • toPromise<T>(this: Observable<T>, PromiseCtor: typeof Promise): Promise<T>
  • toPromise<T>(this: Observable<T>, PromiseCtor: PromiseConstructorLike): Promise<T>
  • Type parameters

    • T

    Parameters

    • this: Observable<T>

    Returns Promise<T>

  • Type parameters

    • T

    Parameters

    • this: Observable<T>
    • PromiseCtor: typeof Promise

    Returns Promise<T>

  • Type parameters

    • T

    Parameters

    • this: Observable<T>
    • PromiseCtor: PromiseConstructorLike

    Returns Promise<T>