ReactivePublisherSchema

The ReactivePublisherSchema class is used to define the data pipeline which handles observed values from ReactiveState or ReactiveStream objects. One thing worth noting is that these data pipelines get compiled into lua functions, so their execution is highly performant.

Stages

It’s important to understand the two stages of a publisher’s data pipeline.

The first stage involves applying transformations and filters to the published values. The former is accomplished via methods such as :Map() and simply transform the published values from one value to another, passing the result to the next step of the data pipeline. Filtering is accomplished via the :Ignore*() methods which either allow the current value through to the next step of the data pipeline or prevent any further execution of the data pipeline. There may be any number of transformations and filters defined in any order on the publisher schema object.

The second stage is handling the result of the data pipeline and performing some action with it. This is accomplished with the :Call*() and :AssignToTableKey() methods. There must be exactly one of these methods called on the publisher schema and defines the end of the data pipeline. These methods commit the schema and return a ReactivePublisher object.

Share

There are often situations where the first few steps of a data pipeline are common between different data pipelines and it’s advantageous to reuse the intermediate value rather than needing to duplicate all the logic (and CPU cycles to execute the pipeline). The :Share() method is used to designate that the value at that point in the data pipeline should be saved and shared across multiple subsequent data pipelines. This method returns a ReactivePublisherSchemaShared object which has most of the same methods, but allows continuing the data pipeline from the steps that would otherwise commit it (i.e. :CallMethod()) at which point the previuosly-saved intermediate value is sent to any following data pipeline steps. The data pipeline is finally committed via the :EndShare() method. See the example below for what this looks like in practice.

Flat Map

In more advanced cases, it’s desirable to be able to transform published values into a new publisher. The :FlatMapCall*() methods are used for this, where the first argument specifies a function which gets published values and returns a new publisher, with the values from that new publisher then being handled by the specified function / method.

Example

Here’s an example which creates a publisher from an expression and shares its value to show / hide add and subtract buttons within a numeric input when the input is focused or hovered.

self._state:Publisher([[subAddEnabled and (mouseOver or hasFocus)]])
   :Share()
   :CallMethod(self._subIcon, "SetShown")
   :CallMethod(self._subBtn, "SetShown")
   :CallMethod(self._addIcon, "SetShown")
   :CallMethod(self._addBtn, "SetShown")
   :EndShare()

Here’s another example for an input field which can optionally have a border color as well as showing the border as red when the input’s value is invalid.

self._state:Publisher([[borderColor or not isValid]])
   :Share()
   :CallMethod(self._borderTexture, "SetShown")
   :ReplaceBooleanWith(BORDER_THICKNESS, 0)
   :CallMethod(self._backgroundTexture, "SetInset")
   :EndShare()
self._state:CallMethod([[isValid and borderColor or "FEEDBACK_RED"]])
   :CallMethod(self._borderTexture, "SetColor")

Memory Management

The lifecycle of publisher schema objects is owned entirely by LibTSMReactive. They are acquired exclusively via methods on ReactiveState and ReactiveStream objects and are recycled internally when they are committed.

API

class ReactivePublisherSchemaBase: Class

IsShared(self: ReactivePublisherSchemaBase): boolean

Returns whether or not this is a shared publisher.

Map(
    self: <T: ReactivePublisherSchemaBase>,
    map: string | number | table | fun(value: any, arg: any): any,
    arg: any
): <T: ReactivePublisherSchemaBase>

Map published values to another value.

Parameters:

• map (string | number | table | fun(value: any, arg: any): any) – Either a map function, table key (string or number) to index, method call (in the form “MyMethod()”), or lookup table

• arg (any) – An additional argument to pass to a map function

MapNonNil(
    self: <T: ReactivePublisherSchemaBase>,
    map: string | fun(value: any, arg: any): any,
    arg: any
): <T: ReactivePublisherSchemaBase>

Map non-nil publishes values to another value.

Parameters:

• map (string | fun(value: any, arg: any): any) – Either a map function or method call (in the form “MyMethod()”) for non-nil values

• arg (any) – An additinoal argument to pass to the map function or method

CoalesceNil(self: <T: ReactivePublisherSchemaBase>, value: any): <T: ReactivePublisherSchemaBase>

Coalesces nil published values to a specific value.

Parameters:

value (any) – The value to map to

InvertBoolean(self: <T: ReactivePublisherSchemaBase>): <T: ReactivePublisherSchemaBase>

Invert published boolean values.

ToBooleanEquals(self: <T: ReactivePublisherSchemaBase>, value: any): <T: ReactivePublisherSchemaBase>

Map published values to a boolean based on whether or not it equals the specified value.

Parameters:

value (any) – The value to compare with

ToBooleanNotEquals(self: <T: ReactivePublisherSchemaBase>, value: any): <T: ReactivePublisherSchemaBase>

Map published values to a boolean based on whether or not it equals the specified value.

Parameters:

value (any) – The value to compare with

ToBooleanGreaterThanOrEquals(
    self: <T: ReactivePublisherSchemaBase>,
    value: string | number
): <T: ReactivePublisherSchemaBase>

Map published values to a boolean based on whether or not it is greater than or equal to the specified value.

Parameters:

value (string | number) – The value to compare with

ToBooleanLessThanOrEquals(
    self: <T: ReactivePublisherSchemaBase>,
    value: string | number
): <T: ReactivePublisherSchemaBase>

Map published values to a boolean based on whether or not it is less than or equal to the specified value.

Parameters:

value (string | number) – The value to compare with

ToStringFormat(
    self: <T: ReactivePublisherSchemaBase>,
    formatStr: string
): <T: ReactivePublisherSchemaBase>

Map published values as arguments to a format string.

Parameters:

formatStr (string) – The string to format with the published values

ReplaceWith(self: <T: ReactivePublisherSchemaBase>, value: any): <T: ReactivePublisherSchemaBase>

Replaces published values with the specific value.

Parameters:

value (any) – The value to replace with

ReplaceBooleanWith(
    self: <T: ReactivePublisherSchemaBase>,
    trueValue: any,
    falseValue: any
): <T: ReactivePublisherSchemaBase>

Replaces published boolean values with the specified true / false values.

Parameters:

• trueValue (any) – The value to replace with to if true

• falseValue (any) – The value to replace with to if false

IgnoreIfEquals(
    self: <T: ReactivePublisherSchemaBase>,
    value: boolean | string | number | nil,
    key?: string | number
): <T: ReactivePublisherSchemaBase>

Ignores published values which equal the specified value.

Parameters:

• value (boolean | string | number | nil) – The value to compare against

• key? (string | number) – The key to access for filtering

IgnoreIfNotEquals(
    self: <T: ReactivePublisherSchemaBase>,
    value: boolean | string | number | nil,
    key?: string | number
): <T: ReactivePublisherSchemaBase>

Ignores published values which don’t equal the specified value.

Parameters:

• value (boolean | string | number | nil) – The value to compare against

• key? (string | number) – The key to access for filtering

IgnoreNil(self: <T: ReactivePublisherSchemaBase>): <T: ReactivePublisherSchemaBase>

Ignores published values if it’s nil.

IgnoreDuplicates(
    self: <T: ReactivePublisherSchemaBase>,
    hashFunc?: string
): <T: ReactivePublisherSchemaBase>

Ignores duplicate published values.

Parameters:

hashFunc? (string) – A method call (in the form “MyMethod()”) to calculate the hash to check for equality

IgnoreDuplicatesWithKeys(self: <T: ReactivePublisherSchemaBase>, ...: string): <T: ReactivePublisherSchemaBase>

Ignores duplicate published values by checking the specified keys.

Parameters:

... (string) – Keys to compare to detect duplicate published values

Print(self: <T: ReactivePublisherSchemaBase>, tag?: string): <T: ReactivePublisherSchemaBase>

Prints published values and passes them through for debugging purposes.

Parameters:

tag? (string) – An optional tag to add to the prints

CallMethod(
    self: <T: ReactivePublisherSchemaBase>,
    obj: table,
    method: string,
    arg: any
): <T: ReactivePublisherSchemaBase>

Calls a method with the published values.

Parameters:

• obj (table) – The object to call the method on

• method (string) – The name of the method to call with the published values

• arg (any) – An additional argument to pass to the method

CallFunction(
    self: <T: ReactivePublisherSchemaBase>,
    func: fun(value: any, arg: any),
    arg: any
): <T: ReactivePublisherSchemaBase>

Calls a function with the published values.

Parameters:

• func (fun(value: any, arg: any)) – The function to call with the published values

• arg (any) – An additional argument to pass to the function

AssignToTableKey(
    self: <T: ReactivePublisherSchemaBase>,
    tbl: table,
    key: string
): <T: ReactivePublisherSchemaBase>

Assigns published values to the specified key in the table.

Parameters:

• tbl (table) – The table to assign the published values into

• key (string) – The key to assign the published values at

FlatMapCallMethod(
    self: <T: ReactivePublisherSchemaBase>,
    map: fun(value: any): ReactivePublisherSchema,
    obj: table,
    method: string,
    arg: any
): <T: ReactivePublisherSchemaBase>

Maps published values to a new publisher which is owned by the current publisher and call a method with values it publishes.

Parameters:

• map (fun(value: any): ReactivePublisherSchema) – A function which takes a published value and returns a new publisher

• obj (table) – The object to call the method on

• method (string) – The name of the method to call with the published values

• arg (any) – An additional argument to pass to the method

FlatMapCallFunction(
    self: <T: ReactivePublisherSchemaBase>,
    map: fun(value: any): ReactivePublisherSchema,
    func: fun(value: any),
    arg: any
): <T: ReactivePublisherSchemaBase>

Maps published values to a new publisher which is owned by the current publisher and call a function with values it publishes.

Parameters:

• map (fun(value: any): ReactivePublisherSchema) – A function which takes a published value and returns a new publisher

• func (fun(value: any)) – The function to call with the published values

• arg (any) – An additional argument to pass to the function

class ReactivePublisherSchema: ReactivePublisherSchemaBase

Share(self: ReactivePublisherSchema): ReactivePublisherSchemaShared

Shares the result of the publisher at the current point in the chain.

class ReactivePublisherSchemaShared: ReactivePublisherSchemaBase

EndShare(self: ReactivePublisherSchemaShared): ReactivePublisher

Ends the share.