keyv-github 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -11,6 +11,10 @@ interface KeyvGithubOptions {
   msg?: (key: string, value: string | null) => 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 ''. */
+  prefix?: string;
+  /** Path suffix appended to every key (e.g. '.json'). Defaults to ''. */
+  suffix?: string;
 }
 /**
  * Keyv storage adapter backed by a GitHub repository.
@@ -29,11 +33,20 @@ declare class KeyvGithub extends EventEmitter implements KeyvStoreAdapter {
   rest: Octokit["rest"];
   private msg;
   readonly enableClear: boolean;
+  readonly prefix: string;
+  readonly suffix: string;
   constructor(url: string, options?: Omit<KeyvGithubOptions, "url">);
+  /** Converts a user key to the GitHub file path. */
+  private toPath;
+  /**
+   * Converts a GitHub file path back to a user key.
+   * Returns null if the path does not match the configured prefix/suffix.
+   */
+  private fromPath;
   private static isHttpError;
-  private validateKey;
+  private validatePath;
   get<Value>(key: string): Promise<StoredData<Value> | undefined>;
-  set(key: string, value: any, _ttl?: number): Promise<void>;
+  set(key: string, value: any, ttl?: number): Promise<void>;
   delete(key: string): Promise<boolean>;
   has(key: string): Promise<boolean>;
   /**
@@ -46,7 +59,6 @@ declare class KeyvGithub extends EventEmitter implements KeyvStoreAdapter {
   setMany(values: Array<{
     key: string;
     value: any;
-    ttl?: number;
   }>): Promise<void>;
   /**
    * Keyv batch-delete: deletes multiple keys in a single commit (7 API calls total).

package/dist/index.mjs

@@ -21,9 +21,11 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 	rest;
 	msg;
 	enableClear;
+	prefix;
+	suffix;
 	constructor(url, options = {}) {
 		super();
-		const match = url.match(/* @__PURE__ */ new RegExp("(?:.*github\\.com[/:])?([^/:]+)/([^/]+?)(?:\\.git)?(?:/tree/([^?#]+))?(?:[?#].*)?$"));
+		const match = url.match(/(?:.*github\.com[/:])?([^/:]+)\/([^/]+?)(?:\.git)?(?:\/tree\/([^?#]+))?(?:[?#].*)?$/);
 		if (!match) throw new Error(`Invalid GitHub repo URL: ${url}`);
 		this.owner = match[1];
 		this.repo = match[2];
@@ -35,25 +37,40 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 		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;
+		this.prefix = options.prefix ?? "";
+		this.suffix = options.suffix ?? "";
+	}
+	/** Converts a user key to the GitHub file path. */
+	toPath(key) {
+		return this.prefix + key + this.suffix;
+	}
+	/**
+	* Converts a GitHub file path back to a user key.
+	* Returns null if the path does not match the configured prefix/suffix.
+	*/
+	fromPath(path) {
+		if (!path.startsWith(this.prefix) || !path.endsWith(this.suffix)) return null;
+		const end = this.suffix ? path.length - this.suffix.length : void 0;
+		return path.slice(this.prefix.length, end);
 	}
 	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}`);
+	validatePath(path) {
+		if (!path) throw new Error("Path must not be empty");
+		if (path.startsWith("/")) throw new Error(`Path must not start with '/': ${path}`);
+		if (path.endsWith("/")) throw new Error(`Path must not end with '/': ${path}`);
+		if (path.includes("//")) throw new Error(`Path must not contain '//': ${path}`);
+		if (path.includes("\0")) throw new Error(`Path must not contain null bytes: ${path}`);
+		if (path.split("/").some((seg) => seg === ".." || seg === ".")) throw new Error(`Path must not contain '.' or '..' segments: ${path}`);
 	}
 	async get(key) {
-		this.validateKey(key);
+		this.validatePath(this.toPath(key));
 		try {
 			const { data } = await this.rest.repos.getContent({
 				owner: this.owner,
 				repo: this.repo,
-				path: key,
+				path: this.toPath(key),
 				ref: this.ref
 			});
 			if (Array.isArray(data) || data.type !== "file") return void 0;
@@ -63,14 +80,17 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			throw e;
 		}
 	}
-	async set(key, value, _ttl) {
-		this.validateKey(key);
+	async set(key, value, ttl) {
+		if (ttl !== void 0) throw new Error("TTL is not supported natively by keyv-github. Use new Keyv(store) which handles TTL via value expiration metadata.");
+		if (typeof value !== "string") throw new Error("keyv-github only supports string values natively. Use new Keyv(store) which serializes values automatically.");
+		this.validatePath(this.toPath(key));
+		const path = this.toPath(key);
 		let sha;
 		try {
 			const { data } = await this.rest.repos.getContent({
 				owner: this.owner,
 				repo: this.repo,
-				path: key,
+				path,
 				ref: this.ref
 			});
 			if (!Array.isArray(data) && data.type === "file") sha = data.sha;
@@ -80,28 +100,29 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 		await this.rest.repos.createOrUpdateFileContents({
 			owner: this.owner,
 			repo: this.repo,
-			path: key,
-			message: this.msg(key, value),
+			path,
+			message: this.msg(path, value),
 			content: Buffer.from(String(value)).toString("base64"),
 			sha,
 			branch: this.ref
 		});
 	}
 	async delete(key) {
-		this.validateKey(key);
+		this.validatePath(this.toPath(key));
+		const path = this.toPath(key);
 		try {
 			const { data } = await this.rest.repos.getContent({
 				owner: this.owner,
 				repo: this.repo,
-				path: key,
+				path,
 				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),
+				path,
+				message: this.msg(path, null),
 				sha: data.sha,
 				branch: this.ref
 			});
@@ -112,12 +133,12 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 		}
 	}
 	async has(key) {
-		this.validateKey(key);
+		this.validatePath(this.toPath(key));
 		try {
 			const { data } = await this.rest.repos.getContent({
 				owner: this.owner,
 				repo: this.repo,
-				path: key,
+				path: this.toPath(key),
 				ref: this.ref
 			});
 			return !Array.isArray(data) && data.type === "file";
@@ -178,8 +199,11 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 	/** 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);
+		for (const { key, value } of values) {
+			if (typeof value !== "string") throw new Error("keyv-github only supports string values natively. Use new Keyv(store) which serializes values automatically.");
+			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`;
 		await this._batchCommit({
 			set: entries,
@@ -192,7 +216,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 	*/
 	async deleteMany(keys) {
 		if (keys.length === 0) return false;
-		for (const key of keys) this.validateKey(key);
+		for (const key of keys) this.validatePath(this.toPath(key));
 		const { data: refData } = await this.rest.git.getRef({
 			owner: this.owner,
 			repo: this.repo,
@@ -205,7 +229,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			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));
+		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`;
 		await this._batchCommit({
@@ -227,7 +251,7 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			tree_sha: refData.object.sha,
 			recursive: "1"
 		});
-		const allPaths = treeData.tree.filter((i) => i.type === "blob" && i.path).map((i) => i.path);
+		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`
@@ -245,10 +269,13 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			tree_sha: refData.object.sha,
 			recursive: "1"
 		});
-		const files = treeData.tree.filter((item) => item.type === "blob" && item.path && (!prefix || item.path.startsWith(prefix)));
+		const pathPrefix = this.prefix + (prefix ?? "");
+		const files = treeData.tree.filter((item) => item.type === "blob" && item.path && item.path.startsWith(pathPrefix) && item.path.endsWith(this.suffix));
 		for (const file of files) if (file.path) {
-			const value = await this.get(file.path);
-			if (value !== void 0) yield [file.path, value];
+			const key = this.fromPath(file.path);
+			if (key === null || key === "") continue;
+			const value = await this.get(key);
+			if (value !== void 0) yield [key, value];
 		}
 	}
 };

package/examples/hello-today.ts

@@ -4,7 +4,9 @@ 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 kv = new KeyvGithub("https://github.com/snomiao/keyv-github/tree/main", {
+	client,
+});
 
 const key = "data/hello-today.txt";
 const value = new Date().toISOString();
@@ -19,19 +21,19 @@ 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",
+	"",
+	"/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}`);
-  }
+	try {
+		await kv.get(bad);
+	} catch (e: any) {
+		console.log(`  ✗ ${JSON.stringify(bad)} → ${e.message}`);
+	}
 }

package/package.json

@@ -1,27 +1,32 @@
 {
-  "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"
-  }
+	"name": "keyv-github",
+	"version": "1.2.0",
+	"module": "src/index.ts",
+	"main": "dist/index.mjs",
+	"types": "dist/index.d.mts",
+	"exports": {
+		".": {
+			"import": "./dist/index.mjs",
+			"types": "./dist/index.d.mts"
+		}
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/snomiao/keyv-github"
+	},
+	"type": "module",
+	"dependencies": {
+		"keyv": "^5.6.0",
+		"octokit": "^5.0.5"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"semantic-release": "^25.0.3",
+		"tsdown": "^0.20.3",
+		"typescript": "^5.9.3"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"test": "bun test"
+	}
 }