@arkstack/cache 0.13.0

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.

package/dist/CacheManager-DfAiI5Ft.js

@@ -0,0 +1,708 @@
+import { mkdir, readFile, readdir, rm, unlink, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { config } from "@arkstack/common";
+//#region src/Contracts/Store.ts
+/**
+* The low level contract every cache store driver must satisfy.
+*
+* Stores are intentionally thin: they only deal in raw key/value persistence
+* and expiration. The higher level convenience API (`remember`, `add`, `pull`,
+* default value resolution, etc.) lives in {@link Repository}, which wraps a
+* store. This keeps drivers simple and behaviour consistent across backends.
+*/
+var Store = class {};
+//#endregion
+//#region src/drivers/DatabaseStore.ts
+/**
+* A cache store that persists entries in a relational table via
+* `@arkstack/database`.
+*
+* The table is expected to have `key` (string, primary), `value` (text), and
+* `expiration` (nullable integer epoch seconds) columns. `@arkstack/database`
+* is an optional peer dependency and is imported lazily.
+*/
+var DatabaseStore = class extends Store {
+	databaseConfig;
+	prefix;
+	db;
+	constructor(databaseConfig, prefix = "") {
+		super();
+		this.databaseConfig = databaseConfig;
+		this.prefix = prefix;
+	}
+	getPrefix() {
+		return this.prefix;
+	}
+	prefixed(key) {
+		return this.prefix + key;
+	}
+	get table() {
+		return this.databaseConfig.table;
+	}
+	async database() {
+		if (this.db) return this.db;
+		try {
+			const { DB } = await import("@arkstack/database");
+			this.db = DB;
+		} catch {
+			throw new Error("The database cache store requires the \"@arkstack/database\" package.");
+		}
+		return this.db;
+	}
+	async get(key) {
+		const db = await this.database();
+		const row = await db.table(this.table).where({ key: this.prefixed(key) }).first();
+		if (!row) return null;
+		if (row.expiration !== null && row.expiration <= Math.floor(Date.now() / 1e3)) {
+			await db.table(this.table).where({ key: this.prefixed(key) }).delete();
+			return null;
+		}
+		try {
+			return JSON.parse(row.value);
+		} catch {
+			return row.value;
+		}
+	}
+	async put(key, value, seconds = null) {
+		const db = await this.database();
+		const expiration = seconds === null ? null : Math.floor(Date.now() / 1e3) + seconds;
+		await db.table(this.table).updateOrInsert({ key: this.prefixed(key) }, {
+			value: JSON.stringify(value),
+			expiration
+		});
+		return true;
+	}
+	async forever(key, value) {
+		return this.put(key, value, null);
+	}
+	async increment(key, value = 1) {
+		const current = await this.get(key);
+		const base = current === null ? 0 : current;
+		if (typeof base !== "number" || Number.isNaN(base)) return false;
+		const next = base + value;
+		const db = await this.database();
+		const existing = await db.table(this.table).where({ key: this.prefixed(key) }).first();
+		await db.table(this.table).updateOrInsert({ key: this.prefixed(key) }, {
+			value: JSON.stringify(next),
+			expiration: existing?.expiration ?? null
+		});
+		return next;
+	}
+	async decrement(key, value = 1) {
+		return this.increment(key, -value);
+	}
+	async forget(key) {
+		await (await this.database()).table(this.table).where({ key: this.prefixed(key) }).delete();
+		return true;
+	}
+	async flush() {
+		await (await this.database()).table(this.table).delete();
+		return true;
+	}
+};
+//#endregion
+//#region src/drivers/FileStore.ts
+/**
+* A cache store that persists each entry as a JSON file on disk.
+*
+* Keys are hashed to produce safe, fixed length file names. Expired files are
+* removed lazily on read and ignored otherwise.
+*/
+var FileStore = class extends Store {
+	directory;
+	prefix;
+	constructor(directory, prefix = "") {
+		super();
+		this.directory = directory;
+		this.prefix = prefix;
+	}
+	getPrefix() {
+		return this.prefix;
+	}
+	pathFor(key) {
+		const hash = createHash("sha1").update(this.prefix + key).digest("hex");
+		return path.join(this.directory, `${hash}.json`);
+	}
+	async ensureDirectory() {
+		if (!existsSync(this.directory)) await mkdir(this.directory, { recursive: true });
+	}
+	async get(key) {
+		const file = this.pathFor(key);
+		if (!existsSync(file)) return null;
+		try {
+			const payload = JSON.parse(await readFile(file, "utf8"));
+			if (payload.expiresAt !== null && payload.expiresAt <= Date.now()) {
+				await unlink(file).catch(() => void 0);
+				return null;
+			}
+			return payload.value;
+		} catch {
+			return null;
+		}
+	}
+	async put(key, value, seconds = null) {
+		await this.ensureDirectory();
+		const payload = {
+			value,
+			expiresAt: seconds === null ? null : Date.now() + seconds * 1e3
+		};
+		await writeFile(this.pathFor(key), JSON.stringify(payload), "utf8");
+		return true;
+	}
+	async forever(key, value) {
+		return this.put(key, value, null);
+	}
+	async increment(key, value = 1) {
+		const current = await this.get(key);
+		const base = current === null ? 0 : current;
+		if (typeof base !== "number" || Number.isNaN(base)) return false;
+		const next = base + value;
+		const file = this.pathFor(key);
+		let expiresAt = null;
+		if (existsSync(file)) try {
+			expiresAt = JSON.parse(await readFile(file, "utf8")).expiresAt;
+		} catch {
+			expiresAt = null;
+		}
+		await this.ensureDirectory();
+		await writeFile(file, JSON.stringify({
+			value: next,
+			expiresAt
+		}), "utf8");
+		return next;
+	}
+	async decrement(key, value = 1) {
+		return this.increment(key, -value);
+	}
+	async forget(key) {
+		const file = this.pathFor(key);
+		if (!existsSync(file)) return false;
+		await unlink(file).catch(() => void 0);
+		return true;
+	}
+	async flush() {
+		if (!existsSync(this.directory)) return true;
+		const files = await readdir(this.directory);
+		await Promise.all(files.filter((name) => name.endsWith(".json")).map((name) => rm(path.join(this.directory, name), { force: true })));
+		return true;
+	}
+};
+//#endregion
+//#region src/drivers/MemoryStore.ts
+/**
+* An in-process cache store backed by a `Map`.
+*
+* The backing map is shared across every `MemoryStore` instance that uses the
+* same prefix, so resolving the store twice within a process sees the same data
+* (matching how the other backends behave). Great for development and tests; it
+* is not shared across processes.
+*/
+var MemoryStore = class MemoryStore extends Store {
+	prefix;
+	static stores = /* @__PURE__ */ new Map();
+	entries;
+	constructor(prefix = "") {
+		super();
+		this.prefix = prefix;
+		if (!MemoryStore.stores.has(prefix)) MemoryStore.stores.set(prefix, /* @__PURE__ */ new Map());
+		this.entries = MemoryStore.stores.get(prefix);
+	}
+	getPrefix() {
+		return this.prefix;
+	}
+	async get(key) {
+		const entry = this.entries.get(key);
+		if (!entry) return null;
+		if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+			this.entries.delete(key);
+			return null;
+		}
+		return entry.value;
+	}
+	async put(key, value, seconds = null) {
+		this.entries.set(key, {
+			value,
+			expiresAt: seconds === null ? null : Date.now() + seconds * 1e3
+		});
+		return true;
+	}
+	async forever(key, value) {
+		return this.put(key, value, null);
+	}
+	async increment(key, value = 1) {
+		const current = await this.get(key);
+		const base = current === null ? 0 : current;
+		if (typeof base !== "number" || Number.isNaN(base)) return false;
+		const next = base + value;
+		const entry = this.entries.get(key);
+		this.entries.set(key, {
+			value: next,
+			expiresAt: entry?.expiresAt ?? null
+		});
+		return next;
+	}
+	async decrement(key, value = 1) {
+		return this.increment(key, -value);
+	}
+	async forget(key) {
+		return this.entries.delete(key);
+	}
+	async flush() {
+		this.entries.clear();
+		return true;
+	}
+};
+//#endregion
+//#region src/drivers/RedisStore.ts
+/**
+* A Redis backed cache store using an ioredis compatible client.
+*
+* Values are JSON serialized. Numeric helpers use native `INCRBY`/`DECRBY` so
+* counters stay atomic across processes. `ioredis` is an optional peer
+* dependency; it is imported lazily so applications that never use the redis
+* store don't need it installed.
+*/
+var RedisStore = class extends Store {
+	redisConfig;
+	prefix;
+	client;
+	constructor(redisConfig, prefix = "") {
+		super();
+		this.redisConfig = redisConfig;
+		this.prefix = prefix;
+	}
+	getPrefix() {
+		return [this.prefix, this.redisConfig.prefix].filter(Boolean).join("");
+	}
+	prefixed(key) {
+		return this.getPrefix() + key;
+	}
+	async connection() {
+		if (this.client) return this.client;
+		let Redis;
+		try {
+			Redis = (await import("ioredis")).default;
+		} catch {
+			throw new Error("The redis cache store requires the \"ioredis\" package. Install it with your package manager.");
+		}
+		this.client = this.redisConfig.url ? new Redis(this.redisConfig.url) : new Redis({
+			host: this.redisConfig.host ?? "127.0.0.1",
+			port: this.redisConfig.port ?? 6379,
+			password: this.redisConfig.password,
+			db: this.redisConfig.db ?? 0
+		});
+		return this.client;
+	}
+	/**
+	* Disconnect the underlying client. Useful for tests and graceful shutdown.
+	*/
+	async disconnect() {
+		await this.client?.quit();
+		this.client = void 0;
+	}
+	async get(key) {
+		const raw = await (await this.connection()).get(this.prefixed(key));
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw);
+		} catch {
+			return raw;
+		}
+	}
+	async put(key, value, seconds = null) {
+		const client = await this.connection();
+		const serialized = JSON.stringify(value);
+		if (seconds === null) await client.set(this.prefixed(key), serialized);
+		else await client.set(this.prefixed(key), serialized, "EX", seconds);
+		return true;
+	}
+	async forever(key, value) {
+		return this.put(key, value, null);
+	}
+	async increment(key, value = 1) {
+		return (await this.connection()).incrby(this.prefixed(key), value);
+	}
+	async decrement(key, value = 1) {
+		return (await this.connection()).decrby(this.prefixed(key), value);
+	}
+	async forget(key) {
+		return await (await this.connection()).del(this.prefixed(key)) > 0;
+	}
+	async flush() {
+		const client = await this.connection();
+		const pattern = `${this.getPrefix()}*`;
+		let cursor = "0";
+		do {
+			const [next, keys] = await client.scan(cursor, "MATCH", pattern, "COUNT", 100);
+			cursor = next;
+			if (keys.length > 0) await client.del(...keys);
+		} while (cursor !== "0");
+		return true;
+	}
+};
+//#endregion
+//#region src/Repository.ts
+/**
+* Resolve a possibly callable default/value into a concrete value.
+*/
+const resolve = async (value) => {
+	return typeof value === "function" ? await value() : value;
+};
+/**
+* Normalize a {@link CacheTtl} into a whole number of seconds, or `null` for a
+* forever entry. A non positive duration is treated as already expired and
+* returns `0`, signalling the caller to skip writing.
+*/
+const ttlToSeconds = (ttl) => {
+	if (ttl === null || ttl === void 0) return null;
+	if (ttl instanceof Date) return Math.max(0, Math.round((ttl.getTime() - Date.now()) / 1e3));
+	return Math.max(0, Math.round(ttl));
+};
+/**
+* A high level wrapper around a {@link Store} that provides the developer facing
+* cache API. A repository is what `Cache.store()` returns.
+*/
+var Repository = class {
+	store;
+	constructor(store) {
+		this.store = store;
+	}
+	/**
+	* Get the underlying store driver.
+	*/
+	getStore() {
+		return this.store;
+	}
+	/**
+	* Determine whether an item exists in the cache and has not expired.
+	* 
+	* @param key 
+	* @returns 
+	*/
+	async has(key) {
+		return await this.store.get(key) !== null;
+	}
+	/**
+	* Determine whether an item is missing from the cache.
+	* 
+	* @param key 
+	* @returns 
+	*/
+	async missing(key) {
+		return !await this.has(key);
+	}
+	/**
+	* Retrieve an item from the cache, falling back to `defaultValue` (which may
+	* be a callback) when the item is absent.
+	* 
+	* @param key 
+	* @returns 
+	*/
+	async get(key, defaultValue = null) {
+		const value = await this.store.get(key);
+		if (value === null || value === void 0) return resolve(defaultValue);
+		return value;
+	}
+	/**
+	* Retrieve an item and delete it from the cache in a single call.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async pull(key, defaultValue = null) {
+		const value = await this.get(key, defaultValue);
+		await this.forget(key);
+		return value;
+	}
+	/**
+	* Store an item in the cache. A `null`/omitted ttl stores the item forever;
+	* a non positive ttl is a no-op that also forgets any existing entry.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async put(key, value, ttl = null) {
+		const seconds = ttlToSeconds(ttl);
+		if (seconds !== null && seconds <= 0) {
+			await this.forget(key);
+			return false;
+		}
+		return this.store.put(key, value, seconds);
+	}
+	/**
+	* Alias for {@link put}.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async set(key, value, ttl = null) {
+		return this.put(key, value, ttl);
+	}
+	/**
+	* Store an item only if it is not already present. Returns `false` when the
+	* key already exists.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async add(key, value, ttl = null) {
+		if (await this.has(key)) return false;
+		return this.put(key, value, ttl);
+	}
+	/**
+	* Store an item that never expires.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async forever(key, value) {
+		return this.store.forever(key, value);
+	}
+	/**
+	* Increment a stored numeric value.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async increment(key, value = 1) {
+		return this.store.increment(key, value);
+	}
+	/**
+	* Decrement a stored numeric value.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async decrement(key, value = 1) {
+		return this.store.decrement(key, value);
+	}
+	/**
+	* Get an item from the cache, or execute the callback, store its result for
+	* the given ttl, and return it.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async remember(key, ttl, callback) {
+		const existing = await this.store.get(key);
+		if (existing !== null && existing !== void 0) return existing;
+		const value = await callback();
+		await this.put(key, value, ttl);
+		return value;
+	}
+	/**
+	* Get an item from the cache, or execute the callback and store its result
+	* forever.
+	* 
+	* @param key 
+	* @param defaultValue 
+	* @returns 
+	*/
+	async rememberForever(key, callback) {
+		const existing = await this.store.get(key);
+		if (existing !== null && existing !== void 0) return existing;
+		const value = await callback();
+		await this.forever(key, value);
+		return value;
+	}
+	/**
+	* Alias for {@link rememberForever}.
+	* 
+	* @param key 
+	* @param callback 
+	* @returns 
+	*/
+	async sear(key, callback) {
+		return this.rememberForever(key, callback);
+	}
+	/**
+	* Remove an item from the cache.
+	* 
+	* @param key 
+	* @param callback 
+	* @returns 
+	*/
+	async forget(key) {
+		return this.store.forget(key);
+	}
+	/**
+	* Alias for {@link forget}.
+	* 
+	* @param key 
+	* @param callback 
+	* @returns 
+	*/
+	async delete(key) {
+		return this.forget(key);
+	}
+	/**
+	* Remove every item from the cache store.
+	* 
+	* @param key 
+	* @param callback 
+	* @returns 
+	*/
+	async flush() {
+		return this.store.flush();
+	}
+	/**
+	* Alias for {@link flush}.
+	* 
+	* @param key 
+	* @param callback 
+	* @returns 
+	*/
+	async clear() {
+		return this.flush();
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Read a value from the `cache` configuration namespace with a fallback.
+*
+* Mirrors the framework `config()` helper but is scoped to the cache config and
+* never throws when the config file is missing, returning the default instead.
+*
+* @param key           Dot path within the cache config.
+* @param defaultValue  Value returned when the key is not set.
+*/
+const configure = (key, defaultValue) => {
+	try {
+		return config(`cache.${key}`, defaultValue);
+	} catch {
+		return defaultValue;
+	}
+};
+//#endregion
+//#region src/CacheManager.ts
+/**
+* The cache manager and primary entry point of `@arkstack/cache`.
+*
+* Resolves named cache stores from configuration, memoizes the resulting
+* repositories, and exposes static convenience methods that proxy the default
+* store, e.g.:
+*
+* ```ts
+* await Cache.put('user:1', user, 60)
+* await Cache.store('redis').remember('stats', 300, computeStats)
+* ```
+*/
+var Cache = class {
+	static repositories = {};
+	static customDrivers = {};
+	/**
+	* Resolve a cache repository for the given store name (or the default store
+	* when omitted). Repositories are memoized per name.
+	*/
+	static store(name) {
+		const store = name ?? configure("default", "memory");
+		if (!this.repositories[store]) this.repositories[store] = this.resolve(store);
+		return this.repositories[store];
+	}
+	/**
+	* Alias for {@link store}.
+	*/
+	static driver(name) {
+		return this.store(name);
+	}
+	/**
+	* Register a custom store driver factory, used when a store's `driver` does
+	* not match a built in one.
+	*/
+	static extend(driver, factory) {
+		this.customDrivers[driver] = factory;
+		return this;
+	}
+	/**
+	* Clear the memoized repositories. Mainly useful between tests or after the
+	* configuration changes at runtime.
+	*/
+	static clearResolved() {
+		this.repositories = {};
+	}
+	/**
+	* Build a repository for a configured store from scratch.
+	*/
+	static resolve(name) {
+		const config = configure(`stores.${name}`, void 0);
+		if (!config) throw new Error(`Cache store "${name}" is not configured.`);
+		return new Repository(this.createStore(config));
+	}
+	/**
+	* Instantiate the concrete {@link Store} for a store config.
+	*/
+	static createStore(config) {
+		const prefix = configure("prefix", "");
+		switch (config.driver) {
+			case "memory":
+			case "array": return new MemoryStore(prefix);
+			case "file": return new FileStore(config.path, prefix);
+			case "redis": return new RedisStore(config, prefix);
+			case "database": return new DatabaseStore(config, prefix);
+			default:
+				if (this.customDrivers[config.driver]) return this.customDrivers[config.driver](config);
+				throw new Error(`Unsupported cache driver: ${config.driver}`);
+		}
+	}
+	static has(key) {
+		return this.store().has(key);
+	}
+	static missing(key) {
+		return this.store().missing(key);
+	}
+	static get(key, defaultValue) {
+		return this.store().get(key, defaultValue);
+	}
+	static pull(key, defaultValue) {
+		return this.store().pull(key, defaultValue);
+	}
+	static put(key, value, ttl) {
+		return this.store().put(key, value, ttl);
+	}
+	static set(key, value, ttl) {
+		return this.store().set(key, value, ttl);
+	}
+	static add(key, value, ttl) {
+		return this.store().add(key, value, ttl);
+	}
+	static forever(key, value) {
+		return this.store().forever(key, value);
+	}
+	static increment(key, value) {
+		return this.store().increment(key, value);
+	}
+	static decrement(key, value) {
+		return this.store().decrement(key, value);
+	}
+	static remember(key, ttl, callback) {
+		return this.store().remember(key, ttl, callback);
+	}
+	static rememberForever(key, callback) {
+		return this.store().rememberForever(key, callback);
+	}
+	static forget(key) {
+		return this.store().forget(key);
+	}
+	static delete(key) {
+		return this.store().delete(key);
+	}
+	static flush() {
+		return this.store().flush();
+	}
+	static clear() {
+		return this.store().clear();
+	}
+};
+//#endregion
+export { RedisStore as a, DatabaseStore as c, ttlToSeconds as i, Store as l, configure as n, MemoryStore as o, Repository as r, FileStore as s, Cache as t };

package/dist/commands/CacheClearCommand.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/CacheClearCommand.d.ts
+/**
+ * Flush all entries from a cache store.
+ */
+declare class CacheClearCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { CacheClearCommand };

package/dist/commands/CacheClearCommand.js

@@ -0,0 +1,19 @@
+import { t as Cache } from "../CacheManager-DfAiI5Ft.js";
+import { Command } from "@h3ravel/musket";
+//#region src/commands/CacheClearCommand.ts
+/**
+* Flush all entries from a cache store.
+*/
+var CacheClearCommand = class extends Command {
+	signature = `cache:clear
+        {--store= : The cache store to flush. Defaults to the configured default store.}
+    `;
+	description = "Flush the application cache.";
+	async handle() {
+		const store = this.option("store");
+		await Cache.store(store).flush();
+		this.info(`Cache store [${store ?? "default"}] cleared successfully.`);
+	}
+};
+//#endregion
+export { CacheClearCommand };

package/dist/index.d.ts

@@ -0,0 +1,525 @@
+import { DotPath, DotPathValue } from "@arkstack/common";
+
+//#region src/Contracts/Store.d.ts
+/**
+ * The low level contract every cache store driver must satisfy.
+ *
+ * Stores are intentionally thin: they only deal in raw key/value persistence
+ * and expiration. The higher level convenience API (`remember`, `add`, `pull`,
+ * default value resolution, etc.) lives in {@link Repository}, which wraps a
+ * store. This keeps drivers simple and behaviour consistent across backends.
+ */
+declare abstract class Store {
+  /**
+   * Retrieve the value for the given key, or `null` when the key is missing
+   * or has expired.
+   *
+   * @param key
+   */
+  abstract get<T = unknown>(key: string): Promise<T | null>;
+  /**
+   * Store a value for the given key.
+   *
+   * @param key       The cache key.
+   * @param value     The value to store (will be serialized by the driver).
+   * @param seconds   Lifetime in seconds, or `null` to store forever.
+   * @returns         Whether the value was stored.
+   */
+  abstract put(key: string, value: unknown, seconds?: number | null): Promise<boolean>;
+  /**
+   * Store a value that never expires.
+   *
+   * @param key
+   * @param value
+   */
+  abstract forever(key: string, value: unknown): Promise<boolean>;
+  /**
+   * Increment a numeric value, creating it (starting at 0) when absent.
+   *
+   * @returns The new value, or `false` when the existing value is not numeric.
+   *
+   * @param key
+   * @param value
+   */
+  abstract increment(key: string, value?: number): Promise<number | false>;
+  /**
+   * Decrement a numeric value, creating it (starting at 0) when absent.
+   *
+   * @returns The new value, or `false` when the existing value is not numeric.
+   *
+   * @param key
+   * @param value
+   */
+  abstract decrement(key: string, value?: number): Promise<number | false>;
+  /**
+   * Remove a single key from the store.
+   *
+   * @param key
+   * @param value
+   */
+  abstract forget(key: string): Promise<boolean>;
+  /**
+   * Remove every entry owned by this store.
+   */
+  abstract flush(): Promise<boolean>;
+  /**
+   * The key prefix applied to every entry by this store.
+   */
+  abstract getPrefix(): string;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * A value, or a function (sync or async) that resolves to a value.
+ *
+ * Used for cache defaults and the `remember` callbacks.
+ */
+type Resolvable<T> = T | (() => T | Promise<T>);
+/**
+ * Time to live for a cache entry.
+ *
+ * - `number`  number of seconds the entry should live.
+ * - `Date`    an absolute expiry time.
+ * - `null`    store forever (no expiration).
+ */
+type CacheTtl = number | Date | null;
+/**
+ * Built in cache store driver names.
+ */
+type CacheDriverName = 'memory' | 'array' | 'file' | 'redis' | 'database';
+interface FilePayload {
+  value: unknown;
+  /** Absolute expiry in epoch milliseconds, or `null` for forever. */
+  expiresAt: number | null;
+}
+interface MemoryStoreConfig {
+  driver: 'memory' | 'array';
+}
+interface FileStoreConfig {
+  driver: 'file';
+  /** Absolute path to the directory cache files are written to. */
+  path: string;
+}
+interface RedisStoreConfig {
+  driver: 'redis';
+  /** A pre built ioredis connection string, e.g. `redis://localhost:6379`. */
+  url?: string;
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  /** Optional per store key prefix applied on top of the global prefix. */
+  prefix?: string;
+}
+interface DatabaseStoreConfig {
+  driver: 'database';
+  /** The table the cache entries are stored in. */
+  table: string;
+  /** Optional named database connection. */
+  connection?: string;
+}
+/**
+ * Apps may augment this registry to register custom store driver configs.
+ */
+interface CustomCacheStoreRegistry {}
+type CacheStoreConfig = MemoryStoreConfig | FileStoreConfig | RedisStoreConfig | DatabaseStoreConfig | ({
+  driver: string;
+} & Record<string, unknown>);
+interface CacheConfig {
+  /**
+   * The default cache store used when no store is explicitly requested.
+   */
+  default: string;
+  /**
+   * A string prepended to every cache key to avoid collisions between
+   * applications sharing the same backing store.
+   */
+  prefix: string;
+  /**
+   * The configured cache stores. Each entry is keyed by the name used with
+   * `Cache.store('<name>')`.
+   */
+  stores: Record<string, CacheStoreConfig> & CustomCacheStoreRegistry;
+}
+/**
+ * Signature for a custom store factory registered via `Cache.extend`.
+ */
+type CacheStoreFactory = (config: CacheStoreConfig) => Store;
+interface MemoryEntry {
+  value: unknown;
+  /** Absolute expiry in epoch milliseconds, or `null` for forever. */
+  expiresAt: number | null;
+}
+interface CacheRow {
+  key: string;
+  value: string;
+  /** Absolute expiry in epoch seconds, or `null` for forever. */
+  expiration: number | null;
+}
+/**
+ * Structural type for the `DB` class exported by `@arkstack/database`, declared
+ * locally so the cache package does not depend on it at build time (it is an
+ * optional peer dependency).
+ */
+interface DatabaseFacade {
+  table(table: string): {
+    where(where: Record<string, unknown>): {
+      first(): Promise<CacheRow | null>;
+      delete(): Promise<unknown>;
+    };
+    updateOrInsert(attributes: Record<string, unknown>, values: Record<string, unknown>): Promise<boolean>;
+    delete(): Promise<unknown>;
+  };
+}
+/**
+ * Minimal structural type for the slice of the ioredis client we use. Declared
+ * locally so the package does not need ioredis types at build time (it is an
+ * optional peer dependency).
+ */
+interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<unknown>;
+  set(key: string, value: string, mode: 'EX', seconds: number): Promise<unknown>;
+  del(...keys: string[]): Promise<number>;
+  incrby(key: string, value: number): Promise<number>;
+  decrby(key: string, value: number): Promise<number>;
+  scan(cursor: string, match: 'MATCH', pattern: string, count: 'COUNT', n: number): Promise<[string, string[]]>;
+  quit(): Promise<unknown>;
+}
+//#endregion
+//#region src/Repository.d.ts
+/**
+ * Normalize a {@link CacheTtl} into a whole number of seconds, or `null` for a
+ * forever entry. A non positive duration is treated as already expired and
+ * returns `0`, signalling the caller to skip writing.
+ */
+declare const ttlToSeconds: (ttl: CacheTtl) => number | null;
+/**
+ * A high level wrapper around a {@link Store} that provides the developer facing
+ * cache API. A repository is what `Cache.store()` returns.
+ */
+declare class Repository {
+  protected readonly store: Store;
+  constructor(store: Store);
+  /**
+   * Get the underlying store driver.
+   */
+  getStore(): Store;
+  /**
+   * Determine whether an item exists in the cache and has not expired.
+   *
+   * @param key
+   * @returns
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Determine whether an item is missing from the cache.
+   *
+   * @param key
+   * @returns
+   */
+  missing(key: string): Promise<boolean>;
+  /**
+   * Retrieve an item from the cache, falling back to `defaultValue` (which may
+   * be a callback) when the item is absent.
+   *
+   * @param key
+   * @returns
+   */
+  get<T = unknown>(key: string, defaultValue?: Resolvable<T | null>): Promise<T | null>;
+  /**
+   * Retrieve an item and delete it from the cache in a single call.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  pull<T = unknown>(key: string, defaultValue?: Resolvable<T | null>): Promise<T | null>;
+  /**
+   * Store an item in the cache. A `null`/omitted ttl stores the item forever;
+   * a non positive ttl is a no-op that also forgets any existing entry.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  put(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+  /**
+   * Alias for {@link put}.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  set(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+  /**
+   * Store an item only if it is not already present. Returns `false` when the
+   * key already exists.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+  /**
+   * Store an item that never expires.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  forever(key: string, value: unknown): Promise<boolean>;
+  /**
+   * Increment a stored numeric value.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  increment(key: string, value?: number): Promise<number | false>;
+  /**
+   * Decrement a stored numeric value.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  decrement(key: string, value?: number): Promise<number | false>;
+  /**
+   * Get an item from the cache, or execute the callback, store its result for
+   * the given ttl, and return it.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  remember<T>(key: string, ttl: CacheTtl, callback: () => T | Promise<T>): Promise<T>;
+  /**
+   * Get an item from the cache, or execute the callback and store its result
+   * forever.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  rememberForever<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
+  /**
+   * Alias for {@link rememberForever}.
+   *
+   * @param key
+   * @param callback
+   * @returns
+   */
+  sear<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
+  /**
+   * Remove an item from the cache.
+   *
+   * @param key
+   * @param callback
+   * @returns
+   */
+  forget(key: string): Promise<boolean>;
+  /**
+   * Alias for {@link forget}.
+   *
+   * @param key
+   * @param callback
+   * @returns
+   */
+  delete(key: string): Promise<boolean>;
+  /**
+   * Remove every item from the cache store.
+   *
+   * @param key
+   * @param callback
+   * @returns
+   */
+  flush(): Promise<boolean>;
+  /**
+   * Alias for {@link flush}.
+   *
+   * @param key
+   * @param callback
+   * @returns
+   */
+  clear(): Promise<boolean>;
+}
+//#endregion
+//#region src/CacheManager.d.ts
+/**
+ * The cache manager and primary entry point of `@arkstack/cache`.
+ *
+ * Resolves named cache stores from configuration, memoizes the resulting
+ * repositories, and exposes static convenience methods that proxy the default
+ * store, e.g.:
+ *
+ * ```ts
+ * await Cache.put('user:1', user, 60)
+ * await Cache.store('redis').remember('stats', 300, computeStats)
+ * ```
+ */
+declare class Cache {
+  private static repositories;
+  private static customDrivers;
+  /**
+   * Resolve a cache repository for the given store name (or the default store
+   * when omitted). Repositories are memoized per name.
+   */
+  static store(name?: string): Repository;
+  /**
+   * Alias for {@link store}.
+   */
+  static driver(name?: string): Repository;
+  /**
+   * Register a custom store driver factory, used when a store's `driver` does
+   * not match a built in one.
+   */
+  static extend(driver: string, factory: CacheStoreFactory): typeof Cache;
+  /**
+   * Clear the memoized repositories. Mainly useful between tests or after the
+   * configuration changes at runtime.
+   */
+  static clearResolved(): void;
+  /**
+   * Build a repository for a configured store from scratch.
+   */
+  private static resolve;
+  /**
+   * Instantiate the concrete {@link Store} for a store config.
+   */
+  private static createStore;
+  static has(key: string): Promise<boolean>;
+  static missing(key: string): Promise<boolean>;
+  static get<T = unknown>(key: string, defaultValue?: Resolvable<T | null>): Promise<T | null>;
+  static pull<T = unknown>(key: string, defaultValue?: Resolvable<T | null>): Promise<T | null>;
+  static put(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+  static set(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+  static add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+  static forever(key: string, value: unknown): Promise<boolean>;
+  static increment(key: string, value?: number): Promise<number | false>;
+  static decrement(key: string, value?: number): Promise<number | false>;
+  static remember<T>(key: string, ttl: CacheTtl, callback: () => T | Promise<T>): Promise<T>;
+  static rememberForever<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
+  static forget(key: string): Promise<boolean>;
+  static delete(key: string): Promise<boolean>;
+  static flush(): Promise<boolean>;
+  static clear(): Promise<boolean>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Read a value from the `cache` configuration namespace with a fallback.
+ *
+ * Mirrors the framework `config()` helper but is scoped to the cache config and
+ * never throws when the config file is missing, returning the default instead.
+ *
+ * @param key           Dot path within the cache config.
+ * @param defaultValue  Value returned when the key is not set.
+ */
+declare const configure: <T extends DotPath<CacheConfig>>(key: T, defaultValue: unknown) => DotPathValue<CacheConfig, T>;
+//#endregion
+//#region src/drivers/MemoryStore.d.ts
+/**
+ * An in-process cache store backed by a `Map`.
+ *
+ * The backing map is shared across every `MemoryStore` instance that uses the
+ * same prefix, so resolving the store twice within a process sees the same data
+ * (matching how the other backends behave). Great for development and tests; it
+ * is not shared across processes.
+ */
+declare class MemoryStore extends Store {
+  private readonly prefix;
+  private static stores;
+  private readonly entries;
+  constructor(prefix?: string);
+  getPrefix(): string;
+  get<T = unknown>(key: string): Promise<T | null>;
+  put(key: string, value: unknown, seconds?: number | null): Promise<boolean>;
+  forever(key: string, value: unknown): Promise<boolean>;
+  increment(key: string, value?: number): Promise<number | false>;
+  decrement(key: string, value?: number): Promise<number | false>;
+  forget(key: string): Promise<boolean>;
+  flush(): Promise<boolean>;
+}
+//#endregion
+//#region src/drivers/FileStore.d.ts
+/**
+ * A cache store that persists each entry as a JSON file on disk.
+ *
+ * Keys are hashed to produce safe, fixed length file names. Expired files are
+ * removed lazily on read and ignored otherwise.
+ */
+declare class FileStore extends Store {
+  private readonly directory;
+  private readonly prefix;
+  constructor(directory: string, prefix?: string);
+  getPrefix(): string;
+  private pathFor;
+  private ensureDirectory;
+  get<T = unknown>(key: string): Promise<T | null>;
+  put(key: string, value: unknown, seconds?: number | null): Promise<boolean>;
+  forever(key: string, value: unknown): Promise<boolean>;
+  increment(key: string, value?: number): Promise<number | false>;
+  decrement(key: string, value?: number): Promise<number | false>;
+  forget(key: string): Promise<boolean>;
+  flush(): Promise<boolean>;
+}
+//#endregion
+//#region src/drivers/RedisStore.d.ts
+/**
+ * A Redis backed cache store using an ioredis compatible client.
+ *
+ * Values are JSON serialized. Numeric helpers use native `INCRBY`/`DECRBY` so
+ * counters stay atomic across processes. `ioredis` is an optional peer
+ * dependency; it is imported lazily so applications that never use the redis
+ * store don't need it installed.
+ */
+declare class RedisStore extends Store {
+  private readonly redisConfig;
+  private readonly prefix;
+  private client?;
+  constructor(redisConfig: RedisStoreConfig, prefix?: string);
+  getPrefix(): string;
+  private prefixed;
+  private connection;
+  /**
+   * Disconnect the underlying client. Useful for tests and graceful shutdown.
+   */
+  disconnect(): Promise<void>;
+  get<T = unknown>(key: string): Promise<T | null>;
+  put(key: string, value: unknown, seconds?: number | null): Promise<boolean>;
+  forever(key: string, value: unknown): Promise<boolean>;
+  increment(key: string, value?: number): Promise<number | false>;
+  decrement(key: string, value?: number): Promise<number | false>;
+  forget(key: string): Promise<boolean>;
+  flush(): Promise<boolean>;
+}
+//#endregion
+//#region src/drivers/DatabaseStore.d.ts
+/**
+ * A cache store that persists entries in a relational table via
+ * `@arkstack/database`.
+ *
+ * The table is expected to have `key` (string, primary), `value` (text), and
+ * `expiration` (nullable integer epoch seconds) columns. `@arkstack/database`
+ * is an optional peer dependency and is imported lazily.
+ */
+declare class DatabaseStore extends Store {
+  private readonly databaseConfig;
+  private readonly prefix;
+  private db?;
+  constructor(databaseConfig: DatabaseStoreConfig, prefix?: string);
+  getPrefix(): string;
+  private prefixed;
+  private get table();
+  private database;
+  get<T = unknown>(key: string): Promise<T | null>;
+  put(key: string, value: unknown, seconds?: number | null): Promise<boolean>;
+  forever(key: string, value: unknown): Promise<boolean>;
+  increment(key: string, value?: number): Promise<number | false>;
+  decrement(key: string, value?: number): Promise<number | false>;
+  forget(key: string): Promise<boolean>;
+  flush(): Promise<boolean>;
+}
+//#endregion
+export { Cache, CacheConfig, CacheDriverName, CacheRow, CacheStoreConfig, CacheStoreFactory, CacheTtl, CustomCacheStoreRegistry, DatabaseFacade, DatabaseStore, DatabaseStoreConfig, FilePayload, FileStore, FileStoreConfig, MemoryEntry, MemoryStore, MemoryStoreConfig, RedisClient, RedisStore, RedisStoreConfig, Repository, Resolvable, Store, configure, ttlToSeconds };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as RedisStore, c as DatabaseStore, i as ttlToSeconds, l as Store, n as configure, o as MemoryStore, r as Repository, s as FileStore, t as Cache } from "./CacheManager-DfAiI5Ft.js";
+export { Cache, DatabaseStore, FileStore, MemoryStore, RedisStore, Repository, Store, configure, ttlToSeconds };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@arkstack/cache",
+  "version": "0.13.0",
+  "type": "module",
+  "description": "Cache module for Arkstack, providing a unified, driver based caching layer for the framework.",
+  "homepage": "https://arkstack.toneflix.net/guide/cache",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkstack-hq/arkstack.git",
+    "directory": "packages/cache"
+  },
+  "keywords": [
+    "cache",
+    "caching",
+    "memory",
+    "file",
+    "redis",
+    "database",
+    "store",
+    "arkstack"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./commands/CacheClearCommand": "./dist/commands/CacheClearCommand.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@arkstack/common": "^0.13.0"
+  },
+  "peerDependencies": {
+    "@h3ravel/musket": "^2.2.0",
+    "ioredis": "^5.4.1",
+    "@arkstack/contract": "^0.13.0",
+    "@arkstack/database": "^0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@arkstack/database": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "version:patch": "pnpm version patch"
+  }
+}