Skip to content

Commit

Permalink
Deprecated loadMany, loadOne, loadOneAndUpdate, and loadOneAndDelete …
Browse files Browse the repository at this point in the history
…in favor of find, findOne, findOneAndUpdate, and findOneAndDelete, respectively. Closes #37
  • Loading branch information
scottwrobinson committed Feb 24, 2016
1 parent 522d4dc commit 1a2905b
Show file tree
Hide file tree
Showing 13 changed files with 121 additions and 99 deletions.
34 changes: 17 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ And at least ONE of the following:
npm install mongodb --save

## Quick Start
Camo was built with ease-of-use and ES6 in mind, so you might notice it has more of an OOP feel to it than many existing libraries and ODMs. Don't worry, focusing on object-oriented design doesn't mean we forgot about functional techniques or asynchronous programming. Promises are built-in to the API. Just about every call you make interacting with the database (load, save, delete, etc) will return a Promise. No more callback hell :)
Camo was built with ease-of-use and ES6 in mind, so you might notice it has more of an OOP feel to it than many existing libraries and ODMs. Don't worry, focusing on object-oriented design doesn't mean we forgot about functional techniques or asynchronous programming. Promises are built-in to the API. Just about every call you make interacting with the database (find, save, delete, etc) will return a Promise. No more callback hell :)

For a short tutorial on using Camo, check out [this](http://stackabuse.com/getting-started-with-camo/) article.

Expand Down Expand Up @@ -250,52 +250,52 @@ Once a document is saved, it will automatically be assigned a unique identifier

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 `.loadOneAndUpdate(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.
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.
### Loading
Both the load and delete methods following closely (but not always exactly) to the MongoDB API, so it should feel fairly familiar.
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.
- `.loadOne(query, options)` (static method)
- `.loadMany(query, options)` (static method)
- `.findOne(query, options)` (static method)
- `.find(query, options)` (static method)
The `.loadOne()` method will return the first document found, even if multiple documents match the query. `.loadMany()` will return all documents matching the query. Each should be called as static methods on the document type you want to load.
The `.findOne()` method will return the first document found, even if multiple documents match the query. `.findMany()` will return all documents matching the query. Each should be called as static methods on the document type you want to load.
```javascript
Dog.loadOne({ name: 'Lassie' }).then(function(l) {
Dog.findOne({ name: 'Lassie' }).then(function(l) {
console.log('Got Lassie!');
console.log('Her unique ID is', l.id);
});
```
`.loadOne()` currently accepts the following option:
`.findOne()` 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.loadOne({name: 'Billy'}, {populate: true})` populates all references in `Person` object
- `Person.loadOne({name: 'Billy'}, {populate: ['address', 'spouse']})` populates only 'address' and 'spouse' in `Person` object
- `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
`.loadMany()` currently accepts the following options:
`.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.loadMany({lastName: 'Smith'}, {populate: true})` populates all references in `Person` object
- `Person.loadMany({lastName: 'Smith'}, {populate: ['address', 'spouse']})` populates only 'address' and 'spouse' in `Person` object
- `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
- `Person.loadMany({}, {sort: '-age'})` sorts by age in descending order
- `Person.find({}, {sort: '-age'})` sorts by age in descending order
- `limit`: Limits the number of documents returned
- `Person.loadMany({}, {limit: 5})` returns a maximum of 5 `Person` objects
- `Person.find({}, {limit: 5})` returns a maximum of 5 `Person` objects
- `skip`: Skips the given number of documents and returns the rest
- `Person.loadMany({}, {skip: 5})` skips the first 5 `Person` objects and returns all others
- `Person.find({}, {skip: 5})` skips the first 5 `Person` objects and returns all others
### Deleting
To remove documents fromt the database, use one of the following:
- `.delete()`
- `.deleteOne(query, options)` (static method)
- `.deleteMany(query, options)` (static method)
- `.loadOneAndDelete(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.
Expand Down
2 changes: 1 addition & 1 deletion lib/base-document.js
Original file line number Diff line number Diff line change
Expand Up @@ -401,7 +401,7 @@ class BaseDocument {
}

// Bulk load dereferences
var p = type.loadMany({ '_id': { $in: keyIds } }, { populate: false })
var p = type.find({ '_id': { $in: keyIds } }, { populate: false })
.then(function(dereferences) {
// Assign each dereferenced object to parent

Expand Down
18 changes: 10 additions & 8 deletions lib/clients/client.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
"use strict";

var deprecate = require('depd')('camo');

class DatabaseClient {
constructor(url) {
this._url = url;
Expand All @@ -21,20 +23,20 @@ class DatabaseClient {
throw new TypeError('You must override deleteMany.');
}

loadOne(collection, query) {
throw new TypeError('You must override loadOne.');
findOne(collection, query) {
throw new TypeError('You must override findOne.');
}

loadOneAndUpdate(collection, query, values, options) {
throw new TypeError('You must override loadOneAndUpdate.');
findOneAndUpdate(collection, query, values, options) {
throw new TypeError('You must override findOneAndUpdate.');
}

loadOneAndDelete(collection, query, options) {
throw new TypeError('You must override loadOneAndDelete.');
findOneAndDelete(collection, query, options) {
throw new TypeError('You must override findOneAndDelete.');
}

loadMany(collection, query) {
throw new TypeError('You must override loadMany.');
find(collection, query, options) {
throw new TypeError('You must override findMany.');
}

count(collection, query) {
Expand Down
8 changes: 4 additions & 4 deletions lib/clients/mongoclient.js
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ class MongoClient extends DatabaseClient {
});
}

loadOne(collection, query) {
findOne(collection, query) {
var that = this;
query = castQueryIds(query);
return new Promise(function(resolve, reject) {
Expand All @@ -91,7 +91,7 @@ class MongoClient extends DatabaseClient {
});
}

loadOneAndUpdate(collection, query, values, options) {
findOneAndUpdate(collection, query, values, options) {
var that = this;
query = castQueryIds(query);
if (!options) {
Expand All @@ -118,7 +118,7 @@ class MongoClient extends DatabaseClient {
});
}

loadOneAndDelete(collection, query, options) {
findOneAndDelete(collection, query, options) {
var that = this;
query = castQueryIds(query);
if (!options) {
Expand All @@ -135,7 +135,7 @@ class MongoClient extends DatabaseClient {
});
}

loadMany(collection, query, options) {
find(collection, query, options) {
var that = this;
query = castQueryIds(query);
return new Promise(function(resolve, reject) {
Expand Down
14 changes: 7 additions & 7 deletions lib/clients/nedbclient.js
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ class NeDbClient extends DatabaseClient {
});
}

loadOne(collection, query) {
findOne(collection, query) {
var that = this;
return new Promise(function(resolve, reject) {
var db = getCollection(collection, that._collections, that._path);
Expand All @@ -118,14 +118,14 @@ class NeDbClient extends DatabaseClient {
});
}

loadOneAndUpdate(collection, query, values, options) {
findOneAndUpdate(collection, query, values, options) {
var that = this;

if (!options) {
options = {};
}

// Since this is 'loadOne...' we'll only allow user to update
// Since this is 'findOne...' we'll only allow user to update
// one document at a time
options.multi = false;

Expand All @@ -139,7 +139,7 @@ class NeDbClient extends DatabaseClient {
resolve(newDoc);
});*/

that.loadOne(collection, query).then(function(data) {
that.findOne(collection, query).then(function(data) {
if (!data) {
if (options.upsert) {
return db.insert(values, function(error, result) {
Expand All @@ -160,14 +160,14 @@ class NeDbClient extends DatabaseClient {
});
}

loadOneAndDelete(collection, query, options) {
findOneAndDelete(collection, query, options) {
var that = this;

if (!options) {
options = {};
}

// Since this is 'loadOne...' we'll only allow user to update
// Since this is 'findOne...' we'll only allow user to update
// one document at a time
options.multi = false;

Expand All @@ -180,7 +180,7 @@ class NeDbClient extends DatabaseClient {
});
}

loadMany(collection, query, options) {
find(collection, query, options) {
var that = this;
return new Promise(function(resolve, reject) {
var db = getCollection(collection, that._collections, that._path);
Expand Down
36 changes: 28 additions & 8 deletions lib/document.js
Original file line number Diff line number Diff line change
Expand Up @@ -179,16 +179,21 @@ class Document extends BaseDocument {
return DB().deleteMany(this.collectionName(), query);
}

// TODO: Need options to specify whether references should be loaded
static loadOne(query, options) {
deprecate('loadOne - use findOne instead');
return this.findOne(query, options);
}

// TODO: Need options to specify whether references should be loaded
static findOne(query, options) {
var that = this;

var populate = true;
if (options && options.hasOwnProperty('populate')) {
populate = options.populate;
}

return DB().loadOne(this.collectionName(), query)
return DB().findOne(this.collectionName(), query)
.then(function(data) {
if (!data) {
return null;
Expand All @@ -209,10 +214,15 @@ class Document extends BaseDocument {
}

static loadOneAndUpdate(query, values, options) {
deprecate('loadOneAndUpdate - use findOneAndUpdate instead');
return this.findOneAndUpdate(query, values, options);
}

static findOneAndUpdate(query, values, options) {
var that = this;

if (arguments.length < 2) {
throw new Error('loadOneAndUpdate requires at least 2 arguments. Got ' + arguments.length + '.');
throw new Error('findOneAndUpdate requires at least 2 arguments. Got ' + arguments.length + '.');
}

if (!options) {
Expand All @@ -224,7 +234,7 @@ class Document extends BaseDocument {
populate = options.populate;
}

return DB().loadOneAndUpdate(this.collectionName(), query, values, options)
return DB().findOneAndUpdate(this.collectionName(), query, values, options)
.then(function(data) {
if (!data) {
return null;
Expand All @@ -245,21 +255,31 @@ class Document extends BaseDocument {
}

static loadOneAndDelete(query, options) {
deprecate('loadOneAndDelete - use findOneAndDelete instead');
return this.findOneAndDelete(query, options);
}

static findOneAndDelete(query, options) {
var that = this;

if (arguments.length < 1) {
throw new Error('loadOneAndDelete requires at least 1 argument. Got ' + arguments.length + '.');
throw new Error('findOneAndDelete requires at least 1 argument. Got ' + arguments.length + '.');
}

if (!options) {
options = {};
}

return DB().loadOneAndDelete(this.collectionName(), query, options);
return DB().findOneAndDelete(this.collectionName(), query, options);
}

// TODO: Need options to specify whether references should be loaded
static loadMany(query, options) {
deprecate('loadMany - use find instead');
return this.find(query, options);
}

// TODO: Need options to specify whether references should be loaded
static find(query, options) {
var that = this;

if (query === undefined || query === null) {
Expand All @@ -271,7 +291,7 @@ class Document extends BaseDocument {
options = {populate: true};
}

return DB().loadMany(this.collectionName(), query, options)
return DB().find(this.collectionName(), query, options)
.then(function(datas) {
var docs = that._fromData(datas);

Expand Down
Loading

0 comments on commit 1a2905b

Please sign in to comment.