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: (
updateData: 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.

caution

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

warning

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

caution

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

Manually Saves a Keep. Commonly useful for speeding up global updates

caution

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

warning

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

warning

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 keep = keepStore:ViewKeep(player.UserId, versionInfo.Version):expect()

		if keep.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>,
GlobalStateProcessor: (
update: GlobalUpdateData,
lock: () → (),
remove: () → ()
) → (),
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

warning

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

caution

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)

caution

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

warning

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

Show raw api
{
    "functions": [
        {
            "name": "Save",
            "desc": "Manually Saves a Keep. Commonly useful for speeding up global updates\n\n:::caution\nCalling ```:Save()``` manually will reset the auto save timer on the Keep.\n:::caution\n\n:::warning\nUsing ```:Save()``` on a **view-only Keep** will error. Use [:Overwrite()](#Overwrite) instead.\n:::warning",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 455,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "Release",
            "desc": "Releases the session lock to allow other servers to access the Keep\n\n:::warning\nThis is called before internal release, but after session release, no edits can be made after this point.\n:::warning",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 498,
                "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": 539,
                "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": 622,
                "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": 644,
                "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": 663,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "GetKeyInfo",
            "desc": "Returns the ```DataStoreKeyInfo``` for the Keep",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DataStoreKeyInfo"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 676,
                "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": 687,
                "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": 717,
                "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": 734,
                "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 keep = keepStore:ViewKeep(player.UserId, versionInfo.Version):expect()\n\n\t\tif keep.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": 796,
                "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:::warning\nWill not save until the next loop unless otherwise called using [:Save()](#Save) or [:Overwrite()](#Overwrite) for view-only Keeps.\n:::warning\n\n:::caution\nAny global updates not taken care of in ```migrateProcessor``` will be lost.\n:::caution",
            "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": 934,
                "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": 989,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "GetLockedGlobalUpdates",
            "desc": "Returns an array of locked global updates (processed)\n\n:::caution\nLock updates can **not** be changed, only cleared after done being used.\n:::caution",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ GlobalUpdate }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1016,
                "path": "src/Keep.luau"
            }
        },
        {
            "name": "ClearLockedUpdate",
            "desc": "Clears a locked global update after being used\n\n:::warning\nPassing an **active** global update id will throw an error & reject the Promise.\n:::warning",
            "params": [
                {
                    "name": "id",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 1045,
                "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:::caution\nUpdates **must** be locked eventually in order for [.OnGlobalUpdate](#OnGlobalUpdate) to get fired.\n:::caution\n\n:::warning\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:::warning",
            "lua_type": "(updateData: GlobalUpdateData, lock: () -> (), remove: () -> ()) -> ()",
            "source": {
                "line": 53,
                "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:::caution\n**ONLY** locked globals are fired.\n:::caution",
            "lua_type": "Signal<GlobalUpdateData, number>",
            "source": {
                "line": 64,
                "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": 83,
                "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": 102,
                "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": 115,
                "path": "src/Keep.luau"
            }
        }
    ],
    "types": [
        {
            "name": "Session",
            "desc": "",
            "lua_type": "{ PlaceId: number, JobId: string }",
            "source": {
                "line": 90,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "MetaData",
            "desc": "",
            "lua_type": "{ ActiveSession: Session?, ForceLoad: Session?, LastUpdate: number, Created: number, LoadCount: number }",
            "source": {
                "line": 100,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "Keep",
            "desc": "",
            "lua_type": "{ Data: { [string]: any }, MetaData: MetaData, GlobalUpdates: GlobalUpdates, UserIds: { number }, OnGlobalUpdate: Signal<GlobalUpdateData, number>, GlobalStateProcessor: (update: GlobalUpdateData, lock: () -> (), remove: () -> ()) -> (), Releasing: Signal<Promise>, Saving: Signal<Promise>, Overwritten: Signal<boolean> }",
            "source": {
                "line": 128,
                "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": 765,
                "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"
    }
}