2018-04-02 04:35:22 +00:00
# Record.js
2018-04-07 04:56:08 +00:00
> A minimalistic object collection library
2018-04-02 04:35:22 +00:00
2018-05-06 23:09:47 +00:00
**Record.js** aims to provide a lite, *2kb* , *zero-dependency* collection utility to help build simple in-memory or local storage database of records. Records are stored as plain arrays.
2018-04-07 04:56:08 +00:00
2018-05-06 23:09:47 +00:00
Records can be exported to JSON, with no internal metadata[*], so you can import your data anywhere; via `.dump()`
2018-04-23 06:43:12 +00:00
### Features
- Tiny, only 2kb
- Zero-Dependencies
- Saves to LocalStorage (if available)
2018-06-06 12:12:03 +00:00
- Data saved, and exported as simple JSON
2018-04-23 06:43:12 +00:00
- Browser or Nodejs compatible
2018-04-02 04:35:22 +00:00
2018-06-06 12:12:03 +00:00
### Why
Sometimes having a simple single-user data storage library that stays out of your way while you prototype out your ideas is all you need. With a small footprint, removing/replacing a library like `record.js` is a breeze. Ideally, using this to library to build out configuration files, mock out test data, or even develop simple applications is where this shines. I use it for just that! I often replace this library once an idea becomes soluble; I export the data to JSON to a real DB and expand.
2018-04-07 04:56:08 +00:00
## Getting Started
- [Download Library ](https://raw.githubusercontent.com/n2geoff/record.js/master/dist/record.min.js ), then...
create a new record collection (in-memory)
const pets = new Record();
add something to the collection
pets.add({"name": "Fluffy", "type": "cat"});
// [{"id": "123fk91j7", "name": "Fluffy", "type": "cat"}]
2018-04-15 21:59:09 +00:00
an `id` field is auto-generated if not provided, this allows easy record retrieval via
2018-04-07 04:56:08 +00:00
pets.find("123fk91j7");
// [{"id": "123fk91j7", "name": "Fluffy", "type": "cat"}]
2018-04-02 04:35:22 +00:00
2018-04-07 04:56:08 +00:00
you can also find items via properties like
pets.find({"type": "cat"});
// [{"id": "123fk91j7", "name": "Fluffy", "type": "cat"}]
and you can remove items via
pets.remove("123fk91j7");
// [{"id": "123fk91j7", "name": "Fluffy", "type": "cat"}]
so, no records, right?
pets.find();
// []
### API
The public API is very simple, you really only need 3 methods: `add` , `remove` , and `find` .
2018-04-07 04:11:28 +00:00
| Method | Description |
2018-04-07 04:56:08 +00:00
|---|---|
2018-05-06 22:54:29 +00:00
| `.add(object)` | Adds entry to collection and returns entry(s) added |
| `.remove(id or object)` | Removes entry(s) from collection and returns removed |
| `.find(id or object)` | find all, find by id, or find by filter, returns array of entries |
| `.dump()` | saves records to JSON file |
2018-04-15 21:59:09 +00:00
#### Length (Count Records)
2018-04-23 06:43:12 +00:00
As `Records` are just plain JavaScript Arrays, you can use `.length` to determine the number of results returned, for example:
2018-04-15 21:59:09 +00:00
```js
let cats = pets.find({"type": "cat"}); // []
cats.length; // 0
```
2018-04-07 04:11:28 +00:00
2018-04-07 04:56:08 +00:00
> NOTICE: `find` is special, changes based on what you pass in, an id, an object, or nothing at all
2018-04-15 21:59:09 +00:00
- Additional [API Documentation ](docs/api.md )
2018-04-07 04:11:28 +00:00
### Options
2018-04-07 04:56:08 +00:00
Records.js constructor supports a few options passed in as an `object`
2018-04-23 06:43:12 +00:00
- **store**: localStorage KEY to use. This actives localStorage if available
- **stores**: TBD
- **debug**: may logout useful information, maybe not;)
- **fields**: TBD
2018-04-02 04:35:22 +00:00
## Tests
npm test
2018-04-02 11:21:19 +00:00
## Support
Please open [an issue ](https://github.com/n2geoff/record.js/issues/new ) for support.
## Contributing
Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the [guidelines ](CONTRIBUTING.md ), there minimalistic;)
## License
[MIT ](LICENSE )
2018-05-06 23:09:47 +00:00
---
2018-06-06 12:12:03 +00:00
> [*]: with exception of a generated ID, if not provided