keyv-github 1.3.0 → 1.4.0

package/README.md

@@ -99,6 +99,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
@@ -109,6 +111,18 @@ Keys must be valid relative file paths:
 
 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:

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,10 @@ 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.
  */
 declare class KeyvGithub extends EventEmitter implements KeyvStoreAdapter {
   opts: KeyvGithubOptions;
@@ -39,6 +55,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,10 @@ 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.
 */
 var KeyvGithub = class KeyvGithub extends EventEmitter {
 	opts;
@@ -20,6 +24,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 	}
 	rest;
 	msg;
+	batchMsg;
 	enableClear;
 	prefix;
 	suffix;
@@ -37,7 +42,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 +233,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 +261,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 +284,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.4.0",
 	"module": "src/index.ts",
 	"main": "dist/index.mjs",
 	"types": "dist/index.d.mts",

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,10 @@ 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.
  */
 export default class KeyvGithub
 	extends EventEmitter
@@ -46,6 +62,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 +90,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 +347,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 +390,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 +426,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),
 			});
 		}
 	}