{"id":15365555,"url":"https://github.com/tunnckocore/github-kv-storage","last_synced_at":"2026-01-20T03:30:41.070Z","repository":{"id":151733177,"uuid":"624648219","full_name":"tunnckoCore/github-kv-storage","owner":"tunnckoCore","description":"StorageArea implementation for GitHub, using the REST v4 API. Because everything else sucks, and I need a basic, centralized, and reliable database.","archived":false,"fork":false,"pushed_at":"2023-04-07T01:19:09.000Z","size":12,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T19:16:49.853Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tunnckoCore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"ko_fi":"tunnckoCore","patreon":"tunnckoCore","github":["tunnckoCore"],"custom":["https://gum.co/tunnckoCoreRecurringDonation","https://gum.co/tunnckocorePatronLicense"]}},"created_at":"2023-04-07T00:05:58.000Z","updated_at":"2023-04-07T04:51:25.000Z","dependencies_parsed_at":"2023-07-24T14:33:43.325Z","dependency_job_id":null,"html_url":"https://github.com/tunnckoCore/github-kv-storage","commit_stats":null,"previous_names":["tunnckocore/github-storage"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tunnckoCore%2Fgithub-kv-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tunnckoCore%2Fgithub-kv-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tunnckoCore%2Fgithub-kv-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tunnckoCore%2Fgithub-kv-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tunnckoCore","download_url":"https://codeload.github.com/tunnckoCore/github-kv-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247492755,"owners_count":20947584,"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-01T13:15:04.121Z","updated_at":"2026-01-20T03:30:41.038Z","avatar_url":"https://github.com/tunnckoCore.png","language":"JavaScript","funding_links":["https://ko-fi.com/tunnckoCore","https://patreon.com/tunnckoCore","https://github.com/sponsors/tunnckoCore","https://gum.co/tunnckoCoreRecurringDonation","https://gum.co/tunnckocorePatronLicense"],"categories":[],"sub_categories":[],"readme":"# github-kv-storage\n\n\u003e StorageArea implementation for GitHub, using the REST v4 API. Because everything else sucks and I need a basic, centralized, and reliable database\n\nShould work as \"adapter\" everwhere`@worker-tools/kv-storage` is used.\n\nWhile work on the [`StorageArea` specification](https://wicg.github.io/kv-storage/) has stopped, KV Storage is still a good interface for asynchronous data access that feels native to JavaScript.\n\nIt create commits on every event - eg. when calling `set`, `delete`, `clear` and `remove`.\nIt **DOES NOT** do that for the other methods like `get`, `keys`, `values`.\n\n## Install\n\n```\nyarn add github-kv-storage\n```\n\nImplements the following, including the `localStorage`/`sessionStorage`-like methods - `getItem`, `setItem`, `removeItem`, `deleteItem`. They are just aliases of the StorageArea methods.\n\n```ts\nexport type AllowedKey = string | number | Date | BufferSource | AllowedKey[];\nexport type Key = string | number | Date | ArrayBuffer | Key[];\n\nexport type Options = Record\u003cstring, any\u003e;\n\ndeclare const StorageArea: {\n  prototype: StorageArea;\n  new (name: string, opts?: Options): StorageArea;\n};\n\n/**\n * Main differences to the working draft:\n * - Unknown backing store.\n * - Added unspecified options paramter to all methods.\n *   This way users can provide extra data to the underlying implementation without type casting.\n */\nexport interface StorageArea {\n  set\u003cT\u003e(key: AllowedKey, value: T, opts?: Options): Promise\u003cvoid\u003e;\n  get\u003cT\u003e(key: AllowedKey, opts?: Options): Promise\u003cT | undefined\u003e;\n  delete(key: AllowedKey, opts?: Options): Promise\u003cvoid\u003e;\n  clear(opts?: Options): Promise\u003cvoid\u003e;\n\n  keys(opts?: Options): AsyncIterableIterator\u003cKey\u003e;\n  values\u003cT\u003e(opts?: Options): AsyncIterableIterator\u003cT\u003e;\n  entries\u003cT\u003e(opts?: Options): AsyncIterableIterator\u003c[Key, T]\u003e;\n\n  backingStore(): unknown;\n}\n```\n\n## Usage\n\nThe constructor accepts `(name, options)`\n\n### name\n\nThe `name` is optional and can be replaced with `options`. We can get the name of the\ndatabase in few ways:\n\n- the `name` param\n- through `options.name`\n- as last part of the url\n- if not found anywhere, it defaults to `db` which means a file named `db.json` should exist\n  in the repository, or pass `options.autoCreate: true`, or call `await storage._create()` to initialize it.\n\nFor example, in the `github://tunnckoCore/foobar/mydb.json` the `mydb` is the name. You can skip the `.json` extension too.\n\n### options\n\n- `token` **{string}** - the required Github Access token\n- `url` **{string}** - url like `github://tunnckoCore/kv-github-storage/package.json`\n- `repo` **{string}** - Github repository\n- `owner` **{string}** - Github username; not needed `url` passed\n- `pretty` **{boolean}** - disabled by default; the written to be indented with 2 spaces\n- `autoCreate` **{boolean}** - default `false`; to create an initial empty database\n\n### Example\n\n```js\nimport GithubStorage from \"github-kv-storage\";\n\nconst store = new GithubStorage({\n  token: \"\u003cyour github access token\u003e\",\n  url: \"github://\u003cusername\u003e/\u003crepo\u003e/\u003cdbname\u003e\",\n  pretty: true,\n  autoCreate: true,\n});\n\nawait store.set(\"foo\", \"bar\");\n\n// all places where `key` is accepted support dot notation\nawait store.set(\"bar.qux\", { zazzy: 123, barry: 456 });\n\n// setting value to `undefined`\n// works like the `store.remove('bar.qux.barry')`\nawait store.set(\"bar.qux.barry\", undefined);\n\n// no arguments, returns the whole store\nawait store.get();\n\n// all methods support dot notation\nawait store.get(\"bar.qux\");\n\nawait store.set(\"bar.zaz\", 123);\n\n// similar to set(key, undefined)\nawait store.delete(\"bar.zazzy\");\n\nawait store.delete(\"foo\");\nawait store.delete(\"bar\");\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftunnckocore%2Fgithub-kv-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftunnckocore%2Fgithub-kv-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftunnckocore%2Fgithub-kv-storage/lists"}