polystore 0.17.0 → 0.18.0

package/index.d.ts

@@ -1,6 +1,4 @@
-type Options = {
-    expires?: number | null | string;
-};
+type Expires = number | null | string;
 type StoreData<T extends Serializable = Serializable> = {
     value: T;
     expires: number | null;
@@ -9,13 +7,14 @@ type Serializable = string | number | boolean | null | (Serializable | null)[] |
     [key: string]: Serializable | null;
 };
 interface ClientExpires {
+    TYPE: string;
     EXPIRES: true;
     promise?: Promise<any>;
     test?: (client: any) => boolean;
     get<T extends Serializable>(key: string): Promise<T | null> | T | null;
-    set<T extends Serializable>(key: string, value: T, options?: Options): Promise<any> | any;
+    set<T extends Serializable>(key: string, value: T, expires?: Expires): Promise<any> | any;
     iterate<T extends Serializable>(prefix: string): AsyncGenerator<[string, T], void, unknown> | Generator<[string, T], void, unknown>;
-    add?<T extends Serializable>(prefix: string, value: T, options?: Options): Promise<string>;
+    add?<T extends Serializable>(prefix: string, value: T, expires?: Expires): Promise<string>;
     has?(key: string): Promise<boolean> | boolean;
     del?(key: string): Promise<any> | any;
     keys?(prefix: string): Promise<string[]> | string[];
@@ -27,13 +26,14 @@ interface ClientExpires {
     close?(): Promise<any> | any;
 }
 interface ClientNonExpires {
+    TYPE: string;
     EXPIRES: false;
     promise?: Promise<any>;
     test?: (client: any) => boolean;
     get<T extends Serializable>(key: string): Promise<StoreData<T> | null> | StoreData<T> | null;
-    set<T extends Serializable>(key: string, value: StoreData<T> | null, options?: Options): Promise<any> | any;
+    set<T extends Serializable>(key: string, value: StoreData<T> | null, ttl?: Expires): Promise<any> | any;
     iterate<T extends Serializable>(prefix: string): AsyncGenerator<[string, StoreData<T>], void, unknown> | Generator<[string, StoreData<T>], void, unknown>;
-    add?<T extends Serializable>(prefix: string, value: StoreData<T>, options?: Options): Promise<string>;
+    add?<T extends Serializable>(prefix: string, value: StoreData<T>, ttl?: Expires): Promise<string>;
     has?(key: string): Promise<boolean> | boolean;
     del?(key: string): Promise<any> | any;
     keys?(prefix: string): Promise<string[]> | string[];
@@ -51,6 +51,7 @@ declare class Store<TDefault extends Serializable = Serializable> {
     PREFIX: string;
     promise: Promise<Client> | null;
     client: Client;
+    type: string;
     constructor(clientPromise?: any);
     /**
      * Save the data on an autogenerated key, can add expiration as well:
@@ -63,8 +64,8 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .add() Docs](https://polystore.dev/documentation#add)**
      */
-    add(value: TDefault, options?: Options): Promise<string>;
-    add<T extends TDefault>(value: T, options?: Options): Promise<string>;
+    add(value: TDefault, ttl?: Expires): Promise<string>;
+    add<T extends TDefault>(value: T, ttl?: Expires): Promise<string>;
     /**
      * Save the data on the given key, can add expiration as well:
      *
@@ -76,8 +77,8 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .set() Docs](https://polystore.dev/documentation#set)**
      */
-    set(key: string, value: TDefault, options?: Options): Promise<string>;
-    set<T extends TDefault>(key: string, value: T, options?: Options): Promise<string>;
+    set(key: string, value: TDefault, ttl?: Expires): Promise<string>;
+    set<T extends TDefault>(key: string, value: T, ttl?: Expires): Promise<string>;
     /**
      * Read a single value from the KV store:
      *
@@ -121,6 +122,17 @@ declare class Store<TDefault extends Serializable = Serializable> {
      * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
      */
     del(key: string): Promise<string>;
+    /**
+     * @alias of .del(key: string)
+     * Remove a single key and its value from the store:
+     *
+     * ```js
+     * const key = await store.delete("key1");
+     * ```
+     *
+     * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+     */
+    delete(key: string): Promise<string>;
     /**
      * An iterator that goes through all of the key:value pairs in the client
      *

package/index.js

@@ -1,5 +1,6 @@
 // src/clients/Client.ts
 var Client = class {
+  TYPE;
   EXPIRES = false;
   client;
   encode = (val) => JSON.stringify(val, null, 2);
@@ -11,6 +12,7 @@ var Client = class {
 
 // src/clients/api.ts
 var Api = class extends Client {
+  TYPE = "API";
   // Indicate that the file handler DOES handle expirations
   EXPIRES = true;
   static test = (client) => typeof client === "string" && /^https?:\/\//.test(client);
@@ -25,7 +27,7 @@ var Api = class extends Client {
     return this.decode(await res.text());
   };
   get = (key) => this.#api(key);
-  set = async (key, value, { expires } = {}) => {
+  set = async (key, value, expires) => {
     const exp = typeof expires === "number" ? `?expires=${expires}` : "";
     await this.#api(key, exp, "PUT", this.encode(value));
   };
@@ -45,15 +47,16 @@ var Api = class extends Client {
 
 // src/clients/cloudflare.ts
 var Cloudflare = class extends Client {
+  TYPE = "CLOUDFLARE";
   // It handles expirations natively
   EXPIRES = true;
-  // Check whether the given store is a FILE-type
-  static test = (client) => client?.constructor?.name === "KvNamespace" || client?.constructor?.name === "EdgeKVNamespace";
+  static testKeys = ["getWithMetadata", "get", "list", "delete"];
   get = async (key) => {
-    return this.decode(await this.client.get(key));
+    const value = await this.client.get(key);
+    return this.decode(value);
   };
-  set = async (key, data, opts) => {
-    const expirationTtl = opts.expires ? Math.round(opts.expires) : void 0;
+  set = async (key, data, expires) => {
+    const expirationTtl = expires ? Math.round(expires) : void 0;
     if (expirationTtl && expirationTtl < 60) {
       throw new Error("Cloudflare's min expiration is '60s'");
     }
@@ -93,6 +96,7 @@ var Cloudflare = class extends Client {
 
 // src/clients/cookie.ts
 var Cookie = class extends Client {
+  TYPE = "COOKIE";
   // It handles expirations natively
   EXPIRES = true;
   // Check if this is the right class for the given client
@@ -118,7 +122,7 @@ var Cookie = class extends Client {
     const all = this.#read();
     return key in all ? all[key] : null;
   };
-  set = (key, data, { expires }) => {
+  set = (key, data, expires) => {
     const k = encodeURIComponent(key);
     const value = encodeURIComponent(this.encode(data ?? ""));
     let exp = "";
@@ -128,7 +132,7 @@ var Cookie = class extends Client {
     }
     document.cookie = `${k}=${value}${exp}`;
   };
-  del = (key) => this.set(key, "", { expires: -100 });
+  del = (key) => this.set(key, "", -100);
   async *iterate(prefix = "") {
     for (let [key, value] of Object.entries(this.#read())) {
       if (!key.startsWith(prefix)) continue;
@@ -139,10 +143,11 @@ var Cookie = class extends Client {
 
 // src/clients/etcd.ts
 var Etcd = class extends Client {
+  TYPE = "ETCD3";
   // It desn't handle expirations natively
   EXPIRES = false;
   // Check if this is the right class for the given client
-  static test = (client) => client?.constructor?.name === "Etcd3";
+  static testKeys = ["leaseClient", "watchClient", "watchManager"];
   get = async (key) => {
     const data = await this.client.get(key).json();
     return data;
@@ -157,14 +162,6 @@ var Etcd = class extends Client {
       yield [key, await this.get(key)];
     }
   }
-  keys = (prefix = "") => {
-    return this.client.getAll().prefix(prefix).keys();
-  };
-  entries = async (prefix = "") => {
-    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]]);
-  };
   clear = async (prefix = "") => {
     if (!prefix) return this.client.delete().all();
     return this.client.delete().prefix(prefix);
@@ -173,6 +170,7 @@ var Etcd = class extends Client {
 
 // src/clients/file.ts
 var File = class extends Client {
+  TYPE = "FILE";
   // It desn't handle expirations natively
   EXPIRES = false;
   fsp;
@@ -266,6 +264,7 @@ var noFileOk = (error) => {
   throw error;
 };
 var Folder = class extends Client {
+  TYPE = "FOLDER";
   // It desn't handle expirations natively
   EXPIRES = false;
   fsp;
@@ -311,6 +310,7 @@ var Folder = class extends Client {
 
 // src/clients/forage.ts
 var Forage = class extends Client {
+  TYPE = "FORAGE";
   // It desn't handle expirations natively
   EXPIRES = false;
   // Check if this is the right class for the given client
@@ -344,10 +344,11 @@ var notFound = (error) => {
   throw error;
 };
 var Level = class extends Client {
+  TYPE = "LEVEL";
   // It desn't handle expirations natively
   EXPIRES = false;
   // Check if this is the right class for the given client
-  static test = (client) => client?.constructor?.name === "ClassicLevel";
+  static testKeys = ["attachResource", "detachResource", "prependOnceListener"];
   get = (key) => this.client.get(key, { valueEncoding }).catch(notFound);
   set = (key, value) => this.client.put(key, value, { valueEncoding });
   del = (key) => this.client.del(key);
@@ -378,6 +379,7 @@ var Level = class extends Client {
 
 // src/clients/memory.ts
 var Memory = class extends Client {
+  TYPE = "MEMORY";
   // It desn't handle expirations natively
   EXPIRES = false;
   // Check if this is the right class for the given client
@@ -395,12 +397,13 @@ var Memory = class extends Client {
 
 // src/clients/redis.ts
 var Redis = class extends Client {
+  TYPE = "REDIS";
   // Indicate if this client handles expirations (true = it does)
   EXPIRES = true;
   // Check if this is the right class for the given client
   static test = (client) => client && client.pSubscribe && client.sSubscribe;
   get = async (key) => this.decode(await this.client.get(key));
-  set = async (key, value, { expires } = {}) => {
+  set = async (key, value, expires) => {
     const EX = expires ? Math.round(expires) : void 0;
     return this.client.set(key, this.encode(value), { EX });
   };
@@ -438,6 +441,7 @@ var Redis = class extends Client {
 
 // src/clients/sqlite.ts
 var SQLite = class extends Client {
+  TYPE = "SQLITE";
   // This one is doing manual time management internally even though
   // sqlite does not natively support expirations. This is because it does
   // support creating a `expires_at:Date` column that makes managing
@@ -474,7 +478,7 @@ var SQLite = class extends Client {
     }
     return this.decode(row.value);
   };
-  set = (id, data, { expires } = {}) => {
+  set = (id, data, expires) => {
     const value = this.encode(data);
     const expires_at = expires ? Date.now() + expires * 1e3 : null;
     this.client.prepare(
@@ -524,6 +528,7 @@ ${prefix ? "AND id LIKE ?" : ""}
 
 // src/clients/storage.ts
 var WebStorage = class extends Client {
+  TYPE = "STORAGE";
   // It desn't handle expirations natively
   EXPIRES = false;
   // Check if this is the right class for the given client
@@ -607,21 +612,28 @@ var Store = class _Store {
   PREFIX = "";
   promise;
   client;
+  type = "UNKNOWN";
   constructor(clientPromise = /* @__PURE__ */ new Map()) {
     this.promise = Promise.resolve(clientPromise).then(async (client) => {
       this.client = this.#find(client);
       this.#validate(this.client);
       this.promise = null;
       await this.client.promise;
+      this.type = this.client?.TYPE || this.type;
       return client;
     });
   }
   #find(store) {
     if (store instanceof _Store) return store.client;
     for (let client of Object.values(clients_default)) {
-      if (client.test && client.test(store)) {
+      if ("test" in client && client.test(store)) {
         return new client(store);
       }
+      if ("testKeys" in client && typeof store === "object") {
+        if (client.testKeys.every((key) => store[key])) {
+          return new client(store);
+        }
+      }
     }
     if (typeof store === "function" && /^class\s/.test(Function.prototype.toString.call(store))) {
       return new store();
@@ -652,29 +664,29 @@ var Store = class _Store {
     if (key) this.del(key);
     return false;
   }
-  async add(value, options = {}) {
+  async add(value, ttl) {
     await this.promise;
-    let expires = parse(options.expires);
+    let expires = parse(ttl);
     if (this.client.add) {
       if (this.client.EXPIRES) {
-        return await this.client.add(this.PREFIX, value, { expires });
+        return await this.client.add(this.PREFIX, value, expires);
       }
       expires = unix(expires);
       const key2 = await this.client.add(this.PREFIX, { expires, value });
       return key2;
     }
     const key = createId();
-    return this.set(key, value, { expires });
+    return this.set(key, value, expires);
   }
-  async set(key, value, options = {}) {
+  async set(key, value, ttl) {
     await this.promise;
     const id = this.PREFIX + key;
-    let expires = parse(options.expires);
+    let expires = parse(ttl);
     if (value === null || typeof expires === "number" && expires <= 0) {
       return this.del(key);
     }
     if (this.client.EXPIRES) {
-      await this.client.set(id, value, { expires });
+      await this.client.set(id, value, expires);
       return key;
     }
     expires = unix(expires);
@@ -736,12 +748,25 @@ var Store = class _Store {
       return key;
     }
     if (this.client.EXPIRES) {
-      await this.client.set(id, null, { expires: 0 });
+      await this.client.set(id, null, 0);
     } else {
       await this.client.set(id, null);
     }
     return key;
   }
+  /**
+   * @alias of .del(key: string)
+   * Remove a single key and its value from the store:
+   *
+   * ```js
+   * const key = await store.delete("key1");
+   * ```
+   *
+   * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+   */
+  async delete(key) {
+    return this.del(key);
+  }
   async *[Symbol.asyncIterator]() {
     await this.promise;
     if (this.client.EXPIRES) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "polystore",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "A small compatibility layer for many popular KV stores like localStorage, Redis, FileSystem, etc.",
-  "homepage": "https://polystore.dev/",
+  "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",

package/readme.md

@@ -1,6 +1,6 @@
 # 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://badgen.net/bundlephobia/minzip/polystore?label=gzip&color=green)](https://bundlephobia.com/package/polystore)
 
-A key-value library to unify the API of [many clients](#clients), like localStorage, Redis, FileSystem, etc:
+A key-value library to unify the API of [many clients](#clients): localStorage, Redis, FileSystem, SQLite, etc.
 
 ```js
 import kv from "polystore";
@@ -14,8 +14,8 @@ const store4 = kv(yourOwnStore); // Create a store based on your code
 These are all the methods of the [API](#api) (they are all `async`):
 
 - [`.get(key)`](#get): read a single value, or `null` if it doesn't exist or is expired.
-- [`.set(key, value, options?)`](#set): save a single value that is serializable.
-- [`.add(value, options?)`](#add): save a single value with an auto-generated key.
+- [`.set(key, value, ttl?)`](#set): save a single value that is serializable.
+- [`.add(value, ttl?)`](#add): save a single value with an auto-generated key.
 - [`.has(key)`](#has): check whether a key exists and is not expired.
 - [`.del(key)`](#del): delete a single key/value from the store.
 - [Iterator](#iterator): go through all of the key/values one by one.
@@ -197,7 +197,7 @@ await store.del('key2');
 console.log(await store.get("key2"));   // null
 
 // Expired
-await store.set("key3", "Hello", { expires: '1s' });
+await store.set("key3", "Hello", "1s");
 console.log(await store.get("key3"));   // "Hello"
 await new Promise((done) => setTimeout(done, 2000)); // Wait 2 seconds
 console.log(await store.get("key3"));   // null (already expired)
@@ -221,11 +221,11 @@ console.log(await session.get('key1'));
 Create or update a value in the store. Will return a promise that resolves with the key when the value has been saved:
 
 ```js
-await store.set(key: string, value: any, options?: { expires: number|string });
+await store.set(key: string, value: any, 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 });
+await store.set("key2", ["my", "grocery", "list"], "1h");
+await store.set("key3", { name: "Francisco" }, 60 * 60);
 ```
 
 You can specify the type either at [the store level](#api) or at the method level:
@@ -268,7 +268,7 @@ In short, only JSON-serializable data is safe to store.
 
 #### Expires
 
-When the `expires` option is set, it can be a number (**seconds**) or a string representing some time:
+When the `ttl` option is set, it can be a number (**seconds**) or a string representing some time:
 
 ```js
 // Valid "expire" values:
@@ -292,14 +292,14 @@ These are all the units available:
 Create a value in the store with an auto-generated key. 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 key:string = await store.add(value: any, 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  });
+const key2 = await store.add(["my", "grocery", "list"], "1h");
+const key3 = await store.add({ name: "Francisco" }, 60 * 60);
 ```
 
-The options and details are similar to [`.set()`](#set), except for the lack of the first argument, since `.add()` will generate the key automatically.
+The value and expires are similar to [`.set()`](#set), except for the lack of the first argument, since `.add()` will generate the key automatically.
 
 The default key is 24 AlphaNumeric characters (upper+lower case), however this can change if you are using a `.prefix()` or some clients might generate it differently (only custom clients can do that right now).
 
@@ -357,7 +357,7 @@ An example of an exception of the above is when you use it as a cache, then you
 async function fetchUser(id) {
   if (!(await store.has(id))) {
     const { data } = await axios.get(`/users/${id}`);
-    await store.set(id, data, { expires: "1h" });
+    await store.set(id, data, "1h");
   }
   return store.get(id);
 }
@@ -599,7 +599,7 @@ import kv from "polystore";
 
 const store = kv(new Map());
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -615,7 +615,7 @@ console.log(await store.get("key1"));
 
 ```js
 // GOOD - with polystore
-await store.set("key1", { name: "Francisco" }, { expires: "2days" });
+await store.set("key1", { name: "Francisco" }, "2days");
 
 // COMPLEX - With sessionStorage
 const data = new Map();
@@ -632,7 +632,7 @@ import kv from "polystore";
 
 const store = kv(localStorage);
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -651,7 +651,7 @@ Same limitations as always apply to localStorage, if you think you are going to
 
 ```js
 // GOOD - with polystore
-await store.set("key1", { name: "Francisco" }, { expires: "2days" });
+await store.set("key1", { name: "Francisco" }, "2days");
 
 // COMPLEX - With localStorage
 const serialValue = JSON.stringify({ name: "Francisco" });
@@ -668,7 +668,7 @@ import kv from "polystore";
 
 const store = kv(sessionStorage);
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -685,7 +685,7 @@ console.log(await store.get("key1"));
 
 ```js
 // GOOD - with polystore
-await store.set("key1", { name: "Francisco" }, { expires: "2days" });
+await store.set("key1", { name: "Francisco" }, "2days");
 
 // COMPLEX - With sessionStorage
 const serialValue = JSON.stringify({ name: "Francisco" });
@@ -702,7 +702,7 @@ import kv from "polystore";
 
 const store = kv("cookie"); // just a plain string
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -731,7 +731,7 @@ import localForage from "localforage";
 
 const store = kv(localForage);
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -755,7 +755,7 @@ import { createClient } from "redis";
 
 const store = kv(createClient().connect());
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -790,7 +790,7 @@ import Database from "better-sqlite3";
 const db = new Database("data.db")
 const store = kv(db);
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -862,7 +862,7 @@ import kv from "polystore";
 
 const store = kv("https://kv.example.com/");
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -882,7 +882,7 @@ import kv from "polystore";
 // Path is "/Users/me/project/cache.json"
 const store = kv("file:///Users/me/project/cache.json");
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -916,7 +916,7 @@ const store1 = kv(new URL(`file://${process.cwd()}/cache.json`));
 
 ```js
 // GOOD - with polystore
-await store.set("key1", { name: "Francisco" }, { expires: "2days" });
+await store.set("key1", { name: "Francisco" }, "2days");
 
 // COMPLEX - With native file managing
 const file = './data/users.json';
@@ -937,7 +937,7 @@ import kv from "polystore";
 
 const store = kv("file:///Users/me/project/data/");
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 // Writes "./data/key1.json"
 console.log(await store.get("key1"));
 // "Hello world"
@@ -975,7 +975,7 @@ const store1 = kv(new URL(`file://${process.cwd()}/cache/`));
 
 ```js
 // GOOD - with polystore
-await store.set("key1", { name: "Francisco" }, { expires: "2days" });
+await store.set("key1", { name: "Francisco" }, "2days");
 
 // COMPLEX - With native folder
 const file = './data/user/key1.json';
@@ -995,7 +995,7 @@ export default {
   async fetch(request, env, ctx) {
     const store = kv(env.YOUR_KV_NAMESPACE);
 
-    await store.set("key1", "Hello world", { expires: "1h" });
+    await store.set("key1", "Hello world", "1h");
     console.log(await store.get("key1"));
     // "Hello world"
 
@@ -1018,7 +1018,7 @@ It expects that you pass the namespace from Cloudflare straight as a `kv()` argu
 
 ```js
 // GOOD - with polystore
-await store.set("user", { name: "Francisco" }, { expires: "2days" });
+await store.set("user", { name: "Francisco" }, "2days");
 
 // COMPLEX - With native Cloudflare KV
 const serialValue = JSON.stringify({ name: "Francisco" });
@@ -1038,7 +1038,7 @@ import { Level } from "level";
 
 const store = kv(new Level("example", { valueEncoding: "json" }));
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -1055,7 +1055,7 @@ You will need to set the `valueEncoding` to `"json"` for the store to work as ex
 
 ```js
 // GOOD - with polystore
-await store.set("user", { hello: 'world' }, { expires: "2days" });
+await store.set("user", { hello: 'world' }, "2days");
 
 // With Level:
 ?? // Just not possible
@@ -1071,7 +1071,7 @@ import { Etcd3 } from "etcd3";
 
 const store = kv(new Etcd3());
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -1101,7 +1101,7 @@ await client.connect();
 
 const store = kv(client);
 
-await store.set("key1", "Hello world", { expires: "1h" });
+await store.set("key1", "Hello world", "1h");
 console.log(await store.get("key1"));
 // "Hello world"
 ```
@@ -1165,7 +1165,7 @@ We unify all of the clients diverse expiration methods into a single, easy one w
 ```js
 // in-memory store
 const store = polystore(new Map());
-await store.set("a", "b", { expires: "1s" });
+await store.set("a", "b", "1s");
 
 // These checks of course work:
 console.log(await store.keys()); // ['a']
@@ -1234,11 +1234,11 @@ class MyClient {
 
   // Mandatory methods
   get (key): Promise<any>;
-  set (key, value, { expires: null|number }): Promise<null>;
+  set (key, value, null|number): Promise<null>;
   iterate(prefix): AyncIterator<[string, any]>
 
   // Optional item methods (for optimization or customization)
-  add (prefix, data, { expires: null|number }): Promise<string>;
+  add (prefix, data, null|number): Promise<string>;
   has (key): Promise<boolean>;
   del (key): Promise<null>;
 
@@ -1283,7 +1283,7 @@ client.keys = (prefix) => {
 
 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
+### Plain Object client
 
 This is a good example of how simple a store can be, however do not use it literally since it behaves the same as the already-supported `new Map()`, only use it as the base for your own clients:
 
@@ -1442,3 +1442,134 @@ const store = kv(CloudflareCustom);
 ````
 
 It's lacking few things, so make sure to adapt to your needs, but it worked for my very simple cache needs.
+
+
+## Examples
+
+### Simple cache
+
+I've used Polystore in many projects as a simple cache. With `fetch()`, it's fairly easy:
+
+```ts
+async function getProductInfo(id: string) {
+  const data = await store.get(id);
+  if (data) return data;
+  
+  const res = await fetch(`https://some-url.com/products/${id}`);
+  const raw = await res.json();
+  
+  // Some processing here
+  const clean = raw??;
+  
+  await store.set(id, clean, '10days');
+  return clean;
+}
+```
+
+You can store either the raw data, or the processed data. Depending on whether the processing is sync or async, and the data size of the raw vs processing data, we pick one or the other.
+
+
+
+### Dev vs Prod
+
+With Polystore it's easy to configure your KV solution to use a different client in dev vs production. We've found particularly useful to use an easy-to-debug client in dev like [Folder](#folder) and a high-performance client in production like [Redis](#redis):
+
+```ts
+// store.ts
+import kv from "polystore";
+import { createClient } from "redis";
+
+let store;
+if (process.env.REDIS_URL) {
+  console.log('kv:redis using Redis for cache data');
+  store = kv(createClient(process.env.REDIS_URL).connect());
+} else {
+  console.log('kv:folder using a folder for cache data');
+  store = kv(`${process.cwd()}/data/`);
+}
+
+export default store;
+```
+
+
+### Better Auth
+
+Polystore is directly compatible with Better Auth, so no need for any wrapper. For example, for Redis:
+
+```ts
+import kv from "polystore";
+import { createClient } from "redis";
+import { betterAuth } from "better-auth";
+
+const secondaryStorage = kv(createClient().connect());
+
+export const auth = betterAuth({
+	// ... other options
+	secondaryStorage
+});
+````
+
+Compare that with their official documentation for using Redis:
+
+```ts
+import { createClient } from "redis";
+import { betterAuth } from "better-auth";
+
+const redis = createClient();
+await redis.connect();
+
+export const auth = betterAuth({
+	// ... other options
+	secondaryStorage: {
+		get: async (key) => {
+			return await redis.get(key);
+		},
+		set: async (key, value, ttl) => {
+			if (ttl) await redis.set(key, value, { EX: ttl });
+			// or for ioredis:
+			// if (ttl) await redis.set(key, value, 'EX', ttl)
+			else await redis.set(key, value);
+		},
+		delete: async (key) => {
+			await redis.del(key);
+		}
+	}
+});
+```
+
+### Express.js
+
+```ts
+import kv from 'polystore/express';
+
+// This is a special, Express-only store
+const store = kv();
+
+app.use(session({ store, ... }));
+````
+
+### Hono
+
+### Elysia?
+
+### Axios Cache Interceptor
+
+### @server/next
+
+> [!info]
+> @server/next is still experimental, but it's the main reason I created Polystore and so I wanted to document it as well
+
+Server.js supports Polystore directly:
+
+```ts
+import kv from "polystore";
+import server from "../../";
+
+const session = kv(new Map());
+
+export default server({ session }).get("/", (ctx) => {
+  if (!ctx.session.counter) ctx.session.counter = 0;
+  ctx.session.counter++;
+  return `User visited ${ctx.session.counter} times`;
+});
+```