@resolid/cache 0.1.0 → 0.2.0

package/README.md

@@ -5,6 +5,91 @@
 
 <b>[Documentation](https://www.resolid.tech/docs/cache)</b> | [Framework Bundle](https://github.com/resolid/framework)
 
+## Type-safe Async Cache for TypeScript
+
+A fully-typed, flexible cache system for modern TypeScript projects.
+Supports single and batch operations, optional TTL, and pluggable storage backends.
+Designed for libraries, frameworks, and applications needing predictable async caching.
+
+### Feature
+
+- Fully typed with TypeScript — no `any`.
+- Supports get/set/del/clear operations.
+- Supports batch operations: getMultiple, setMultiple, delMultiple.
+- Optional TTL for automatic expiration.
+- Pluggable store backend (default is `nullCache`).
+- Detects existence of keys via `has`.
+- Handles disposal of resources via `dispose`.
+
+### Installation
+
+```shell
+pnpm add @resolid/cache
+# or
+npm install @resolid/cache
+# or
+yarn add @resolid/cache
+# or
+bun add @resolid/cache
+```
+
+### Usage
+
+```js
+import { Cacher } from "@resolid/cache";
+
+const cache = new Cacher({ defaultTtl: 1000 });
+
+// Single set/get
+await cache.set("foo", { a: 1 });
+const value = await cache.get("foo"); // -> { a: 1 }
+
+// Check existence
+const exists = await cache.has("foo"); // -> true
+
+// Batch set/get
+await cache.setMultiple({ key1: 1, key2: 2 });
+const values = await cache.getMultiple(["key1", "key2"]); // -> [1, 2]
+
+// Delete
+await cache.del("foo");
+await cache.delMultiple(["key1", "key2"]);
+
+// Clear all
+await cache.clear();
+
+// Dispose store if necessary
+await cache.dispose();
+```
+
+### Options
+
+```ts
+export interface CacheOptions {
+  store?: CacheStore;
+  defaultTtl?: number;
+}
+```
+
+### Store Interface
+
+Your custom store should implement `CacheStore`:
+
+```ts
+export interface CacheStore {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, ttl?: number): Promise<boolean>;
+  del(key: string): Promise<boolean>;
+  clear(): Promise<boolean>;
+
+  getMultiple?(keys: string[]): Promise<(string | undefined)[]>;
+  setMultiple?(values: Record<string, string>, ttl?: number): Promise<boolean>;
+  delMultiple?(keys: string[]): Promise<boolean>;
+  has?(key: string): Promise<boolean>;
+  dispose?(): Promise<void> | void;
+}
+```
+
 ## License
 
 MIT License (MIT). Please see [LICENSE](./LICENSE) for more information.

package/dist/index.d.ts

@@ -1,21 +1,26 @@
 import { t as CacheStore } from "./index-DvzAtk0z.js";
 
 //#region src/index.d.ts
-type CreateCacheOptions = {
+interface CacheOptions {
   store?: CacheStore;
   defaultTtl?: number;
-};
-type CacheInstance = {
-  get: <T>(key: string, defaultValue?: T) => Promise<T | undefined>;
-  set: <T>(key: string, value: T, ttl?: number) => Promise<boolean>;
-  del: (key: string) => Promise<boolean>;
-  clear: () => Promise<boolean>;
-  getMultiple: <T>(keys: string[], defaultValue?: T) => Promise<(T | undefined)[]>;
-  setMultiple: <T>(values: Record<string, T>, ttl?: number) => Promise<boolean>;
-  delMultiple: (keys: string[]) => Promise<boolean>;
-  has: (key: string) => Promise<boolean>;
-  dispose: () => Promise<void> | void;
-};
-declare const createCache: (options?: CreateCacheOptions) => CacheInstance;
+}
+declare class Cacher {
+  private readonly store;
+  private readonly defaultTtl?;
+  constructor({
+    store,
+    defaultTtl
+  }?: CacheOptions);
+  get<T>(key: string, defaultValue?: T): Promise<T | undefined>;
+  set<T>(key: string, value: T, ttl?: number): Promise<boolean>;
+  del(key: string): Promise<boolean>;
+  clear(): Promise<boolean>;
+  getMultiple<T>(keys: string[], defaultValue?: T): Promise<(T | undefined)[]>;
+  setMultiple<T>(values: Record<string, T>, ttl?: number): Promise<boolean>;
+  delMultiple(keys: string[]): Promise<boolean>;
+  has(key: string): Promise<boolean>;
+  dispose(): Promise<void>;
+}
 //#endregion
-export { CacheInstance, CreateCacheOptions, createCache };
+export { CacheOptions, Cacher };

package/dist/index.js

@@ -1 +1 @@
-import{t as e}from"./null-cache-2iHFUXTp.js";import{t}from"./utils-CV58ddJF.js";import{destr as n}from"destr";const r=(r={})=>{let{defaultTtl:i,store:a=e}=r,o=async(e,r)=>{let i=await a.get(t(e));return i===void 0?r:n(i)},s=(e,n,r)=>a.set(t(e),JSON.stringify(n),r??i),c=e=>a.del(t(e));return{get:o,set:s,del:c,clear:()=>a.clear(),getMultiple:(e,r)=>typeof a.getMultiple==`function`?a.getMultiple(e.map(e=>t(e))).then(e=>e.map(e=>e===void 0?r:n(e))):Promise.all(e.map(e=>o(e,r))),setMultiple:(e,n)=>typeof a.setMultiple==`function`?a.setMultiple(Object.entries(e).reduce((e,[n,r])=>(e[t(n)]=JSON.stringify(r),e),{}),n):Promise.all(Object.entries(e).map(([e,t])=>s(e,t,n))).then(e=>e.every(Boolean)),delMultiple:e=>typeof a.delMultiple==`function`?a.delMultiple(e.map(e=>t(e))):Promise.all(e.map(c)).then(e=>e.every(Boolean)),has:async e=>typeof a.has==`function`?a.has(t(e)):o(e).then(e=>e!==void 0),dispose:async()=>{a.dispose&&await a.dispose()}}};export{r as createCache};
+import{t as e}from"./null-cache-95ZKDSid.js";import{t}from"./utils-CV58ddJF.js";import{destr as n}from"destr";var r=class{store;defaultTtl;constructor({store:t=new e,defaultTtl:n}={}){this.store=t,this.defaultTtl=n}async get(e,r){let i=await this.store.get(t(e));return i===void 0?r:n(i)}set(e,n,r){return this.store.set(t(e),JSON.stringify(n),r??this.defaultTtl)}del(e){return this.store.del(t(e))}clear(){return this.store.clear()}async getMultiple(e,r){return this.store.getMultiple?(await this.store.getMultiple(e.map(t))).map(e=>e===void 0?r:n(e)):Promise.all(e.map(e=>this.get(e,r)))}async setMultiple(e,n){if(this.store.setMultiple){let r=Object.entries(e).reduce((e,[n,r])=>(e[t(n)]=JSON.stringify(r),e),{});return this.store.setMultiple(r,n)}return(await Promise.all(Object.entries(e).map(([e,t])=>this.set(e,t,n)))).every(Boolean)}async delMultiple(e){return this.store.delMultiple?this.store.delMultiple(e.map(t)):(await Promise.all(e.map(e=>this.del(e)))).every(Boolean)}async has(e){return this.store.has?this.store.has(t(e)):await this.get(e)!==void 0}async dispose(){await this.store.dispose?.()}};export{r as Cacher};

package/dist/null-cache-95ZKDSid.js

@@ -0,0 +1 @@
+var e=class{async get(e){}async set(e,t,n){return!0}async del(e){return!0}async clear(){return!0}async getMultiple(e){return e.map(()=>void 0)}async setMultiple(e,t){return!0}async delMultiple(e){return!0}async has(e){return!1}async dispose(){}};export{e as t};

package/dist/stores.d.ts

@@ -1,9 +1,27 @@
 import { t as CacheStore } from "./index-DvzAtk0z.js";
 
 //#region src/stores/memory-cache.d.ts
-declare const createMemoryCache: (maxSize?: number) => CacheStore;
+declare class MemoryCache implements CacheStore {
+  private readonly lru;
+  constructor(maxSize?: number);
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, ttl?: number): Promise<boolean>;
+  del(key: string): Promise<boolean>;
+  clear(): Promise<boolean>;
+  dispose(): Promise<void>;
+}
 //#endregion
 //#region src/stores/null-cache.d.ts
-declare const nullCache: Required<CacheStore>;
+declare class NullCache implements Required<CacheStore> {
+  get<T>(_: string): Promise<T>;
+  set(_key: string, _value: string, _ttl?: number): Promise<boolean>;
+  del(_key: string): Promise<boolean>;
+  clear(): Promise<boolean>;
+  getMultiple<T>(_keys: string[]): Promise<(T | undefined)[]>;
+  setMultiple(_values: Record<string, string>, _ttl?: number): Promise<boolean>;
+  delMultiple(_keys: string[]): Promise<boolean>;
+  has(_key: string): Promise<boolean>;
+  dispose(): Promise<void>;
+}
 //#endregion
-export { createMemoryCache, nullCache };
+export { MemoryCache, NullCache };

package/dist/stores.js

@@ -1 +1 @@
-import{t as e}from"./null-cache-2iHFUXTp.js";import t from"quick-lru";const n=(e=1e3)=>{let n=new t({maxSize:e});return{get:async e=>n.get(e),set:async(e,t,r)=>(n.set(e,t,r?{maxAge:r*1e3}:void 0),!0),del:async e=>n.delete(e),clear:async()=>(n.clear(),!0),dispose:async()=>{n.clear()}}};export{n as createMemoryCache,e as nullCache};
+import{t as e}from"./null-cache-95ZKDSid.js";import t from"quick-lru";var n=class{lru;constructor(e=1e3){this.lru=new t({maxSize:e})}async get(e){return this.lru.get(e)}async set(e,t,n){return this.lru.set(e,t,n?{maxAge:n*1e3}:void 0),!0}async del(e){return this.lru.delete(e)}async clear(){return this.lru.clear(),!0}async dispose(){this.lru.clear()}};export{n as MemoryCache,e as NullCache};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resolid/cache",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "The Resolid Cache package.",
   "keywords": [
@@ -44,21 +44,15 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "destr": "^2.0.5",
     "quick-lru": "^7.3.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "beta",
-    "tsdown": "^0.15.9",
+    "@vitest/coverage-v8": "^4.0.3",
+    "tsdown": "^0.15.10",
     "typescript": "^5.9.3",
-    "vitest": "beta"
+    "vitest": "^4.0.3"
   },
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24"
@@ -66,5 +60,11 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/dist/null-cache-2iHFUXTp.js

@@ -1 +0,0 @@
-const e={get:async()=>{},set:async()=>!0,del:async()=>!0,clear:async()=>!0,getMultiple:async e=>e.map(()=>void 0),setMultiple:async()=>!0,delMultiple:async()=>!0,has:async()=>!1,dispose:async()=>{}};export{e as t};