@rbxts/charm
Advanced tools
Atomic state management for Roblox.
npm package →
Charm is an atomic state management library inspired by Jotai and Nanostores. Store your immutable state in atoms, and write intuitive functions that read, write, and subscribe to state.
See an example of Charm's features in this example repository.
⚛️ Manage state with atoms. Decompose state into tiny, composable containers called atoms, as opposed to combining them into a single store.
💪 Minimal, yet powerful. Less boilerplate — write simple functions to read from and write to state.
🔬 Immediate updates. Listeners run asynchronously by default, avoiding the cascading effects of deferred updates and improving responsiveness.
🦄 Like magic. Selector functions can be subscribed to as-is — with implicit dependency tracking, atoms are captured and memoized for you.
Install Charm for roblox-ts using your package manager of choice.
npm install @rbxts/charm
yarn add @rbxts/charm
pnpm add @rbxts/charm
Alternatively, add littensy/charm to your wally.toml file.
[dependencies]
Charm = "littensy/charm@VERSION"
Charm provides a debug mode to help you identify potential bugs in your project. To enable debug mode, set the global _G.__DEV__ flag to true at the entry point of your project.
Enabling __DEV__ adds a few helpful features:
Better error handling for selectors, subscriptions, and batched functions:
Server state is validated for remote event limitations before being passed to the client.
Enabling debug mode in unit tests, storybooks, and other development environments can help you catch potential issues early. However, remember to turn off debug mode in production to avoid the performance overhead.
atom(state, options?)Atoms are the building blocks of Charm. They are functions that hold a single value, and calling them can read or write to that value. Atoms, or any function that reads from atoms, can also be subscribed to.
Call atom to create a state container initialized with the value state.
local nameAtom = atom("John")
local todosAtom: Atom<{ string }> = atom({})
state: The value to assign to the atom initially.
optional options: An object that configures the behavior of this atom.
equals: An equality function to determine whether the state has changed. By default, strict equality (==) is used.The atom constructor returns an atom function with two possible operations:
local function newTodo()
nameAtom("Jane")
todosAtom(function(todos)
todos = table.clone(todos)
table.insert(todos, "Buy milk")
return todos
end)
print(nameAtom()) --> "Jane"
end
subscribe(callback, listener)Call subscribe to listen for changes in an atom or selector function. When the function's result changes, subscriptions are immediately called with the new state and the previous state.
local nameAtom = atom("John")
subscribe(nameAtom, function(name, prevName)
print(name)
end)
nameAtom("Jane") --> "Jane"
You may also pass a selector function that calls other atoms. The function will be memoized and only runs when its atom dependencies update.
local function getUppercase()
return string.upper(nameAtom())
end
subscribe(getUppercase, function(name)
print(name)
end)
nameAtom("Jane") --> "JANE"
callback: The function to subscribe to. This may be an atom or a selector function that depends on an atom.
listener: The listener is called when the result of the callback changes. It receives the new state and the previous state as arguments.
subscribe returns a cleanup function.
effect(callback)Call effect to track state changes in all atoms read within the callback. The callback will run once to retrieve its dependencies, and then again whenever they change. Your callback may return a cleanup function to run when the effect is removed or about to re-run.
local nameAtom = atom("John")
effect(function()
print(nameAtom())
return function()
print("Cleanup function called!")
end
end)
Because effect implicitly tracks all atoms read within the callback, it might be useful to exclude atoms that should not trigger a re-run. You can use peek to read from atoms without tracking them as dependencies.
callback: The function to track for state changes. The callback will run once to retrieve its dependencies, and then again whenever they change.effect returns a cleanup function.
computed(callback, options?)Call computed when you want to derive a new atom from one or more atoms. The callback will be memoized, meaning that subsequent calls to the atom return a cached value that is only re-calculated when the dependencies change.
local todosAtom: Atom<{ string }> = atom({})
local mapToUppercase = computed(function()
local result = table.clone(todosAtom())
for key, todo in result do
result[key] = string.upper(todo)
end
return result
end)
Because computed implicitly tracks all atoms read within the callback, it might be useful to exclude atoms that should not trigger a re-run. You can use peek to read from atoms without tracking them as dependencies.
This function is also useful for optimizing effect calls that depend on multiple atoms. For instance, if an effect derives some value from two atoms, it will run twice if both atoms change at the same time. Using computed can group these dependencies together and avoid re-running side effects.
callback: A function that returns a new value depending on one or more atoms.
optional options: An object that configures the behavior of this atom.
computed returns a read-only atom.
observe(callback, factory)Call observe to create an instance of factory for each key present in a dictionary or array. Your factory can return a cleanup function to run when the key is removed or the observer is cleaned up.
[!NOTE] Because
observetracks the lifetime of each key in your data, your keys must be unique and unchanging. If your data is not keyed by unique and stable identifiers, consider usingmappedto transform it into a keyed object before passing it toobserve.
local todosAtom: Atom<{ [string]: Todo }> = atom({})
observe(todosAtom, function(todo, key)
print(`Added {key}: {todo.name}`)
return function()
print(`Removed {key}`)
end
end)
callback: An atom or selector function that returns a dictionary or an array of values. When a key is added to the state, the factory will be called with the new key and its initial value.
factory: A function that will be called whenever a key is added or removed from the atom's state. The callback will receive the key and the entry's initial value as arguments, and may return a cleanup function.
observe returns a cleanup function.
mapped(callback, mapper)Call mapped to transform the keys and values of your state. The mapper function will be called for each key-value pair in the atom's state, and the new keys and atoms will be stored in a new atom.
local todosAtom: Atom<{ Todo }> = atom({})
local todosById = mapped(todosAtom, function(todo, index)
return todo, todo.id
end)
callback: The function whose result you want to map over. This can be an atom or a selector function that reads from atoms.
mapper: The mapper is called for each key in your state. Given the current value and key, it should return a new corresponding value and key:
nil for the value to remove the key from the resulting table.mapped returns a read-only atom.
peek(value, ...)Call peek to call a function without tracking it as the dependency of an effect or a selector function.
local nameAtom = atom("John")
local ageAtom = atom(25)
effect(function()
local name = nameAtom()
local age = peek(ageAtom)
end)
value: Any value. If the value is a function, peek will call it without tracking dependencies and return the result.
optional ...args: Additional arguments to pass to the value if it is a function.
peek returns the result of the given function. If the value is not a function, it will return the value as-is.
batch(callback)Call batch to defer state changes until after the callback has run. This is useful when you need to make multiple changes to the state and only want listeners to be notified once.
local nameAtom = atom("John")
local ageAtom = atom(25)
batch(function()
nameAtom("Jane")
ageAtom(26)
end)
callback: A function that updates atoms. Listeners will only be notified once all changes have been applied.batch does not return anything.
Install the React bindings for Charm using your package manager of choice.
npm install @rbxts/react-charm
yarn add @rbxts/react-charm
pnpm add @rbxts/react-charm
[dependencies]
ReactCharm = "littensy/react-charm@VERSION"
useAtom(callback, dependencies?)Call useAtom at the top-level of a React component to read from an atom or selector. The component will re-render when the value changes.
local todosAtom = require(script.Parent.todosAtom)
local function Todos()
local todos = useAtom(todosAtom)
-- ...
end
If your selector depends on the component's state or props, remember to pass them in a dependency array. This prevents skipped updates when an untracked parameter of the selector changes.
local todos = useAtom(function()
return searchTodos(props.filter)
end, { props.filter })
callback: An atom or selector function that depends on an atom.
optional dependencies: An array of outside values that the selector depends on. If the dependencies change, the subscription is re-created and the component re-renders with the new state.
useAtom returns the current state of the atom.
Install the Vide bindings for Charm using your package manager of choice.
npm install @rbxts/vide-charm
yarn add @rbxts/vide-charm
pnpm add @rbxts/vide-charm
[dependencies]
VideCharm = "littensy/vide-charm@VERSION"
useAtom(callback)Call useAtom in any scope to create a Vide source that returns the current state of an atom or selector.
local todosAtom = require(script.Parent.todosAtom)
local function Todos()
local todos = useAtom(todosAtom)
-- ...
end
callback: An atom or selector function that depends on an atom.useAtom returns a Vide source.
The Charm Sync package provides server-client synchronization for your Charm atoms. Install it using your package manager of choice.
npm install @rbxts/charm-sync
yarn add @rbxts/charm-sync
pnpm add @rbxts/charm-sync
[dependencies]
CharmSync = "littensy/charm-sync@VERSION"
server(options)Call server to create a server sync object. This synchronizes every client's atoms with the server's state by sending partial patches that the client merges into its state.
local syncer = CharmSync.server({
atoms = atomsToSync, -- A dictionary of the atoms to sync, matching the client's
interval = 0, -- The minimum interval between state updates
preserveHistory = false, -- Whether to send a full history of changes made to the atoms (slower)
})
-- Sends state updates to clients when a synced atom changes.
-- Omitting sensitive information and data serialization can be done here.
syncer:connect(function(player, ...)
remotes.syncState:fire(player, ...)
end)
-- Sends the initial state to a player upon request. This should fire when a
-- player joins the game.
remotes.requestState:connect(function(player)
syncer:hydrate(player)
end)
options: An object to configure sync behavior.
atoms: A dictionary of the atoms to sync. The keys should match the keys on the client.
optional interval: The interval at which to batch state updates to clients. Defaults to 0, meaning updates are batched every frame.
optional preserveHistory: Whether to sync an exhaustive history of changes made to the atoms since the last sync event. If true, the server sends multiple payloads instead of one. Defaults to false for performance.
server returns an object with the following methods:
syncer:connect(callback): Registers a callback to send state updates to clients. The callback will receive the player and the payload(s) to send, and should fire a remote event. The payload is read-only, so any changes should be applied to a copy of the payload.
syncer:hydrate(player): Sends the player a full state update for all synced atoms.
By default, Charm omits the individual changes made to atoms between sync events (i.e. a counterAtom set to 1 and then 2 will only send the final state of 2). If you need to preserve a history of changes, set preserveHistory to true.
Charm does not handle network communication. You must implement your own network layer to send and receive state updates. This is implemented via the remotes namespace in the example above.
client(options)Call client to create a client sync object. This synchronizes the client's atoms with the server's state by merging partial patches sent by the server into each atom.
local syncer = CharmSync.client({
atoms = atomsToSync, -- A dictionary of the atoms to sync, matching the server's
})
-- Applies state updates from the server to the client's atoms.
-- Data deserialization can be done here.
remotes.syncState:connect(function(...)
syncer:sync(...)
end)
-- Requests the initial state from the server when the client joins the game.
-- Before this runs, the client uses the atoms' default values.
remotes.requestState:fire()
options: An object to configure sync behavior.
atoms: A dictionary of the atoms to sync. The keys should match the keys on the server.client returns an object with the following methods:
syncer:sync(...payloads) applies a state update from the server.requestState in the example above.isNone(value)Call isNone to check if a value is None. Charm's partial state patches omit values that did not change between sync events, so to mark keys for deletion, Charm uses the None marker.
This function can be used to check whether a value is about to be removed from an atom.
local syncer = CharmSync.server({ atoms = atomsToSync })
syncer:connect(function(player, payload)
if
payload.type === "patch"
and payload.data.todosAtom
and CharmSync.isNone(payload.data.todosAtom.eggs)
then
-- 'eggs' will be removed from the client's todo list
end
remotes.syncState.fire(player, payload)
end)
value: Any value. If the value is None, isNone will return true.isNone returns a boolean.
local counterAtom = atom(0)
-- Create a selector that returns double the counter value
local function doubleCounter()
return counterAtom() * 2
end
-- Runs after counterAtom is updated and prints double the new value
subscribe(doubleCounter, function(value)
print(value)
end)
counterAtom(1) --> 2
counterAtom(function(count)
return count + 1
end) --> 4
local counter = require(script.Parent.counter)
local counterAtom = counter.counterAtom
local incrementCounter = counter.incrementCounter
local function Counter()
local count = useAtom(counterAtom)
return React.createElement("TextButton", {
[React.Event.Activated] = incrementCounter,
Text = `Count: {count}`,
Size = UDim2.new(0, 100, 0, 50),
})
end
local counter = require(script.Parent.counter)
local counterAtom = counter.counterAtom
local incrementCounter = counter.incrementCounter
local function Counter()
local count = useAtom(counterAtom)
return create "TextButton" {
Activated = incrementCounter,
Text = function()
return `Count: {count()}`
end,
Size = UDim2.new(0, 100, 0, 50),
}
end
Charm is designed for both client and server use, but there are often cases where the client needs to reference state that lives on the server. The CharmSync package provides a way to synchronize atoms between the server and its clients using remote events.
Start by creating a set of atoms to sync between the server and clients. Export these atoms from a module to be shared between the server and client:
-- atoms.luau
local counter = require(script.Parent.counter)
local todos = require(script.Parent.todos)
return {
counterAtom = counter.counterAtom,
todosAtom = todos.todosAtom,
}
Then, on the server, create a server sync object and pass in the atoms to sync. Use remote events to broadcast state updates and send initial state to clients upon request.
[!NOTE] If
preserveHistoryistrue, the server will send multiple payloads to the client, so the callback passed toconnectshould accept a variadic...payloadsparameter. Otherwise, you only need to handle a singlepayloadparameter.
-- sync.server.luau
local atoms = require(script.Parent.atoms)
local syncer = CharmSync.server({ atoms = atoms })
-- Sends state updates to clients when a synced atom changes.
-- Omitting sensitive information and data serialization can be done here.
syncer:connect(function(player, payload)
remotes.syncState.fire(player, payload)
end)
-- Sends the initial state to a player upon request. This should fire when a
-- player joins the game.
remotes.requestState:connect(function(player)
syncer:hydrate(player)
end)
Finally, on the client, create a client sync object and use it to apply incoming state changes.
-- sync.client.luau
local atoms = require(script.Parent.atoms)
local syncer = CharmSync.client({ atoms = atoms })
-- Applies state updates from the server to the client's atoms.
remotes.syncState:connect(function(payload)
syncer:sync(payload)
end)
-- Requests the initial state from the server when the client joins the game.
-- Before this runs, the client uses the atoms' default values.
remotes.requestState:fire()
Charm is released under the MIT License.
FAQs
An atomic state management library for Roblox
We found that @rbxts/charm demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."