keyv-github 1.3.0 → 1.5.0

package/demo-best-practice.ts

@@ -0,0 +1,100 @@
+/**
+ * Demo: Best Practice - 3-layer cache with keyv-nest
+ *
+ * This demo shows how to use memory + file + GitHub cache layers
+ * to minimize API calls while keeping data in sync.
+ *
+ * Run with GitHub:
+ *   GITHUB_TOKEN=your_token GITHUB_REPO=owner/repo bun demo-best-practice.ts
+ *
+ * Run local-only (no GitHub):
+ *   bun demo-best-practice.ts --local
+ */
+
+import Keyv from "keyv";
+import KeyvNest from "keyv-nest";
+import { Octokit } from "octokit";
+import KeyvGithub from "./src/index.ts";
+// Use local version with prefix/suffix support (pending npm publish)
+import { KeyvDirStore } from "./tmp/keyv-dir-store/index.ts";
+
+const LOCAL_ONLY = process.argv.includes("--local");
+const REPO = process.env.GITHUB_REPO || "snomiao/keyv-github-demo";
+const TOKEN = process.env.GITHUB_TOKEN;
+
+if (!LOCAL_ONLY && !TOKEN) {
+	console.log("No GITHUB_TOKEN set. Running in local-only mode.");
+	console.log("To sync with GitHub, run:");
+	console.log(
+		"  GITHUB_TOKEN=xxx GITHUB_REPO=owner/repo bun demo-best-practice.ts\n",
+	);
+}
+
+// Use same prefix/suffix so local cache mirrors GitHub paths
+const prefix = "data/";
+const suffix = ".txt";
+
+// Simple Map-based memory store (no namespace prefix)
+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();
+	},
+};
+
+// Build cache layers
+const layers: any[] = [
+	memoryStore, // L1: Memory (fastest)
+	new KeyvDirStore("./cache", {
+		// L2: Local files (fast)
+		prefix,
+		suffix,
+		filename: (k) => k, // use key as-is, no hashing
+	}),
+];
+
+// Add GitHub layer if token is available
+if (TOKEN && !LOCAL_ONLY) {
+	const client = new Octokit({ auth: TOKEN });
+	layers.push(
+		new KeyvGithub(`${REPO}/tree/main`, { client, prefix, suffix }), // L3: GitHub
+	);
+	console.log(`Using 3-layer cache: Memory -> Files -> GitHub (${REPO})`);
+} else {
+	console.log("Using 2-layer cache: Memory -> Files (local only)");
+}
+
+const store = KeyvNest(...layers);
+// Add opts for Keyv compatibility
+(store as any).opts = { url: "", dialect: "keyv-nest" };
+// Use empty namespace to avoid keyv: prefix on keys
+const kv = new Keyv({ store, namespace: "" });
+
+// Demo: Write today's best thing
+const today = new Date().toISOString().split("T")[0];
+const content = `Today's best thing: ${today}\n\nWritten at: ${new Date().toISOString()}`;
+
+console.log("\nSetting data/best-today.txt...");
+await kv.set("best-today", content);
+
+console.log("Reading back from cache layers...");
+const result = await kv.get("best-today");
+console.log("Content:", result);
+
+console.log("\nDone! Check:");
+console.log(`  Local:  ./cache/${prefix}best-today${suffix}`);
+if (TOKEN && !LOCAL_ONLY) {
+	console.log(
+		`  GitHub: https://github.com/${REPO}/blob/main/${prefix}best-today${suffix}`,
+	);
+}

package/dist/index.d.mts

@@ -12,8 +12,20 @@ interface KeyvGithubOptions {
   url: string;
   branch?: string;
   client?: Octokit | Octokit["rest"];
-  /** Customize the commit message. value is null for deletes. */
+  /**
+   * Customize the commit message for single-key operations. value is null for deletes.
+   * @warning Consider adding `[skip ci]` to your commit messages to prevent
+   * triggering CI workflows on each key-value update.
+   */
   msg?: (key: string, value: string | null) => string;
+  /**
+   * Customize the commit message for batch operations (setMany, deleteMany, clear).
+   * @param operation - 'set' | 'delete' | 'clear'
+   * @param paths - array of file paths being modified
+   * @warning Consider adding `[skip ci]` to your commit messages to prevent
+   * triggering CI workflows on each key-value update.
+   */
+  batchMsg?: (operation: "set" | "delete" | "clear", paths: string[]) => string;
   /** clear() deletes every file in the repo and is disabled by default. Set to true to allow it. */
   enableClear?: boolean;
   /** Path prefix prepended to every key (e.g. 'data/'). Defaults to ''. */
@@ -28,6 +40,11 @@ interface KeyvGithubOptions {
  *
  * Each key is a file path in the repo; the file content is the value.
  * Example: new KeyvGithub("https://github.com/owner/repo/tree/main", { client })
+ *
+ * @warning **Keys are validated but NOT sanitized.** You must ensure keys are valid
+ * GitHub file paths before calling any method. Invalid keys throw an error.
+ * Requirements: non-empty, no leading/trailing `/`, no `//`, no `.`/`..` segments, no null bytes.
+ * OS-specific invalid characters (e.g. `<>:"|?*\` on Windows) are NOT checked — sanitize them yourself.
  */
 declare class KeyvGithub extends EventEmitter implements KeyvStoreAdapter {
   opts: KeyvGithubOptions;
@@ -39,6 +56,7 @@ declare class KeyvGithub extends EventEmitter implements KeyvStoreAdapter {
   get branch(): string;
   rest: Octokit["rest"];
   private msg;
+  private batchMsg;
   readonly enableClear: boolean;
   readonly prefix: string;
   readonly suffix: string;

package/dist/index.mjs

@@ -7,6 +7,11 @@ import { Octokit } from "octokit";
 *
 * Each key is a file path in the repo; the file content is the value.
 * Example: new KeyvGithub("https://github.com/owner/repo/tree/main", { client })
+*
+* @warning **Keys are validated but NOT sanitized.** You must ensure keys are valid
+* GitHub file paths before calling any method. Invalid keys throw an error.
+* Requirements: non-empty, no leading/trailing `/`, no `//`, no `.`/`..` segments, no null bytes.
+* OS-specific invalid characters (e.g. `<>:"|?*\` on Windows) are NOT checked — sanitize them yourself.
 */
 var KeyvGithub = class KeyvGithub extends EventEmitter {
 	opts;
@@ -20,6 +25,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 	}
 	rest;
 	msg;
+	batchMsg;
 	enableClear;
 	prefix;
 	suffix;
@@ -37,7 +43,12 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			...options
 		};
 		this.rest = options.client instanceof Octokit ? options.client.rest : options.client ?? new Octokit().rest;
-		this.msg = options.msg ?? ((key, value) => value === null ? `delete ${key}` : `update ${key}`);
+		this.msg = options.msg ?? ((key, value) => value === null ? `delete ${key} [skip ci]` : `update ${key} [skip ci]`);
+		this.batchMsg = options.batchMsg ?? ((op, paths) => {
+			const n = paths.length;
+			if (op === "clear") return `clear: remove ${n} files [skip ci]`;
+			return `batch ${op} ${n} files [skip ci]`;
+		});
 		this.enableClear = options.enableClear ?? false;
 		this.prefix = options.prefix ?? "";
 		this.suffix = options.suffix ?? "";
@@ -223,7 +234,8 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			this.validatePath(this.toPath(key));
 		}
 		const entries = values.map(({ key, value }) => [this.toPath(key), String(value)]);
-		const message = entries.length === 1 ? this.msg(entries[0][0], entries[0][1]) : `batch update ${entries.length} files`;
+		const paths = entries.map(([p]) => p);
+		const message = entries.length === 1 ? this.msg(entries[0][0], entries[0][1]) : this.batchMsg("set", paths);
 		await this._batchCommit({
 			set: entries,
 			message
@@ -250,7 +262,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 		const existingPaths = new Set(treeData.tree.filter((i) => i.type === "blob" && i.path).map((i) => i.path));
 		const toDelete = keys.map((k) => this.toPath(k)).filter((p) => existingPaths.has(p));
 		if (toDelete.length === 0) return false;
-		const message = toDelete.length === 1 ? this.msg(toDelete[0], null) : `batch delete ${toDelete.length} files`;
+		const message = toDelete.length === 1 ? this.msg(toDelete[0], null) : this.batchMsg("delete", toDelete);
 		await this._batchCommit({
 			delete: toDelete,
 			message
@@ -273,7 +285,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 		const allPaths = treeData.tree.filter((i) => i.type === "blob" && i.path && i.path.startsWith(this.prefix) && i.path.endsWith(this.suffix)).map((i) => i.path);
 		if (allPaths.length > 0) await this._batchCommit({
 			delete: allPaths,
-			message: `clear: remove ${allPaths.length} files`
+			message: this.batchMsg("clear", allPaths)
 		});
 	}
 	async *iterator(prefix) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "keyv-github",
-	"version": "1.3.0",
+	"version": "1.5.0",
 	"module": "src/index.ts",
 	"main": "dist/index.mjs",
 	"types": "dist/index.d.mts",
@@ -17,6 +17,8 @@
 	"type": "module",
 	"dependencies": {
 		"keyv": "^5.6.0",
+		"keyv-dir-store": "^0.0.9",
+		"keyv-nest": "^0.0.7",
 		"octokit": "^5.0.5"
 	},
 	"devDependencies": {

package/src/index.test.ts

@@ -386,7 +386,7 @@ describe("setMany", () => {
 		expect(mockFiles.get("b/2.txt")?.content).toBe("world");
 		expect(mockFiles.get("c/3.txt")?.content).toBe("!");
 		expect(messages).toHaveLength(1); // single commit
-		expect(messages[0]).toBe("batch update 3 files");
+		expect(messages[0]).toBe("batch set 3 files [skip ci]");
 	});
 
 	test("uses msg hook for single-entry batch", async () => {
@@ -440,7 +440,7 @@ describe("deleteMany", () => {
 		expect(mockFiles.has("b")).toBe(false);
 		expect(mockFiles.has("c")).toBe(true);
 		expect(messages).toHaveLength(1); // single commit
-		expect(messages[0]).toBe("batch delete 2 files");
+		expect(messages[0]).toBe("batch delete 2 files [skip ci]");
 	});
 
 	test("returns false when no keys exist", async () => {
@@ -527,15 +527,15 @@ describe("msg hook", () => {
 		expect(messages[messages.length - 1]).toBe("chore: rm to/remove");
 	});
 
-	test("default msg falls back to 'update <key>' / 'delete <key>'", async () => {
+	test("default msg falls back to 'update <key> [skip ci]' / 'delete <key> [skip ci]'", async () => {
 		const { store, messages } = makeStore();
 		await store.set("k", "v");
-		expect(messages[messages.length - 1]).toBe("update k");
+		expect(messages[messages.length - 1]).toBe("update k [skip ci]");
 
 		const files2 = new Map([["k2", { content: "v", sha: "s1" }]]);
 		const { store: store2, messages: messages2 } = makeStore(files2);
 		await store2.delete("k2");
-		expect(messages2[messages2.length - 1]).toBe("delete k2");
+		expect(messages2[messages2.length - 1]).toBe("delete k2 [skip ci]");
 	});
 });
 

package/src/index.ts

@@ -12,8 +12,20 @@ export interface KeyvGithubOptions {
 	url: string;
 	branch?: string;
 	client?: Octokit | Octokit["rest"];
-	/** Customize the commit message. value is null for deletes. */
+	/**
+	 * Customize the commit message for single-key operations. value is null for deletes.
+	 * @warning Consider adding `[skip ci]` to your commit messages to prevent
+	 * triggering CI workflows on each key-value update.
+	 */
 	msg?: (key: string, value: string | null) => string;
+	/**
+	 * Customize the commit message for batch operations (setMany, deleteMany, clear).
+	 * @param operation - 'set' | 'delete' | 'clear'
+	 * @param paths - array of file paths being modified
+	 * @warning Consider adding `[skip ci]` to your commit messages to prevent
+	 * triggering CI workflows on each key-value update.
+	 */
+	batchMsg?: (operation: "set" | "delete" | "clear", paths: string[]) => string;
 	/** clear() deletes every file in the repo and is disabled by default. Set to true to allow it. */
 	enableClear?: boolean;
 	/** Path prefix prepended to every key (e.g. 'data/'). Defaults to ''. */
@@ -29,6 +41,11 @@ export interface KeyvGithubOptions {
  *
  * Each key is a file path in the repo; the file content is the value.
  * Example: new KeyvGithub("https://github.com/owner/repo/tree/main", { client })
+ *
+ * @warning **Keys are validated but NOT sanitized.** You must ensure keys are valid
+ * GitHub file paths before calling any method. Invalid keys throw an error.
+ * Requirements: non-empty, no leading/trailing `/`, no `//`, no `.`/`..` segments, no null bytes.
+ * OS-specific invalid characters (e.g. `<>:"|?*\` on Windows) are NOT checked — sanitize them yourself.
  */
 export default class KeyvGithub
 	extends EventEmitter
@@ -46,6 +63,10 @@ export default class KeyvGithub
 	}
 	rest: Octokit["rest"];
 	private msg: (key: string, value: string | null) => string;
+	private batchMsg: (
+		operation: "set" | "delete" | "clear",
+		paths: string[],
+	) => string;
 	readonly enableClear: boolean;
 	readonly prefix: string;
 	readonly suffix: string;
@@ -70,7 +91,15 @@ export default class KeyvGithub
 				: (options.client ?? new Octokit().rest);
 		this.msg =
 			options.msg ??
-			((key, value) => (value === null ? `delete ${key}` : `update ${key}`));
+			((key, value) =>
+				value === null ? `delete ${key} [skip ci]` : `update ${key} [skip ci]`);
+		this.batchMsg =
+			options.batchMsg ??
+			((op, paths) => {
+				const n = paths.length;
+				if (op === "clear") return `clear: remove ${n} files [skip ci]`;
+				return `batch ${op} ${n} files [skip ci]`;
+			});
 		this.enableClear = options.enableClear ?? false;
 		this.prefix = options.prefix ?? "";
 		this.suffix = options.suffix ?? "";
@@ -319,10 +348,11 @@ export default class KeyvGithub
 			this.toPath(key),
 			String(value),
 		]);
+		const paths = entries.map(([p]) => p);
 		const message =
 			entries.length === 1
 				? this.msg(entries[0]![0], entries[0]![1])
-				: `batch update ${entries.length} files`;
+				: this.batchMsg("set", paths);
 		await this._batchCommit({ set: entries, message });
 	}
 
@@ -361,7 +391,7 @@ export default class KeyvGithub
 		const message =
 			toDelete.length === 1
 				? this.msg(toDelete[0]!, null)
-				: `batch delete ${toDelete.length} files`;
+				: this.batchMsg("delete", toDelete);
 		await this._batchCommit({ delete: toDelete, message });
 		return true;
 	}
@@ -397,7 +427,7 @@ export default class KeyvGithub
 		if (allPaths.length > 0) {
 			await this._batchCommit({
 				delete: allPaths,
-				message: `clear: remove ${allPaths.length} files`,
+				message: this.batchMsg("clear", allPaths),
 			});
 		}
 	}