polystore 0.14.1 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.14.1",
+  "version": "0.15.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",
@@ -14,11 +14,11 @@
     "src/"
   ],
   "scripts": {
-    "size": "echo $(gzip -c src/index.js | wc -c) bytes",
     "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"
+    "db": "etcd",
+    "server": "bun ./src/server.js"
   },
   "keywords": [
     "kv",
@@ -29,10 +29,10 @@
     "value"
   ],
   "license": "MIT",
-  "dependencies": {},
   "devDependencies": {
     "@deno/kv": "^0.8.1",
     "check-dts": "^0.8.0",
+    "cross-fetch": "^4.0.0",
     "dotenv": "^16.3.1",
     "edge-mock": "^0.0.15",
     "etcd3": "^1.1.2",

package/readme.md

@@ -35,6 +35,7 @@ Available clients for the KV store:
 - [**Session Storage** `sessionStorage`](#session-storage) (fe): persist the data in the browser's sessionStorage.
 - [**Cookies** `"cookie"`](#cookies) (fe): persist the data using cookies
 - [**LocalForage** `localForage`](#local-forage) (fe): persist the data on IndexedDB
+- [**Fetch API** `"https://..."`](#fetch-api) (fe+be): call an API to save/retrieve the data
 - [**File** `new URL('file:///...')`](#file) (be): store the data in a single JSON file in your FS
 - [**Folder** `new URL('file:///...')`](#folder) (be): store each key in a folder as json files
 - [**Redis Client** `redisClient`](#redis-client) (be): use the Redis instance that you connect to
@@ -629,6 +630,25 @@ You don't need to `await` for the connect or similar, this will process it prope
   </ul>
 </details>
 
+### Fetch API
+
+Calls an API to get/put the data:
+
+```js
+import kv from "polystore";
+
+const store = kv("https://kv.example.com/");
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+> Note: the API client expire resolution is in the seconds, so times shorter than 1 second like `expires: 0.02` (20 ms) don't make sense for this storage method and won't properly save them.
+
+> Note: see the reference implementation in src/server.js
+
+
 ### File
 
 Treat a JSON file in your filesystem as the source for the KV store:
@@ -643,7 +663,7 @@ console.log(await store.get("key1"));
 // "Hello world"
 ```
 
-> Note: an extension is needed, to desambiguate with "folder"
+> Note: an extension is needed, to disambiguate with "folder"
 
 You can also create multiple stores:
 
@@ -680,7 +700,7 @@ await fsp.writeFile(file, serialValue);
 
 ### Folder
 
-Treat a single folder in your filesystem as the source for the KV store, with each key being within a file:
+Treat a single folder in your filesystem as the store, where each key is a file:
 
 ```js
 import kv from "polystore";
@@ -688,21 +708,24 @@ import kv from "polystore";
 const store = kv(new URL("file:///Users/me/project/data/"));
 
 await store.set("key1", "Hello world", { expires: "1h" });
+// Writes "./data/key1.json"
 console.log(await store.get("key1"));
 // "Hello world"
 ```
 
-> Note: the ending slash `/` is needed, to desambiguate with "file"
+> Note: the ending slash `/` is needed, to disambiguate with "file"
 
 You can also create multiple stores:
 
 ```js
-// Paths need to be absolute, but you can use process.cwd() to make
-// it relative to the current process:
+// Paths need to be absolute, but you can use `process.cwd()` to make
+// it relative to the current process, or `import.meta.dirname`:
 const store1 = kv(new URL(`file://${process.cwd()}/cache/`));
 const store2 = kv(new URL(`file://${import.meta.dirname}/data/`));
 ```
 
+The folder is created if it doesn't exist. When a key is deleted, the corresponding file is also deleted. The data is serialized as JSON, with a meta wrapper to store the expiration date.
+
 <details>
   <summary>Why use polystore with a folder?</summary>
   <p>These benefits are for wrapping a folder with polystore:</p>

package/src/clients/api.js

@@ -0,0 +1,71 @@
+// Use fetch()
+export default class Api {
+  // Indicate that the file handler does NOT handle expirations
+  EXPIRES = true;
+
+  // Check whether the given store is a FILE-type
+  static test(client) {
+    return (
+      typeof client === "string" &&
+      (client.startsWith("https://") || client.startsWith("http://"))
+    );
+  }
+
+  constructor(client) {
+    client = client.replace(/\/$/, "") + "/";
+    this.client = async (path, opts = {}) => {
+      const query = Object.entries(opts.query || {})
+        .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+        .join("&");
+      let url = client + path.replace(/^\//, "") + "?" + query;
+      opts.headers = opts.headers || {};
+      opts.headers.accept = "application/json";
+      if (opts.body) opts.headers["content-type"] = "application/json";
+      const res = await fetch(url, opts);
+      if (!res.ok) return null;
+      if (!res.headers["content-type"] !== "application/json") {
+        console.warn("Not a JSON API");
+      }
+      return res.json();
+    };
+  }
+
+  async get(key) {
+    return await this.client(`/${key}`);
+  }
+
+  async set(key, value, { expires } = {}) {
+    return await this.client(`/${encodeURIComponent(key)}`, {
+      query: { expires },
+      method: "put",
+      body: JSON.stringify(value),
+    });
+  }
+
+  async del(key) {
+    return await this.client(`/${encodeURIComponent(key)}`, {
+      method: "delete",
+    });
+  }
+
+  // Since we have pagination, we don't want to get all of the
+  // keys at once if we can avoid it
+  async *iterate(prefix = "") {
+    const data = await this.client("/", { query: { prefix } });
+    if (!data) return [];
+    for (let [key, value] of Object.entries(data)) {
+      yield [prefix + key, value];
+    }
+  }
+
+  async keys(prefix = "") {
+    const data = await this.client(`/`, { query: { prefix } });
+    if (!data) return [];
+    return Object.keys(data).map((k) => prefix + k);
+  }
+
+  async clear(prefix = "") {
+    const list = await this.keys(prefix);
+    return Promise.all(list.map((k) => this.del(k)));
+  }
+}

package/src/clients/file.js

@@ -29,7 +29,8 @@ export default class File {
       // We want to make sure the file already exists, so attempt to
       // create the folders and the file (but not OVERWRITE it, that's why the x flag)
       // It fails if it already exists, hence the catch case
-      await fsp.mkdir(path.dirname(this.file), { recursive: true });
+      const folder = path.dirname(this.file);
+      await fsp.mkdir(folder, { recursive: true }).catch(() => {});
       await fsp.writeFile(this.file, "{}", { flag: "wx" }).catch((err) => {
         if (err.code !== "EEXIST") throw err;
       });

package/src/clients/folder.js

@@ -32,7 +32,7 @@ export default class Folder {
 
       // Make sure the folder already exists, so attempt to create it
       // It fails if it already exists, hence the catch case
-      await fsp.mkdir(this.folder, { recursive: true }).catch((err) => {});
+      await fsp.mkdir(this.folder, { recursive: true }).catch(() => {});
       return fsp;
     })();
   }

package/src/clients/index.js

@@ -1,3 +1,4 @@
+import api from "./api.js";
 import cloudflare from "./cloudflare.js";
 import cookie from "./cookie.js";
 import etcd from "./etcd.js";
@@ -10,6 +11,7 @@ import redis from "./redis.js";
 import storage from "./storage.js";
 
 export default {
+  api,
   cloudflare,
   cookie,
   etcd,

package/src/server.js

@@ -0,0 +1,75 @@
+// This is an example server implementation of the HTTP library!
+import http from "node:http";
+import kv from "./index.js";
+import { parse } from "./utils.js";
+
+// Modify this to use any sub-store as desired. It's nice
+// to use polystore itself for the polystore server library!'
+const store = kv(new Map());
+
+// Some reply helpers
+const notFound = () => new Response(null, { status: 404 });
+const sendJson = (data, status = 200) => {
+  const body = JSON.stringify(data);
+  const headers = { "content-type": "application/json" };
+  return new Response(body, { status, headers });
+};
+
+async function fetch({ method, url, body }) {
+  method = method.toLowerCase();
+  url = new URL(url);
+  let [, id] = url.pathname.split("/");
+  id = decodeURIComponent(id);
+  const expires = Number(url.searchParams.get("expires")) || null;
+  const prefix = url.searchParams.get("prefix") || null;
+
+  let local = store;
+  if (prefix) local = store.prefix(prefix);
+
+  if (method === "get") {
+    if (id === "ping") return new Response(null, { status: 200 });
+    if (!id) return sendJson(await local.all());
+    const data = await local.get(id);
+    if (data === null) return notFound();
+    return sendJson(data);
+  }
+
+  if (method === "put") {
+    if (!id) return notFound();
+    const data = await new Response(body).json();
+    if (!data) return notFound();
+    await local.set(id, data, { expires });
+    return sendJson(id);
+  }
+
+  if (method === "delete" && id) {
+    await local.del(id);
+    return sendJson(id);
+  }
+
+  return notFound();
+}
+
+// http or express server-like handler:
+async function server(req, res) {
+  const url = new URL(req.url, "http://localhost:3000/").href;
+  const reply = await fetch({ ...req, url });
+  res.writeHead(reply.status, null, reply.headers || {});
+  if (reply.body) res.write(reply.body);
+  res.end();
+}
+
+function start(port = 3000) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(server);
+    server.on("clientError", (error, socket) => {
+      reject(error);
+      socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+    });
+    server.listen(port, resolve);
+    return () => server.close();
+  });
+}
+
+export { fetch, server, start };
+export default { fetch, server, start };