Skip to content

Latest commit

 

History

History
483 lines (369 loc) · 18 KB

API.md

File metadata and controls

483 lines (369 loc) · 18 KB

API reference

Properties

_idClass

The type used to cast _id properties. Defaults to MongoDB.ObjectId.

If you wanted to use plain strings for your document _id properties you could:

Kitten._idClass = String;

When you define a custom _idClass property for your model you just need to pass an _id parameter of that type when you create new documents.

const data = {
    _id: 'captain-cute',
    name: 'Captain Cute'
};

Kitten.insert(data, (err, results) => {

    // handle response
});

collection

The name of the collection in MongoDB.

Kitten.collection = 'kittens';

ObjectId

An alias to MongoDB.ObjectId.

schema

A joi object schema. See: https://github.com/hapijs/joi

Kitten.schema = Joi.object().keys({
    _id: Joi.string(),
    name: Joi.string().required(),
    email: Joi.string().required()
});

Methods

connect(uri, options, callback)

Connects to a MongoDB server where:

  • uri - the connection string passed to MongoClient.connect.
  • options - an optional object passed to MongoClient.connect.
  • callback - the callback method using the signature function (err, db) where:
    • err - if the connection failed, the error reason, otherwise null.
    • db - if the connection succeeded, the initialized db object.

aggregate(pipeline, [options], callback)

Calculates aggregate values for the data in a collection where:

  • pipeline - A sequence of data aggregation operations or stages.
  • options - an options object passed to MongoDB's native aggregate method.
  • callback - the callback method using the signature function (err, results) where:
    • err - if the query failed, the error reason, otherwise null.
    • results - if the query succeeded, an array of documents return from the aggregation.

count(filter, [options], callback)

Counts documents matching a filter where:

  • filter - a filter object used to select the documents to count.
  • options - an options object passed to MongoDB's native count method.
  • callback - the callback method using the signature function (err, count) where:
    • err - if the query failed, the error reason, otherwise null.
    • count - if the query succeeded, a number indicating how many documents matched the filter.

createIndexes(indexSpecs, [callback])

Note: createIndexes is called during plugin registration for each model when the autoIndex option is set to true.

Creates multiple indexes in the collection where:

  • indexSpecs - an array of objects containing index specifications to be created.
  • callback - the callback method using the signature function (err, result) where:
    • err - if creating the indexes failed, the error reason, otherwise null.
    • result - if creating the indexes succeeded, the result object.

Indexes are defined as a static property on your models like:

Kitten.indexes = [
    { key: { name: 1 } },
    { key: { email: -1 } }
];

For details on all the options an index specification may have see:

https://docs.mongodb.org/manual/reference/command/createIndexes/

deleteMany(filter, [options], callback)

Deletes multiple documents and returns the count of deleted documents where:

  • filter - a filter object used to select the documents to delete.
  • options - an options object passed to MongoDB's native deleteMany method.
  • callback - the callback method using the signature function (err, count) where:
    • err - if the query failed, the error reason, otherwise null.
    • count - if the query succeeded, a number indicating how many documents were deleted.

deleteOne(filter, [options], callback)

Deletes a document and returns the count of deleted documents where:

  • filter - a filter object used to select the document to delete.
  • options - an options object passed to MongoDB's native deleteOne method.
  • callback - the callback method using the signature function (err, count) where:
    • err - if the query failed, the error reason, otherwise null.
    • count - if the query succeeded, a number indicating how many documents were deleted.

disconnect()

Closes the current db connection.

distinct(field, [filter], callback)

Finds the distinct values for the specified field.

  • field - a string representing the field for which to return distinct values.
  • filter - an optional filter object used to limit the documents distinct applies to.
  • callback - the callback method using the signature function (err, values) where:
    • err - if the query failed, the error reason, otherwise null.
    • values - if the query succeeded, an array of values representing the distinct values for the specified field.

fieldsAdapter(fields)

A helper method to create a fields object suitable to use with MongoDB queries where:

  • fields - a string with space separated field names. Fields may be prefixed with - to indicate exclusion instead of inclusion.

Returns a MongoDB friendly fields object.

Kitten.fieldsAdapter('name -email');

// { name: true, email: false }

find(filter, [options], callback)

Finds documents where:

  • filter - a filter object used to select the documents.
  • options - an options object passed to MongoDB's native find method.
  • callback - the callback method using the signature function (err, results) where:
    • err - if the query failed, the error reason, otherwise null.
    • results - if the query succeeded, an array of documents as class instances.

findById(id, [options], callback)

Finds a document by _id where:

  • id - is a string value of the _id to find. It will be casted to the type of _idClass.
  • options - an options object passed to MongoDB's native findOne method.
  • callback - the callback method using the signature function (err, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • result - if the query succeeded, a document as a class instance.

findByIdAndDelete(id, callback)

Finds a document by _id, deletes it and returns it where:

  • id - is a string value of the _id to find. It will be casted to the type of _idClass.
  • callback - the callback method using the signature function (err, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • result - if the query succeeded, a document as a class instance.

findByIdAndUpdate(id, update, [options], callback)

Finds a document by _id, updates it and returns it where:

  • id - is a string value of the _id to find. It will be casted to the type of _idClass.
  • update - an object containing the fields/values to be updated.
  • options - an optional options object passed to MongoDB's native findOneAndUpdate method. Defaults to { returnOriginal: false }.
  • callback - the callback method using the signature function (err, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • result - if the query succeeded, a document as a class instance.

findOne(filter, [options], callback)

Finds one document matching a filter where:

  • filter - a filter object used to select the document.
  • options - an options object passed to MongoDB's native findOne method.
  • callback - the callback method using the signature function (err, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • result - if the query succeeded, a document as a class instance.

findOneAndDelete(filter, [options], callback)

Finds one document matching a filter, deletes it and returns it where:

  • filter - a filter object used to select the document to delete.
  • options - an options object passed to MongoDB's native findOneAndDelete method.
  • callback - the callback method using the signature function (err, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • result - if the query succeeded, a document as a class instance.

findOneAndUpdate(filter, update, [options], callback)

Finds one document matching a filter, updates it and returns it where:

  • filter - a filter object used to select the document to update.
  • update - an object containing the fields/values to be updated.
  • options - an options object passed to MongoDB's native findOneAndUpdate method. Defaults to { returnOriginal: false }.
  • callback - the callback method using the signature function (err, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • result - if the command succeeded, a document as a class instance.

insertMany(docs, [options], callback)

Inserts multiple documents and returns them where:

  • docs - an array of document objects to insert.
  • options - an options object passed to MongoDB's native insertMany method.
  • callback - the callback method using the signature function (err, results) where:
    • err - if the query failed, the error reason, otherwise null.
    • results - if the command succeeded, an array of documents as a class instances.

insertOne(doc, [options], callback)

Inserts a document and returns the new document where:

  • doc - a document object to insert.
  • options - an options object passed to MongoDB's native insertOne method.
  • callback - the callback method using the signature function (err, results) where:
    • err - if the query failed, the error reason, otherwise null.
    • results - if the command succeeded, an array of documents as a class instances.

pagedFind(filter, fields, sort, limit, page, callback)

Finds documents with paginated results where:

  • filter - a filter object used to select the documents.
  • fields - indicates which fields should be included in the response (default is all). Can be a string with space separated field names.
  • sort - indicates how to sort documents. Can be a string with space separated fields. Fields may be prefixed with - to indicate decending sort order.
  • limit - a number indicating how many results should be returned.
  • page - a number indicating the current page.
  • callback - is the callback method using the signature function (err, results) where:
    • err - if the query failed, the error reason, otherwise null.
    • results - the results object where:
      • data - an array of documents from the query as class instances.
      • pages - an object where:
        • current - a number indicating the current page.
        • prev - a number indicating the previous page.
        • hasPrev - a boolean indicating if there is a previous page.
        • next - a number indicating the next page.
        • hasNext - a boolean indicating if there is a next page.
        • total - a number indicating the total number of pages.
      • items - an object where:
        • limit - a number indicating the how many results should be returned.
        • begin - a number indicating what item number the results begin with.
        • end - a number indicating what item number the results end with.
        • total - a number indicating the total number of matching results.

replaceOne(filter, doc, [options], callback)

Replaces a document and returns the count of modified documents where:

  • filter - a filter object used to select the document to replace.
  • doc - the document that replaces the matching document.
  • options - an options object passed to MongoDB's native replaceOne method.
  • callback - the callback method using the signature function (err, count, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • count - if the query succeeded, a number indicating how many documents were modified.
    • result - if the query succeeded, the raw result document returned by MongoDB's native driver.

sortAdapter(sorts)

A helper method to create a sort object suitable to use with MongoDB queries where:

  • sorts - a string with space separated field names. Fields may be prefixed with - to indicate decending sort order.

Returns a MongoDB friendly sort object.

Kitten.sortAdapter('name -email');

// { name: 1, email: -1 }

updateMany(filter, update, [options], callback)

Updates multiple documents and returns the count of modified documents where:

  • filter - a filter object used to select the documents to update.
  • update - the update operations object.
  • options - an options object passed to MongoDB's native updateMany method.
  • callback - the callback method using the signature function (err, count, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • count - if the command succeeded, a number indicating how many documents were modified.
    • result - if the query succeeded, the raw result document returned by MongoDB's native driver.

updateOne(filter, update, [options], callback)

Updates a document and returns the count of modified documents where:

  • filter - a filter object used to select the document to update.
  • update - the update operations object.
  • options - an options object passed to MongoDB's native updateOne method.
  • callback - the callback method using the signature function (err, count, result) where:
    • err - if the query failed, the error reason, otherwise null.
    • count - if the command succeeded, a number indicating how many documents were modified.
    • result - if the query succeeded, the raw result document returned by MongoDB's native driver.

validate(callback)

Uses joi validation using the static schema object property of a model class to validate the instance data of a model where:

  • callback - is the callback method using the signature function (err, value) where:
    • err - if validation failed, the error reason, otherwise null.
    • value - the validated value with any type conversions and other modifiers applied.
const cc = new Kitten({
    name: 'Captain Cute'
});

cc.validate((err, value) => {

    // handle results
});

See: https://github.com/hapijs/joi/blob/master/API.md#validatevalue-schema-options-callback

validate(input, callback)

Uses joi validation using the static schema object property of a model class to validate input where:

  • input - is the object to validate.
  • callback - is the callback method using the signature function (err, value) where:
    • err - if validation failed, the error reason, otherwise null.
    • value - the validated value with any type conversions and other modifiers applied.
const data = {
    name: 'Captain Cute'
};

Kitten.validate(data, (err, value) => {

    // handle results
});

See: https://github.com/hapijs/joi/blob/master/API.md#validatevalue-schema-options-callback