@bedrockio/model 0.1.0 → 0.1.1

package/README.md

@@ -378,6 +378,30 @@ Due to ambiguity with the soft delete module, the following methods will throw a
 - `Model.findOneAndRemove` - Use `Model.findOneAndDelete` instead.
 - `Model.findByIdAndRemove` - Use `Model.findByIdAndDelete` instead.
 
+#### Unique Constraints
+
+Note that although monogoose allows a `unique` option on fields, this will add a unique index to the mongo collection itself which is incompatible with soft deletion.
+
+This package will intercept `unique: true` to create a soft delete compatible validation which will:
+
+- Throw an error if other non-deleted documents with the same fields exist when calling:
+  - `Document.save`
+  - `Document.update`
+  - `Document.restore`
+  - `Model.updateOne` (see note below)
+  - `Model.updateMany` (see note below)
+  - `Model.restoreOne`
+  - `Model.restoreMany`
+  - `Model.insertMany`
+  - `Model.replaceOne`
+- Append the same validation to `Model.getCreateSchema` and `Model.getUpdateSchema` to allow this constraint to trickle down to the API.
+
+> :warning: updateOne and updateMany
+>
+> Note that calling `Model.updateOne` will throw an error when a unique field exists on any document **including the document being updated**. This is an intentional constraint that allows `updateOne` better peformance by not having to fetch the ids of the documents being updated in order to exclude them. To avoid this call `Document.save` instead.
+>
+> Note also that calling `Model.updateMany` with a unique field passed will always throw an error as the result would inherently be non-unique.
+
 ### Validation
 
 Models are extended with methods that allow complex validation that derives from the schema. Bedrock validation is generally used at the API level:

package/dist/cjs/access.js

@@ -15,6 +15,10 @@ function hasReadAccess(allowed, options) {
 function hasWriteAccess(allowed, options) {
   return hasAccess('write', allowed, options);
 }
+
+/**
+ * @param {string|string[]} allowed
+ */
 function hasAccess(type, allowed = 'all', options = {}) {
   if (allowed === 'all') {
     return true;

package/dist/cjs/assign.js

@@ -4,9 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.applyAssign = applyAssign;
-var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
+var _lodash = require("lodash");
 var _utils = require("./utils");
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 function applyAssign(schema) {
   schema.method('assign', function assign(fields) {
     unsetReferenceFields(fields, schema.obj);
@@ -40,7 +39,7 @@ function unsetReferenceFields(fields, schema = {}) {
 function flattenObject(obj, root = {}, rootPath = []) {
   for (let [key, val] of Object.entries(obj)) {
     const path = [...rootPath, key];
-    if ((0, _isPlainObject2.default)(val)) {
+    if ((0, _lodash.isPlainObject)(val)) {
       flattenObject(val, root, path);
     } else {
       root[path.join('.')] = val;

package/dist/cjs/disallowed.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.applyDisallowed = applyDisallowed;
+var _warn = _interopRequireDefault(require("./warn"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function applyDisallowed(schema) {
+  schema.method('remove', function () {
+    (0, _warn.default)('The "remove" method on documents is disallowed due to ambiguity.', 'To permanently delete a document use "destroy", otherwise "delete".');
+    throw new Error('Method not allowed.');
+  }, {
+    suppressWarning: true
+  });
+  schema.method('update', function () {
+    (0, _warn.default)('The "update" method on documents is deprecated. Use "updateOne" instead.');
+    throw new Error('Method not allowed.');
+  });
+  schema.method('deleteOne', function () {
+    (0, _warn.default)('The "deleteOne" method on documents is disallowed due to ambiguity', 'Use either "delete" or "deleteOne" on the model.');
+    throw new Error('Method not allowed.');
+  });
+  schema.static('remove', function () {
+    (0, _warn.default)('The "remove" method on models is disallowed due to ambiguity.', 'To permanently delete a document use "destroyMany", otherwise "deleteMany".');
+    throw new Error('Method not allowed.');
+  });
+  schema.static('findOneAndRemove', function () {
+    (0, _warn.default)('The "findOneAndRemove" method on models is disallowed due to ambiguity.', 'To permanently delete a document use "findOneAndDestroy", otherwise "findOneAndDelete".');
+    throw new Error('Method not allowed.');
+  });
+  schema.static('findByIdAndRemove', function () {
+    (0, _warn.default)('The "findByIdAndRemove" method on models is disallowed due to ambiguity.', 'To permanently delete a document use "findByIdAndDestroy", otherwise "findByIdAndDelete".');
+    throw new Error('Method not allowed.');
+  });
+  schema.static('count', function () {
+    (0, _warn.default)('The "count" method on models is deprecated. Use "countDocuments" instead.');
+    throw new Error('Method not allowed.');
+  });
+}

package/dist/cjs/include.js

@@ -6,11 +6,12 @@ Object.defineProperty(exports, "__esModule", {
 exports.applyInclude = applyInclude;
 exports.checkSelects = checkSelects;
 exports.getIncludes = getIncludes;
-var _escapeRegExp2 = _interopRequireDefault(require("lodash/escapeRegExp"));
 var _mongoose = _interopRequireDefault(require("mongoose"));
+var _lodash = require("lodash");
 var _utils = require("./utils");
 var _const = require("./const");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+// @ts-ignore
 // Overloading mongoose Query prototype to
 // allow an "include" method for queries.
 _mongoose.default.Query.prototype.include = function include(paths) {
@@ -205,7 +206,7 @@ function setNodePath(node, options) {
 function resolvePaths(schema, str) {
   let paths;
   if (str.includes('*')) {
-    let source = (0, _escapeRegExp2.default)(str);
+    let source = (0, _lodash.escapeRegExp)(str);
     source = source.replaceAll('\\*\\*', '.+');
     source = source.replaceAll('\\*', '[^.]+');
     source = `^${source}$`;

package/dist/cjs/load.js

@@ -5,12 +5,18 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.loadModel = loadModel;
 exports.loadModelDir = loadModelDir;
-var _startCase2 = _interopRequireDefault(require("lodash/startCase"));
 var _fs = _interopRequireDefault(require("fs"));
 var _path = _interopRequireDefault(require("path"));
 var _mongoose = _interopRequireDefault(require("mongoose"));
+var _lodash = require("lodash");
 var _schema = require("./schema");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * Loads a single model by definition and name.
+ * @param {object} definition
+ * @param {string} name
+ * @returns mongoose.Model
+ */
 function loadModel(definition, name) {
   if (!definition.attributes) {
     throw new Error(`Invalid model definition for ${name}, need attributes`);
@@ -22,15 +28,21 @@ function loadModel(definition, name) {
     throw new Error(`${err.message} (loading ${name})`);
   }
 }
+
+/**
+ * Loads all model definitions in the given directory.
+ * Returns the full loaded model set.
+ * @param {string} dirPath
+ */
 function loadModelDir(dirPath) {
   const files = _fs.default.readdirSync(dirPath);
   for (const file of files) {
     const basename = _path.default.basename(file, '.json');
     if (file.match(/\.json$/)) {
       const filePath = _path.default.join(dirPath, file);
-      const data = _fs.default.readFileSync(filePath);
+      const data = _fs.default.readFileSync(filePath, 'utf-8');
       const definition = JSON.parse(data);
-      const modelName = definition.modelName || (0, _startCase2.default)(basename).replace(/\s/g, '');
+      const modelName = definition.modelName || (0, _lodash.startCase)(basename).replace(/\s/g, '');
       if (!_mongoose.default.models[modelName]) {
         loadModel(definition, modelName);
       }

package/dist/cjs/schema.js

@@ -6,11 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.RESERVED_FIELDS = void 0;
 exports.createSchema = createSchema;
 exports.normalizeAttributes = normalizeAttributes;
-var _camelCase2 = _interopRequireDefault(require("lodash/camelCase"));
-var _capitalize2 = _interopRequireDefault(require("lodash/capitalize"));
-var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
-var _pick2 = _interopRequireDefault(require("lodash/pick"));
 var _mongoose = _interopRequireDefault(require("mongoose"));
+var _lodash = require("lodash");
 var _utils = require("./utils");
 var _serialization = require("./serialization");
 var _slug = require("./slug");
@@ -19,9 +16,19 @@ var _assign = require("./assign");
 var _include = require("./include");
 var _references = require("./references");
 var _softDelete = require("./soft-delete");
+var _disallowed = require("./disallowed");
 var _validation = require("./validation");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 const RESERVED_FIELDS = ['createdAt', 'updatedAt', 'deletedAt', 'deleted'];
+
+/**
+ * Creates a new Mongoose schema with Bedrock extensions
+ * applied. For more about syntax and functionality see
+ * [the documentation](https://github.com/bedrockio/model#schemas).
+ * @param {object} definition
+ * @param {mongoose.SchemaOptions} options
+ * @returns mongoose.Schema
+ */
 exports.RESERVED_FIELDS = RESERVED_FIELDS;
 function createSchema(definition, options = {}) {
   const schema = new _mongoose.default.Schema(attributesToMongoose(normalizeAttributes({
@@ -42,13 +49,14 @@ function createSchema(definition, options = {}) {
     toObject: _serialization.serializeOptions,
     ...options
   });
-  (0, _softDelete.applySoftDelete)(schema, definition);
   (0, _validation.applyValidation)(schema, definition);
-  (0, _references.applyReferences)(schema, definition);
-  (0, _include.applyInclude)(schema, definition);
   (0, _search.applySearch)(schema, definition);
-  (0, _assign.applyAssign)(schema, definition);
-  (0, _slug.applySlug)(schema, definition);
+  (0, _softDelete.applySoftDelete)(schema);
+  (0, _references.applyReferences)(schema);
+  (0, _disallowed.applyDisallowed)(schema);
+  (0, _include.applyInclude)(schema);
+  (0, _assign.applyAssign)(schema);
+  (0, _slug.applySlug)(schema);
   return schema;
 }
 function normalizeAttributes(arg, path = []) {
@@ -115,7 +123,7 @@ function attributesToMongoose(attributes) {
         // Allow custom mongoose validation function that derives from the schema.
         val = (0, _validation.getNamedValidator)(val);
       }
-    } else if ((0, _isPlainObject2.default)(val)) {
+    } else if ((0, _lodash.isPlainObject)(val)) {
       if (isScopeExtension(val)) {
         applyScopeExtension(val, definition);
         continue;
@@ -160,7 +168,7 @@ function assertRefs(field, path) {
   }
 }
 function camelUpper(str) {
-  return (0, _capitalize2.default)((0, _camelCase2.default)(str));
+  return (0, _lodash.capitalize)((0, _lodash.camelCase)(str));
 }
 function isObjectIdType(type) {
   return type === 'ObjectId' || type === _mongoose.default.Schema.Types.ObjectId;
@@ -170,6 +178,7 @@ function isMongooseType(type) {
 }
 function applyExtensions(typedef) {
   applySyntaxExtensions(typedef);
+  applyUniqueExtension(typedef);
   applyTupleExtension(typedef);
 }
 function applySyntaxExtensions(typedef) {
@@ -192,7 +201,7 @@ function applySyntaxExtensions(typedef) {
 // Hoist read/write scopes from a nested element.
 // See the readme for more.
 function applyOptionHoisting(typedef) {
-  Object.assign(typedef, (0, _pick2.default)(typedef.type[0], 'readAccess', 'writeAccess'));
+  Object.assign(typedef, (0, _lodash.pick)(typedef.type[0], 'readAccess', 'writeAccess'));
 }
 function isExtendedSyntax(typedef) {
   const {
@@ -228,6 +237,14 @@ function applyTupleExtension(typedef) {
     typedef.validate = (0, _validation.getTupleValidator)(type);
   }
 }
+
+// Intercepts "unique" options and changes to "softUnique".
+function applyUniqueExtension(typedef) {
+  if (typedef.unique === true) {
+    typedef.softUnique = true;
+    delete typedef.unique;
+  }
+}
 function applyArrayValidators(typedef) {
   let {
     minLength,

package/dist/cjs/search.js

@@ -5,13 +5,12 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.applySearch = applySearch;
 exports.searchValidation = searchValidation;
-var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
-var _isEmpty2 = _interopRequireDefault(require("lodash/isEmpty"));
-var _pick2 = _interopRequireDefault(require("lodash/pick"));
 var _yada = _interopRequireDefault(require("@bedrockio/yada"));
 var _mongoose = _interopRequireDefault(require("mongoose"));
+var _lodash = require("lodash");
 var _utils = require("./utils");
 var _const = require("./const");
+var _validation = require("./validation");
 var _warn = _interopRequireDefault(require("./warn"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 const {
@@ -20,7 +19,7 @@ const {
 const SORT_SCHEMA = _yada.default.object({
   field: _yada.default.string().required(),
   order: _yada.default.string().allow('desc', 'asc').required()
-});
+}).description('An object describing the sort order of results.');
 function applySearch(schema, definition) {
   validateDefinition(definition);
   schema.static('search', function search(body = {}) {
@@ -75,22 +74,23 @@ function applySearch(schema, definition) {
   });
 }
 function searchValidation(definition, options = {}) {
+  options = {
+    ..._const.SEARCH_DEFAULTS,
+    ...(0, _lodash.pick)(definition.search, 'limit', 'sort'),
+    ...options
+  };
   const {
     limit,
     sort,
     ...rest
-  } = {
-    ..._const.SEARCH_DEFAULTS,
-    ...(0, _pick2.default)(definition.search, 'limit', 'sort'),
-    ...options
-  };
+  } = options;
   return {
-    ids: _yada.default.array(_yada.default.string().mongo()),
-    keyword: _yada.default.string(),
-    include: _yada.default.string(),
-    skip: _yada.default.number().default(0),
+    ids: _yada.default.array(_validation.OBJECT_ID_SCHEMA),
+    keyword: _yada.default.string().description('A keyword to perform a text search against.'),
+    include: _yada.default.string().description('Fields to be selected or populated.'),
+    skip: _yada.default.number().default(0).description('Number of records to skip.'),
     sort: _yada.default.allow(SORT_SCHEMA, _yada.default.array(SORT_SCHEMA)).default(sort),
-    limit: _yada.default.number().positive().default(limit),
+    limit: _yada.default.number().positive().default(limit).description('Limits the number of results.'),
     ...rest
   };
 }
@@ -202,7 +202,7 @@ function normalizeQuery(query, schema, root = {}, rootPath = []) {
   for (let [key, value] of Object.entries(query)) {
     const path = [...rootPath, key];
     if (isRangeQuery(schema, key, value)) {
-      if (!(0, _isEmpty2.default)(value)) {
+      if (!(0, _lodash.isEmpty)(value)) {
         root[path.join('.')] = mapOperatorQuery(value);
       }
     } else if (isNestedQuery(key, value)) {
@@ -220,7 +220,7 @@ function normalizeQuery(query, schema, root = {}, rootPath = []) {
   return root;
 }
 function isNestedQuery(key, value) {
-  if (isMongoOperator(key) || !(0, _isPlainObject2.default)(value)) {
+  if (isMongoOperator(key) || !(0, _lodash.isPlainObject)(value)) {
     return false;
   }
   return Object.keys(value).every(key => {

package/dist/cjs/serialization.js

@@ -4,11 +4,10 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.serializeOptions = void 0;
-var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
+var _lodash = require("lodash");
 var _include = require("./include");
 var _access = require("./access");
 var _utils = require("./utils");
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 const serializeOptions = {
   getters: true,
   versionKey: false,
@@ -24,7 +23,7 @@ function transformField(obj, field, options) {
     for (let el of obj) {
       transformField(el, field, options);
     }
-  } else if ((0, _isPlainObject2.default)(obj)) {
+  } else if ((0, _lodash.isPlainObject)(obj)) {
     for (let [key, val] of Object.entries(obj)) {
       if (!isAllowedField(key, field, options)) {
         delete obj[key];