polystore 0.17.0 → 0.19.0

package/index.d.ts

@@ -1,5 +1,8 @@
+type Prefix = string;
+type Expires = number | null | string;
 type Options = {
-    expires?: number | null | string;
+    prefix?: Prefix;
+    expires?: Expires;
 };
 type StoreData<T extends Serializable = Serializable> = {
     value: T;
@@ -9,13 +12,14 @@ type Serializable = string | number | boolean | null | (Serializable | null)[] |
     [key: string]: Serializable | null;
 };
 interface ClientExpires {
-    EXPIRES: true;
+    TYPE: string;
+    HAS_EXPIRATION: 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 +31,14 @@ interface ClientExpires {
     close?(): Promise<any> | any;
 }
 interface ClientNonExpires {
-    EXPIRES: false;
+    TYPE: string;
+    HAS_EXPIRATION: 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[];
@@ -46,12 +51,14 @@ interface ClientNonExpires {
 }
 type Client = ClientExpires | ClientNonExpires;
 
-declare class Store<TDefault extends Serializable = Serializable> {
+declare class Store<TD extends Serializable = Serializable> {
     #private;
-    PREFIX: string;
+    PREFIX: Prefix;
+    EXPIRES: Expires;
     promise: Promise<Client> | null;
     client: Client;
-    constructor(clientPromise?: any);
+    type: string;
+    constructor(clientPromise?: any, options?: Options);
     /**
      * Save the data on an autogenerated key, can add expiration as well:
      *
@@ -63,8 +70,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: TD, options?: Options): Promise<string>;
+    add<T extends TD>(value: T, options?: Options): Promise<string>;
     /**
      * Save the data on the given key, can add expiration as well:
      *
@@ -76,8 +83,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: TD, options?: Options): Promise<string>;
+    set<T extends TD>(key: string, value: T, options?: Options): Promise<string>;
     /**
      * Read a single value from the KV store:
      *
@@ -92,8 +99,8 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .get() Docs](https://polystore.dev/documentation#get)**
      */
-    get(key: string): Promise<TDefault | null>;
-    get<T extends TDefault>(key: string): Promise<T | null>;
+    get(key: string): Promise<TD | null>;
+    get<T extends TD>(key: string): Promise<T | null>;
     /**
      * Check whether a key exists or not:
      *
@@ -121,6 +128,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
      *
@@ -132,8 +150,8 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full Iterator Docs](https://polystore.dev/documentation#iterator)**
      */
-    [Symbol.asyncIterator](): AsyncGenerator<[string, TDefault], void, unknown>;
-    [Symbol.asyncIterator]<T extends TDefault>(): AsyncGenerator<[
+    [Symbol.asyncIterator](): AsyncGenerator<[string, TD], void, unknown>;
+    [Symbol.asyncIterator]<T extends TD>(): AsyncGenerator<[
         string,
         T
     ], void, unknown>;
@@ -150,8 +168,8 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .entries() Docs](https://polystore.dev/documentation#entries)**
      */
-    entries(): Promise<[string, TDefault][]>;
-    entries<T extends TDefault>(): Promise<[string, T][]>;
+    entries(): Promise<[string, TD][]>;
+    entries<T extends TD>(): Promise<[string, T][]>;
     /**
      * Return an array of the keys in the store:
      *
@@ -179,8 +197,8 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
      */
-    values(): Promise<TDefault[]>;
-    values<T extends TDefault>(): Promise<T[]>;
+    values(): Promise<TD[]>;
+    values<T extends TD>(): Promise<T[]>;
     /**
      * Return an object with the keys:values in the store:
      *
@@ -194,20 +212,24 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .all() Docs](https://polystore.dev/documentation#all)**
      */
-    all(): Promise<Record<string, TDefault>>;
-    all<T extends TDefault>(): Promise<Record<string, T>>;
+    all(): Promise<Record<string, TD>>;
+    all<T extends TD>(): Promise<Record<string, T>>;
     /**
-     * Delete all of the records of the store:
+     * Create a substore where all the keys are stored with
+     * the given prefix:
      *
      * ```js
-     * await store.clear();
+     * const session = store.prefix("session:");
+     * await session.set("key1", "value1");
+     * console.log(await session.entries());  // session.
+     * // [["key1", "value1"]]
+     * console.log(await store.entries());  // store.
+     * // [["session:key1", "value1"]]
      * ```
      *
-     * It's useful for cache invalidation, clearing the data, and testing.
-     *
-     * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+     * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
      */
-    clear(): Promise<void>;
+    prefix(prefix?: Prefix): Store<TD>;
     /**
      * Create a substore where all the keys are stored with
      * the given prefix:
@@ -223,7 +245,29 @@ declare class Store<TDefault extends Serializable = Serializable> {
      *
      * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
      */
-    prefix(prefix?: string): Store<TDefault>;
+    expires(expires?: Expires): Store<TD>;
+    /**
+     * Delete all of the records of the store:
+     *
+     * ```js
+     * await store.clear();
+     * ```
+     *
+     * It's useful for cache invalidation, clearing the data, and testing.
+     *
+     * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+     */
+    clear(): Promise<void>;
+    /**
+     * Remove all expired records from the store.
+     *
+     * ```js
+     * await store.prune();
+     * ```
+     *
+     * Only affects stores where expiration is managed by this wrapper.
+     */
+    prune(): Promise<void>;
     /**
      * Stop the connection to the store, if any:
      *
@@ -238,6 +282,6 @@ declare class Store<TDefault extends Serializable = Serializable> {
     close(): Promise<void>;
 }
 declare function createStore(): Store<Serializable>;
-declare function createStore<T extends Serializable = Serializable>(client?: any): Store<T>;
+declare function createStore<T extends Serializable = Serializable>(client?: any, options?: Options): Store<T>;
 
 export { type Client, type Serializable, Store, createStore as default };

package/index.js

@@ -1,6 +1,7 @@
 // src/clients/Client.ts
 var Client = class {
-  EXPIRES = false;
+  TYPE;
+  HAS_EXPIRATION = false;
   client;
   encode = (val) => JSON.stringify(val, null, 2);
   decode = (val) => val ? JSON.parse(val) : null;
@@ -11,8 +12,9 @@ var Client = class {
 
 // src/clients/api.ts
 var Api = class extends Client {
+  TYPE = "API";
   // Indicate that the file handler DOES handle expirations
-  EXPIRES = true;
+  HAS_EXPIRATION = true;
   static test = (client) => typeof client === "string" && /^https?:\/\//.test(client);
   #api = async (key, opts = "", method = "GET", body) => {
     const url = `${this.client.replace(/\/$/, "")}/${encodeURIComponent(key)}${opts}`;
@@ -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";
+  HAS_EXPIRATION = true;
+  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,8 +96,9 @@ var Cloudflare = class extends Client {
 
 // src/clients/cookie.ts
 var Cookie = class extends Client {
+  TYPE = "COOKIE";
   // It handles expirations natively
-  EXPIRES = true;
+  HAS_EXPIRATION = true;
   // Check if this is the right class for the given client
   static test = (client) => {
     return client === "cookie" || client === "cookies";
@@ -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;
+  HAS_EXPIRATION = 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,8 +170,9 @@ var Etcd = class extends Client {
 
 // src/clients/file.ts
 var File = class extends Client {
+  TYPE = "FILE";
   // It desn't handle expirations natively
-  EXPIRES = false;
+  HAS_EXPIRATION = false;
   fsp;
   file = "";
   #lock = Promise.resolve();
@@ -266,8 +264,9 @@ var noFileOk = (error) => {
   throw error;
 };
 var Folder = class extends Client {
+  TYPE = "FOLDER";
   // It desn't handle expirations natively
-  EXPIRES = false;
+  HAS_EXPIRATION = false;
   fsp;
   folder;
   // Check if this is the right class for the given client
@@ -311,8 +310,9 @@ var Folder = class extends Client {
 
 // src/clients/forage.ts
 var Forage = class extends Client {
+  TYPE = "FORAGE";
   // It desn't handle expirations natively
-  EXPIRES = false;
+  HAS_EXPIRATION = false;
   // Check if this is the right class for the given client
   static test = (client) => client?.defineDriver && client?.dropInstance && client?.INDEXEDDB;
   get = (key) => this.client.getItem(key);
@@ -344,10 +344,11 @@ var notFound = (error) => {
   throw error;
 };
 var Level = class extends Client {
+  TYPE = "LEVEL";
   // It desn't handle expirations natively
-  EXPIRES = false;
+  HAS_EXPIRATION = 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,8 +379,9 @@ var Level = class extends Client {
 
 // src/clients/memory.ts
 var Memory = class extends Client {
+  TYPE = "MEMORY";
   // It desn't handle expirations natively
-  EXPIRES = false;
+  HAS_EXPIRATION = false;
   // Check if this is the right class for the given client
   static test = (client) => client instanceof Map;
   get = (key) => this.client.get(key) ?? null;
@@ -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;
+  HAS_EXPIRATION = 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,11 +441,12 @@ 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
   // expirations much easier, so it's really "somewhere in between"
-  EXPIRES = true;
+  HAS_EXPIRATION = true;
   // The table name to use
   table = "kv";
   // Make sure the folder already exists, so attempt to create it
@@ -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,8 +528,9 @@ ${prefix ? "AND id LIKE ?" : ""}
 
 // src/clients/storage.ts
 var WebStorage = class extends Client {
+  TYPE = "STORAGE";
   // It desn't handle expirations natively
-  EXPIRES = false;
+  HAS_EXPIRATION = false;
   // Check if this is the right class for the given client
   static test(client) {
     if (typeof Storage === "undefined") return false;
@@ -605,23 +610,36 @@ function unix(expires) {
 // src/index.ts
 var Store = class _Store {
   PREFIX = "";
+  EXPIRES = null;
   promise;
   client;
-  constructor(clientPromise = /* @__PURE__ */ new Map()) {
+  type = "UNKNOWN";
+  constructor(clientPromise = /* @__PURE__ */ new Map(), options = {
+    prefix: "",
+    expires: null
+  }) {
+    this.PREFIX = options.prefix || "";
+    this.EXPIRES = parse(options.expires || null);
     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();
@@ -633,7 +651,7 @@ var Store = class _Store {
     if (!client.set || !client.get || !client.iterate) {
       throw new Error("Client should have .get(), .set() and .iterate()");
     }
-    if (client.EXPIRES) return;
+    if (client.HAS_EXPIRATION) return;
     for (let method of ["has", "keys", "values"]) {
       if (client[method]) {
         const msg = `You can only define client.${method}() when the client manages the expiration.`;
@@ -641,50 +659,48 @@ var Store = class _Store {
       }
     }
   }
-  // Check if the given data is fresh or not; if
+  // Check if the given data is fresh or not
   #isFresh(data, key) {
     if (!data || typeof data !== "object" || !("value" in data)) {
-      if (key) this.del(key);
       return false;
     }
-    if (data.expires === null) return true;
-    if (data.expires > Date.now()) return true;
-    if (key) this.del(key);
-    return false;
+    return data.expires === null || data.expires > Date.now();
   }
-  async add(value, options = {}) {
+  // Normalize returns the instance's `prefix` and `expires`
+  #expiration(expires) {
+    return parse(expires !== void 0 ? expires : this.EXPIRES);
+  }
+  async add(value, options) {
     await this.promise;
-    let expires = parse(options.expires);
+    const expires = this.#expiration(options?.expires);
+    const prefix = options?.prefix || this.PREFIX;
     if (this.client.add) {
-      if (this.client.EXPIRES) {
-        return await this.client.add(this.PREFIX, value, { expires });
+      if (this.client.HAS_EXPIRATION) {
+        return this.client.add(prefix, value, expires);
       }
-      expires = unix(expires);
-      const key2 = await this.client.add(this.PREFIX, { expires, value });
-      return key2;
+      return this.client.add(prefix, { expires: unix(expires), value });
     }
-    const key = createId();
-    return this.set(key, value, { expires });
+    return this.set(createId(), value, { prefix, expires });
   }
-  async set(key, value, options = {}) {
+  async set(key, value, options) {
     await this.promise;
-    const id = this.PREFIX + key;
-    let expires = parse(options.expires);
+    const expires = this.#expiration(options?.expires);
+    const prefix = options?.prefix || this.PREFIX;
+    const id = prefix + key;
     if (value === null || typeof expires === "number" && expires <= 0) {
       return this.del(key);
     }
-    if (this.client.EXPIRES) {
-      await this.client.set(id, value, { expires });
+    if (this.client.HAS_EXPIRATION) {
+      await this.client.set(id, value, expires);
       return key;
     }
-    expires = unix(expires);
-    await this.client.set(id, { expires, value });
+    await this.client.set(id, { expires: unix(expires), value });
     return key;
   }
   async get(key) {
     await this.promise;
     const id = this.PREFIX + key;
-    if (this.client.EXPIRES) {
+    if (this.client.HAS_EXPIRATION) {
       const data = await this.client.get(id) ?? null;
       if (data === null) return null;
       return data;
@@ -735,16 +751,29 @@ var Store = class _Store {
       await this.client.del(id);
       return key;
     }
-    if (this.client.EXPIRES) {
-      await this.client.set(id, null, { expires: 0 });
+    if (this.client.HAS_EXPIRATION) {
+      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) {
+    if (this.client.HAS_EXPIRATION) {
       for await (const [name, data] of this.client.iterate(this.PREFIX)) {
         const key = name.slice(this.PREFIX.length);
         yield [key, data];
@@ -762,7 +791,7 @@ var Store = class _Store {
     await this.promise;
     const trim = (key) => key.slice(this.PREFIX.length);
     if (this.client.entries) {
-      if (this.client.EXPIRES) {
+      if (this.client.HAS_EXPIRATION) {
         const entries = await this.client.entries(this.PREFIX);
         return entries.map(([k, v]) => [trim(k), v]);
       } else {
@@ -770,7 +799,7 @@ var Store = class _Store {
         return entries.map(([k, v]) => [trim(k), v]).filter(([key, data]) => this.#isFresh(data, key)).map(([key, data]) => [key, data.value]);
       }
     }
-    if (this.client.EXPIRES) {
+    if (this.client.HAS_EXPIRATION) {
       const list = [];
       for await (const [k, v] of this.client.iterate(this.PREFIX)) {
         list.push([trim(k), v]);
@@ -812,7 +841,7 @@ var Store = class _Store {
   async values() {
     await this.promise;
     if (this.client.values) {
-      if (this.client.EXPIRES) return this.client.values(this.PREFIX);
+      if (this.client.HAS_EXPIRATION) return this.client.values(this.PREFIX);
       const list = await this.client.values(this.PREFIX);
       return list.filter((data) => this.#isFresh(data)).map((data) => data.value);
     }
@@ -823,6 +852,52 @@ var Store = class _Store {
     const entries = await this.entries();
     return Object.fromEntries(entries);
   }
+  /**
+   * Create a substore where all the keys are stored with
+   * the given prefix:
+   *
+   * ```js
+   * const session = store.prefix("session:");
+   * await session.set("key1", "value1");
+   * console.log(await session.entries());  // session.
+   * // [["key1", "value1"]]
+   * console.log(await store.entries());  // store.
+   * // [["session:key1", "value1"]]
+   * ```
+   *
+   * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+   */
+  prefix(prefix = "") {
+    const store = new _Store(
+      Promise.resolve(this.promise).then(() => this.client)
+    );
+    store.PREFIX = this.PREFIX + prefix;
+    store.EXPIRES = this.EXPIRES;
+    return store;
+  }
+  /**
+   * Create a substore where all the keys are stored with
+   * the given prefix:
+   *
+   * ```js
+   * const session = store.prefix("session:");
+   * await session.set("key1", "value1");
+   * console.log(await session.entries());  // session.
+   * // [["key1", "value1"]]
+   * console.log(await store.entries());  // store.
+   * // [["session:key1", "value1"]]
+   * ```
+   *
+   * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+   */
+  expires(expires = null) {
+    const store = new _Store(
+      Promise.resolve(this.promise).then(() => this.client)
+    );
+    store.EXPIRES = parse(expires);
+    store.PREFIX = this.PREFIX;
+    return store;
+  }
   /**
    * Delete all of the records of the store:
    *
@@ -846,26 +921,25 @@ var Store = class _Store {
     await Promise.all(keys.map((key) => this.del(key)));
   }
   /**
-   * Create a substore where all the keys are stored with
-   * the given prefix:
+   * Remove all expired records from the store.
    *
    * ```js
-   * const session = store.prefix("session:");
-   * await session.set("key1", "value1");
-   * console.log(await session.entries());  // session.
-   * // [["key1", "value1"]]
-   * console.log(await store.entries());  // store.
-   * // [["session:key1", "value1"]]
+   * await store.prune();
    * ```
    *
-   * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+   * Only affects stores where expiration is managed by this wrapper.
    */
-  prefix(prefix = "") {
-    const store = new _Store(
-      Promise.resolve(this.promise).then(() => this.client)
-    );
-    store.PREFIX = this.PREFIX + prefix;
-    return store;
+  async prune() {
+    await this.promise;
+    if (this.client.HAS_EXPIRATION) return;
+    for await (const [name, data] of this.client.iterate(
+      this.PREFIX
+    )) {
+      const key = name.slice(this.PREFIX.length);
+      if (!this.#isFresh(data, key)) {
+        await this.del(key);
+      }
+    }
   }
   /**
    * Stop the connection to the store, if any:
@@ -885,8 +959,8 @@ var Store = class _Store {
     }
   }
 };
-function createStore(client) {
-  return new Store(client);
+function createStore(client, options) {
+  return new Store(client, options);
 }
 export {
   createStore as default

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "polystore",
-  "version": "0.17.0",
+  "version": "0.19.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",
@@ -11,9 +11,17 @@
   "sideEffects": false,
   "main": "index.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./express": "./src/express.js"
+  },
   "files": [
     "index.js",
-    "index.d.ts"
+    "index.d.ts",
+    "src/express.js"
   ],
   "scripts": {
     "analyze": "npm run build && esbuild src/index.ts --bundle --packages=external --format=esm --minify --outfile=index.min.js && echo 'Final size:' && gzip-size index.min.js && rm index.min.js",

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";
@@ -18,14 +18,16 @@ These are all the methods of the [API](#api) (they are all `async`):
 - [`.add(value, options?)`](#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.
+- [`.prefix(prefix)`](#prefix): create a sub-store that manages the keys with that prefix.
+- [`.expires(expires)`](#expires): create a sub-store with a different default expiration.
 - [Iterator](#iterator): go through all of the key/values one by one.
 - [`.keys()`](#keys): get a list of all the available keys in the store.
 - [`.values()`](#values): get a list of all the available values in the store.
 - [`.entries()`](#entries): get a list of all the available key-value pairs.
 - [`.all()`](#all): get an object of all the key:values mapped.
-- [`.clear()`](#clear): delete ALL of the data in the store, effectively resetting it.
+- [`.clear()`](#clear): delete **all** of the data in the store, effectively resetting it.
+- [`.prune()`](#prune): delete only the **expired** data from the store.
 - [`.close()`](#close): (only _some_ stores) ends the connection to the store.
-- [`.prefix(prefix)`](#prefix): create a sub-store that manages the keys with that prefix.
 
 Available clients for the KV store:
 
@@ -97,7 +99,7 @@ The base `kv()` initialization is shared across clients ([see full clients list]
 import kv from "polystore";
 
 // Initialize it; NO "new"; NO "await", just a plain function wrap:
-const store = kv(MyClientOrStoreInstance);
+const store = kv(MyClientInstance, { expires: null, prefix: "" });
 
 // use the store
 ```
@@ -120,23 +122,24 @@ store.get<number>("abc"); // number | null
 store.set<number>("abc", 10);
 
 store.set<number>("abc", "hello"); // FAILS
-````
+```
 
 > [!WARNING]
-> If you enforce types at _both_ the store level and method level, the method type must be a subset of the store type. For example, `kv<string | number>().get<string>("a")` works, but `kv<string>().get<number>("a")` _won't work_.
+> If you enforce types at _both_ the store level and method level, the method type must be a subset of the store type. For example, `kv<string | number>().get<string>("a")` works, but `kv<string>().get<number>("a")` will show an error as expected.
 
 Store values must be JSON-like data. The Serializable type represents values composed of `string`, `number`, `boolean`, `null`, and `arrays` and plain `objects` whose values are serializable. Class instances or non-plain objects will lose their prototypes and methods when stored.
 
-These are the exported types, `Client`, `Serializable` and `Store`:
+These are the exported types, `Client`, `Serializable`, `Store` and `Options`:
 
 ```ts
 import kv from "polystore";
-import type { Client, Serializable, Store } from "polystore";
+import type { Client, Serializable, Store, Options } from "polystore";
 
 const client: Client = ...;  // See #creating-a-store
-const store: Store = kv(client);
-const value: Serializable = store.get('hello');
-````
+const store: Store = kv(client, opts as Options);
+const key = await store.set('hello', 'b', opts as Options)
+const value: Serializable = await store.get('hello');
+```
 
 ### .get()
 
@@ -150,7 +153,7 @@ console.log(await store.get("key2"));  // ["my", "grocery", "list"]
 console.log(await store.get("key3"));  // { name: "Francisco" }
 ```
 
-You can specify the type either at [the store level](#api) or at the method level:
+You can specify the type of the return:
 
 ```ts
 console.log(await store.get<string>("key1"));  // "Hello World"
@@ -197,15 +200,12 @@ await store.del('key2');
 console.log(await store.get("key2"));   // null
 
 // Expired
-await store.set("key3", "Hello", { expires: '1s' });
+await store.set("key3", "Hello", { expires: "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)
 ```
 
-> [!WARNING]
-> Attempting to read an expired key that wasn't automatically evicted will trigger a delete internally. This should not affect you directly, but it's good to know since you might expect a `read` operation not to modify the underlying data. See the [Eviction](#eviction) section and your specific client for details.
-
 If you are using a substore with `.prefix()`, `.get()` will respect it:
 
 ```ts
@@ -220,8 +220,12 @@ 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 });
+```ts
+const key = await store.set(
+  key: string,
+  value: any,
+  options?: { expires?: number|string; prefix?: string }
+);
 
 await store.set("key1", "Hello World");
 await store.set("key2", ["my", "grocery", "list"], { expires: "1h" });
@@ -292,14 +296,17 @@ 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,
+  options?: { expires?: number|string; prefix?: 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 key3 = await store.add({ name: "Francisco" }, { expires: 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 options are similar to [`.set()`](#set), except for the lack of the first argument, since `.add()` automatically generates the key.
 
 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).
 
@@ -346,7 +353,7 @@ In many cases, internally the check for `.has()` is the same as `.get()`, so if
 
 ```js
 const val = await store.get("key1");
-if (val) { ... }
+if (val !== null) { ... }
 ```
 
 An example of an exception of the above is when you use it as a cache, then you can write code like this:
@@ -379,7 +386,7 @@ const has3 = await store.has("session:key1");
 Remove a single key from the store and return the key itself:
 
 ```js
-await store.del(key: string);
+const key = await store.del(key: string);
 ```
 
 It will ignore the operation if the key or value don't exist already (but won't throw). The API makes it easy to delete multiple keys at once:
@@ -387,7 +394,7 @@ It will ignore the operation if the key or value don't exist already (but won't
 ```js
 const keys = ["key1", "key2"];
 await Promise.all(keys.map(store.del));
-console.log(done);
+console.log("done");
 ```
 
 An example with a prefix:
@@ -411,7 +418,7 @@ for await (const [key, value] of store) {
 }
 ```
 
-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 asynchronously while the async iterator is running.
+This is very useful for performance reasons 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 asynchronously 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)):
 
@@ -428,11 +435,11 @@ for await (const [key, value] of store.prefix("session:")) {
 }
 ```
 
-There are also methods to retrieve all of the keys, values, or entries at once below, but those [have worse performance](#performance).
+There are also methods to retrieve all the keys, values, or entries at once below, but those [have worse performance](#performance).
 
 ### .keys()
 
-Get all of the keys in the store as a simple array of strings:
+Get all the keys in the store as a simple array of strings:
 
 ```js
 await store.keys();
@@ -446,11 +453,11 @@ const sessions = await store.prefix("session:").keys();
 // ["keyA", "keyB"]
 ```
 
-> We ensure that all of the keys returned by this method are _not_ expired, while discarding any potentially expired key. See [**expirations**](#expirations) for more details.
+> We ensure that all the keys returned by this method are _not_ expired, while discarding any potentially expired key. See [**expirations**](#expirations) for more details.
 
 ### .values()
 
-Get all of the values in the store as a simple array with all the values:
+Get all the values in the store as a simple array with all the values:
 
 ```js
 await store.values();
@@ -467,11 +474,11 @@ const companies = await store.prefix("company:").values();
 // 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 [**expirations**](#expirations) for more details.
+> We ensure that all the values returned by this method are _not_ expired, while discarding any potentially expired key. See [**expirations**](#expirations) for more details.
 
 ### .entries()
 
-Get all of the entries (key:value tuples) in the store:
+Get all the entries (key:value tuples) in the store:
 
 ```js
 const entries = await store.entries();
@@ -512,31 +519,57 @@ const sessionObj = await store.prefix('session:').all();
 
 ### .clear()
 
-Remove all of the data from the client and resets it to the original state:
+Remove all data from the current store and resets it to the original state:
 
 ```js
 await store.clear();
 ```
 
+If called on a `.prefix()` substore, only keys with that prefix are removed:
+
+```ts
+const sessions = store.prefix("session:");
+
+await sessions.clear();
+// removes only session:* keys
+````
+
+### .prune()
+
+> [!IMPORTANT]
+> For stores with native expiration (Redis, Cloudflare KV, etc.), `.prune()` usually does nothing because the underlying client already removes expired keys automatically.
+
+Remove only expired records from the store.
+
+```ts
+await store.prune();
+```
+
+This method is only useful for stores that do not support native expiration (such as Map, localStorage, files, etc.). In those cases expired records are hidden by the API but may still exist internally until they are removed.
+
+Calling `.prune()` scans the store and deletes all expired entries.
+
+This operation is O(n) and should typically be run in a scheduled job or maintenance task rather than on every request.
+
 ### .close()
 
-Close the connetion (if any) from the client:
+Close the connection (if any) from the client:
 
 ```js
 await store.close();
-````
+```
 
 ### .prefix()
 
-> There's [an in-depth explanation about Substores](#substores) that is very informative for production usage.
-
-Creates **a new instance** of the Store, _with the same client_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the client. You only write `.prefix()` once and then don't need to worry about any prefix for any method anymore, it's all automatic. It's **the only method** that you don't need to await:
+Creates **a new instance** of the Store, _with the same client_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the client. You only write `.prefix()` once and then don't need to worry about any prefix for any method anymore, it's all automatic. You don't need to await for it:
 
 ```js
 const store = kv(new Map());
 const session = store.prefix("session:");
 ```
 
+> There's [an in-depth explanation about Substores](#substores) that is very informative for production usage.
+
 Then all of the operations will be converted internally to add the prefix when reading, writing, etc:
 
 ```js
@@ -567,6 +600,31 @@ const books = kv(`file://${import.meta.dirname}/books.json`);
 
 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_.
 
+### .expires()
+
+Create a substore with a different default expiration time.
+
+```ts
+const store = kv(new Map());   // No expiration
+const cache = store.expires("10min");  // 10 min expiration
+await cache.set("a", "b");  // 10 mins
+await cache.set("c", "e", { expires: '5s' });  // 5 seconds, overwrites it
+```
+
+> There's [an in-depth explanation about Expirations](#expirations) that is very informative for production usage.
+
+But applied automatically to all writes in the substore. Explicit expiration always overrides the default:
+
+```ts
+await cache.set("a", "b", { expires: "1h" });
+```
+
+You can combine it with .prefix():
+
+```ts
+const sessions = store.prefix("session:").expires("1day");
+```
+
 ## Clients
 
 A client is the library that manages the low-level store operations. For example, the Redis Client, or the browser's `localStorage` API. In some exceptions it's just a string and we do a bit more work on Polystore, like with `"cookie"` or `"file:///users/me/data.json"`.
@@ -617,7 +675,7 @@ console.log(await store.get("key1"));
 // GOOD - with polystore
 await store.set("key1", { name: "Francisco" }, { expires: "2days" });
 
-// COMPLEX - With sessionStorage
+// COMPLEX - With plain Map
 const data = new Map();
 data.set("key1", { name: "Francisco" });
 // Expiration not supported
@@ -830,13 +888,13 @@ db.exec(`
 db.exec(
   `CREATE INDEX IF NOT EXISTS idx_kv_expires_at ON kv (expires_at)`,
 );
-````
+```
 
 #### SQLite expirations
 
 If `expires` is provided, Polystore will convert it to a timestamp and persist it in `expires_at`. We handle reading/writing rows and expiration checks.
 
-However, these are not auto-evicted since SQLite doesn't have native expiration eviction. To avoid having stale data that is not used anymore, it's recommended you set a periodic check and clear expired records manually.
+Expired rows remain in the table unless you delete them manually. To avoid having stale data that is not used anymore, it's recommended you set a periodic check and clear expired records manually.
 
 There's many ways of doing this, but a simple/basic one is this:
 
@@ -845,7 +903,7 @@ There's many ways of doing this, but a simple/basic one is this:
 setInterval(() => {
   db.prepare(`DELETE FROM kv WHERE expires_at < ?`).run(Date.now());
 }, 10 * 60 * 1000);
-````
+```
 
 Note that Polystore is self-reliant and won't have any problem even if you don't set that script, it will never render a stale record. It's just for both your convenience and privacy reasons.
 
@@ -867,14 +925,14 @@ console.log(await store.get("key1"));
 // "Hello world"
 ```
 
-> Note: the API 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.
+> Note: the API client expire resolution is in 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.
 
 > Note: see the [reference implementation in src/server.js](https://github.com/franciscop/polystore/blob/master/src/server.js)
 
 
 ### File
 
-Treat a JSON file in your filesystem as the source for the KV store. Pass it an absolute `file://` url or a `new URL('file://...')` instance:
+Treat a JSON file in your filesystem as the source for the KV store. Pass it an absolute `file://` url or a `new URL("file://...")` instance:
 
 ```js
 import kv from "polystore";
@@ -1150,9 +1208,9 @@ Please see the [creating a store](#creating-a-store) section for all the details
 
 While all of our stores support `expires`, `.prefix()` and group operations, the nature of those makes them to have different performance characteristics.
 
-**Expires** we polyfill expiration when the underlying client library does not support it. The impact on read/write operations and on data size of each key should be minimal. However, it can have a big impact in storage size, since the expired keys are not evicted automatically. Note that when attempting to read *an expired key*, polystore **will delete that key**. However, if an expired key is never read, it would remain in the datastore and could create some old-data issues. This is **especially important where sensitive data is involved**! To fix this, the easiest way is calling `await store.entries();` on a cron job and that should evict all of the old keys (this operation is O(n) though, so not suitable for calling it on EVERY API call, see the next point).
+**Expires** we polyfill expiration when the underlying client library does not support it. The impact on read/write operations and on data size of each key should be minimal. However, it can have a big impact in storage size, since the expired keys are not evicted automatically. Expired keys remain in the datastore and could create some old-data issues. This is **especially important where sensitive data is involved**! To fix this, the easiest way is calling `await store.prune();` on a cron job and that should evict all of the old keys (this operation is O(n) though, so not suitable for calling it on EVERY API call, see the next point).
 
-**Group operations** these are there mostly for small datasets only, for one-off scripts or for dev purposes, since by their own nature they can _never_ be high performance in the general case. But this is normal if you think about traditional DBs, reading a single record by its ID is O(1), while reading all of the IDs in the DB into an array is going to be O(n). Same applies with polystore.
+**Group operations** are mostly intended for small datasets, for one-off scripts or for dev purposes, since by their own nature they can _never_ be high performance in the general case. But this is normal if you think about traditional DBs, reading a single record by its ID is O(1), while reading all of the IDs in the DB into an array is going to be O(n). Same applies with polystore.
 
 **Substores** when dealing with a `.prefix()` substore, the same applies. Item operations should see no performance degradation from `.prefix()`, but group operations follow the above performance considerations. Some engines might have native prefix support, so performance in those is better for group operations in a substore than the whole store. But in general you should consider `.prefix()` as a convenient way of classifying your keys and not as a performance fix for group operations.
 
@@ -1164,7 +1222,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());
+const store = kv(new Map());
 await store.set("a", "b", { expires: "1s" });
 
 // These checks of course work:
@@ -1214,7 +1272,7 @@ These details are explained in the respective client information.
 
 What `.prefix()` does is it creates **a new instance** of the Store, _with the same client_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the client. The issue is that support from the underlying clients is inconsistent.
 
-When dealing with large or complex amounts of data in a KV store, some times it's useful to divide them by categories. Some examples might be:
+When dealing with large or complex amounts of data in a KV store, sometimes it's useful to divide them by categories. Some examples might be:
 
 - You use KV as a cache, and have different categories of data.
 - You use KV as a session store, and want to differentiate different kinds of sessions.
@@ -1230,15 +1288,15 @@ To create a store, you define a class with these properties and methods:
 class MyClient {
   // If this is set to `true`, the CLIENT (you) handle the expiration, so
   // the `.set()` and `.add()` receive a `expires` that is a `null` or `number`:
-  EXPIRES = false;
+  HAS_EXPIRATION = false;
 
   // Mandatory methods
   get (key): Promise<any>;
-  set (key, value, { expires: null|number }): Promise<null>;
-  iterate(prefix): AyncIterator<[string, any]>
+  set (key, value, null|number): Promise<null>;
+  iterate(prefix): AsyncIterator<[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>;
 
@@ -1255,7 +1313,7 @@ class MyClient {
 
 Note that this is NOT the public API, it's the internal **client** API. It's simpler than the public API since we do some of the heavy lifting as an intermediate layer (e.g. for the client, the `expires` will always be a `null` or `number`, never `undefined` or a `string`), but also it differs from polystore's public API, like `.add()` has a different signature, and the group methods all take a explicit prefix.
 
-**Expires**: if you set the `EXPIRES = true`, then you are indicating that the client WILL manage the lifecycle of the data. This includes all methods, for example if an item is expired, then its key should not be returned in `.keys()`, it's value should not be returned in `.values()`, and the method `.has()` will return `false`. The good news is that you will always receive the option `expires`, which is either `null` (no expiration) or a `number` indicating the **seconds** for the key/value to will expire.
+**Expires**: if you set the `HAS_EXPIRATION = true`, then you are indicating that the client WILL manage the lifecycle of the data. This includes all methods, for example if an item is expired, then its key should not be returned in `.keys()`, it's value should not be returned in `.values()`, and the method `.has()` will return `false`. The good news is that you will always receive the option `expires`, which is either `null` (no expiration) or a `number` indicating the **seconds** for the key/value to will expire.
 
 **Prefix**: we manage the `prefix` as an invisible layer on top, you only need to be aware of it in the `.add()` method, as well as in the group methods:
 
@@ -1283,7 +1341,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:
 
@@ -1311,7 +1369,7 @@ class MyClient {
 }
 ```
 
-We don't set `EXPIRES` to true since plain objects do NOT support expiration natively. So by not adding the `EXPIRES` property, it's the same as setting it to `false`, and polystore will manage all the expirations as a layer on top of the data. We could be more explicit and set it to `EXPIRES = false`, but it's not needed in this case.
+We don't set `HAS_EXPIRATION` to true since plain objects do NOT support expiration natively. So by not adding the `HAS_EXPIRATION` property, it's the same as setting it to `false`, and polystore will manage all the expirations as a layer on top of the data. We could be more explicit and set it to `HAS_EXPIRATION = false`, but it's not needed in this case.
 
 ### Example: custom ID generation
 
@@ -1321,10 +1379,10 @@ You might want to provide your custom key generation algorithm, which I'm going
 class MyClient {
 
   // Add the opt method .add() to have more control over the ID generation
-  async add (prefix, data, { expires }) {
+  async add (prefix, data, expires) {
     const id = customId();
     const key = prefix + id;
-    return this.set(key, data, { expires });
+    return this.set(key, data, expires);
   }
 
   //
@@ -1375,7 +1433,7 @@ class MyClient {
 
 In this example on one of my projects, I needed to use Cloudflare's REST API since I didn't have access to any KV store I was happy with on Netlify's Edge Functions. So I created it like this:
 
-> Warning: this code snippet is an experimental example and hasn't gone through rigurous testing as the rest of the library, so please treat with caution.
+> Warning: this code snippet is an experimental example and hasn't gone through rigorous testing as the rest of the library, so please treat with caution.
 
 ```js
 const {
@@ -1392,7 +1450,7 @@ const headers = {
 };
 
 class CloudflareCustom {
-  EXPIRES = true;
+  HAS_EXPIRATION = true;
 
   async get(key) {
     const res = await fetch(`${baseUrl}/values/${key}`, { headers });
@@ -1439,6 +1497,74 @@ class CloudflareCustom {
 }
 
 const store = kv(CloudflareCustom);
-````
+```
+
+It's lacking a 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, { expires: "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.
 
-It's lacking few things, so make sure to adapt to your needs, but it worked for my very simple cache needs.
+
+
+### 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(`file://${process.cwd()}/data/`);
+}
+
+export default store;
+```
+
+### @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`;
+});
+```

package/src/express.js

@@ -0,0 +1,47 @@
+import session from "express-session";
+import kv from "../index.js";
+
+const ttlFromSession = (data) => {
+  const maxAge = data?.cookie?.originalMaxAge;
+  return typeof maxAge === "number" ? Math.ceil(maxAge / 1000) : null;
+};
+
+export class PolystoreSessionStore extends session.Store {
+  constructor(store) {
+    super();
+    this.store = store;
+  }
+
+  prefix(prefix = "") {
+    return new PolystoreSessionStore(this.store.prefix(prefix));
+  }
+
+  get(sid, cb) {
+    this.store.get(sid).then((data) => cb(null, data)).catch(cb);
+  }
+
+  set(sid, data, cb) {
+    this.store
+      .set(sid, data, ttlFromSession(data))
+      .then(() => cb && cb())
+      .catch((error) => cb && cb(error));
+  }
+
+  destroy(sid, cb) {
+    this.store
+      .del(sid)
+      .then(() => cb && cb())
+      .catch((error) => cb && cb(error));
+  }
+
+  touch(sid, data, cb) {
+    this.store
+      .set(sid, data, ttlFromSession(data))
+      .then(() => cb && cb())
+      .catch((error) => cb && cb(error));
+  }
+}
+
+export default function expressStore(client = new Map()) {
+  return new PolystoreSessionStore(kv(client));
+}