Skip to content

ForValues state object since v0.2

Processes a table from another state object by transforming its values only.

(
    input: CanBeState<{[K]: VI}>,
    valueProcessor: (VI, M) -> (VO, M),
    valueDestructor: ((VO, M) -> ())?
) -> ForValues<K, VI, VO, M>

Parameters

  • input: CanBeState<{[K]: VI}> - the table to be processed, either as a state object or a constant value
  • valueProcessor: (VI, M) -> (VO, M) - transforms input values into new values, optionally providing metadata for the destructor alone
  • valueDestructor: ((VO, M) -> ())? - disposes of values generated by valueProcessor when they are no longer in use

Object Methods

since v0.2

ForValues:get()

Returns the current value stored in the state object.

If dependencies are being captured (e.g. inside a computed callback), this state object will also be added as a dependency.

(asDependency: boolean?) -> {[K]: VO}

Example Usage

local data = Value({
    one = 1,
    two = 2,
    three = 3,
    four = 4
})

local transformed = ForValues(data, function(value)
    local newValue = value * 2
    return newValue
end)

print(transformed:get()) --> {ONE = 2, TWO = 4 ... }

Dependency Management

ForValues objects automatically detect dependencies used inside their callback each time their callback runs. This means, when you use a function like :get() on a state object, it will register that state object as a dependency:

local multiplier = Value(2)
local data = Value({1, 2, 3, 4, 5})

local scaledData = ForValues(data, function(value)
    -- Fusion detects you called :get() on `multiplier`, and so adds `multiplier`
    -- as a dependency specifically for this value.
    return value * multiplier:get()
end)

When that dependency changes value, the specific values using that dependency are recalculated.

See the Computed docs for specifics on how dependency management works.

Destructors

The valueDestructor callback, if provided, is called when this object swaps out an old value for a newly-generated one. It is called with the old value as the first parameter, and - if provided - an extra value returned from valueProcessor as a customisable second parameter.

Destructors are required when working with data types that require destruction, such as instances. Otherwise, they are optional, so not all calculations have to specify destruction behaviour.

Fusion guarantees that values passed to destructors by default will never be used again by the library, so it is safe to finalise them. This does not apply to the customisable second parameter, which the user is responsible for handling properly.

Optimisations

ForValues does not allow access to the keys of the input table. This guarantees that all generated values are completely independent of the key they were generated for. This means that values may be moved between keys instead of being destroyed when their original key changes value. Values are only reused once - values aren't copied when there are multiple occurences of the same input.

Back to top