Skip to main content

Cache

Cache class for storing data in a cache instance.

Based off node-cache.

Install with wally by adding the following to your wally.toml:

Cache = "dig1t/cache@1.0.10"

Types​

CacheOptions​

</>
interface CacheOptions {
defaultTTL?: number--

The default time-to-live for a cache entry. Defaults to 6000.

checkInterval?: number--

The interval in seconds to check for expired cache entries. Defaults to 600.

maxKeys?: number--

The maximum amount of keys to store in the cache. 0 for unlimited. Defaults to 0.

}

CacheEntry​

</>
interface CacheEntry {
key: Key--

The key of the cache entry.

value: any--

The value of the cache entry.

expires: number--

The unix timestamp of when the cache entry expires.

}

Functions​

new​

</>
Cache.new(options?: {defaultTTL: number?}) → Cache

Creates a new Cache instance.

Set​

</>
Cache:Set(
key: string,--

The key to set.

value: any,--

The value to set.

ttl: number?--

The time-to-live for the cache entry. Defaults to the defaultTTL option. 0 for unlimited.

) → boolean--

Whether or not the value was set.

Store a key:

Sets a key value pair. It is possible to define a ttl (in seconds). Returns true on success.

local obj = { my = "Special", variable = 42 }

local success = myCache:Set( "myKey", obj, 10000 )
-- true

Note: If the key expires based on it's ttl it will be deleted entirely from the internal data object.

SetMultiple​

</>
Cache:SetMultiple(
cacheObjects: {CacheObject}--

The key to set.

) → boolean--

Whether or not the value was set.

Store multiple keys:

Sets multiple key value pairs. It is possible to define a ttl (in seconds). Returns true on success.

local obj = { my = "Special", variable = 42 }
local obj2 = { my = "other special", variable = 1337 }

local success = myCache:SetMultiple({
	{ key = "myKey", value = obj, ttl = 10000 },
	{ key = "myKey2", value = obj2 }
})
-- true

Get​

</>
Cache:Get(
key: Key--

The key to retrieve.

) → CacheEntry?--

The value of the key.

Retrieve a key:

Gets a saved value from the cache. Returns nil if not found or expired. If the value was found it returns the value.

local value = myCache:Get("myKey")

Take​

</>
Cache:Take(
key: Key--

The key to retrieve.

) → CacheEntry?--

The value of the key.

Take a key:

Get the cached value and remove the key from the cache. Equivalent to calling get(key) + delete(key). Useful for implementing single use mechanism, where once a value is read it will become obsolete. 

myCache:Set("myKey", "myValue", 10000)
myCache:Has("myKey") -- true
local value = myCache:Take("myKey") -- "myValue"
myCache:Has("myKey") -- false

GetMultiple​

</>
Cache:GetMultiple(
keys: {Key}--

The keys to retrieve.

) → {[Key]: any}--

The values of the keys.

Retrieve multiple keys:

Gets multiple saved values from the cache. Returns an empty table {} if not found or expired.

If the values were found it returns a table with the key value pair(s).

local values = myCache:GetMultiple({ "myKey", "myKey2" })

Delete​

</>
Cache:Delete(
key: Key--

The key to delete.

) → number--

The number of deleted entries.

Deletes a key. Returns the number of deleted entries. A delete will not fail if the key is not existing.

local deleted: number = myCache:Delete("myKey")

MultipleDelete​

</>
Cache:MultipleDelete(
keys: {Key}--

The keys to delete.

) → number--

The number of deleted entries.

Deletes multiple keys. Returns the number of deleted entries. This will not fail if a key is not existing.

local deleted: number = myCache:MultipleDelete({ "myKey", "myKey2" })

TTL​

</>
Cache:TTL(
key: string,--

The key to update.

ttl: number--

The time-to-live for the cache entry.

) → boolean--

Whether or not the ttl was updated.

Updates the ttl of a key. Returns true on success.

local success = myCache:TTL("myKey", 10000)

GetTTL​

</>
Cache:GetTTL(
key: string--

The key to retrieve.

) → number?--

The time-to-live for the cache entry.

Returns the ttl of a key. Returns nil if not found or expired.

local ttl = myCache:GetTTL("myKey")

Keys​

</>
Cache:Keys() → {Key}--

The keys in the cache.

Returns all keys in the cache.

local keys = myCache:Keys()

Has​

</>
Cache:Has(
key: string--

The key to check.

) → boolean--

Whether or not the key exists.

Returns a boolean indicating whether an element with the specified key exists or not.

myCache:Has("myKey") -- true

Clear​

</>
Cache:Clear() → ()

Clears the cache.

Destroy​

Cleanup
</>
Cache:Destroy() → ()

Deletes all keys and values from the cache.

Used for cleanup.

myCache:Destroy()
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new Cache instance.",
            "params": [
                {
                    "name": "options?",
                    "desc": "",
                    "lua_type": "{ defaultTTL: number? }"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Cache\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 79,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Set",
            "desc": "### Store a key:\n\nSets a `key` `value` pair. It is possible to define a ttl (in seconds). Returns `true` on success.\n\n```lua\nlocal obj = { my = \"Special\", variable = 42 }\n\nlocal success = myCache:Set( \"myKey\", obj, 10000 )\n-- true\n```\n> Note: If the key expires based on it's `ttl` it will be deleted entirely from the internal data object.",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to set.",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "The value to set.",
                    "lua_type": "any"
                },
                {
                    "name": "ttl",
                    "desc": "The time-to-live for the cache entry. Defaults to the defaultTTL option. 0 for unlimited.",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "Whether or not the value was set.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 131,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "SetMultiple",
            "desc": "### Store multiple keys:\n\nSets multiple `key` `value` pairs. It is possible to define a `ttl` (in seconds). Returns `true` on success.\n\n```lua\nlocal obj = { my = \"Special\", variable = 42 }\nlocal obj2 = { my = \"other special\", variable = 1337 }\n\nlocal success = myCache:SetMultiple({\n\t{ key = \"myKey\", value = obj, ttl = 10000 },\n\t{ key = \"myKey2\", value = obj2 }\n})\n-- true\n```",
            "params": [
                {
                    "name": "cacheObjects",
                    "desc": "The key to set.",
                    "lua_type": "{ CacheObject }"
                }
            ],
            "returns": [
                {
                    "desc": "Whether or not the value was set.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 170,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Get",
            "desc": "### Retrieve a key:\n\nGets a saved `value` from the cache. Returns `nil` if not found or expired. If the `value` was found it returns the `value`.\n\n```lua\nlocal value = myCache:Get(\"myKey\")\n```",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to retrieve.",
                    "lua_type": "Key"
                }
            ],
            "returns": [
                {
                    "desc": "The value of the key.",
                    "lua_type": "CacheEntry?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 197,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Take",
            "desc": "### Take a key:\n\nGet the cached `value` and remove the `key` from the cache.\nEquivalent to calling `get(key)` + `delete(key)`.\nUseful for implementing `single use` mechanism, where once a value is read it will become obsolete.\n\n```lua\nmyCache:Set(\"myKey\", \"myValue\", 10000)\nmyCache:Has(\"myKey\") -- true\nlocal value = myCache:Take(\"myKey\") -- \"myValue\"\nmyCache:Has(\"myKey\") -- false\n```",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to retrieve.",
                    "lua_type": "Key"
                }
            ],
            "returns": [
                {
                    "desc": "The value of the key.",
                    "lua_type": "CacheEntry?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 228,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "GetMultiple",
            "desc": "### Retrieve multiple keys:\n\nGets multiple saved values from the cache. Returns an empty table `{}` if not found or expired.\n\nIf the values were found it returns a table with the `key` `value` pair(s).\n\n```lua\nlocal values = myCache:GetMultiple({ \"myKey\", \"myKey2\" })\n```",
            "params": [
                {
                    "name": "keys",
                    "desc": "The keys to retrieve.",
                    "lua_type": "{ Key }"
                }
            ],
            "returns": [
                {
                    "desc": "The values of the keys.",
                    "lua_type": "{ [Key]: any }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 258,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Delete",
            "desc": "Deletes a key. Returns the number of deleted entries. A delete will not fail if the key is not existing.\n\n```lua\nlocal deleted: number = myCache:Delete(\"myKey\")\n```",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to delete.",
                    "lua_type": "Key"
                }
            ],
            "returns": [
                {
                    "desc": "The number of deleted entries.",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 280,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "MultipleDelete",
            "desc": "Deletes multiple keys. Returns the number of deleted entries. This will not fail if a key is not existing.\n\n```lua\nlocal deleted: number = myCache:MultipleDelete({ \"myKey\", \"myKey2\" })\n```",
            "params": [
                {
                    "name": "keys",
                    "desc": "The keys to delete.",
                    "lua_type": "{ Key }"
                }
            ],
            "returns": [
                {
                    "desc": "The number of deleted entries.",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 304,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "TTL",
            "desc": "Updates the `ttl` of a key. Returns `true` on success.\n\n```lua\nlocal success = myCache:TTL(\"myKey\", 10000)\n```",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to update.",
                    "lua_type": "string"
                },
                {
                    "name": "ttl",
                    "desc": "The time-to-live for the cache entry.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "Whether or not the ttl was updated.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 327,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "GetTTL",
            "desc": "Returns the `ttl` of a key. Returns `nil` if not found or expired.\n\n```lua\nlocal ttl = myCache:GetTTL(\"myKey\")\n```",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to retrieve.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The time-to-live for the cache entry.",
                    "lua_type": "number?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 354,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Keys",
            "desc": "Returns all keys in the cache.\n\n```lua\nlocal keys = myCache:Keys()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "The keys in the cache.",
                    "lua_type": "{ Key }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 377,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Has",
            "desc": "Returns a boolean indicating whether an element with the specified key exists or not.\n\n```lua\nmyCache:Has(\"myKey\") -- true\n```",
            "params": [
                {
                    "name": "key",
                    "desc": "The key to check.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "Whether or not the key exists.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 399,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Clear",
            "desc": "Clears the cache.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 406,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Deletes all keys and values from the cache.\n\nUsed for cleanup.\n\n```lua\nmyCache:Destroy()\n```",
            "params": [],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Cleanup"
            ],
            "source": {
                "line": 423,
                "path": "src/Cache/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "CacheOptions",
            "desc": "",
            "fields": [
                {
                    "name": "defaultTTL?",
                    "lua_type": "number",
                    "desc": "The default time-to-live for a cache entry. Defaults to 6000."
                },
                {
                    "name": "checkInterval?",
                    "lua_type": "number",
                    "desc": "The interval in seconds to check for expired cache entries. Defaults to 600."
                },
                {
                    "name": "maxKeys?",
                    "lua_type": "number",
                    "desc": "The maximum amount of keys to store in the cache. 0 for unlimited. Defaults to 0."
                }
            ],
            "source": {
                "line": 34,
                "path": "src/Cache/init.luau"
            }
        },
        {
            "name": "CacheEntry",
            "desc": "",
            "fields": [
                {
                    "name": "key",
                    "lua_type": "Key",
                    "desc": "The key of the cache entry."
                },
                {
                    "name": "value",
                    "lua_type": "any",
                    "desc": "The value of the cache entry."
                },
                {
                    "name": "expires",
                    "lua_type": "number",
                    "desc": "The unix timestamp of when the cache entry expires."
                }
            ],
            "source": {
                "line": 62,
                "path": "src/Cache/init.luau"
            }
        }
    ],
    "name": "Cache",
    "desc": "Cache class for storing data in a cache instance.\n\nBased off [node-cache](https://npmjs.com/package/node-cache).\n\nInstall with wally by adding the following to your `wally.toml`:\n```toml\nCache = \"dig1t/cache@1.0.10\"\n```",
    "source": {
        "line": 16,
        "path": "src/Cache/init.luau"
    }
}