Skip to main content

Keep

This item only works when running on the server. Server

Keep class holds the data for a specific key in a store, and methods to manipulate data.

Types​

Session​

</>
type Session = {
PlaceId: number,
JobId: string
}

MetaData​

</>
type MetaData = {
ActiveSession: Session?,
ForceLoad: Session?,
LastUpdate: number,
Created: number,
LoadCount: number
}

Properties​

GlobalStateProcessor​

</>
Keep.GlobalStateProcessor: (
globalUpdateData: GlobalUpdateData,
lock: () → (),
remove: () → ()
) → ()

Define how to process global updates, by default just locks the global update (this is only ran if the Keep is online).

The function reveals the lock and remove global update function through the parameters.

WARNING

Updates must be locked eventually in order for .OnGlobalUpdate to get fired.

DANGER

The lock and remove function revealed here are NOT the same as the ones in the Keep class, they are only for this function.

OnGlobalUpdate​

</>
Keep.OnGlobalUpdate: Signal<GlobalUpdateData,number>

Fired when a new global update is locked and ready to be processed, which can happen only during save.

WARNING

ONLY locked globals are fired.

Releasing​

</>
Keep.Releasing: Signal<Promise<()>>

Fired when the Keep is releasing (fires before internally released, but during session release).

keep.Releasing:Connect(function(state)
	print(`Releasing {keep:Identify()}`)

	state:andThen(function()
		print(`Released {keep:Identify()}`)
	end, function()
		print(`Failed to release {keep:Identify()}`)
	end)
end)

Saving​

</>
Keep.Saving: Signal<Promise<()>>

Fired when the Keep is saving, resolves on complete.

keep.Saving:Connect(function(state)
	print(`Saving {keep:Identify()}`)

	state:andThen(function()
		print(`Saved {keep:Identify()}`)
	end):catch(function()
		print(`Failed to save {keep:Identify()}`)
	end)
end)

Overwritten​

</>
Keep.Overwritten: Signal<boolean>

Fired when the Keep has been overwritten. Keep will be released if isReleasingSession is set to true.

keep.Overwritten:Connect(function(isReleasingSession)
	print(`{keep:Identify()} has been overwritten. Is releasing session: {isReleasingSession}`)
end)

Functions​

Save​

</>
Keep:Save() → Promise<()>

Performs a manual save.

WARNING

Calling :Save() manually will reset the auto save timer on the Keep.

DANGER

Using :Save() on a view-only Keep will error. Use :Overwrite() instead.

Release​

</>
Keep:Release() → Promise<()>

Releases the session lock to allow other servers to access the Keep.

DANGER

This is called before internal release, but after session release, no edits can be made after this point.

Overwrite​

</>
Keep:Overwrite(shouldKeepExistingSession: boolean?) → Promise<()>

Used to overwrite a view-only Keep.

shouldKeepExistingSession controls the behavior of the server with the active session lock, defaults to false.

Destroy​

</>
Keep:Destroy() → ()

Destroys the Keep, removing all signals connections. Should be used only for cleaning view-only Keeps.

IsActive​

</>
Keep:IsActive() → boolean

Returns true if the Keep is active in the session (not locked by another server).

Identify​

</>
Keep:Identify() → string

Returns the string identifier for the Keep.

GetKeyInfo​

</>
Keep:GetKeyInfo() → DataStoreKeyInfo

Returns the DataStoreKeyInfo for the Keep.

Reconcile​

</>
Keep:Reconcile() → ()

Fills in any missing data in the Keep using the data template.

AddUserId​

</>
Keep:AddUserId(userId: number) → ()

Associates a userId to a datastore to assist with GDPR requests (The right to erasure).

RemoveUserId​

</>
Keep:RemoveUserId(userId: number) → ()

Unassociates a userId from a datastore.

GetVersions​

</>
Keep:GetVersions(
minDate: number?,
maxDate: number?
) → Promise<Iterator>

Types

​

interface Iterator {
Current: () → DataStoreObjectVersionInfo?--

Returns the current versionInfo, nil if none.

Next: () → DataStoreObjectVersionInfo?--

Returns the next versionInfo, nil if none.

Previous: () → DataStoreObjectVersionInfo?--

Returns the previous versionInfo, nil if none.

PageUp: () → ()--

Goes to the next page of versions.

PageDown: () → ()--

Goes to the previous page of versions.

SkipEnd: () → ()--

Goes to the last page of versions.

SkipStart: () → ()--

Goes to the first page of versions.

}

Grabs past versions of the Keep and returns an iterator to customize how to handle the versions.

"I lost my progress! Last time I had 200 gems!"

keep:GetVersions():andThen(function(iterator)
	local versionInfo = iterator.Current()

	while versionInfo do
		local oldKeep = store:ViewKeep(player.UserId, versionInfo.Version):expect()

		if oldKeep.Data.Gems >= 200 then
			print("Found the version with 200 gems!")
			break
		end

		versionInfo = iterator.Next()
	end
end)

SetVersion​

</>
Keep:SetVersion(
version: string,
migrateProcessor: ((versionKeep: Keep) → Keep)?
) → Promise<Keep>

Types

​

type Keep = {
Data: {[string]: any},
MetaData: MetaData,
GlobalUpdates: GlobalUpdates,
UserIds: {number},
OnGlobalUpdate: Signal<GlobalUpdateData,
number>,
Releasing: Signal<Promise<()>>,
Saving: Signal<Promise<()>>,
Overwritten: Signal<boolean>
}

Allows for a manual versioning process, where the version is set and the data is migrated to the new version using the optional migrateProcessor function.

DataKeep provides a version list iterator. See :GetVersions().

Returns a Promise that resolves to the old Keep (before the migration) This is the last time the old Keep's GlobalUpdates will be accessible before permanently being removed.

DANGER

Will not save until the next loop unless otherwise called using :Save() or :Overwrite() for view-only Keeps.

WARNING

Any global updates not taken care of in migrateProcessor will be lost.

GetActiveGlobalUpdates​

</>
Keep:GetActiveGlobalUpdates() → {GlobalUpdate}

Returns an array of active global updates (not locked / processed).

GetLockedGlobalUpdates​

</>
Keep:GetLockedGlobalUpdates() → {GlobalUpdate}

Returns an array of locked global updates (processed).

WARNING

Lock updates can not be changed, only cleared after done being used.

ClearLockedUpdate​

</>
Keep:ClearLockedUpdate(id: number) → Promise<()>

Clears a locked global update after being used.

DANGER

Passing an active global update id will throw an error & reject the Promise.

Show raw api
{
    "functions": [
        {
            "name": "Save",
            "desc": "Performs a manual save.\n\n:::warning\nCalling ```:Save()``` manually will reset the auto save timer on the Keep.\n:::\n\n:::danger\nUsing ```:Save()``` on a **view-only Keep** will error. Use [:Overwrite()](#Overwrite) instead.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 442,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Release",
            "desc": "Releases the session lock to allow other servers to access the Keep.\n\n:::danger\nThis is called before internal release, but after session release, no edits can be made after this point.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 494,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Overwrite",
            "desc": "Used to overwrite a view-only Keep.\n\n```shouldKeepExistingSession``` controls the behavior of the server with the active session lock, defaults to ```false```.",
            "params": [
                {
                    "name": "shouldKeepExistingSession",
                    "desc": "",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 542,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the Keep, removing all signals connections. Should be used only for cleaning view-only Keeps.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 644,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "IsActive",
            "desc": "Returns ```true``` if the Keep is active in the session (not locked by another server).",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 666,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Identify",
            "desc": "Returns the string identifier for the Keep.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 685,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "GetKeyInfo",
            "desc": "Returns the ```DataStoreKeyInfo``` for the Keep.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DataStoreKeyInfo"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 698,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Reconcile",
            "desc": "Fills in any missing data in the Keep using the data template.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 709,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "AddUserId",
            "desc": "Associates a ```userId``` to a datastore to assist with GDPR requests (The right to erasure).",
            "params": [
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 739,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "RemoveUserId",
            "desc": "Unassociates a ```userId``` from a datastore.",
            "params": [
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 756,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "GetVersions",
            "desc": "Grabs past versions of the Keep and returns an iterator to customize how to handle the versions.\n\n\"I lost my progress! Last time I had 200 gems!\"\n\n```lua\nkeep:GetVersions():andThen(function(iterator)\n\tlocal versionInfo = iterator.Current()\n\n\twhile versionInfo do\n\t\tlocal oldKeep = store:ViewKeep(player.UserId, versionInfo.Version):expect()\n\n\t\tif oldKeep.Data.Gems >= 200 then\n\t\t\tprint(\"Found the version with 200 gems!\")\n\t\t\tbreak\n\t\tend\n\n\t\tversionInfo = iterator.Next()\n\tend\nend)\n```",
            "params": [
                {
                    "name": "minDate",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "maxDate",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<Iterator>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 818,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "SetVersion",
            "desc": "Allows for a manual versioning process, where the version is set and the data is migrated to the new version using the optional ```migrateProcessor``` function.\n\nDataKeep provides a version list iterator. See [:GetVersions()](#GetVersions).\n\nReturns a Promise that resolves to the old Keep (before the migration) This is the **last** time the old Keep's GlobalUpdates will be accessible before **permanently** being removed.\n\n:::danger\nWill not save until the next loop unless otherwise called using [:Save()](#Save) or [:Overwrite()](#Overwrite) for view-only Keeps.\n:::\n\n:::warning\nAny global updates not taken care of in ```migrateProcessor``` will be lost.\n:::",
            "params": [
                {
                    "name": "version",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "migrateProcessor",
                    "desc": "",
                    "lua_type": "((versionKeep: Keep) -> Keep)?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<Keep>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 956,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "GetActiveGlobalUpdates",
            "desc": "Returns an array of active global updates (not locked / processed).",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ GlobalUpdate }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1011,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "GetLockedGlobalUpdates",
            "desc": "Returns an array of locked global updates (processed).\n\n:::warning\nLock updates can **not** be changed, only cleared after done being used.\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ GlobalUpdate }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1038,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "ClearLockedUpdate",
            "desc": "Clears a locked global update after being used.\n\n:::danger\nPassing an **active** global update id will throw an error & reject the Promise.\n:::",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1067,
                "path": "src/Keep.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "GlobalStateProcessor",
            "desc": "Define how to process global updates, by default just locks the global update (this is only ran if the Keep is online).\n\nThe function reveals the lock and remove global update function through the parameters.\n\n:::warning\nUpdates **must** be locked eventually in order for [.OnGlobalUpdate](#OnGlobalUpdate) to get fired.\n:::\n\n:::danger\nThe lock and remove function revealed here are **NOT** the same as the ones in the Keep class, they are only for this function.\n:::",
            "lua_type": "(globalUpdateData: GlobalUpdateData, lock: () -> (), remove: () -> ()) -> ()",
            "source": {
                "line": 47,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "OnGlobalUpdate",
            "desc": "Fired when a new global update is locked and ready to be processed, which can happen only during save.\n\n:::warning\n**ONLY** locked globals are fired.\n:::",
            "lua_type": "Signal<GlobalUpdateData, number>",
            "source": {
                "line": 58,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Releasing",
            "desc": "Fired when the Keep is releasing (fires before internally released, but during session release).\n\n```lua\nkeep.Releasing:Connect(function(state)\n\tprint(`Releasing {keep:Identify()}`)\n\n\tstate:andThen(function()\n\t\tprint(`Released {keep:Identify()}`)\n\tend, function()\n\t\tprint(`Failed to release {keep:Identify()}`)\n\tend)\nend)\n```",
            "lua_type": "Signal<Promise<()>>",
            "source": {
                "line": 77,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Saving",
            "desc": "Fired when the Keep is saving, resolves on complete.\n\n```lua\nkeep.Saving:Connect(function(state)\n\tprint(`Saving {keep:Identify()}`)\n\n\tstate:andThen(function()\n\t\tprint(`Saved {keep:Identify()}`)\n\tend):catch(function()\n\t\tprint(`Failed to save {keep:Identify()}`)\n\tend)\nend)\n```",
            "lua_type": "Signal<Promise<()>>",
            "source": {
                "line": 96,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Overwritten",
            "desc": "Fired when the Keep has been overwritten. Keep will be released if ```isReleasingSession``` is set to ```true```.\n\n```lua\nkeep.Overwritten:Connect(function(isReleasingSession)\n\tprint(`{keep:Identify()} has been overwritten. Is releasing session: {isReleasingSession}`)\nend)\n```",
            "lua_type": "Signal<boolean>",
            "source": {
                "line": 109,
                "path": "src/Keep.luau"
            }
        }
    ],
    "types": [
        {
            "name": "Session",
            "desc": "",
            "lua_type": "{ PlaceId: number, JobId: string }",
            "source": {
                "line": 147,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "MetaData",
            "desc": "",
            "lua_type": "{ ActiveSession: Session?, ForceLoad: Session?, LastUpdate: number, Created: number, LoadCount: number }",
            "source": {
                "line": 157,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "Keep",
            "desc": "",
            "lua_type": "{ Data: { [string]: any }, MetaData: MetaData, GlobalUpdates: GlobalUpdates, UserIds: { number }, OnGlobalUpdate: Signal<GlobalUpdateData, number>, Releasing: Signal<Promise<()>>, Saving: Signal<Promise<()>>, Overwritten: Signal<boolean> }",
            "source": {
                "line": 217,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "Iterator",
            "desc": "",
            "fields": [
                {
                    "name": "Current",
                    "lua_type": "() -> DataStoreObjectVersionInfo?",
                    "desc": "Returns the current versionInfo, nil if none."
                },
                {
                    "name": "Next",
                    "lua_type": "() -> DataStoreObjectVersionInfo?",
                    "desc": "Returns the next versionInfo, nil if none."
                },
                {
                    "name": "Previous",
                    "lua_type": "() -> DataStoreObjectVersionInfo?",
                    "desc": "Returns the previous versionInfo, nil if none."
                },
                {
                    "name": "PageUp",
                    "lua_type": "() -> ()",
                    "desc": "Goes to the next page of versions."
                },
                {
                    "name": "PageDown",
                    "lua_type": "() -> ()",
                    "desc": "Goes to the previous page of versions."
                },
                {
                    "name": "SkipEnd",
                    "lua_type": "() -> ()",
                    "desc": "Goes to the last page of versions."
                },
                {
                    "name": "SkipStart",
                    "lua_type": "() -> ()",
                    "desc": "Goes to the first page of versions."
                }
            ],
            "source": {
                "line": 787,
                "path": "src/Keep.luau"
            }
        }
    ],
    "name": "Keep",
    "desc": "Keep class holds the data for a specific key in a store, and methods to manipulate data.",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 30,
        "path": "src/Keep.luau"
    }
}