{"id":13826476,"url":"https://github.com/usmakestwo/githubDB","last_synced_at":"2025-07-09T00:33:41.611Z","repository":{"id":21479323,"uuid":"92852430","full_name":"usmakestwo/githubDB","owner":"usmakestwo","description":"A Lightweight Cloud based JSON Database with a MongoDB like API for Node.","archived":false,"fork":false,"pushed_at":"2022-12-07T17:38:27.000Z","size":560,"stargazers_count":217,"open_issues_count":14,"forks_count":28,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-05T14:15:30.463Z","etag":null,"topics":["cloud","database","github-api","json"],"latest_commit_sha":null,"homepage":"","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/usmakestwo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-30T16:17:09.000Z","updated_at":"2024-09-16T15:04:26.000Z","dependencies_parsed_at":"2023-01-11T21:14:04.481Z","dependency_job_id":null,"html_url":"https://github.com/usmakestwo/githubDB","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmakestwo%2FgithubDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmakestwo%2FgithubDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmakestwo%2FgithubDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmakestwo%2FgithubDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usmakestwo","download_url":"https://codeload.github.com/usmakestwo/githubDB/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224983015,"owners_count":17402405,"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":["cloud","database","github-api","json"],"created_at":"2024-08-04T09:01:38.526Z","updated_at":"2024-11-20T05:30:47.680Z","avatar_url":"https://github.com/usmakestwo.png","language":"JavaScript","readme":"# githubDB\n[![Build Status](https://travis-ci.org/usmakestwo/githubDB.svg?branch=master)](https://travis-ci.org/usmakestwo/githubDB)\n\nA Lightweight Cloud based JSON Database with a MongoDB like API for Node.\n\n_You will never know that you are interacting with a Github_\n\n## Contents\n\n* [Introduction](#introduction)\n  * [Prerequisites](#prerequisites)\n  * [Getting Started](#getting-started)\n* [Documentation](#documentation)\n  * [Connect](#connect-to-db)\n  * [Load Collections](#load-collections)\n  * [Write/Save](#writesave-to-collection)\n  * [Read](#read-from-collection)\n  * [Update](#update-collection)\n  * [Remove](#remove-collection)\n  * [Count](#count)\n* [Examples](#examples)\n* [Performance](#performance)\n* [Contributing](#contributing)\n* [Release History](#release-history)\n\n## Introduction\n\nEver wanted to use Github as your private database, now you can.\n\nWhy would I want to use Github as my database?\n\nGood question. Developers have many choices of different databases, GithubDB however leverages\nall the features you have come to love from Github.\n\n- Logging (With Github, you can quicky look at your commits and see the write and updates for your request).\n- Visualization (Github offers amazing tools to visualize the incoming number of read/writes).\n- Persistance (With Github you can rollback to early stages of your data and see how it has evolved).\n- Security (Using Github, your database inherits the same standards from Github).\n- Availability (Github has known to be down, but let's be honest, it is good enough unless you are Facebook).\n\n### Prerequisites\n\nIn order to sucessfully use Github, you are going to need two things.\n\n1) Personal Access Token\n\nCreate a new [personal access token](https://github.com/settings/tokens/new) from Github. The only permission you need\nare **repo**.\n\nWrite it down and store it somewhere same.\n\n2) An repository that you have access to with an file that has the extension .json.\n\nInside that file (let's say you called it database.json), you are going to create an empty array.\n\n\n### Getting Starteed\n\nInstall the module locally :\n```bash\n$ npm install github-db\n```\n\n```js\n/**\n* We are going to authenticate with Github and\n* specify our repo name and file we just created.\n*/\nvar options = {\n  host: 'private-github-api.com', // \u003c-- Private github api url. If not passed, defaults to 'api.github.com'\n  pathPrefix: 'prefix-for-enterprise-instance', // \u003c-- Private github api url prefix. If not passed, defaults to null.\n  protocol: 'https', // \u003c-- http protocol 'https' or 'http'. If not passed, defaults to 'https'\n  owner: 'github-username', // \u003c-- Your Github username\n  repo: 'github-repo', // \u003c-- Your repository to be used a db\n  path: 'filename-with-extension-json' // \u003c- File with extension .json\n};\n\n// Require GithubDB\nvar GithubDB = require('..').default;\n// Initialize it with the options from above.\nvar githubDB = new GithubDB(options);\n\n// Authenticate Github DB -\u003e grab a token from here https://github.com/settings/tokens\ngithubDB.auth(personalAccessToken);\n\n// Connect to repository\ngithubDB.connectToRepo();\n\n// You are now authenticated with Github and you are ready to use it as your database.\ngithubDB.save({\"message\": \"wooohoo\"});\n```\n\n## Documentation\n\n### Authenticating with Github\n\n```js\ngithubDB.auth(personalAccessToken)\n```\nIn order to use Github DB, you will require a personal access token. You can request one\nfrom (Github)[https://github.com/settings/tokens]. It is recommended that you set your token\nas an enviroment variable. Never commit your token!\n\n```js\nvar personalAccessToken = process.env.TOKEN; // Set the variable here\n```\n\nStart the server with the token\n```bash\n$ TOKEN=xxxx node app.js\n```\n\nOnce you are authenticated to you connect to your new Github Database.\n```js\ngithubDB.connectToRepo();\n```\n\n**Note** : Please make sure the file on Github you are using as your database contains a valid JSON array, otherwise githubDB\nwill return an empty array.\n\n```js\n[]\n```\nElse it will throw an error like\n\n```bash\nundefined:0\n\n^\nSyntaxError: Unexpected end of input\n```\n---\n\n### Write/Save to Collection\n\nWith githubDb you can easily save an object. Since you are making a call to a network.\nThis method is asynchronous. \n\n```js\ngithubDB.save(users).then((res) =\u003e {\n    // The result from the same\n    console.log(res);\n});\n```\n\nYou can also save multiple objects at once like\n\n```js\n\nvar article1 = {\n    title : 'githubDB rocks',\n    published : 'today',\n    rating : '5 stars'\n}\n\nvar article2 = {\n    title : 'githubDB rocks',\n    published : 'yesterday',\n    rating : '5 stars'\n}\n\nvar article3 = {\n    title : 'githubDB rocks',\n    published : 'today',\n    rating : '4 stars'\n}\n\ngithubDB.save([article1, article2, article3]).then((res) =\u003e {\n    // The result from the same\n    console.log(res);\n});\n```\nAnd this will return the inserted objects\n\n```js\n[ { title: 'githubDB rocks',\n    published: 'today',\n    rating: '4 stars',\n    _id: 'b1cdbb3525b84e8c822fc78896d0ca7b' },\n  { title: 'githubDB rocks',\n    published: 'yesterday',\n    rating: '5 stars',\n    _id: '42997c62e1714e9f9d88bf3b87901f3b' },\n  { title: 'githubDB rocks',\n    published: 'today',\n    rating: '5 stars',\n    _id: '4ca1c1597ddc4020bc41b4418e7a568e' } ]\n```\n---\n\n### Read from Collection\nThere are 3 methods available for reading the JSON collection\n* db.collectionName.find(query)\n* db.collectionName.findExact(query)\n* db.collectionName.findOne(query)\n\n#### githubDB.find()\n```js\ngithubDB.find().then((results) =\u003e {\n    // Results here\n    console.log(results);\n});\n```\nThis will return all the records\n```js\n[{\n    title: 'githubDB rocks',\n    published: 'today',\n    rating: '5 stars',\n    _id: '0f6047c6c69149f0be0c8f5943be91be'\n}]\n```\nYou can also query with a criteria like\n```js\ngithubDB.find({rating : \"5 stars\"}).then((results)=\u003e {\n    console.log(results);\n});\n```\nThis will return all the articles which have a rating of 5.\n\nFind can take multiple criteria\n```js\ngithubDB.find({rating : \"5 stars\", published: \"yesterday\"}).then((results) =\u003e {\n    console.log(results);  \n});\n```\nThis will return all the articles with a rating of 5, published yesterday.\n\n#### githubDB.findExact(query)\nThis method returns exact match of records from the collection. \n```js\ngithubDB.findExact({\n        title: 'githubDB rocks', \n        rating: '4 stars'\n    }).then((results)=\u003e {\n    console.log(results);\n});\n```\nThis will return all the records\n```js\n[{\n    title: 'githubDB rocks',\n    published: 'today',\n    rating: '4 stars',\n    _id: 'b1cdbb3525b84e8c822fc78896d0ca7b' \n}]\n```\n#### githubDB.findOne(query)\n```js\ngithubDB.findOne().then((results)=\u003e {\n    console.log(results);\n});\n```\n\nIf you do not pass a query, githubDB will return the first article in the collection. If you pass a query, it will return first article in the filtered data.\n\n```js\ngithubDB.findOne({_id: '0f6047c6c69149f0be0c8f5943be91be'}).then((results)=\u003e {\n    console.log(results);\n});\n```\n---\n### Update Collection\n```js\ngithubDB.update(query, data, options).then((updated)=\u003e {\n    console.log(updated);  // { updated: 1, inserted: 0 }\n});;\n```\n\nYou can also update one or many objects in the collection\n```js\noptions = {\n    multi: false, // update multiple - default false\n    upsert: false // if object is not found, add it (update-insert) - default false\n}\n```\nUsage\n```js\nvar query = {\n  title : 'githubDB rocks'\n};\n\nvar dataToBeUpdate = {\n  title : 'githubDB rocks again!',\n};\n\nvar options = {\n   multi: false,\n   upsert: false\n};\n\nvar updated = githubDB.update(query, dataToBeUpdate, options).then((results) =\u003e {\n  console.log(updated); // { updated: 1, inserted: 0 }  \n});\n```\n---\n### Remove Collection\n```js\ngithubDB.removeAll();\ngithubDB.remove(query, multi);\n```\nYou can remove the entire collection (including the file) or you can remove the matched objects by passing in a query. When you pass a query, you can either delete all the matched objects or only the first one by passing `multi` as `false`. The default value of `multi` is `true`.\n\n```js\ngithubDB.remove({rating : \"5 stars\"});\n```\n```js\ngithubDB.remove({rating : \"5 stars\"}, true); // remove all matched. Default - multi = true\n```\n\n```js\ngithubDB.remove({rating : \"5 stars\"}, false); // remove only the first match\n```\n\nTo delete the file simple use removeAll();\n```js\ngithubDB.removeAll();\n```\n## Performance\n\nThe module makes synchronous request to Github. The performance is then inhereted from the network connection speed.\n\n\n## Contributing\nSee the [CONTRIBUTING Guidelines](https://github.com/usmakestwo/githubDB/blob/master/CONTRIBUTING.md)\n\n## Release History\n\n- 1.1.3\n  - Add findExact method which returns exact match of objects from the collection\n\n- 1.1.2\n  - Allow to pass a path prefix when connecting to Enterprise Github\n\n- 1.1.1\n  - Compiled dist to update with previous version\n\n- 1.1.0\n  - Parameterized github API host url\n  - Added eslint\n  - Fixed test cases\n\n- 1.0.0\n  - Working version\n\n## License\nCopyright (c) 2017 UsMakesTwo. Licensed under the MIT license.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusmakestwo%2FgithubDB","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusmakestwo%2FgithubDB","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusmakestwo%2FgithubDB/lists"}