<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## Monoxide

## connect

Connect to a Mongo database

**Parameters**

-   `uri` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The URL of the database to connect to
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Optional callback when connected, if omitted this function is syncronous

Returns **monoxide** The Monoxide chainable object

## monoxideModel

## express

### sendError

Function to use when sending an error to the browser
NOTE: This function will first look for a res.sendError(code, text) function and use that if it finds one. Otherwise it will default to res.status(code).send(text).end()

**Parameters**

-   `res` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The response object
-   `code` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** A valida HTTP return code
-   `err` **any?** Optional error text to report

## isObjectId

Alias of isObjectID

## runMiddleware

Run optional middleware

Middleware can be:
	\- A function(req, res, next)

-   An array of functions(req, res, next) - Functions will be called in sequence, all functions must call the next method
-   A string - If specified (and `obj` is also specified) the middleware to use will be looked up as a key of the object. This is useful if you need to invoke similar methods on different entry points (e.g. monoxide.express.middleware('widgets', {save: function(req, res, next) { // Check something // }, create: 'save'}) - where the `create` method invokes the same middleware as \`save)

**Parameters**

-   `middleware` **(null | [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) \| [array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array))** The optional middleware to run this can be a function, an array of functions or a string
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The callback to invoke when completed. This may not be called
-   `obj` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The parent object to look up inherited functions from (if middleware is a string)
-   `req`  
-   `res`  

**Examples**

```javascript
// Set up a Monoxide express middleware to check user logins on each save or create operaion
app.use('/api/widgets/:id?', monoxide.express.middleware('widgets', {
	create: function(req, res, next) {
	if (req.user && req.user._id) {
			next();
		} else {
			res.status(403).send('You are not logged in').end();
	}
},
	save: 'create', // Point to the same checks as the `create` middleware
}));
```

## monoxide.get

Retrieve a single record from a model via its ID
This function will ONLY retrieve via the ID field, all other fields are ignored
NOTE: Really this function just wraps the monoxide.query() function to provide functionality like populate

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.$id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The ID to return
    -   `q.$populate` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>)?** Population criteria to apply
-   `id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The ID to return (alternative syntax)
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** (err, result) the callback to call on completion or error

**Examples**

```javascript
// Return a single widget by its ID (string syntax)
monoxide.get('widgets', '56e2421f475c1ef4135a1d58', function(err, res) {
	console.log('Widget:', res);
});
```

```javascript
// Return a single widget by its ID (object syntax)
monoxide.get({$collection: 'widgets', $id: '56e2421f475c1ef4135a1d58'}, function(err, res) {
	console.log('Widget:', res);
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.queryBuilder.find

Add a filtering function to an existing query

**Parameters**

-   `q` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))?** Optional filtering object or callback (in which case we act as exec())
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.select

Add select criteria to an existing query
If this function is passed a falsy value it is ignored

**Parameters**

-   `q` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))?** Select criteria, for strings or arrays of strings use the field name optionally prefixed with '-' for omission. For Objects use `{field: 1|-1}`
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.sort

Add sort criteria to an existing query
If this function is passed a falsy value it is ignored

**Parameters**

-   `q` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))?** Sorting criteria, for strings or arrays of strings use the field name optionally prefixed with '-' for decending search order. For Objects use `{ field: 1|-1|'asc'|'desc'}`
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.limit

Add limit criteria to an existing query
If this function is passed a falsy value the limit is removed

**Parameters**

-   `q` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Limit records to this number
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.skip

Add skip criteria to an existing query
If this function is passed a falsy value the skip offset is removed

**Parameters**

-   `q` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Skip this number of records
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.populate

Add population criteria to an existing query
If this function is passed a falsy value it is ignored

**Parameters**

-   `q` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))?** Population criteria, for strings or arrays of strings use the field name
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.exec

Execute the query and return the error and any results

**Parameters**

-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** (err,result)

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.queryBuilder.optional

Convenience function to set $errNotFound

**Parameters**

-   `isOptional` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))?** Whether the return from this query should NOT throw an error if nothing was found (optional, default `true`)
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** This chainable object

## monoxide.aggregate

Perform a direct aggregation and return the result

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.$stages` **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The aggregation stages array
        -   `q.$stages.$project` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Fields to be supplied in the aggregation (in the form `{field: true}`)
            -   `q.$stages.$project._id` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** If true surpress the output of the `_id` field (optional, default `false`)
        -   `q.$stages.$match` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Specify a filter on fields (in the form `{field: CRITERIA}`)
        -   `q.$stages.$redract` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$limit` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$skip` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$unwind` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$group` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$sample` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$sort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Specify an object of fields to sort by (in the form `{field: 1|-1}` where 1 is ascending and -1 is decending sort order)
        -   `q.$stages.$geoNear` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$lookup` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$out` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
        -   `q.$stages.$indexStats` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** (err, result) the callback to call on completion or error

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.query

Query Mongo directly with the Monoxide query syntax

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.$id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** If specified return only one record by its master ID (implies $one=true). If present all other conditionals will be ignored and only the object is returned (see $one)
    -   `q.$select` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>)?** Field selection criteria to apply (implies q.$applySchema=false as we will be dealing with a partial schema). Any fields prefixed with '-' are removed
    -   `q.$sort` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>)?** Sorting criteria to apply
    -   `q.$populate` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>)?** Population criteria to apply
    -   `q.$one` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether a single object should be returned (implies $limit=1). If enabled an object is returned not an array (optional, default `false`)
    -   `q.$limit` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Limit the return to this many rows
    -   `q.$skip` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Offset return by this number of rows
    -   `q.$data` **([object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))?** Set the user-defined data object, if this is a function the callback result is used
    -   `q.$decorate` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Add all Monoxide methods, functions and meta properties (optional, default `true`)
    -   `q.$plain` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Return a plain object or object array. This is the equivelent of calling .toObject() on any resultant object. Implies $decorate=true (optional, default `false`)
    -   `q.$cacheFKs` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Cache the foreign keys (objectIDs) within an object so future retrievals dont have to recalculate the model structure (optional, default `true`)
    -   `q.$applySchema` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Apply the schema for each document retrieval - this slows retrieval but means any alterations to the schema are applied to each retrieved record (optional, default `true`)
    -   `q.$dirty` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether the entire document contents should be marked as dirty (modified). If true this also skips the computation of modified fields (optional, default `false`)
    -   `q.$errNotFound` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Raise an error if a specifically requested document is not found (requires $id)
    -   `q.filter` **...any?** Any other field (not beginning with '$') is treated as filtering criteria
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** (err, result) the callback to call on completion or error. If $one is truthy this returns a single monoxide.monoxideDocument, if not it returns an array of them

**Examples**

```javascript
// Return all Widgets, sorted by name
monoxide.query({$collection: 'widgets', $sort: 'name'}, function(err, res) {
	console.log('Widgets:', res);
});
```

```javascript
// Filter Users to only return admins while also populating their country
monoxide.query({$collection: 'users', $populate: 'country', role: 'admin'}, function(err, res) {
	console.log('Admin users:', res);
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.count

Similar to query() but only return the count of possible results rather than the results themselves

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.filter` **...any?** Any other field (not beginning with '$') is treated as filtering criteria
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** (err,count) the callback to call on completion or error

**Examples**

```javascript
// Count all Widgets
monoxide.count({$collection: 'widgets'}, function(err, count) {
	console.log('Number of Widgets:', count);
});
```

```javascript
// Count all admin Users
monoxide.query({$collection: 'users', role: 'admin'}, function(err, count) {
	console.log('Number of Admin Users:', count);
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.save

Save an existing Mongo document by its ID
If you wish to create a new document see the monoxide.create() function.
If the existing document ID is not found this function will execute the callback with an error

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.$id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The ID of the document to save
    -   `q.$refetch` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether to refetch the record after update, false returns `null` in the callback (optional, default `true`)
    -   `q.$errNoUpdate` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Raise an error if no documents were actually updated (optional, default `false`)
    -   `q.$errBlankUpdate` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Raise an error if no fields are updated (optional, default `false`)
    -   `q.$returnUpdated` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** If true returns the updated document, if false it returns the document that was replaced (optional, default `true`)
    -   `q.$version` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Increment the `__v` property when updating (optional, default `true`)
    -   `q.field` **...any?** Any other field (not beginning with '$') is treated as data to save
-   `function`  (err,result)] Optional callback to call on completion or error

**Examples**

```javascript
// Save a Widget
monoxide.save({
	$collection: 'widgets',
	$id: 1234,
	name: 'New name',
}, function(err, widget) {
	console.log('Saved widget is now', widget);
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.update

Update multiple documents

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to query by
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.$refetch` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Return the newly updated record (optional, default `true`)
    -   `q.field` **...any?** Any other field (not beginning with '$') is treated as filter data
-   `qUpdate` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to update into the found documents
    -   `qUpdate.field` **...any?** Data to save into every record found by `q`
-   `function`  (err,result)] Optional callback to call on completion or error

**Examples**

```javascript
// Set all widgets to active
monoxide.update({
	$collection: 'widgets',
	status: 'active',
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.create

Create a new Mongo document and return it
If you wish to save an existing document see the monoxide.save() function.

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to query
    -   `q.$refetch` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Return the newly create record (optional, default `true`)
    -   `q.$version` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Set the `__v` field to 0 when creating the document (optional, default `true`)
    -   `q.field` **...any?** Any other field (not beginning with '$') is treated as data to save
-   `function`  (err,result)] Optional callback to call on completion or error

**Examples**

```javascript
// Create a Widget
monoxide.save({
	$collection: 'widgets',
	name: 'New widget name',
}, function(err, widget) {
	console.log('Created widget is', widget);
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.delete

Delete a Mongo document by its ID
This function has two behaviours - it will, by default, only delete a single record by its ID. If `q.$multiple` is true it will delete by query.
If `q.$multiple` is false and the document is not found (by `q.$id`) this function will execute the callback with an error
Delete will only work with no parameters if monoxide.settings.removeAll is truthy as an extra safety check

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The collection / model to query
    -   `q.$id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The ID of the document to delete (if you wish to do a remove based on query set q.$query=true)
    -   `q.$multiple` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Allow deletion of multiple records by query
    -   `q.$errNotFound` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Raise an error if a specifically requested document is not found (requires $id)
-   `function`  (err,result)] Optional callback to call on completion or error

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.meta

Return information about a Mongo collection schema

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to process
    -   `q.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection / model to examine
    -   `q.$collectionEnums` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Provide all enums as a collection object instead of an array (optional, default `false`)
    -   `q.$filterPrivate` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Ignore all private fields (optional, default `true`)
    -   `q.$prototype` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Provide the $prototype meta object (optional, default `false`)
-   `function`  (err,result)] Optional callback to call on completion or error

**Examples**

```javascript
// Describe a collection
monoxide.meta({$collection: 'widgets'}, function(err, res) {
	console.log('About the widget collection:', res);
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.meta

Run an internal MongoDB command and fire an optional callback on the result

**Parameters**

-   `cmd` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The command to process
-   `function`  (err,result)] Optional callback to call on completion or error

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.queryBuilder

Returns data from a Monoxide model

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** 

## $mongoModel

The raw MongoDB-Core model

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)

## $mongooseModel

The raw Mongoose model

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)

## $oids

Holder for all OID information
This can either be the `._id` of the object, sub-documents, array pointers or object pointers

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)

## findOneById

Alias of findOneByID

## delete

Alias of remove()

## method

Add a method to a all documents returned from this model
A method is a user defined function which extends the `monoxide.monoxideDocument` prototype

**Parameters**

-   `name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The function name to add as a static method
-   `func` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The function to add as a static method

Returns **monoxide.monoxideModel** The chainable monoxideModel

## static

Add a static method to a model
A static is a user defined function which extends the `monoxide.monoxideModel` prototype

**Parameters**

-   `name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The function name to add as a static method
-   `func` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The function to add as a static method

Returns **monoxide.monoxideModel** The chainable monoxideModel

## virtual

Define a virtual (a handler when a property gets set or read)

**Parameters**

-   `name` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** The virtual name to apply or the full virtual object (must pretain to the Object.defineProperty descriptor)
-   `getCallback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The get function to call when the virtual value is read
-   `setCallback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The set function to call when the virtual value changes

Returns **monoxide.monoxideModel** The chainable monoxideModel

## hasVirtuals

Return whether a model has virtuals

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether any virtuals are present

## hook

Attach a hook to a model
A hook is exactly the same as a eventEmitter.on() event but must return a callback
Multiple hooks can be attached and all will be called in parallel on certain events such as 'save'
All hooks must return non-errors to proceed with the operation

**Parameters**

-   `eventName`  
-   `callback`  

Returns **monoxide.monoxideModel** The chainable monoxideModel

## hasHook

Return whether a model has a specific hook
If an array is passed the result is whether the model has none or all of the specified hooks

**Parameters**

-   `hooks` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) | null)** The hook(s) to query, if undefined or null this returns if any hooks are present

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether the hook(s) is present

## fire

Execute all hooks for an event
This function fires all hooks in parallel and expects all to resolve correctly via callback
NOTE: Hooks are always fired with the callback as the first argument

**Parameters**

-   `name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of the hook to invoke
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The callback to invoke on success
-   `parameters` **...any** Any other parameters to be passed to each hook

Returns **monoxide.monoxideModel** The chainable monoxideModel

## meta

Return the meta structure for a specific model

**Parameters**

-   `Options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** to return when computing the meta object. See the main meta() function for details
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The callback to call with (err, layout)

Returns **monoxide.monoxideModel** The chainable monoxideModel

## use

Run a third party plugin against a model
This function is really just a shorthand way to pass a Monoxide model into a function

**Parameters**

-   `plugin` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The plugin to run. This gets the arguments (model, callback)
-   `callback`  

Returns **monoxide.monoxideModel** The chainable monoxideModel

## distinct

Return an array of all distinct field values

**Parameters**

-   `field` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The field to return the values of
-   `plugin` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The plugin to run. This gets the arguments (values)
-   `callback`  

Returns **monoxide.monoxideModel** The chainable monoxideModel

## monoxide.monoxideModel.find

Shortcut function to create a monoxide.queryBuilder object and immediately start filtering
This also sets $count=true in the queryBuilder

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional filtering object
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** 

## monoxide.monoxideModel.find

Shortcut function to create a monoxide.queryBuilder object and immediately start filtering

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional filtering object
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** 

## monoxide.monoxideModel.findOne

Shortcut function to create a monoxide.queryBuilder object and immediately start filtering
This also sets $one=true in the queryBuilder

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional filtering object
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** 

## monoxide.monoxideModel.findOneByID

Shortcut function to create a monoxide.queryBuilder object and immediately start filtering
This also sets $id=q in the queryBuilder

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional filtering object
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback. If present this is the equivelent of calling exec()

Returns **[monoxide.queryBuilder](#monoxidequerybuilder)** 

## monoxide.monoxideModel.create

Shortcut function to create a new record within a collection

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional document contents
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback

Returns **monoxide.monoxideModel** The chainable monoxideModel

## monoxide.monoxideMode.update

Shortcut to invoke update on a given model

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The filter to query by
-   `qUpdate` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The object to update into the found documents
-   `function`  (err,result)] Optional callback to call on completion or error

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This chainable object

## monoxide.monoxideModel.remove

Shortcut function to remove a number of rows based on a query

**Parameters**

-   `q` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional filtering object
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback

Returns **monoxide** 

## monoxide.monoxideDocument

Returns a single instance of a Monoxide document

**Parameters**

-   `setup` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The prototype fields. Everything in this object is extended into the prototype
    -   `setup.$applySchema` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether to enforce the model schema on the object. This includes applying default values (optional, default `true`)
    -   `setup.$dirty` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether the entire document contents should be marked as dirty (modified). If true this also skips the computation of modified fields (optional, default `false`)
    -   `setup.$collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The collection this document belongs to
-   `data` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The initial data

Returns **[monoxide.monoxideDocument](#monoxidemonoxidedocument)** 

## save

Save a document
By default this function will only save back modfified data
If `data` is specified this is used as well as the modified fields (unless `data.$ignoreModified` is falsy, in which case modified fields are ignored)

**Parameters**

-   `data` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** An optional data patch to save
    -   `data.$ignoreModified` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Ignore all modified fields and only process save data being passed in the `data` object (use this to directly address what should be saved, ignoring everything else). Setting this drastically speeds up the save operation but at the cost of having to be specific as to what to save (optional, default `false`)
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** The callback to invoke on saving

## remove

Remove the document from the collection
This method is really just a thin wrapper around monoxide.delete()

**Parameters**

-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Optional callback to invoke on completion

## omit

Remove certain fields from the document object
This method is really just a thin wrapper around monoxide.delete()

**Parameters**

-   `fields` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [regexp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) \| [array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array))** Either a single field name, regular expression or array of strings/regexps to filter by. Any key matching will be removed from the object

Returns **[monoxide.monoxideDocument](#monoxidemonoxidedocument)** This object after the fields have been removed

## toObject

Transform a MonoxideDocument into a plain JavaScript object

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Plain JavaScript object with all special properties and other gunk removed

## toMongoObject

Transform a MonoxideDocument into a Mongo object
This function transforms all OID strings back into their Mongo equivalent

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Plain JavaScript object with all special properties and other gunk removed

## populate

Expand given paths into objects

**Parameters**

-   `populations` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** A single or multiple populations to perform
-   `callback` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The callback to run on completion
-   `strict` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether to raise errors and agressively retry if a population fails (optional, default `false`)

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** This document

## getNodesBySchemaPath

Retrieves all 'leaf' elements matching a schema path
Since any segment of the path could be a nested object, array or sub-document collection this function is likely to return multiple elements
For the nearest approximation of how this function operates think of it like performing the jQuery expression: `$('p').each(function() { ... })`

**Parameters**

-   `schemaPath` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The schema path to iterate down
-   `strict` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Optional indicator that an error should be thrown if a path cannot be traversed (optional, default `false`)

Returns **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of all found leaf nodes

## getOIDs

Return an array of all OID leaf nodes within the document
This function combines the behaviour of monoxide.utilities.extractFKs with monoxide.monoxideDocument.getNodesBySchemaPath)

Returns **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** An array of all leaf nodes

## monoxide.model

Return a defined Monoxide model
The model must have been previously defined by monoxide.schema()
This function is identical to accessing the model directly via `monoxide.models[modelName]`

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The model name (generally lowercase plurals e.g. 'users', 'widgets', 'favouriteItems' etc.)

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The monoxide model of the generated schema

## monoxide.schema

Construct and return a Mongo model
This function creates a valid schema specificaion then returns it as if model() were called

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The model name (generally lowercase plurals e.g. 'users', 'widgets', 'favouriteItems' etc.)
-   `spec` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The schema specification composed of a hierarhical object of keys with each value being the specification of that field

**Examples**

```javascript
// Example schema for a widget
var Widgets = monoxide.schema('widgets', {
	name: String,
	content: String,
	status: {type: String, enum: ['active', 'deleted'], default: 'active'},
	color: {type: String, enum: ['red', 'green', 'blue'], default: 'blue', index: true},
});
```

```javascript
// Example schema for a user
var Users = monoxide.schema('users', {
	name: String,
	role: {type: 'string', enum: ['user', 'admin'], default: 'user'},
	favourite: {type: 'pointer', ref: 'widgets'},
	items: [{type: 'pointer', ref: 'widgets'}],
	settings: {type: 'any'},
	mostPurchased: [
		{
			number: {type: 'number', default: 0},
			item: {type: 'pointer', ref: 'widgets'},
		}
	],
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The monoxide model of the generated schema


## monoxide.use

Calls a single or array of plugin functions which should mutate the main Monoxide modules behaviour.

```javascript
var myPlugin = (finish, monoxide) => {
	// Attach to each model and print to the conole when we are saving something
	_(monoxide.models)
		.forEach(model =>
			model.hook('save', (done, q) => console.log('Saving', q))
		)

	finish();
};

monoxide.use(myPlugin)

// Every subsequent save operation will now print to the console
```


## monoxide.register

Register a callback against an event being fired for any model.

```javascript
monoxide.register('create', function(done, q) {
	console.log('CREATE RECORD ON MODEL', this.$collection, q);
	done();
});
```


## monoxide.express.defaults

Set the default settings used when calling other monoxide.express.middleware functions
The provided settings will be merged with the existing defaults, so its possible to call this function multiple times to override previous invocations
NOTE: This will only effect functions called AFTER it was invoked.

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings

**Examples**

```javascript
// Enable saving globally
monoxide.express.defaults({save: true});
```

```javascript
// Add a middleware function to all delete operations (assuming the invidiual controllers dont override it)
monoxide.express.defaults({
	delete: function(req, res, next) {
		// Check the user is logged in - deny otherwise
		if (!req.user) return res.status(403).send('You are not logged in').end();
		next();
	},
});
```

Returns **monoxide** This chainable monoxide instance

## monoxide.express.middleware

Return an Express middleware binding

See monoxide.express.defaults() to change the default settings for this function globally

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to
    -   `settings.count` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow GET + Count functionality (optional, default `true`)
    -   `settings.get` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow single record retrieval by its ID via the GET method. If this is disabled an ID MUST be specified for any GET to be successful within req.params (optional, default `true`)
    -   `settings.query` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow record querying via the GET method (optional, default `true`)
    -   `settings.create` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow the creation of records via the POST method (optional, default `false`)
    -   `settings.save` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow saving of records via the POST method (optional, default `false`)
    -   `settings.delete` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow deleting of records via the DELETE method (optional, default `false`)
    -   `settings.meta` **([boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [monoxide.express.middlewareCallback](#monoxideexpressmiddlewarecallback))?** Allow retrival of meta information (optional, default `false`)

**Examples**

```javascript
// Bind an express method to serve widgets
app.use('/api/widgets/:id?', monoxide.express.middleware('widgets'));
```

```javascript
// Bind an express method to serve users but disallow counting and querying (i.e. direct ID access only)
app.use('/api/users/:id?', monoxide.express.middleware('users', {query: false, count: false}));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.get

Return an Express middleware binding for single record retrieval operations
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to
    -   `settings.queryRemaps` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Object of keys that should be translated from the incomming req.query into their Monoxide equivelents (e.g. `{populate: '$populate'`})
    -   `settings.queryAllowed` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Optional specification on what types of values should be permitted for query fields (keys can be: 'scalar', 'scalarCSV', 'array') (optional, default `Object`)
    -   `settings.omitFields` **([array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [regexp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp))?** Run all results though monoxideDocument.omit() before returning to remove the stated fields
    -   `settings.map` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Run the document though this map function before returning

**Examples**

```javascript
// Bind an express method to serve widgets
app.get('/api/widgets/:id?', monoxide.express.get('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.query

Return an Express middleware binding for multiple record retrieval operations
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to
    -   `settings.queryRemaps` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Object of keys that should be translated from the incomming req.query into their Monoxide equivelents (e.g. `{populate: '$populate'`}) (optional, default `Object`)
    -   `settings.queryAllowed` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Optional specification on what types of values should be permitted for query fields (keys can be: 'scalar', 'scalarCSV', 'array') (optional, default `Object`)
    -   `settings.shorthandArrays` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Remap simple arrays (e.g. `key=val1&key=val2` into `key:{$in:[val1,val2]}`) automatically (optional, default `true`)
    -   `settings.omitFields` **([array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [regexp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp))?** Run all results though monoxideDocument.omit() before returning to remove the stated fields
    -   `settings.map` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Run all documents though this map function before returning

**Examples**

```javascript
// Bind an express method to serve widgets
app.get('/api/widgets', monoxide.express.query('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.count

Return an Express middleware binding for GET operations - specifically for returning COUNTs of objects
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to

**Examples**

```javascript
// Bind an express method to count widgets
app.get('/api/widgets/count', monoxide.express.get('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.save

Return an Express middleware binding for POST/PATCH operations which update an existing record with new fields
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to

**Examples**

```javascript
// Bind an express method to save widgets
app.post('/api/widgets/:id', monoxide.express.save('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.create

Return an Express middleware binding for POST/PUT operations which create a new record
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to

**Examples**

```javascript
// Bind an express method to create widgets
app.post('/api/widgets', monoxide.express.create('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.delete

Return an Express middleware binding for DELETE operations
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to

**Examples**

```javascript
// Bind an express method to delete widgets
app.delete('/api/widgets/:id', monoxide.express.delete('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.meta

Return an Express middleware binding for meta information about a schema
Unless you have specific routing requirements its better to use monoxide.express.middleware() as a generic router

**Parameters**

-   `model` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to (this can also be specified as settings.collection)
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Middleware settings
    -   `settings.collection` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** The model name to bind to

**Examples**

```javascript
// Bind an express method provide meta information
app.delete('/api/widgets/meta', monoxide.express.meta('widgets'));
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** callback(req, res, next) Express compatible middleware function

## monoxide.express.middlewareCallback

Callback function for Express middleware
This callback applies to the monoxide.express.middleware() function for get, query, save, delete etc.

Type: [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)

**Parameters**

-   `req` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The request object
-   `res` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The response object
-   `next` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** The next callback chain (optional to call this or deal with `res` yourself)

**Examples**

```javascript
// Allow deleting of widgets only if 'force'===true
app.use('/api/widgets/:id?', monoxide.express.middleware('widgets', {
	delete: function(req, res, next) {
		// Only allow delete if the query contains 'force' as a string
		if (req.query.force && req.query.force === 'confirm') return next();
		return res.status(403).send('Nope!').end();
	},
}));
```

## monoxide.utilities.extractFKs

Extract all FKs in dotted path notation from a Mongoose model

**Parameters**

-   `schema` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The schema object to examine (usually monoxide.models[model].$mongooseModel.schema)
-   `prefix` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** existing Path prefix to use (internal use only)
-   `base` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Base object to append flat paths to (internal use only)

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** A dictionary of foreign keys for the schema (each key will be the info of the object)

## monoxide.utilities.objectID

Construct and return a MongoDB-Core compatible ObjectID object
This is mainly used within functions that need to convert a string ID into an object
This has one additional check which will return undefined if the value passed in is falsy

**Parameters**

-   `str` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The string to convert into an ObjectID

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** A MongoDB-Core compatible ObjectID object instance

## monoxide.utilities.isObjectID

Return if the input is a valid MongoDB-Core compatible ObjectID object
This is mainly used within functions that need to check that a given variable is a Mongo OID

**Parameters**

-   `subject` **mixed** The item to examine

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether the subject is a MongoDB-Core compatible ObjectID object instance

## monoxide.utilities.diff

Diff two monoxide.monoxideDocument objects and return the changes as an object
This change object is suitable for passing directly into monoxide.save()
While originally intended only for comparing monoxide.monoxideDocument objects this function can be used to compare any type of object
NOTE: If you are comparing MonoxideDocuments call `.toObject()` before passing the object in to strip it of its noise

**Parameters**

-   `originalDoc` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The original source document to compare to
-   `newDoc` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The new document with possible changes

**Examples**

```javascript
// Get the patch of two documents
monoxide.query({$collection: 'widgets', $id: '123'}, function(err, res) {
	var docA = res.toObject();
	var docB = res.toObject();

// Change some fields
	docB.title = 'Hello world';

	var patch = monoxide.utilities.diff(docA, docB);
	// => should only return {title: 'Hello World'}
});
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The patch object

## monoxide.utilities.rewriteQuery

Returns a rewritten version of an incomming query that obeys various rules
This usually accepts req.query as a parameter and a complex settings object as a secondary
This function is used internally by middleware functions to clean up the incomming query

**Parameters**

-   `query` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The user-provided query object
-   `settings` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The settings object to apply (see middleware functions)

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The rewritten query object