polystore 0.21.2 → 0.22.0

package/package.json

@@ -1,65 +1,83 @@
 {
   "name": "polystore",
-  "version": "0.21.2",
+  "version": "0.22.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",
-  "bugs": "https://github.com/franciscop/polystore/issues",
-  "funding": "https://www.paypal.me/franciscopresencia/19",
+  "repository": "github:franciscop/polystore",
   "author": "Francisco Presencia <public@francisco.io> (https://francisco.io/)",
-  "type": "module",
-  "sideEffects": false,
+  "funding": "https://www.paypal.me/franciscopresencia/19",
+  "license": "MIT",
+  "keywords": [
+    "kv",
+    "store",
+    "polystore",
+    "key-value",
+    "key",
+    "value"
+  ],
+  "scripts": {
+    "size": "echo $(gzip -c index.js | wc -c) bytes",
+    "build": "bunx tsup src/index.ts --format esm --dts --out-dir . --target node24 && bunx tsup src/plugins/express/index.ts --format esm --dts --out-dir src/plugins/express --target node24 --external polystore --external express-session && bunx tsup src/plugins/hono-sessions/index.ts --format esm --dts --out-dir src/plugins/hono-sessions --target node24 --external polystore --external hono-sessions && bunx tsup src/plugins/better-auth/index.ts --format esm --dts --out-dir src/plugins/better-auth --target node24 --external polystore",
+    "lint": "tsc",
+    "start": "bun test --watch",
+    "service:db": "etcd",
+    "service:redis": "brew services start redis",
+    "service:postgres": "brew services start postgresql",
+    "service:server": "bun ./src/server.ts",
+    "services": "concurrently \"npm run service:db\" \"npm run service:redis\" \"npm run service:postgres\" \"npm run service:server\"",
+    "test": "bun run test:bun && bun run test:jest",
+    "test:bun": "bun test ./test/index.test.ts ./src/plugins/",
+    "test:jest": "jest ./test/index.test.ts --detectOpenHandles --forceExit"
+  },
+  "workspaces": [
+    "examples/*"
+  ],
   "main": "index.js",
+  "type": "module",
   "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/plugins/express/index.js",
+    "src/plugins/express/index.d.ts",
+    "src/plugins/hono-sessions/index.js",
+    "src/plugins/hono-sessions/index.d.ts",
+    "src/plugins/better-auth/index.js",
+    "src/plugins/better-auth/index.d.ts"
+  ],
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
     },
     "./express": {
-      "types": "./src/integrations/express.d.ts",
-      "import": "./src/integrations/express.js"
+      "types": "./src/plugins/express/index.d.ts",
+      "import": "./src/plugins/express/index.js"
     },
     "./hono-sessions": {
-      "types": "./src/integrations/hono-sessions.d.ts",
-      "import": "./src/integrations/hono-sessions.js"
+      "types": "./src/plugins/hono-sessions/index.d.ts",
+      "import": "./src/plugins/hono-sessions/index.js"
+    },
+    "./better-auth": {
+      "types": "./src/plugins/better-auth/index.d.ts",
+      "import": "./src/plugins/better-auth/index.js"
     }
   },
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "src/integrations/express.js",
-    "src/integrations/express.d.ts",
-    "src/integrations/hono-sessions.js",
-    "src/integrations/hono-sessions.d.ts"
-  ],
-  "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",
-    "build": "bunx tsup src/index.ts --format esm --dts --out-dir . --target node24 && bunx tsup src/integrations/express.ts src/integrations/hono-sessions.ts --format esm --dts --out-dir src/integrations --target node24 --external polystore --external express-session --external hono-sessions",
-    "lint": "tsc",
-    "start": "bun test --watch",
-    "service:db": "etcd",
-    "service:redis": "brew services start redis",
-    "service:postgres": "brew services start postgresql",
-    "service:server": "bun ./src/server.ts",
-    "services": "concurrently \"npm run service:db\" \"npm run service:redis\" \"npm run service:postgres\" \"npm run service:server\"",
-    "test": "npm run test:bun && npm run test:jest",
-    "test:bun": "bun test ./test/index.test.ts ./src/integrations/",
-    "test:jest": "jest ./test/index.test.ts --detectOpenHandles --forceExit"
+  "documentation.page": {
+    "title": "🏬 Polystore - A universal library for standardizing any KV-store",
+    "home": "assets/home.html",
+    "homepage": "https://polystore.dev/",
+    "menu": {
+      "Documentation": "/documentation",
+      "Issues": "https://github.com/franciscop/polystore/issues",
+      "Get help": "https://superpeer.com/francisco/-/javascript-and-react-help",
+      "Github": "https://github.com/franciscop/polystore"
+    }
   },
-  "keywords": [
-    "kv",
-    "store",
-    "polystore",
-    "key-value",
-    "key",
-    "value"
-  ],
-  "license": "MIT",
   "devDependencies": {
     "@deno/kv": "^0.8.1",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/bun": "^1.3.3",
+    "@types/bun": "^1.3.0",
     "@types/express": "^5.0.6",
     "@types/express-session": "^1.18.2",
     "@types/jest": "^30.0.0",
@@ -67,9 +85,7 @@
     "@types/pg": "^8.11.10",
     "@types/supertest": "^7.2.0",
     "better-sqlite3": "^12.6.0",
-    "check-dts": "^0.8.0",
     "concurrently": "^9.2.1",
-    "cross-fetch": "^4.1.0",
     "dotenv": "^16.3.1",
     "edge-mock": "^0.0.15",
     "esbuild": "^0.27.0",
@@ -87,19 +103,8 @@
     "redis": "^4.6.10",
     "supertest": "^7.2.2",
     "ts-jest": "^29.4.6",
-    "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.2"
   },
-  "documentation": {
-    "title": "🏬 Polystore - A universal library for standardizing any KV-store",
-    "home": "assets/home.html",
-    "homepage": "https://polystore.dev/",
-    "menu": {
-      "Documentation": "/documentation",
-      "Issues": "https://github.com/franciscop/polystore/issues",
-      "Get help": "https://superpeer.com/francisco/-/javascript-and-react-help",
-      "Github": "https://github.com/franciscop/polystore"
-    }
-  }
+  "sideEffects": false
 }

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/actions) [![gzip size](https://badgen.net/bundlephobia/minzip/polystore?label=gzip&color=green)](https://bundlephobia.com/package/polystore) [![dependencies](https://img.shields.io/badge/dependencies-0-limegreen.svg)](https://github.com/franciscop/polystore/blob/master/package.json)
+# Polystore [![polystore](https://img.shields.io/npm/v/polystore?label=polystore&color=greenlime)](https://www.npmjs.com/package/polystore) [![tests](https://github.com/franciscop/polystore/workflows/tests/badge.svg)](https://github.com/franciscop/polystore/actions) [![gzip size](https://img.badgesize.io/franciscop/polystore/master/index.js.svg?label=gzip&logo=&compression=gzip)](https://github.com/franciscop/polystore/blob/master/index.js) [![dependencies](https://img.shields.io/badge/dependencies-0-limegreen.svg)](https://github.com/franciscop/polystore/blob/master/package.json)
 
-A key-value library to unify the API of [many clients](#clients): localStorage, Redis, FileSystem, SQLite, etc.
+A key-value library to unify the API of [many adapters](#adapters): localStorage, Redis, FileSystem, SQLite, etc.
 
 ```js
 import kv from "polystore";
@@ -8,7 +8,7 @@ const store1 = kv(new Map()); // in-memory
 const store2 = kv(localStorage); // Persist in the browser
 const store3 = kv(redisClient); // Use a Redis client for backend persistence
 const store4 = kv(yourOwnStore); // Create a store based on your code
-// Many more clients available
+// Many more adapters available
 ```
 
 These are all the methods of the [API](#api) (they are all `async`):
@@ -29,7 +29,7 @@ These are all the methods of the [API](#api) (they are all `async`):
 - [`.prune()`](#prune): delete only the **expired** data from the store.
 - [`.close()`](#close): (only _some_ stores) ends the connection to the store.
 
-Available clients for the KV store:
+Available adapters for the KV store:
 
 - [**Memory** `new Map()`](#memory) (fe+be): an in-memory API to keep your KV store.
 - [**Local Storage** `localStorage`](#local-storage) (fe): persist the data in the browser's localStorage.
@@ -42,7 +42,7 @@ Available clients for the KV store:
 - [**File** `"file:///[...].json"`](#file) (be): store the data in a single JSON file in your FS.
 - [**Folder** `"file:///[...]/"`](#folder) (be): store each key in a folder as json files.
 - [**Cloudflare KV** `env.KV_NAMESPACE`](#cloudflare-kv) (be): use Cloudflare's KV store.
-- [**Postgres** `pool`](#postgres) (be): use PostgreSQL with the pg library.
+- [**Postgres** `pg`](#postgres) (be): use PostgreSQL with the pg library.
 - [**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.
 - [**_Custom_** `{}`](#creating-a-store) (fe+be): create your own store with just 3 methods!
@@ -61,7 +61,7 @@ MyApi({ cache: env.KV_NAMESPACE }); // OR
 
 ## Getting started
 
-First, install `polystore` and whatever [supported client](#clients) that you prefer. Let's see Redis as an example here:
+First, install `polystore` and whatever [supported adapter](#adapters) 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)); an argument that receives the client or a string representing the client and then the options:
+The base `kv()` initialization is shared across adapters ([see full adapters list](#adapters)); an argument that receives the adapter or a string representing the adapter and then the options:
 
 ```js
 import kv from "polystore";
@@ -104,9 +104,6 @@ const store = kv(MyClientInstance, { expires: null, prefix: "" });
 // use the store
 ```
 
-> [!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 the values either at store creation or at the method level:
 
 ```ts
@@ -129,14 +126,14 @@ store.set<number>("abc", "hello"); // FAILS
 
 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`, `Store` and `Options`:
+These are the exported types, `Adapter`, `Serializable`, `Store` and `Options`:
 
 ```ts
 import kv from "polystore";
-import type { Client, Serializable, Store, Options } from "polystore";
+import type { Adapter, Serializable, Store, Options } from "polystore";
 
-const client: Client = ...;  // See #creating-a-store
-const store: Store = kv(client, opts as Options);
+const adapter: Adapter = ...;  // See #creating-a-store
+const store: Store = kv(adapter, opts as Options);
 const key = await store.set('hello', 'b', opts as Options)
 const value: Serializable = await store.get('hello');
 ```
@@ -308,9 +305,9 @@ const key3 = await store.add({ name: "Francisco" }, { expires: 60 * 60 });
 
 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).
+The default key is 24 AlphaNumeric characters (upper+lower case), however this can change if you are using a `.prefix()` or some adapters might generate it differently (only custom adapters 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).
+Some adapters 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>
@@ -553,7 +550,7 @@ This operation is O(n) and should typically be run in a scheduled job or mainten
 
 ### .close()
 
-Close the connection (if any) from the client:
+Close the connection (if any) from the adapter:
 
 ```js
 await store.close();
@@ -561,7 +558,7 @@ await store.close();
 
 ### .prefix()
 
-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:
+Creates **a new instance** of the Store, _with the same adapter_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the adapter. 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());
@@ -586,7 +583,7 @@ for await (const [key, value] of session) {
 }
 ```
 
-Different clients have better/worse support for substores, and in some cases some operations might be slower. This should be documented on each client's documentation (see below). As an alternative, you can always create two different stores instead of a substore:
+Different adapters have better/worse support for substores, and in some cases some operations might be slower. This should be documented on each adapter's documentation (see below). As an alternative, you can always create two different stores instead of a substore:
 
 ```js
 // Two in-memory stores
@@ -625,15 +622,15 @@ You can combine it with .prefix():
 const sessions = store.prefix("session:").expires("1day");
 ```
 
-## Clients
+## Adapters
 
-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"`.
+An adapter is the library that manages the low-level store operations. For example, the Redis adapter, 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"`.
 
 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 |
+| Adapter | Runtime | Persistence | Native expiration | Notes |
 |---|---|---|---|---|
 | [Memory](#memory) | Node.js + Browser | ❌ | ❌ | Great for tests and ephemeral caches |
 | [Local Storage](#local-storage) | Browser | ✅ | ❌ | Persistent browser storage |
@@ -650,7 +647,7 @@ Quick overview:
 | [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:
+While you can keep a reference to the underlying adapter 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();
@@ -1225,12 +1222,14 @@ This keeps a single table while preserving namespace-style grouping through pref
 
 Please see the [creating a store](#creating-a-store) section for all the details!
 
-## Integrations
+## Plugins
 
-Polystore has some easy integrations for you to use it as a simple connector.
+Polystore has easy plugins to drop into popular frameworks and auth libraries. Each one has a runnable example in the [`examples/`](https://github.com/franciscop/polystore/tree/master/examples) folder.
 
 ### Express
 
+> [Full example →](https://github.com/franciscop/polystore/tree/master/examples/express)
+
 Use any Polystore-compatible store as an [express-session](https://github.com/expressjs/session) store:
 
 ```js
@@ -1243,7 +1242,7 @@ app.use(session({
 }));
 ```
 
-By default it uses an in-memory `Map`, which is fine for development. For production, pass any Polystore client:
+By default it uses an in-memory `Map`, which is fine for development. For production, pass any Polystore adapter:
 
 ```js
 import { createClient } from "redis";
@@ -1255,7 +1254,7 @@ 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.
+Any adapter 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:
 
@@ -1270,30 +1269,35 @@ app.use((req, res, next) => {
 
 ### Hono Sessions
 
+> [Full example →](https://github.com/franciscop/polystore/tree/master/examples/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";
+import kv from "polystore/hono-sessions";
 
-const app = new Hono();
+const store = kv();
 
+const app = new Hono();
 app.use("*", sessionMiddleware({
-  store: honoStore(),
+  store,
   encryptionKey: process.env.SESSION_KEY,
   expireAfterSeconds: 3600,
 }));
 ```
 
-By default it uses an in-memory `Map`. For production, pass any Polystore client:
+By default it uses an in-memory `Map`. For production, pass any Polystore adapter:
 
 ```js
 import { createClient } from "redis";
-import honoStore from "polystore/hono-sessions";
+import kv from "polystore/hono-sessions";
+
+const store = kv(createClient().connect());
 
 app.use("*", sessionMiddleware({
-  store: honoStore(createClient().connect()),
+  store,
   encryptionKey: process.env.SESSION_KEY,
   expireAfterSeconds: 3600,
 }));
@@ -1316,6 +1320,36 @@ app.use("*", (c, next) => {
 ```
 
 
+### Better Auth
+
+> [Full example →](https://github.com/franciscop/polystore/tree/master/examples/better-auth)
+
+Use any Polystore-compatible store as the [`secondaryStorage`](https://www.better-auth.com/docs/concepts/database#secondary-storage) for [Better Auth](https://better-auth.com). No database required — Polystore handles session caching and token storage:
+
+```js
+import { betterAuth } from "better-auth";
+import betterAuthStorage from "polystore/better-auth";
+
+export const auth = betterAuth({
+  secondaryStorage: betterAuthStorage(),  // in-memory by default
+  emailAndPassword: { enabled: true },
+});
+```
+
+For production, swap in any Polystore adapter:
+
+```js
+import { createClient } from "redis";
+
+secondaryStorage: betterAuthStorage(createClient().connect())
+```
+
+Use `.prefix()` to namespace keys in a shared store:
+
+```js
+secondaryStorage: betterAuthStorage(createClient().connect()).prefix("auth:")
+```
+
 ### 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:
@@ -1378,7 +1412,7 @@ export default server({ session }).get("/", (ctx) => {
 
 ### 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 adapter 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.
 
@@ -1390,9 +1424,9 @@ While all of our stores support `expires`, `.prefix()` and group operations, the
 
 ### 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.
+> Warning: if an adapter 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` (**seconds** | string):
+We unify all of the adapters' diverse expiration methods into a single, easy one with `expires` (**seconds** | string):
 
 ```js
 // in-memory store
@@ -1438,13 +1472,13 @@ However, in some stores this does come with some potential performance disadvant
 
 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.
+These details are explained in the respective adapter information.
 
 ### Substores
 
 > There's some [basic `.prefix()` API info](#prefix) for everyday usage, this section is the in-depth explanation.
 
-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.
+What `.prefix()` does is it creates **a new instance** of the Store, _with the same adapter_ as you provided, but now any key you read, write, etc. will be passed with the given prefix to the adapter. The issue is that support from the underlying adapters is inconsistent.
 
 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:
 
@@ -1465,15 +1499,15 @@ Polystore methods return promises and surface errors from the underlying client.
    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.
+   Invalid adapter 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.
+- Log enough context (`adapter type`, `key`, operation name) without logging sensitive values.
+- For remote adapters, consider retry/backoff only for transient failures.
+- Call `.close()` during shutdown when the adapter supports it.
 
 Example:
 
@@ -1524,43 +1558,43 @@ 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.
+Note that this is NOT the public API, it's the internal **adapter** API. It's simpler than the public API since we do some of the heavy lifting as an intermediate layer (e.g. for the adapter, 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 `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.
+**Expires**: if you set the `HAS_EXPIRATION = true`, then you are indicating that the adapter 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:
 
 ```js
 // What the user of polystore does:
-const store = await kv(client).prefix("hello:").prefix("world:");
+const store = await kv(adapter).prefix("hello:").prefix("world:");
 
-// User calls this, then the client is called with that:
+// User calls this, then the adapter is called with that:
 const value = await store.get("a");
-// client.get("hello:world:a");
+// adapter.get("hello:world:a");
 
-// User calls this, then the client is called with that:
+// User calls this, then the adapter is called with that:
 for await (const [key, value] of store) {}
-// client.iterate("hello:world:");
+// adapter.iterate("hello:world:");
 ```
 
 > Note: all of the _group methods_ that return keys, should return them **with the prefix**:
 
 ```js
-client.keys = (prefix) => {
+adapter.keys = (prefix) => {
   // Filter the keys, and return them INCLUDING the prefix!
   return Object.keys(subStore).filter((key) => key.startsWith(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).
+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 adapter 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
+### Plain Object adapter
 
-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:
+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 adapters:
 
 ```js
 const dataSource = {};
@@ -1590,10 +1624,10 @@ We don't set `HAS_EXPIRATION` to true since plain objects do NOT support expirat
 
 ### 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:
+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 adapter with a custom generator:
 
 ```js
-class MyClient {
+class MyAdapter {
 
   // Add the opt method .add() to have more control over the ID generation
   async add (prefix, data, expires) {
@@ -1623,10 +1657,10 @@ const id2 = await store.prefix("hello:").add({ hello: "world" });
 
 ### 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:
+If you need to serialize the data before storing it, you can do it within your custom adapter. Here's an example of how you can handle data serialization when setting values:
 
 ```js
-class MyClient {
+class MyAdapter {
   get(key) {
     const data = dataSource[key];
     return data ? JSON.parse(data) : null;
@@ -1741,7 +1775,7 @@ You can store either the raw data, or the processed data. Depending on whether t
 
 ### 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):
+With Polystore it's easy to configure your KV solution to use a different adapter in dev vs production. We've found particularly useful to use an easy-to-debug adapter in dev like [Folder](#folder) and a high-performance adapter in production like [Redis](#redis):
 
 ```ts
 // store.ts

package/src/plugins/better-auth/index.d.ts

@@ -0,0 +1,18 @@
+import { Store } from 'polystore';
+
+type SecondaryStorage = {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+declare class PolystoreBetterAuthStorage implements SecondaryStorage {
+    private store;
+    constructor(store: Store);
+    prefix(prefix?: string): PolystoreBetterAuthStorage;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare function betterAuthStorage(store?: any): PolystoreBetterAuthStorage;
+
+export { PolystoreBetterAuthStorage, betterAuthStorage as default };

package/src/plugins/better-auth/index.js

@@ -0,0 +1,27 @@
+// src/plugins/better-auth/index.ts
+import kv from "polystore";
+var PolystoreBetterAuthStorage = class _PolystoreBetterAuthStorage {
+  store;
+  constructor(store) {
+    this.store = store;
+  }
+  prefix(prefix = "") {
+    return new _PolystoreBetterAuthStorage(this.store.prefix(prefix));
+  }
+  get(key) {
+    return this.store.get(key);
+  }
+  async set(key, value, ttl) {
+    await this.store.set(key, value, ttl ? { expires: ttl } : void 0);
+  }
+  async delete(key) {
+    await this.store.del(key);
+  }
+};
+function betterAuthStorage(store = /* @__PURE__ */ new Map()) {
+  return new PolystoreBetterAuthStorage(kv(store));
+}
+export {
+  PolystoreBetterAuthStorage,
+  betterAuthStorage as default
+};

package/src/plugins/express/index.d.ts

@@ -0,0 +1,20 @@
+import session, { SessionData } from 'express-session';
+import { Store } from 'polystore';
+
+type Callback = (err?: any) => void;
+declare class PolystoreSessionStore extends session.Store {
+    private store;
+    constructor(store: Store);
+    prefix(prefix?: string): PolystoreSessionStore;
+    get(sid: string, cb: (err: any, session?: SessionData | null) => void): void;
+    set(sid: string, data: SessionData, cb?: Callback): void;
+    destroy(sid: string, cb?: Callback): void;
+    touch(sid: string, data: SessionData, cb?: Callback): void;
+    all(cb: (err: any, sessions?: SessionData[] | {
+        [sid: string]: SessionData;
+    } | null) => void): void;
+    clear(cb?: Callback): void;
+}
+declare function expressStore(store?: Map<any, any>): PolystoreSessionStore;
+
+export { PolystoreSessionStore, expressStore as default };

package/src/{integrations/express.js → plugins/express/index.js}

@@ -1,4 +1,4 @@
-// src/integrations/express.ts
+// src/plugins/express/index.ts
 import session from "express-session";
 import kv from "polystore";
 var ttlFromSession = (data) => {
@@ -33,8 +33,8 @@ var PolystoreSessionStore = class _PolystoreSessionStore extends session.Store {
     this.store.clear().then(() => cb?.()).catch((err) => cb?.(err));
   }
 };
-function expressStore(client = /* @__PURE__ */ new Map()) {
-  return new PolystoreSessionStore(kv(client));
+function expressStore(store = /* @__PURE__ */ new Map()) {
+  return new PolystoreSessionStore(kv(store));
 }
 export {
   PolystoreSessionStore,