Skip to main content

Types

This item is only intended to be used by the module's authors. Private

Common types shared among different modules.

Types​

PatchOperation​

</>
interface PatchOperation {
op: "add" | "replace" | "remove"--

The operation type.

path: string--

A JSON Pointer string indicating the target location.

value: any?--

The value to add or replace (used for "add" and "replace"). Optional for "remove".

}

Represents a single operation within a JSON Patch array. Used for describing changes between data states.

TxPatch​

</>
type TxPatch = {PatchOperation}

An array of PatchOperation objects representing the changes made during a transaction.

TxInfo​

</>
interface TxInfo {
committedData: any--

The last known data state that was successfully saved to the primary DataStore record before the transaction identified by txId began.

txId: string?--

The unique identifier of the transaction currently attempting to modify this data. If nil, no transaction is active or the last one completed and was cleaned up.

txPatch: TxPatch?--

The set of changes (JSON Patch) applied by the transaction identified by txId. This is used to reconstruct the final state if the transaction is confirmed as committed.

}

Holds information about the state of data potentially involved in a transaction. Used by the Transactions module to determine the correct data to return during reads.

File​

</>
interface File {
data: any?--

The actual data, if it was stored directly (not sharded). Mutually exclusive with shard and count.

shard: string?--

The unique identifier for the set of shards, if the data was sharded. Mutually exclusive with data.

count: number?--

The total number of shards, if the data was sharded. Mutually exclusive with data.

}

Represents the stored data, abstracting away the sharding mechanism.

If the data was small enough, it's stored directly in the data field. If the data was large and sharded, shard and count are present instead, pointing to the location and number of data shards stored separately.

DataStoreRecord​

</>
interface DataStoreRecord {
appliedMigrations: {string}--

A list of names of migration steps that have already been successfully applied to the data associated with this record. Initialized as empty.

file: File--

A File object representing the actual user data. This might contain the data directly or point to shards.

orphanedFiles: {File}--

A list of sharded File objects that are no longer referenced by any active record. This is used for cleanup and garbage collection of unused data. Initialized as empty.

}

The structure of the primary record stored in the main DataStore for each key. This record contains metadata and a reference (File) to the actual user data.

MigrationStep​

</>
interface MigrationStep {
name: string--

The unique name of the migration step.

apply: (data: {[string]: any}) → {[string]: any}--

The function that transforms the data for this step.

}

Represents a migration step that can be applied to data when loading it. Each step has a name and an apply function that takes the data as input and returns a modified version of the data.

StoreContext<T>​

</>
interface StoreContext<T> {
name: string--

The name of the store, used for logging and potentially identifying DataStore keys.

template: T--

A default template object representing the initial state for new data entries.

schema: (value: any) → (
boolean,
string?
)--

A validation function (like one created by t) used to check if loaded or modified data conforms to the expected structure. Returns true if valid, or false and an error message string if invalid.

migrationSteps: {MigrationStep}--

A list of migration steps to apply to data when it's loaded, based on the appliedMigrations field in the DataStoreRecord. Initialized as empty.

importLegacyData: ((key: string) → any?)?--

An optional function to load data from a legacy storage system when a key is accessed for the first time in this store.

dataStoreService: DataStoreService--

The Roblox DataStoreService instance.

memoryStoreService: MemoryStoreService--

The Roblox MemoryStoreService instance.

changedCallbacks: {(
key: string,
newData: T,
oldData: T?
) → ()}--

A list of functions to call whenever data for a key is successfully changed. Provides the key, the new data state, and the previous data state (if available). Initialized as empty.

logger: Logger--

A Logger instance used for internal logging within the store and its components.

onLockLost: ((key: string) → ())?--

An optional callback function triggered if the distributed lock for a key is lost unexpectedly (e.g., due to expiration or external interference).

recordStore: DataStore--

The DataStore used to store DataStoreRecord objects.

shardStore: DataStore--

The DataStore used to store the actual data shards for large files.

txStore: DataStore--

The DataStore used to store transaction status markers (txId keys).

lockHashMap: MemoryStoreHashMap--

The MemoryStore HashMap used for managing distributed locks.

}

Contains all the contextual information and dependencies required for a Store or PlayerStore instance to operate. This includes configuration, service instances, callbacks, and underlying storage objects.

RetryHandle<T>​

</>
interface RetryHandle<T> {
promise: T--

The Promise representing the asynchronous operation being retried. This promise resolves or rejects based on the outcome of the operation after retries.

cancel: () → ()--

A function that can be called to signal cancellation. If called, the retry mechanism will stop further attempts and reject the promise.

}

A handle returned by retry utility functions like hashMapRetry. It bundles the core Promise with a way to cancel the retry operation.

When the cancel function is called, instead of cancelling the Promise itself, the retry mechanism is stopped, and the Promise is rejected with a cancellation error when the next retry attempt is made.

Show raw api
{
    "functions": [],
    "properties": [],
    "types": [
        {
            "name": "PatchOperation",
            "desc": "Represents a single operation within a JSON Patch array.\nUsed for describing changes between data states.",
            "fields": [
                {
                    "name": "op",
                    "lua_type": "\"add\" | \"replace\" | \"remove\"",
                    "desc": "The operation type."
                },
                {
                    "name": "path",
                    "lua_type": "string",
                    "desc": "A JSON Pointer string indicating the target location."
                },
                {
                    "name": "value",
                    "lua_type": "any?",
                    "desc": "The value to add or replace (used for \"add\" and \"replace\"). Optional for \"remove\"."
                }
            ],
            "source": {
                "line": 21,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "TxPatch",
            "desc": "An array of PatchOperation objects representing the changes made during a transaction.",
            "lua_type": "{ PatchOperation }",
            "source": {
                "line": 32,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "TxInfo",
            "desc": "Holds information about the state of data potentially involved in a transaction.\nUsed by the `Transactions` module to determine the correct data to return during reads.",
            "fields": [
                {
                    "name": "committedData",
                    "lua_type": "any",
                    "desc": "The last known data state that was successfully saved to the primary DataStore record *before* the transaction identified by `txId` began."
                },
                {
                    "name": "txId",
                    "lua_type": "string?",
                    "desc": "The unique identifier of the transaction currently attempting to modify this data. If `nil`, no transaction is active or the last one completed and was cleaned up."
                },
                {
                    "name": "txPatch",
                    "lua_type": "TxPatch?",
                    "desc": "The set of changes (JSON Patch) applied by the transaction identified by `txId`. This is used to reconstruct the final state if the transaction is confirmed as committed."
                }
            ],
            "source": {
                "line": 44,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "File",
            "desc": "Represents the stored data, abstracting away the sharding mechanism.\n\nIf the data was small enough, it's stored directly in the `data` field.\nIf the data was large and sharded, `shard` and `count` are present instead,\npointing to the location and number of data shards stored separately.",
            "fields": [
                {
                    "name": "data",
                    "lua_type": "any?",
                    "desc": "The actual data, if it was stored directly (not sharded). Mutually exclusive with `shard` and `count`."
                },
                {
                    "name": "shard",
                    "lua_type": "string?",
                    "desc": "The unique identifier for the set of shards, if the data was sharded. Mutually exclusive with `data`."
                },
                {
                    "name": "count",
                    "lua_type": "number?",
                    "desc": "The total number of shards, if the data was sharded. Mutually exclusive with `data`."
                }
            ],
            "source": {
                "line": 63,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "DataStoreRecord",
            "desc": "The structure of the primary record stored in the main DataStore for each key.\nThis record contains metadata and a reference (`File`) to the actual user data.",
            "fields": [
                {
                    "name": "appliedMigrations",
                    "lua_type": "{string}",
                    "desc": "A list of names of migration steps that have already been successfully applied to the data associated with this record. Initialized as empty."
                },
                {
                    "name": "file",
                    "lua_type": "File",
                    "desc": "A `File` object representing the actual user data. This might contain the data directly or point to shards."
                },
                {
                    "name": "orphanedFiles",
                    "lua_type": "{File}",
                    "desc": "A list of sharded `File` objects that are no longer referenced by any active record. This is used for cleanup and garbage collection of unused data. Initialized as empty."
                }
            ],
            "source": {
                "line": 80,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "MigrationStep",
            "desc": "Represents a migration step that can be applied to data when loading it.\nEach step has a name and an `apply` function that takes the data as input\nand returns a modified version of the data.",
            "fields": [
                {
                    "name": "name",
                    "lua_type": "string",
                    "desc": "The unique name of the migration step."
                },
                {
                    "name": "apply",
                    "lua_type": "(data: { [string]: any }) -> { [string]: any }",
                    "desc": "The function that transforms the data for this step."
                }
            ],
            "source": {
                "line": 96,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "StoreContext<T>",
            "desc": "Contains all the contextual information and dependencies required for a `Store`\nor `PlayerStore` instance to operate. This includes configuration, service instances,\ncallbacks, and underlying storage objects.",
            "fields": [
                {
                    "name": "name",
                    "lua_type": "string",
                    "desc": "The name of the store, used for logging and potentially identifying DataStore keys."
                },
                {
                    "name": "template",
                    "lua_type": "T",
                    "desc": "A default template object representing the initial state for new data entries."
                },
                {
                    "name": "schema",
                    "lua_type": "(value: any) -> (boolean, string?)",
                    "desc": "A validation function (like one created by `t`) used to check if loaded or modified data conforms to the expected structure. Returns `true` if valid, or `false` and an error message string if invalid."
                },
                {
                    "name": "migrationSteps",
                    "lua_type": "{MigrationStep}",
                    "desc": "A list of migration steps to apply to data when it's loaded, based on the `appliedMigrations` field in the `DataStoreRecord`. Initialized as empty."
                },
                {
                    "name": "importLegacyData",
                    "lua_type": "((key: string) -> any?)?",
                    "desc": "An optional function to load data from a legacy storage system when a key is accessed for the first time in this store."
                },
                {
                    "name": "dataStoreService",
                    "lua_type": "DataStoreService",
                    "desc": "The Roblox DataStoreService instance."
                },
                {
                    "name": "memoryStoreService",
                    "lua_type": "MemoryStoreService",
                    "desc": "The Roblox MemoryStoreService instance."
                },
                {
                    "name": "changedCallbacks",
                    "lua_type": "{ (key: string, newData: T, oldData: T?) -> () }",
                    "desc": "A list of functions to call whenever data for a key is successfully changed. Provides the key, the new data state, and the previous data state (if available). Initialized as empty."
                },
                {
                    "name": "logger",
                    "lua_type": "Logger",
                    "desc": "A `Logger` instance used for internal logging within the store and its components."
                },
                {
                    "name": "onLockLost",
                    "lua_type": "((key: string) -> ())?",
                    "desc": "An optional callback function triggered if the distributed lock for a key is lost unexpectedly (e.g., due to expiration or external interference)."
                },
                {
                    "name": "recordStore",
                    "lua_type": "DataStore",
                    "desc": "The DataStore used to store `DataStoreRecord` objects."
                },
                {
                    "name": "shardStore",
                    "lua_type": "DataStore",
                    "desc": "The DataStore used to store the actual data shards for large files."
                },
                {
                    "name": "txStore",
                    "lua_type": "DataStore",
                    "desc": "The DataStore used to store transaction status markers (`txId` keys)."
                },
                {
                    "name": "lockHashMap",
                    "lua_type": "MemoryStoreHashMap",
                    "desc": "The MemoryStore HashMap used for managing distributed locks."
                }
            ],
            "source": {
                "line": 127,
                "path": "src/Types.luau"
            }
        },
        {
            "name": "RetryHandle<T>",
            "desc": "A handle returned by retry utility functions like `hashMapRetry`.\nIt bundles the core Promise with a way to cancel the retry operation.\n\nWhen the `cancel` function is called, instead of cancelling the Promise itself,\nthe retry mechanism is stopped, and the Promise is rejected with a cancellation error\nwhen the next retry attempt is made.",
            "fields": [
                {
                    "name": "promise",
                    "lua_type": "T",
                    "desc": "The Promise representing the asynchronous operation being retried. This promise resolves or rejects based on the outcome of the operation after retries."
                },
                {
                    "name": "cancel",
                    "lua_type": "() -> ()",
                    "desc": "A function that can be called to signal cancellation. If called, the retry mechanism will stop further attempts and reject the `promise`."
                }
            ],
            "source": {
                "line": 169,
                "path": "src/Types.luau"
            }
        }
    ],
    "name": "Types",
    "desc": "Common types shared among different modules.",
    "private": true,
    "source": {
        "line": 7,
        "path": "src/Types.luau"
    }
}