Skip to main content

utils

Functions​

batch​

</>
utils.batch(f: () → ...unknown) → ()

Batches any state write operation up until the given function is done running.

local text = swan.state("Hey, how is it going?")

swan.effect(function()
	print(text())
end)

utils.batch(function()
	text("Hello, World!")
	text("Bye, World!")
end) -- the previous effect will only print "Bye, World!"

utils.batch(function()
	text.value = "Oops"
end) -- be careful! If the last write operation is done through .value, the effect will also trigger! -- "Oops"

branch​

</>
utils.branch(
...: any--

The values and the branches.

) → ()

Branching function to be used within effects.

Pass a condition to be checked, and after it a function to be run if it's successful. The last value, if a function, and if not after a condition, will be threated as the "else" branch. 

local age = swan.state(16)
local role = "admin"

local bad_validator = swan.effect(function()
	if role ~= "admin" then -- admins can bypass the age verification
		assert(age() >= 18, "Your age is too low!")
	end
end) -- won't detect `age` since in the first run, the condition was false, and age() wasn't called.

local validator = swan.effect(function()
	utils.branch(
		role ~= "admin", function()
			assert(age() >= 18, "Your age is too low!")
		end
	)
end) -- will detect `age`

is_state​

</>
utils.is_state(v: T) → boolean

Returns whether the given value is a state.

local not_a_state = "Hey"
print(utils.is_state(not_a_state)) -- false

local a_state = swan.state("Cool")
print(utils.is_state(a_state)) -- true

is_proxy​

</>
utils.is_proxy(v: T) → boolean

Returns whether the given value is a proxy.

local not_a_proxy = "Hey"
print(utils.is_proxy(not_a_proxy)) -- false

local a_proxy_state = swan.proxy_state({
	hello = "world"
})
print(utils.is_proxy(a_proxy_state())) -- true

is_proxy_state​

</>
utils.is_proxy_state(v: T) → boolean

Returns whether the given value is a state holding a proxy.

local not_a_proxy_state = "Hey"
print(utils.is_proxy_state(not_a_proxy_state)) -- false
not_a_proxy_state = swan.state("Hey")
print(utils.is_proxy_state(not_a_proxy_state)) -- false

local a_proxy_state = swan.proxy_state({
	hello = "world"
})
print(utils.is_proxy_state(a_proxy_state)) -- true

get_real​

</>
utils.get_real(pr: proxy_base_hack<T>) → T

Returns the "real" value of a proxy.

local todos = swan.proxy_state {
	"go outside",
	"touch grass",
	"write more todos"
}

print(todos(), todos()[1]) -- {}, "go outside"
print(swan.get_real(todos())) --[[ {
	"go outside",
	"touch grass",
	"write more todos"
}
]]--

state_get_real​

</>
utils.state_get_real(proxy_state: state<proxy_base_hack<T>>) → T

Returns the "real" value of a state's proxy.

local todos = swan.proxy_state {
	"go outside",
	"touch grass",
	"write more todos"
}

print(todos(), todos()[1]) -- {}, "go outside"
print(swan.state_get_real(todos)) --[[ {
	"go outside",
	"touch grass",
	"write more todos"
}
]]--

clear​

</>
utils.clear(state: state<T>?) → ()

Disconnects all the effects from a specific state or in general.

local money = swan.state(10000)
local health = swan.state(100)

swan.effect(function()
	print("Your money:", money())
	print("Your health:", health())
end)

swan.effect(function()
	print("Your money (again):", money())
end)

money(100) -- "Your money: 100", "Your health: 50", "Your money (again): 100"
health(50) -- "Your money: 100", "Your health: 50"

swan.clear(health)
health(200) -- *crickets*
money(50) -- "Your money: 50", "Your health: 200", "Your money (again): 50"

swan.clear()
money(10) -- *crickets*
Show raw api
{
    "functions": [
        {
            "name": "batch",
            "desc": "Batches any state write operation up until the given function is done running.\n\n```lua\nlocal text = swan.state(\"Hey, how is it going?\")\n\nswan.effect(function()\n\tprint(text())\nend)\n\nutils.batch(function()\n\ttext(\"Hello, World!\")\n\ttext(\"Bye, World!\")\nend) -- the previous effect will only print \"Bye, World!\"\n\nutils.batch(function()\n\ttext.value = \"Oops\"\nend) -- be careful! If the last write operation is done through .value, the effect will also trigger! -- \"Oops\"\n```",
            "params": [
                {
                    "name": "f",
                    "desc": "",
                    "lua_type": "() -> ...unknown"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 565,
                "path": "src/init.luau"
            }
        },
        {
            "name": "branch",
            "desc": "[Branching](/docs/concepts#branching) function to be used within effects.\n\nPass a condition to be checked, and after it a function to be run if it's successful.\nThe last value, if a function, and if not after a condition, will be threated as the \"else\" branch.\n\n\n```lua\nlocal age = swan.state(16)\nlocal role = \"admin\"\n\nlocal bad_validator = swan.effect(function()\n\tif role ~= \"admin\" then -- admins can bypass the age verification\n\t\tassert(age() >= 18, \"Your age is too low!\")\n\tend\nend) -- won't detect `age` since in the first run, the condition was false, and age() wasn't called.\n\nlocal validator = swan.effect(function()\n\tutils.branch(\n\t\trole ~= \"admin\", function()\n\t\t\tassert(age() >= 18, \"Your age is too low!\")\n\t\tend\n\t)\nend) -- will detect `age`\n```",
            "params": [
                {
                    "name": "...",
                    "desc": "The values and the branches.",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 606,
                "path": "src/init.luau"
            }
        },
        {
            "name": "is_state",
            "desc": "Returns whether the given value is a state.\n\n```lua\nlocal not_a_state = \"Hey\"\nprint(utils.is_state(not_a_state)) -- false\n\nlocal a_state = swan.state(\"Cool\")\nprint(utils.is_state(a_state)) -- true\n```",
            "params": [
                {
                    "name": "v",
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 636,
                "path": "src/init.luau"
            }
        },
        {
            "name": "is_proxy",
            "desc": "Returns whether the given value is a proxy.\n\n```lua\nlocal not_a_proxy = \"Hey\"\nprint(utils.is_proxy(not_a_proxy)) -- false\n\nlocal a_proxy_state = swan.proxy_state({\n\thello = \"world\"\n})\nprint(utils.is_proxy(a_proxy_state())) -- true\n```",
            "params": [
                {
                    "name": "v",
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 654,
                "path": "src/init.luau"
            }
        },
        {
            "name": "is_proxy_state",
            "desc": "Returns whether the given value is a state holding a proxy.\n\n```lua\nlocal not_a_proxy_state = \"Hey\"\nprint(utils.is_proxy_state(not_a_proxy_state)) -- false\nnot_a_proxy_state = swan.state(\"Hey\")\nprint(utils.is_proxy_state(not_a_proxy_state)) -- false\n\nlocal a_proxy_state = swan.proxy_state({\n\thello = \"world\"\n})\nprint(utils.is_proxy_state(a_proxy_state)) -- true\n```",
            "params": [
                {
                    "name": "v",
                    "desc": "",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 675,
                "path": "src/init.luau"
            }
        },
        {
            "name": "get_real",
            "desc": "Returns the \"real\" value of a proxy.\n\n```lua\nlocal todos = swan.proxy_state {\n\t\"go outside\",\n\t\"touch grass\",\n\t\"write more todos\"\n}\n\nprint(todos(), todos()[1]) -- {}, \"go outside\"\nprint(swan.get_real(todos())) --[[ {\n\t\"go outside\",\n\t\"touch grass\",\n\t\"write more todos\"\n}\n]]--\n```",
            "params": [
                {
                    "name": "pr",
                    "desc": "",
                    "lua_type": "proxy_base_hack<T>"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 698,
                "path": "src/init.luau"
            }
        },
        {
            "name": "state_get_real",
            "desc": "Returns the \"real\" value of a state's proxy.\n\n```lua\nlocal todos = swan.proxy_state {\n\t\"go outside\",\n\t\"touch grass\",\n\t\"write more todos\"\n}\n\nprint(todos(), todos()[1]) -- {}, \"go outside\"\nprint(swan.state_get_real(todos)) --[[ {\n\t\"go outside\",\n\t\"touch grass\",\n\t\"write more todos\"\n}\n]]--\n```",
            "params": [
                {
                    "name": "proxy_state",
                    "desc": "",
                    "lua_type": "state<proxy_base_hack<T>>"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 721,
                "path": "src/init.luau"
            }
        },
        {
            "name": "clear",
            "desc": "Disconnects all the effects from a specific state or in general.\n\n```lua\nlocal money = swan.state(10000)\nlocal health = swan.state(100)\n\nswan.effect(function()\n\tprint(\"Your money:\", money())\n\tprint(\"Your health:\", health())\nend)\n\nswan.effect(function()\n\tprint(\"Your money (again):\", money())\nend)\n\nmoney(100) -- \"Your money: 100\", \"Your health: 50\", \"Your money (again): 100\"\nhealth(50) -- \"Your money: 100\", \"Your health: 50\"\n\nswan.clear(health)\nhealth(200) -- *crickets*\nmoney(50) -- \"Your money: 50\", \"Your health: 200\", \"Your money (again): 50\"\n\nswan.clear()\nmoney(10) -- *crickets*\n```",
            "params": [
                {
                    "name": "state",
                    "desc": "",
                    "lua_type": "state<T>?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 752,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "utils",
    "desc": "",
    "source": {
        "line": 38,
        "path": "src/init.luau"
    }
}