polystore 0.9.3 → 0.10.0

package/assets/home.html

@@ -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>
@@ -180,6 +181,7 @@ console.log(await store.get(key));
         <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>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "polystore",
-  "version": "0.9.3",
+  "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",
@@ -25,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",
@@ -36,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();
@@ -515,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`:
 
@@ -572,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 {
@@ -580,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][]>;
@@ -600,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.
 
@@ -619,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

@@ -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";
 
@@ -151,7 +156,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");
@@ -302,6 +307,34 @@ 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:
@@ -347,34 +380,6 @@ class Store {
     return entries.map((e) => e[1]);
   }
 
-  // #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 .all()
   /**
    * Return an object with the keys:values in the store:
@@ -458,6 +463,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/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,
+  });
+}