This is a key-value based "database" library that uses Git for the underlying storage. It provides a get/set interface for storing and retrieving data using hosted on GitHub. Other providers can be added in the future. This is useful in scenarios where you don't really care about your write frequency or latency, and your repository (or files in it) are deployed to something like a CDN or Vercel Edge Config.
Inspired by this @cramforce tweet. I don't necessarily recommend using this in production. Mostly written by claude-3-opus.
- Set and retrieve key-value pairs using a simple API
- Automatically commit and push changes to a GitHub repository
- Create and manage branches for organizing data
- Open pull requests programmatically
To use this library in your project, you can install it via npm:
pnpm i gitkv
# or yarn add gitkv
# or npm i gitkv
First, import the GithubProvider
class from the library:
import { GithubProvider } from "gitkv";
Then create an instance of the GithubProvider
:
const config = {
// You should probably read this from environment variables
personalAccessToken: "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN",
repo: "YOUR_REPOSITORY_NAME",
branch: "BRANCH_NAME", // Optional, defaults to 'main'
owner: "YOUR_GITHUB_USERNAME",
};
const provider = new GithubProvider(config);
To set a key-value pair, use the set
method:
const path = "path/to/your/key"; // The path to the key relative from the root of the repository
const data = "Your data goes here";
const message = "Commit message";
// Commits and pushes the changes to the repository. To queue multiple changes, use the `add` method.
const commit = await provider.set(path, data, message);
To retrieve the value associated with a key, use the get
method:
const path = "path/to/your/key";
const value = await provider.get(path);
You likely want to never use this, or implement some heavy caching around your get
calls.
Ideally the files you're writing are deployed somewhere you're supposed to read files from programatically.
You can also stage changes using the add
method (similar to git add
):
provider.add("path/to/your/key", "Your data goes here");
To commit the staged changes, use the commit
method:
const commit = provider.commit("Commit message");
To push the committed changes to the GitHub repository, use the push
method:
const commitCount = await provider.push();
You can open a pull request programmatically using the openPullRequest
method:
const pullRequestUrl = await provider.openPullRequest(
"Pull Request Title",
"Pull Request Body",
"head-branch",
);
The library throws a GitKVError
when an error occurs. You can catch and handle these errors in your code:
import { GitKVError } from "gitkv";
try {
// Your code here
} catch (error) {
if (error instanceof GitKVError) {
console.error("Git DB Error:", error.message);
} else {
console.error("Unknown Error:", error);
}
}
This library is open-source and available under the MIT License.