simple-in-memory-cache 0.4.2 → 0.4.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "simple-in-memory-cache",
   "author": "ehmpathy",
   "description": "A simple in-memory cache, for nodejs and the browser, with time based expiration policies.",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "repository": "ehmpathy/simple-in-memory-cache",
   "homepage": "https://github.com/ehmpathy/simple-in-memory-cache",
   "keywords": [

package/readme.md

@@ -3,36 +3,96 @@
 ![test](https://github.com/ehmpathy/simple-in-memory-cache/workflows/test/badge.svg)
 ![publish](https://github.com/ehmpathy/simple-in-memory-cache/workflows/publish/badge.svg)
 
-A simple in-memory cache, for nodejs and the browser, with time based expiration policies.
+A simple, typed, in-memory cache for nodejs and the browser with time-based expiration policies.
 
-# Install
+## install
 
 ```sh
 npm install --save simple-in-memory-cache
 ```
 
-# Example
+## usage
 
-Quickly set and get from the cache:
+### set and get
 
 ```ts
 import { createCache } from 'simple-in-memory-cache';
 
 const { set, get } = createCache();
-set('meaning of life', 42);
-const meaningOfLife = get('meaning of life'); // returns 42
+set('purpose of life', 42);
+const purpose = get('purpose of life'); // returns 42
 ```
 
-Items in the cache live 5 minutes until expiration, by default.
+### expiration
 
-You can change this default when creating the cache:
+items in the cache expire after 5 minutes by default.
+
+change the default expiration on cache creation:
+
+```ts
+const { set, get } = createCache({ expiration: { minutes: 10 } });
+```
+
+override expiration per item:
 
 ```ts
-const { set, get } = createCache({ defaultSecondsUntilExpiration: 10 * 60 }); // updates the default seconds until expiration to 10 minutes
+set('ice cream state', 'solid', { expiration: { seconds: 30 } });
 ```
 
-And you can also override this when setting an item:
+set an item to never expire:
 
 ```ts
-set('acceleration due to gravity', 9.81, { secondsUntilExpiration: Infinity }); // gravity will not change, so we dont need to expire it
+set('speed of light', 299792458, { expiration: null });
 ```
+
+### invalidation
+
+invalidate a cached item with `set(key, undefined)`:
+
+```ts
+set('purpose of life', 42);
+get('purpose of life'); // returns 42
+
+set('purpose of life', undefined);
+get('purpose of life'); // returns undefined
+```
+
+### keys
+
+list all non-expired keys in the cache:
+
+```ts
+const { set, keys } = createCache();
+set('a', 1);
+set('b', 2);
+keys(); // returns ['a', 'b']
+```
+
+## types
+
+the cache is fully typed:
+
+```ts
+import { createCache, SimpleInMemoryCache } from 'simple-in-memory-cache';
+
+const cache: SimpleInMemoryCache<number> = createCache<number>();
+cache.set('answer', 42);
+const answer: number | undefined = cache.get('answer');
+```
+
+## api
+
+### `createCache<T>(options?)`
+
+creates a new cache instance.
+
+**options:**
+- `expiration?: IsoDuration | null` — default expiration for items (default: `{ minutes: 5 }`)
+
+**returns:** `SimpleInMemoryCache<T>`
+
+### `SimpleInMemoryCache<T>`
+
+- `get(key: string): T | undefined` — retrieve an item (returns `undefined` if absent or expired)
+- `set(key: string, value: T, options?): void` — store an item (or invalidate with `undefined`)
+- `keys(): string[]` — list all non-expired keys