keyv-github 1.1.0 → 1.2.0

package/README.md

@@ -45,11 +45,38 @@ await kv.delete("data/hello.txt");
 new KeyvGithub(repoUrl, options?)
 ```
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `branch` | `string` | parsed from URL or `"main"` | Target branch |
-| `client` | `Octokit` | `new Octokit()` | Authenticated Octokit instance |
-| `msg` | `(key, value) => string` | `"update <key>"` / `"delete <key>"` | Customize commit messages; `value` is `null` for deletes |
+| Option   | Type                     | Default                             | Description                                              |
+| -------- | ------------------------ | ----------------------------------- | -------------------------------------------------------- |
+| `branch` | `string`                 | parsed from URL or `"main"`         | Target branch                                            |
+| `client` | `Octokit`                | `new Octokit()`                     | Authenticated Octokit instance                           |
+| `msg`    | `(key, value) => string` | `"update <key>"` / `"delete <key>"` | Customize commit messages; `value` is `null` for deletes |
+| `prefix` | `string`                 | `""`                                | Path prefix prepended to every key (e.g. `"data/"`)      |
+| `suffix` | `string`                 | `""`                                | Path suffix appended to every key (e.g. `".json"`)       |
+
+### Store limitations
+
+When using `KeyvGithub` directly (without wrapping in `Keyv`):
+
+- **Values must be strings** — objects, arrays, and numbers will throw an error
+- **TTL is not supported** — passing a TTL parameter throws an error
+
+To store non-string values or use TTL, wrap the store with `new Keyv(store)`:
+
+```ts
+// Direct usage: strings only, no TTL
+await store.set("key", "string value"); // ✓
+await store.set("key", { obj: true });  // ✗ throws error
+await store.set("key", "value", 1000);  // ✗ throws error
+
+// With Keyv wrapper: any serializable value, TTL supported
+const kv = new Keyv({ store });
+await kv.set("key", { obj: true });     // ✓ serialized automatically
+await kv.set("key", "value", 1000);     // ✓ TTL handled by Keyv
+```
+
+### TTL
+
+TTL is **not enforced at the adapter level** — GitHub has no native file expiry. If you pass a `ttl` to `new Keyv({ store, ttl })`, Keyv handles it by wrapping values as `{"value":…,"expires":…}` and filtering on read. Expired files remain in the repo as inert files until overwritten or deleted. This adapter is best suited for long-lived or permanent storage.
 
 ### URL formats accepted
 
@@ -66,9 +93,7 @@ owner/repo/tree/my-branch
 ```ts
 const store = new KeyvGithub("owner/repo", {
   msg: (key, value) =>
-    value === null
-      ? `chore: delete ${key}`
-      : `chore: update ${key} → ${value.slice(0, 40)}`,
+    value === null ? `chore: delete ${key}` : `chore: update ${key} → ${value.slice(0, 40)}`,
 });
 ```
 
@@ -84,6 +109,17 @@ Keys must be valid relative file paths:
 
 Invalid keys throw synchronously before any API request.
 
+## See Also
+
+Other Keyv storage adapters by the same author:
+
+- [keyv-sqlite](https://github.com/snomiao/keyv-sqlite) — SQLite storage adapter
+- [keyv-mongodb-store](https://github.com/snomiao/keyv-mongodb-store) — MongoDB storage adapter
+- [keyv-nedb-store](https://github.com/snomiao/keyv-nedb-store) — NeDB embedded file-based adapter
+- [keyv-dir-store](https://github.com/snomiao/keyv-dir-store) — file-per-key directory adapter with TTL via mtime
+- [keyv-cache-proxy](https://github.com/snomiao/keyv-cache-proxy) — transparent caching proxy that wraps any object
+- [keyv-nest](https://github.com/snomiao/keyv-nest) — hierarchical multi-layer caching adapter
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -46,7 +46,7 @@ declare class KeyvGithub extends EventEmitter implements KeyvStoreAdapter {
   private static isHttpError;
   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>;
   /**
@@ -59,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

@@ -80,7 +80,9 @@ var KeyvGithub = class KeyvGithub extends EventEmitter {
 			throw e;
 		}
 	}
-	async set(key, value, _ttl) {
+	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;
@@ -197,7 +199,10 @@ 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;
-		for (const { key } of values) this.validatePath(this.toPath(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({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "keyv-github",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"module": "src/index.ts",
 	"main": "dist/index.mjs",
 	"types": "dist/index.d.mts",

package/src/index.test.ts

@@ -204,7 +204,9 @@ describe("KeyvGithub constructor", () => {
 		const client = makeMockClient();
 		const store = new KeyvGithub(
 			"https://github.com/owner/repo/tree/feature/my-branch",
-			{ client: client.rest as unknown as Octokit["rest"] },
+			{
+				client: client.rest as unknown as Octokit["rest"],
+			},
 		);
 		expect(store.branch).toBe("feature/my-branch");
 	});
@@ -294,6 +296,26 @@ describe("set", () => {
 		await store.set("unicode", "日本語テスト 🎉");
 		expect(mockFiles.get("unicode")?.content).toBe("日本語テスト 🎉");
 	});
+
+	test("throws when TTL is provided (not supported natively)", async () => {
+		const { store } = makeStore();
+		expect(store.set("key", "value", 1000)).rejects.toThrow(
+			"TTL is not supported natively",
+		);
+	});
+
+	test("throws when value is not a string", async () => {
+		const { store } = makeStore();
+		expect(store.set("key", { obj: true })).rejects.toThrow(
+			"only supports string values",
+		);
+		expect(store.set("key", 123)).rejects.toThrow(
+			"only supports string values",
+		);
+		expect(store.set("key", ["array"])).rejects.toThrow(
+			"only supports string values",
+		);
+	});
 });
 
 describe("delete", () => {
@@ -391,6 +413,17 @@ describe("setMany", () => {
 		).rejects.toThrow();
 		expect(mockFiles.size).toBe(0);
 	});
+
+	test("throws when any value is not a string", async () => {
+		const { store, mockFiles } = makeStore();
+		expect(
+			store.setMany([
+				{ key: "a", value: "ok" },
+				{ key: "b", value: { obj: true } },
+			]),
+		).rejects.toThrow("only supports string values");
+		expect(mockFiles.size).toBe(0);
+	});
 });
 
 describe("deleteMany", () => {

package/src/index.ts

@@ -124,7 +124,19 @@ export default class KeyvGithub
 		}
 	}
 
-	async set(key: string, value: any, _ttl?: number): Promise<void> {
+	async set(key: string, value: any, ttl?: number): Promise<void> {
+		if (ttl !== undefined) {
+			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: string | undefined;
@@ -257,11 +269,17 @@ export default class KeyvGithub
 	}
 
 	/** Keyv batch-set: writes multiple keys in a single commit (5 API calls total). */
-	async setMany(
-		values: Array<{ key: string; value: any; ttl?: number }>,
-	): Promise<void> {
+	async setMany(values: Array<{ key: string; value: any }>): Promise<void> {
 		if (values.length === 0) return;
-		for (const { key } of values) this.validatePath(this.toPath(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: [string, string][] = values.map(({ key, value }) => [
 			this.toPath(key),
 			String(value),