@rbxts/deep-charm 0.1.0-rc.1 → 0.1.0

package/README.md

@@ -18,20 +18,20 @@
 
 </div>
 
-Charm is a state management library based on [fine-grained reactivity](https://dev.to/ryansolid/a-hands-on-introduction-to-fine-grained-reactivity-3ndf). Connect behavior to data with reactive signals, ensuring games stay up-to-date with their underlying data while eliminating the need for manual updates.
+Charm is a reactive state management library designed for storing data in discrete containers called _signals_. Connect behavior to data with signals, ensuring systems stay up-to-date with their underlying data while reactivity eliminates the need for manual updates.
 
 **Build game state from simple building blocks:**
 
-- Store state in [signals](#signalinitialvalue-equals): state containers that hold a value
-- React to state changes with [effects](#effectcallback): re-run code when a dependency updates
-- Derive values from state with [computed signals](#computedgetter): memoized functions with dependency tracking
+- Store data in [signals](#signalinitialvalue-equals): reactive state containers that hold a value
+- React to state changes with [effects](#effectcallback): re-run code when signals update
+- Derive new values from data with [computed signals](#computedgetter): memoize functions that access signals
 
-**Want to learn more about signals?**
+**Want to learn more about reactivity?**
 
 - https://dev.to/ryansolid/a-hands-on-introduction-to-fine-grained-reactivity-3ndf
 - https://preactjs.com/blog/introducing-signals
 - https://docs.solidjs.com/advanced-concepts/fine-grained-reactivity
-- https://angular.dev/guide/signals
+- https://github.com/roblox/signals
 
 [Migrating from an older version of Charm?](#migration)
 
@@ -51,7 +51,7 @@ Charm is a state management library based on [fine-grained reactivity](https://d
     - [`subscribe(getter, callback)`](#subscribegetter-callback)
     - [`untracked(callback)`](#untrackedcallback)
     - [`batch(callback)`](#batchcallback)
-    - [`mapped(getter, mapper)`](#mappedgetter-mapper)
+    - [`mapped(getter, transform)`](#mappedgetter-transform)
     - [`onCleanup(callback, failSilently?)`](#oncleanupcallback-failsilently)
     - [`atom(initialValue, equals?)`](#atominitialvalue-equals)
     - [`trigger(callback)`](#triggercallback)
@@ -472,11 +472,11 @@ end)
 
 ---
 
-### `mapped(getter, mapper)`
+### `mapped(getter, transform)`
 
-The `mapped` function iterates over every key in a table and uses the mapper to assign them to a new key and value. The result is returned as a read-only signal containing the new keys and values. When a key's value changes, or a new key is added to the table, the mapper is called for that key and its current value.
+The `mapped` function iterates over every key in a table and uses the transform function to assign them to a new key and value. The result is returned as a read-only signal containing the new keys and values. When a key's value changes, or a new key is added to the table, `transform` is called for that key and its current value.
 
-The first value returned by the mapper is used as the new value:
+The first value returned by the transform function is used as the new value:
 
 ```luau
 local getList, setList = signal({ "a", "b", "c" })
@@ -488,7 +488,7 @@ end)
 print(getUppercase()) -- { "A", "B", "C" }
 ```
 
-If the mapper returns two values, the second value is used as the new key:
+If the transform function returns two values, the second value is used as the new key:
 
 ```luau
 local getList, setList = signal({ "a", "b", "c" })
@@ -602,7 +602,7 @@ Charm exposes the following global flags to customize behavior:
 | frozen            | `true`\* | Enforces data immutability by deep-freezing tables passed to signals, excluding objects with metatables.                                               |
 | trackInnerEffects | `true`   | Whether nested effects should be tracked and cleaned up when the parent effect re-runs. This should only be disabled to debug issues during migration. |
 
-The `strict` and `frozen` flags are automatically enabled in Roblox Studio and other development environments where the Luau optimization level is `O1` or lower.
+The `strict` and `frozen` flags are automatically enabled in Roblox Studio.
 
 ---
 
@@ -640,25 +640,19 @@ return {
 }
 ```
 
-When a player joins on the server, call `server.addSignalsToClient` with the keyed signals that the client should receive updates for. Once they leave, call `server.removeClient` to unsubscribe them from all updates.
+When a player notifies the server that they're ready to start syncing, call `server.addSignalsToClient` with the signals that the client should receive updates for. Once they leave, call `server.removeClient` to unsubscribe them from all updates.
 
-Then, use `server.connect` to specify how state updates should be sent to each client. Pass a callback function that fires a remote with the given target player and the state updates they subscribed to.
+Then, use `server.connect` to specify how state updates should be sent to each client. Pass a callback function that fires a remote with the given target player and the state updates they subscribed to:
 
 ```luau
-local function onPlayerAdded(player: Player)
-	-- Add signal getters, computed signals, atoms, or reactive objects
+playerReadyEvent.OnServerEvent:Connect(function(player)
+	-- Sync signal getters, computed signals, atoms, or reactive proxies
 	server.addSignalsToClient(player, {
 		name = nameStore.getName,
 		surname = nameStore.getSurname,
 		age = nameStore.ageAtom,
 	})
-end
-
-for _, player in Players:GetPlayers() do
-	onPlayerAdded(player)
-end
-
-Players.PlayerAdded:Connect(onPlayerAdded)
+end)
 
 Players.PlayerRemoving:Connect(function(player)
 	server.removeClient(player)
@@ -671,7 +665,7 @@ end)
 ```
 
 > [!NOTE]
-> On the server, make sure each key corresponds to the same signal across all players. If two players subscribe to the same key, but were given different signals, Charm will output a warning.
+> On the server, make sure each key corresponds to the same data across all players. If two players subscribe to the same key, but were given different signals, Charm will output a warning.
 
 To sync the client with the server's state, call `client.addSignals` with a table of writable signals (setter functions or atoms) whose keys match their server counterparts.
 
@@ -701,8 +695,8 @@ A configuration table that customizes the behavior of Charm Sync on the server.
 | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | interval        | `0`     | The frequency at which the server will send patches to the client, in seconds. A value of `0` sends updates on the next frame. Set to a negative value to disable the interval.                                                                                       |
 | preserveHistory | `false` | Whether to preserve a full history of state changes since the last sync, at the cost of performance. This is useful if you need to replicate each individual change that occurs between sync events.                                                                  |
-| fixArrays       | `true`  | When `true`, Charm will attempt to work around Roblox remote event limitations regarding array patches. Disable this if your networking library serializes remote arguments (Zap, ByteNet, etc.).                                                                     |
-| validatePatches | `true`  | When `true`, and both `fixArrays` and strict mode are enabled, synced values containing unsafe sparse arrays or mixed tables will throw an error. See the [remote argument limitations](https://create.roblox.com/docs/scripting/events/remote#argument-limitations). |
+| fixArrays       | `true`  | When `true`, Charm will attempt to work around remote event limitations that cause data loss in array patches. Disable this if your networking library serializes remote arguments (Zap, ByteNet, etc.).                                                              |
+| validatePatches | `true`  | When `true`, and both `fixArrays` and strict mode are enabled, synced values containing unsafe sparse arrays or mixed tables will emit a warning. See the [remote argument limitations](https://create.roblox.com/docs/scripting/events/remote#argument-limitations). |
 
 ---
 
@@ -713,7 +707,7 @@ The `addSignalsToClient` function subscribes a client to updates in the given si
 You can pass signal getter functions, computed signals, atoms, and [reactive objects](#reactiveinitialvalue) in the `getters` table. This function can also be called multiple times on the same client to subscribe to new signals.
 
 ```luau
-Players.PlayerAdded:Connect(function(player)
+playerReadyEvent.OnServerEvent:Connect(function(player)
 	server.addSignalsToClient(player, {
 		name = nameStore.getName,
 		surname = nameStore.getSurname,
@@ -722,14 +716,22 @@ Players.PlayerAdded:Connect(function(player)
 end)
 ```
 
-You're also allowed to create new signals to sync to specific players, as long as the key is unique to that player:
+You're also allowed to create new signals to sync to specific players, as long as the key is unique to that data:
 
 ```luau
-server.addSignalsToClient(player, {
-	[`data-{player.UserId}`] = computed(function()
-		return getPlayerData(player.UserId)
-	end),
-})
+playerReadyEvent.OnServerEvent:Connect(function(player)
+	server.addSignalsToClient(player, {
+		-- 🟢 Good: Player-specific data is synced with a unique key
+		[`data-{player.UserId}`] = computed(function()
+			return getPlayerData(player.UserId)
+		end),
+
+		-- 🔴 Bad: Syncing different data with the same keys does not work
+		playerData = computed(function()
+			return getPlayerData(player.UserId)
+		end),
+	})
+end)
 ```
 
 ---
@@ -754,7 +756,7 @@ server.removeSignalsFromClient(player, "surname")
 The `removeClient` function unsubscribes a client from receiving all state updates from the server. You should call this function when a player leaves the game.
 
 ```luau
-Players.PlayerAdded:Connect(function(player)
+playerReadyEvent.OnServerEvent:Connect(function(player)
 	server.addSignalsToClient(player, signals)
 end)
 
@@ -883,6 +885,9 @@ You can opt-in to deep reactivity with the Deep Charm library:
 
 ### Installation
 
+> [!WARNING]
+> Deep Charm is an experimental library that is not fully documented, and the API is subject to breaking changes.
+
 ```sh
 npm install @rbxts/deep-charm
 yarn add @rbxts/deep-charm
@@ -938,6 +943,22 @@ local proxy = reactive(raw)
 print(toRaw(proxy) == raw) -- true
 ```
 
+Calling `toRaw()` on a proxy also subscribes to its changes. This allows you to use proxies with `observe()` and other Charm APIs that accept a getter function:
+
+```luau
+local proxy, updateProxy = reactive({})
+
+observe(function()
+	return toRaw(proxy)
+end, function(value, key)
+	print(`Value {value} added at key {key}`)
+end)
+
+updateProxy(function(state)
+	table.insert(state, "foo")
+end) -- Value foo added at key 1
+```
+
 ---
 
 ### `isReactive(value)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/deep-charm",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0",
   "description": "Use Charm with plain Luau tables",
   "license": "MIT",
   "main": "src/init.luau",
@@ -18,7 +18,7 @@
     "url": "git+https://github.com/littensy/charm.git"
   },
   "dependencies": {
-    "@rbxts/charm": "^0.11.0-rc.5"
+    "@rbxts/charm": "^0.11.0"
   },
   "scripts": {
     "publish:wally": "wally publish"

package/src/init.luau

@@ -36,7 +36,7 @@ end
 ]]
 local function toRaw<T>(value: T): T
 	if isReactive(value) then
-		local value = value :: ReactiveProxy<T> & T
+		value = value :: ReactiveProxy<T>
 		value.__track()
 		return toRaw(value.__target)
 	end