Skip to main content

DocumentStore

Represents a collection of Documents, analagous to a DataStore.

warning

Multiple DocumentStores can be created for the same DataStore. You should avoid this, as they will return different Document objects in different sessions. If you need to access the same DocumentStore in multiple scripts, create a module and require that module. Do not use DocumentService with Actors or Parallel Luau.

Functions​

new​

</>
DocumentStore.new(props: DocumentStoreProps) → DocumentStore<T>

Types

​

interface DocumentStoreProps {
dataStore: DataStore--

The object returned by DataStoreService:GetDataStore()

check: (unknown) → (
boolean,
T
)--

A type check function for your data, errors if types are invalid

default: T&{}--

Default values, which are set if keys are empty

migrations: Migrations--

Migrations

lockSessions: boolean--

Should the documents be session locked?

bindToClose: boolean?--

Should the DocumentStore close all documents on BindToClose? [default=true] (This should always be true in production)

}

Creates a new DocumentStore.

warning

This should only be called once per server for each DataStore in a live game. If there are multiple instances of a DocumentStore for one key, any Documents will be treated as if they are from different sessions. This is useful for unit testing but can lead to weird bugs in production. DocumentStores should persist through an entire server's lifespan and are not garbage collected.

GetDocument​

</>
DocumentStore.GetDocument(
self: DocumentStore<T>,
key: string
) → (
boolean--

whether a new document was created

)

Gets the document for the key given, or creates one if it does not exist.

info

Documents are cached in a weak table, so once they are closed, they will be marked for garbage collection if you have no references to them. Be careful of references created by closures.

Documents that are not session locked will be garbage collected once there are no other references to them.

CloseAllDocuments​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
DocumentStore.CloseAllDocuments(self: DocumentStore<T>) → ()

Closes all open documents as fast as possible. This runs on BindToClose already.

Will also wait for any documents that are opening to open, and then close them.

warning

Yields until all documents are closed. If there is a systematic error in your :Close, for example a hook errors, this could infinitely yield.

Closes documents asynchronously when request budget allows, and yields all open documents are closed.

isDocumentStore​

</>
DocumentStore.isDocumentStore(instance: metatable) → boolean

Checks if a metatable passed is a DocumentStore.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new DocumentStore.\n\n:::warning\nThis should only be called once per server for each DataStore in a live game.\nIf there are multiple instances of a DocumentStore for one key, any Documents\nwill be treated as if they are from different sessions. This is useful for\nunit testing but can lead to weird bugs in production. DocumentStores should\npersist through an entire server's lifespan and are not garbage collected.\n:::",
            "params": [
                {
                    "name": "props",
                    "desc": "",
                    "lua_type": "DocumentStoreProps"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DocumentStore<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 85,
                "path": "src/DocumentStore.luau"
            }
        },
        {
            "name": "GetDocument",
            "desc": "Gets the document for the key given, or creates one if it does not exist.\n\n:::info\nDocuments are cached in a weak table, so once they are closed, they will\nbe marked for garbage collection if you have no references to them. Be\ncareful of references created by closures.\n\nDocuments that are not session locked will be garbage collected once there\nare no other references to them.\n:::",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DocumentStore<T>"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Document<T>"
                },
                {
                    "desc": "whether a new document was created",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 129,
                "path": "src/DocumentStore.luau"
            }
        },
        {
            "name": "CloseAllDocuments",
            "desc": "Closes all open documents as fast as possible. This runs on BindToClose already.\n\nWill also wait for any documents that are opening to open, and then close them.\n\n:::warning\nYields until all documents are closed. If there is a systematic error\nin your :Close, for example a hook errors, this could infinitely yield.\n:::\n\nCloses documents asynchronously when request budget allows, and yields\nall open documents are closed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DocumentStore<T>"
                }
            ],
            "returns": [],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 182,
                "path": "src/DocumentStore.luau"
            }
        },
        {
            "name": "isDocumentStore",
            "desc": "Checks if a metatable passed is a DocumentStore.",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "metatable"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 257,
                "path": "src/DocumentStore.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "DocumentStoreProps",
            "desc": "",
            "fields": [
                {
                    "name": "dataStore",
                    "lua_type": "DataStore",
                    "desc": "The object returned by DataStoreService:GetDataStore()"
                },
                {
                    "name": "check",
                    "lua_type": "(unknown) -> (boolean, T)",
                    "desc": "A type check function for your data, errors if types are invalid"
                },
                {
                    "name": "default",
                    "lua_type": "T & {}",
                    "desc": "Default values, which are set if keys are empty"
                },
                {
                    "name": "migrations",
                    "lua_type": "Migrations",
                    "desc": "Migrations"
                },
                {
                    "name": "lockSessions",
                    "lua_type": "boolean",
                    "desc": "Should the documents be session locked?"
                },
                {
                    "name": "bindToClose",
                    "lua_type": "boolean?",
                    "desc": "Should the DocumentStore close all documents on BindToClose? [default=true] (This should always be true in production)"
                }
            ],
            "source": {
                "line": 70,
                "path": "src/DocumentStore.luau"
            }
        }
    ],
    "name": "DocumentStore",
    "desc": "Represents a collection of Documents, analagous to a DataStore.\n\n:::warning\nMultiple DocumentStores can be created for the same DataStore. You should\navoid this, as they will return different Document objects in different\nsessions. If you need to access the same DocumentStore in multiple scripts,\ncreate a module and require that module. Do not use DocumentService\nwith Actors or Parallel Luau.\n:::",
    "source": {
        "line": 24,
        "path": "src/DocumentStore.luau"
    }
}