Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dimadeveatii/mongo-dot-notation
Transform objects to MongoDB update instructions
https://github.com/dimadeveatii/mongo-dot-notation
dot-notation mongo mongo-dot-notation mongo-operators mongodb
Last synced: 19 days ago
JSON representation
Transform objects to MongoDB update instructions
- Host: GitHub
- URL: https://github.com/dimadeveatii/mongo-dot-notation
- Owner: dimadeveatii
- License: mit
- Created: 2015-08-19T15:23:15.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2024-03-29T22:13:39.000Z (8 months ago)
- Last Synced: 2024-10-12T03:11:45.611Z (about 1 month ago)
- Topics: dot-notation, mongo, mongo-dot-notation, mongo-operators, mongodb
- Language: TypeScript
- Homepage:
- Size: 202 KB
- Stars: 46
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE-OF-CONDUCT.md
Awesome Lists containing this project
README
# mongo-dot-notation
Transform objects to MongoDB update instructions.
[](https://github.com/dimadeveatii/mongo-dot-notation/actions/workflows/ci.yml?query=branch%3Amain++)
[](https://coveralls.io/github/dimadeveatii/mongo-dot-notation?branch=main)
[](https://npmjs.org/package/mongo-dot-notation)
[](https://npmjs.org/package/mongo-dot-notation)
```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](https://www.mongodb.com/docs/manual/reference/operator/update/)
- 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
### Using operators to update fields
```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 });
```
### Flattening arrays
```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"
}
```
### Using positional operator
```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 } }
);
```
### Using filtered positional operator
```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 } }] }
);
```
### Merge array documents
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.
### Update nested arrays
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/mongo.e2e.ts) tests file for more examples.
## API
**Table of contents**
- [Options](#options)
- [flatten](#flatten)
- [isOperator](#isOperator)
- [Field update operators](#field-update-operators)
- [$currentDate](#currentdate)
- [$timestamp](#timestamp)
- [$inc](#inc)
- [$min](#min)
- [$max](#max)
- [$mul](#mul)
- [$rename](#rename)
- [$set](#set)
- [$setOnInsert](#setoninsert)
- [$unset](#unset)
- [Array update operators](#array-update-operators)
- [$](#-positional)
- [$addToSet](#addtoset)
- [$pop](#pop)
- [$pull](#pull)
- [$push](#push)
- [$pullAll](#pullall)
- [$slice](#slice)
- [$sort](#sort)
- [Bitwise update operators](#bitwise-update-operators)
- [$bit](#bit)
- [$and](#and)
- [$or](#or)
- [$xor](#xor)
### Options
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': {} } }
```
### flatten
> `$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](#options) |
**Example:**
```ts
flatten({
firstName: 'Alice',
contact: { phone: '874-478-1254' },
address: {
primary: {
state: 'NY',
nr: 42,
},
},
});
```
### isOperator
> `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
```
---
### Field update operators
### $currentDate
> `$currentDate(type?: 'date' | 'timestamp')`
| Param | Description |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | _(default `date`)_ sets to MongoDB's [Date](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-document-bson-type-date) or [Timestamp](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-document-bson-type-timestamp) type. |
Sets the value of a field to the current date.
**Example:**
```ts
flatten({
createdOn: $currentDate(),
});
```
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/currentDate/)
### $timestamp
> `$timestamp()`
Sets the value of a field to the current date as a MondoDB's [Timestamp](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-document-bson-type-timestamp) type.
This function is an alias for `$currentDate('timestamp')`.
**Example:**
```ts
flatten({
updatedOn: $timestamp(),
});
```
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/currentDate/)
### $inc
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/inc/)
### $min
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/min/)
### $max
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/max/)
### $mul
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/max/)
### $rename
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/rename/)
### $set
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/set/)
### $setOnInsert
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/setOnInsert/)
### $unset
> `$unset()`
Deletes the specified field from a document.
**Example:**
```ts
flatten({
resetPassword: $unset(),
});
```
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/unset/)
---
### Array update operators
### $ _(positional)_
> `$(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](#update-nested-arrays) for examples using `$().merge`.
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/positional/)
### $addToSet
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/addToSet/)
### $pop
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/pop/)
### $pull
> `$pull(value: T | T[])`
Removes from an existing array all instances of a value or values that match a specified condition.
Unlike the [$pullAll](#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](https://www.mongodb.com/docs/manual/reference/operator/update/pull/)
### $push
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/push/)
### $pullAll
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/pullAll/)
### $slice
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/slice/)
### $sort
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/sort/)
---
### Bitwise update operators
### $bit
> `$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](https://www.mongodb.com/docs/manual/reference/operator/update/bit/)
### $and
> `$and(value: T)`
Uses a bitwise _and_ operation to update a field.
Alias for `$bit().$and()`.
**Example:**
```ts
flatten({
admin: $and(7),
});
```
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/bit/#bitwise-and)
### $or
> `$or(value: T)`
Uses a bitwise _or_ operation to update a field.
Alias for `$bit().$or()`.
**Example:**
```ts
flatten({
read: $or(4),
});
```
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/bit/#bitwise-or)
### $xor
> `$xor(value: T)`
Uses a bitwise _xor_ operation to update a field.
Alias for `$bit().$xor()`.
**Example:**
```ts
flatten({
write: $xor(3),
});
```
[MongoDB manual](https://www.mongodb.com/docs/manual/reference/operator/update/bit/#bitwise-xor)
## License
[MIT](LICENSE)