polystore 0.15.13 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.15.13",
+  "version": "0.16.1",
   "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",
@@ -9,18 +9,20 @@
   "author": "Francisco Presencia <public@francisco.io> (https://francisco.io/)",
   "type": "module",
   "sideEffects": false,
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
+  "main": "index.js",
+  "types": "index.d.ts",
   "files": [
-    "src/"
+    "index.js",
+    "index.d.ts"
   ],
   "scripts": {
-    "analyze": "esbuild ./ --bundle --packages=external --format=esm --minify --outfile=index.min.js && gzip-size index.min.js && rm index.min.js",
-    "lint": "check-dts test/index.types.ts",
-    "start": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch --coverage --detectOpenHandles",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --ci --watchAll=false --detectOpenHandles",
-    "db": "etcd",
-    "server": "bun ./src/server.js"
+    "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",
+    "build": "bunx tsup src/index.ts --format esm --dts --out-dir . --target node24",
+    "lint": "npx tsc --noEmit",
+    "start": "bun test --watch",
+    "test": "bun test",
+    "run:db": "etcd",
+    "run:server": "bun ./src/server.ts"
   },
   "keywords": [
     "kv",
@@ -33,16 +35,21 @@
   "license": "MIT",
   "devDependencies": {
     "@deno/kv": "^0.8.1",
+    "@types/bun": "^1.3.3",
+    "@types/jsdom": "^27.0.0",
+    "better-sqlite3": "^12.5.0",
     "check-dts": "^0.8.0",
     "cross-fetch": "^4.0.0",
     "dotenv": "^16.3.1",
     "edge-mock": "^0.0.15",
+    "esbuild": "^0.27.0",
     "etcd3": "^1.1.2",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
+    "gzip-size-cli": "^5.1.0",
+    "jsdom": "^27.2.0",
     "level": "^8.0.1",
     "localforage": "^1.10.0",
-    "redis": "^4.6.10"
+    "redis": "^4.6.10",
+    "tsup": "^8.5.1"
   },
   "documentation": {
     "title": "🏬 Polystore - A universal library for standardizing any KV-store",
@@ -54,16 +61,5 @@
       "Get help": "https://superpeer.com/francisco/-/javascript-and-react-help",
       "Github": "https://github.com/franciscop/polystore"
     }
-  },
-  "jest": {
-    "testTimeout": 15000,
-    "testEnvironment": "jsdom",
-    "setupFiles": [
-      "./test/setup.js"
-    ],
-    "transform": {},
-    "modulePathIgnorePatterns": [
-      "test/cloudflare"
-    ]
   }
 }

package/readme.md

@@ -42,6 +42,8 @@ Available clients for the KV store:
 - [**Cloudflare KV** `env.KV_NAMESPACE`](#cloudflare-kv) (be): use Cloudflare's KV store
 - [**Level** `new Level('example', { valueEncoding: 'json' })`](#level) (fe+be): support the whole Level ecosystem
 - [**Etcd** `new Etcd3()`](#etcd) (be): the Microsoft's high performance KV store.
+- [**Postgres** `pool`](#postgres) (be): use PostgreSQL with the pg library
+- [**Prisma** `prisma.store`](#prisma) (be): use Prisma ORM as a key-value store
 - [**_Custom_** `{}`](#creating-a-store) (fe+be): create your own store with just 3 methods!
 
 I made this library to be used as a "building block" of other libraries, so that _your library_ can accept many cache stores effortlessly! It's universal (Node.js, Bun and the Browser) and tiny (~3KB). For example, let's say you create an API library, then you can accept the stores from your client:
@@ -74,7 +76,7 @@ import { createClient } from "redis";
 const REDIS = process.env.REDIS_URL;
 
 // Wrap the redis creation with Polystore (kv())
-const store = kv(createClient(REDIS).connect());
+const store = kv(createClient({ url: REDIS }).connect());
 ```
 
 Now your store is ready to use! Add, set, get, del different keys. [See full API](#api).
@@ -101,21 +103,37 @@ const store = kv(MyClientOrStoreInstance);
 // use the store
 ```
 
-While you can keep a reference to the store and access it directly, we strongly recommend if you are going to use a store, to only access it through `polystore`, since we might add custom serialization and extra properties for e.g. expiration time:
+The above represents the recommended naming; the default export, `kv` in this case, is a wrapper that will generate a "store" that then you use all around your codebase.
 
-```js
-const map = new Map();
-const store = kv(map);
+You can enforce the **types** for the store values directly at the store creation, or at the method level:
 
-// Works as expected
-await store.set("a", "b");
-console.log(await store.get("a"));
+```ts
+const store = kv<number>(new Map());
+store.get("abc"); // number | null
+store.set("abc", 10);
 
-// DON'T DO THIS; this will break the app since we apply more
-// advanced serialization to the values stored in memory
-map.set("a", "b");
-console.log(await store.get("a")); // THROWS ERROR
-```
+store.set("abc", "hello"); // FAILS
+
+// At the method level
+const store = kv(new Map());
+store.get<number>("abc"); // number | null
+store.set<number>("abc", 10);
+
+store.set<number>("abc", "hello"); // FAILS
+````
+
+> If you try to enforce data structure at _both_ the store level AND method level, then the method data type _should_ be a subclass of the store data structure, e.g. `kv<string | number>().get<string>("a")` will work, but `kv<string>().get<number>("a")` will _not_ work.
+
+The type should always be `Serializable`, which is `number | string | boolean | Object | Array` (values can be `null` inside Object+Array). These types, along with the Store and Client, are exported as well:
+
+```ts
+import kv from "polystore";
+import type { Client, Serializable, Store } from "polystore";
+
+const client: Client = ...;  // See #creating-a-store
+const store: Store = kv(client);
+const value: Serializable = store.get('hello');
+````
 
 ### .get()
 
@@ -174,7 +192,7 @@ These are all the units available:
 
 ### .add()
 
-Create a value in the store with a random key string. Will return a promise that resolves with the key when the value has been saved. The value needs to be serializable:
+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 });
@@ -186,7 +204,9 @@ 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 default key will be 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).
+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).
+
+Some clients will generate their own key, e.g. you can connect to a SQL client that does auto-incremental integers (always casted to `string` since a `key` is always a string in Polystore).
 
 <details>
   <summary>Key Generation details</summary>
@@ -206,7 +226,8 @@ const key1 = await session.add("value1");
 
 console.log(await session.keys()); // on the "session" store
 // ["c4ONlvweshXPUEy76q3eFHPL"]
-console.log(await store.keys()); // on the root store
+// 
+console.log(await store.keys()); // on the ROOT store
 // ["session:c4ONlvweshXPUEy76q3eFHPL"]
 ```
 
@@ -264,7 +285,7 @@ Remove a single key from the store and return the key itself:
 await store.del(key: string);
 ```
 
-It will ignore the operation if the key or value don't exist already (but won't thorw). The API makes it easy to delete multiple keys at once:
+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:
 
 ```js
 const keys = ["key1", "key2"];
@@ -293,7 +314,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 while the async iterator is running.
+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.
 
 You can also iterate on a subset of the entries with `.prefix()` (the prefix is stripped from the key here, see [.`prefix()`](#prefix)):
 
@@ -328,7 +349,7 @@ 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 [**expiration explained**](#expiration-explained) for more details.
+> 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.
 
 ### .values()
 
@@ -349,7 +370,7 @@ 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 [**expiration explained**](#expiration-explained) for more details.
+> 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.
 
 ### .entries()
 
@@ -369,7 +390,7 @@ const sessionEntries = await store.prefix('session:').entries();
 // [["keyA", "valueA"], ["keyB", "valueB"]]
 ```
 
-> We ensure that all of the entries returned by this method are _not_ expired, while discarding any potentially expired key. See [**expiration explained**](#expiration-explained) for more details.
+> We ensure that all of the entries returned by this method are _not_ expired, while discarding any potentially expired key. See [**expirations**](#expirations) for more details.
 
 ### .all()
 
@@ -385,21 +406,29 @@ It's in the format of a normal key:value object, where the object key is the sto
 If you want to filter for a particular prefix, use `.prefix()`, which will return the object with only the keys that have that given prefix (stripping the keys of the prefix!):
 
 ```js
-const sessionObj = await store.prefix('session:').entries();
+const sessionObj = await store.prefix('session:').all();
 // { keyA: "valueA", keyB: "valueB" }
 ```
 
-> We ensure that all of the entries returned by this method are _not_ expired, while discarding any potentially expired key. See [**expiration explained**](#expiration-explained) for more details.
+> We ensure that all of the entries returned by this method are _not_ expired, while discarding any potentially expired key. See [**expirations**](#expirations) for more details.
 
 
 ### .clear()
 
-Remove all of the data from the store and resets it to the original state:
+Remove all of the data from the client and resets it to the original state:
 
 ```js
 await store.clear();
 ```
 
+### .close()
+
+Close the connetion (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.
@@ -447,6 +476,23 @@ 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.
 
+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
+const map = new Map();
+const store = kv(map);
+
+// Works as expected
+await store.set("a", "b");
+console.log(await store.get("a"));
+
+// DON'T DO THIS; this will break the app since we apply more
+// advanced serialization to the values stored in memory
+map.set("a", "b");
+console.log(await store.get("a")); // THROWS ERROR
+```
+
+
 ### Memory
 
 An in-memory KV store, with promises and expiration time:
@@ -465,7 +511,7 @@ console.log(await store.get("key1"));
   <summary>Why use polystore with <code>new Map()</code>?</summary>
   <p>These benefits are for wrapping Map() with polystore:</p>
   <ul>
-    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -501,7 +547,7 @@ Same limitations as always apply to localStorage, if you think you are going to
   <p>These benefits are for wrapping localStorage with polystore:</p>
   <ul>
     <li><strong>Data structures</strong>: with Polystore you can pass more complex data structures and we'll handle the serialization/deserialization.</li>
-    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -535,7 +581,7 @@ console.log(await store.get("key1"));
   <p>These benefits are for wrapping sessionStorage with polystore:</p>
   <ul>
     <li><strong>Data structures</strong>: with Polystore you can pass more complex data structures and we'll handle the serialization/deserialization.</li>
-    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -573,7 +619,7 @@ It is fairly limited for how powerful cookies are, but in exchange it has the sa
   <p>These benefits are for wrapping cookies with polystore:</p>
   <ul>
     <li><strong>Data structures</strong>: with Polystore you can pass more complex data structures and we'll handle the serialization/deserialization.</li>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -594,10 +640,10 @@ console.log(await store.get("key1"));
 ```
 
 <details>
-  <summary>Why use polystore with <code>localStorage</code>?</summary>
+  <summary>Why use polystore with <code>localForage</code>?</summary>
   <p>These benefits are for wrapping localStorage with polystore:</p>
   <ul>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -625,7 +671,7 @@ You don't need to `await` for the connect or similar, this will process it prope
   <summary>Why use polystore with <code>Redis</code>?</summary>
   <p>These benefits are for wrapping Redis with polystore:</p>
   <ul>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -686,7 +732,7 @@ const store1 = kv(new URL(`file://${process.cwd()}/cache.json`));
   <p>These benefits are for wrapping a file with polystore:</p>
   <ul>
     <li><strong>Data structures</strong>: with Polystore you can pass more complex data structures and we'll handle the serialization/deserialization.</li>
-    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -745,7 +791,7 @@ const store1 = kv(new URL(`file://${process.cwd()}/cache/`));
   <p>These benefits are for wrapping a folder with polystore:</p>
   <ul>
     <li><strong>Data structures</strong>: with Polystore you can pass more complex data structures and we'll handle the serialization/deserialization.</li>
-    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Expiration</strong>: you can now set lifetime to your values so that they are automatically evicted when the time passes. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -788,7 +834,7 @@ It expects that you pass the namespace from Cloudflare straight as a `kv()` argu
   <p>These benefits are for wrapping Cloudflare's KV with polystore:</p>
   <ul>
     <li><strong>Data structures</strong>: with Polystore you can pass more complex data structures and we'll handle the serialization/deserialization.</li>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -826,7 +872,7 @@ You will need to set the `valueEncoding` to `"json"` for the store to work as ex
   <summary>Why use polystore with Level?</summary>
   <p>These benefits are for wrapping Level with polystore:</p>
   <ul>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
   </ul>
 </details>
 
@@ -859,7 +905,172 @@ You'll need to be running the etcd store for this to work as expected.
   <summary>Why use polystore with Etcd?</summary>
   <p>These benefits are for wrapping Etcd with polystore:</p>
   <ul>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration-explained">Expiration explained</a>.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
+    <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
+  </ul>
+</details>
+
+
+## SQLite
+
+Supports both **`bun:sqlite`** and **`better-sqlite3`** directly. Pass an already-opened database instance to `kv()` and Polystore will use the `kv` table to store keys, values, and expirations:
+
+> [!IMPORTANT]
+> The table `kv` must already exist in the Database
+
+```js
+import kv from "polystore";
+import Database from "better-sqlite3";
+// Or: import Database from "bun:sqlite";
+
+const db = new Database("data.db")
+const store = kv(db);
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+### SQLite schema
+
+This is the required schema:
+
+```sql
+CREATE TABLE kv (
+  id TEXT PRIMARY KEY,
+  value TEXT,
+  expires_at INTEGER
+);
+```
+
+You can create these with failsafes to make it much easier to initialize:
+
+```js
+db.run(`
+  CREATE TABLE IF NOT EXISTS kv (
+    id TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    expires_at INTEGER
+  )
+`);
+db.run(
+  `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 a native expiration. To avoid having stale data that is not used anymore, it's recommended you set a periodic check and clear expired records manually:
+
+```js
+// Clear expired keys once every 10 minutes
+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.
+
+<details>
+  <summary>Why use polystore with <code>SQLite</code>?</summary>
+  <p>These benefits apply when wrapping a SQLite DB with polystore:</p>
+  <ul>
+    <li><strong>Intuitive expirations</strong>: specify expiration times like <code>10min</code> or <code>2h</code> without manual date handling.</li>
+    <li><strong>Substores</strong>: use prefixes to isolate sets of keys cleanly.</li>
+    <li><strong>Simple persistence</strong>: full on-disk durability with a minimal driver.</li>
+  </ul>
+</details>
+
+
+### Postgres
+
+Use PostgreSQL with the `pg` library as a key-value store:
+
+```js
+import kv from "polystore";
+import { Client } from "pg";
+
+const client = new Client({ connectionString: process.env.DATABASE_URL });
+await client.connect();
+
+const store = kv(client);
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+You can also use `pg.Pool` instead of `pg.Client` for connection pooling.
+
+Your database needs a table with three columns: `id` (text), `value` (text), and `expiresAt` (timestamp, nullable):
+
+```sql
+CREATE TABLE kv (
+  id TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  "expiresAt" TIMESTAMP
+);
+```
+
+The default table name is `kv`, but you can use different tables via `.prefix()`:
+
+```js
+const sessions = store.prefix("session:"); // Uses 'session' table
+const cache = store.prefix("cache:");      // Uses 'cache' table
+
+await sessions.set("user123", { name: "Alice" });
+```
+
+This maps prefixes to table names for better performance on group operations.
+
+<details>
+  <summary>Why use polystore with Postgres?</summary>
+  <p>These benefits are for wrapping Postgres with polystore:</p>
+  <ul>
+    <li><strong>Unified API</strong>: use the same API across all your storage backends.</li>
+    <li><strong>Database-backed persistence</strong>: leverage your existing database for key-value storage.</li>
+    <li><strong>Table-based substores</strong>: <code>.prefix()</code> maps to different tables for optimal query performance.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expirations">Expirations</a>.</li>
+  </ul>
+</details>
+
+### Prisma
+
+Use Prisma as a key-value store by passing a table model directly:
+
+```js
+import kv from "polystore";
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+const store = kv(prisma.session);
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+Your Prisma schema needs a model with three columns: `id` (String), `value` (String/Text), and `expiresAt` (DateTime, nullable):
+
+```prisma
+model session {
+  id        String    @id
+  value     String    @db.Text
+  expiresAt DateTime?
+}
+```
+
+All three columns are required. The `expiresAt` column should be nullable (`DateTime?`) to support records without expiration.
+
+<details>
+  <summary>Why use polystore with Prisma?</summary>
+  <p>These benefits are for wrapping Prisma with polystore:</p>
+  <ul>
+    <li><strong>Unified API</strong>: use the same API across all your storage backends.</li>
+    <li><strong>Database-backed persistence</strong>: leverage your existing database for key-value storage.</li>
+    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration">Expirations</a>.</li>
     <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
   </ul>
 </details>
@@ -870,7 +1081,7 @@ Please see the [creating a store](#creating-a-store) section for all the details
 
 ## 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.
+> 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.
 
 While all of our stores support `expires`, `.prefix()` and group operations, the nature of those makes them to have different performance characteristics.
 
@@ -880,11 +1091,11 @@ 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.
 
-## Expires
+## 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.
 
-We unify all of the clients diverse expiration methods into a single, easy one with `expires`:
+We unify all of the clients diverse expiration methods into a single, easy one with `expires` (**seconds** | string):
 
 ```js
 // in-memory store
@@ -905,12 +1116,33 @@ console.log(await store.has("a")); // false
 console.log(await store.get("a")); // null
 ```
 
+These can be set with natural language, or a single number for the seconds:
+
+```js
+// Valid "expire" values:
+0 - expire immediately (AKA delete it)
+0.1 - expire after 100ms*
+60 * 60 - expire after 1h
+3_600 - expire after 1h
+"10s" - expire after 10 seconds
+"2minutes" - expire after 2 minutes
+"5d" - expire after 5 days
+```
+
+These are all the units available:
+
+> "ms", "millisecond", "s", "sec", "second", "m", "min", "minute", "h", "hr", "hour", "d", "day", "w", "wk", "week", "b" (month), "month", "y", "yr", "year"
+
 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
+
 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.
 
 For other stores like Redis this is not a problem, because the low-level operations already do them natively, so we don't need to worry about this for performance at the user-level. Instead, Redis and cookies have the problem that they only have expiration resolution at the second level. Meaning that 800ms is not a valid Redis expiration time, it has to be 1s, 2s, etc.
 
+These details are explained in the respective client information.
+
 ## Substores
 
 > There's some [basic `.prefix()` API info](#prefix) for everyday usage, this section is the in-depth explanation.

package/src/clients/Client.js

@@ -1,7 +0,0 @@
-export default class Client {
-  constructor(client) {
-    this.client = client;
-  }
-  encode = (val) => JSON.stringify(val, null, 2);
-  decode = (val) => (val ? JSON.parse(val) : null);
-}

package/src/clients/api.js

@@ -1,34 +0,0 @@
-import Client from "./Client.js";
-
-// Handle an API endpoint with fetch()
-export default class Api extends Client {
-  // Indicate that the file handler DOES handle expirations
-  EXPIRES = 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}`;
-    const headers = { accept: "application/json" };
-    if (body) headers["content-type"] = "application/json";
-    const res = await fetch(url, { method, headers, body });
-    if (!res.ok) return null;
-    if (res.headers.get("content-type")?.includes("application/json")) {
-      return res.json();
-    }
-    return res.text();
-  };
-
-  get = (key) => this.#api(key);
-  set = (key, value, { expires } = {}) =>
-    this.#api(key, `?expires=${expires || ""}`, "PUT", this.encode(value));
-  del = (key) => this.#api(key, "", "DELETE");
-
-  async *iterate(prefix = "") {
-    const data = await this.#api("", `?prefix=${encodeURIComponent(prefix)}`);
-    for (let [key, value] of Object.entries(data || {})) {
-      yield [prefix + key, value];
-    }
-  }
-}