Replacing: StateObject:get()

[dphfox]

Starting with Fusion 0.3, you may see this error in your output.

StateObject:get() has been replaced by `use()` and `peek()` - see discussion #217 on GitHub.

Why is :get() problematic?

In Fusion 0.2 and earlier, :get() would automatically decide which state object you were 'currently inside' by using some internal tracking magic. If you called :get() inside of a computed's processor callback, for example, it'll connect to the state objects to detect and apply changes in the future:

local foo = Value(2)
local doubleFoo = Computed(function()
    return foo:get() * 2 -- Fusion detects this and makes `doubleFoo` listen to `foo` for changes
end)

However, in other cases, such as when you're not currently inside any such callback, :get() is completely inert and only returns the value without adding dependencies, as it is assumed you don't need dependencies added in that situation:

print(foo:get()) -- We're not in any callback, so this adds no dependencies.

This automatic detection becomes brittle in deeply nested systems. Oftentimes, :get() will be called outside of any callbacks inside of a reusable function. This silently booby-traps that function, because if you ever call it from within a callback, it'll transitively apply the dependencies from those naked :get() calls into your computed object (or other dependency-tracking state object):

local foo = Value(2)

local function innocentFunction()
    print(foo:get()) -- This shouldn't add any dependencies, right?
end

local bar = Computed(function()
    innocentFunction() -- ...right?
end)

Needless to say, this is not acceptable. It should always be clear when your code can and can't add dependencies, so you can make strong assertations about how your code works without having to review or colour every function.

What's replacing it?

Firstly, a new function is being introduced to replace naked :get() calls outside of callbacks. Fusion.peek takes a single value as an argument, and if it's a state object, it'll return the interior value:

local foo = Value(2)

print(peek(foo)) --> 2

Importantly, peek will never add dependencies. The name is reflective of this - you are only 'peeking' at the value without enacting any other action. If you use it incorrectly, for example inside of a computed object, it's really obvious that it's wrong:

local doubleFoo = Computed(function()
    return peek(foo) * 2 -- yeah, this is never going to work, ever
end)

For cases when you want your computed object (or equivalent) to listen to foo for changes, they'll now provide their own callback as an argument. This callback works identically to peek, but will add any state objects as dependencies if it's given any. By convention, it's called use:

local doubleFoo = Computed(function(use)
    return use(foo) * 2 -- now you're getting the value AND you're listening for changes
end)

Why this?

The reason this is great is because it's now impossible for a nested function to add dependencies unless you give it the use callback:

local foo = Value(2)

local function innocentFunction()
    print(peek(foo)) -- This shouldn't add any dependencies, but for real this time
end

local bar = Computed(function(use)
    innocentFunction() -- No `use`, no dependencies, no worries :)
end)

If you ever want to grant another function permission to add dependencies, you signal that permission by giving it the use callback, which now becomes a visible marker that this function has that permission:

local foo = Value(2)

-- Gotta ask for that `use` function now...
local function innocentFunction(use)
    print(use(foo))
end

local bar = Computed(function(use)
    innocentFunction(use) -- Okay, you have permission to add dependencies :)
end)

In addition to this, both functions accept constant (i.e. non-state) arguments. They're passed through directly:

print(peek(5)) --> 5

local bar = Computed(function(use)
    return use(2)
end)
print(peek(bar)) --> 2

This is especially powerful because it means you can freely mix and match constants and state objects in your code. This is particularly useful for defining flexible components, where properties can be either constants or state objects.

---

We hope that this change sets a much more stable and dependable foundation for your scripts into the future. Let us know if there's anything you find that's broken or unaccounted for :)

[autonordev]

Is there any particular reason peek is being added to the main Fusion object and not the individual StateObjects (like :get() currently is)?

[dphfox]

Is there any particular reason peek is being added to the main Fusion object and not the individual StateObjects (like :get() currently is)?

Primarily because it harms interoperability with constant values. Suppose you have a variable that can be either a constant or a state object:

local foo: CanBeState<number>

How do you read the value of foo? If it's number then you just use it as normal, but if it's StateObject<number> then you need to call :get() on it first. Either way will cause an error if foo is of the opposite type.

With a global function, this problem goes away; for constants, the value is passed through, and for state objects, the interior value is returned. It unifies the access method across both constants and state objects, which is of special importance for building things like components which need to be able to deal with both,

[plasma-node]

Understandable.

Whilst I get that Fusion is still in early beta and that I am agreeing to it breaking, it would be great to be able to upgrade to the next version with minimal changes, currently the way Omegaspace and Dracaria's UI systems work it would mean spending time recoding. It's also nice to be able to share Values to a module that does not require Fusion.

It would be nice for Values to still have these functions within their individual objects.