A class-based ES6 ODM for Mongo-like databases. Forked from camo.
npm install follicleFollicle is a fork of camo made for the needs of Seald
Throughout development this eventually turned in to a library full of ES6 features. Coming from a Java background, its easier for me to design and write code in terms of classes, and I suspect this is true for many JavaScript beginners. While ES6 classes don't bring any new functionality to the language, they certainly do make it much easier to jump in to OOP with JavaScript, which is reason enough to warrent a new library, IMO.
Camo is awesome but has too many incompatible patterns for internal use such as having only one database client connected which can be difficult in tests where you need multiple databases connected at the same time, a PR wouldn't make sense.
- ES6: ES6 features are quickly being added to Node, especially now that it has merged with io.js. With all of these new features being released, Follicle is getting a head start in writing tested and proven ES6 code. This also means that native Promises are built-in to Follicle, so no more promisify-ing your ODM or waiting for Promise support to be added natively.
- Easy to use: While JavaScript is a great language overall, it isn't always the easiest for beginners to pick up. Follicle aims to ease that transition by providing familiar-looking classes and a simple interface. Also, there is no need to install a full MongoDB instance to get started thanks to the support of NeDB.
- Multiple backends: Follicle was designed and built with multiple Mongo-like backends in mind, like NeDB, LokiJS\, and TaffyDB\. With NeDB support, for example, you don't need to install a full MongoDB instance for development or for smaller projects. This also allows you to use Follicle in the browser, since databases like NeDB supports in-memory storage.
- Lightweight: Follicle is just a very thin wrapper around the backend databases, which mean you won't be sacrificing performance.
\* Support coming soon.
npm install follicle --save
And at least ONE of the following:
npm install @seald-io/nedb --save
OR
npm install mongodb --save
WARNING: the examples below are out of date for follicle. They are being updated.
nedb://memory. See below for details:- MongoDB:
- Format: mongodb://[username:password@]host[:port][/db-name]
- Example: var uri = 'mongodb://scott:abc123@localhost:27017/animals';
- NeDB:
- Format: nedb://[directory-path] OR nedb://memory
- Example: var uri = 'nedb:///Users/scott/data/animals';
So to connect to an NeDB database, use the following:
``javascript
const connect = require('camo').connect;
const main = async () => {
const migrations = {
Data: [entry => {
// DO STUFF
return entry
}]
}
const { client, validators, BaseDocument, Document, EmbeddedDocument } = await connect('nedb:///Users/scott/data/animals', {}, migrations)
class MyModel extends Document {
// DO STUFF
}
}
`
class, which handles much of the interface to your backend NoSQL database.`javascript
var Document = require('camo').Document;class Company extends Document {
constructor() {
super();
this.name = String;
this.valuation = {
type: Number,
default: 10000000000,
min: 0
};
this.employees = [String];
this.dateFounded = {
type: Date,
default: Date.now
};
}
static collectionName() {
return 'companies';
}
}
`Notice how the schema is declared right in the constructor as member variables. All _public_ member variables (variables that don't start with an underscore [_]) are added to the schema.
The name of the collection can be set by overriding the
method, which should return the desired collection name as a string. If one isn't given, then Camo uses the name of the class and naively appends an 's' to the end to make it plural.Schemas can also be defined using the
this.schema() method. For example, in the constructor() method you could use:`javascript
this.schema({
name: String,
valuation: {
type: Number,
default: 10000000000,
min: 0
},
employees: [String],
dateFounded: {
type: Date,
default: Date.now
}
});
`Currently supported variable types are:
-
-
-
-
-
-
-
-
- Document ReferenceArrays can either be declared as either un-typed (using
or []), or typed (using the [TYPE] syntax, like [String]). Typed arrays are enforced by Camo on .save() and an Error will be thrown if a value of the wrong type is saved in the array. Arrays of references are also supported.To declare a member variable in the schema, either directly assign it one of the types listed above, or assign it an object with options, like this:
`javascript
this.primeNumber = {
type: Number,
default: 2,
min: 0,
max: 25,
choices: [2, 3, 5, 7, 11, 13, 17, 19, 23],
unique: true
}
`The
option supports both values and no-argument functions (like Date.now). Currently the supported options/validators are:-
type: The value's type (required)
- default: The value to be assigned if none is provided (optional)
- min: The minimum value a Number can be (optional)
- max: The maximum value a Number can be (optional)
- choices: A list of possible values (optional)
- match: A regex string that should match the value (optional)
- validate: A 1-argument function that returns false if the value is invalid (optional)
- unique: A boolean value indicating if a 'unique' index should be set (optional)
- required: A boolean value indicating if a key value is required (optional)To reference another document, just use its class name as the type.
`javascript
class Dog extends Document {
constructor() {
super(); this.name = String;
this.breed = String;
}
}
class Person extends Document {
constructor() {
super();
this.pet = Dog;
this.name = String;
this.age = String;
}
static collectionName() {
return 'people';
}
}
`#### Embedded Documents
Embedded documents can also be used within
s. You must declare them separately from the main Document that it is being used in. EmbeddedDocuments are good for when you need an Object, but also need enforced schemas, validation, defaults, hooks, and member functions. All of the options (type, default, min, etc) mentioned above work on EmbeddedDocuments as well.`javascript
var Document = require('camo').Document;
var EmbeddedDocument = require('camo').EmbeddedDocument;class Money extends EmbeddedDocument {
constructor() {
super();
this.value = {
type: Number,
choices: [1, 5, 10, 20, 50, 100]
};
this.currency = {
type: String,
default: 'usd'
}
}
}
class Wallet extends Document {
constructor() {
super();
this.contents = [Money];
}
}
var wallet = Wallet.create();
wallet.contents.push(Money.create());
wallet.contents[0].value = 5;
wallet.contents.push(Money.create());
wallet.contents[1].value = 100;
wallet.save().then(function() {
console.log('Both Wallet and Money objects were saved!');
});
``$3
To create a new instance of our document, we need to use the method, which handles all of the construction for us.`javascript
var lassie = Dog.create({
name: 'Lassie',
breed: 'Collie'
});lassie.save().then(function(l) {
console.log(l._id);
});
`Once a document is saved, it will automatically be assigned a unique identifier by the backend database. This ID can be accessed by the
property.If you specified a default value (or function) for a schema variable, that value will be assigned on creation of the object.
An alternative to
.save() is .findOneAndUpdate(query, update, options). This static method will find and update (or insert) a document in one atomic operation (atomicity is guaranteed in MongoDB only). Using the {upsert: true} option will return a new document if one is not found with the given query.$3
Both the find and delete methods following closely (but not always exactly) to the MongoDB API, so it should feel fairly familiar.If querying an object by
id, you _must_ use _id and not id.To retrieve an object, you have a few methods available to you.
-
.findOne(query, options) (static method)
- .find(query, options) (static method)The
.findOne() method will return the first document found, even if multiple documents match the query. .find() will return all documents matching the query. Each should be called as static methods on the document type you want to load.`javascript
Dog.findOne({ name: 'Lassie' }).then(function(l) {
console.log('Got Lassie!');
console.log('Her unique ID is', l._id);
});
` currently accepts the following option:-
populate: Boolean value to load all or no references. Pass an array of field names to only populate the specified references
- Person.findOne({name: 'Billy'}, {populate: true}) populates all references in Person object
- Person.findOne({name: 'Billy'}, {populate: ['address', 'spouse']}) populates only 'address' and 'spouse' in Person object.find() currently accepts the following options:-
populate: Boolean value to load all or no references. Pass an array of field names to only populate the specified references
- Person.find({lastName: 'Smith'}, {populate: true}) populates all references in Person object
- Person.find({lastName: 'Smith'}, {populate: ['address', 'spouse']}) populates only 'address' and 'spouse' in Person object
- sort: Sort the documents by the given field(s)
- Person.find({}, {sort: '-age'}) sorts by age in descending order
- Person.find({}, {sort: ['age', 'name']}) sorts by ascending age and then name, alphabetically
- limit: Limits the number of documents returned
- Person.find({}, {limit: 5}) returns a maximum of 5 Person objects
- skip: Skips the given number of documents and returns the rest
- Person.find({}, {skip: 5}) skips the first 5 Person objects and returns all others$3
To remove documents from the database, use one of the following:-
.delete()
- (static method)
- .deleteMany(query, options) (static method)
- .findOneAndDelete(query, options) (static method)The
.delete() method should only be used on an instantiated document with a valid id. The other three methods should be used on the class of the document(s) you want to delete.`javascript
Dog.deleteMany({ breed: 'Collie' }).then(function(numDeleted) {
console.log('Deleted', numDeleted, 'Collies from the database.');
});
`$3
To get the number of matching documents for a query without actually retrieving all of the data, use the method.`javascript
Dog.count({ breed: 'Collie' }).then(function(count) {
console.log('Found', count, 'Collies.');
});
`$3
Camo provides hooks for you to execute code before and after critical parts of your database interactions. For each hook you use, you may return a value (which, as of now, will be discarded) or a Promise for executing asynchronous code. Using Promises throughout Camo allows us to not have to provide separate async and sync hooks, thus making your code simpler and easier to understand.Hooks can be used not only on
objects, but EmbeddedDocument objects as well. The embedded object's hooks will be called when it's parent Document is saved/validated/deleted (depending on the hook you provide).In order to create a hook, you must override a class method. The hooks currently provided, and their corresponding methods, are:
- pre-validate:
preValidate()
- post-validate:
- pre-save:
- post-save:
- pre-delete:
- post-delete: Here is an example of using a hook (pre-delete, in this case):
javascript
class Company extends Document {
constructor() {
super(); this.employees = [Person]
}
static collectionName() {
return 'companies';
}
preDelete() {
var deletes = [];
this.employees.forEach(function(e) {
var p = new Promise(function(resolve, reject) {
resolve(e.delete());
});
deletes.push(p);
});
return Promise.all(deletes);
}
}
`The code above shows a pre-delete hook that deletes all the employees of the company before it itself is deleted. As you can see, this is much more convenient than needing to always remember to delete referenced employees in the application code.
Note: The
and .postDelete() hooks are _only_ called when calling .delete() on a Document instance. Calling .deleteOne() or .deleteMany() will not trigger the hook methods.$3
- camo.getClient(): Retrieves the Camo database client
- camo.getClient().driver(): Retrieves the underlying database driver (MongoClient or a map of NeDB collections)
- Document.toJSON()`: Serializes the given document to just the data, which includes nested and referenced data- Babel
- babel-preset-camo: Babel preset for all es2015 plugins supported by Camo
- TypeScript
- DefinitelyTyped/camo: Camo declaration file (h/t lucasmciruzzi)
- IndefinitivelyTyped/camo: Typings support for Camo (h/t WorldMaker)
Before opening an issue or submitting a PR, I ask that you follow these guidelines:
Issues
- Please state whether your issue is a question, feature request, or bug report.
- Always try the latest version of Camo before opening an issue.
- If the issue is a bug, be sure to clearly state your problem, what you expected to happen, and what all you have tried to resolve it.
- Always try to post simplified code that shows the problem. Use Gists for longer examples.
Pull Requests
- If your PR is a new feature, please consult with me first.
- Any PR should contain only one feature or bug fix. If you have more than one, please submit them as separate PRs.
- Always try to include relevant tests with your PRs. If you aren't sure where a test should go or how to create one, feel free to ask.
- Include updates to the README when needed.
- Do not update the package version or CHANGELOG. I'll handle that for each release.
- Email: s.w.robinson+camo@gmail.com
- Twitter: @ScottWRobinson
For short questions and faster responses, try Twitter.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.