@bedrockio/model 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.16.0
+
+- Added `upsert` method.
+
 ## 0.15.0
 
 - Tagged outer includes schema.

package/README.md

@@ -931,6 +931,20 @@ caller does not need to know whether the path contains subdocuments or foreign
 references. As Bedrock has knowledge of the schemas, it is able to build the
 appropriate call to `populate` for you.
 
+#### Include Syntax
+
+| Example           | Type      | Populated | Description                                          |
+| ----------------- | --------- | --------- | ---------------------------------------------------- |
+| `shop`            | Inclusive | shop      | Populates top level document.                        |
+| `shop.user`       | Inclusive | shop/user | Populates two levels deep.                           |
+| `^name`           | Exclusive |           | Selects only `name`.                                 |
+| `^shop.name`      | Exclusive | shop      | Selects only `shop.name`.                            |
+| `^shop.user.name` | Exclusive | shop/user | Selects only `shop.user.name`.                       |
+| `shop.^user.name` | Exclusive | shop/user | Selects root fields and `shop.user.name`.            |
+| `shop.user.^name` | Exclusive | shop/user | Selects root and `shop` fields and `shop.user.name`. |
+| `*Name`           | Wildcard  |           | Matches any root field ending with `Name`.           |
+| `**Name`          | Wildcard  |           | Matches any root or nested field ending with `Name`. |
+
 #### Exclusive Fields
 
 By default, arguments to `include` are for population. However often field
@@ -1650,35 +1664,52 @@ string, both of which would be stored in the database if naively assigned with
 
 ### Upsert
 
-This module adds a single `findOrCreate` convenience method that is easy to
-understand and avoids some of the gotchas that come with upserting documents in
-Mongoose:
+This module adds two similar methods:
+
+- `upsert`
+- `findOrCreate`
+
+The `upsert` method is used when documents must always be overwritten with the
+latest data.
 
 ```js
-const shop = await Shop.findOrCreate({
-  name: 'My Shop',
-});
+const shop = await Shop.upsert(
+  {
+    name: 'My Shop',
+  },
+  {
+    name: 'My Shop',
+    slug: 'my-shop',
+  },
+);
+
+// This is equivalent to:
 
-// This is equivalent to running:
 let shop = await Shop.findOne({
   name: 'My Shop',
 });
 
-if (!shop) {
+if (shop) {
+  shop.assign({
+    name: 'My Shop',
+    slug: 'my-shop',
+  });
+  await shop.save();
+} else {
   shop = await Shop.create({
     name: 'My Shop',
+    slug: 'my-shop',
   });
 }
 ```
 
-In most cases not all of the fields should be queried on to determine if an
-existing document exists. In this case two arguments should be passed the first
-of which is the query:
+The `findOrCreate` method does just whan the name implies and will return the
+document it finds without modifying it.
 
 ```js
 const shop = await Shop.findOrCreate(
   {
-    slug: 'my-shop',
+    name: 'My Shop',
   },
   {
     name: 'My Shop',
@@ -1686,9 +1717,10 @@ const shop = await Shop.findOrCreate(
   },
 );
 
-// This is equivalent to running:
+// This is equivalent to:
+
 let shop = await Shop.findOne({
-  slug: 'my-shop',
+  name: 'My Shop',
 });
 
 if (!shop) {
@@ -1699,6 +1731,27 @@ if (!shop) {
 }
 ```
 
+Note that a single argument can also be passed as a shortcut to both the query
+and the update for simple cases:
+
+```js
+const shop = await Shop.findOrCreate({
+  name: 'My Shop',
+});
+
+// This is equivalent to:
+
+let shop = await Shop.findOne({
+  name: 'My Shop',
+});
+
+if (!shop) {
+  shop = await Shop.create({
+    name: 'My Shop',
+  });
+}
+```
+
 ### Clone
 
 Adds a single `clone` method on documents. This is an async method mostly for

package/dist/cjs/upsert.js

@@ -5,11 +5,22 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.applyUpsert = applyUpsert;
 function applyUpsert(schema) {
-  // Note: Intentionally avoiding the findOneAndUpdate approach here
-  // as this will prevent hooks from being run on the document. This
-  // means however that we cannot always return a query here as the
-  // operations are inherently different.
+  // Note: Avoiding the findOneAndUpdate approach here as this
+  // will prevent hooks from being run on the document. This
+  // means however that we cannot always return a query here
+  // as the operations are inherently different.
 
+  schema.static('upsert', async function upsert(query, fields) {
+    fields ||= query;
+    let doc = await this.findOne(query);
+    if (doc) {
+      doc.assign(fields);
+      await doc.save();
+    } else {
+      doc = await this.create(fields);
+    }
+    return doc;
+  });
   schema.static('findOrCreate', async function findOrCreate(query, fields) {
     fields ||= query;
     let doc = await this.findOne(query);

package/dist/cjs/validation-schemas.js

@@ -70,6 +70,6 @@ An object with an \`id\` field may also be passed, which will be converted into
 const INCLUDE_FIELD_SCHEMA = exports.INCLUDE_FIELD_SCHEMA = _yada.default.object({
   include: _yada.default.allow(_yada.default.string(), _yada.default.array(_yada.default.string())).tag({
     'x-schema': 'Includes',
-    'x-description': 'A `string` or `array` of fields to be selected or populated using [includes syntax](http://bit.ly/4q2viXl).'
+    'x-description': 'A `string` or `array` of fields to be selected or populated using [includes syntax](https://bit.ly/4mZwSq4).'
   })
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrockio/model",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Bedrock utilities for model creation.",
   "type": "module",
   "scripts": {

package/src/upsert.js

@@ -1,8 +1,23 @@
 export function applyUpsert(schema) {
-  // Note: Intentionally avoiding the findOneAndUpdate approach here
-  // as this will prevent hooks from being run on the document. This
-  // means however that we cannot always return a query here as the
-  // operations are inherently different.
+  // Note: Avoiding the findOneAndUpdate approach here as this
+  // will prevent hooks from being run on the document. This
+  // means however that we cannot always return a query here
+  // as the operations are inherently different.
+
+  schema.static('upsert', async function upsert(query, fields) {
+    fields ||= query;
+
+    let doc = await this.findOne(query);
+
+    if (doc) {
+      doc.assign(fields);
+      await doc.save();
+    } else {
+      doc = await this.create(fields);
+    }
+
+    return doc;
+  });
 
   schema.static('findOrCreate', async function findOrCreate(query, fields) {
     fields ||= query;

package/src/validation-schemas.js

@@ -105,6 +105,6 @@ export const INCLUDE_FIELD_SCHEMA = yd.object({
   include: yd.allow(yd.string(), yd.array(yd.string())).tag({
     'x-schema': 'Includes',
     'x-description':
-      'A `string` or `array` of fields to be selected or populated using [includes syntax](http://bit.ly/4q2viXl).',
+      'A `string` or `array` of fields to be selected or populated using [includes syntax](https://bit.ly/4mZwSq4).',
   }),
 });

package/types/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../src/upsert.js"],"names":[],"mappings":"AAAA,+CAiBC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../src/upsert.js"],"names":[],"mappings":"AAAA,+CAgCC"}

package/types/validation-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-schemas.d.ts","sourceRoot":"","sources":["../src/validation-schemas.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAwFsB,CAAC;;;;;;;;;;;;;;;;;;;EAxFmC;AAE1D;;;;;;;;;;;;;;;;eAyBwB,CAAC;;;;;;;;;;;;iBAuBjB,CAAA;kBAA4B,CAAC;kBAEjC,CAAF;oBAEI,CAAC;oBAEI,CAAC;;;wBA2BC,CAAC;8BAGI,CAAC;oBAA+B,CAAC;oBAE1C,CAAC;oCAEL,CAAC;uBAAkC,CAAC;8BAAyC,CAAC;uBACzD,CAAC;iBAA4B,CAAC;;;mBAW2D,CAAC;yBAAoC,CAAC;0BAAqC,CAAC;yBAAoC,CAAC;sBAAiC,CAAC;yBAAoC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdrR,CAAC;;;;;;;;;;;;;;;;;;;EA9ElB;AAEL;;;;;;;;;;;;kBA0Fob,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdlgB,CAAC;;;;;;;;;;;;;;;;;EAlElB;AAEL;;;;;;;;;;;;kBA8Eob,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdlgB,CAAC;;;;;;;;;;;;;;;;;EAtDlB;AAEL;;;;;;;;;;;;kBAkEob,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdlgB,CAAC;;;;;;;;;;;;;;;;;EAlBlB;AAEL,8EAqBK;AAEL;;;;;;;;;;;;kBAOob,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdlgB,CAAC;;;;;;;;;;;;;;;;;EAapB"}
+{"version":3,"file":"validation-schemas.d.ts","sourceRoot":"","sources":["../src/validation-schemas.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAwFsB,CAAC;;;;;;;;;;;;;;;;;;;EAxFmC;AAE1D;;;;;;;;;;;;;;;;eAyBwB,CAAC;;;;;;;;;;;;iBAuBjB,CAAA;kBAA4B,CAAC;kBAEjC,CAAF;oBAEI,CAAC;oBAEI,CAAC;;;wBA2BC,CAAC;8BAGI,CAAC;oBAA+B,CAAC;oBAE1C,CAAC;oCAEL,CAAC;uBAAkC,CAAC;8BAAyC,CAAC;uBACzD,CAAC;iBAA4B,CAAC;;;mBAW0D,CAAC;yBAAoC,CAAC;0BAAqC,CAAC;yBAAoC,CAAC;sBAAiC,CAAC;yBAAoC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdpR,CAAC;;;;;;;;;;;;;;;;;;;EA9ElB;AAEL;;;;;;;;;;;;kBA0Fmb,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdjgB,CAAC;;;;;;;;;;;;;;;;;EAlElB;AAEL;;;;;;;;;;;;kBA8Emb,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdjgB,CAAC;;;;;;;;;;;;;;;;;EAtDlB;AAEL;;;;;;;;;;;;kBAkEmb,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdjgB,CAAC;;;;;;;;;;;;;;;;;EAlBlB;AAEL,8EAqBK;AAEL;;;;;;;;;;;;kBAOmb,CAAC;oBAA+B,CAAC;qBAAgC,CAAC;sBAAiC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAdjgB,CAAC;;;;;;;;;;;;;;;;;EAapB"}