{"id":"z13ak/omnistore","name":"omnistore","scope":"z13ak","platform":"roblox","description":"Typed, game-agnostic Roblox persistence with leases, migrations, and safe mutation APIs","version":"0.2.0-rc.4","latest":"0.2.0-rc.4","versions":["0.2.0-rc.3","0.2.0-rc.4"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"9f00a471756d01a3cb6c2235d17166e925e8e10eb34e539a69cab1b6c9e75463","likes":0,"downloads":0,"install":"forest install z13ak/omnistore","url":"https://forest.dev/p/roblox/z13ak/omnistore","files":"https://api.forest.dev/ai/package/roblox/z13ak/omnistore/files","readme":"<p align=\"center\">\r\n  <img src=\"assets/github-banner.png\" alt=\"OmniStore — Typed Persistence for Roblox\" width=\"100%\">\r\n</p>\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://github.com/z13ak/OmniStore/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/z13ak/OmniStore/actions/workflows/ci.yml/badge.svg\"></a>\r\n  <a href=\"https://github.com/z13ak/OmniStore/releases\"><img alt=\"Release\" src=\"https://img.shields.io/github/v/release/z13ak/OmniStore?include_prereleases&sort=semver\"></a>\r\n  <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-22c55e.svg\"></a>\r\n</p>\r\n\r\nOmniStore is a typed persistence library for Roblox:\r\n\r\n`OmniStore -> Store -> Record -> Data`\r\n\r\nA record key can represent any durable entity: a player, server, guild, world, plot, or something\r\nspecific to your game. Stores add schemas, migrations, session leases, autosave, and safe mutation\r\nhelpers on top of Roblox DataStores. Read-only client replication is optional.\r\n\r\n> **Status:** `0.2.0-rc.4` is a release candidate. It adds persistence reliability fixes and expanded\r\n> regression coverage. Validate migrations and representative stored data in a separate test universe\r\n> before upgrading a production experience.\r\n\r\n## Quick start\r\n\r\n```lua\r\nlocal Players = game:GetService(\"Players\")\r\nlocal OmniStore = require(game.ReplicatedStorage.Packages.OmniStore)\r\n\r\nlocal data = OmniStore.new({ namespace = \"MyGame\" })\r\nlocal profiles = data:GetStore(\"Profiles\", {\r\n    template = {\r\n        Coins = 0,\r\n        Inventory = {},\r\n        Settings = { Music = true },\r\n    },\r\n    schemaVersion = 1,\r\n})\r\n\r\nPlayers.PlayerAdded:Connect(function(player)\r\n    local loaded = profiles:LoadAsync(player.UserId)\r\n    if not loaded.ok then\r\n        warn(\"Profile load failed\", player.UserId, loaded.error.code)\r\n        player:Kick(\"Your data could not be loaded. Please rejoin.\")\r\n        return\r\n    end\r\n\r\n    local profile = loaded.value\r\n    profile:Increment(\"Coins\", 25)\r\n    profile:Insert(\"Inventory\", { Id = \"WoodenSword\" })\r\nend)\r\n\r\nPlayers.PlayerRemoving:Connect(function(player)\r\n    local closed = profiles:CloseRecordAsync(player.UserId, 10)\r\n    if not closed.ok then\r\n        warn(\"Profile close failed\", player.UserId, closed.error.code)\r\n    end\r\nend)\r\n```\r\n\r\nEvery operation that can fail returns `{ ok = true, value = ... }` or\r\n`{ ok = false, error = ... }`. Data reads return defensive copies; mutations must go through the\r\nrecord API so dirty tracking and validation cannot be bypassed accidentally.\r\n\r\n## How writes behave\r\n\r\n- `UpdateAsync`-oriented writes and atomic per-key lease checks.\r\n- A live lease is never intentionally overwritten; expired leases can be recovered.\r\n- Serialization and optional schema validation run before writes.\r\n- Retryable adapter failures use bounded exponential backoff with jitter.\r\n- Concurrent save calls coalesce, while mutations made during a save remain dirty.\r\n- `CloseAsync` saves and releases the lease in the same atomic update.\r\n- In-memory transactions use isolated drafts and publish changes only after a successful commit.\r\n- Replication is server-authoritative and exposes only explicitly allowed paths.\r\n\r\n## Important limits\r\n\r\n### Upgrading from rc.3\r\n\r\nThis candidate changes deletion to retain empty tombstones and escapes literal tables that resemble\r\ncodec markers. Old readers do not safely understand every new representation, and old deletion\r\npaths can bypass the updated lease checks. Pause writes and drain all rc.3 servers before enabling\r\ndeletion or new-format writes. Reverting to rc.3 after those writes is unsafe; see the\r\n[compatibility and upgrade procedure](docs/COMPATIBILITY.md).\r\n\r\n### Persistence guarantees\r\n\r\nOmniStore cannot provide database-wide ACID transactions, guaranteed shutdown saves, protection\r\nfrom a compromised server, or immunity to Roblox outages and platform limits. A transaction is\r\natomic only in local memory until a later single-record save. Roblox `UpdateAsync` supplies the\r\natomic compare/transform behavior for one key; operations across keys are not atomic. See\r\n[failure semantics](docs/FAILURE_SEMANTICS.md) and [security](docs/SECURITY.md).\r\n\r\n## Documentation\r\n\r\nStart with the [API reference](docs/API.md), [configuration guide](docs/CONFIGURATION.md), and\r\n[examples](examples). The focused guides cover:\r\n\r\n- Data integrity: [failure semantics](docs/FAILURE_SEMANTICS.md),\r\n  [sessions](docs/SESSIONS.md), [migrations](docs/MIGRATIONS.md), and\r\n  [transactions](docs/TRANSACTIONS.md).\r\n- Data shape: [schemas, models, and codecs](docs/SCHEMAS_MODELS_CODECS.md).\r\n- Operations: [reliability](docs/RELIABILITY.md), [performance](docs/PERFORMANCE.md),\r\n  [testing](docs/TESTING.md), and [incident response](docs/INCIDENT_RESPONSE.md).\r\n- Project internals: [architecture](docs/ARCHITECTURE.md),\r\n  [replication](docs/REPLICATION.md), [security](docs/SECURITY.md), and\r\n  [compatibility](docs/COMPATIBILITY.md).\r\n\r\n## Installation\r\n\r\nAdd OmniStore to your `wally.toml`:\r\n\r\n```toml\r\n[dependencies]\r\nOmniStore = \"z13ak/omnistore@0.2.0-rc.4\"\r\n```\r\n\r\nThen run `wally install`. Prebuilt files are also available from the\r\n[GitHub releases](https://github.com/z13ak/OmniStore/releases).\r\n\r\nGitHub assets and Wally registry publication are separate. If rc.4 is not yet available in the\r\nregistry, use the matching GitHub release model; rc.3 does not contain these reliability fixes.\r\n\r\n## Development\r\n\r\nWith [Rokit](https://github.com/rojo-rbx/rokit) installed:\r\n\r\n```sh\r\nrokit install\r\nwally install\r\nrojo build default.project.json -o OmniStore.rbxm\r\nrojo build dev.project.json -o OmniStoreDevelopment.rbxlx\r\nrojo serve test.project.json\r\nstylua --check src tests examples\r\nselene src tests examples\r\n```\r\n\r\nOn Windows, `./scripts/verify.ps1` runs the local format, lint, build, and package checks.\r\n\r\nAfter `wally install`, connect Studio to `test.project.json`; `tests/init.server.lua` runs the\r\nTestEZ suite. DataStore testing requires a\r\npublished test place with **Enable Studio Access to API Services** enabled; use a separate test\r\nuniverse, never a production universe.\r\n\r\nPull requests run formatting, linting, all Rojo builds, and Wally package inspection in CI. Studio\r\nTestEZ and isolated-universe DataStore smoke tests remain explicit runtime release gates.\r\n\r\nThe reviewed library source passed 103 TestEZ tests and dedicated-universe integration checks.\r\nReported checks for locking, handover, crash recovery, stale-owner protection, failed loads/saves,\r\nand shutdown persistence are recorded in the [manual test results](docs/MANUAL_TESTS.md), including\r\nthe limits of the recorded evidence. These results do not establish production-scale capacity or\r\ncompatibility with a game's existing data.\r\n\r\n## License\r\n\r\nMIT. See [LICENSE](LICENSE).\r\n","readmeTruncated":false}