# json-fs-store

> File system storage and retrieval of objects as JSON

Latest version **1.0.1** (published 2016-09-21) · 0 weekly downloads

## Install

```sh
npm install json-fs-store
pnpm add json-fs-store
yarn add json-fs-store
bun add json-fs-store
```

## 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.1 |
| Published | 2016-09-21 |
| First published | 2015-10-15 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.4.12 |
| Dependencies | 4 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 59 |
| Maintainers | alexkwolfe |

## Links

- npm: https://www.npmjs.com/package/json-fs-store
- Repository: https://github.com/alexkwolfe/json-fs-store
- Issues: https://github.com/alexkwolfe/json-fs-store/issues
- npm.io page: https://npm.io/package/json-fs-store

## Dependencies (4)

- [async](https://npm.io/package/async.md) ^1.4.2
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [node-uuid](https://npm.io/package/node-uuid.md) ^1.4.4
- [graceful-fs](https://npm.io/package/graceful-fs.md) ^4.1.2

## Recent versions

- 1.0.1 (latest) — 2016-09-21
- 1.0.0 — 2015-11-27
- 0.1.0 — 2015-10-16
- 0.0.5 — 2015-10-15
- 0.0.4 — 2015-10-15
- 0.0.3 — 2015-10-15
- 0.0.2 — 2015-10-15
- 0.0.1 — 2015-10-15

## README

This Node.js npm module simply serializes JavaScript objects to JSON files into the file system directory of your choosing.

[![Build Status](https://travis-ci.org/alexkwolfe/json-fs-store.svg?branch=master)](https://travis-ci.org/alexkwolfe/json-fs-store)
[![Dependencies](https://david-dm.org/alexkwolfe/json-fs-store.svg?branch=master)](https://david-dm.org/alexkwolfe/json-fs-store)

### Installing

```
npm install json-fs-store
```

### Creating a store

The store module is a function that takes a single parameter: the path to the location on the file system where you want to store your objects. If you omit the storage location the 'store' directory in your current working directory will be used.

```javascript
var store = require('json-fs-store')('/path/to/storage/location');
```

### Adding an object

A stored object must have an `id` attribute (one will be provided if it does not). The object
will be serialized to JSON using `JSON.stringify` and written to the storage location. 

To customize the JSON, you can define the `#toJSON` function on the object to be stored. That function
must return a JavaScript object.

```javascript
var donkey = {
  id: '12345',
  name: 'samuel',
  color: 'brown'
};

store.add(donkey, function(err) {
  // called when the file has been written
  // to the /path/to/storage/location/12345.json
  if (err) throw err; // err if the save failed
});
```

### Retrieving an object

To retrieve an object, you must know its `id` attribute and use it as a parameter for the `load()` function.

```javascript
store.load('12345', function(err, object){
  if(err) throw err; // err if JSON parsing failed

  // do something with object here

});
```

### Listing stored objects

Every call to the `list()` function reads the file system and returns the objects stored in the directory you specified when you created your store.
Objects will be sorted according to their `name` attribute, if defined.

```javascript
store.list(function(err, objects) {
  // err if there was trouble reading the file system
  if (err) throw err;
  // objects is an array of JS objects sorted by name, one per JSON file
  console.log(objects);
});
```

### Removing stored objects

A stored object may be removed simply by passing the object's `id` attribute to the `remove()` function.
The attribute will be used to remove the object's file from the file system.

```javascript
store.remove('12345', function(err) {
  // called after the file has been removed
  if (err) throw err; // err if the file removal failed
});
```

# FIN.

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