@bedrockio/model 0.6.0 → 0.7.0

package/README.md

@@ -19,6 +19,7 @@ Bedrock utilities for model creation.
   - [Delete Hooks](#delete-hooks)
   - [Access Control](#access-control)
   - [Assign](#assign)
+  - [Upsert](#upsert)
   - [Slugs](#slugs)
 - [Testing](#testing)
 - [Troubleshooting](#troubleshooting)
@@ -568,11 +569,55 @@ will be flattened to:
 }
 ```
 
+#### Searching Arrays
+
+Passing an array to `search` will perform a query using `$in`, which matches on
+the intersection of any elements. For example,
+
+```json
+tags: ["one", "two"]
+```
+
+is effectively saying "match any documents whose `tags` array contains any of
+`one` or `two`".
+
+For this reason, passing an empty array here is ambiguous as it could be asking:
+
+- Match any documents whose `tags` array is empty.
+- Match any documents whose `tags` array contains any of `[]` (ie. no elements
+  passed so no match).
+
+The difference here is subtle, but for example in a UI field where tags can be
+chosen but none happen to be selected, it would be unexpected to return
+documents simply because their `tags` array happens to be empty.
+
+The `search` method takes the simpler approach here where an empty array will
+simply be passed along to `$in`, which will never result in a match.
+
+However, as a special case, `null` may instead be passed to `search` for array
+fields to explicitly search for empty arrays:
+
+```js
+await User.search({
+  tags: null,
+});
+// Equivalent to:
+await User.find({
+  tags: [],
+});
+```
+
+This works because Mongoose will always initialize an array field in its
+documents (ie. the field is always guarnateed to exist and be an array), so an
+empty array can be thought of as equivalent to `{ $exists: false }` for array
+fields. Thinking of it this way makes it more intuitive that `null` should
+match.
+
 #### Range Based Search
 
 Additionally, date and number fields allow range queries in the form:
 
-```
+```json
 age: {
   gt: 1
   lt: 2
@@ -653,7 +698,57 @@ schema.pre('save', function () {
 });
 ```
 
-##### Syncing Cache Fields
+#### Syncing Cached Fields
+
+When a foreign document is updated the cached fields will be out of sync, for
+example:
+
+```js
+await shop.save();
+console.log(shop.userName);
+// The current user name
+
+user.name = 'New Name';
+await user.save();
+
+shop = await Shop.findById(shop.id);
+console.log(shop.userName);
+// Cached userName is out of sync as the user has been updated
+```
+
+A simple mechanism is provided via the `sync` key to keep the documents in sync:
+
+```jsonc
+// In user.json
+{
+  "attributes": {
+    "name": "String"
+  },
+  "search": {
+    "sync": [
+      {
+        "ref": "Shop",
+        "path": "user"
+      }
+    ]
+  }
+}
+```
+
+This is the equivalent of running the following in a post save hook:
+
+```js
+const shops = await Shop.find({
+  user: user.id,
+});
+for (let shop of shops) {
+  await shop.save();
+}
+```
+
+This will run the hooks on each shop, synchronizing the cached fields.
+
+##### Initial Sync
 
 When first applying or making changes to defined cached search fields, existing
 documents will be out of sync. The static method `syncCacheFields` is provided
@@ -1490,6 +1585,12 @@ provided as `undefined` cannot be represented in JSON which requires using
 either a `null` or empty string, both of which would be stored in the database
 if naively assigned with `Object.assign`.
 
+### 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.
+
 ### Slugs
 
 A common requirement is to allow slugs on documents to serve as ids for human

package/dist/cjs/search.js

@@ -237,6 +237,8 @@ function normalizeQuery(query, schema, root = {}, rootPath = []) {
       root[path.join('.')] = {
         $in: value
       };
+    } else if (isEmptyArrayQuery(schema, key, value)) {
+      root[path.join('.')] = [];
     } else {
       root[path.join('.')] = value;
     }
@@ -256,12 +258,15 @@ function isNestedQuery(key, value) {
 function isArrayQuery(key, value) {
   return !isMongoOperator(key) && !isInclude(key) && Array.isArray(value);
 }
+function isEmptyArrayQuery(schema, key, value) {
+  return !isMongoOperator(key) && (0, _utils.isArrayField)(schema, key) && value === null;
+}
 function isRangeQuery(schema, key, value) {
   // Range queries only allowed on Date and Number fields.
   if (!(0, _utils.isDateField)(schema, key) && !(0, _utils.isNumberField)(schema, key)) {
     return false;
   }
-  return typeof value === 'object';
+  return typeof value === 'object' && !!value;
 }
 function mapOperatorQuery(obj) {
   const query = {};
@@ -323,9 +328,7 @@ function applySearchCache(schema, definition) {
     if (!force) {
       const $or = Object.keys(cache).map(cachedField => {
         return {
-          [cachedField]: {
-            $exists: false
-          }
+          [cachedField]: null
         };
       });
       query.$or = $or;

package/dist/cjs/utils.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.getField = getField;
 exports.getInnerField = getInnerField;
+exports.isArrayField = isArrayField;
 exports.isDateField = isDateField;
 exports.isEqual = isEqual;
 exports.isMongooseSchema = isMongooseSchema;
@@ -44,6 +45,10 @@ function isDateField(obj, path) {
 function isNumberField(obj, path) {
   return isType(obj, path, 'Number');
 }
+function isArrayField(obj, path) {
+  const field = getField(obj, path);
+  return Array.isArray(field?.type);
+}
 function isType(obj, path, test) {
   const {
     type

package/dist/cjs/validation.js

@@ -137,6 +137,7 @@ function applyValidation(schema, definition) {
     } = options;
     return getSchemaFromMongoose(schema, {
       model: this,
+      allowNull: true,
       allowSearch: true,
       skipRequired: true,
       allowInclude: true,
@@ -284,9 +285,11 @@ function getSchemaForTypedef(typedef, options = {}) {
   } else {
     schema = getSchemaForType(type, options);
 
-    // Unsetting only allowed for primitive types.
+    // Only allowed for primitive types.
     if (allowUnset(typedef, options)) {
-      schema = _yada.default.allow(null, '', schema);
+      schema = _yada.default.allow(schema, '').nullable();
+    } else if (allowNull(typedef, options)) {
+      schema = schema.nullable();
     } else if (allowEmpty(typedef, options)) {
       schema = schema.options({
         allowEmpty: true
@@ -402,6 +405,9 @@ function getSearchSchema(schema, type) {
 function isRequired(typedef, options) {
   return typedef.required && !typedef.default && !options.skipRequired;
 }
+function allowNull(typedef, options) {
+  return options.allowNull && !typedef.required;
+}
 function allowUnset(typedef, options) {
   return options.allowUnset && !typedef.required;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrockio/model",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Bedrock utilities for model creation.",
   "type": "module",
   "scripts": {
@@ -30,7 +30,7 @@
     "lodash": "^4.17.21"
   },
   "peerDependencies": {
-    "@bedrockio/yada": "^1.1.2",
+    "@bedrockio/yada": "^1.1.3",
     "mongoose": "^8.5.1"
   },
   "devDependencies": {
@@ -38,7 +38,7 @@
     "@babel/core": "^7.20.12",
     "@babel/preset-env": "^7.20.2",
     "@bedrockio/prettier-config": "^1.0.2",
-    "@bedrockio/yada": "^1.1.2",
+    "@bedrockio/yada": "^1.1.3",
     "@shelf/jest-mongodb": "^4.3.2",
     "eslint": "^8.33.0",
     "eslint-plugin-bedrock": "^1.0.26",

package/src/search.js

@@ -3,7 +3,7 @@ import logger from '@bedrockio/logger';
 import mongoose from 'mongoose';
 import { get, pick, isEmpty, escapeRegExp, isPlainObject } from 'lodash';
 
-import { isDateField, isNumberField, getField } from './utils';
+import { isArrayField, isDateField, isNumberField, getField } from './utils';
 import { SEARCH_DEFAULTS } from './const';
 import { OBJECT_ID_SCHEMA } from './validation';
 import { debug } from './env';
@@ -241,6 +241,8 @@ function normalizeQuery(query, schema, root = {}, rootPath = []) {
       root[path.join('.')] = parseRegexQuery(value);
     } else if (isArrayQuery(key, value)) {
       root[path.join('.')] = { $in: value };
+    } else if (isEmptyArrayQuery(schema, key, value)) {
+      root[path.join('.')] = [];
     } else {
       root[path.join('.')] = value;
     }
@@ -262,12 +264,16 @@ function isArrayQuery(key, value) {
   return !isMongoOperator(key) && !isInclude(key) && Array.isArray(value);
 }
 
+function isEmptyArrayQuery(schema, key, value) {
+  return !isMongoOperator(key) && isArrayField(schema, key) && value === null;
+}
+
 function isRangeQuery(schema, key, value) {
   // Range queries only allowed on Date and Number fields.
   if (!isDateField(schema, key) && !isNumberField(schema, key)) {
     return false;
   }
-  return typeof value === 'object';
+  return typeof value === 'object' && !!value;
 }
 
 function mapOperatorQuery(obj) {
@@ -340,9 +346,7 @@ function applySearchCache(schema, definition) {
       if (!force) {
         const $or = Object.keys(cache).map((cachedField) => {
           return {
-            [cachedField]: {
-              $exists: false,
-            },
+            [cachedField]: null,
           };
         });
         query.$or = $or;

package/src/utils.js

@@ -36,6 +36,11 @@ export function isNumberField(obj, path) {
   return isType(obj, path, 'Number');
 }
 
+export function isArrayField(obj, path) {
+  const field = getField(obj, path);
+  return Array.isArray(field?.type);
+}
+
 function isType(obj, path, test) {
   const { type } = getInnerField(obj, path);
   return type === test || type === mongoose.Schema.Types[test];

package/src/validation.js

@@ -152,6 +152,7 @@ export function applyValidation(schema, definition) {
 
       return getSchemaFromMongoose(schema, {
         model: this,
+        allowNull: true,
         allowSearch: true,
         skipRequired: true,
         allowInclude: true,
@@ -299,9 +300,11 @@ function getSchemaForTypedef(typedef, options = {}) {
   } else {
     schema = getSchemaForType(type, options);
 
-    // Unsetting only allowed for primitive types.
+    // Only allowed for primitive types.
     if (allowUnset(typedef, options)) {
-      schema = yd.allow(null, '', schema);
+      schema = yd.allow(schema, '').nullable();
+    } else if (allowNull(typedef, options)) {
+      schema = schema.nullable();
     } else if (allowEmpty(typedef, options)) {
       schema = schema.options({
         allowEmpty: true,
@@ -352,6 +355,7 @@ function getSchemaForTypedef(typedef, options = {}) {
   if (typedef.writeAccess && options.requireWriteAccess) {
     schema = validateAccess('write', schema, typedef.writeAccess, options);
   }
+
   return schema;
 }
 
@@ -460,6 +464,10 @@ function isRequired(typedef, options) {
   return typedef.required && !typedef.default && !options.skipRequired;
 }
 
+function allowNull(typedef, options) {
+  return options.allowNull && !typedef.required;
+}
+
 function allowUnset(typedef, options) {
   return options.allowUnset && !typedef.required;
 }

package/types/include.d.ts

@@ -18,6 +18,7 @@ export const INCLUDE_FIELD_SCHEMA: {
     strip(strip: any): any;
     allow(...set: any[]): any;
     reject(...set: any[]): any;
+    nullable(): any;
     message(message: any): any;
     tag(tags: any): any;
     description(description: any): any;
@@ -33,8 +34,11 @@ export const INCLUDE_FIELD_SCHEMA: {
     } | {
         default: any;
     };
-    inspect(): string;
+    getNullable(): {
+        nullable: boolean;
+    };
     expandExtra(extra?: {}): {};
+    inspect(): string;
     assertEnum(set: any, allow: any): any;
     assert(type: any, fn: any): any;
     pushAssertion(assertion: any): void;

package/types/include.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../src/include.js"],"names":[],"mappings":"AA2BA,gDAuEC;AAMD,uDA4BC;AAGD,yDAIC;AAGD,yEAUC;AApID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKG"}
+{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../src/include.js"],"names":[],"mappings":"AA2BA,gDAuEC;AAMD,uDA4BC;AAGD,yDAIC;AAGD,yEAUC;AApID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKG"}

package/types/search.d.ts

@@ -15,6 +15,7 @@ export function searchValidation(options?: {}): {
     strip(strip: any): any;
     allow(...set: any[]): any;
     reject(...set: any[]): any;
+    nullable(): any;
     message(message: any): any;
     tag(tags: any): any;
     description(description: any): any;
@@ -30,8 +31,11 @@ export function searchValidation(options?: {}): {
     } | {
         default: any;
     };
-    inspect(): string;
+    getNullable(): {
+        nullable: boolean;
+    };
     expandExtra(extra?: {}): {};
+    inspect(): string;
     assertEnum(set: any, allow: any): any;
     assert(type: any, fn: any): any;
     pushAssertion(assertion: any): void;

package/types/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.js"],"names":[],"mappings":"AAgBA,gEA0DC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBC"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.js"],"names":[],"mappings":"AAgBA,gEA0DC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBC"}

package/types/utils.d.ts

@@ -3,6 +3,7 @@ export function isMongooseSchema(obj: any): boolean;
 export function isReferenceField(obj: any, path: any): boolean;
 export function isDateField(obj: any, path: any): boolean;
 export function isNumberField(obj: any, path: any): boolean;
+export function isArrayField(obj: any, path: any): boolean;
 export function isSchemaTypedef(arg: any): boolean;
 export function getField(obj: any, path: any): any;
 export function getInnerField(obj: any, path: any): any;

package/types/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.js"],"names":[],"mappings":"AAMA,iDAcC;AAED,oDAEC;AAED,+DAEC;AAED,0DAEC;AAED,4DAEC;AAOD,mDAGC;AAuBD,mDAYC;AAKD,wDAEC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.js"],"names":[],"mappings":"AAMA,iDAcC;AAED,oDAEC;AAED,+DAEC;AAED,0DAEC;AAED,4DAEC;AAED,2DAGC;AAOD,mDAGC;AAuBD,mDAYC;AAKD,wDAEC"}

package/types/validation.d.ts

@@ -77,6 +77,7 @@ export const OBJECT_ID_SCHEMA: {
     strip(strip: any): any;
     allow(...set: any[]): any;
     reject(...set: any[]): any;
+    nullable(): any;
     message(message: any): any;
     tag(tags: any): any;
     description(description: any): any;
@@ -93,8 +94,11 @@ export const OBJECT_ID_SCHEMA: {
     } | {
         default: any;
     };
-    inspect(): string;
+    getNullable(): {
+        nullable: boolean;
+    };
     expandExtra(extra?: {}): {};
+    inspect(): string;
     assertEnum(set: any, allow: any): any;
     assert(type: any, fn: any): any;
     pushAssertion(assertion: any): void;

package/types/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.js"],"names":[],"mappings":"AAkFA,kDAEC;AAED,oEA+FC;AAsBD,wEA2BC;AA2SD;;;EAEC;AAED;;;EAOC;AA1gBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQK"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.js"],"names":[],"mappings":"AAkFA,kDAEC;AAED,oEAgGC;AAsBD,wEA2BC;AAkTD;;;EAEC;AAED;;;EAOC;AAlhBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQK"}