keyv-github 1.3.0 → 1.5.0

package/README.md

@@ -15,6 +15,50 @@ Every `set` costs **2 API calls** (read SHA + write), every `delete` costs **2**
 
 Use a [GitHub App](https://docs.github.com/en/developers/apps) token or a fine-grained PAT with `contents: write` permission to maximise your quota.
 
+### Best Practice: Use cache layers
+
+To reduce API calls, chain memory and file caches before keyv-github using [keyv-nest](https://github.com/snomiao/keyv-nest) and [keyv-dir-store](https://github.com/snomiao/keyv-dir-store):
+
+```ts
+import Keyv from "keyv";
+import KeyvNest from "keyv-nest";
+import { KeyvDirStore } from "keyv-dir-store";
+import KeyvGithub from "keyv-github";
+
+// Simple memory store (avoids Keyv namespace prefix issues)
+const memoryStore = {
+  cache: new Map<string, any>(),
+  opts: { url: "", dialect: "map" },
+  get(key: string) { return this.cache.get(key); },
+  set(key: string, value: any) { this.cache.set(key, value); },
+  delete(key: string) { return this.cache.delete(key); },
+  clear() { this.cache.clear(); },
+};
+
+// Use same prefix/suffix so local cache mirrors GitHub paths
+const prefix = "data/";
+const suffix = ".json";
+
+const store = KeyvNest(
+  memoryStore,                             // L1: Memory (fastest)
+  new KeyvDirStore("./cache", {            // L2: Local files (fast)
+    prefix,
+    suffix,
+    filename: (k) => k,  // use key as-is, no hashing
+  }),
+  new KeyvGithub("owner/repo/tree/main", { client, prefix, suffix })  // L3: GitHub
+);
+
+// Wrap with Keyv (use empty namespace to preserve keys)
+(store as any).opts = { url: "", dialect: "keyv-nest" };
+const kv = new Keyv({ store, namespace: "" });
+// key "foo" -> ./cache/data/foo.json (local) and data/foo.json (GitHub)
+```
+
+See [demo-best-practice.ts](./demo-best-practice.ts) for a runnable example.
+
+Reads check L1 → L2 → L3, with automatic backfill to faster layers on cache miss.
+
 ## Install
 
 ```sh
@@ -99,6 +143,8 @@ const store = new KeyvGithub("owner/repo", {
 
 ## Key rules
 
+⚠️ **Keys are validated but NOT sanitized.** You must sanitize keys yourself before passing them to this adapter. Invalid keys will throw an error.
+
 Keys must be valid relative file paths:
 
 - Non-empty
@@ -107,8 +153,22 @@ Keys must be valid relative file paths:
 - No `.` or `..` segments
 - No null bytes
 
+**OS-specific characters** like `<>:"|?*\` (invalid on Windows) are NOT validated — you must sanitize these yourself if your keys might contain them.
+
 Invalid keys throw synchronously before any API request.
 
+```ts
+// ✗ These will throw errors
+await store.set("/absolute/path", "value");     // leading slash
+await store.set("path/", "value");               // trailing slash
+await store.set("path/../escape", "value");      // directory traversal
+await store.set("path//double", "value");        // double slashes
+
+// ✓ Valid keys
+await store.set("data/file.txt", "value");
+await store.set("nested/path/key.json", "value");
+```
+
 ## See Also
 
 Other Keyv storage adapters by the same author: