polystore 0.19.0 → 0.20.0

package/index.d.ts

@@ -45,6 +45,7 @@ interface ClientNonExpires {
     values?<T extends Serializable>(prefix: string): Promise<StoreData<T>[]> | StoreData<T>[];
     entries?<T extends Serializable>(prefix: string): Promise<[string, StoreData<T>][]> | [string, StoreData<T>][];
     all?<T extends Serializable>(prefix: string): Promise<Record<string, StoreData<T>>> | Record<string, StoreData<T>>;
+    prune?(): Promise<any> | any;
     clear?(prefix: string): Promise<any> | any;
     clearAll?(): Promise<any> | any;
     close?(): Promise<any> | any;

package/index.js

@@ -244,8 +244,10 @@ var File = class extends Client {
     }
   }
   // Bulk updates are worth creating a custom method here
-  clearAll = () => this.#withLock(() => this.#write({}));
   clear = async (prefix = "") => {
+    if (!prefix) {
+      await this.#withLock(() => this.#write({}));
+    }
     return this.#withLock(async () => {
       const data = await this.#read();
       for (let key in data) {
@@ -366,8 +368,10 @@ var Level = class extends Client {
       list.map(async (k) => [k, await this.get(k)])
     );
   };
-  clearAll = () => this.client.clear();
   clear = async (prefix = "") => {
+    if (!prefix) {
+      return await this.client.clear();
+    }
     const keys = await this.client.keys().all();
     const list = keys.filter((k) => k.startsWith(prefix));
     return this.client.batch(
@@ -395,6 +399,97 @@ var Memory = class extends Client {
   clearAll = () => this.client.clear();
 };
 
+// src/clients/postgres.ts
+var Postgres = class extends Client {
+  TYPE = "POSTGRES";
+  // 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"
+  HAS_EXPIRATION = true;
+  // The table name to use
+  table = "kv";
+  // Ensure schema exists before any operation
+  promise = (async () => {
+    if (!/^[a-zA-Z_]+$/.test(this.table)) {
+      throw new Error(`Invalid table name ${this.table}`);
+    }
+    await this.client.query(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        id TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        expires_at TIMESTAMPTZ
+      )
+    `);
+    await this.client.query(
+      `CREATE INDEX IF NOT EXISTS idx_${this.table}_expires_at ON ${this.table} (expires_at)`
+    );
+  })();
+  static test = (client) => {
+    return client && client.query && !client.filename;
+  };
+  get = async (id) => {
+    const result = await this.client.query(
+      `SELECT value
+       FROM ${this.table}
+       WHERE id = $1 AND (expires_at IS NULL OR expires_at > NOW())`,
+      [id]
+    );
+    if (!result.rows.length) return null;
+    return this.decode(result.rows[0].value);
+  };
+  set = async (id, data, expires) => {
+    const value = this.encode(data);
+    const expires_at = expires ? new Date(Date.now() + expires * 1e3) : null;
+    await this.client.query(
+      `INSERT INTO ${this.table} (id, value, expires_at)
+       VALUES ($1, $2, $3)
+       ON CONFLICT (id) DO UPDATE
+       SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at`,
+      [id, value, expires_at]
+    );
+  };
+  del = async (id) => {
+    await this.client.query(`DELETE FROM ${this.table} WHERE id = $1`, [id]);
+  };
+  async *iterate(prefix = "") {
+    const result = await this.client.query(
+      `SELECT id, value FROM ${this.table}
+        WHERE (expires_at IS NULL OR expires_at > NOW()) ${prefix ? `AND id LIKE $1` : ""}`,
+      prefix ? [`${prefix}%`] : []
+    );
+    for (const row of result.rows) {
+      yield [row.id, this.decode(row.value)];
+    }
+  }
+  async keys(prefix = "") {
+    const result = await this.client.query(
+      `SELECT id FROM ${this.table}
+       WHERE (expires_at IS NULL OR expires_at > NOW())
+       ${prefix ? `AND id LIKE $1` : ""}`,
+      prefix ? [`${prefix}%`] : []
+    );
+    return result.rows.map((r) => r.id);
+  }
+  prune = async () => {
+    await this.client.query(
+      `DELETE FROM ${this.table}
+       WHERE expires_at IS NOT NULL AND expires_at <= NOW()`
+    );
+  };
+  clear = async (prefix = "") => {
+    await this.client.query(
+      `DELETE FROM ${this.table} ${prefix ? `WHERE id LIKE $1` : ""}`,
+      prefix ? [`${prefix}%`] : []
+    );
+  };
+  close = async () => {
+    if (this.client.end) {
+      await this.client.end();
+    }
+  };
+};
+
 // src/clients/redis.ts
 var Redis = class extends Client {
   TYPE = "REDIS";
@@ -470,13 +565,11 @@ var SQLite = class extends 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;
-    if (row.expires_at && row.expires_at < Date.now()) {
-      this.del(id);
-      return null;
-    }
-    return this.decode(row.value);
+    const value = this.client.prepare(
+      `SELECT value, expires_at FROM kv WHERE id = ? AND (expires_at IS NULL OR expires_at > ?)`
+    ).get(id, Date.now())?.value;
+    if (!value) return null;
+    return this.decode(value);
   };
   set = (id, data, expires) => {
     const value = this.encode(data);
@@ -485,8 +578,8 @@ var SQLite = class extends Client {
       `INSERT INTO kv (id, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`
     ).run(id, value, expires_at);
   };
-  del = async (id) => {
-    await this.client.prepare(`DELETE FROM kv WHERE id = ?`).run(id);
+  del = (id) => {
+    this.client.prepare(`DELETE FROM kv WHERE id = ?`).run(id);
   };
   has = (id) => {
     const row = this.client.prepare(`SELECT expires_at FROM kv WHERE id = ?`).get(id);
@@ -498,7 +591,6 @@ var SQLite = class extends Client {
     return true;
   };
   *iterate(prefix = "") {
-    this.#clearExpired();
     const sql = `SELECT id, value FROM kv WHERE (expires_at IS NULL OR expires_at > ?) ${prefix ? "AND id LIKE ?" : ""}
     `;
     const params = prefix ? [Date.now(), `${prefix}%`] : [Date.now()];
@@ -507,7 +599,6 @@ var SQLite = class extends Client {
     }
   }
   keys = (prefix = "") => {
-    this.#clearExpired();
     const sql = `SELECT id FROM kv WHERE (expires_at IS NULL OR expires_at > ?)
 ${prefix ? "AND id LIKE ?" : ""}
     `;
@@ -515,11 +606,15 @@ ${prefix ? "AND id LIKE ?" : ""}
     const rows = this.client.prepare(sql).all(...params);
     return rows.map((r) => r.id);
   };
-  #clearExpired = () => {
-    this.client.prepare(`DELETE FROM kv WHERE expires_at < ?`).run(Date.now());
+  prune = () => {
+    this.client.prepare(`DELETE FROM kv WHERE expires_at <= ?`).run(Date.now());
   };
-  clearAll = () => {
-    this.client.exec(`DELETE FROM kv`);
+  clear = (prefix = "") => {
+    if (!prefix) {
+      this.client.prepare(`DELETE FROM ${this.table}`).run();
+      return;
+    }
+    this.client.prepare(`DELETE FROM ${this.table} WHERE id LIKE ?`).run(`${prefix}%`);
   };
   close = () => {
     this.client.close?.();
@@ -564,8 +659,7 @@ var clients_default = {
   forage: Forage,
   level: Level,
   memory: Memory,
-  // postgres,
-  // prisma,
+  postgres: Postgres,
   redis: Redis,
   storage: WebStorage,
   sqlite: SQLite
@@ -932,13 +1026,8 @@ var Store = class _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);
-      }
+    if (this.client.prune) {
+      await this.client.prune();
     }
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "A small compatibility layer for many popular KV stores like localStorage, Redis, FileSystem, etc.",
   "homepage": "https://polystore.dev",
   "repository": "https://github.com/franciscop/polystore.git",
@@ -32,6 +32,8 @@
     "test:bun": "bun test ./test/index.test.ts",
     "test:jest": "jest ./test/index.test.ts --detectOpenHandles --forceExit",
     "run:db": "etcd",
+    "run:redis": "brew services start redis",
+    "run:postgres": "brew services start postgresql",
     "run:server": "bun ./src/server.ts"
   },
   "keywords": [
@@ -49,6 +51,7 @@
     "@types/bun": "^1.3.3",
     "@types/jest": "^30.0.0",
     "@types/jsdom": "^27.0.0",
+    "@types/pg": "^8.11.10",
     "better-sqlite3": "^12.6.0",
     "check-dts": "^0.8.0",
     "cross-fetch": "^4.1.0",
@@ -61,6 +64,7 @@
     "jsdom": "^27.2.0",
     "level": "^8.0.1",
     "localforage": "^1.10.0",
+    "pg": "^8.13.1",
     "redis": "^4.6.10",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",

package/readme.md

@@ -631,6 +631,25 @@ A client is the library that manages the low-level store operations. For example
 
 Polystore provides a unified API you can use `Promises`, `expires` and `.prefix()` even with those stores that do not support these operations natively.
 
+Quick overview:
+
+| Client | Runtime | Persistence | Native expiration | Notes |
+|---|---|---|---|---|
+| [Memory](#memory) | Node.js + Browser | ❌ | ❌ | Great for tests and ephemeral caches |
+| [Local Storage](#local-storage) | Browser | ✅ | ❌ | Persistent browser storage |
+| [Session Storage](#session-storage) | Browser | ❌ | ❌ | Cleared when tab/session ends |
+| [Cookies](#cookies) | Browser | ✅ | ✅ | Browser-side cookies |
+| [Local Forage](#local-forage) | Browser | ✅ | ❓ | Better capacity than localStorage |
+| [Redis](#redis) | Node.js | ✅ | ✅ | Good distributed cache backend |
+| [SQLite](#sqlite) | Node.js | ✅ | ❌ | Simple local persistence |
+| [Fetch API](#fetch-api) | Any with `fetch` | ❓ | ❓ | Bring your own KV HTTP API |
+| [File](#file) | Node.js | ✅ | ❌ | Single JSON file store |
+| [Folder](#folder) | Node.js | ✅ | ❌ | One-file-per-key store |
+| [Cloudflare KV](#cloudflare-kv) | Cloudflare | ✅ | ✅ | Edge-native KV |
+| [Level](#level) | Node.js | ✅ | ❌ | Uses Level ecosystem |
+| [Etcd](#etcd) | Node.js | ✅ | ✅ | Distributed KV |
+| [Postgres](#postgres) | Node.js | ✅ | ❌ | Table-backed KV |
+
 While you can keep a reference to the client and access it directly, we strongly recommend to only access it through `polystore`, since we might add custom serialization and extra properties for e.g. expiration time:
 
 ```js
@@ -1164,28 +1183,32 @@ console.log(await store.get("key1"));
 // "Hello world"
 ```
 
-You can also use `pg.Pool` instead of `pg.Client` for connection pooling.
+Polystore will initialize the schema automatically: it creates the `kv` table and expiration index if they do not exist yet, and does not fail if they already exist.
 
-Your database needs a table with three columns: `id` (text), `value` (text), and `expiresAt` (timestamp, nullable):
+Required schema (auto-created by Polystore):
 
 ```sql
-CREATE TABLE kv (
+CREATE TABLE IF NOT EXISTS kv (
   id TEXT PRIMARY KEY,
   value TEXT NOT NULL,
   "expiresAt" TIMESTAMP
 );
+
+CREATE INDEX IF NOT EXISTS idx_kv_expiresAt
+  ON kv ("expiresAt");
 ```
 
-The default table name is `kv`, but you can use different tables via `.prefix()`:
+The default table name is `kv`. Key prefixes still work as normal key namespaces:
 
 ```js
-const sessions = store.prefix("session:"); // Uses 'session' table
-const cache = store.prefix("cache:");      // Uses 'cache' table
+const sessions = store.prefix("session:");
+const cache = store.prefix("cache:");
 
 await sessions.set("user123", { name: "Alice" });
+// Stored key in Postgres: "session:user123"
 ```
 
-This maps prefixes to table names for better performance on group operations.
+This keeps a single table while preserving namespace-style grouping through prefixed keys.
 
 <details>
   <summary>Why use polystore with Postgres?</summary>
@@ -1202,7 +1225,9 @@ This maps prefixes to table names for better performance on group operations.
 
 Please see the [creating a store](#creating-a-store) section for all the details!
 
-## Performance
+## Guides
+
+### Performance
 
 > TL;DR: if you only use the item operations (add, set, get, has, del) and your client supports expiration natively, you have nothing to worry about! Otherwise, please read on.
 
@@ -1214,7 +1239,7 @@ While all of our stores support `expires`, `.prefix()` and group operations, the
 
 **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.
 
-## Expirations
+### Expirations
 
 > Warning: if a client doesn't support expiration natively, we will hide expired keys on the API calls for a nice DX, but _old data might not be evicted automatically_. See [the notes in Performance](#performance) for details on how to work around this.
 
@@ -1258,7 +1283,7 @@ These are all the units available:
 
 This is great because with polystore we do ensure that if a key has expired, it doesn't show up in `.keys()`, `.entries()`, `.values()`, `.has()` or `.get()`.
 
-### Eviction
+#### Eviction
 
 However, in some stores this does come with some potential performance disadvantages. For example, both the in-memory example above and localStorage _don't_ have a native expiration/eviction process, so we have to store that information as metadata, meaning that even to check if a key exists we need to read and decode its value. For one or few keys it's not a problem, but for large sets this can become an issue.
 
@@ -1266,7 +1291,7 @@ For other stores like Redis this is not a problem, because the low-level operati
 
 These details are explained in the respective client information.
 
-## Substores
+### Substores
 
 > There's some [basic `.prefix()` API info](#prefix) for everyday usage, this section is the in-depth explanation.
 
@@ -1280,7 +1305,46 @@ When dealing with large or complex amounts of data in a KV store, sometimes it's
 
 For these and more situations, you can use `.prefix()` to simplify your life further.
 
-## Creating a store
+### Error Handling
+
+Polystore methods return promises and surface errors from the underlying client. A good rule of thumb is to treat errors in three categories:
+
+1. **Connectivity/runtime errors**  
+   Network/database/filesystem/client runtime failures (for example Redis unavailable, failed fetch, permission denied on files).
+
+2. **Data/serialization errors**  
+   Invalid JSON payloads, invalid value encoding, or data that was written outside Polystore and cannot be decoded with its metadata expectations.
+
+3. **Usage/configuration errors**  
+   Invalid client setup, invalid URLs/paths, or unsupported operations in a specific runtime.
+
+Recommended patterns:
+
+- Use `try/catch` around all write/read operations in production paths.
+- Prefer returning safe fallbacks for cache-like usage (`null`, stale response, or refetch).
+- Log enough context (`client type`, `key`, operation name) without logging sensitive values.
+- For remote clients, consider retry/backoff only for transient failures.
+- Call `.close()` during shutdown when the client supports it.
+
+Example:
+
+```js
+const key = `user:${userId}`;
+
+try {
+  const cached = await store.get(key);
+  if (cached) return cached;
+
+  const fresh = await fetchUserFromAPI(userId);
+  await store.set(key, fresh, { expires: "10min" });
+  return fresh;
+} catch (err) {
+  console.error("polystore error", { key, err });
+  return fetchUserFromAPI(userId);
+}
+```
+
+### Creating a store
 
 To create a store, you define a class with these properties and methods:
 
@@ -1341,6 +1405,10 @@ 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).
 
+
+
+## Examples
+
 ### 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:
@@ -1371,7 +1439,7 @@ class MyClient {
 
 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
+### Custom ID generation
 
 You might want to provide your custom key generation algorithm, which I'm going to call `customId()` for example purposes. The only place where `polystore` generates IDs is in `add`, so you can provide your client with a custom generator:
 
@@ -1404,7 +1472,7 @@ const id2 = await store.prefix("hello:").add({ hello: "world" });
 // this is `hello:{your own custom id}`
 ```
 
-### Example: serializing the data
+### Serializing the data
 
 If you need to serialize the data before storing it, you can do it within your custom client. Here's an example of how you can handle data serialization when setting values:
 
@@ -1429,7 +1497,7 @@ class MyClient {
 }
 ```
 
-### Example: Cloudflare API calls
+### Cloudflare API calls
 
 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:
 
@@ -1501,9 +1569,6 @@ 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:
@@ -1514,12 +1579,9 @@ async function getProductInfo(id: string) {
   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??;
+  const data = await res.json();
   
-  await store.set(id, clean, { expires: "10days" });
+  await store.set(id, data, { expires: "10days" });
   return clean;
 }
 ```