Start typing to search packages!
omnistore
By @z13ak
Roblox
Mirrored from Wally[image: OmniStore — Typed Persistence for Roblox]
OmniStore is a typed persistence library for Roblox:
OmniStore -> Store -> Record -> Data
A record key can represent any durable entity: a player, server, guild, world, plot, or something specific to your game. Stores add schemas, migrations, session leases, autosave, and safe mutation helpers on top of Roblox DataStores. Read-only client replication is optional.
Status:
0.2.0-rc.4is a release candidate. It adds persistence reliability fixes and expanded regression coverage. Validate migrations and representative stored data in a separate test universe before upgrading a production experience.
Quick start
local Players = game:GetService("Players")
local OmniStore = require(game.ReplicatedStorage.Packages.OmniStore)
local data = OmniStore.new({ namespace = "MyGame" })
local profiles = data:GetStore("Profiles", {
template = {
Coins = 0,
Inventory = {},
Settings = { Music = true },
},
schemaVersion = 1,
})
Players.PlayerAdded:Connect(function(player)
local loaded = profiles:LoadAsync(player.UserId)
if not loaded.ok then
warn("Profile load failed", player.UserId, loaded.error.code)
player:Kick("Your data could not be loaded. Please rejoin.")
return
end
local profile = loaded.value
profile:Increment("Coins", 25)
profile:Insert("Inventory", { Id = "WoodenSword" })
end)
Players.PlayerRemoving:Connect(function(player)
local closed = profiles:CloseRecordAsync(player.UserId, 10)
if not closed.ok then
warn("Profile close failed", player.UserId, closed.error.code)
end
end)
Every operation that can fail returns { ok = true, value = ... } or
{ ok = false, error = ... }. Data reads return defensive copies; mutations must go through the
record API so dirty tracking and validation cannot be bypassed accidentally.
How writes behave
UpdateAsync-oriented writes and atomic per-key lease checks.- A live lease is never intentionally overwritten; expired leases can be recovered.
- Serialization and optional schema validation run before writes.
- Retryable adapter failures use bounded exponential backoff with jitter.
- Concurrent save calls coalesce, while mutations made during a save remain dirty.
CloseAsyncsaves and releases the lease in the same atomic update.- In-memory transactions use isolated drafts and publish changes only after a successful commit.
- Replication is server-authoritative and exposes only explicitly allowed paths.
Important limits
Upgrading from rc.3
This candidate changes deletion to retain empty tombstones and escapes literal tables that resemble codec markers. Old readers do not safely understand every new representation, and old deletion paths can bypass the updated lease checks. Pause writes and drain all rc.3 servers before enabling deletion or new-format writes. Reverting to rc.3 after those writes is unsafe; see the compatibility and upgrade procedure.
Persistence guarantees
OmniStore cannot provide database-wide ACID transactions, guaranteed shutdown saves, protection
from a compromised server, or immunity to Roblox outages and platform limits. A transaction is
atomic only in local memory until a later single-record save. Roblox UpdateAsync supplies the
atomic compare/transform behavior for one key; operations across keys are not atomic. See
failure semantics and security.
Documentation
Start with the API reference, configuration guide, and examples. The focused guides cover:
- Data integrity: failure semantics, sessions, migrations, and transactions.
- Data shape: schemas, models, and codecs.
- Operations: reliability, performance, testing, and incident response.
- Project internals: architecture, replication, security, and compatibility.
Installation
Add OmniStore to your wally.toml:
[dependencies]
OmniStore = "z13ak/omnistore@0.2.0-rc.4"
Then run wally install. Prebuilt files are also available from the
GitHub releases.
GitHub assets and Wally registry publication are separate. If rc.4 is not yet available in the registry, use the matching GitHub release model; rc.3 does not contain these reliability fixes.
Development
With Rokit installed:
rokit install
wally install
rojo build default.project.json -o OmniStore.rbxm
rojo build dev.project.json -o OmniStoreDevelopment.rbxlx
rojo serve test.project.json
stylua --check src tests examples
selene src tests examples
On Windows, ./scripts/verify.ps1 runs the local format, lint, build, and package checks.
After wally install, connect Studio to test.project.json; tests/init.server.lua runs the
TestEZ suite. DataStore testing requires a
published test place with Enable Studio Access to API Services enabled; use a separate test
universe, never a production universe.
Pull requests run formatting, linting, all Rojo builds, and Wally package inspection in CI. Studio TestEZ and isolated-universe DataStore smoke tests remain explicit runtime release gates.
The reviewed library source passed 103 TestEZ tests and dedicated-universe integration checks. Reported checks for locking, handover, crash recovery, stale-owner protection, failed loads/saves, and shutdown persistence are recorded in the manual test results, including the limits of the recorded evidence. These results do not establish production-scale capacity or compatibility with a game's existing data.
License
MIT. See LICENSE.
Package Details
Install command (Click to copy)
Version
0.2.0-rc.4
License
MIT
Safe for commercial use
Automated license review — not legal advice.
