{"id":15707009,"url":"https://github.com/maxleiter/gitkv","last_synced_at":"2025-05-12T19:13:34.301Z","repository":{"id":227027865,"uuid":"770144761","full_name":"MaxLeiter/gitkv","owner":"MaxLeiter","description":"A KV wrapper around GitHub in TypeScript","archived":false,"fork":false,"pushed_at":"2024-03-16T05:49:04.000Z","size":74,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-12T19:13:23.549Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaxLeiter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-11T02:21:00.000Z","updated_at":"2024-03-21T04:21:34.000Z","dependencies_parsed_at":"2024-10-24T07:45:48.582Z","dependency_job_id":"130ae020-bace-41cc-a113-6f3806211084","html_url":"https://github.com/MaxLeiter/gitkv","commit_stats":null,"previous_names":["maxleiter/gitkv"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxLeiter%2Fgitkv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxLeiter%2Fgitkv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxLeiter%2Fgitkv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxLeiter%2Fgitkv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaxLeiter","download_url":"https://codeload.github.com/MaxLeiter/gitkv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253805850,"owners_count":21967053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T20:32:29.034Z","updated_at":"2025-05-12T19:13:34.281Z","avatar_url":"https://github.com/MaxLeiter.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitkv\n\nThis 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](https://vercel.com/docs/storage/edge-config). \n\nInspired by [this @cramforce tweet](https://twitter.com/cramforce/status/1766656925809381772). I don't necessarily recommend using this in production.\nMostly written by [claude-3-opus](https://www.anthropic.com/news/claude-3-family).\n\n## Features\n\n- Set and retrieve key-value pairs using a simple API\n- Automatically commit and push changes to a GitHub repository\n- Create and manage branches for organizing data\n- Open pull requests programmatically\n\n## Installation\n\nTo use this library in your project, you can install it via npm:\n\n```bash\npnpm i gitkv\n# or yarn add gitkv\n# or npm i gitkv\n```\n\n## Usage\n\nFirst, import the `GithubProvider` class from the library:\n\n```typescript\nimport { GithubProvider } from \"gitkv\";\n```\n\nThen create an instance of the `GithubProvider`:\n\n```typescript\nconst config = {\n  // You should probably read this from environment variables \n  personalAccessToken: \"YOUR_GITHUB_PERSONAL_ACCESS_TOKEN\",\n  repo: \"YOUR_REPOSITORY_NAME\",\n  branch: \"BRANCH_NAME\", // Optional, defaults to 'main'\n  owner: \"YOUR_GITHUB_USERNAME\",\n};\n\nconst provider = new GithubProvider(config);\n```\n\n### Setting a Key-Value Pair\n\nTo set a key-value pair, use the `set` method:\n\n```typescript\nconst path = \"path/to/your/key\"; // The path to the key relative from the root of the repository\nconst data = \"Your data goes here\";\nconst message = \"Commit message\";\n\n// Commits and pushes the changes to the repository. To queue multiple changes, use the `add` method.\nconst commit = await provider.set(path, data, message);\n```\n\n### Retrieving a Value\n\nTo retrieve the value associated with a key, use the `get` method:\n\n```typescript\nconst path = \"path/to/your/key\";\n\nconst value = await provider.get(path);\n```\n\nYou likely want to never use this, or implement some heavy caching around your `get` calls. \nIdeally the files you're writing are deployed somewhere you're supposed to read files from programatically. \n\n### Staging Changes\n\nYou can also stage changes using the `add` method (similar to `git add`):\n\n```typescript\nprovider.add(\"path/to/your/key\", \"Your data goes here\");\n```\n\n### Committing Changes\n\nTo commit the staged changes, use the `commit` method:\n\n```typescript\nconst commit = provider.commit(\"Commit message\");\n```\n\n### Pushing Changes\n\nTo push the committed changes to the GitHub repository, use the `push` method:\n\n```typescript\nconst commitCount = await provider.push();\n```\n\n### Opening a Pull Request\n\nYou can open a pull request programmatically using the `openPullRequest` method:\n\n```typescript\nconst pullRequestUrl = await provider.openPullRequest(\n  \"Pull Request Title\",\n  \"Pull Request Body\",\n  \"head-branch\",\n);\n```\n\n## Error Handling\n\nThe library throws a `GitKVError` when an error occurs. You can catch and handle these errors in your code:\n\n```typescript\nimport { GitKVError } from \"gitkv\";\n\ntry {\n  // Your code here\n} catch (error) {\n  if (error instanceof GitKVError) {\n    console.error(\"Git DB Error:\", error.message);\n  } else {\n    console.error(\"Unknown Error:\", error);\n  }\n}\n```\n\n## License\n\nThis library is open-source and available under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxleiter%2Fgitkv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxleiter%2Fgitkv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxleiter%2Fgitkv/lists"}