polystore 0.16.1 → 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,17 +27,18 @@ 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));
   };
-  del = async (key) => {
-    await this.#api(key, "", "DELETE");
-  };
+  del = (key) => this.#api(key, "", "DELETE");
   async *iterate(prefix = "") {
-    const data = await this.#api("", `?prefix=${encodeURIComponent(prefix)}`);
+    const data = await this.#api(
+      "",
+      `?prefix=${encodeURIComponent(prefix)}`
+    );
     for (let [key, value] of Object.entries(data || {})) {
-      if (value !== null && value !== void 0) {
+      if (value !== null) {
         yield [prefix + key, value];
       }
     }
@@ -44,17 +47,20 @@ 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";
-  get = async (key) => this.decode(await this.client.get(key));
-  set = (key, data, opts) => {
-    const expirationTtl = opts.expires ? Math.round(opts.expires) : void 0;
+  static testKeys = ["getWithMetadata", "get", "list", "delete"];
+  get = async (key) => {
+    const value = await this.client.get(key);
+    return this.decode(value);
+  };
+  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'");
     }
-    return this.client.put(key, this.encode(data), { expirationTtl });
+    await this.client.put(key, this.encode(data), { expirationTtl });
   };
   del = (key) => this.client.delete(key);
   // Since we have pagination, we don't want to get all of the
@@ -84,12 +90,13 @@ var Cloudflare = class extends Client {
   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]]);
+    return keys.map((k, i) => [k, values[i]]).filter((p) => p[1] !== null);
   };
 };
 
 // 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
@@ -115,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 = "";
@@ -125,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;
@@ -136,12 +143,18 @@ 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";
-  get = (key) => this.client.get(key).json();
-  set = (key, value) => this.client.put(key).value(this.encode(value));
+  static testKeys = ["leaseClient", "watchClient", "watchManager"];
+  get = async (key) => {
+    const data = await this.client.get(key).json();
+    return data;
+  };
+  set = async (key, value) => {
+    await this.client.put(key).value(this.encode(value));
+  };
   del = (key) => this.client.delete().key(key).exec();
   async *iterate(prefix = "") {
     const keys = await this.client.getAll().prefix(prefix).keys();
@@ -149,12 +162,6 @@ var Etcd = class extends Client {
       yield [key, await this.get(key)];
     }
   }
-  keys = (prefix = "") => 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);
@@ -163,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;
@@ -256,6 +264,7 @@ var noFileOk = (error) => {
   throw error;
 };
 var Folder = class extends Client {
+  TYPE = "FOLDER";
   // It desn't handle expirations natively
   EXPIRES = false;
   fsp;
@@ -274,13 +283,16 @@ var Folder = class extends Client {
     });
   })();
   file = (key) => this.folder + key + ".json";
-  get = (key) => {
-    return this.fsp.readFile(this.file(key), "utf8").then(this.decode, noFileOk);
+  get = async (key) => {
+    const file = await this.fsp.readFile(this.file(key), "utf8").catch(noFileOk);
+    return this.decode(file);
   };
-  set = (key, value) => {
-    return this.fsp.writeFile(this.file(key), this.encode(value), "utf8");
+  set = async (key, value) => {
+    await this.fsp.writeFile(this.file(key), this.encode(value), "utf8");
+  };
+  del = async (key) => {
+    await this.fsp.unlink(this.file(key)).catch(noFileOk);
   };
-  del = (key) => this.fsp.unlink(this.file(key)).catch(noFileOk);
   async *iterate(prefix = "") {
     const all = await this.fsp.readdir(this.folder);
     const keys = all.filter((f) => f.startsWith(prefix) && f.endsWith(".json"));
@@ -288,7 +300,7 @@ var Folder = class extends Client {
       const key = name.slice(0, -".json".length);
       try {
         const data = await this.get(key);
-        yield [key, data];
+        if (data !== null && data !== void 0) yield [key, data];
       } catch {
         continue;
       }
@@ -298,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
@@ -331,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);
@@ -365,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
@@ -382,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 });
   };
@@ -425,12 +441,34 @@ 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"
+  // expirations much easier, so it's really "somewhere in between"
   EXPIRES = true;
-  static test = (client) => typeof client?.prepare === "function";
+  // The table name to use
+  table = "kv";
+  // Make sure the folder already exists, so attempt to create it
+  // It fails if it already exists, hence the catch case
+  promise = (async () => {
+    if (!/^[a-zA-Z_]+$/.test(this.table)) {
+      throw new Error(`Invalid table name ${this.table}`);
+    }
+    this.client.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        id TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        expires_at INTEGER
+      )
+    `);
+    this.client.exec(
+      `CREATE INDEX IF NOT EXISTS idx_${this.table}_expires_at ON ${this.table} (expires_at)`
+    );
+  })();
+  static test = (client) => {
+    return typeof client?.prepare === "function" && typeof client?.exec === "function";
+  };
   get = (id) => {
     const row = this.client.prepare(`SELECT value, expires_at FROM kv WHERE id = ?`).get(id);
     if (!row) return null;
@@ -440,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(
@@ -481,7 +519,7 @@ ${prefix ? "AND id LIKE ?" : ""}
     this.client.prepare(`DELETE FROM kv WHERE expires_at < ?`).run(Date.now());
   };
   clearAll = () => {
-    this.client.run(`DELETE FROM kv`);
+    this.client.exec(`DELETE FROM kv`);
   };
   close = () => {
     this.client.close?.();
@@ -490,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
@@ -573,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();
@@ -618,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);
@@ -702,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.16.1",
+  "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",
@@ -16,11 +16,13 @@
     "index.d.ts"
   ],
   "scripts": {
-    "analyze": "npm run build && esbuild src/index.ts --bundle --packages=external --format=esm --minify --outfile=index.min.js && gzip-size index.min.js && rm index.min.js",
+    "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",
     "build": "bunx tsup src/index.ts --format esm --dts --out-dir . --target node24",
     "lint": "npx tsc --noEmit",
     "start": "bun test --watch",
-    "test": "bun test",
+    "test": "npm run test:bun && npm run test:jest",
+    "test:bun": "bun test ./test/index.test.ts",
+    "test:jest": "jest ./test/index.test.ts --detectOpenHandles --forceExit",
     "run:db": "etcd",
     "run:server": "bun ./src/server.ts"
   },
@@ -35,21 +37,27 @@
   "license": "MIT",
   "devDependencies": {
     "@deno/kv": "^0.8.1",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "^1.3.3",
+    "@types/jest": "^30.0.0",
     "@types/jsdom": "^27.0.0",
-    "better-sqlite3": "^12.5.0",
+    "better-sqlite3": "^12.6.0",
     "check-dts": "^0.8.0",
-    "cross-fetch": "^4.0.0",
+    "cross-fetch": "^4.1.0",
     "dotenv": "^16.3.1",
     "edge-mock": "^0.0.15",
     "esbuild": "^0.27.0",
     "etcd3": "^1.1.2",
     "gzip-size-cli": "^5.1.0",
+    "jest": "^30.2.0",
     "jsdom": "^27.2.0",
     "level": "^8.0.1",
     "localforage": "^1.10.0",
     "redis": "^4.6.10",
-    "tsup": "^8.5.1"
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   },
   "documentation": {
     "title": "🏬 Polystore - A universal library for standardizing any KV-store",