Record.js

A minimalistic object collection library

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.

Records can be exported to JSON, with no internal metadata[*], so you can import your data anywhere; via .dump()

Features

• Tiny, only >2kb
• Zero-Dependencies
• Saves to LocalStorage (if available)
• Data saved, and exported as simple JSON
• Browser ESM or Nodejs (use require('record.cjs.js').default)

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.

Getting Started

• Download Library, 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"}]

an id field is auto-generated if not provided, this allows easy record retrieval via

pets.find("123fk91j7");
// [{"id": "123fk91j7", "name": "Fluffy", "type": "cat"}]

you can also find items via properties like

pets.find({"type": "cat"});
// [{"id": "123fk91j7", "name": "Fluffy", "type": "cat"}]

and when it comes time to update you can do that to

var fluffy = pets.find({"name": "Fluffy"})[0]; // one record
fluffy.age = 25;

pets.update(fluffy);

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 4 methods: add, update, remove, and find.

Method	Description
.add(object)	Adds entry to collection and returns entry(s) added
.update(object)	Updates a record
.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

Length (Count Records)

As Records are just plain JavaScript Arrays, you can use .length to determine the number of results returned, for example:

let cats = pets.find({"type": "cat"}); // []
cats.length;  // 0

NOTICE: find is special, changes based on what you pass in, an id, an object, or nothing at all

• Additional API Documentation

Options

Records.js constructor supports a few options passed in as an object

• store: localStorage KEY to use. This actives localStorage if available
• stores: TBD
• debug: may logout useful information, maybe not;)
• fields: TBD

Tests

npm test

Build

npm install esbuild -g

npm run build

Support

Please open an issue for support.

Contributing

Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the guidelines, there minimalistic;)

License

MIT

---

[*]: with exception of a generated ID, if not provided

TODO

• make reactive, so just doing fluffy.age = 25 updates