polystore 0.9.3 → 0.11.0

package/assets/home.html

@@ -14,7 +14,7 @@
       <a
         class="pseudo button"
         href="https://superpeer.com/francisco/-/javascript-and-react-help"
-        >Professional JS help</a
+        >Get JS help</a
       >
     </div>
   </div>
@@ -77,7 +77,8 @@ console.log(await store.get(key));
         <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(key));
       <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>
@@ -179,7 +180,10 @@ console.log(await store.get(key));
         </svg>
         <h3>Intuitive expirations</h3>
       </header>
-      <p>Write the expiration as <code>100s</code>, <code>1week</code>, etc.</p>
+      <p>
+        Write the expiration as <code>100s</code>, <code>1week</code>, etc. and
+        forget time-related bugs.
+      </p>
     </div>
   </div>
 </section>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "polystore",
-  "version": "0.9.3",
+  "version": "0.11.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",
@@ -24,11 +24,12 @@
     "value"
   ],
   "license": "MIT",
+  "dependencies": {},
   "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",
@@ -36,6 +37,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();
@@ -209,6 +241,26 @@ Remove a single key from the store and return the key itself:
 await store.del(key: string);
 ```
 
+It will ignore the operation if the key or value don't exist already (but won't thorw).
+
+### _Iterator_
+
+You can iterate over the whole store with an async iterator:
+
+```js
+for await (const [key, value] of store) {
+  // ...
+}
+```
+
+This is very useful for performance resons. You can also iterate on a subset of the entries with .prefix:
+
+```js
+for await (const [key, value] of store.prefix("session:")) {
+  // ...
+}
+```
+
 ### .keys()
 
 Get all of the keys in the store, optionally filtered by a prefix:
@@ -515,19 +567,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`:
 
@@ -572,7 +624,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 {
@@ -580,10 +632,10 @@ 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][]>;
+  iterate(prefix): AyncIterator<[string, any]>
 
   // Optional item methods (for optimization or customization)
   add (prefix, data, { expires: null|number }): Promise<string>;
@@ -591,6 +643,7 @@ class MyClient {
   del (key): Promise<null>;
 
   // Optional group methods
+  entries (prefix): Promise<[string, any][]>;
   keys (prefix): Promise<string[]>;
   values (prefix): Promise<any[]>;
   clear (prefix): Promise<null>;
@@ -600,7 +653,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.
 
@@ -615,26 +668,20 @@ 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:");
+for await (const entry of store.iterate()) {
+}
+// client.iterate("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**
@@ -655,10 +702,12 @@ class MyClient {
   }
 
   // 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));
+  *iterate(prefix) {
+    for (const [key, value] of Object.entries(dataSource)) {
+      if (key.startsWith(prefix)) {
+        yield [key, value];
+      }
+    }
   }
 }
 ```

package/src/clients/cloudflare.js

@@ -31,9 +31,33 @@ export default class Cloudflare {
     return this.client.delete(key);
   }
 
+  // Since we have pagination, we don't want to get all of the
+  // keys at once if we can avoid it
+  async *iterate(prefix = "") {
+    let cursor;
+    do {
+      const raw = await this.client.list({ prefix, cursor });
+      const keys = raw.keys.map((k) => k.name);
+      for (let key of keys) {
+        const value = await this.get(key);
+        // By the time this specific value is read, it could
+        // already be gone!
+        if (!value) continue;
+        yield [key, value];
+      }
+      cursor = raw.list_complete ? null : raw.cursor;
+    } while (cursor);
+  }
+
   async keys(prefix = "") {
-    const raw = await this.client.list({ prefix });
-    return raw.keys.map((k) => k.name);
+    const keys = [];
+    let cursor;
+    do {
+      const raw = await this.client.list({ prefix, cursor });
+      keys.push(...raw.keys.map((k) => k.name));
+      cursor = raw.list_complete ? null : raw.cursor;
+    } while (cursor);
+    return keys;
   }
 
   async entries(prefix = "") {

package/src/clients/cookie.js

@@ -8,9 +8,25 @@ export default class Cookie {
     return client === "cookie" || client === "cookies";
   }
 
+  // Group methods
+  #read() {
+    const all = {};
+    for (let entry of document.cookie.split(";")) {
+      try {
+        const [rawKey, rawValue] = entry.split("=");
+        const key = decodeURIComponent(rawKey.trim());
+        const value = JSON.parse(decodeURIComponent(rawValue.trim()));
+        all[key] = value;
+      } catch (error) {
+        // no-op (some 3rd party can set cookies independently)
+      }
+    }
+    return all;
+  }
+
   // For cookies, an empty value is the same as null, even `""`
   get(key) {
-    return this.all()[key] || null;
+    return this.#read()[key] || null;
   }
 
   set(key, data = null, { expires } = {}) {
@@ -33,23 +49,10 @@ export default class Cookie {
     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)
-      }
+  async *iterate(prefix = "") {
+    for (let [key, value] of Object.entries(this.#read())) {
+      if (!key.startsWith(prefix)) continue;
+      yield [key, value];
     }
-    return all;
-  }
-
-  entries(prefix = "") {
-    return Object.entries(this.all(prefix));
   }
 }

package/src/clients/etcd.js

@@ -21,6 +21,13 @@ export default class Etcd {
     await this.client.put(key).value(JSON.stringify(value));
   }
 
+  async *iterate(prefix = "") {
+    const keys = await this.client.getAll().prefix(prefix).keys();
+    for (const key of keys) {
+      yield [key, await this.get(key)];
+    }
+  }
+
   async entries(prefix = "") {
     const keys = await this.client.getAll().prefix(prefix).keys();
     const values = await Promise.all(keys.map((k) => this.get(k)));

package/src/clients/file.js

@@ -53,10 +53,12 @@ export default class File {
     return key;
   }
 
-  // Group methods
-  async entries(prefix = "") {
+  async *iterate(prefix = "") {
     const data = await this.#read();
-    return Object.entries(data).filter((p) => p[0].startsWith(prefix));
+    const entries = Object.entries(data).filter((p) => p[0].startsWith(prefix));
+    for (const entry of entries) {
+      yield entry;
+    }
   }
 
   async clear(prefix = "") {

package/src/clients/forage.js

@@ -22,12 +22,18 @@ export default class Forage {
     return key;
   }
 
+  async *iterate(prefix = "") {
+    const keys = await this.client.keys();
+    const list = keys.filter((k) => k.startsWith(prefix));
+    for (const key of list) {
+      yield [key, await this.get(key)];
+    }
+  }
+
   async entries(prefix = "") {
     const all = await this.client.keys();
     const keys = all.filter((k) => k.startsWith(prefix));
-    const values = await Promise.all(
-      keys.map((key) => this.client.getItem(key))
-    );
+    const values = await Promise.all(keys.map((key) => this.get(key)));
     return keys.map((key, i) => [key, values[i]]);
   }
 

package/src/clients/level.js

@@ -26,6 +26,14 @@ export default class Level {
     return this.client.del(key);
   }
 
+  async *iterate(prefix = "") {
+    const keys = await this.client.keys().all();
+    const list = keys.filter((k) => k.startsWith(prefix));
+    for (const key of list) {
+      yield [key, await this.get(key)];
+    }
+  }
+
   async entries(prefix = "") {
     const keys = await this.client.keys().all();
     const list = keys.filter((k) => k.startsWith(prefix));

package/src/clients/memory.js

@@ -21,6 +21,14 @@ export default class Memory {
     this.client.delete(key);
   }
 
+  *iterate(prefix = "") {
+    const entries = this.entries();
+    for (const entry of entries) {
+      if (!entry[0].startsWith(prefix)) continue;
+      yield entry;
+    }
+  }
+
   // Group methods
   entries(prefix = "") {
     const entries = [...this.client.entries()];

package/src/clients/redis.js

@@ -37,12 +37,33 @@ export default class Redis {
     return this.client.keys(prefix + "*");
   }
 
+  // Go through each of the [key, value] in the set
+  async *iterate(prefix = "") {
+    const MATCH = prefix + "*";
+    for await (const key of this.client.scanIterator({ MATCH })) {
+      const value = await this.get(key);
+      yield [key, value];
+    }
+  }
+
+  // Optimizing the retrieval of them all in bulk by loading the values
+  // in parallel
   async entries(prefix = "") {
-    const keys = await this.client.keys(prefix + "*");
+    const keys = await this.keys(prefix);
     const values = await Promise.all(keys.map((k) => this.get(k)));
     return keys.map((k, i) => [k, values[i]]);
   }
 
+  // Optimizing the retrieval of them by not getting their values
+  async keys(prefix = "") {
+    const MATCH = prefix + "*";
+    const keys = [];
+    for await (const key of this.client.scanIterator({ MATCH })) {
+      keys.push(key);
+    }
+    return keys;
+  }
+
   async clear(prefix = "") {
     if (!prefix) return this.client.flushAll();
 

package/src/clients/storage.js

@@ -25,6 +25,13 @@ export default class WebStorage {
     return key;
   }
 
+  *iterate(prefix = "") {
+    const entries = this.entries(prefix);
+    for (const entry of entries) {
+      yield entry;
+    }
+  }
+
   // Group methods
   entries(prefix = "") {
     const entries = Object.entries(this.client);

package/src/index.d.ts

@@ -1,21 +1,181 @@
 type Options = { expires?: number | string | null };
 type Value = null | string | { [key: string]: Value } | Value[];
 
-type Store = {
+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>;
-  add: (value: any, options?: Options) => Promise<string>;
-  set: (key: string, value: any, options?: Options) => Promise<string>;
+
+  /**
+   * 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[]>;
-  values: () => Promise<any[]>;
-  entries: () => Promise<[key: string, value: any][]>;
 
-  prefix: (prefix: string) => Store;
+  /**
+   * 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,3 +1,8 @@
+/**
+ * A number, or a string containing a number.
+ * @typedef {(number|string|object|array)} Value
+ */
+
 import clients from "./clients/index.js";
 import { createId, isClass, parse } from "./utils.js";
 
@@ -38,9 +43,9 @@ class Store {
 
   // #region #validate()
   #validate(client) {
-    if (!client.set || !client.get || !client.entries) {
+    if (!client.set || !client.get || !client.iterate) {
       throw new Error(
-        "A client should have at least a .get(), .set() and .entries()"
+        "A client should have at least a .get(), .set() and .iterate()"
       );
     }
 
@@ -63,6 +68,31 @@ class Store {
     }
   }
 
+  #unix(expires) {
+    const now = new Date().getTime();
+    return expires === null ? null : now + expires * 1000;
+  }
+
+  // Check if the given data is fresh or not; if
+  #isFresh(data, key) {
+    // Should never happen, but COULD happen; schedule it for
+    // removal and mark it as stale
+    if (!data || !data.value || typeof data !== "object") {
+      if (key) this.del(key);
+      return false;
+    }
+
+    // It never expires, so keep it
+    if (data.expires === null) return true;
+
+    // It's fresh, keep it
+    if (data.expires > Date.now()) return true;
+
+    // It's expired, remove it
+    if (key) this.del(key);
+    return false;
+  }
+
   // #region .add()
   /**
    * Save the data on an autogenerated key, can add expiration as well:
@@ -89,9 +119,10 @@ class Store {
       }
 
       // 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 });
+      return this.client.add(this.PREFIX, {
+        expires: this.#unix(expires),
+        value,
+      });
     }
 
     const id = createId();
@@ -121,7 +152,7 @@ class Store {
     const expires = parse(options.expire ?? options.expires);
 
     // Quick delete
-    if (value === null) {
+    if (value === null || (typeof expires === "number" && expires <= 0)) {
       await this.del(id);
       return key;
     }
@@ -132,16 +163,8 @@ class Store {
       return key;
     }
 
-    // Already expired, then delete it
-    if (expires === 0) {
-      await this.del(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(id, { expires: expDiff, value });
+    await this.client.set(id, { expires: this.#unix(expires), value });
     return key;
   }
 
@@ -151,7 +174,7 @@ class Store {
    *
    * ```js
    * const value1 = await store.get("key1");
-   * // null (it doesn't exist, or it has expired)
+   * // null (doesn't exist or has expired)
    * const value2 = await store.get("key2");
    * // "value2"
    * const value3 = await store.get("key3");
@@ -175,23 +198,8 @@ class Store {
     // so we can assume it's the raw user data
     if (this.client.EXPIRES) return data;
 
-    // Make sure that if there's no data by now, empty is returned
-    if (!data) return null;
-
-    // We manage expiration manually, so we know it should have this structure
-    // TODO: ADD A CHECK HERE
-    const { expires, value } = data;
-
-    // It never expires
-    if (expires === null) return value ?? null;
-
-    // Already expired! Return nothing, and remove the whole key
-    if (expires <= new Date().getTime()) {
-      await this.del(key);
-      return null;
-    }
-
-    return value;
+    if (!this.#isFresh(data, key)) return null;
+    return data.value;
   }
 
   // #region .has()
@@ -251,6 +259,19 @@ class Store {
     return key;
   }
 
+  async *[Symbol.asyncIterator]() {
+    await this.promise;
+
+    for await (const [name, data] of this.client.iterate(this.PREFIX)) {
+      const key = name.slice(this.PREFIX.length);
+      if (this.client.EXPIRES) {
+        yield [key, data];
+      } else if (this.#isFresh(data, key)) {
+        yield [key, data.value];
+      }
+    }
+  }
+
   // #region .entries()
   /**
    * Return an array of the entries, in the [key, value] format:
@@ -269,110 +290,84 @@ class Store {
   async entries() {
     await this.promise;
 
-    const entries = await this.client.entries(this.PREFIX);
-    const list = entries.map(([key, data]) => [
-      key.slice(this.PREFIX.length),
-      data,
-    ]);
+    let list = [];
+    if (this.client.entries) {
+      list = (await this.client.entries(this.PREFIX)).map(([key, value]) => [
+        key.slice(this.PREFIX.length),
+        value,
+      ]);
+    } else {
+      for await (const [key, value] of this.client.iterate(this.PREFIX)) {
+        list.push([key.slice(this.PREFIX.length), value]);
+      }
+    }
 
     // The client already manages the expiration, so we can assume
     // that at this point, all entries are not-expired
     if (this.client.EXPIRES) return list;
 
     // We need to do manual expiration checking
-    const now = new Date().getTime();
     return list
-      .filter(([key, data]) => {
-        // Should never happen
-        if (!data || data.value === null) return false;
-
-        // It never expires, so keep it
-        const { expires } = data;
-        if (expires === null) return true;
-
-        // It's expired, so remove it
-        if (expires <= now) {
-          this.del(key);
-          return false;
-        }
-
-        // It's not expired, keep it
-        return true;
-      })
+      .filter(([key, data]) => this.#isFresh(data, key))
       .map(([key, data]) => [key, data.value]);
   }
 
-  // #region .values()
+  // #region .keys()
   /**
-   * Return an array of the values in the store:
+   * Return an array of the keys in the store:
    *
    * ```js
-   * const values = await store.values();
-   * // ["value1", { hello: "world" }, ...]
+   * const keys = await store.keys();
+   * // ["key1", "key2", ...]
    *
    * // To limit it to a given prefix, use `.prefix()`:
-   * const sessions = await store.prefix("session:").values();
+   * const sessions = await store.prefix("session:").keys();
    * ```
    *
-   * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
-   * @returns {Promise<Value[]>}
+   * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
+   * @returns {Promise<string[]>}
    */
-  async values() {
+  async keys() {
     await this.promise;
 
-    if (this.client.values) {
-      const list = this.client.values(this.PREFIX);
-      if (this.client.EXPIRES) return list;
-      const now = new Date().getTime();
-      return list
-        .filter((data) => {
-          // There's no data, so remove this
-          if (!data || data.value === null) return false;
-
-          // It never expires, so keep it
-          const { expires } = data;
-          if (expires === null) return true;
-
-          // It's expired, so remove it
-          // We cannot unfortunately evict it since we don't know the key!
-          if (expires <= now) return false;
-
-          // It's not expired, keep it
-          return true;
-        })
-        .map((data) => data.value);
+    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[1]);
+    return entries.map((e) => e[0]);
   }
 
-  // #region .keys()
+  // #region .values()
   /**
-   * Return an array of the keys in the store:
+   * Return an array of the values in the store:
    *
    * ```js
-   * const keys = await store.keys();
-   * // ["key1", "key2", ...]
+   * const values = await store.values();
+   * // ["value1", { hello: "world" }, ...]
    *
    * // To limit it to a given prefix, use `.prefix()`:
-   * const sessions = await store.prefix("session:").keys();
+   * const sessions = await store.prefix("session:").values();
    * ```
    *
-   * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
-   * @returns {Promise<string[]>}
+   * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
+   * @returns {Promise<Value[]>}
    */
-  async keys() {
+  async values() {
     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));
+    if (this.client.values) {
+      const list = this.client.values(this.PREFIX);
+      if (this.client.EXPIRES) return list;
+      return list
+        .filter((data) => this.#isFresh(data))
+        .map((data) => data.value);
     }
 
     const entries = await this.entries();
-    return entries.map((e) => e[0]);
+    return entries.map((e) => e[1]);
   }
 
   // #region .all()
@@ -458,6 +453,18 @@ class 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

@@ -11,8 +11,6 @@ import kv from "./index.js";
 import customFull from "./test/customFull.js";
 import customSimple from "./test/customSimple.js";
 
-global.setImmediate = global.setImmediate || ((cb) => setTimeout(cb, 0));
-
 const stores = [];
 stores.push(["kv()", kv()]);
 stores.push(["kv(new Map())", kv(new Map())]);
@@ -30,6 +28,7 @@ if (process.env.REDIS) {
   stores.push(["kv(redis)", kv(createClient())]);
 }
 if (process.env.ETCD) {
+  // Note: need to add to .env "ETCD=true" and run `etcd` in the terminal
   stores.push(["kv(new Etcd3())", kv(new Etcd3())]);
 }
 
@@ -41,7 +40,7 @@ const delay = (t) => new Promise((done) => setTimeout(done, t));
 class Base {
   get() {}
   set() {}
-  entries() {}
+  *iterate() {}
 }
 
 global.console = {
@@ -56,7 +55,7 @@ describe("potato", () => {
 
   it("an empty object is not a valid store", async () => {
     await expect(() => kv({}).get("any")).rejects.toThrow({
-      message: "A client should have at least a .get(), .set() and .entries()",
+      message: "A client should have at least a .get(), .set() and .iterate()",
     });
   });
 
@@ -343,6 +342,42 @@ for (let [name, store] of stores) {
       expect(await store.get("a")).toBe("b");
     });
 
+    describe("iteration", () => {
+      beforeEach(async () => {
+        await store.clear();
+      });
+
+      it("supports raw iteration", async () => {
+        await store.set("a", "b");
+        await store.set("c", "d");
+
+        const entries = [];
+        for await (const entry of store) {
+          entries.push(entry);
+        }
+        expect(entries).toEqual([
+          ["a", "b"],
+          ["c", "d"],
+        ]);
+      });
+
+      it("supports raw prefix iteration", async () => {
+        await store.set("a:a", "b");
+        await store.set("b:a", "d");
+        await store.set("a:c", "d");
+        await store.set("b:c", "d");
+
+        const entries = [];
+        for await (const entry of store.prefix("a:")) {
+          entries.push(entry);
+        }
+        expect(entries.sort()).toEqual([
+          ["a", "b"],
+          ["c", "d"],
+        ]);
+      });
+    });
+
     describe("expires", () => {
       // The mock implementation does NOT support expiration 😪
       if (name === "kv(new KVNamespace())") return;

package/src/test/customFull.js

@@ -19,6 +19,13 @@ export default class MyClient {
     delete dataSource[key];
   }
 
+  *iterate(prefix) {
+    const entries = this.entries(prefix);
+    for (const entry of entries) {
+      yield entry;
+    }
+  }
+
   // Filter them by the prefix, note that `prefix` will always be a string
   entries(prefix) {
     const entries = Object.entries(dataSource);

package/src/test/customSimple.js

@@ -15,9 +15,13 @@ export default class MyClient {
   }
 
   // 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));
+  *iterate(prefix) {
+    const raw = Object.entries(dataSource);
+    const entries = prefix
+      ? raw.filter(([key, value]) => key.startsWith(prefix))
+      : raw;
+    for (const entry of entries) {
+      yield entry;
+    }
   }
 }

package/src/test/setup.js

@@ -2,11 +2,22 @@ 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,
+  });
+}
+
+if (typeof setImmediate === "undefined") {
+  Object.defineProperty(window, "setImmediate", {
+    writable: true,
+    value: (cb) => setTimeout(cb, 0),
+  });
+}