mongo-dot-notation

Transform objects to MongoDB update instructions.


``ts
import { flatten, $timestamp, $unset } from 'mongo-dot-notation';

const user = flatten({
firstName: 'Alice',
contact: { phone: '874-478-1254' },
address: {
primary: {
state: 'NY',
nr: 42,
},
},
});
`

Sets user to:

`json
{
"$set": {
"firstName": "Alice",
"contact.phone": "874-478-1254",
"address.primary.state": "NY",
"address.primary.nr": 42
}
}
`

Installation

`sh
npm install mongo-dot-notation
`

Highlights

- Supports all MongoDB update operators
- Field update operators
- Array update operators
- Bitwise update operators
- No npm dependency on mongo
- Written in TypeScript
- Type definitions for all exported functions
- Supports flattening and updating array elements by index

Usage and examples

$3

`ts
import { flatten, $inc, $currentDate, $push, $setOnInsert } from 'mongo-dot-notation';

const review = {
// Add a comment and keep only the last ten ones
comments: $push('Like it!').$each().$slice(-10),
rating: 10,
counters: {
// increment the total by one
total: $inc(),
},
details: {
// set only if the document is inserted
createdOn: $setOnInsert(new Date()),
// set to current date as a mongo Date
updatedOn: $currentDate(),
},
};

// Provided reviews is a MongoDB collection
await reviews.updateOne(reviewId, flatten(review), { upsert: true });
`

$3

`ts
import { flatten } from 'mongo-dot-notation';

const user = {
phones: [
{
number: '123-456-789',
primary: true,
},
{
number: '789-012-345',
},
],
};

// Provided users is a MongoDB collection
await users.updateOne(userId, flatten(user, { array: true }));
`

The above user object is flattened to:

`json
{
"phones.0.number": "123-456-789",
"phones.0.primary": true,
"phones.1.number": "789-012-345"
}
`

$3

`ts
import { flatten, $, $inc } from 'mongo-dot-notation';

const student = {
grades: $().$inc(),
};

// Finds the element with value 80 in the "grades" array
// and increments it by one.
student.updateOne(
{ _id: 1, grades: 80 },
flatten(student) // { $inc: { "grades.$" : 1 } }
);
`

The position operator supports updating a nested document:

`ts
import { flatten, $, $inc } from 'mongo-dot-notation';

const student = {
grades: $('value').$inc(),
};

// Finds the document with "value" field equal to 80 in the "grades" array
// and increments it by one.
student.updateOne(
{ _id: 1, grades: 80 },
flatten(student) // { $inc: { "grades.$.value" : 1 } }
);
`

To update all elements in a array, use _all positional_ operator:

`ts
import { flatten, $, $inc } from 'mongo-dot-notation';

const student = {
grades: $('[]').$inc(),
};

// Increment all grades by one
student.updateOne(
{ _id: 1 },
flatten(student) // { $inc: { "grades.$[]" : 1 } }
);
`

Similarly, updating nested documents:

`ts
import { flatten, $, $inc } from 'mongo-dot-notation';

const student = {
grades: $('[].values').$inc(),
};

// Increment all grades' values by one
student.updateOne(
{ _id: 1 },
flatten(student) // { $inc: { "grades.$[].values" : 1 } }
);
`

$3

`ts
import { flatten, $, $mul } from 'mongo-dot-notation';

const student = {
grades: $('[element]').$mul(9),
};

// Multiply by ten all grades that are below 9
student.updateOne(
{ _id: 1 },
flatten(student), // { $mul: { "grades.$[element]" : 10 } }
{ arrayFilters: [{ element: { $lte: 9 } }] }
);
`

Similarly, updating nested documents:

`ts
import { flatten, $, $mul } from 'mongo-dot-notation';

const student = {
grades: $('[element].value').$mul(9),
};

// Multiply by ten all grades that are below 9
student.updateOne(
{ _id: 1 },
flatten(student), // { $mul: { "grades.$[element].value" : 10 } }
{ arrayFilters: [{ 'element.value': { $lte: 9 } }] }
);
`

$3

Using positional operator to merge fields into the matched element:

`ts
import { flatten, $, $inc, $currentDate } from 'mongo-dot-notation';

const student = {
grades: $().merge({
class: '101',
prof: 'Alice',
value: $inc(),
date: $currentDate(),
}),
};

flatten(student);
`

Result:

`json
{
"$set": {
"grades.$.class": "101",
"grades.$.prof": "Alice"
},
"$inc": {
"grades.$.value": 1
},
"$currentDate": {
"grades.$.date": { "$type": "date" }
}
}
`

To update all elements, use $('[]') instead of $() in the above example.

$3

Using positional operator to update nested arrays:

`ts
import { flatten, $, $mul } from 'mongo-dot-notation';

const student = {
grades: $().merge({
questions: $('[]').merge({
value: $mul(100),
}),
}),
};

flatten(student);
`

Calling flatten(student) results in:

`json
{
"$mul": {
"grades.$.questions.$[].value": 100
}
}
`

See the end-to-end tests file for more examples.

API

Table of contents

- Options
- flatten
- isOperator

- Field update operators

- $currentDate
- $timestamp
- $inc
- $min
- $max
- $mul
- $rename
- $set
- $setOnInsert
- $unset

- Array update operators

- $
- $addToSet
- $pop
- $pull
- $push
- $pullAll
- $slice
- $sort

- Bitwise update operators

- $bit
- $and
- $or
- $xor

$3

The following options are available:

| Option | Description |
| ------------------ | --------------------------------------------------------------------------------------------- |
| array | _(default false)_ if true, arrays will be flattened and their indexes will be used as keys. |
| skipEmptyObjects | _(default false)_ if true, empty objects are ignored and removed from the flattened result. |

Example:

`ts
flatten({ rules: [{ value: 7 }] }, { array: true });
// { $set: { 'rules.0.value': 7 } }

flatten({ rules: [{ value: 7 }] }, { array: false });
// { $set: { 'rules': [{value: 7}] } }

flatten({ left: { x: 1 }, right: {} }, { skipEmptyObjects: true });
// { $set: { 'left.x': 1 } }

flatten({ left: { x: 1 }, right: {} }, { skipEmptyObjects: false });
// { $set: { 'left.x': 1, 'right': {} } }
`

$3

> $flatten(obj: T, options?: Options)

Transforms a given object into the MongoDB's update instructions.

| Param | Description |
| --------- | -------------------------------------------------------- |
| obj | _(required)_ the input object to transform |
| options | _(optional)_ additional options, see Options |

Example:

`ts
flatten({
firstName: 'Alice',
contact: { phone: '874-478-1254' },
address: {
primary: {
state: 'NY',
nr: 42,
},
},
});
`

$3

> isOperator(obj: T): boolean

Checks if a given object is an operator.

| Param | Description |
| ----- | -------------------------------------- |
| obj | _(required)_ the input object to check |

Example:

`ts
isOperator($set(1)); // true
isOperator({}); // false
`

---

$3

$3

> $currentDate(type?: 'date' | 'timestamp')

| Param | Description |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | _(default date)_ sets to MongoDB's Date or Timestamp type. |

Sets the value of a field to the current date.

Example:

`ts
flatten({
createdOn: $currentDate(),
});
`

MongoDB manual

$3

> $timestamp()

Sets the value of a field to the current date as a MondoDB's Timestamp type.

This function is an alias for $currentDate('timestamp').

Example:

`ts
flatten({
updatedOn: $timestamp(),
});
`

MongoDB manual

$3

> $inc(value?: T)

Increments a field by a specified value.

| Param | Description |
| ------- | ----------------------------- |
| value | _(default 1)_ increment value |

Example:

`ts
flatten({
visits: $inc(),
clicks: $inc(5),
});
`

MongoDB manual

$3

> $min(value: T)

Updates the value of the field to a specified value if the specified value is less than the current value of the field.

| Param | Description |
| ------- | ---------------------- |
| value | _(required)_ min value |

Example:

`ts
flatten({
score: $min(100),
});
`

MongoDB manual

$3

> $max(value: T)

Updates the value of the field to a specified value if the specified value is greater than the current value of the field.

| Param | Description |
| ------- | ---------------------- |
| value | _(required)_ max value |

Example:

`ts
flatten({
score: $max(0),
});
`

MongoDB manual

$3

> $mul(value?: T)

Multiplies the value of a field by a number.

| Param | Description |
| ------- | ----------------------------- |
| value | _(default 1)_ multiply factor |

Example:

`ts
flatten({
score: $mul(2.5),
});
`

MongoDB manual

$3

> $rename(field: string)

Updates the name of a field.

| Param | Description |
| ------- | --------------------------- |
| field | _(required)_ new field name |

Example:

`ts
flatten({
profile: {
first_name: $rename('firstName'),
},
});
`

MongoDB manual

$3

> $set(value: T)

Replaces the value of a field with the specified value.
This is an implicit operator, but could be useful when an entire object should be replaced.

| Param | Description |
| ------- | ------------------------------ |
| value | _(required)_ replacement value |

Example:

`ts
// Replaces the address object entirely rather than just
// updating the "city" field.
flatten({
address: $set({ city: 'NY' }),
profile: { name: 'Alice' },
});

// Outputs:
// {
// "$set": {
// "address": { "city": "NY" },
// "profile.name": "Alice"
// }
// }
`

MongoDB manual

$3

> $setOnInsert(value: T)

Assigns the specified value to the field when { upsert: true } operation is used and
results in a new document being created. If the update operation does not result in an insert,
does nothing.

| Param | Description |
| ------- | -------------------------------------------------- |
| value | _(required)_ the value to set on document creation |

Example:

`ts
flatten({
logging: {
createdOn: $setOnInsert(new Date()),
},
});
`

MongoDB manual

$3

> $unset()

Deletes the specified field from a document.

Example:

`ts
flatten({
resetPassword: $unset(),
});
`

MongoDB manual

---

$3

$3

> $(field?: number | string)

The positional operator identifies an element or multiple elements matching a
given query condition to be updated in an array.

| Param | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| field | _(optional)_ when empty - performs the update on array's element;
when a number or a string starting with a number, specifies the index of the element to update or its field;
when starts with "[]" or "[query]", specifies that this is an _all positional_ operator; |

Example:

`ts
// Sets to 7 first element that matches the update query
$().$set(7);

// Increment by one the first element's score field that matches the update query
$('score').$inc(1);

// Multiplies all elements by two
$('[]').$mul(2);

// Ensures all elements in array are positive
$('[].score').$max(0);

// Find all grades documents that have the std lower than seven
// and increment their grade by ten.
collection.updateOne(criteria, flatten({ grades: $('[element].grade').$inc(10) }), {
arrayFilters: [{ 'element.std': { $lt: 7 } }],
});
`

See update nested arrays for examples using $().merge.

MongoDB manual

$3

> $addToSet(value: T | T[])

Adds a value to an array unless the value is already present.
To add multiple values, chain with $each operator.

| Param | Description |
| ------- | ---------------------------------------- |
| value | _(required)_ the value to add to the set |

Note that while $addToSet([1, 2]) adds the entire array as single element,
$addToSet([1, 2]).$each() adds 1 and 2 as separate elements.

Example:

`ts
// add just one element
flatten({ permissions: $addToSet('admin') });

// add multiple elements
flatten({ permissions: $addToSet(['read', 'write']).$each() });
`

MongoDB manual

$3

> $pop(value?: -1 | 1)

Removes the first or last element of an array

| Param | Description |
| ------- | -------------------------------------------------------------------------------------- |
| value | _(default 1)_ specify -1 to remove the first element, 1 to remove the last element |

Example:

`ts
// remove the first element from the array
flatten({ grades: $pop(-1) });
// equivalent to:
flatten({ grades: $pop().first() });

// remove the last element from the array
flatten({ scores: $pop(1) });
// equivalent to:
flatten({ scores: $pop().last() });
`

MongoDB manual

$3

> $pull(value: T | T[])

Removes from an existing array all instances of a value or values that match a specified condition.
Unlike the $pullAll operator, this operator can be used to remove all instances that match a query.

| Param | Description |
| ------- | ---------------------------------------------------------------------------------- |
| value | _(required)_ the value(s) to remove or the condition to match for removed elements |

Example:

`ts
// remove all instances of the value 0 and 1 from the array;
// same as using $pullAll
flatten({ scores: $pull([0, 1]) });

// remove all instances lower than or equal to 3
flatten({ scores: $pull({ $lte: 3 }) });

// remove all documents with the field name equal to Test
flatten({ users: $pull({ name: { $eq: 'Test' } }) });
`

MongoDB manual

$3

> $push(value?: T | T[])

Appends a specified value to an array.
Can be chained with .$slice(), .$sort() and .$position() modifiers to specify how the array should be updated.
The order in which additional operators are chained doesn't matter, so that $push().$each().$slice().$sort() is the same as
$push().$each().$sort().$slice().

| Param | Description |
| ------- | ------------------------------------------------ |
| value | _(optional)_ the value(s) to append to the array |

Example:

`ts
// append one element
flatten({ scores: $push(1) });

// append multiple elements
flatten({ scores: $push([1, 2, 3]).$each() });

// append an element and update to leave only the last ten
flatten({ scores: $push(7).$each().$slice(-10) });

// append an element and update to leave only the last ten sorted by value
flatten({ scores: $push(7).$each().$sort(1).$slice(-10) });

// append an element at position three in the array
flatten({ scores: $push(7).$each().$position(2) });
`

MongoDB manual

$3

> $pullAll(value: T | T[])

Removes all instances of the specified values from an existing array.

| Param | Description |
| ------- | -------------------------------------------------- |
| value | _(required)_ the value(s) to remove from the array |

Example:

`ts
// remove all instances of the value 1 and 2 from the array
flatten({ score: $pullAll([1, 2]) });

// remove all instances of the value 0
flatten({ score: $pullAll(0) });
`

MongoDB manual

$3

> $slice(count: number)

Limits the number of array elements.
Alias for $push().$each().$slice().

| Param | Description |
| ------- | --------------------------------------- |
| count | _(required)_ number of elements to take |

Example:

`ts
// leave only the first 3 elements
flatten({ grades: $slice(3) });

// leave only the last element
flatten({ grades: $slice(-1) });

// empty the array
flatten({ grades: $slice(0) });
`

MongoDB manual

$3

> $sort(specification?: T)

Orders the elements of an array.
Alias for $push().$each().$sort().

| Param | Description |
| --------------- | -------------------------------- |
| specification | _(default 1)_ sort specification |

Example:

`ts
// sort ascending
flatten({ scores: $sort(1) });

// sort descending
flatten({ scores: $sort(-1) });

// sort ascending an array of documents with name field
flatten({ users: $sort({ name: 1 }) });
`

MongoDB manual

---

$3

$3

> $bit()

Performs a bitwise update of a field.
Should be chained with a logical operator.

Example:

`ts
flatten({
admin: $bit().$and(7),
read: $bit().$or(4),
write: $bit().$xor(3),
});
`

MongoDB manual

$3

> $and(value: T)

Uses a bitwise _and_ operation to update a field.
Alias for $bit().$and().

Example:

`ts
flatten({
admin: $and(7),
});
`

MongoDB manual

$3

> $or(value: T)

Uses a bitwise _or_ operation to update a field.
Alias for $bit().$or().

Example:

`ts
flatten({
read: $or(4),
});
`

MongoDB manual

$3

> $xor(value: T)

Uses a bitwise _xor_ operation to update a field.
Alias for $bit().$xor().

Example:

`ts
flatten({
write: $xor(3),
});
``

MongoDB manual

License

MIT