Skip to content

API.md

Latest commit

 

History

History
478 lines (349 loc) · 16.3 KB

API.md

File metadata and controls

478 lines (349 loc) · 16.3 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:

Customer._idClass = String;

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

const document = new Customer({
    _id: 'stephen-colbert',
    name: 'Stephen Colbert'
});

const customers = await Customer.insertOne(data);

collectionName

The name of the collection in MongoDB.

Customer.collectionName = 'customers';

indexes

An array of index specifications for this model. See the index specification.

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

Note: These are just the definitions, the async createIndexes(indexSpecs, [options]) method doesn't automatically use this property. You could pass this property to that method though:

const result = await Customer.createIndexes(Customer.indexes);

ObjectID

An alias to MongoDB.ObjectID.

schema

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

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

Methods

constructor(data)

Constructs a new instance of your class using the data provided where:

  • data - an object containing the fields and values of the model instance. Internally data is passed to the validate function, throwing an error if present or assigning the value (the validated value with any type conversions and other modifiers applied) to the object as properties.

async aggregate(pipeline, [options])

Execute an aggregation framework pipeline against the collection.

  • pipeline - an array containing all the aggregation framework commands.
  • options - an optional object passed to MongoDB's native Collection.aggregate method.

collection()

Returns the underlying MongoDB.Collection.

async connect(connection, [options], [name])

Connects to a MongoDB server and returns the MongoDB.Db where:

  • connection - an object where:
  • options - an optional object passed to MongoClient.connect.
  • name - an optional string to identify the connection. Used to support multiple connections along with the with(name) method. Defaults to default.

async count(query, [options])

Returns the number of documents matching a query where:

  • query - a filter object used to select the documents to count.
  • options - an optional object passed to the native Collection.count method.

async createIndexes(indexSpecs, [options])

Creates multiple indexes in the collection and returns the result where:

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

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

async deleteMany(filter, [options])

Deletes multiple documents and returns the Collection.deleteWriteOpResult where:

  • filter - a filter object used to select the documents to delete.
  • options - an optional object passed to MongoDB's native Collection.deleteMany method.

async deleteOne(filter, [options])

Deletes a document and returns the Collection.deleteWriteOpResult where:

  • filter - a filter object used to select the document to delete.
  • options - an optional object passed to MongoDB's native Collection.deleteOne method.

disconnect([name])

Closes a specific connection by name or all connections if no name is specified.

async distinct(key, query, [options])

Returns a list of distinct values for the given key across a collection where:

  • key - a string representing the field for which to return distinct values.
  • query - an optional query object used to limit the documents distinct applies to.

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.

Customer.fieldsAdapter('name -email');

// { name: true, email: false }

async find(query, [options])

Finds documents and returns an array of model instances where:

  • query - a query object used to select the documents.
  • options - an optional object passed to MongoDB's native Collection.find method.

async findById(id, [options])

Finds a document by _id and returns a model instance where:

  • id - a string value of the _id to find. The id will be casted to the type of _idClass.
  • options - an optional object passed to MongoDB's native Collection.findOne method.

async findByIdAndDelete(id)

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

  • id - a string value of the _id to find. The id will be casted to the type of _idClass.

async findByIdAndUpdate(id, update, [options])

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

  • id - a string value of the _id to find. The id will be casted to the type of _idClass.
  • update - an object containing the fields/values to be updated.
  • options - an optional object passed to MongoDB's native Collection.findOneAndUpdate method. Defaults to { returnOriginal: false }.

async findOne(query, [options])

Finds one document matching the query and returns a model intance where:

  • query - a filter object used to select the document.
  • options - an optional object passed to MongoDB's native Collection.findOne method.

async findOneAndDelete(filter, [options])

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

  • filter - a filter object used to select the document to delete.
  • options - an optional object passed to MongoDB's native Collection.findOneAndDelete method.

async findOneAndReplace(filter, replacement, [options])

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

  • filter - a filter object used to select the document to delete.
  • replacement - the document replacing the matching document.
  • options - an optional object passed to MongoDB's native Collection.findOneAndReplace method. Defaults to { returnOriginal: false }.

async findOneAndUpdate(filter, update, [options])

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

  • filter - a filter object used to select the document to update.
  • update - an object containing the fields/values to be updated.
  • options - an optional object passed to MongoDB's native Collection.findOneAndUpdate method. Defaults to { returnOriginal: false }.

async insertMany(docs, [options])

Inserts multiple documents and returns and array of model instances where:

  • docs - an array of document objects to insert.
  • options - an optional object passed to MongoDB's native Collection.insertMany method.

async insertOne(doc, [options])

Inserts a document and returns a model instance where:

  • doc - a document object to insert.
  • options - an optional object passed to MongoDB's native Collection.insertOne method.

async pagedFind(filter, page, limit, [options])

Finds documents and returns the results where:

  • filter - a filter object used to select the documents.
  • page - a number indicating the current page.
  • limit - a number indicating how many results should be returned.
  • options - an optional object passed to MongoDB's native Collection.find method.

The returned value is an object where:

  • data - an array of model 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.

async replaceOne(filter, doc, [options])

Replaces a document and returns a Collection.updateWriteOpResult where:

  • filter - a filter object used to select the document to replace.
  • doc - the document that replaces the matching document.
  • options - an optional object passed to MongoDB's native Collection.replaceOne method.

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.

Customer.sortAdapter('name -email');

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

async updateMany(filter, update, [options])

Updates multiple documents and returns a Collection.updateWriteOpResult where:

  • filter - a filter object used to select the documents to update.
  • update - the update operations object.
  • options - an optional object passed to MongoDB's native Collection.updateMany method.

async updateOne(filter, update, [options])

Updates a document and returns a Collection.updateWriteOpResult where:

  • filter - a filter object used to select the document to update.
  • update - the update operations object.
  • options - an optional object passed to MongoDB's native Collection.updateOne method.

validate()

Uses joi validation internally with the static schema property of the model to validate the instance data and returns the validated value where:

const stephen = new Customer({
    name: 'Stephen Colbert'
});

const result = stephen.validate();

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

validate(input)

Uses joi validation internally with the static schema property of the model to validate the input data and returns the validated value where:

  • input - is the object to validate.
const data = {
    name: 'Stephen Colbert'
};

const result = Customer.validate(data);

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

with(name)

For use with multiple named connections (See: connect(connection, [options], [name])).

Returns an object containing a subset of the model's methods bound to the named connection.

Available methods include:

  • aggregate
  • collection
  • count
  • createIndexes
  • deleteMany
  • deleteOne
  • distinct
  • find
  • findById
  • findByIdAndDelete
  • findByIdAndUpdate
  • findOne
  • findOneAndDelete
  • findOneAndReplace
  • findOneAndUpdate
  • insertMany
  • insertOne
  • pagedFind
  • replaceOne
  • updateMany
  • updateOne
await MongoModels.connect(config.connection, config.options, 'alt');

// ...

const count = await Customer.with('alt').count({});