@rbxts/document-service

DocumentService - A powerful, schematised Roblox datastore library

DocumentService is a fully strictly typed Luau library for saving data with Roblox DataStores. It can be used for sesssion-locked data, such as player data, or for non-session-locked data, like shared groups or houses.

See the docs for more information.

This is a new release and, although it has been thoroughly unit tested, it hasn't yet been used in a live production game - as with any open source software, use it at your own risk! I am working on adding it to my game, so this will not be a concern for too long.

Features

• Fully strictly typed. This means you get full intellisense and typechecking on your data, and on every API method, including possible errors for each method.
• Superior Rust-inspired error handling (Result types).
• Immutable cache and autosaves - preventing bugs caused by updates interfering with eachother.
• Migrations, inspired by nezuo's Lapis.
• Validate your data with support for runtime and static typechecking.
• Documents can be session-locked, or not (to allow multi-server editing).
• Run hooks before and after operations, e.g. logging.
• Automatic retries with exponential backoff.
• Migrate from no library, or another library if you're brave.
• Checks your data can be stored in JSON to avoid silent errors.
• Simple API: session-locking a document simply extends the API.
• Use any Mock DataStore you like.

Installation

Method 1: Wally

Add DocumentService = "anthony0br/documentservice@LATEST_VERSION" to your wally.toml.

Method 2: Manual

DocumentService has no dependencies so you can just copy and paste the contents of target/roblox into your project.

Long-term goals

• ACID transactions involving multiple Documents. Please get in touch if you can help with this!
• See the issues page to discuss ways to make DocumentService better!

Inspiration

This library takes inspiration from Lapis, ProfileService, keyForm, and kampfkarren's blog. These are all great projects but didn't meet my needs in some way.

Contributing

Contributions are accepted. Your contributions must run in Lune directly from src and, when compiled by darklua to target/roblox, in Roblox. You should use moonwave to update/generate documentation.

To build for Roblox:

1. Install necessary tools (see aftman.toml).
2. Run rojo sourcemap source.project.json -o sourcemap.json. It is necessary to generate a sourcemap of the src folder so darklua can convert our requires.
3. Run darklua process src target/roblox.

Contact

The best way to get in touch is to ping me in the thread in the Roblox OSS discord, or create an issue.