@arkstack/cache 0.5.3

package/dist/CacheManager-Do82q7KO.js

@@ -0,0 +1,709 @@
+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. Run
+* `ark publish --tag cache-migrations` to add the migration that creates it.
+* `@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 };