{"id":"gamingguy84/reactivestate","name":"reactivestate","scope":"gamingguy84","platform":"roblox","description":"A idiomatic state replication package.","version":"0.1.9","latest":"0.1.9","versions":["0.0.3","0.0.4","0.1.4","0.1.5","0.1.6","0.1.7","0.1.8","0.1.9"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"data-oriented-house/lemonsignal":{"version":"^1.11.0","alias":"lemonsignal"},"ivasmigins/replica":{"version":"^0.1.0","alias":"replica"}},"integrity":"f04dbaeb537224d786853e422357cc385480a24ed3f3c66f29589f4b1365e942","likes":0,"downloads":0,"install":"forest install gamingguy84/reactivestate","url":"https://forest.dev/p/roblox/gamingguy84/reactivestate","files":"https://api.forest.dev/ai/package/roblox/gamingguy84/reactivestate/files","readme":"# ReactiveState\r\n\r\nReactiveState is a lightweight Luau state layer for Roblox built on top of Replica. It gives you a schema-aware, proxy-based server state and a mirrored, event-driven client view for shared data.\r\n\r\n---\r\n\r\n## Features\r\n\r\n- Proxy-based server state with natural table syntax\r\n- Server-side schema validation for writes\r\n- Batched updates with `:Batch(...)`\r\n- Replica-backed replication to clients\r\n- Event-driven client signals for changes, descendants, arrays, and dictionaries\r\n- Simple `Get` and `OnReady` APIs for client-side reads\r\n\r\n---\r\n\r\n## Installation\r\n\r\nPlace ReactiveState in a shared location such as ReplicatedStorage and require it from scripts on both sides:\r\n\r\n```lua\r\nlocal ReactiveState = require(path.to.ReactiveState)\r\n```\r\n\r\nThe module exposes two entry points:\r\n\r\n```lua\r\nlocal client = ReactiveState.client\r\nlocal server = ReactiveState.server\r\n```\r\n\r\n---\r\n\r\n## Server Example\r\n\r\n```lua\r\nlocal ReactiveState = require(path.to.ReactiveState)\r\nlocal server = ReactiveState.server\r\n\r\nlocal state = server.new(\"PlayerState\", {\r\n    Schema = {\r\n        Health = true,\r\n        Stats = {\r\n            Damage = true,\r\n        },\r\n    },\r\n    Data = {\r\n        Health = 100,\r\n        Stats = {\r\n            Damage = 10,\r\n        },\r\n    },\r\n})\r\n\r\nstate.Health = 90\r\n\r\nstate:Batch(function()\r\n    state.Health = 80\r\n    state.Stats.Damage = 15\r\nend)\r\n\r\nstate:Destroy()\r\n```\r\n\r\n---\r\n\r\n## Client Example\r\n\r\n```lua\r\nlocal ReactiveState = require(path.to.ReactiveState)\r\nlocal client = ReactiveState.client\r\n\r\nlocal state = client.OnNew(\"PlayerState\")\r\n\r\nstate:OnReady(function()\r\n    print(\"Health:\", state:Get({\"Health\"}))\r\nend)\r\n\r\nlocal healthSignal = state:GetChangedSignal({\"Health\"})\r\nhealthSignal:Connect(function(newValue, oldValue, path)\r\n    print(\"Health changed:\", newValue, oldValue, path)\r\nend)\r\n```\r\n\r\n---\r\n\r\n## API\r\n\r\n### Server\r\n\r\n```lua\r\nlocal server = ReactiveState.server\r\n\r\nlocal state = server.new(Name: string, Params: {\r\n    Schema: {[string]: boolean | any},\r\n    Data: T? | {}\r\n})\r\n```\r\n\r\nMethods:\r\n\r\n```lua\r\nstate:Batch(callback)\r\nstate:Destroy()\r\n```\r\n\r\nThe server-side object is a proxy, so writes such as `state.Health = 100` are routed through the replica layer.\r\n\r\n### Client\r\n\r\n```lua\r\nlocal client = ReactiveState.client\r\n\r\nlocal state = client.OnNew(Name: string)\r\n```\r\n\r\nMethods:\r\n\r\n```lua\r\nstate:OnReady(callback)\r\nstate:Get(path: {string})\r\nstate:GetChangedSignal(path)\r\nstate:GetDescendantsChangedSignal(path)\r\nstate:GetArrayInsertedSignal(path)\r\nstate:GetArrayRemovedSignal(path)\r\nstate:GetArrayChangedSignal(path)\r\nstate:GetDictionaryAddedSignal(path)\r\nstate:GetDictionaryRemovedSignal(path)\r\nstate:GetDictionaryChangedSignal(path)\r\n```\r\n\r\n---\r\n\r\n## How It Works\r\n\r\nReactiveState uses Replica as the replication transport. On the server, updates are written to a proxy-backed state object and forwarded to a Replica instance. On the client, the same Replica is observed and mirrored into a local state table. The result is a natural table-like API that still stays synced across the network.\r\n\r\n---\r\n\r\n## Limitations\r\n\r\n- Best suited for small-to-medium state trees rather than large ECS-style worlds\r\n- Server writes are validated against the provided schema\r\n- The client view is a snapshot of the currently replicated state and updates through change signals\r\n- The package assumes you are already using or are willing to use Replica as the transport layer\r\n","readmeTruncated":false}