# grud

> Simple JSON data store in GitHub for Node, Electron and the browser.

Latest version **1.0.12** (published 2021-10-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install grud
pnpm add grud
yarn add grud
bun add grud
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.12 |
| Published | 2021-10-28 |
| First published | 2021-02-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 37.8 KB |
| Known vulnerabilities | 0 (+24 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Anees Ahammed |
| Maintainers | aneesahammed |
| Keywords | JSON, Database, CRUD, GitHub, flat, file, storage |

## Links

- npm: https://www.npmjs.com/package/grud
- Repository: https://github.com/aneesahammed/grud
- Homepage: https://github.com/aneesahammed/grud#readme
- Issues: https://github.com/aneesahammed/grud/issues
- npm.io page: https://npm.io/package/grud

## Dependencies (7)

- [uuid](https://npm.io/package/uuid.md) ^8.3.2
- [axios](https://npm.io/package/axios.md) ^0.21.1
- [chalk](https://npm.io/package/chalk.md) ^4.1.0
- [lodash.find](https://npm.io/package/lodash.find.md) ^4.6.0
- [lodash.without](https://npm.io/package/lodash.without.md) ^4.4.0
- [lodash.findindex](https://npm.io/package/lodash.findindex.md) ^4.6.0
- [regenerator-runtime](https://npm.io/package/regenerator-runtime.md) ^0.13.7

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.0.12 (latest) — 2021-10-28
- 1.0.11 — 2021-04-17
- 1.0.10 — 2021-04-17
- 1.0.9 — 2021-04-17
- 1.0.8 — 2021-04-17
- 1.0.6 — 2021-04-17
- 1.0.5 — 2021-03-03
- 1.0.4 — 2021-03-01
- 1.0.3 — 2021-03-01
- 1.0.2 — 2021-03-01
- 1.0.1 — 2021-02-27
- 1.0.0 — 2021-02-27

## README

<h1 align="center">Welcome to grud 👋</h1>
<p>
  <img alt="Version" src="https://img.shields.io/badge/version-1.0.7-blue.svg?cacheSeconds=2592000" />
  <a href="https://github.com/aneesahammed/grud#readme" target="_blank">
    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
  </a>
  <a href="https://github.com/aneesahammed/grud/graphs/commit-activity" target="_blank">
    <img alt="Maintenance" src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" />
  </a>
  <a href="https://github.com/aneesahammed/grud/blob/master/LICENSE" target="_blank">
    <img alt="License: MIT" src="https://img.shields.io/github/license/aneesahammed/grud" />
  </a>
  <a href="https://twitter.com/aneesahammed" target="_blank">
    <img alt="Twitter: aneesahammed" src="https://img.shields.io/twitter/follow/aneesahammed.svg?style=social" />
  </a>
  <a href="https://www.npmjs.com/package/grud">
    <img src="https://img.shields.io/npm/dt/grud.svg" alt="downloads" />
  </a>
</p>

> Simple JSON data store in GitHub with CRUD interface for React, Node, Electron and the browser.<br/>
> **grud** is a convenient method of storing & performing read, update & delete operations on data without setting up a database server.

### 🏠 [Homepage](https://github.com/aneesahammed/grud#readme)

## Install

```sh
npm install grud
```

## Initialize

To get started with **grud**, initialize the `db` object by passing the required config.

```js
const Grud = require("grud");

let config = {
  protocol: "https",           //If not passed, defaults to 'https'
  host: "api.github.com",      //If not passed, defaults to 'api.github.com' | In case of Enterprise-GitHub e.g github.snapcircle.net.
  pathPrefix: "",              //Leave empty if you are using github.com | In case of Enterprise-GitHub e.g api/v3
  owner: "username",           //Your GitHub username
  repo: "my-repo",             //Your repository name where you'd like to have your JSON store hosted
  path: "db.json",             //Your data store file with .json extension
  personalAccessToken: "xxxx", //Your personal-access-token with write access
};
let db = new Grud(config);
```

Create your GitHub personal token from [here](https://github.com/settings/tokens).<br/>
And please note that **grud** will create a new JSON data store file as mentioned in the `config` (db.json in our case) if the file is not found.<br/>
If the file exists, data shall get appended to the collection array.

# Create

## Create a single record

The following query creates a single `post` record in your JSON dataStore (`db.json`).

```js
const data = {
  author: "Anand",
  title: "sunt aut facere repellat provident ",
  body: "quia et suscipit\nsuscipit recusandae consequuntur ",
};
const posts = await db.save(data);
```

## Create multiple records

The following query creates multiple `post` records in your defined JSON datastore.

```js
const data = [
  {
    author: "Sarath",
    title: "sunt aut facere repellat provident ",
    body: "quia et suscipit\nsuscipit recusandae consequuntur ",
  },
  {
    author: "Anand",
    title: "qui est esse",
    body: "est rerum tempore vitae\nsequi sint nihil",
  },
];
const posts = await db.save(data);
```

# Read

## Get record by Id or unique identifier

The following query returns a single `post` record by unique identifier or Id.

```js
const post = await db.find({ _id: "301b63faac384a31b3e785ebf40295e5" });
```

or

```js
const post = await db.find({ author: "Anand" });
```

## Get all records

The following query returns all `posts` records.

```js
const posts = await db.find();
```

## Update

Update record by Id or unique identifier. <br/>
The following query finds the `post` record and updates it.

```js
const posts = await db.update(
  { _id: "301b63faac384a31b3e785ebf40295e5" },
  data
);
```

or

```
const posts = await db.update({ author: "Anand" }, data);
```

# Delete

## Delete a single record

The following query deletes a single `post` record.

```js
await db.deleteOne({ _id: "301b63faac384a31b3e785ebf40295e5" });
```

or

```js
await db.deleteOne({ author: "Anand" });
```

## Delete all records

TBA

## Run tests

```sh
npm run test
```

## 🤝 Contributing

Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/aneesahammed/grud/issues). You can also take a look at the [contributing guide](https://github.com/aneesahammed/grud/blob/master/CONTRIBUTING.md).

## Show your support

Give a ⭐️ if this project helped you!

## Limits

**grud** came out from the frequent need of having a database for internal tooling purpose.<br/>
If your priority is to have secure/high-performance storage, you should stick to traditional databases like MongoDB.

## Author

👤 **Anees Ahammed**

- Twitter: [@aneesahammed](https://twitter.com/aneesahammed)

## 📝 License

Copyright © 2021 [Anees Ahammed](https://github.com/aneesahammed).<br />
This project is [MIT](https://github.com/aneesahammed/grud/blob/master/LICENSE) licensed.

---
_Source: https://npm.io/package/grud · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._