Skip to main content

Document

Functions​

read​

</>
Document:read() → any

Returns the document's data.

write​

</>
Document:write(data: any) → ()

Updates the document's cached data. This method doesn't save the data to the DataStore; it only modifies the document's in-memory data.

This method should be used when performing immutable updates to the document's data. For mutable updates, the data can be directly modified: 

local data = document:read()
data.coins += 100
warning

Throws an error if the document was closed or if the data is invalid.

addUserId​

</>
Document:addUserId(userId: number) → ()

Adds a user id to the document's DataStoreKeyInfo:GetUserIds(). The change won't apply until the document is saved or closed.

If the user id is already associated with the document the method won't do anything.

removeUserId​

</>
Document:removeUserId(userId: number) → ()

Removes a user id from the document's DataStoreKeyInfo:GetUserIds(). The change won't apply until the document is saved or closed.

If the user id is not associated with the document the method won't do anything.

keyInfo​

</>
Document:keyInfo() → DataStoreKeyInfo

Returns the last updated DataStoreKeyInfo returned from loading, saving, or closing the document.

save​

</>
Document:save() → Promise<()>

Saves the document's data. If the save is throttled and you call it multiple times, it will save only once with the latest data.

Documents are saved automatically. This method is used mainly to handle developer product purchases (see the example) or other situations requiring immediate saving.

warning

Throws an error if the document was closed.

warning

If the beforeSave callback yields or errors, the returned promise will reject and the data will not be saved.

close​

</>
Document:close() → Promise<()>

Saves the document and removes the session lock. The document is unusable after calling. If a save is currently in progress it will close the document instead.

If called again, it will return the promise from the original call.

warning

If the beforeSave or beforeClose callbacks yield or error, the returned promise will reject and the data will not be saved.

beforeSave​

</>
Document:beforeSave(callback: () → ()) → ()

Sets a callback that is run inside document:save and document:close before it saves. The document can be read and written to in the callback.

The callback will run before the beforeClose callback inside of document:close.

warning

Throws an error if it was called previously.

beforeClose​

</>
Document:beforeClose(callback: () → ()) → ()

Sets a callback that is run inside document:close before it saves. The document can be read and written to in the callback.

warning

Throws an error if it was called previously.

Show raw api
{
    "functions": [
        {
            "name": "read",
            "desc": "Returns the document's data.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 50,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "write",
            "desc": "Updates the document's cached data. This method doesn't save the data to the DataStore; it only modifies the\ndocument's in-memory data.\n\nThis method should be used when performing immutable updates to the document's data. For mutable updates, the data\ncan be directly modified:\n```lua\nlocal data = document:read()\ndata.coins += 100\n```\n\n:::warning\nThrows an error if the document was closed or if the data is invalid.\n:::",
            "params": [
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 71,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "addUserId",
            "desc": "Adds a user id to the document's `DataStoreKeyInfo:GetUserIds()`. The change won't apply until the document is\nsaved or closed.\n\nIf the user id is already associated with the document the method won't do anything.",
            "params": [
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 93,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "removeUserId",
            "desc": "Removes a user id from the document's `DataStoreKeyInfo:GetUserIds()`. The change won't apply until the document is\nsaved or closed.\n\nIf the user id is not associated with the document the method won't do anything.",
            "params": [
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 109,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "keyInfo",
            "desc": "Returns the last updated `DataStoreKeyInfo` returned from loading, saving, or closing the document.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DataStoreKeyInfo"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 124,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "save",
            "desc": "Saves the document's data. If the save is throttled and you call it multiple times, it will save only once with the\nlatest data.\n\nDocuments are saved automatically. This method is used mainly to handle developer product purchases\n(see the [example](../docs/DeveloperProduct)) or other situations requiring immediate saving.\n\n:::warning\nThrows an error if the document was closed.\n:::\n\n:::warning\nIf the beforeSave callback yields or errors, the returned promise will reject and the data will not be saved.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 145,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "close",
            "desc": "Saves the document and removes the session lock. The document is unusable after calling. If a save is currently in\nprogress it will close the document instead.\n\nIf called again, it will return the promise from the original call.\n\n:::warning\nIf the beforeSave or beforeClose callbacks yield or error, the returned promise will reject and the data will not be saved.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 195,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "beforeSave",
            "desc": "Sets a callback that is run inside `document:save` and `document:close` before it saves. The document can be read and written to in the\ncallback.\n\nThe callback will run before the beforeClose callback inside of `document:close`.\n\n:::warning\nThrows an error if it was called previously.\n:::",
            "params": [
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 271,
                "path": "src/Document.luau"
            }
        },
        {
            "name": "beforeClose",
            "desc": "Sets a callback that is run inside `document:close` before it saves. The document can be read and written to in the\ncallback.\n\n:::warning\nThrows an error if it was called previously.\n:::",
            "params": [
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 287,
                "path": "src/Document.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Document",
    "desc": "",
    "source": {
        "line": 29,
        "path": "src/Document.luau"
    }
}