polystore 0.9.2 → 0.10.0

package/.github/workflows/tests.yml

@@ -8,12 +8,12 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [18.x, 20.x]
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - name: install dependencies

package/assets/home.html

@@ -4,17 +4,17 @@
   <div>
     <h1>Polystore</h1>
     <p style="max-width: 620px">
-      A universal library for standardizing KV-stores. Great when you don't want
-      to depend on a specific implementation, or for library builders that want
-      to accept any KV store available.
+      A library to unify KV-stores. Allows you to write code that works on any
+      KV store, both on the front-end and backend. Supports substores and
+      intuitive expiration times. Get started:
     </p>
     <pre class="small">npm install polystore</pre>
     <div class="buttons">
       <a class="button" href="/documentation">Documentation</a>
       <a
         class="pseudo button"
-        href="https://www.paypal.me/franciscopresencia/19"
-        >Donate</a
+        href="https://superpeer.com/francisco/-/javascript-and-react-help"
+        >Professional JS help</a
       >
     </div>
   </div>
@@ -25,8 +25,8 @@ import { createClient } from "redis";
 const REDIS = process.env.REDIS_URL;
 const store = kv(createClient(REDIS));
 
-await store.set(&quot;key1&quot;, { hello: &quot;world&quot; });
-console.log(await store.get(&quot;key1&quot;));
+await store.set(key, data, { expires: "1h" });
+console.log(await store.get(key));
 // { hello: &quot;world&quot; }</code></pre>
   </div>
 </section>
@@ -77,7 +77,8 @@ console.log(await store.get(&quot;key1&quot;));
         <a href="/documentation#getting-started">Getting started</a>,
         <a href="/documentation#api">API</a>,
         <a href="/documentation#clients">Clients</a> and
-        <a href="/documentation#examples">examples</a> for your convenience.
+        <a href="/documentation#creating-a-store">custom stores</a> for your
+        convenience.
       </p>
     </div>
   </div>
@@ -152,7 +153,7 @@ console.log(await store.get(&quot;key1&quot;));
       <p>
         At
         <a href="https://bundlephobia.com/package/polystore" target="_blank"
-          >just <strong>2.4kb</strong></a
+          >just <strong>3kb</strong></a
         >
         (min+gzip), the impact on your app loading time is minimal.
       </p>
@@ -180,6 +181,7 @@ console.log(await store.get(&quot;key1&quot;));
         <h3>Intuitive expirations</h3>
       </header>
       <p>Write the expiration as <code>100s</code>, <code>1week</code>, etc.</p>
+      and forget time-related bugs.
     </div>
   </div>
 </section>
@@ -209,7 +211,7 @@ console.log(await store.get(&quot;key1&quot;));
       </p>
       <p>
         <a class="pseudo button" href="/documentation#clients">
-          Documentation
+          Clients Docs
         </a>
       </p>
     </div>
@@ -233,26 +235,25 @@ const store6 = kv(yourOwnStore);</code></pre>
     <div class="content">
       <h2>🏖️ Clean and intuitive API</h2>
       <p>
-        A set of high-performance atomic operations with <code>.add()</code>,
+        A set of high-performance item operations with <code>.add()</code>,
         <code>.set()</code>, <code>.get()</code>, <code>.has()</code> or
-        <code>.del()</code>
+        <code>.del()</code>. We also provide group operations to manage your
+        data easily.
       </p>
       <p>
-        You can also work with all of entries with <code>.keys()</code>,
-        <code>.values()</code>, <code>.entries()</code>, <code>.all()</code> and
-        <code>.clear()</code>.
+        <a class="pseudo button" href="/documentation#api">API Docs</a>
       </p>
     </div>
   </div>
   <div>
-    <pre><code class="language-js">const key1 = await store.add(&quot;value2&quot;);
-const key2 = await store.set(&quot;key1&quot;, &quot;value1&quot;);
+    <pre><code class="language-js">import kv from "polystore";
+const store = kv(new Map());
+      
+const key1 = await store.add(&quot;value1&quot;);
+const key2 = await store.set(&quot;key2&quot;, &quot;value2&quot;);
+const val1 = await store.get(&quot;key1&quot;);
 const isthere = await store.has(&quot;key1&quot;);
-
-const allKeys = await store.keys();
-const allValues = await store.values();
-const obj = await store.all();
-// etc</code></pre>
+await store.del(key1);</code></pre>
   </div>
 </section>
 
@@ -261,28 +262,26 @@ const obj = await store.all();
     <div class="content">
       <h2>🛗 Create substores</h2>
       <p>
-        We include the `.prefix()` method to allow you to work with a subset of
-        items easily.
+        Create a new substore with <code>.prefix()</code>, then you can ignore
+        anything related to the prefix and treat it as if it was a brand new
+        store.
       </p>
       <p>
-        e.g. if you have a session store and want to create a subset of sessions
-        only for auth, you would do
-        <code>const auth = session.prefix('auth:');</code> and then use
-        <code>auth</code> like if it was an independent, KV store.
+        <a class="pseudo button" href="/documentation#substores"
+          >Substore Docs
+        </a>
       </p>
     </div>
   </div>
   <div>
-    <pre><code class="language-js">import kv from &quot;polystore&quot;;
-const store = kv(new Map());
+    <pre><code class="language-js">const session = store.prefix("session:");
+session.set("key1", "value1");
 
-const auth = store.prefix(&quot;auth:&quot;);
-auth.set(&quot;key1&quot;, &quot;value1&quot;);
-console.log(await auth.entries());
-// [[&quot;key1&quot;, &quot;value1&quot;]]
+console.log(await session.all());
+// { "key1": "value1" }
 
-console.log(await store.entries());
-// [[&quot;auth:key1&quot;, &quot;value1&quot;]]</code></pre>
+console.log(await store.all());
+// { "session:key1": "value1" }</code></pre>
   </div>
 </section>
 
@@ -293,10 +292,8 @@ console.log(await store.entries());
     <div class="content">
       <h2>⏰ Easy expiration time</h2>
       <p>
-        Unified expiration time so you can do
-        <code>{ expires: "1day" }</code> across ANY client. With polystore just
-        write in English and forget about calculating TTL, Unix time, seconds vs
-        milliseconds bugs, etc.
+        Simply write <code>{ expires: "1day" }</code> with ANY client and forget
+        about calculating TTL, Unix time, seconds vs milliseconds bugs, etc.
       </p>
       <p>
         <a class="pseudo button" href="/documentation#expiration-explained">

package/documentation.page.json

@@ -5,7 +5,6 @@
   "menu": {
     "Documentation": "/documentation",
     "Issues": "https://github.com/franciscop/polystore/issues",
-    "Contribute": "https://github.com/franciscop/polystore/blob/master/Contributing.md",
     "Get help": "https://superpeer.com/francisco/-/javascript-and-react-help",
     "Github": "https://github.com/franciscop/polystore"
   }

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "polystore",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "A small compatibility layer for many popular KV stores like localStorage, Redis, FileSystem, etc.",
-  "homepage": "https://github.com/franciscop/polystore",
+  "homepage": "https://polystore.dev/",
   "repository": "https://github.com/franciscop/polystore.git",
   "bugs": "https://github.com/franciscop/polystore/issues",
   "funding": "https://www.paypal.me/franciscopresencia/19",
   "author": "Francisco Presencia <public@francisco.io> (https://francisco.io/)",
   "main": "src/index.js",
   "type": "module",
+  "types": "src/index.d.ts",
   "scripts": {
     "size": "echo $(gzip -c src/index.js | wc -c) bytes",
     "start": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch --coverage --detectOpenHandles",
@@ -24,10 +25,10 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "check-dts": "^0.7.2",
+    "@deno/kv": "^0.8.1",
+    "check-dts": "^0.8.0",
     "dotenv": "^16.3.1",
     "edge-mock": "^0.0.15",
-    "esbuild": "^0.19.4",
     "etcd3": "^1.1.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
@@ -35,6 +36,17 @@
     "localforage": "^1.10.0",
     "redis": "^4.6.10"
   },
+  "documentation": {
+    "title": "🏬 Polystore - A universal library for standardizing any KV-store",
+    "home": "assets/home.html",
+    "homepage": "https://polystore.dev/",
+    "menu": {
+      "Documentation": "/documentation",
+      "Issues": "https://github.com/franciscop/polystore/issues",
+      "Get help": "https://superpeer.com/francisco/-/javascript-and-react-help",
+      "Github": "https://github.com/franciscop/polystore"
+    }
+  },
   "jest": {
     "testEnvironment": "jsdom",
     "setupFiles": [

package/readme.md

@@ -36,13 +36,13 @@ Available clients for the KV store:
 - [**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.
+- [**Level** `new Level('example', { valueEncoding: 'json' })`](#level) (fe+be): support the whole Level ecosystem
+- [**Etcd** `new Etcd3()`](#etcd) (be): 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:
+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, Bun 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:
 
 ```js
 import MyApi from "my-api";
@@ -54,6 +54,38 @@ MyApi({ cache: env.KV_NAMESPACE }); // OR
 // ...
 ```
 
+## Getting started
+
+First, install `polystore` and whatever [supported client](#clients) that you prefer. Let's see Redis as an example here:
+
+```
+npm i polystore redis
+```
+
+Then import both, initialize the Redis client and pass it to Polystore:
+
+```js
+import kv from "polystore";
+import { createClient } from "redis";
+
+// Import the Redis configuration
+const REDIS = process.env.REDIS_URL;
+
+// Wrap the redis creation with Polystore (kv())
+const store = kv(createClient(REDIS).connect());
+```
+
+Now your store is ready to use! Add, set, get, del different keys. [See full API](#api).
+
+```js
+const key = await store.add("Hello");
+
+console.log(await store.get(key));
+// Hello
+
+await store.del(key);
+```
+
 ## API
 
 See how to initialize each store [in the Clients list documentation](#clients). But basically for every store, it's like this:
@@ -79,7 +111,7 @@ client.connect();
 const store = kv(client);
 ```
 
-While you can keep a reference to the store and access it directly, we strongly recommend if you are going to use a store, to only access it through `polystore`, since we do add custom serialization and extra properties for e.g. expiration time:
+While you can keep a reference to the store and access it directly, we strongly recommend if you are going to use a store, to only access it through `polystore`, since we might add custom serialization and extra properties for e.g. expiration time:
 
 ```js
 const map = new Map();
@@ -175,11 +207,32 @@ Check whether the key is available in the store and not expired:
 ```js
 await store.has(key: string);
 
-if (await store.has('cookie-consent')) {
+if (await store.has("cookie-consent")) {
   loadCookies();
 }
 ```
 
+In many cases, internally the check for `.has()` is the same as `.get()`, so if you are going to use the value straight away it's usually better to just read it:
+
+```js
+const val = await store.get("key1");
+if (val) { ... }
+```
+
+An example of an exception of the above is when you use it as a cache, then you can write code like this:
+
+```js
+// First time for a given user does a network roundtrip, while
+// the second time for the same user gets it from cache
+async function fetchUser(id) {
+  if (!(await store.has(id))) {
+    const { data } = await axios.get(`/users/${id}`);
+    await store.set(id, data, { expires: "1h" });
+  }
+  return store.get(id);
+}
+```
+
 ### .del()
 
 Remove a single key from the store and return the key itself:
@@ -494,19 +547,19 @@ 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!
+> TL;DR: if you only use the item operations (add,set,get,has,del) and your client 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).
+**Expires** we polyfill expiration when the underlying client 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.
+**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 in the general case. 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)).
+> 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_. See [the notes in Performance](#performance) for details on how to work around this.
 
 We unify all of the clients diverse expiration methods into a single, easy one with `expires`:
 
@@ -551,7 +604,7 @@ For these and more situations, you can use `.prefix()` to simplify your life fur
 
 ## Creating a store
 
-To create a store, you define a class with these methods:
+To create a store, you define a class with these properties and methods:
 
 ```js
 class MyClient {
@@ -559,7 +612,7 @@ class MyClient {
   // the `.set()` and `.add()` receive a `expires` that is a `null` or `number`:
   EXPIRES = false;
 
-  // Mandatory methods (2 item-methods, 2 group-methods)
+  // Mandatory methods
   get (key): Promise<any>;
   set (key, value, { expires: null|number }): Promise<null>;
   entries (prefix): Promise<[string, any][]>;
@@ -579,7 +632,7 @@ class MyClient {
 }
 ```
 
-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.
+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. for the client, the `expires` will always be a `null` or `number`, never `undefined` or a `string`), but also it differs from polystore's public 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.
 
@@ -598,22 +651,15 @@ 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**:
+> Note: all of the _group methods_ that return keys, should return them **with the prefix**:
 
 ```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!
+  // Filter the keys, and return them INCLUDING the prefix!
+  return Object.keys(subStore).filter((key) => key.startsWith(prefix));
 };
 ```
 
-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**

package/src/index.d.ts

@@ -0,0 +1,181 @@
+type Options = { expires?: number | string | null };
+type Value = null | string | { [key: string]: Value } | Value[];
+
+interface Store {
+  /**
+   * Save the data on an autogenerated key, can add expiration as well:
+   *
+   * ```js
+   * const key1 = await store.add("value1");
+   * const key2 = await store.add({ hello: "world" });
+   * const key3 = await store.add("value3", { expires: "1h" });
+   * ```
+   *
+   * **[→ Full .add() Docs](https://polystore.dev/documentation#add)**
+   */
+  add: (value: Value, options?: Options) => Promise<string>;
+
+  /**
+   * Save the data on the given key, can add expiration as well:
+   *
+   * ```js
+   * const key = await store.set("key1", "value1");
+   * await store.set("key2", { hello: "world" });
+   * await store.set("key3", "value3", { expires: "1h" });
+   * ```
+   *
+   * **[→ Full .set() Docs](https://polystore.dev/documentation#set)**
+   */
+  set: (key: string, value: Value, options?: Options) => Promise<string>;
+
+  /**
+   * Read a single value from the KV store:
+   *
+   * ```js
+   * const value1 = await store.get("key1");
+   * // null (doesn't exist or has expired)
+   * const value2 = await store.get("key2");
+   * // "value2"
+   * const value3 = await store.get("key3");
+   * // { hello: "world" }
+   * ```
+   *
+   * **[→ Full .get() Docs](https://polystore.dev/documentation#get)**
+   */
+  get: (key: string) => Promise<Value>;
+
+  /**
+   * Check whether a key exists or not:
+   *
+   * ```js
+   * if (await store.has("key1")) { ... }
+   * ```
+   *
+   * If you are going to use the value, it's better to just read it:
+   *
+   * ```js
+   * const val = await store.get("key1");
+   * if (val) { ... }
+   * ```
+   *
+   *
+   * **[→ Full .has() Docs](https://polystore.dev/documentation#has)**
+   */
+  has: (key: string) => Promise<boolean>;
+
+  /**
+   * Remove a single key and its value from the store:
+   *
+   * ```js
+   * const key = await store.del("key1");
+   * ```
+   *
+   * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+   */
+  del: (key: string) => Promise<null>;
+
+  /**
+   * Return an array of the entries, in the [key, value] format:
+   *
+   * ```js
+   * const entries = await store.entries();
+   * // [["key1", "value1"], ["key2", { hello: "world" }], ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").entries();
+   * ```
+   *
+   * **[→ Full .entries() Docs](https://polystore.dev/documentation#entries)**
+   */
+  entries: () => Promise<[key: string, value: Value][]>;
+
+  /**
+   * Return an array of the keys in the store:
+   *
+   * ```js
+   * const keys = await store.keys();
+   * // ["key1", "key2", ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").keys();
+   * ```
+   *
+   * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
+   */
+  keys: () => Promise<string[]>;
+
+  /**
+   * Return an array of the values in the store:
+   *
+   * ```js
+   * const values = await store.values();
+   * // ["value1", { hello: "world" }, ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").values();
+   * ```
+   *
+   * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
+   */
+  values: () => Promise<Value[]>;
+
+  /**
+   * Return an object with the keys:values in the store:
+   *
+   * ```js
+   * const obj = await store.all();
+   * // { key1: "value1", key2: { hello: "world" }, ... }
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").all();
+   * ```
+   *
+   * **[→ Full .all() Docs](https://polystore.dev/documentation#all)**
+   */
+  all: () => Promise<{ [key: string]: Value }>;
+
+  /**
+   * Delete all of the records of the store:
+   *
+   * ```js
+   * await store.clear();
+   * ```
+   *
+   * It's useful for cache invalidation, clearing the data, and testing.
+   *
+   * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+   */
+  clear: () => Promise<null>;
+
+  /**
+   * Create a substore where all the keys are stored with
+   * the given prefix:
+   *
+   * ```js
+   * const session = store.prefix("session:");
+   * await session.set("key1", "value1");
+   * console.log(await session.entries());  // session.
+   * // [["key1", "value1"]]
+   * console.log(await store.entries());  // store.
+   * // [["session:key1", "value1"]]
+   * ```
+   *
+   * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+   */
+  prefix: (prefix: string) => Store;
+
+  /**
+   * Stop the connection to the store, if any:
+   *
+   * ```js
+   * await session.set("key1", "value1");
+   * await store.close();
+   * await session.set("key2", "value2");  // error
+   * ```
+   *
+   * **[→ Full .close() Docs](https://polystore.dev/documentation#close)**
+   */
+  close?: () => Promise<null>;
+}
+
+export default function (store?: any): Store;

package/src/index.js

@@ -1,32 +1,12 @@
-import clients from "./clients/index.js";
-import { createId, parse } from "./utils.js";
-
-function isClass(func) {
-  return (
-    typeof func === "function" &&
-    /^class\s/.test(Function.prototype.toString.call(func))
-  );
-}
-
-const getClient = (store) => {
-  // Already a fully compliant KV store
-  if (store instanceof Store) return store.client;
+/**
+ * A number, or a string containing a number.
+ * @typedef {(number|string|object|array)} Value
+ */
 
-  // One of the supported ones, so we receive an instance and
-  // wrap it with the client wrapper
-  for (let client of Object.values(clients)) {
-    if (client.test && client.test(store)) {
-      return new client(store);
-    }
-  }
-
-  // A raw one, we just receive the single instance to use directly
-  if (isClass(store)) {
-    return new store();
-  }
-  return store;
-};
+import clients from "./clients/index.js";
+import { createId, isClass, parse } from "./utils.js";
 
+// #region Store
 class Store {
   PREFIX = "";
 
@@ -34,14 +14,34 @@ class Store {
     this.promise = Promise.resolve(clientPromise).then(async (client) => {
       if (client?.open) await client.open();
       if (client?.connect) await client.connect();
-      client = getClient(client);
-      this.#validate(client);
-      this.client = client;
+      this.client = this.#find(client);
+      this.#validate(this.client);
       this.promise = null;
       return client;
     });
   }
 
+  // #region #client()
+  #find(store) {
+    // Already a fully compliant KV store
+    if (store instanceof Store) return store.client;
+
+    // One of the supported ones, so we receive an instance and
+    // wrap it with the client wrapper
+    for (let client of Object.values(clients)) {
+      if (client.test && client.test(store)) {
+        return new client(store);
+      }
+    }
+
+    // A raw one, we just receive the single instance to use directly
+    if (isClass(store)) {
+      return new store();
+    }
+    return store;
+  }
+
+  // #region #validate()
   #validate(client) {
     if (!client.set || !client.get || !client.entries) {
       throw new Error(
@@ -68,69 +68,104 @@ class Store {
     }
   }
 
-  async add(data, options = {}) {
+  // #region .add()
+  /**
+   * Save the data on an autogenerated key, can add expiration as well:
+   *
+   * ```js
+   * const key1 = await store.add("value1");
+   * const key2 = await store.add({ hello: "world" });
+   * const key3 = await store.add("value3", { expires: "1h" });
+   * ```
+   *
+   * **[→ Full .add() Docs](https://polystore.dev/documentation#add)**
+   * @param {Value} value
+   * @param {{ expires: string }} options
+   * @returns {Promise<string>}
+   */
+  async add(value, options = {}) {
     await this.promise;
     const expires = parse(options.expire ?? options.expires);
 
     // Use the underlying one from the client if found
     if (this.client.add) {
       if (this.client.EXPIRES) {
-        return this.client.add(this.PREFIX, data, { expires });
+        return this.client.add(this.PREFIX, value, { expires });
       }
 
       // In the data we need the timestamp since we need it "absolute":
       const now = new Date().getTime();
       const expDiff = expires === null ? null : now + expires * 1000;
-      return this.client.add(this.PREFIX, { expires: expDiff, value: data });
+      return this.client.add(this.PREFIX, { expires: expDiff, value });
     }
 
     const id = createId();
-    await this.set(id, data, { expires });
+    await this.set(id, value, { expires });
     return id; // The plain one without the prefix
   }
 
-  async set(id, data, options = {}) {
+  // #region .set()
+  /**
+   * Save the data on the given key, can add expiration as well:
+   *
+   * ```js
+   * const key = await store.set("key1", "value1");
+   * await store.set("key2", { hello: "world" });
+   * await store.set("key3", "value3", { expires: "1h" });
+   * ```
+   *
+   * **[→ Full .set() Docs](https://polystore.dev/documentation#set)**
+   * @param {string} key
+   * @param {Value} value
+   * @param {{ expires: string }} options
+   * @returns {Promise<string>}
+   */
+  async set(key, value, options = {}) {
     await this.promise;
-    const key = this.PREFIX + id;
+    const id = this.PREFIX + key;
     const expires = parse(options.expire ?? options.expires);
 
     // Quick delete
-    if (data === null) {
-      await this.del(key, null);
-      return id;
+    if (value === null) {
+      await this.del(id);
+      return key;
     }
 
     // The client manages the expiration, so let it manage it
     if (this.client.EXPIRES) {
-      await this.client.set(key, data, { expires });
-      return id;
+      await this.client.set(id, value, { expires });
+      return key;
     }
 
     // Already expired, then delete it
     if (expires === 0) {
       await this.del(id);
-      return id;
+      return key;
     }
 
     // In the data we need the timestamp since we need it "absolute":
     const now = new Date().getTime();
     const expDiff = expires === null ? null : now + expires * 1000;
-    await this.client.set(key, { expires: expDiff, value: data });
-    return id;
+    await this.client.set(id, { expires: expDiff, value });
+    return key;
   }
 
+  // #region .get()
   /**
    * Read a single value from the KV store:
    *
    * ```js
-   * const key = await store.set("key1", "value1");
-   * const value = await store.get("key1");
-   * // "value1"
+   * const value1 = await store.get("key1");
+   * // null (doesn't exist or has expired)
+   * const value2 = await store.get("key2");
+   * // "value2"
+   * const value3 = await store.get("key3");
+   * // { hello: "world" }
    * ```
    *
    * **[→ Full .get() Docs](https://polystore.dev/documentation#get)**
-   * @param {(string)} key
-   * @returns {(any)} value
+   * @param {string} key
+   * @returns {Promise<Value>}
    */
   async get(key) {
     await this.promise;
@@ -164,31 +199,78 @@ class Store {
     return value;
   }
 
-  async has(id) {
+  // #region .has()
+  /**
+   * Check whether a key exists or not:
+   *
+   * ```js
+   * if (await store.has("key1")) { ... }
+   * ```
+   *
+   * If you are going to use the value, it's better to just read it:
+   *
+   * ```js
+   * const val = await store.get("key1");
+   * if (val) { ... }
+   * ```
+   *
+   *
+   * **[→ Full .has() Docs](https://polystore.dev/documentation#has)**
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async has(key) {
     await this.promise;
-    const key = this.PREFIX + id;
+    const id = this.PREFIX + key;
 
     if (this.client.has) {
-      return this.client.has(key);
+      return this.client.has(id);
     }
 
     const value = await this.get(key);
     return value !== null;
   }
 
-  async del(id) {
+  // #region .del()
+  /**
+   * Remove a single key and its value from the store:
+   *
+   * ```js
+   * const key = await store.del("key1");
+   * ```
+   *
+   * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+   * @param {string} key
+   * @returns {Promise<string>}
+   */
+  async del(key) {
     await this.promise;
-    const key = this.PREFIX + id;
+    const id = this.PREFIX + key;
 
     if (this.client.del) {
-      await this.client.del(key);
-      return id;
+      await this.client.del(id);
+      return key;
     }
 
-    await this.client.set(key, null, { expires: 0 });
-    return id;
+    await this.client.set(id, null, { expires: 0 });
+    return key;
   }
 
+  // #region .entries()
+  /**
+   * Return an array of the entries, in the [key, value] format:
+   *
+   * ```js
+   * const entries = await store.entries();
+   * // [["key1", "value1"], ["key2", { hello: "world" }], ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").entries();
+   * ```
+   *
+   * **[→ Full .entries() Docs](https://polystore.dev/documentation#entries)**
+   * @returns {Promise<[string, Value][]>}
+   */
   async entries() {
     await this.promise;
 
@@ -225,6 +307,49 @@ class Store {
       .map(([key, data]) => [key, data.value]);
   }
 
+  // #region .keys()
+  /**
+   * Return an array of the keys in the store:
+   *
+   * ```js
+   * const keys = await store.keys();
+   * // ["key1", "key2", ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").keys();
+   * ```
+   *
+   * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
+   * @returns {Promise<string[]>}
+   */
+  async keys() {
+    await this.promise;
+
+    if (this.client.keys) {
+      const list = await this.client.keys(this.PREFIX);
+      if (!this.PREFIX) return list;
+      return list.map((k) => k.slice(this.PREFIX.length));
+    }
+
+    const entries = await this.entries();
+    return entries.map((e) => e[0]);
+  }
+
+  // #region .values()
+  /**
+   * Return an array of the values in the store:
+   *
+   * ```js
+   * const values = await store.values();
+   * // ["value1", { hello: "world" }, ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").values();
+   * ```
+   *
+   * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
+   * @returns {Promise<Value[]>}
+   */
   async values() {
     await this.promise;
 
@@ -255,19 +380,21 @@ class Store {
     return entries.map((e) => e[1]);
   }
 
-  async keys() {
-    await this.promise;
-
-    if (this.client.keys) {
-      const list = await this.client.keys(this.PREFIX);
-      if (!this.PREFIX) return list;
-      return list.map((k) => k.slice(this.PREFIX.length));
-    }
-
-    const entries = await this.entries();
-    return entries.map((e) => e[0]);
-  }
-
+  // #region .all()
+  /**
+   * Return an object with the keys:values in the store:
+   *
+   * ```js
+   * const obj = await store.all();
+   * // { key1: "value1", key2: { hello: "world" }, ... }
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").all();
+   * ```
+   *
+   * **[→ Full .all() Docs](https://polystore.dev/documentation#all)**
+   * @returns {Promise<{ [key:string]: Value }>}
+   */
   async all() {
     await this.promise;
 
@@ -285,6 +412,19 @@ class Store {
     return Object.fromEntries(entries);
   }
 
+  // #region .clear()
+  /**
+   * Delete all of the records of the store:
+   *
+   * ```js
+   * await store.clear();
+   * ```
+   *
+   * It's useful for cache invalidation, clearing the data, and testing.
+   *
+   * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+   * @returns {Promise<null>}
+   */
   async clear() {
     await this.promise;
 
@@ -294,9 +434,26 @@ class Store {
 
     const keys = await this.keys();
     // Note: this gives trouble of concurrent deletes in the FS
-    return await Promise.all(keys.map((key) => this.del(key)));
+    await Promise.all(keys.map((key) => this.del(key)));
   }
 
+  // #region .prefix()
+  /**
+   * Create a substore where all the keys are stored with
+   * the given prefix:
+   *
+   * ```js
+   * const session = store.prefix("session:");
+   * await session.set("key1", "value1");
+   * console.log(await session.entries());  // session.
+   * // [["key1", "value1"]]
+   * console.log(await store.entries());  // store.
+   * // [["session:key1", "value1"]]
+   * ```
+   *
+   * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+   * @returns {Store}
+   */
   prefix(prefix = "") {
     const store = new Store(
       Promise.resolve(this.promise).then((client) => client || this.client)
@@ -305,6 +462,19 @@ class Store {
     return store;
   }
 
+  // #region .close()
+  /**
+   * Stop the connection to the store, if any:
+   *
+   * ```js
+   * await session.set("key1", "value1");
+   * await store.close();
+   * await session.set("key2", "value2");  // error
+   * ```
+   *
+   * **[→ Full .close() Docs](https://polystore.dev/documentation#close)**
+   * @returns {Store}
+   */
   async close() {
     await this.promise;
 

package/src/index.test.js

@@ -7,7 +7,7 @@ import { Level } from "level";
 import localForage from "localforage";
 import { createClient } from "redis";
 
-import kv from "./";
+import kv from "./index.js";
 import customFull from "./test/customFull.js";
 import customSimple from "./test/customSimple.js";
 
@@ -113,7 +113,9 @@ for (let [name, store] of stores) {
 
     it("can perform a CRUD", async () => {
       expect(await store.get("a")).toBe(null);
+      expect(await store.has("a")).toBe(false);
       expect(await store.set("a", "b")).toBe("a");
+      expect(await store.has("a")).toBe(true);
       expect(await store.get("a")).toBe("b");
       expect(await store.del("a")).toBe("a");
       expect(await store.get("a")).toBe(null);
@@ -510,6 +512,12 @@ for (let [name, store] of stores) {
         expect(await store.get("session:a")).toBe("b");
       });
 
+      it("checks the has properly", async () => {
+        expect(await session.has("a")).toBe(false);
+        await session.set("a", "b");
+        expect(await session.has("a")).toBe(true);
+      });
+
       it("can add with the prefix", async () => {
         const id = await session.add("b");
         expect(id.length).toBe(24);

package/src/test/setup.js

@@ -2,11 +2,15 @@ import * as util from "util";
 
 // ref: https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom
 // ref: https://github.com/jsdom/jsdom/issues/2524
-Object.defineProperty(window, "TextEncoder", {
-  writable: true,
-  value: util.TextEncoder,
-});
-Object.defineProperty(window, "TextDecoder", {
-  writable: true,
-  value: util.TextDecoder,
-});
+if (typeof TextEncoder === "undefined") {
+  Object.defineProperty(window, "TextEncoder", {
+    writable: true,
+    value: util.TextEncoder,
+  });
+}
+if (typeof TextDecoder === "undefined") {
+  Object.defineProperty(window, "TextDecoder", {
+    writable: true,
+    value: util.TextDecoder,
+  });
+}

package/src/utils.js

@@ -10,7 +10,7 @@ parse.year = parse.yr = parse.y = parse.d * 365.25;
 parse.month = parse.b = parse.y / 12;
 
 // Returns the time in milliseconds
-function parse(str) {
+export function parse(str) {
   if (str === null || str === undefined) return null;
   if (typeof str === "number") return str;
   // ignore commas/placeholders
@@ -28,7 +28,7 @@ function parse(str) {
 const urlAlphabet =
   "useandom26T198340PX75pxJACKVERYMINDBUSHWOLFGQZbfghjklqvwyzrict";
 
-function createId() {
+export function createId() {
   let size = 24;
   let id = "";
   let bytes = crypto.getRandomValues(new Uint8Array(size));
@@ -41,4 +41,9 @@ function createId() {
   return id;
 }
 
-export { parse, createId };
+export function isClass(func) {
+  return (
+    typeof func === "function" &&
+    /^class\s/.test(Function.prototype.toString.call(func))
+  );
+}

package/src/indexa.d.ts

@@ -1,21 +0,0 @@
-type Key = string;
-type Options = { expires?: number | string | null };
-
-type Store = {
-  get: (key: Key) => Promise<any>;
-  add: (value: any, options?: Options) => Promise<Key>;
-  set: (key: Key, value: any, options?: Options) => Promise<Key>;
-  has: (key: Key) => Promise<boolean>;
-  del: (key: Key) => Promise<null>;
-
-  keys: () => Promise<string[]>;
-  values: () => Promise<any[]>;
-  entries: () => Promise<[key: string, value: any][]>;
-
-  prefix: (prefix: string) => Store;
-
-  clear: () => Promise<null>;
-  close?: () => Promise<null>;
-};
-
-export default function (store?: any): Store;