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-04-23 06:43:12 +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 simple arrays.
2018-04-07 04:56:08 +00:00
2018-04-23 06:43:12 +00:00
Records can be exported to JSON, with no internals so you can import your data anywhere; via `.dump()`
### Features
- Tiny, only 2kb
- Zero-Dependencies
- Saves to LocalStorage (if available)
- Saves to simple JSON
- Browser or Nodejs compatible
2018-04-02 04:35:22 +00:00
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
|---|---|
| `.add(object)` | Adds entry to collection and returns entry(s) added |
| `.remove(id|object)` | Removes entry(s) from collection and returns removed |
2018-04-07 04:11:28 +00:00
| `.find(id|object)` | find all, find by id, or find by filter, returns array of entries |
2018-04-15 21:59:09 +00:00
| `.dump()` | saves records to JSON file |
#### 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 )