polystore 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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",

package/readme.md

@@ -1,4 +1,4 @@
-# Polystore [![npm install polystore](https://img.shields.io/badge/npm%20install-polystore-blue.svg)](https://www.npmjs.com/package/polystore) [![test badge](https://github.com/franciscop/polystore/workflows/tests/badge.svg "test badge")](https://github.com/franciscop/polystore/blob/master/.github/workflows/tests.yml) [![gzip size](https://img.badgesize.io/franciscop/polystore/master/index.min.js.svg?compression=gzip)](https://github.com/franciscop/polystore/blob/master/index.min.js)
+# Polystore [![npm install polystore](https://img.shields.io/badge/npm%20install-polystore-blue.svg)](https://www.npmjs.com/package/polystore) [![test badge](https://github.com/franciscop/polystore/workflows/tests/badge.svg "test badge")](https://github.com/franciscop/polystore/blob/master/.github/workflows/tests.yml) [![gzip size](https://img.badgesize.io/franciscop/polystore/master/src/index.js.svg?compression=gzip)](https://github.com/franciscop/polystore/blob/master/src/index.js)
 
 A small compatibility layer for many KV stores like localStorage, Redis, FileSystem, etc:
 
@@ -14,9 +14,12 @@ This is the [API](#api) with all of the methods (they are all `async`):
 
 - `.get(key): any`: retrieve a single value, or `null` if it doesn't exist or is expired.
 - `.set(key, value, options?)`: save a single value, which can be anything that is serializable.
+- `.add(value, options?)`: same as with `.set()`, but auto-generate the key.
 - `.has(key): boolean`: check whether the key is in the store or not.
 - `.del(key)`: delete a single value from the store.
 - `.keys(prefix?): string[]`: get a list of all the available strings in the store.
+- `.values(prefix?): any[]`: get a list of all the values in the store.
+- `.entries(prefix?): [string, any][]`: get a list of all the key-value pairs in the store.
 - `.clear()`: delete ALL of the data in the store, effectively resetting it.
 - `.close()`: (only _some_ stores) ends the connection to the store.
 
@@ -91,7 +94,7 @@ If the value is returned, it can be a simple type like `boolean`, `string` or `n
 
 ### .set()
 
-Create or update a value in the store. Will return a promise that resolves when the value has been saved. The value needs to be serializable:
+Create or update a value in the store. Will return a promise that resolves with the key when the value has been saved. The value needs to be serializable:
 
 ```js
 await store.set(key: string, value: any, options?: { expires: number|string });
@@ -109,29 +112,53 @@ The value can be a simple type like `boolean`, `string` or `number`, or it can b
 
 #### Expires
 
-When the `expires` option is set, it can be a number (ms) or a string representing some time:
+When the `expires` option is set, it can be a number (**seconds**) or a string representing some time:
 
 ```js
 // Valid "expire" values:
 0 - expire immediately (AKA delete it)
-100 - expire after 100ms
-60 * 60 * 1000 - expire after 1h
-3_600_000 - expire after 1h
+0.1 - expire after 100ms*
+60 * 60 - expire after 1h
+3_600 - expire after 1h
 "10s" - expire after 10 seconds
 "2minutes" - expire after 2 minutes
 "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
+
 These are all the units available:
 
 > "ms", "millisecond", "s", "sec", "second", "m", "min", "minute", "h", "hr", "hour", "d", "day", "w", "wk", "week", "b" (month), "month", "y", "yr", "year"
 
+### .add()
+
+Create a value in the store with a random key string. Will return a promise that resolves with the key when the value has been saved. The value needs to be serializable:
+
+```js
+const key:string = await store.add(value: any, options?: { expires: number|string });
+
+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  });
+```
+
+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.
+
+Here is the safety: "If you generate 1 million keys/second, it will take ~14 million years in order to have a 1% probability of at least one collision."
+
+> 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.
+
 ### .has()
 
 Check whether the key is available in the store and not expired:
 
 ```js
 await store.has(key: string);
+
+if (await store.has('cookie-consent')) {
+  loadCookies();
+}
 ```
 
 ### .del()
@@ -150,6 +177,45 @@ Get all of the keys in the store, optionally filtered by a prefix:
 await store.keys(filter?: string);
 ```
 
+> We ensure that all of the keys returned by this method are _not_ expired, while discarding any potentially expired key. See [**expiration explained**](#expiration-explained) for more details.
+
+### .values()
+
+Get all of the values in the store, optionally filtered by a **key** prefix:
+
+```js
+await store.values(filter?: string);
+```
+
+This is useful specially when you already have the id/key within the value as an object, then you can just get a list of all of them:
+
+```js
+const sessions = await store.values("session:");
+// A list of all the sessions
+
+const companies = await store.values("company:");
+// A list of all the companies
+```
+
+> We ensure that all of the values returned by this method are _not_ expired, while discarding any potentially expired key. See [**expiration explained**](#expiration-explained) for more details.
+
+### .entries()
+
+Get all of the entries (key:value tuples) in the store, optionally filtered by a **key** prefix:
+
+```js
+await store.entries(filter?: string);
+```
+
+It is in a format that you can easily build an object out of it:
+
+```js
+const sessionEntries = await store.entries("session:");
+const sessions = Object.fromEntries(sessionEntries);
+```
+
+> We ensure that all of the entries returned by this method are _not_ expired, while discarding any potentially expired key. See [**expiration explained**](#expiration-explained) for more details.
+
 ### .clear()
 
 Remove all of the data from the store:
@@ -164,26 +230,26 @@ Create a sub-store where all the operations use the given prefix:
 
 ```js
 const store = kv(new Map());
-const sub = store.prefix("session:");
+const session = store.prefix("session:");
 ```
 
 Then all of the operations will be converted internally to add the prefix when reading, writing, etc:
 
 ```js
-const val = await sub.get("key1"); // .get('session:key1');
-await sub.set("key2", "some data"); // .set('session:key2', ...);
-const val = await sub.has("key3"); // .has('session:key3');
-await sub.del("key4"); // .del('session:key4');
-await sub.keys(); // .keys('session:');
+const val = await session.get("key1"); // .get('session:key1');
+await session.set("key2", "some data"); // .set('session:key2', ...);
+const val = await session.has("key3"); // .has('session:key3');
+await session.del("key4"); // .del('session:key4');
+await session.keys(); // .keys('session:');
 // ['key1', 'key2', ...]   Note no prefix here
-await sub.clear(); // delete only keys with the prefix
+await session.clear(); // delete only keys with the prefix
 ```
 
 This will probably never be stable given the nature of some engines, so as an alternative please consider using two stores instead of prefixes:
 
 ```js
 const store = kv(new Map());
-const sessionStore = kv(new Map());
+const session = kv(new Map());
 ```
 
 The main reason this is not stable is because [_some_ store engines don't allow for atomic deletion of keys given a prefix](https://stackoverflow.com/q/4006324/938236). While we do still clear them internally in those cases, that is a non-atomic operation and it could have some trouble if some other thread is reading/writing the data _at the same time_.
@@ -251,7 +317,7 @@ console.log(await store.get("key1"));
 
 It is fairly limited for how powerful cookies are, but in exchange it has the same API as any other method or KV store. It works with browser-side Cookies (no http-only).
 
-> Note: the cookie expire resolution is in the seconds. While it still expects you to pass the number of ms as with the other methods (or [a string like `1h`](#expires)), times shorter than 1 second like `expires: 200` (ms) don't make sense for this storage method and won't properly save them.
+> Note: the cookie expire resolution is in the seconds, so times shorter than 1 second like `expires: 0.02` (20 ms) don't make sense for this storage method and won't properly save them.
 
 ### Local Forage
 
@@ -280,7 +346,7 @@ await store.set("key1", "Hello world");
 console.log(await store.get("key1"));
 ```
 
-> Note: the Redis client expire resolution is in the seconds. While it still expects you to pass the number of ms as with the other methods (or [a string like `1h`](#expires)), times shorter than 1 second like `expires: 200` (ms) don't make sense for this storage method and won't properly save them.
+> Note: the Redis client expire resolution is in the seconds, so times shorter than 1 second like `expires: 0.02` (20 ms) don't make sense for this storage method and won't properly save them.
 
 ### FS File
 
@@ -317,7 +383,7 @@ export default {
 };
 ```
 
-The Cloudflare native KV store only accepts strings and has you manually calculating timeouts, but as usual with `polystore` you can set/get any serializable value and set the timeout in a familiar format:
+Why? The Cloudflare native KV store only accepts strings and has you manually calculating timeouts, but as usual with `polystore` you can set/get any serializable value and set the timeout in a familiar format:
 
 ```js
 // GOOD - with polystore
@@ -330,3 +396,55 @@ await env.YOUR_KV_NAMESPACE.put("user", serialValue, {
   expirationTtl: twoDaysInSeconds,
 });
 ```
+
+## Expiration explained
+
+While different engines do expiration slightly differently internally, in creating polystore we want to ensure certain constrains, which _can_ affect performance. For example, if you do this operation:
+
+```js
+// in-memory store
+const store = polystore(new Map());
+await store.set("a", "b", { expires: "1s" });
+
+// These checks of course work:
+console.log(await store.keys()); // ['a']
+console.log(await store.has("a")); // true
+console.log(await store.get("a")); // 'b'
+
+// Make sure the key is expired
+await delay(2000); // 2s
+
+// Not only the .get() is null, but `.has()` returns false, and .keys() ignores it
+console.log(await store.keys()); // []
+console.log(await store.has("a")); // false
+console.log(await store.get("a")); // null
+```
+
+This is great because with polystore we do ensure that if a key has expired, it doesn't show up in `.keys()`, `.entries()`, `.values()`, `.has()` or `.get()`.
+
+However, in some stores this does come with some potential performance disadvantages. For example, both the in-memory example above and localStorage _don't_ have a native expiration/eviction process, so we have to store that information as metadata, meaning that even to check if a key exists we need to read and decode its value. For one or few keys it's not a problem, but for large sets this can become an issue.
+
+For other stores like Redis this is not a problem, because the low-level operations already do them natively, so we don't need to worry about this for performance at the user-level. Instead, Redis and cookies have the problem that they only have expiration resolution at the second level. Meaning that 800ms is not a valid Redis expiration time, it has to be 1s, 2s, etc.
+
+## Creating a store
+
+A store needs at least 4 methods with these signatures:
+
+```js
+const store = {};
+store.get = (key: string) => Promise<any>;
+store.set = (key: string, value: any, { expires: number }) => Promise<string>;
+store.entries = (prefix: string = "") => Promise<[key:string, value:any][]>;
+store.clear = () => Promise<null>;
+```
+
+All of the other methods will be implemented on top of these if not available, but you can provide those as well for optimizations, incompatible APIs, etc. For example, `.set('a', null)` _should_ delete the key `a`, and for this you may provide a native implementation:
+
+```js
+const native = myNativeStore();
+
+const store = {};
+store.get = (key) => native.getItem(key);
+// ...
+store.del = (key) => native.deleteItem(key);
+```

package/src/index.d.ts

@@ -1,15 +1,19 @@
+type Key = string;
+type Options = { expires?: number | string | null };
+
 type Store = {
-  get: (key: string) => Promise<any>;
-  set: (
-    key: string,
-    value: any,
-    opts?: { expires?: number | string | null }
-  ) => Promise<null>;
-  has: (key: string) => Promise<boolean>;
-  del: (key: string) => Promise<null>;
+  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>;
 
   keys: (prefix?: string) => Promise<string[]>;
+  values: (prefix?: string) => Promise<any[]>;
+  entries: (prefix?: string) => Promise<[key: string, value: any][]>;
+
   clear: () => Promise<null>;
+  close?: () => Promise<null>;
 };
 
 export default function (store?: any): Store;

package/src/index.js

@@ -2,8 +2,8 @@ const layers = {};
 
 const times = /(-?(?:\d+\.?\d*|\d*\.?\d+)(?:e[-+]?\d+)?)\s*([\p{L}]*)/iu;
 
-parse.millisecond = parse.ms = 1;
-parse.second = parse.sec = parse.s = parse[""] = parse.ms * 1000;
+parse.millisecond = parse.ms = 0.001;
+parse.second = parse.sec = parse.s = parse[""] = 1;
 parse.minute = parse.min = parse.m = parse.s * 60;
 parse.hour = parse.hr = parse.h = parse.m * 60;
 parse.day = parse.d = parse.h * 24;
@@ -22,17 +22,53 @@ function parse(str) {
   const unitValue = parse[units] || parse[units.replace(/s$/, "")];
   if (!unitValue) return null;
   const result = unitValue * parseFloat(value, 10);
-  return Math.abs(Math.round(result));
+  return Math.abs(Math.round(result * 1000) / 1000);
 }
 
+// "nanoid" imported manually
+// Something about improved GZIP performance with this string
+const urlAlphabet =
+  "useandom26T198340PX75pxJACKVERYMINDBUSHWOLFGQZbfghjklqvwyzrict";
+
+export let random = (bytes) => crypto.getRandomValues(new Uint8Array(bytes));
+
+function generateId() {
+  let size = 24;
+  let id = "";
+  let bytes = crypto.getRandomValues(new Uint8Array(size));
+  while (size--) {
+    // Using the bitwise AND operator to "cap" the value of
+    // the random byte from 255 to 63, in that way we can make sure
+    // that the value will be a valid index for the "chars" string.
+    id += urlAlphabet[bytes[size] & 61];
+  }
+  return id;
+}
+
+layers.extra = (store) => {
+  const add = async (value, options) => store.set(generateId(), value, options);
+  const has = async (key) => (await store.get(key)) !== null;
+  const del = async (key) => store.set(key, null);
+  const keys = async (prefix = "") => {
+    const all = await store.entries(prefix);
+    return all.map((p) => p[0]);
+  };
+  const values = async (prefix = "") => {
+    const all = await store.entries(prefix);
+    return all.map((p) => p[1]);
+  };
+  return { add, has, del, keys, values, ...store };
+};
+
 // Adds an expiration layer to those stores that don't have it;
 // it's not perfect since it's not deleted until it's read, but
 // hey it's better than nothing
 layers.expire = (store) => {
   // Item methods
   const get = async (key) => {
-    if (!(await store.has(key))) return null;
-    const { value, expire } = await store.get(key);
+    const data = await store.get(key);
+    if (!data) return null;
+    const { value, expire } = data;
     // It never expires
     if (expire === null) return value;
     const diff = expire - new Date().getTime();
@@ -42,122 +78,182 @@ layers.expire = (store) => {
   const set = async (key, value, { expire, expires } = {}) => {
     const time = parse(expire || expires);
     // Already expired, or do _not_ save it, then delete it
-    if (value === null || time === 0) return del(key);
-    const expDiff = time !== null ? new Date().getTime() + time : null;
+    if (value === null || time === 0) return store.set(key, null);
+    const expDiff = time !== null ? new Date().getTime() + time * 1000 : null;
     return store.set(key, { expire: expDiff, value });
   };
-  const has = async (key) => (await store.get(key)) !== null;
-  const del = store.del;
 
   // Group methods
-  const keys = store.keys;
-  const clear = store.clear;
+  const entries = async (prefix = "") => {
+    const all = await store.entries(prefix);
+    const now = new Date().getTime();
+    return all
+      .filter(([, data]) => {
+        // There's no data, so remove this
+        if (!data || data === null) return false;
+
+        // It never expires, so keep it
+        const { expire } = data;
+        if (expire === null) return true;
+
+        // It's expired, so remove it
+        if (expire - now <= 0) return false;
+
+        // It's not expired, keep it
+        return true;
+      })
+      .map(([key, data]) => [key, data.value]);
+  };
 
-  return { get, set, has, del, keys, clear };
+  // We want to force overwrite here!
+  return { ...store, get, set, entries };
 };
 
 layers.memory = (store) => {
   // Item methods
   const get = async (key) => store.get(key) ?? null;
-  const set = async (key, data) => store.set(key, data);
-  const has = async (key) => store.has(key);
-  const del = async (key) => store.delete(key);
+  const set = async (key, data) => {
+    if (data === null) {
+      await store.delete(key);
+    } else {
+      await store.set(key, data);
+    }
+    return key;
+  };
 
   // Group methods
-  const keys = async (prefix = "") =>
-    [...(await store.keys())].filter((k) => k.startsWith(prefix));
+  const entries = async (prefix = "") => {
+    const entries = [...store.entries()];
+    return entries.filter((p) => p[0].startsWith(prefix));
+  };
   const clear = () => store.clear();
 
-  return { get, set, has, del, keys, clear };
+  return { get, set, entries, clear };
 };
 
 layers.storage = (store) => {
   // Item methods
   const get = async (key) => (store[key] ? JSON.parse(store[key]) : null);
-  const set = async (key, data) => store.setItem(key, JSON.stringify(data));
-  const has = async (key) => key in store;
-  const del = async (key) => store.removeItem(key);
+  const set = async (key, data) => {
+    if (data === null) {
+      await store.removeItem(key);
+    } else {
+      await store.setItem(key, JSON.stringify(data));
+    }
+    return key;
+  };
 
   // Group methods
-  const keys = async (prefix = "") =>
-    Object.keys(store).filter((k) => k.startsWith(prefix));
+  const entries = async (prefix = "") => {
+    const entries = Object.entries(store);
+    return entries
+      .map((p) => [p[0], p[1] ? JSON.parse(p[1]) : null])
+      .filter((p) => p[0].startsWith(prefix));
+  };
   const clear = () => store.clear();
 
-  return { get, set, has, del, keys, clear };
+  return { get, set, entries, clear };
 };
 
+// Cookies auto-expire, so we cannot do expiration checks manually
 layers.cookie = () => {
-  const get = async (key) => {
-    const value =
-      document.cookie
-        .split("; ")
-        .filter(Boolean)
-        .find((row) => row.startsWith(key + "="))
-        ?.split("=")[1] || null;
-    return JSON.parse(decodeURIComponent(value));
+  const getAll = () => {
+    const all = {};
+    for (let entry of document.cookie
+      .split(";")
+      .map((k) => k.trim())
+      .filter(Boolean)) {
+      const [key, data] = entry.split("=");
+      try {
+        all[key.trim()] = JSON.parse(decodeURIComponent(data.trim()));
+      } catch (error) {
+        // no-op (some 3rd party can set cookies independently)
+      }
+    }
+    return all;
   };
 
+  const get = async (key) => getAll()[key] ?? null;
+
   const set = async (key, data, { expire, expires } = {}) => {
-    const time = parse(expire || expires);
-    const now = new Date().getTime();
-    // NOTE: 0 is already considered here!
-    const expireStr =
-      time !== null ? `; expires=${new Date(now + time).toUTCString()}` : "";
-    const value = encodeURIComponent(JSON.stringify(data));
-    document.cookie = key + "=" + value + expireStr;
+    if (data === null) {
+      await set(key, "", { expire: -100 });
+    } else {
+      const time = parse(expire || expires);
+      const now = new Date().getTime();
+      // NOTE: 0 is already considered here!
+      const expireStr =
+        time !== null
+          ? `; expires=${new Date(now + time * 1000).toUTCString()}`
+          : "";
+      const value = encodeURIComponent(JSON.stringify(data));
+      document.cookie = key + "=" + value + expireStr;
+    }
+    return key;
   };
-  const has = async (key) => (await keys()).includes(key);
-  const del = async (key) => set(key, "", { expire: -100 });
 
   // Group methods
-  const keys = async (prefix = "") =>
-    document.cookie
-      .split(";")
-      .map((l) => l.split("=")[0].trim())
-      .filter(Boolean)
-      .filter((k) => k.startsWith(prefix));
+  const entries = async (prefix = "") => {
+    const all = Object.entries(getAll());
+    return all.filter((p) => p[0].startsWith(prefix));
+  };
+
   const clear = async () => {
-    await Promise.all((await keys()).map(del));
+    const keys = Object.keys(getAll());
+    await Promise.all(keys.map((key) => set(key, null)));
   };
 
-  return { get, set, has, del, keys, clear };
+  return { get, set, entries, clear };
 };
 
+// Plain 'redis' and not ioredis or similar
 layers.redis = (store) => {
   const get = async (key) => {
-    const client = await store;
-    const value = await client.get(key);
+    const value = await store.get(key);
     if (!value) return null;
     return JSON.parse(value);
   };
   const set = async (key, value, { expire, expires } = {}) => {
     const time = parse(expire || expires);
     if (value === null || time === 0) return del(key);
-    const client = await store;
-    const EX = time ? Math.round(time / 1000) : undefined;
-    return client.set(key, JSON.stringify(value), { EX });
+    const EX = time ? Math.round(time) : undefined;
+    await store.set(key, JSON.stringify(value), { EX });
+    return key;
   };
-  const has = async (key) => Boolean(await (await store).exists(key));
-  const del = async (key) => (await store).del(key);
-
-  const keys = async (prefix = "") => (await store).keys(prefix + "*");
-  const clear = async () => (await store).flushAll();
-  const close = async () => (await store).quit();
+  const has = async (key) => Boolean(await store.exists(key));
+  const del = async (key) => store.del(key);
+
+  const keys = async (prefix = "") => store.keys(prefix + "*");
+  const entries = async (prefix = "") => {
+    const keys = await store.keys(prefix + "*");
+    const values = await Promise.all(keys.map((k) => get(k)));
+    return keys.map((k, i) => [k, values[i]]);
+  };
+  const clear = async () => store.flushAll();
+  const close = async () => store.quit();
 
-  return { get, set, has, del, keys, clear, close };
+  return { get, set, has, del, keys, entries, clear, close };
 };
 
 layers.localForage = (store) => {
-  const get = (key) => store.getItem(key);
-  const set = (key, value) => store.setItem(key, value);
-  const has = async (key) => (await get(key)) !== null;
-  const del = (key) => store.removeItem(key);
-
-  const keys = async (prefix = "") =>
-    (await store.keys()).filter((k) => k.startsWith(prefix));
-  const clear = () => store.clear();
+  const get = async (key) => store.getItem(key);
+  const set = async (key, value) => {
+    if (value === null) {
+      await store.removeItem(key);
+    } else {
+      await store.setItem(key, value);
+    }
+    return key;
+  };
+  const entries = async (prefix = "") => {
+    const all = await store.keys();
+    const keys = all.filter((k) => k.startsWith(prefix));
+    const values = await Promise.all(keys.map((key) => store.getItem(key)));
+    return keys.map((key, i) => [key, values[i]]);
+  };
+  const clear = async () => store.clear();
 
-  return { get, set, has, del, keys, clear };
+  return { get, set, entries, clear };
 };
 
 layers.cloudflare = (store) => {
@@ -170,14 +266,25 @@ layers.cloudflare = (store) => {
     const time = parse(expire || expires);
     if (value === null || time === 0) return del(key);
     const client = await store;
-    const expirationTtl = time ? Math.round(time / 1000) : undefined;
-    return client.put(key, JSON.stringify(value), { expirationTtl });
+    const expirationTtl = time ? Math.round(time) : undefined;
+    client.put(key, JSON.stringify(value), { expirationTtl });
+    return key;
   };
   const has = async (key) => Boolean(await store.get(key));
   const del = (key) => store.delete(key);
-  const keys = (prefix) => store.list({ prefix });
+
+  // Group methods
+  const keys = async (prefix = "") => {
+    const raw = await store.list({ prefix });
+    return raw.keys;
+  };
+  const entries = async (prefix = "") => {
+    const all = await keys(prefix);
+    const values = await Promise.all(all.map((k) => get(k)));
+    return all.map((key, i) => [key, values[i]]);
+  };
   const clear = () => {};
-  return { get, set, has, del, keys, clear };
+  return { get, set, has, del, entries, keys, clear };
 };
 
 layers.file = (file) => {
@@ -209,57 +316,60 @@ layers.file = (file) => {
   };
   const set = async (key, value) => {
     const data = await getContent();
-    data[key] = value;
+    if (value === null) {
+      delete data[key];
+    } else {
+      data[key] = value;
+    }
     await setContent(data);
+    return key;
   };
   const has = async (key) => (await get(key)) !== null;
-  const del = async (key) => {
-    const data = await getContent();
-    delete data[key];
-    await setContent(data);
-  };
-  const keys = async (prefix = "") => {
+  const del = async (key) => set(key, null);
+
+  // Group methods
+  const entries = async (prefix = "") => {
     const data = await getContent();
-    return Object.keys(data).filter((k) => k.startsWith(prefix));
+    return Object.entries(data).filter((p) => p[0].startsWith(prefix));
   };
   const clear = async () => {
     await setContent({});
   };
-  return { get, set, has, del, keys, clear };
+  return { get, set, has, del, entries, clear };
 };
 
 const getStore = async (store) => {
   // Convert it to the normalized kv, then add the expiry layer on top
   if (store instanceof Map) {
-    return layers.expire(layers.memory(store));
+    return layers.extra(layers.expire(layers.memory(store)));
   }
 
   if (typeof localStorage !== "undefined" && store === localStorage) {
-    return layers.expire(layers.storage(store));
+    return layers.extra(layers.expire(layers.storage(store)));
   }
 
   if (typeof sessionStorage !== "undefined" && store === sessionStorage) {
-    return layers.expire(layers.storage(store));
+    return layers.extra(layers.expire(layers.storage(store)));
   }
 
   if (store === "cookie") {
-    return layers.cookie();
+    return layers.extra(layers.cookie());
   }
 
   if (store.defineDriver && store.dropInstance && store.INDEXEDDB) {
-    return layers.expire(layers.localForage(store));
+    return layers.extra(layers.expire(layers.localForage(store)));
   }
 
   if (store.protocol && store.protocol === "file:") {
-    return layers.expire(layers.file(store));
+    return layers.extra(layers.expire(layers.file(store)));
   }
 
   if (store.pSubscribe && store.sSubscribe) {
-    return layers.redis(store);
+    return layers.extra(layers.redis(store));
   }
 
   if (store?.constructor?.name === "KvNamespace") {
-    return layers.cloudflare(store);
+    return layers.extra(layers.cloudflare(store));
   }
 
   // ¯\_(ツ)_/¯
@@ -270,17 +380,22 @@ export default function compat(storeClient = new Map()) {
   return new Proxy(
     {},
     {
-      get: (_, key) => {
+      get: (instance, key) => {
         return async (...args) => {
-          const store = await getStore(await storeClient);
+          // Only once, even if called twice in succession, since the
+          // second time will go straight to the await
+          if (!instance.store && !instance.promise) {
+            instance.promise = getStore(await storeClient);
+          }
+          instance.store = await instance.promise;
           // Throw at the first chance when the store failed to init:
-          if (!store) {
+          if (!instance.store) {
             throw new Error("Store is not valid");
           }
           // The store.close() is the only one allowed to be called even
           // if it doesn't exist, since it's optional in some stores
-          if (!store[key] && key === "close") return null;
-          return store[key](...args);
+          if (!instance.store[key] && key === "close") return null;
+          return instance.store[key](...args);
         };
       },
     }

package/src/index.test.js

@@ -46,10 +46,20 @@ for (let [name, store] of stores) {
       expect(await store.has("a")).toBe(false);
     });
 
+    it("can add() arbitrary values", async () => {
+      const key = await store.add("b");
+      expect(typeof key).toBe("string");
+      expect(await store.get(key)).toBe("b");
+      expect(await store.has(key)).toBe(true);
+      expect(key.length).toBe(24);
+      expect(key).toMatch(/^[a-zA-Z0-9]{24}$/);
+    });
+
     it("can store values", async () => {
-      await store.set("a", "b");
+      const key = await store.set("a", "b");
       expect(await store.get("a")).toBe("b");
       expect(await store.has("a")).toBe(true);
+      expect(key).toBe("a");
     });
 
     it("can store basic types", async () => {
@@ -62,8 +72,8 @@ for (let [name, store] of stores) {
     });
 
     it("can store arrays of JSON values", async () => {
-      await store.set("a", ["b"]);
-      expect(await store.get("a")).toEqual(["b"]);
+      await store.set("a", ["b", "c"]);
+      expect(await store.get("a")).toEqual(["b", "c"]);
       expect(await store.has("a")).toBe(true);
     });
 
@@ -73,22 +83,83 @@ for (let [name, store] of stores) {
       expect(await store.has("a")).toBe(true);
     });
 
-    it("can retrieve the prefixed keys with colon", async () => {
+    it("can get the keys", async () => {
+      await store.set("a", "b");
+      await store.set("c", "d");
+      expect(await store.keys()).toEqual(["a", "c"]);
+    });
+
+    it("can get the values", async () => {
+      await store.set("a", "b");
+      await store.set("c", "d");
+      expect(await store.values()).toEqual(["b", "d"]);
+    });
+
+    it("can get the entries", async () => {
+      await store.set("a", "b");
+      await store.set("c", "d");
+      expect(await store.entries()).toEqual([
+        ["a", "b"],
+        ["c", "d"],
+      ]);
+    });
+
+    it("can get the keys with a colon prefix", async () => {
       await store.set("a:0", "a0");
       await store.set("a:1", "a1");
       await store.set("b:0", "b0");
-      await store.set("a:2", "b2");
+      await store.set("a:2", "a2");
       expect((await store.keys("a:")).sort()).toEqual(["a:0", "a:1", "a:2"]);
     });
 
-    it("can retrieve the prefixed keys with dash", async () => {
+    it("can get the values with a colon prefix", async () => {
+      await store.set("a:0", "a0");
+      await store.set("a:1", "a1");
+      await store.set("b:0", "b0");
+      await store.set("a:2", "a2");
+      expect((await store.values("a:")).sort()).toEqual(["a0", "a1", "a2"]);
+    });
+
+    it("can get the entries with a colon prefix", async () => {
+      await store.set("a:0", "a0");
+      await store.set("a:1", "a1");
+      await store.set("b:0", "b0");
+      await store.set("a:2", "a2");
+      expect((await store.entries("a:")).sort()).toEqual([
+        ["a:0", "a0"],
+        ["a:1", "a1"],
+        ["a:2", "a2"],
+      ]);
+    });
+
+    it("can get the keys with a dash prefix", async () => {
       await store.set("a-0", "a0");
       await store.set("a-1", "a1");
       await store.set("b-0", "b0");
-      await store.set("a-2", "b2");
+      await store.set("a-2", "a2");
       expect((await store.keys("a-")).sort()).toEqual(["a-0", "a-1", "a-2"]);
     });
 
+    it("can get the values with a dash prefix", async () => {
+      await store.set("a-0", "a0");
+      await store.set("a-1", "a1");
+      await store.set("b-0", "b0");
+      await store.set("a-2", "a2");
+      expect((await store.values("a-")).sort()).toEqual(["a0", "a1", "a2"]);
+    });
+
+    it("can get the entries with a dash prefix", async () => {
+      await store.set("a-0", "a0");
+      await store.set("a-1", "a1");
+      await store.set("b-0", "b0");
+      await store.set("a-2", "a2");
+      expect((await store.entries("a-")).sort()).toEqual([
+        ["a-0", "a0"],
+        ["a-1", "a1"],
+        ["a-2", "a2"],
+      ]);
+    });
+
     it("can delete the data", async () => {
       await store.set("a", "b");
       expect(await store.get("a")).toBe("b");
@@ -96,12 +167,6 @@ for (let [name, store] of stores) {
       expect(await store.get("a")).toBe(null);
     });
 
-    it("can get the keys", async () => {
-      await store.set("a", "b");
-      await store.set("c", "d");
-      expect(await store.keys()).toEqual(["a", "c"]);
-    });
-
     it("can clear all the values", async () => {
       await store.set("a", "b");
       await store.set("c", "d");
@@ -116,6 +181,10 @@ for (let [name, store] of stores) {
       it("expires = 0 means immediately", async () => {
         await store.set("a", "b", { expires: 0 });
         expect(await store.get("a")).toBe(null);
+        expect(await store.has("a")).toBe(false);
+        expect(await store.keys()).toEqual([]);
+        expect(await store.values()).toEqual([]);
+        expect(await store.entries()).toEqual([]);
       });
 
       it("expires = potato means undefined = forever", async () => {
@@ -147,8 +216,9 @@ for (let [name, store] of stores) {
       });
 
       if (name !== "kv('cookie')" && name !== "kv(redis)") {
-        it("can use 10 expire", async () => {
-          await store.set("a", "b", { expires: 10 });
+        it("can use 0.01 expire", async () => {
+          // 10ms
+          await store.set("a", "b", { expires: 0.01 });
           expect(await store.get("a")).toBe("b");
           await delay(100);
           expect(await store.get("a")).toBe(null);
@@ -175,8 +245,8 @@ for (let [name, store] of stores) {
           expect(await store.get("a")).toBe(null);
         });
       } else {
-        it("can use 1000 expire", async () => {
-          await store.set("a", "b", { expires: 1000 });
+        it("can use 1 (second) expire", async () => {
+          await store.set("a", "b", { expires: 1 });
           expect(await store.get("a")).toBe("b");
           await delay(2000);
           expect(await store.get("a")).toBe(null);

package/src/index.types.ts

@@ -8,6 +8,10 @@ const store = kv();
   await store.set("key", "value", {});
   await store.set("key", "value", { expires: 100 });
   await store.set("key", "value", { expires: "100s" });
+  const key1: string = await store.add("value");
+  const key2: string = await store.add("value", { expires: 100 });
+  const key3: string = await store.add("value", { expires: "100s" });
+  console.log(key1, key2, key3);
   if (await store.has("key")) {
   }
 })();