keyv-github 1.0.0

package/dist/index.mjs

@@ -0,0 +1,257 @@
+import { EventEmitter } from "events";
+import { Octokit } from "octokit";
+
+//#region src/index.ts
+/**
+* Keyv storage adapter backed by a GitHub repository.
+*
+* 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 })
+*/
+var KeyvGithub = class KeyvGithub extends EventEmitter {
+	opts;
+	namespace;
+	owner;
+	repo;
+	ref;
+	/** Alias for {@link ref}. */
+	get branch() {
+		return this.ref;
+	}
+	rest;
+	msg;
+	enableClear;
+	constructor(url, options = {}) {
+		super();
+		const match = url.match(/* @__PURE__ */ new RegExp("(?:.*github\\.com[/:])?([^/:]+)/([^/]+?)(?:\\.git)?(?:/tree/([^?#]+))?(?:[?#].*)?$"));
+		if (!match) throw new Error(`Invalid GitHub repo URL: ${url}`);
+		this.owner = match[1];
+		this.repo = match[2];
+		this.ref = options.branch ?? match[3] ?? "main";
+		this.opts = {
+			url,
+			...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.enableClear = options.enableClear ?? false;
+	}
+	static isHttpError(e) {
+		return typeof e === "object" && e !== null && "status" in e && typeof e.status === "number";
+	}
+	validateKey(key) {
+		if (!key) throw new Error("Key must not be empty");
+		if (key.startsWith("/")) throw new Error(`Key must not start with '/': ${key}`);
+		if (key.endsWith("/")) throw new Error(`Key must not end with '/': ${key}`);
+		if (key.includes("//")) throw new Error(`Key must not contain '//': ${key}`);
+		if (key.includes("\0")) throw new Error(`Key must not contain null bytes: ${key}`);
+		if (key.split("/").some((seg) => seg === ".." || seg === ".")) throw new Error(`Key must not contain '.' or '..' segments: ${key}`);
+	}
+	async get(key) {
+		this.validateKey(key);
+		try {
+			const { data } = await this.rest.repos.getContent({
+				owner: this.owner,
+				repo: this.repo,
+				path: key,
+				ref: this.ref
+			});
+			if (Array.isArray(data) || data.type !== "file") return void 0;
+			return Buffer.from(data.content, "base64").toString("utf-8");
+		} catch (e) {
+			if (KeyvGithub.isHttpError(e) && e.status === 404) return void 0;
+			throw e;
+		}
+	}
+	async set(key, value, _ttl) {
+		this.validateKey(key);
+		let sha;
+		try {
+			const { data } = await this.rest.repos.getContent({
+				owner: this.owner,
+				repo: this.repo,
+				path: key,
+				ref: this.ref
+			});
+			if (!Array.isArray(data) && data.type === "file") sha = data.sha;
+		} catch (e) {
+			if (!KeyvGithub.isHttpError(e) || e.status !== 404) throw e;
+		}
+		await this.rest.repos.createOrUpdateFileContents({
+			owner: this.owner,
+			repo: this.repo,
+			path: key,
+			message: this.msg(key, value),
+			content: Buffer.from(String(value)).toString("base64"),
+			sha,
+			branch: this.ref
+		});
+	}
+	async delete(key) {
+		this.validateKey(key);
+		try {
+			const { data } = await this.rest.repos.getContent({
+				owner: this.owner,
+				repo: this.repo,
+				path: key,
+				ref: this.ref
+			});
+			if (Array.isArray(data) || data.type !== "file") return false;
+			await this.rest.repos.deleteFile({
+				owner: this.owner,
+				repo: this.repo,
+				path: key,
+				message: this.msg(key, null),
+				sha: data.sha,
+				branch: this.ref
+			});
+			return true;
+		} catch (e) {
+			if (KeyvGithub.isHttpError(e) && e.status === 404) return false;
+			throw e;
+		}
+	}
+	async has(key) {
+		this.validateKey(key);
+		try {
+			const { data } = await this.rest.repos.getContent({
+				owner: this.owner,
+				repo: this.repo,
+				path: key,
+				ref: this.ref
+			});
+			return !Array.isArray(data) && data.type === "file";
+		} catch (e) {
+			if (KeyvGithub.isHttpError(e) && e.status === 404) return false;
+			throw e;
+		}
+	}
+	/**
+	* Commit multiple file changes in one roundtrip: 5 API calls for any N.
+	* set entries: written inline into the tree (no separate blob creation).
+	* delete paths: removed by setting sha: null in the tree.
+	*/
+	async _batchCommit(params) {
+		const { set = [], delete: del = [], message } = params;
+		const { data: refData } = await this.rest.git.getRef({
+			owner: this.owner,
+			repo: this.repo,
+			ref: `heads/${this.ref}`
+		});
+		const headSha = refData.object.sha;
+		const { data: commitData } = await this.rest.git.getCommit({
+			owner: this.owner,
+			repo: this.repo,
+			commit_sha: headSha
+		});
+		const treeEntries = [...set.map(([path, content]) => ({
+			path,
+			mode: "100644",
+			type: "blob",
+			content
+		})), ...del.map((path) => ({
+			path,
+			mode: "100644",
+			type: "blob",
+			sha: null
+		}))];
+		const { data: newTree } = await this.rest.git.createTree({
+			owner: this.owner,
+			repo: this.repo,
+			base_tree: commitData.tree.sha,
+			tree: treeEntries
+		});
+		const { data: newCommit } = await this.rest.git.createCommit({
+			owner: this.owner,
+			repo: this.repo,
+			message,
+			tree: newTree.sha,
+			parents: [headSha]
+		});
+		await this.rest.git.updateRef({
+			owner: this.owner,
+			repo: this.repo,
+			ref: `heads/${this.ref}`,
+			sha: newCommit.sha
+		});
+	}
+	/** Keyv batch-set: writes multiple keys in a single commit (5 API calls total). */
+	async setMany(values) {
+		if (values.length === 0) return;
+		const entries = values.map(({ key, value }) => [key, String(value)]);
+		for (const [key] of entries) this.validateKey(key);
+		const message = entries.length === 1 ? this.msg(entries[0][0], entries[0][1]) : `batch update ${entries.length} files`;
+		await this._batchCommit({
+			set: entries,
+			message
+		});
+	}
+	/**
+	* Keyv batch-delete: deletes multiple keys in a single commit (7 API calls total).
+	* Returns true if any keys were deleted.
+	*/
+	async deleteMany(keys) {
+		if (keys.length === 0) return false;
+		for (const key of keys) this.validateKey(key);
+		const { data: refData } = await this.rest.git.getRef({
+			owner: this.owner,
+			repo: this.repo,
+			ref: `heads/${this.ref}`
+		});
+		const { data: treeData } = await this.rest.git.getTree({
+			owner: this.owner,
+			repo: this.repo,
+			tree_sha: refData.object.sha,
+			recursive: "1"
+		});
+		const existingPaths = new Set(treeData.tree.filter((i) => i.type === "blob" && i.path).map((i) => i.path));
+		const toDelete = keys.filter((k) => existingPaths.has(k));
+		if (toDelete.length === 0) return false;
+		const message = toDelete.length === 1 ? this.msg(toDelete[0], null) : `batch delete ${toDelete.length} files`;
+		await this._batchCommit({
+			delete: toDelete,
+			message
+		});
+		return true;
+	}
+	async clear() {
+		if (!this.enableClear) throw new Error("clear() is disabled. Set enableClear: true in options to allow it.");
+		const { data: refData } = await this.rest.git.getRef({
+			owner: this.owner,
+			repo: this.repo,
+			ref: `heads/${this.ref}`
+		});
+		const { data: treeData } = await this.rest.git.getTree({
+			owner: this.owner,
+			repo: this.repo,
+			tree_sha: refData.object.sha,
+			recursive: "1"
+		});
+		const allPaths = treeData.tree.filter((i) => i.type === "blob" && i.path).map((i) => i.path);
+		if (allPaths.length > 0) await this._batchCommit({
+			delete: allPaths,
+			message: `clear: remove ${allPaths.length} files`
+		});
+	}
+	async *iterator(prefix) {
+		const { data: refData } = await this.rest.git.getRef({
+			owner: this.owner,
+			repo: this.repo,
+			ref: `heads/${this.ref}`
+		});
+		const { data: treeData } = await this.rest.git.getTree({
+			owner: this.owner,
+			repo: this.repo,
+			tree_sha: refData.object.sha,
+			recursive: "1"
+		});
+		const files = treeData.tree.filter((item) => item.type === "blob" && item.path && (!prefix || item.path.startsWith(prefix)));
+		for (const file of files) if (file.path) {
+			const value = await this.get(file.path);
+			if (value !== void 0) yield [file.path, value];
+		}
+	}
+};
+
+//#endregion
+export { KeyvGithub as default };

package/examples/hello-today.ts

@@ -0,0 +1,37 @@
+import { Octokit } from "octokit";
+import KeyvGithub from "../src/index.ts";
+
+// Authenticate via GITHUB_TOKEN env var (required for writes)
+const client = new Octokit({ auth: process.env.GITHUB_TOKEN });
+
+const kv = new KeyvGithub("https://github.com/snomiao/keyv-github/tree/main", { client });
+
+const key = "data/hello-today.txt";
+const value = new Date().toISOString();
+
+console.log(`set  ${key} = ${value}`);
+await kv.set(key, value);
+
+const read = await kv.get(key);
+console.log(`get  ${key} = ${read}`);
+
+console.log(`has  ${key} = ${await kv.has(key)}`);
+
+// Demonstrate path validation — these throw immediately without hitting the API
+const invalidPaths = [
+  "",
+  "/absolute/path",
+  "trailing/slash/",
+  "double//slash",
+  "../escape",
+  "a/./b",
+];
+
+console.log("\nPath validation:");
+for (const bad of invalidPaths) {
+  try {
+    await kv.get(bad);
+  } catch (e: any) {
+    console.log(`  ✗ ${JSON.stringify(bad)} → ${e.message}`);
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "keyv-github",
+  "version": "1.0.0",
+  "module": "src/index.ts",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "keyv": "^5.6.0",
+    "octokit": "^5.0.5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "bun test"
+  }
+}