polystore 0.19.0 → 0.21.0

package/readme.md

@@ -63,7 +63,7 @@ MyApi({ cache: env.KV_NAMESPACE }); // OR
 
 First, install `polystore` and whatever [supported client](#clients) that you prefer. Let's see Redis as an example here:
 
-```
+```sh
 npm i polystore redis
 ```
 
@@ -93,7 +93,7 @@ await store.del(key);
 
 ## API
 
-The base `kv()` initialization is shared across clients ([see full clients list](#clients)); single argument that receives the client or a string representing the client:
+The base `kv()` initialization is shared across clients ([see full clients list](#clients)); an argument that receives the client or a string representing the client and then the options:
 
 ```js
 import kv from "polystore";
@@ -107,7 +107,7 @@ const store = kv(MyClientInstance, { expires: null, prefix: "" });
 > [!IMPORTANT]
 > The library delivers excellent performance for item-level operations (GET, SET, ADD, HAS, DEL). For other methods or detailed guidance, check the performance considerations and consult your specific client’s documentation.
 
-You can enforce **types** for store values either at store creation or at the method level:
+You can enforce **types** for the values either at store creation or at the method level:
 
 ```ts
 const store = kv<number>(new Map());
@@ -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,158 @@ 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
+## Integrations
+
+Polystore has some easy integrations for you to use it as a simple connector.
+
+### Express
+
+Use any Polystore-compatible store as an [express-session](https://github.com/expressjs/session) store:
+
+```js
+import session from "express-session";
+import expressStore from "polystore/express";
+
+app.use(session({
+  secret: "my-secret",
+  store: expressStore(),
+}));
+```
+
+By default it uses an in-memory `Map`, which is fine for development. For production, pass any Polystore client:
+
+```js
+import { createClient } from "redis";
+// `npm install polystore`
+import expressStore from "polystore/express";
+
+const store = expressStore(createClient().connect());
+
+app.use(session({ secret: "my-secret", store }));
+```
+
+Any client works — Redis, Postgres, SQLite, file-based, etc. Session TTL is read automatically from `cookie.originalMaxAge` so you don't need to configure it separately.
+
+Use `.prefix()` to namespace sessions, for example in a multi-tenant app:
+
+```js
+const store = expressStore(createClient().connect());
+
+app.use((req, res, next) => {
+  req.sessionStore = store.prefix(`tenant:${req.params.tenant}:`);
+  next();
+});
+```
+
+### Hono Sessions
+
+Use any Polystore-compatible store as a [hono-sessions](https://github.com/jcs224/hono_sessions) store:
+
+```js
+import { Hono } from "hono";
+import { sessionMiddleware } from "hono-sessions";
+import honoStore from "polystore/hono-sessions";
+
+const app = new Hono();
+
+app.use("*", sessionMiddleware({
+  store: honoStore(),
+  encryptionKey: process.env.SESSION_KEY,
+  expireAfterSeconds: 3600,
+}));
+```
+
+By default it uses an in-memory `Map`. For production, pass any Polystore client:
+
+```js
+import { createClient } from "redis";
+import honoStore from "polystore/hono-sessions";
+
+app.use("*", sessionMiddleware({
+  store: honoStore(createClient().connect()),
+  encryptionKey: process.env.SESSION_KEY,
+  expireAfterSeconds: 3600,
+}));
+```
+
+Session TTL is derived automatically from `expireAfterSeconds` — hono-sessions writes it to `_expire` on the session data, and Polystore uses it to set the underlying store TTL for automatic cleanup.
+
+Use `.prefix()` to namespace sessions per tenant:
+
+```js
+const store = honoStore(createClient().connect());
+
+app.use("*", (c, next) => {
+  const tenant = c.req.param("tenant");
+  return sessionMiddleware({
+    store: store.prefix(`tenant:${tenant}:`),
+    encryptionKey: process.env.SESSION_KEY,
+  })(c, next);
+});
+```
+
+
+### fch
+
+[Fch](https://www.npmjs.com/package/fch) is a lightweight fetch wrapper that uses Polystore natively for caching. Pass any Polystore store as the `cache` option and GET responses are cached automatically:
+
+```js
+import fch from "fch";
+import kv from "polystore";
+
+const api = fch.create({
+  baseUrl: "https://api.example.com",
+  cache: kv(new Map(), { expires: "1h" }),
+});
+
+await api.get("/users"); // fetched from network, stored in cache
+await api.get("/users"); // served from cache
+```
+
+Swap the backend without changing anything else:
+
+```js
+import { createClient } from "redis";
+
+const api = fch.create({
+  cache: kv(createClient().connect(), { expires: "10min" }),
+});
+```
+
+You can override or skip the cache per request:
+
+```js
+const shortCache = kv(new Map(), { expires: "30s" });
+
+api.get("/realtime", { cache: null });         // skip cache
+api.get("/prices", { cache: shortCache });      // use a different cache
+```
+
+
+### @server/next
+
+> [!WARNING]
+> @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 "@server/next";
+
+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`;
+});
+```
+
+
+## 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 +1388,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 +1432,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 +1440,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 +1454,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 +1554,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 +1588,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 +1621,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 +1646,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 +1718,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 +1728,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;
 }
 ```
@@ -1548,23 +1759,3 @@ if (process.env.REDIS_URL) {
 
 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`;
-});
-```