Skip to content

ForPairs state object since v0.2

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

(
    input: CanBeState<{[KI]: VI}>,
    pairProcessor: (KI, VI, M) -> (KO, VO, M),
    pairDestructor: ((KO, VO, M) -> ())?
) -> ForPairs<KI, VI, KO, VO, M>

Parameters

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

Object Methods

since v0.2

ForPairs: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?) -> {[KO]: VO}

Example Usage

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

local transformed = ForPairs(data, function(key, value)
    local newKey = value
    local newValue = string.upper(key)
    return newKey, newValue
end)

print(transformed:get()) --> {[1] = "ONE", [2] = "TWO" ... }

Dependency Management

ForPairs 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 = ForPairs(data, function(key, value)
    -- Fusion detects you called :get() on `multiplier`, and so adds `multiplier`
    -- as a dependency specifically for this key-value pair.
    return key * multiplier:get(), value * multiplier:get()
end)

When that dependency changes value, the specific key-value pairs using that value are recalculated.

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

Destructors

The pairDestructor callback, if provided, is called when this object swaps out an old key-value pair for a newly-generated one. It is called with the old pair as the first and second parameters, and - if provided - an extra value returned from pairProcessor as a customisable third 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 third parameter, which the user is responsible for handling properly.

Optimisations

ForPairs is the least restrictive of the For objects, allowing full access to the key-value pairs being processed. This means that very little optimisation is applied - values are always locked to the specific key they were generated for, and any change in the input's key or value will prompt a recalculation.

For other optimisations, consider using ForValues or ForKeys, which impose stricter restrictions to allow for less frequent updates and greater reuse.

Back to top