polystore 0.11.4 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "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",
@@ -15,8 +15,9 @@
   ],
   "scripts": {
     "size": "echo $(gzip -c src/index.js | wc -c) bytes",
+    "lint": "check-dts test/index.types.ts",
     "start": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch --coverage --detectOpenHandles",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --ci --watchAll=false --detectOpenHandles && check-dts test/index.types.ts"
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --ci --watchAll=false --detectOpenHandles"
   },
   "keywords": [
     "kv",
@@ -56,6 +57,9 @@
     "setupFiles": [
       "./test/setup.js"
     ],
-    "transform": {}
+    "transform": {},
+    "modulePathIgnorePatterns": [
+      "test/cloudflare"
+    ]
   }
 }

package/readme.md

@@ -99,18 +99,6 @@ const store = kv(MyClientOrStoreInstance);
 // use the store
 ```
 
-If the instance you pass contains a `connect()` or `open()` method, polystore **will** call that without any argument:
-
-```js
-// Simpler
-const store = kv(createClient());
-
-// NO NEED
-const client = createClient();
-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 might add custom serialization and extra properties for e.g. expiration time:
 
 ```js
@@ -141,7 +129,7 @@ console.log(await store.get("key3"));  // { name: "Francisco" }
 
 If the value is returned, it can be a simple type like `boolean`, `string` or `number`, or it can be a plain Object or Array, or a combination of those.
 
-> The value cannot be more complex or non-serializable values like a `Date()`, `Infinity`, `undefined` (casted to `null`), a Symbol, etc.
+> The value cannot be more complex or non-serializable values like a `Date()`, `Infinity`, `undefined`, a `Symbol`, etc.
 
 ### .set()
 
@@ -152,7 +140,7 @@ await store.set(key: string, value: any, options?: { expires: number|string });
 
 await store.set("key1", "Hello World");
 await store.set("key2", ["my", "grocery", "list"], { expires: "1h" });
-await store.set("key3", { name: "Francisco" }, { expires: 60 * 60 * 1000  });
+await store.set("key3", { name: "Francisco" }, { expires: 60 * 60 });
 ```
 
 The value can be a simple type like `boolean`, `string` or `number`, or it can be a plain Object or Array, or a combination of those. It **cannot** be a more complex or non-serializable values like a `Date()`, `Infinity`, `undefined` (casted to `null`), a `Symbol`, etc.
@@ -176,7 +164,7 @@ When the `expires` option is set, it can be a number (**seconds**) or a string r
 "5d" - expire after 5 days
 ```
 
-\* not all stores support sub-second expirations, notably Redis and Cookies don't, so it's safer to always use an integer or an amount larger than 1s
+\* not all stores support sub-second expirations, notably Redis and Cookies don't, so it's safer to always use an integer or an amount larger than 1s. There will be a note in each store for this.
 
 These are all the units available:
 
@@ -191,7 +179,7 @@ const key:string = await store.add(value: any, options?: { expires: number|strin
 
 const key1 = await store.add("Hello World");
 const key2 = await store.add(["my", "grocery", "list"], { expires: "1h" });
-const key3 = await store.add({ name: "Francisco" }, { expires: 60 * 60 * 1000  });
+const key3 = await store.add({ name: "Francisco" }, { expires: 60 * 60  });
 ```
 
 The generated key is 24 AlphaNumeric characters (including upper and lower case) generated with random cryptography to make sure it's unguessable, high entropy and safe to use in most contexts like URLs, queries, etc. We use [`nanoid`](https://github.com/ai/nanoid/) with a custom dictionary, so you can check the entropy [in this dictionary](https://zelark.github.io/nano-id-cc/) by removing the "\_" and "-", and setting it to 24 characters.
@@ -200,9 +188,26 @@ Here is the safety: "If you generate 1 million keys/second, it will take ~14 mil
 
 > Note: please make sure to read the [`.set()`](#set) section for all the details, since `.set()` and `.add()` behave the same way except for the first argument.
 
+The main reason why `.add()` exists is to allow it to work with the prefix seamlessly:
+
+```js
+const session = store.prefix("session:");
+
+// Creates a key with the prefix (returns only the key)
+const key1 = await session.add("value1");
+// "c4ONlvweshXPUEy76q3eFHPL"
+
+console.log(await session.keys()); // on the "session" store
+// ["c4ONlvweshXPUEy76q3eFHPL"]
+console.log(await store.keys()); // on the root store
+// ["session:c4ONlvweshXPUEy76q3eFHPL"]
+```
+
+Remember that [substores with `.prefix()`](#prefix) behave as if they were an independent store, so when adding, manipulating, etc. a value you should treat the key as if it had no prefix. This is explained in detail in the [.prefix()](#prefix) documentation.
+
 ### .has()
 
-Check whether the key is available in the store and not expired:
+Check whether the key:value is available in the store and not expired:
 
 ```js
 await store.has(key: string);
@@ -233,6 +238,17 @@ async function fetchUser(id) {
 }
 ```
 
+An example with a prefix:
+
+```js
+const session = store.prefix("session:");
+
+// These three perform the same operation internally
+const has1 = await session.has("key1");
+const has2 = await store.prefix("session:").has("key1");
+const has3 = await store.has("session:key1");
+```
+
 ### .del()
 
 Remove a single key from the store and return the key itself:
@@ -241,7 +257,24 @@ 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).
+It will ignore the operation if the key or value don't exist already (but won't thorw). The API makes it easy to delete multiple keys at once:
+
+```js
+const keys = ["key1", "key2"];
+await Promise.all(keys.map(store.del));
+console.log(done);
+```
+
+An example with a prefix:
+
+```js
+const session = store.prefix("session:");
+
+// These three perform the same operation internally
+await session.del("key1");
+await store.prefix("session:").del("key1");
+await store.del("session:key1");
+```
 
 ### _Iterator_
 
@@ -249,18 +282,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:
@@ -374,15 +418,6 @@ console.log(await store.get("key1"));
 // "Hello world"
 ```
 
-It can also be initialized empty, then it'll use the in-memory store:
-
-```js
-import kv from "polystore";
-
-const store = kv();
-const store = kv(new Map());
-```
-
 <details>
   <summary>Why use polystore with <code>new Map()</code>?</summary>
   <p>Besides the other benefits already documented elsewhere, these are the ones specifically for wrapping Map() with polystore:</p>

package/src/clients/cloudflare.js

@@ -23,6 +23,9 @@ export default class Cloudflare {
 
   async set(key, value, { expires } = {}) {
     const expirationTtl = expires ? Math.round(expires) : undefined;
+    if (expirationTtl && expirationTtl < 60) {
+      throw new Error("Cloudflare's min expiration is '60s'");
+    }
     return this.client.put(key, JSON.stringify(value), { expirationTtl });
   }
 

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

@@ -4,7 +4,7 @@ import { createId, isClass, parse } from "./utils.js";
 class Store {
   PREFIX = "";
 
-  constructor(clientPromise = new Map()) {
+  constructor(clientPromise) {
     this.promise = Promise.resolve(clientPromise).then(async (client) => {
       this.client = this.#find(client);
       this.#validate(this.client);
@@ -33,10 +33,9 @@ class Store {
   }
 
   #validate(client) {
+    if (!client) throw new Error("No client received");
     if (!client.set || !client.get || !client.iterate) {
-      throw new Error(
-        "A client should have at least a .get(), .set() and .iterate()"
-      );
+      throw new Error("Client should have .get(), .set() and .iterate()");
     }
 
     if (!client.EXPIRES) {

package/src/utils.js

@@ -9,7 +9,7 @@ parse.week = parse.wk = parse.w = parse.d * 7;
 parse.year = parse.yr = parse.y = parse.d * 365.25;
 parse.month = parse.b = parse.y / 12;
 
-// Returns the time in milliseconds
+// Returns the time in seconds
 export function parse(str) {
   if (str === null || str === undefined) return null;
   if (typeof str === "number") return str;