keyv-github 1.0.0 → 1.2.0

package/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+# Release workflow
+
+# check https://www.npmjs.com/package/[package-name]/access for OIDC setup
+# 1. repo = this repo
+# 2. package-name = package to publish
+
+name: Release
+description: "Release workflow for publishing package"
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    tags:
+      - 'v*.*.*'
+    branches:
+      - main
+      - beta
+
+permissions:
+  id-token: write # required for OIDC
+  contents: write # read and write access to repository contents
+  issues: write  
+
+jobs:
+  build-test-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with: {node-version: latest} #[semantic-release]: node version >=20.8.1 is required. Found v18.20.5.
+      - uses: oven-sh/setup-bun@v2
+      - run: bun i
+      - run: bunx biofix
+      - run: bun run build
+      - run: bun run test
+      - if: github.event_name == 'push'
+        run: bunx semantic-release
+        env:
+          # reminder to setup read/write permission for this token
+          # here: REPO_URL/settings/actions
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -29,7 +29,7 @@ import Keyv from "keyv";
 import KeyvGithub from "keyv-github";
 
 const store = new KeyvGithub("https://github.com/owner/repo/tree/main", {
-  client: new Octokit({ auth: process.env.GITHUB_TOKEN }),
+  client: new Octokit({ auth: process.env.GITHUB_TOKEN }), // only required if you want .set(), or .get() in private repo
 });
 
 const kv = new Keyv({ store });
@@ -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