@rbxts/rl 0.1.11

package/PESDE_README.md

@@ -0,0 +1,39 @@
+# rl
+`rl` is a simple reactive library for Luau, inspired by [Vide](https://centau.github.io/vide)'s sources and effects system.
+
+# API Reference
+You can read `rl`'s API reference [here](https://pesde.dev/packages/wiam/rl/latest/any/docs/api_ref).
+
+# Demo
+```luau
+--!strict
+
+local rl = require("path/to/rl")
+local s = rl.state
+local e = rl.effect
+
+local name = s("john", true)
+local login_year = s(2020)
+
+local login_d = e(function(last_login : number)
+	print(`{name.value}, it's been {login_year() - (last_login or 0)} years!`)
+end)
+
+login_year(2025) -- "wiam, it's been 5 years!"
+login_year(2025) -- doesn't print because value didn't change
+login_year(2025, true) -- "wiam, it's been 0 years!" - this prints since it's forced
+
+name("doe") -- doesn't print because we are reading with name.value, and not name()
+
+e(function(old_name : string)
+	print(`hey {old_name}, your name has been changed to '{name()}'`)
+end)
+
+name("jane") -- "hey doe, your name has been changed to jane"
+name("jane") -- "hey jane, your name has been changed to jane" - this one is forced by default
+
+login_d()
+login_year(2026) -- doesn't print because the effect was disconnected
+
+rl.cleanup() -- disconnect all effects
+```

package/README.md

@@ -0,0 +1,56 @@
+# rl
+`rl` is a simple reactive library for Luau, inspired by [Vide](https://centau.github.io/vide)'s sources and effects system.
+
+# Installation
+## Pesde
+```console
+# pesde add wiam/rl && pesde install
+```
+
+## Wally
+Add the following to your `wally.toml`, in the `[dependencies]` section:
+```toml
+rl = "wiam/rl@<version>"
+```
+
+Then run:
+```console
+# wally install
+```
+
+# API Reference
+You can read the API reference in `rl`'s [Pesde package page](https://pesde.dev/packages/wiam/rl/latest/any/docs/api_ref).
+
+# Demo
+```luau
+--!strict
+
+local rl = require("path/to/rl")
+local s = rl.state
+local e = rl.effect
+
+local name = s("john", true)
+local login_year = s(2020)
+
+local login_d = e(function(last_login : number)
+	print(`{name.value}, it's been {login_year() - (last_login or 0)} years!`)
+end)
+
+login_year(2025) -- "wiam, it's been 5 years!"
+login_year(2025) -- doesn't print because value didn't change
+login_year(2025, true) -- "wiam, it's been 0 years!" - this prints since it's forced
+
+name("doe") -- doesn't print because we are reading with name.value, and not name()
+
+e(function(old_name : string)
+	print(`hey {old_name}, your name has been changed to '{name()}'`)
+end)
+
+name("jane") -- "hey doe, your name has been changed to jane"
+name("jane") -- "hey jane, your name has been changed to jane" - this one is forced by default
+
+login_d()
+login_year(2026) -- doesn't print because the effect was disconnected
+
+rl.cleanup() -- disconnect all effects
+```

package/base_pesde.toml

@@ -0,0 +1,10 @@
+name = "wiam/rl"
+version = "0.1.11"
+description = "Simple reactive library for Luau."
+authors = ["wiam"]
+repository = "https://codeberg.org/wiam/rl"
+license = "GPL-3.0-or-later"
+includes = ["src/*", "pesde.toml", "COPYING", "README.md", "docs/*"]
+
+[indices]
+default = "https://github.com/pesde-pkg/index"

package/build.luau

@@ -0,0 +1,30 @@
+--!strict
+
+local fs = require("@lune/fs")
+local serde = require("@lune/serde")
+
+local TARGETS = {"luau", "lune", "roblox"}
+local INCLUDES = {"src", "COPYING", "PESDE_README.md", "docs"}
+
+local base_manifest = fs.readFile("base_pesde.toml")
+
+if fs.isDir("build") then
+	fs.removeDir("build")
+end
+
+fs.writeDir("build")
+
+for _, target in TARGETS do
+	local out_dir = "build/"..target
+	fs.writeDir(out_dir)
+
+	for _, include in INCLUDES do
+		fs.copy(include, out_dir.."/"..if include == "PESDE_README.md" then "README.md" else include)
+	end
+
+	fs.writeFile(out_dir.."/pesde.toml", base_manifest.."\n"..serde.encode("toml", {target = {
+		environment = target,
+		lib = "src/init.luau",
+		build_files = target == "roblox" and {"src"}
+	}}, true))
+end

package/default.project.json

@@ -0,0 +1,6 @@
+{
+  "name": "rl",
+  "tree": {
+    "$path": "src"
+  }
+}

package/docs/api_ref.md

@@ -0,0 +1,202 @@
+# rl API Reference
+## Types
+### state\<T>
+The [state](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#state) type.
+
+```luau
+type state<T> = (() -> T) & ((value : T, force : boolean?) -> T) & {
+	value : T
+}
+```
+
+### callback
+Function which gets called when its [effect](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#effect) is triggered.
+Takes the previous value of the state which triggered the effect, as well as its "index", determined by the order in which it appears within the function.
+
+```luau
+type callback<T> = (old_value : T, state_i : number?) -> any
+```
+
+## Functions
+### state
+Creates a new [state](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#state), with the given initial value, and whether to always [force](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#forcing), and returns it.
+
+```luau
+function state<T>(value : T?, force : boolean?) : state<T>
+
+-- Example
+local health = state(100)
+local stamina = state(100, true)
+```
+
+### derive
+Wraps an Effect around the given callback which sets a newly created State's value
+to be the return value of the callback.
+Returns the created State, the Effect's disconnect function and a flag which can be ignored.
+
+This is useful for States which depend on the value of another State, since their value will
+be updated only when the State they depend on is also updated, and not every time it is read,
+as how would happen with a function which's return value depends on a State.
+
+```luau
+function derive<T, U>(callback : () -> U) : (state<U>, () -> (), true)
+
+-- Example
+-- without derive() (normal function)
+local half_health = function()
+	print("some computation")
+	return health() / 2
+end
+
+print(half_health()) -- "some computation" 50
+print(half_health()) -- "some computation" 50
+health(50)
+print(half_health()) -- "some computation" 25
+print(half_health()) -- "some computation" 25
+
+-- with derive()
+local derive_half_health = derive(half_health) -- "some computation"
+
+print(derive_half_health()) -- 25
+print(derive_half_health()) -- 25
+health(20) -- "some computation"
+print(derive_half_health()) -- 10
+print(derive_half_health()) -- 10
+```
+
+### effect
+Creates a new [effect](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#effect), with the given [callback](https://pesde.dev/packages/wiam/rl/latest/any/docs/api_ref#callback) function, and returns its disconnect function.
+
+```luau
+function effect<T>(callback : callback<T>) : () -> ()
+
+-- Example
+effect(function()
+	print(`new health: {health()}`)
+end)
+
+health(10) -- "new health: 10"
+health(10) -- doesn't print because the new value is the same as the current one
+health(10, true) -- "new health: 10"; this prints because we forced it
+
+local disconnect = effect(function()
+	print(`new stamina: {stamina()}`)
+end)
+
+stamina(90) -- "new stamina: 90"
+stamina(90) -- "new stamina: 90"; this prints because `stamina` is always forced.
+disconnect()
+
+stamina(40) -- doesn't print because we disconnected the effect.
+```
+
+### batch
+Batches any State write operation up until the function is done running.
+
+```luau
+function batch(f : () -> any) : ()
+
+-- Example
+batch(function()
+	health(420)
+	health(1337, true)
+	health(69)
+end)
+
+-- "new health: 69"
+
+```
+
+### scope
+Returns a function which calls the given functions.
+Any non-function or function which precedes a "true" value by 2 indices is going to be skipped (the second happens because of derives).
+This is intended to be used for disconnecting Effects in bulk.
+
+```luau
+function scope<T>(... : T) : () -> ()
+
+-- Example
+-- without scope
+local disconnect_health = effect(function()
+	print(`your health is : {health()}`)
+end)
+
+local disconnect_stamina = effect(function()
+	print(`your stamina is : {stamina()}`)
+end)
+
+-- ...
+
+disconnect_health()
+disconnect_stamina()
+
+-- with scope
+local vitals_scope = scope(
+	effect(function()
+		print(`your health is : {health()}`)
+	end),
+	effect(function()
+		print(`your stamina is : {stamina()}`)
+	end)
+)
+
+-- ...
+
+vitals_scope()
+```
+
+### branch
+Alternative `if`-like function to be used within effects. Learn more about it in the [tracking section of the Concepts page](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#tracking).
+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.
+
+```luau
+function branch(...) : ()
+
+-- Example
+-- A single effect for the same functionality as the examples above, thanks to the use of state_i and the branching function.
+effect(function(_, state_i)
+	branch(
+		state_i == 1, function()
+			print(`new health: {health()}`)
+		end,
+		state_i == 2, function()
+			print(`new stamina: {stamina()}`)
+		end
+	)
+end)
+```
+
+### mirror
+Takes a table and for every function or state, creates an effect which automatically updates the element to be either the function's return value, or, if a state, to its value.
+The created effects' disconnect functions are put at t\["disconnect"..k], where k is either the key, if it's a string, or the index at which it was iterated over.
+Returns the given table, as well as a function which disconnects all created effects.
+
+```luau
+function mirror<K, V>(t : {[K] : V}) : ({[K] : V}, () -> ())
+
+-- Example
+local name = state("john")
+local data = mirror {
+	username = name,
+}
+
+print(data.username) -- "john"
+name("joe")
+print(data.username) -- "joe"
+data.disconnect_username()
+
+name("doe")
+print({data.username}) -- "joe"; didn't update because we disconnected the effect
+```
+
+### cleanup
+Disconnects all [effects](https://pesde.dev/packages/wiam/rl/latest/any/docs/concepts#effect).
+
+```luau
+function cleanup() : ()
+
+-- Example
+cleanup()
+health(77) -- doesn't print because no effect is connected to this state (we just disconnected)
+```

package/docs/concepts.md

@@ -0,0 +1,21 @@
+# rl concepts
+## Effect
+An Effect is the binding of a function to an event triggered when States read (with tracking) within it are written.
+
+## Tracking
+Tracking, or registering, is the process done internally by `rl` for assigning States to Effects, so that the latters' functions can be ran when the formers' values are written.\
+This works by calling an Effect's function once when created to check which States are read (with tracking) within it.\
+But this introduces a problem: when branching within the function, only the branch which satisfies the condition is going to be checked.\
+That could be solved by reading all the States that are going to be used before any branch, but it misses the point of the library.\
+Instead, `rl` solves this by providing the `branch` function, which works like standard branching, but runs all branches when it's doing the tracking process, so that all States are correctly assigned.
+
+## State
+A State is a container for a value.\
+Internally, it is an userdata that has a metatable with the `__index` and `__newindex` metamethods, which permit reading and writing the value with special mechanisms.\
+Call it with no arguments for reading with tracking.\
+Call with arguments for writing, where the first argument is the new value, and the second one is whether to force for this specific call.\
+Access the `.value` field for reading without tracking. Note that this is read-only, and attempting to modify it will cause an error. `rawset` doesn't work either, since an userdata is not a table.
+
+## Forcing
+Forcing is when you write a new value to a State, and always trigger its Effects, even when the new value is the same as the old one.\
+States, when created, can be opted in to always force their values; you can overwrite this in individual write operations.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@rbxts/rl",
+  "version": "0.1.11",
+  "description": "simple reactive library",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/wiam/rl"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "wi_am",
+  "main": "src/init.luau",
+  "typings": "src/index.d.ts"
+}

package/pesde.toml

@@ -0,0 +1,14 @@
+name = "wiam/rl_root"
+version = "1.0.0"
+license = "GPL-3.0-or-later"
+workspace_members = ["build/*"]
+private = true
+
+[target]
+environment = "lune"
+
+[scripts]
+build = "./build.luau"
+
+[indices]
+default = "https://github.com/pesde-pkg/index"

package/publish.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+ 
+pesde run build && pesde update && pesde publish -y && wally publish

package/rokit.toml

@@ -0,0 +1,4 @@
+[tools]
+wally = "UpliftGames/wally@0.3.2"
+rojo = "rojo-rbx/rojo@7.6.1"
+lune = "lune-org/lune@0.10.4"

package/src/index.d.ts

@@ -0,0 +1,74 @@
+export type state<T> = {
+  (new_value: T, force?: boolean): T
+  (): T
+  readonly value: T
+}
+
+export type callback<T> = (old_value: T, state_i?: number) => any
+
+/**
+ * Disconnects all Effects.
+ */
+export function cleanup(): void
+
+/**
+ * Creates a State.
+ * 
+ * @param value T -- Initial value.
+ * @param force? boolean -- Whether Effects connected to this State will trigger, despite the fact that the value didn't change.
+ * @returns state<T> -- State. Call with no arguments for reading with tracking, call with arguments for writing (2nd argument is for forcing), read .value field for reading without tracking.
+ */
+export function state<T>(value: T, force?: boolean): state<T>
+
+/**
+ * Batches any State write operation up until the function is done running.
+ * @param f () => any -- The function.
+ */
+export function batch(f: () => any): void
+
+/**
+ * Creates an Effect, a binding of the given function to the event of States read (by calling) within it being updated.
+ * 
+ * @param callback callback<T> -- The function to be bound.
+ * @returns () => void -- Function which disconnects the Effect from the States.
+ */
+export function effect<T>(callback: callback<T>): () => void
+
+/**
+ * Returns a function which calls the given functions.
+ * Any non-function or function which precedes a "true" value by 2 indices is going to be skipped (the second happens because of derives).
+ * This is intended to be used for disconnecting Effects in bulk.
+ * @param ... () => () -- The functions.
+ * @returns () => () -- The function caller.
+ */
+export function scope<T>(...t : T[]): () => void
+
+/**
+ * Wraps an Effect around the given callback which sets a newly created State's value
+ * to be the return value of the callback.
+ * Returns the created State, the Effect's disconnect function and a flag which can be ignored.
+ * This is useful for States which depend on the value of another State, since their value will
+ * be updated only when the State they depend on is also updated, and not every time it is read,
+ * as how would happen with a function which's return value depends on a State.
+ * @param callback () => U -- the callback
+ * @returns state<U> -- the State that was created
+ * @returns () => void -- the created Effect's disconnect function
+ * @returns true -- a flag used internally by rl.scope(); can be ignored.
+ */
+export function derive<T, U>(callback: () => U) : [state<U>, () => void, true]
+
+/**
+ * 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.
+ */
+export function branch(...a : any) : void
+
+/**
+ * Creates an effect for every function or State within the given table, which updates the key to either the return value of the function, or the value of the State.
+ * Each Effect's disconnect function gets put in the table as t["disconnect_"..key], when key is a string, or as t["disconnect"_..i], where i is the numerical index at which the key was iterated over.
+ * @param t {[K] : V} -- The table.
+ * @return {[K] : V} -- The same table.
+ * @returns () => void -- Function which disconnects and eliminates each disconnect function of the created Effects.
+ */
+export function mirror<K, V>(t : Map<K, V>): [Map<K, V>, () => void]