React-local-mongoose NPM

React Local Mongoose

A mongoose-esque wrapper for localStorage

NB: This package is not affiliated with Mongoose in any way. It is simply an attempt to match their API.

This package has been heavily influenced by LocalDB by kucukkanat.

Installation

Install with npm or yarn:

npm i --save react-local-mongoose

yarn add react-local-mongoose

Defining a model

import LocalDb from 'react-local-mongoose';

const schema = {
  pathName: { type[, required[, unique[, ref ]  ] ] }
};

const model = new LocalDb(schema, collectionName);

Arguments

schema Object: Contains path names with settings. Required
- pathName (Object|Array): settings for each path. Can only be an array of references at this time.
  - type Constructor: data type for path (eg ObjectID, String, Number, Boolean etc). Required
  - required (Boolean|String): indicates whether field is required. If string is provided, it will be used as an error message.
  - unique (Boolean|String): indicates whether field should be unique. If string is provided, it will be used as an error message.
  - ref String: indicates the name of the referenced model.
collectionName: String used to set collection in localStorage (eg: 'User', 'Post', 'Cheese' etc). Required

Return value

A new instance of LocalDb which behaves like a mongoose model

Example

import LocalDB, { ObjectID } from 'react-local-mongoose';

const cheeseSchema = {
  name: { type: String, required: 'This field is required', unique: 'That name is already taken' },
  origin: { type: ObjectID, ref: 'Country', required: true }, // reference to Country model
  strength: { type: Number, required: true },
  tastingNotes: { type: String },
  image: { type: String }
};

const Cheese = new LocalDB(cheeseSchema, 'Cheese');

export default Cheese;

Querying Methods

NB: In all examples Cheese is a model created using the example above

`find`

Cheese.find(query)

Arguments

query Object: An object defining search params. Uses sift for mongodb-esque queries

Return value

A promise which resolves all documents that match the query.

`findOne`

Cheese.findOne(query)

Arguments

query Object: An object defining search params. Uses sift for mongodb-esque queries

Return value

A promise which resolves with the first document that matches the query.

`findById`

Cheese.findById(id)

Arguments

id String: The id of the document to find.

Return value

A promise which resolves with the found document or null. If the document contains references, they will be populated.

Examples

Cheese.find({ strength: 4 })
  .then(records => console.log(records)); // returns an array of all records that have a strength of 4

Cheese.findOne({ name: 'Gorgonzola' })
  .then(record => console.log(record)); // returns the first record with the name of 'Gorgonzola'

Cheese.findById('5a36be1b15301600007f38f7')
  .then(record => console.log(record)); // returns the record with the id of '5a36be1b15301600007f38f7'

`create`

Cheese.create(data)

Arguments

data (Object|Array): An object containing the data to be stored, or an array containing objects to be stored. Data will be validated before saving to localStorage.

Return value

A promise which resolves with the stored documents, and rejects with an error containing validation error messages.

Example

Cheese.create({ name: 'Gorgonzola', strength: 4 })
  .catch(err => console.log(err.errors)); // { name: 'That name is already taken', origin: 'Path `origin` is required' }

Country.find({ $or: [{ name: 'Italy' }, { name: 'Netherlands'} ] })
  .then(countries => {
    return Cheese.create([
      { name: 'Gorgonzola', origin: countries[0], strength: 4 },
      { name: 'Edam', origin: countries[1], strength: 2 }
    ])
  })

  .then(records => console.log(records));
/*
  [
    { _id: '5a36be1b15301600007f38f7', 'name: 'Gorgonzola', origin: '5a37d33656e4ce00008a9b31', strength: 4 },
    { _id: '5a36be1b15301600007f38f8', name: 'Edam', origin: '5a37d33656e4ce00008a9b26', strength: 2 }
  ]
*/

`update`

Cheese.update(query, data)

Arguments

query Object: An object defining search params. Uses sift for mongodb-esque queries
data (Object|Array): An object containing the data to be updated.

Return value

A promise which resolves with the updated documents, and rejects with an error containing validation error messages.

Example

Cheese.update({ name: 'Gorgonzola' }, { strength: 2 })
  .then(records => console.log(records))); // [{ name: 'Gorgonzola', origin: '5a37d33656e4ce00008a9b31', strength: 2 }]

`findByIdAndUpdate`

Cheese.findByIdAndUpdate(id, data)

Arguments

id String: The id of the document to find.
data (Object|Array): An object containing the data to be updated.

Return value

A promise which resolves with the updated document, and rejects with an error containing validation error messages.

Example

Cheese.findByIdAndUpdate('5a36be1b15301600007f38f7', { strength: 2 })
  .then(records => console.log(records))); // { name: 'Gorgonzola', origin: '5a37d33656e4ce00008a9b31', strength: 2 }

`remove`

Cheese.remove(query)

Arguments

query Object: An object defining search params. Uses sift for mongodb-esque queries

Return value

A promise which resolves with null.

Example

Cheese.remove({ name: 'Gorgonzola' })
  .then(() => console.log('Record removed'));

`findByIdAndRemove`

Cheese.findByIdAndRemove(id)

Arguments

id String: The id of the document to remove.

Return value

A promise which resolves with null.

Example

Cheese.findByIdAndRemove('5a36be1b15301600007f38f7')
  .then(() => console.log('Record removed'));

`drop`

Cheese.drop()

Return value

drop always returns true.

Example

Cheese.drop(); // true

Limitations

Storage capacity

The amount of data that can be stored is depended on device and browser. For more info check out these resources:

Embedded / Referenced Data

Mongoose and Mongo allow for embedded schemas and references to other collections, with population functionality. This is not and will never be a full implementation of mongodb or mongoose on the client-side. Complex data structures are better persisted to an actual database.

I have added the ability to set references to models, however their use is limited. References can be set by passing an id or array of ids, or a record or an array of records. (see the examples above).

All find methods will populate records accordingly.

Embedded records are not supported at this time. It requires recursively validating the data, and populating. Again I may add it in the future.

Document methods, virtuals and other advanced Mongoose features

Again, if you need mongoose's advanced feature set, best use mongoose in conjunction with an API, and make requests via AJAX.

Contributing

Contributions are very welcome.

Fork the repository
yarn install or npm i to install the dependencies
yarn link or npm link to make your local fork available to other local projects
yarn link react-local-mongoose or npm link react-local-mongoose in a local React project to test your updates
When you're happy make a PR!