polystore 0.9.2 → 0.9.3

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>
@@ -209,7 +209,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 +233,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 +260,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 +290,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,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "A small compatibility layer for many popular KV stores like localStorage, Redis, FileSystem, etc.",
   "homepage": "https://github.com/franciscop/polystore",
   "repository": "https://github.com/franciscop/polystore.git",
@@ -9,6 +9,7 @@
   "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",

package/readme.md

@@ -175,11 +175,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:

package/src/{indexa.d.ts → index.d.ts}

@@ -1,12 +1,12 @@
-type Key = string;
 type Options = { expires?: number | string | null };
+type Value = null | string | { [key: string]: Value } | Value[];
 
 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>;
+  get: (key: string) => Promise<Value>;
+  add: (value: any, options?: Options) => Promise<string>;
+  set: (key: string, value: any, options?: Options) => Promise<string>;
+  has: (key: string) => Promise<boolean>;
+  del: (key: string) => Promise<null>;
 
   keys: () => Promise<string[]>;
   values: () => Promise<any[]>;

package/src/index.js

@@ -1,32 +1,7 @@
 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;
-
-  // 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 { createId, isClass, parse } from "./utils.js";
 
+// #region Store
 class Store {
   PREFIX = "";
 
@@ -34,14 +9,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 +63,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 (it doesn't exist, or it 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 +194,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 +302,21 @@ class Store {
       .map(([key, data]) => [key, data.value]);
   }
 
+  // #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,6 +347,21 @@ 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;
 
@@ -268,6 +375,21 @@ class Store {
     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 +407,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 +429,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 +457,7 @@ class Store {
     return store;
   }
 
+  // #region .close()
   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/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))
+  );
+}