gitkv

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.

Features

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

Installation

To use this library in your project, you can install it via npm:

pnpm i gitkv
# or yarn add gitkv
# or npm i gitkv

Usage

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);

Setting a Key-Value Pair

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);

Retrieving a Value

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.

Staging Changes

You can also stage changes using the add method (similar to git add):

provider.add("path/to/your/key", "Your data goes here");

Committing Changes

To commit the staged changes, use the commit method:

const commit = provider.commit("Commit message");

Pushing Changes

To push the committed changes to the GitHub repository, use the push method:

const commitCount = await provider.push();

Opening a Pull Request

You can open a pull request programmatically using the openPullRequest method:

const pullRequestUrl = await provider.openPullRequest(
  "Pull Request Title",
  "Pull Request Body",
  "head-branch",
);

Error Handling

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);
  }
}

License

This library is open-source and available under the MIT License.

MaxLeiter / gitkv