@arkstack/cache 0.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @arkstack/cache
+
+[![@arkstack/cache](https://img.shields.io/npm/dt/@arkstack/cache?style=flat-square&label=@arkstack/cache&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/cache)](https://www.npmjs.com/package/@arkstack/cache)
+
+Cache module for Arkstack, providing a unified, driver based caching layer for the framework.
+
+## Stores
+
+`@arkstack/cache` ships with four stores out of the box:
+
+| Driver     | Backing store                | Notes                                    |
+| ---------- | ---------------------------- | ---------------------------------------- |
+| `memory`   | in-process `Map`             | default; great for dev and tests         |
+| `file`     | JSON files on disk           | no external service required             |
+| `redis`    | Redis (via `ioredis`)        | distributed; atomic counters             |
+| `database` | a table via `@arkstack/database` | reuses your database connection      |
+
+## Configuration
+
+```ts
+// src/config/cache.ts
+import { Arkstack } from '@arkstack/contract'
+import type { CacheConfig } from '@arkstack/cache'
+import path from 'node:path'
+
+export default (): CacheConfig => ({
+  default: env('CACHE_STORE', 'memory'),
+  prefix: env('CACHE_PREFIX', 'arkstack_cache_'),
+  stores: {
+    memory: { driver: 'memory' },
+    file: { driver: 'file', path: path.join(Arkstack.rootDir(), './storage/framework/cache') },
+    redis: { driver: 'redis', host: env('REDIS_HOST', '127.0.0.1'), port: env('REDIS_PORT', 6379) },
+    database: { driver: 'database', table: 'cache' },
+  },
+})
+```
+
+## Usage
+
+```ts
+import { Cache } from '@arkstack/cache'
+
+// default store
+await Cache.put('user:1', user, 60)        // ttl in seconds
+await Cache.get('user:1')
+await Cache.forget('user:1')
+
+// remember: read-through caching
+const stats = await Cache.remember('stats', 300, () => computeStats())
+
+// counters
+await Cache.increment('hits')
+await Cache.decrement('hits', 2)
+
+// a specific store
+await Cache.store('redis').forever('flag', true)
+```
+
+The ttl accepts a number of seconds, a `Date`, or `null` (forever).
+
+## Custom drivers
+
+```ts
+import { Cache, Store } from '@arkstack/cache'
+
+class TagStore extends Store { /* ... implement the Store contract ... */ }
+
+Cache.extend('tags', (config) => new TagStore(config))
+```
+
+Then reference `{ driver: 'tags' }` in a store config.