polystore 0.8.0 → 0.9.0

package/readme.md

@@ -1,40 +1,46 @@
 # Polystore [![npm install polystore](https://img.shields.io/badge/npm%20install-polystore-blue.svg)](https://www.npmjs.com/package/polystore) [![test badge](https://github.com/franciscop/polystore/workflows/tests/badge.svg "test badge")](https://github.com/franciscop/polystore/blob/master/.github/workflows/tests.yml) [![gzip size](https://badgen.net/bundlephobia/minzip/polystore?label=gzip&color=green)](https://github.com/franciscop/polystore/blob/master/src/index.js)
 
-A small compatibility layer for many KV stores like localStorage, Redis, FileSystem, etc:
+A key-value library to unify the API of [many clients](#clients), like localStorage, Redis, FileSystem, etc:
 
 ```js
 import kv from "polystore";
-const store = kv(new Map()); // in-memory
-const store1 = kv(localStorage); // Persist in the browser
-const store2 = kv(redisClient); // Use a Redis client for backend persistence
-// etc.
-```
-
-This is the [API](#api) with all of the methods (they are all `async`):
-
-- `.get(key): any`: retrieve a single value, or `null` if it doesn't exist or is expired.
-- `.set(key, value, options?)`: save a single value, which can be anything that is serializable.
-- `.add(value, options?)`: same as with `.set()`, but auto-generate the key.
-- `.has(key): boolean`: check whether the key is in the store or not.
-- `.del(key)`: delete a single value from the store.
-- `.keys(prefix?): string[]`: get a list of all the available strings in the store.
-- `.values(prefix?): any[]`: get a list of all the values in the store.
-- `.entries(prefix?): [string, any][]`: get a list of all the key-value pairs in the store.
-- `.clear()`: delete ALL of the data in the store, effectively resetting it.
-- `.close()`: (only _some_ stores) ends the connection to the store.
-- `.prefix(prefix): store`: create a new sub-instance of the store where all the keys have this prefix.
-
-Available stores:
-
-- **Memory** `new Map()` (fe+be): an in-memory API to keep your KV store
-- **Local Storage** `localStorage` (fe): persist the data in the browser's localStorage
-- **Session Storage** `sessionStorage` (fe): persist the data in the browser's sessionStorage
-- **Cookies** `"cookie"` (fe): persist the data using cookies
-- **LocalForage** `localForage` (fe): persist the data on IndexedDB
-- **FS File** `new URL('file:///...')` (be): store the data in a single JSON file
-- **Redis Client** `redisClient` (be): use the Redis instance that you connect to
-- **Cloudflare KV** `env.KV_NAMESPACE` (be): use Cloudflare's KV store
-- (WIP) **Consul KV** `new Consul()` (fe+be): use Hashicorp's Consul KV store (https://www.npmjs.com/package/consul#kv)
+const store1 = kv(new Map()); // in-memory
+const store2 = kv(localStorage); // Persist in the browser
+const store3 = kv(redisClient); // Use a Redis client for backend persistence
+const store4 = kv(yourOwnStore); // Create a store based on your code
+// Many more here
+```
+
+These are all the methods of the [API](#api) (they are all `async`):
+
+- [`.get(key)`](#get): read a single value, or `null` if it doesn't exist or is expired.
+- [`.set(key, value, options?)`](#set): save a single value that is serializable.
+- [`.add(value, options?)`](#add): same as `.set()`, but auto-generates the key.
+- [`.has(key)`](#has): check whether a key exists or not.
+- [`.del(key)`](#del): delete a single value from the store.
+- [`.keys()`](#keys): get a list of all the available strings in the store.
+- [`.values()`](#values): get a list of all the values in the store.
+- [`.entries()`](#entries): get a list of all the key-value pairs.
+- [`.all()`](#all): get an object with the key:values mapped.
+- [`.clear()`](#clear): delete ALL of the data in the store, effectively resetting it.
+- [`.close()`](#close): (only _some_ stores) ends the connection to the store.
+- [`.prefix(prefix)`](#prefix): create a sub-store that only manages the keys with the given prefix.
+
+Available clients for the KV store:
+
+- [**Memory** `new Map()`](#memory) (fe+be): an in-memory API to keep your KV store.
+- [**Local Storage** `localStorage`](#local-storage) (fe): persist the data in the browser's localStorage.
+- [**Session Storage** `sessionStorage`](#session-storage) (fe): persist the data in the browser's sessionStorage.
+- [**Cookies** `"cookie"`](#cookies) (fe): persist the data using cookies
+- [**LocalForage** `localForage`](#local-forage) (fe): persist the data on IndexedDB
+- [**File** `new URL('file:///...')`](#file) (be): store the data in a single JSON file in your FS
+- [**Redis Client** `redisClient`](#redis-client) (be): use the Redis instance that you connect to
+- [**Cloudflare KV** `env.KV_NAMESPACE`](#cloudflare-kv) (be): use Cloudflare's KV store
+- [**Level** `new Level('example', { valueEncoding: 'json' })`](#level): support the whole Level ecosystem
+- [**Etcd** `new Etcd3()`](#etcd): the Microsoft's high performance KV store.
+- [**_Custom_** `{}`](#creating-a-store) (?): create your own store with just 3 methods!
+
+> This library should be as performant as the client you use with the item methods (GET/SET/ADD/HAS/DEL). For other and advanced cases, see [the performance considerations](#performance) and read the docs on your client.
 
 I made this library to be used as a "building block" of other libraries, so that _your library_ can accept many cache stores effortlessly! It's isomorphic (Node.js and the Browser) and tiny (~2KB). For example, let's say you create an API library, then you can accept the stores from your client:
 
@@ -50,7 +56,7 @@ MyApi({ cache: env.KV_NAMESPACE }); // OR
 
 ## API
 
-See how to initialize each store [in the Stores list documentation](#stores). But basically for every store, it's like this:
+See how to initialize each store [in the Clients list documentation](#clients). But basically for every store, it's like this:
 
 ```js
 import kv from "polystore";
@@ -164,7 +170,7 @@ if (await store.has('cookie-consent')) {
 
 ### .del()
 
-Remove a single key from the store:
+Remove a single key from the store and return the key itself:
 
 ```js
 await store.del(key: string);
@@ -225,9 +231,11 @@ Remove all of the data from the store:
 await store.clear();
 ```
 
-### .prefix() (unstable)
+### .prefix()
 
-Create a sub-store where all the operations use the given prefix. This is **the only method** of the store that is sync and you don't need to await:
+> There's [an in-depth explanation about Substores](#substores) that is very informative for production usage.
+
+Creates **a new instance** of the Store, _with the same client_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the client. You only write `.prefix()` once and then don't need to worry about any prefix for any method anymore, it's all automatic. It's **the only method** that you don't need to await:
 
 ```js
 const store = kv(new Map());
@@ -237,16 +245,17 @@ const session = store.prefix("session:");
 Then all of the operations will be converted internally to add the prefix when reading, writing, etc:
 
 ```js
-const val = await session.get("key1"); // .get('session:key1');
-await session.set("key2", "some data"); // .set('session:key2', ...);
-const val = await session.has("key3"); // .has('session:key3');
-await session.del("key4"); // .del('session:key4');
-await session.keys(); // .keys('session:');
+const session = store.prefix("session:");
+const val = await session.get("key1"); // store.get('session:key1');
+await session.set("key2", "some data"); // store.set('session:key2', ...);
+const val = await session.has("key3"); // store.has('session:key3');
+await session.del("key4"); // store.del('session:key4');
+await session.keys(); // store.keys(); + filter
 // ['key1', 'key2', ...]   Note no prefix here
 await session.clear(); // delete only keys with the prefix
 ```
 
-This will probably never be stable given the nature of some engines, so as an alternative please consider using two stores instead of prefixes:
+Different clients have better/worse support for substores, and in some cases some operations might be slower. This should be documented on each client's documentation (see below). As an alternative, you can always create two different stores instead of a substore:
 
 ```js
 // Two in-memory stores
@@ -260,9 +269,11 @@ const books = kv(new URL(`file://${import.meta.dirname}/books.json`));
 
 The main reason this is not stable is because [_some_ store engines don't allow for atomic deletion of keys given a prefix](https://stackoverflow.com/q/4006324/938236). While we do still clear them internally in those cases, that is a non-atomic operation and it could have some trouble if some other thread is reading/writing the data _at the same time_.
 
-## Stores
+## Clients
 
-Accepts directly the store, or a promise that resolves into a store. All of the stores, including those that natively _don't_ support it, are enhanced with `Promises` and `expires` times, so they all work the same way.
+A client is the library that manages the low-level store operations. For example, the Redis Client, or the browser's `localStorage` API. In some exceptions it's just a string and we do a bit more work on Polystore, like with `"cookie"` or `"file:///users/me/data.json"`.
+
+Polystore provides a unified API you can use `Promises`, `expires` and `.prefix()` even with those stores that do not support these operations natively.
 
 ### Memory
 
@@ -271,18 +282,31 @@ An in-memory KV store, with promises and expiration time:
 ```js
 import kv from "polystore";
 
-// This already works, by default if there's nothing it'll use
-// a new Map()
-const store = kv();
-await store.set("key1", "Hello world");
+const store = kv(new Map());
+
+await store.set("key1", "Hello world", { expires: "1h" });
 console.log(await store.get("key1"));
+// "Hello world"
+```
+
+It can also be initialized empty, then it'll use the in-memory store:
+
+```js
+import kv from "polystore";
 
-// Or you can be explicit:
+const store = kv();
 const store = kv(new Map());
-await store.set("key1", "Hello world");
-console.log(await store.get("key1"));
 ```
 
+<details>
+  <summary>Why use polystore with <code>new Map()</code>?</summary>
+  <p>Besides the other benefits already documented elsewhere, these are the ones specifically for wrapping Map() with polystore:</p>
+  <ul>
+    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
+  </ul>
+</details>
+
 ### Local Storage
 
 The traditional localStorage that we all know and love, this time with a unified API, and promises:
@@ -291,8 +315,10 @@ The traditional localStorage that we all know and love, this time with a unified
 import kv from "polystore";
 
 const store = kv(localStorage);
-await store.set("key1", "Hello world");
+
+await store.set("key1", "Hello world", { expires: "1h" });
 console.log(await store.get("key1"));
+// "Hello world"
 ```
 
 Same limitations as always apply to localStorage, if you think you are going to use too much storage try instead our integration with [Local Forage](#local-forage)!
@@ -305,8 +331,10 @@ Same as localStorage, but now for the session only:
 import kv from "polystore";
 
 const store = kv(sessionStorage);
-await store.set("key1", "Hello world");
+
+await store.set("key1", "Hello world", { expires: "1h" });
 console.log(await store.get("key1"));
+// "Hello world"
 ```
 
 ### Cookies
@@ -316,9 +344,11 @@ Supports native browser cookies, including setting the expire time:
 ```js
 import kv from "polystore";
 
-const store = kv("cookie"); // yes, just a plain string
-await store.set("key1", "Hello world");
+const store = kv("cookie"); // just a plain string
+
+await store.set("key1", "Hello world", { expires: "1h" });
 console.log(await store.get("key1"));
+// "Hello world"
 ```
 
 It is fairly limited for how powerful cookies are, but in exchange it has the same API as any other method or KV store. It works with browser-side Cookies (no http-only).
@@ -334,8 +364,10 @@ import kv from "polystore";
 import localForage from "localforage";
 
 const store = kv(localForage);
+
 await store.set("key1", "Hello world", { expires: "1h" });
 console.log(await store.get("key1"));
+// "Hello world"
 ```
 
 ### Redis Client
@@ -346,25 +378,37 @@ Supports the official Node Redis Client. You can pass either the client or the p
 import kv from "polystore";
 import { createClient } from "redis";
 
-// Note: no need for await or similar
 const store = kv(createClient().connect());
-await store.set("key1", "Hello world");
+
+await store.set("key1", "Hello world", { expires: "1h" });
 console.log(await store.get("key1"));
+// "Hello world"
 ```
 
+You don't need to `await` for the connect or similar, this will process it properly.
+
 > Note: the Redis client expire resolution is in the seconds, so times shorter than 1 second like `expires: 0.02` (20 ms) don't make sense for this storage method and won't properly save them.
 
-### FS File
+### File
+
+Treat a JSON file in your filesystem as the source for the KV store:
 
 ```js
 import kv from "polystore";
 
-// Create a url with the file protocol:
 const store = kv(new URL("file:///Users/me/project/cache.json"));
 
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+You can also create multiple stores:
+
+```js
 // Paths need to be absolute, but you can use process.cwd() to make
 // it relative to the current process:
-const store = kv(new URL(`file://${process.cwd()}/cache.json`));
+const store1 = kv(new URL(`file://${process.cwd()}/cache.json`));
 const store2 = kv(new URL(`file://${import.meta.dirname}/data.json`));
 ```
 
@@ -379,18 +423,16 @@ export default {
   async fetch(request, env, ctx) {
     const store = kv(env.YOUR_KV_NAMESPACE);
 
-    await store.set("KEY", "VALUE");
-    const value = await store.get("KEY");
+    await store.set("key1", "Hello world", { expires: "1h" });
+    console.log(await store.get("key1"));
+    // "Hello world"
 
-    if (!value) {
-      return new Response("Value not found", { status: 404 });
-    }
-    return new Response(value);
+    return new Response("My response");
   },
 };
 ```
 
-Why? The Cloudflare native KV store only accepts strings and has you manually calculating timeouts, but as usual with `polystore` you can set/get any serializable value and set the timeout in a familiar format:
+Why use polystore? The Cloudflare native KV store only accepts strings and has you manually calculating timeouts, but as usual with `polystore` you can set/get any serializable value and set the timeout in a familiar format:
 
 ```js
 // GOOD - with polystore
@@ -404,9 +446,57 @@ await env.YOUR_KV_NAMESPACE.put("user", serialValue, {
 });
 ```
 
-## Expiration explained
+### Level
 
-While different engines do expiration slightly differently internally, in creating polystore we want to ensure certain constrains, which _can_ affect performance. For example, if you do this operation:
+Support [the Level ecosystem](https://github.com/Level/level), which is itself composed of modular methods:
+
+```js
+import kv from "polystore";
+import { Level } from "level";
+
+const store = kv(new Level("example", { valueEncoding: "json" }));
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+### Etcd
+
+Connect to Microsoft's Etcd Key-Value store:
+
+```js
+import kv from "polystore";
+import { Etcd3 } from "etcd3";
+
+const store = kv(new Etcd3());
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+### Custom store
+
+Please see the [creating a store](#creating-a-store) section for more details!
+
+## Performance
+
+> TL;DR: if you only use the item operations (add,set,get,has,del) and your store supports expiration natively, you have nothing to worry about!
+
+While all of our stores support `expires`, `.prefix()` and group operations, the nature of those makes them to have different performance characteristics.
+
+**Expires** we polyfill expiration when the underlying library does not support it. The impact on read/write operations and on data size of each key should be minimal. However, it can have a big impact in storage size, since the expired keys are not evicted automatically. Note that when attempting to read an expired key, polystore **will delete that key**. However, if an expired key is never read, it would remain in the datastore and could create some old-data issues. This is **especially important where sensitive data is involved**! To fix this, the easiest way is calling `await store.entries();` on a cron job and that should evict all of the old keys (this operation is O(n) though, so not suitable for calling it on EVERY API call, see the next point).
+
+**Group operations** these are there mostly for small datasets only, for one-off scripts or for dev purposes, since by their own nature they can _never_ be high performance. But this is normal if you think about traditional DBs, reading a single record by its ID is O(1), while reading all of the IDs in the DB into an array is going to be O(n). Same applies with polystore.
+
+**Substores** when dealing with a `.prefix()` substore, the same applies. Item operations should see no performance degradation from `.prefix()`, but group operations follow the above performance considerations. Some engines might have native prefix support, so performance in those is better for group operations in a substore than the whole store. But in general you should consider `.prefix()` as a convenient way of classifying your keys and not as a performance fix for group operations.
+
+## Expires
+
+> Warning: if a client doesn't support expiration natively, we will hide expired keys on the API calls for a nice DX, but _old data might not be evicted automatically_, which is relevant especially for sensitive information. You'd want to set up a cron job to evict it manually, since for large datasets it might be more expensive (O(n)).
+
+We unify all of the clients diverse expiration methods into a single, easy one with `expires`:
 
 ```js
 // in-memory store
@@ -421,7 +511,7 @@ console.log(await store.get("a")); // 'b'
 // Make sure the key is expired
 await delay(2000); // 2s
 
-// Not only the .get() is null, but `.has()` returns false, and .keys() ignores it
+// The group methods also ignore expired keys
 console.log(await store.keys()); // []
 console.log(await store.has("a")); // false
 console.log(await store.get("a")); // null
@@ -433,25 +523,144 @@ However, in some stores this does come with some potential performance disadvant
 
 For other stores like Redis this is not a problem, because the low-level operations already do them natively, so we don't need to worry about this for performance at the user-level. Instead, Redis and cookies have the problem that they only have expiration resolution at the second level. Meaning that 800ms is not a valid Redis expiration time, it has to be 1s, 2s, etc.
 
+## Substores
+
+> There's some [basic `.prefix()` API info](#prefix) for everyday usage, this section is the in-depth explanation.
+
+What `.prefix()` does is it creates **a new instance** of the Store, _with the same client_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the client. The issue is that support from the underlying clients is inconsistent.
+
+When dealing with large or complex amounts of data in a KV store, some times it's useful to divide them by categories. Some examples might be:
+
+- You use KV as a cache, and have different categories of data.
+- You use KV as a session store, and want to differentiate different kinds of sessions.
+- You use KV as a primary data store, and have different types of datasets.
+
+For these and more situations, you can use `.prefix()` to simplify your life further.
+
 ## Creating a store
 
-A store needs at least 4 methods with these signatures:
+To create a store, you define a class with these methods:
 
 ```js
-const store = {};
-store.get = (key: string) => Promise<any>;
-store.set = (key: string, value: any, { expires: number }) => Promise<string>;
-store.entries = (prefix: string = "") => Promise<[key:string, value:any][]>;
-store.clear = () => Promise<null>;
+class MyClient {
+  // If this is set to `true`, the CLIENT (you) handle the expiration, so
+  // the `.set()` and `.add()` receive a `expires` that is a `null` or `number`:
+  EXPIRES = false;
+
+  // Mandatory methods (2 item-methods, 2 group-methods)
+  get (key): Promise<any>;
+  set (key, value, { expires: null|number }): Promise<null>;
+  entries (prefix): Promise<[string, any][]>;
+
+  // Optional item methods (for optimization or customization)
+  add (prefix, data, { expires: null|number }): Promise<string>;
+  has (key): Promise<boolean>;
+  del (key): Promise<null>;
+
+  // Optional group methods
+  keys (prefix): Promise<string[]>;
+  values (prefix): Promise<any[]>;
+  clear (prefix): Promise<null>;
+
+  // Optional misc method
+  close (): Promise<null>;
+}
 ```
 
-All of the other methods will be implemented on top of these if not available, but you can provide those as well for optimizations, incompatible APIs, etc. For example, `.set('a', null)` _should_ delete the key `a`, and for this you may provide a native implementation:
+Note that this is NOT the public API, it's the internal **client** API. It's simpler than the public API since we do some of the heavy lifting as an intermediate layer (e.g. the `expires` will always be a `null` or `number`, never `undefined` or a `string`), but also it differs from polystore's API, like `.add()` has a different signature, and the group methods all take a explicit prefix.
+
+**Expires**: if you set the `EXPIRES = true`, then you are indicating that the client WILL manage the lifecycle of the data. This includes all methods, for example if an item is expired, then its key should not be returned in `.keys()`, it's value should not be returned in `.values()`, and the method `.has()` will return `false`. The good news is that you will always receive the option `expires`, which is either `null` (no expiration) or a `number` indicating the time when it will expire.
+
+**Prefix**: we manage the `prefix` as an invisible layer on top, you only need to be aware of it in the `.add()` method, as well as in the group methods:
 
 ```js
-const native = myNativeStore();
+// What the user of polystore does:
+const store = await kv(client).prefix("hello:").prefix("world:");
 
-const store = {};
-store.get = (key) => native.getItem(key);
-// ...
-store.del = (key) => native.deleteItem(key);
+// User calls this, then the client is called with that:
+const value = await store.get("a");
+// client.get("hello:world:a");
+
+// User calls this, then the client is called with that:
+const value = await store.entries();
+// client.entries("hello:world:");
+```
+
+> Note: all of the _group methods_ that return keys, should return them **with the prefix stripped**:
+
+```js
+// Example if your client works around a simple object {}, we want to remove
+// the `prefix` from the beginning of the keys returned:
+client.keys = (prefix) => {
+  return Object.keys(subStore)
+    .filter((key) => key.startsWith(prefix))
+    .map((key) => key.slice(prefix.length)); // <= Important!
+};
+```
+
+You can and should just concatenate the `key + options.prefix`. We don't do it for two reasons: in some cases, like `.add()`, there's no key that we can use to concatenate, and also you might
+
+For example, if the user of `polystore` does `kv(client).prefix('hello:').get('a')`, your store will be directly called with `client.get('a', { prefix: 'hello:' })`. You can safely concatenate `options.prefix + key` since this library always ensures that the prefix is defined and defaults to `''`. We don't concatenate it interally because in some cases (like in `.add()`) it makes more sense that this is handled by the client as an optimization.
+
+While the signatures are different, you can check each entries on the output of Polystore API to see what is expected for the methods of the client to do, e.g. `.clear()` will remove all of the items that match the prefix (or everything if there's no prefix).
+
+**Example: Plain Object client**
+
+This is a good example of how simple a store can be, however do not use it literally since it behaves the same as the already-supported `new Map()`, only use it as the base for your own clients:
+
+```js
+const dataSource = {};
+
+class MyClient {
+  get(key) {
+    return dataSource[key];
+  }
+
+  // No need to stringify it or anything for a plain object storage
+  set(key, value) {
+    dataSource[key] = value;
+  }
+
+  // Filter them by the prefix, note that `prefix` will always be a string
+  entries(prefix) {
+    const entries = Object.entries(dataSource);
+    if (!prefix) return entries;
+    return entries.filter(([key, value]) => key.startsWith(prefix));
+  }
+}
+```
+
+We don't set `EXPIRES` to true since plain objects do NOT support expiration natively. So by not adding the `EXPIRES` property, it's the same as setting it to `false`, and polystore will manage all the expirations as a layer on top of the data. We could be more explicit and set it to `EXPIRES = false`, but it's not needed in this case.
+
+**Example: custom ID generation**
+
+You might want to provide your custom key generation algorithm, which I'm going to call `customId()` for example purposes. The only place where `polystore` generates IDs is in `add`, so you can provide your client with a custom generator:
+
+```js
+class MyClient {
+
+  // Add the opt method .add() to have more control over the ID generation
+  async add (prefix, data, { expires }) {
+    const id = customId();
+    const key = prefix + id;
+    return this.set(key, data, { expires });
+  }
+
+  //
+  async set (...) {
+    // ...
+  }
+}
+```
+
+That way, when using the store, you can simply use `.add()` to generate it:
+
+```js
+import kv from "polystore";
+
+const store = kv(MyClient);
+const id = await store.add({ hello: "world" });
+// this is your own custom id
+const id2 = await store.prefix("hello:").add({ hello: "world" });
+// this is `hello:{your own custom id}`
 ```

package/src/clients/cloudflare.js

@@ -0,0 +1,49 @@
+// Use Cloudflare's KV store
+export default class Cloudflare {
+  // Indicate that the file handler does NOT handle expirations
+  EXPIRES = true;
+
+  // Check whether the given store is a FILE-type
+  static test(client) {
+    return (
+      client?.constructor?.name === "KvNamespace" ||
+      client?.constructor?.name === "EdgeKVNamespace"
+    );
+  }
+
+  constructor(client) {
+    this.client = client;
+  }
+
+  async get(key) {
+    const data = await this.client.get(key);
+    if (!data) return null;
+    return JSON.parse(data);
+  }
+
+  async set(key, value, { expires } = {}) {
+    const expirationTtl = expires ? Math.round(expires) : undefined;
+    this.client.put(key, JSON.stringify(value), { expirationTtl });
+    return key;
+  }
+
+  async del(key) {
+    return this.client.delete(key);
+  }
+
+  async keys(prefix = "") {
+    const raw = await this.client.list({ prefix });
+    return raw.keys.map((k) => k.name);
+  }
+
+  async entries(prefix = "") {
+    const keys = await this.keys(prefix);
+    const values = await Promise.all(keys.map((k) => this.get(k)));
+    return keys.map((key, i) => [key, values[i]]);
+  }
+
+  async clear(prefix = "") {
+    const list = await this.keys(prefix);
+    return Promise.all(list.map((k) => this.del(k)));
+  }
+}

package/src/clients/cookie.js

@@ -0,0 +1,55 @@
+// A client that uses a single file (JSON) as a store
+export default class Cookie {
+  // Indicate if this client handles expirations (true = it does)
+  EXPIRES = true;
+
+  // Check if this is the right class for the given client
+  static test(client) {
+    return client === "cookie" || client === "cookies";
+  }
+
+  // For cookies, an empty value is the same as null, even `""`
+  get(key) {
+    return this.all()[key] || null;
+  }
+
+  set(key, data = null, { expires } = {}) {
+    // Setting it to null deletes it
+    if (data === null) {
+      data = "";
+      expires = -100;
+    }
+
+    let expireStr = "";
+    // NOTE: 0 is already considered here!
+    if (expires !== null) {
+      const now = new Date().getTime();
+      const time = new Date(now + expires * 1000).toUTCString();
+      expireStr = `; expires=${time}`;
+    }
+
+    const value = encodeURIComponent(JSON.stringify(data));
+    document.cookie = encodeURIComponent(key) + "=" + value + expireStr;
+    return key;
+  }
+
+  // Group methods
+  all(prefix = "") {
+    const all = {};
+    for (let entry of document.cookie.split(";")) {
+      const [key, data] = entry.split("=");
+      const name = decodeURIComponent(key.trim());
+      if (!name.startsWith(prefix)) continue;
+      try {
+        all[name] = JSON.parse(decodeURIComponent(data.trim()));
+      } catch (error) {
+        // no-op (some 3rd party can set cookies independently)
+      }
+    }
+    return all;
+  }
+
+  entries(prefix = "") {
+    return Object.entries(this.all(prefix));
+  }
+}