polystore 0.11.3 → 0.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "A small compatibility layer for many popular KV stores like localStorage, Redis, FileSystem, etc.",
   "homepage": "https://polystore.dev/",
   "repository": "https://github.com/franciscop/polystore.git",

package/readme.md

@@ -249,18 +249,29 @@ You can iterate over the whole store with an async iterator:
 
 ```js
 for await (const [key, value] of store) {
-  // ...
+  console.log(key, value);
 }
 ```
 
-This is very useful for performance resons. You can also iterate on a subset of the entries with .prefix:
+This is very useful for performance resons since it will retrieve the data sequentially, avoiding blocking the client while retrieving it all at once. The main disadvantage is if you keep writing data while the async iterator is running.
+
+You can also iterate on a subset of the entries with `.prefix()` (the prefix is stripped from the key here, see [.`prefix()`](#prefix)):
 
 ```js
+const session = store.prefix("session:");
+for await (const [key, value] of session) {
+  console.log(key, value);
+}
+
+// Same as this (both have the prefix stripped):
+
 for await (const [key, value] of store.prefix("session:")) {
-  // ...
+  console.log(key, value);
 }
 ```
 
+There are also methods to retrieve all of the keys, values, or entries at once below, but those [have worse performance](#performance).
+
 ### .keys()
 
 Get all of the keys in the store, optionally filtered by a prefix:

package/src/clients/cloudflare.js

@@ -23,8 +23,7 @@ export default class Cloudflare {
 
   async set(key, value, { expires } = {}) {
     const expirationTtl = expires ? Math.round(expires) : undefined;
-    this.client.put(key, JSON.stringify(value), { expirationTtl });
-    return key;
+    return this.client.put(key, JSON.stringify(value), { expirationTtl });
   }
 
   async del(key) {
@@ -40,8 +39,7 @@ export default class Cloudflare {
       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!
+        // By the time this specific value is read, it could be gone!
         if (!value) continue;
         yield [key, value];
       }
@@ -63,7 +61,7 @@ export default class Cloudflare {
   async entries(prefix = "") {
     const keys = await this.keys(prefix);
     const values = await Promise.all(keys.map((k) => this.get(k)));
-    return keys.map((key, i) => [key, values[i]]);
+    return keys.map((k, i) => [k, values[i]]);
   }
 
   async clear(prefix = "") {

package/src/clients/cookie.js

@@ -31,22 +31,19 @@ export default class Cookie {
 
   set(key, data = null, { expires } = {}) {
     // Setting it to null deletes it
-    if (data === null) {
-      data = "";
-      expires = -100;
-    }
-
     let expireStr = "";
     // NOTE: 0 is already considered here!
     if (expires !== null) {
-      const now = new Date().getTime();
-      const time = new Date(now + expires * 1000).toUTCString();
+      const time = new Date(Date.now() + expires * 1000).toUTCString();
       expireStr = `; expires=${time}`;
     }
 
-    const value = encodeURIComponent(JSON.stringify(data));
+    const value = encodeURIComponent(JSON.stringify(data || ""));
     document.cookie = encodeURIComponent(key) + "=" + value + expireStr;
-    return key;
+  }
+
+  del(key) {
+    this.set(key, "", { expires: -100 });
   }
 
   async *iterate(prefix = "") {

package/src/clients/etcd.js

@@ -14,11 +14,11 @@ export default class Etcd {
   }
 
   async set(key, value) {
-    if (value === null) {
-      return this.client.delete().key(key).exec();
-    }
+    return this.client.put(key).value(JSON.stringify(value));
+  }
 
-    await this.client.put(key).value(JSON.stringify(value));
+  async del(key) {
+    return this.client.delete().key(key).exec();
   }
 
   async *iterate(prefix = "") {
@@ -28,19 +28,18 @@ export default class Etcd {
     }
   }
 
+  async keys(prefix = "") {
+    return this.client.getAll().prefix(prefix).keys();
+  }
+
   async entries(prefix = "") {
-    const keys = await this.client.getAll().prefix(prefix).keys();
+    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]]);
   }
 
   async clear(prefix = "") {
     if (!prefix) return this.client.delete().all();
-
     return this.client.delete().prefix(prefix);
   }
-
-  async close() {
-    // return this.client.close();
-  }
 }

package/src/clients/forage.js

@@ -14,12 +14,11 @@ export default class Forage {
   }
 
   async set(key, value) {
-    if (value === null) {
-      await this.client.removeItem(key);
-    } else {
-      await this.client.setItem(key, value);
-    }
-    return key;
+    return this.client.setItem(key, value);
+  }
+
+  async del(key) {
+    return this.client.removeItem(key);
   }
 
   async *iterate(prefix = "") {

package/src/clients/memory.js

@@ -14,33 +14,27 @@ export default class Memory {
   }
 
   set(key, data) {
-    this.client.set(key, data);
+    return this.client.set(key, data);
   }
 
   del(key) {
-    this.client.delete(key);
+    return this.client.delete(key);
   }
 
   *iterate(prefix = "") {
-    const entries = this.entries();
-    for (const entry of entries) {
+    for (const entry of this.client.entries()) {
       if (!entry[0].startsWith(prefix)) continue;
       yield entry;
     }
   }
 
-  // Group methods
-  entries(prefix = "") {
-    const entries = [...this.client.entries()];
-    return entries.filter((p) => p[0].startsWith(prefix));
-  }
-
   clear(prefix = "") {
     // Delete the whole dataset
     if (!prefix) return this.client.clear();
 
     // Delete them in a map
-    const list = this.entries(prefix);
-    return Promise.all(list.map((e) => e[0]).map((k) => this.del(k)));
+    return [...this.client.keys()]
+      .filter((k) => k.startsWith(prefix))
+      .map((k) => this.del(k));
   }
 }

package/src/clients/redis.js

@@ -19,13 +19,12 @@ export default class Redis {
   }
 
   async set(key, value, { expires } = {}) {
-    if (value === null || expires === 0) {
-      return this.client.del(key);
-    }
-
     const EX = expires ? Math.round(expires) : undefined;
-    await this.client.set(key, JSON.stringify(value), { EX });
-    return key;
+    return this.client.set(key, JSON.stringify(value), { EX });
+  }
+
+  async del(key) {
+    return this.client.del(key);
   }
 
   async has(key) {
@@ -42,6 +41,8 @@ export default class Redis {
     const MATCH = prefix + "*";
     for await (const key of this.client.scanIterator({ MATCH })) {
       const value = await this.get(key);
+      // By the time this specific value is read, it could be gone!
+      if (!value) continue;
       yield [key, value];
     }
   }
@@ -68,7 +69,7 @@ export default class Redis {
     if (!prefix) return this.client.flushAll();
 
     const list = await this.keys(prefix);
-    return Promise.all(list.map((k) => this.set(k, null)));
+    return Promise.all(list.map((k) => this.client.del(k)));
   }
 
   async close() {

package/src/clients/storage.js

@@ -17,27 +17,20 @@ export default class WebStorage {
   }
 
   set(key, data) {
-    if (data === null) {
-      this.client.removeItem(key);
-    } else {
-      this.client.setItem(key, JSON.stringify(data));
-    }
-    return key;
+    return this.client.setItem(key, JSON.stringify(data));
   }
 
-  *iterate(prefix = "") {
-    const entries = this.entries(prefix);
-    for (const entry of entries) {
-      yield entry;
-    }
+  del(key) {
+    return this.client.removeItem(key);
   }
 
-  // Group methods
-  entries(prefix = "") {
-    const entries = Object.entries(this.client);
-    return entries
-      .map((p) => [p[0], p[1] ? JSON.parse(p[1]) : null])
-      .filter((p) => p[0].startsWith(prefix));
+  *iterate(prefix = "") {
+    for (const key of Object.keys(this.client)) {
+      if (!key.startsWith(prefix)) continue;
+      const value = this.get(key);
+      if (!value) continue;
+      yield [key, value];
+    }
   }
 
   clear(prefix = "") {
@@ -45,6 +38,8 @@ export default class WebStorage {
     if (!prefix) return this.client.clear();
 
     // Delete them in a map
-    return this.entries(prefix).map((e) => this.set(e[0], null));
+    return Object.keys(this.client)
+      .filter((k) => k.startsWith(prefix))
+      .map((k) => this.del(k));
   }
 }

package/src/index.d.ts

@@ -1,7 +1,7 @@
-type Options = { expires?: number | string | null };
-type Value = null | string | { [key: string]: Value } | Value[];
+export type Options = { expires?: number | string | null };
+export type Value = string | { [key: string]: Value } | Value[];
 
-interface Store {
+export interface Store {
   /**
    * Save the data on an autogenerated key, can add expiration as well:
    *
@@ -13,7 +13,7 @@ interface Store {
    *
    * **[→ Full .add() Docs](https://polystore.dev/documentation#add)**
    */
-  add: (value: Value, options?: Options) => Promise<string>;
+  add: <T = Value>(value: T, options?: Options) => Promise<string>;
 
   /**
    * Save the data on the given key, can add expiration as well:
@@ -26,7 +26,7 @@ interface Store {
    *
    * **[→ Full .set() Docs](https://polystore.dev/documentation#set)**
    */
-  set: (key: string, value: Value, options?: Options) => Promise<string>;
+  set: <T = Value>(key: string, value: T, options?: Options) => Promise<string>;
 
   /**
    * Read a single value from the KV store:
@@ -42,7 +42,7 @@ interface Store {
    *
    * **[→ Full .get() Docs](https://polystore.dev/documentation#get)**
    */
-  get: (key: string) => Promise<Value>;
+  get: <T = Value>(key: string) => Promise<T | null>;
 
   /**
    * Check whether a key exists or not:
@@ -72,7 +72,7 @@ interface Store {
    *
    * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
    */
-  del: (key: string) => Promise<null>;
+  del: (key: string) => Promise<string>;
 
   /**
    * Return an array of the entries, in the [key, value] format:
@@ -87,7 +87,7 @@ interface Store {
    *
    * **[→ Full .entries() Docs](https://polystore.dev/documentation#entries)**
    */
-  entries: () => Promise<[key: string, value: Value][]>;
+  entries: <T = Value>() => Promise<[key: string, value: T][]>;
 
   /**
    * Return an array of the keys in the store:
@@ -117,7 +117,7 @@ interface Store {
    *
    * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
    */
-  values: () => Promise<Value[]>;
+  values: <T = Value>() => Promise<T[]>;
 
   /**
    * Return an object with the keys:values in the store:
@@ -132,7 +132,7 @@ interface Store {
    *
    * **[→ Full .all() Docs](https://polystore.dev/documentation#all)**
    */
-  all: () => Promise<{ [key: string]: Value }>;
+  all: <T = Value>() => Promise<{ [key: string]: T }>;
 
   /**
    * Delete all of the records of the store:
@@ -176,6 +176,21 @@ interface Store {
    * **[→ Full .close() Docs](https://polystore.dev/documentation#close)**
    */
   close?: () => Promise<null>;
+
+  /**
+   * An iterator that goes through all of the key:value pairs in the client
+   *
+   * ```js
+   * for await (const [key, value] of store) {
+   *   console.log(key, value);
+   * }
+   * ```
+   *
+   * **[→ Full Iterator Docs](https://polystore.dev/documentation#iterator)**
+   */
+  [Symbol.asyncIterator]: () => {
+    next: () => Promise<{ value: [string, Value] }>;
+  };
 }
 
 export default function (store?: any): Store;

package/src/index.js

@@ -6,8 +6,6 @@ class Store {
 
   constructor(clientPromise = new Map()) {
     this.promise = Promise.resolve(clientPromise).then(async (client) => {
-      if (client?.open) await client.open();
-      if (client?.connect) await client.connect();
       this.client = this.#find(client);
       this.#validate(this.client);
       this.promise = null;
@@ -42,20 +40,12 @@ class Store {
     }
 
     if (!client.EXPIRES) {
-      if (client.has) {
-        throw new Error(
-          `You can only define client.has() when the client manages the expiration; otherwise please do NOT define .has() and let us manage it`
-        );
-      }
-      if (client.keys) {
-        throw new Error(
-          `You can only define client.keys() when the client manages the expiration; otherwise please do NOT define .keys() and let us manage them`
-        );
-      }
-      if (client.values) {
-        console.warn(
-          `Since this KV client does not manage expiration, it's better not to define client.values() since it doesn't allow us to evict expired keys`
-        );
+      for (let method of ["has", "keys", "values"]) {
+        if (client[method]) {
+          throw new Error(
+            `You can only define client.${method}() when the client manages the expiration; otherwise please do NOT define .${method}() and let us manage it`
+          );
+        }
       }
     }
   }