{"id":"neohertz/neocache","name":"neocache","scope":"neohertz","platform":"roblox","description":"A very fast caching module for roblox.","version":"0.1.1","latest":"0.1.1","versions":["0.0.1","0.1.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"e9728453f851db64e1e5f3a7ea3d2166f29ec555d0f461bcce21dccbbab64926","likes":0,"downloads":0,"install":"forest install neohertz/neocache","url":"https://forest.dev/p/roblox/neohertz/neocache","files":"https://api.forest.dev/ai/package/roblox/neohertz/neocache/files","readme":"# Neocache\n\nA very fast caching module for instances and beyond.\n\n> [!WARNING]\n> Neocache is pre v1.0 software. You may encounter bugs.\n\n## Example Usage\n\n```lua\nlocal audioCache = neocache.new(function()\n\tlocal sfx = Instance.new(\"Sound\")\n\tsfx.Parent = SoundService\n\treturn sfx\nend, 100, 10)\n\nfunction playSoundEffect(id: string)\n\tlocal sound = audioCache:next()\n\tsound.SoundID = id\n\tsound:Play()\nend\n```\n\n## Behavior\n\nNeocache acts like a ring buffer. Whenever `:next()` or `reserveNext()` is invoked, it will increment the pointer to find the next available instance. If it doesn't exist, it will just create it.\n\nNeocache also has support for locking, allowing you to \"check out\" a result from the cache, modify it, then return it once done. While an entry is locked, it will be skipped in all future `next() / reserveNext()` calls.\n\n## Install\n\n### Wally\n\nGet the latest version from [Wally](https://wally.run/package/neohertz/neocache).\n\n```toml\n# wally.toml\nneocache = \"neohertz/neocache@x.x.x\"\n```\n\n### Typescript (Roblox-TS)\n\nInstall neocache via npm. (coming soon)\n\n```sh\nnpm i @rbxts/neocache\n```\n\n# Creating a Cache\n\n`neocache.new(factory: () -> T, size: number, buffer: number?)`\n\n- Factory\n    - Invoked whenever the cache needs to create a new instance. Returns a value.\n- Size\n    - How big the cache should be.\n- Buffer\n    - Prewarm the cache by populating the first X entries.\n\n```lua\nlocal audioCache = neocache.new(function()\n\tlocal sfx = Instance.new(\"Sound\")\n\tsfx.Parent = SoundService\n\treturn sfx\nend, 100, 10)\n```\n\n# API\n\n### `cache:next(fast: boolean?)`\n\nGet a reference to the next **available** item in the cache and increment the internal pointer.\n\nIf `fast` is true, the cache will grab the next item in the queue. If this item is locked, `:next(true)` will return nil.\n\n```lua\nlocal sound = audioCache:next()\n\nif sound then\n\tsound:Play()\nend\n```\n\n### `cache:reserveNext(fast: boolean?)`\n\nSame thing as `cache:next()`, but this instance is locked until the returned unlock method is invoked.\n\nWhile this item is locked or _\"checked out\"_, it will be skipped in any future `next()` or `reserveNext()` calls.\n\nIf `fast` is true, the cache will grab the next item in the queue. If this item is locked, `:reserveNext(true)` will return nil.\n\n> This is useful if you want to prevent overlapping operations on a specific item in the cache.\n\n```lua\nlocal sound, release = audioCache:reserveNext()\n\nif sound then\n\tsound:Play()\n\tsound.Ended:Once(function()\n\t\trelease()\n\tend)\nend\n```\n\n### `cache:unique()`\n\nGrab a unique, non cached instance from the factory.\n\n```lua\nlocal uniqueSoundEffect = audioCache:unique()\n```\n\n### `cache:peek()`\n\nView the next item in the cache.\n\n```lua\nlocal ref = audioCache:peek()\n```\n\n### `cache:resize(newSize: number, newBuffer: number?)`\n\nResize the cache. This operation is destructive on shrinking.\n\nIf the cache grows to a size below the buffer, those items will be immediately generated.\n\n```lua\n-- Current Size: 100 | Current Buffer: 10\n-- 5 deletions guaranteed, 90 possible.\ncache:resize(5)\n\n-- Current Size: 5 | Current Buffer: 10\n-- 5 factory invocations guaranteed.\ncache:resize(10)\n```\n\n### `cache:clear()`\n\nEntirely wipe the cache. Invokes the cleanup method. Neocache will automatically regenerate the objects upon subsequent `next()` or `reserveNext()` calls.\n\n```lua\naudioCache:clear()\naudioCache:next() -- invokes factory.\n```\n\n### `cache:useCleanupMethod<T>(fn: (obj: T) -> ())`\n\nOverride the default cleanup method with a custom one. This method will be invoked by both `cache:clear()` and `cache:destroy()`.\n\nUseful when using non-instance items within the cache.\n\n```lua\ncache:useCleanupMethod(function(class: MyClass)\n\tclass:Cleanup()\nend)\n```\n\n### `cache:destroy()`\n\nDestroy the cache and any instances within entirely.\nSubsequent calls to this cache will error.\n\n```lua\ncahce:destroy()\ncache:next() -- ❌ error!\n```\n","readmeTruncated":false}