@bedrockio/model 0.1.0 → 0.1.1

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@bedrockio/model",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Bedrock utilities for model creation.",
   "type": "module",
   "scripts": {
     "test": "jest",
     "lint": "eslint",
     "build": "scripts/build",
-    "prepublishOnly": "npm run build"
+    "types": "tsc",
+    "prepublishOnly": "yarn build && yarn types"
   },
   "main": "dist/cjs/index.js",
   "module": "src/index.js",
+  "types": "types/index.d.ts",
   "contributors": [
     {
       "name": "Andrew Plummer",
@@ -23,8 +25,8 @@
     "url": "https://github.com/bedrockio/model"
   },
   "dependencies": {
-    "@bedrockio/logger": "^1.0.3",
-    "@bedrockio/yada": "^1.0.9",
+    "@bedrockio/logger": "^1.0.5",
+    "@bedrockio/yada": "^1.0.16",
     "lodash": "^4.17.21"
   },
   "peerDependencies": {
@@ -37,14 +39,14 @@
     "@bedrockio/prettier-config": "^1.0.2",
     "@shelf/jest-mongodb": "^4.1.6",
     "babel-plugin-import-replacement": "^1.0.1",
-    "babel-plugin-lodash": "^3.3.4",
     "eslint": "^8.33.0",
-    "eslint-plugin-bedrock": "^1.0.21",
+    "eslint-plugin-bedrock": "^1.0.24",
     "jest": "^29.4.1",
     "jest-environment-node": "^29.4.1",
     "mongodb": "4.13.0",
     "mongoose": "^6.9.0",
-    "prettier-eslint": "^15.0.1"
+    "prettier-eslint": "^15.0.1",
+    "typescript": "^4.9.5"
   },
   "volta": {
     "node": "18.14.0",

package/src/access.js

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

package/src/disallowed.js

@@ -0,0 +1,63 @@
+import warn from './warn';
+
+export function applyDisallowed(schema) {
+  schema.method(
+    'remove',
+    function () {
+      warn(
+        '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 () {
+    warn(
+      'The "update" method on documents is deprecated. Use "updateOne" instead.'
+    );
+    throw new Error('Method not allowed.');
+  });
+
+  schema.method('deleteOne', function () {
+    warn(
+      '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 () {
+    warn(
+      '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 () {
+    warn(
+      '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 () {
+    warn(
+      '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 () {
+    warn(
+      'The "count" method on models is deprecated. Use "countDocuments" instead.'
+    );
+    throw new Error('Method not allowed.');
+  });
+}

package/src/include.js

@@ -4,6 +4,7 @@ import { escapeRegExp } from 'lodash';
 import { resolveInnerField } from './utils';
 import { POPULATE_MAX_DEPTH } from './const';
 
+// @ts-ignore
 // Overloading mongoose Query prototype to
 // allow an "include" method for queries.
 mongoose.Query.prototype.include = function include(paths) {

package/src/load.js

@@ -6,6 +6,12 @@ import { startCase } from 'lodash';
 
 import { createSchema } from './schema';
 
+/**
+ * Loads a single model by definition and name.
+ * @param {object} definition
+ * @param {string} name
+ * @returns mongoose.Model
+ */
 export function loadModel(definition, name) {
   if (!definition.attributes) {
     throw new Error(`Invalid model definition for ${name}, need attributes`);
@@ -18,13 +24,18 @@ export function loadModel(definition, name) {
   }
 }
 
+/**
+ * Loads all model definitions in the given directory.
+ * Returns the full loaded model set.
+ * @param {string} dirPath
+ */
 export function loadModelDir(dirPath) {
   const files = fs.readdirSync(dirPath);
   for (const file of files) {
     const basename = path.basename(file, '.json');
     if (file.match(/\.json$/)) {
       const filePath = path.join(dirPath, file);
-      const data = fs.readFileSync(filePath);
+      const data = fs.readFileSync(filePath, 'utf-8');
       const definition = JSON.parse(data);
       const modelName =
         definition.modelName || startCase(basename).replace(/\s/g, '');

package/src/schema.js

@@ -10,6 +10,8 @@ import { applyAssign } from './assign';
 import { applyInclude } from './include';
 import { applyReferences } from './references';
 import { applySoftDelete } from './soft-delete';
+import { applyDisallowed } from './disallowed';
+
 import {
   applyValidation,
   getNamedValidator,
@@ -23,6 +25,14 @@ export const RESERVED_FIELDS = [
   '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
+ */
 export function createSchema(definition, options = {}) {
   const schema = new mongoose.Schema(
     attributesToMongoose(
@@ -46,13 +56,14 @@ export function createSchema(definition, options = {}) {
     }
   );
 
-  applySoftDelete(schema, definition);
   applyValidation(schema, definition);
-  applyReferences(schema, definition);
-  applyInclude(schema, definition);
   applySearch(schema, definition);
-  applyAssign(schema, definition);
-  applySlug(schema, definition);
+  applySoftDelete(schema);
+  applyReferences(schema);
+  applyDisallowed(schema);
+  applyInclude(schema);
+  applyAssign(schema);
+  applySlug(schema);
 
   return schema;
 }
@@ -185,6 +196,7 @@ function isMongooseType(type) {
 
 function applyExtensions(typedef) {
   applySyntaxExtensions(typedef);
+  applyUniqueExtension(typedef);
   applyTupleExtension(typedef);
 }
 
@@ -236,6 +248,14 @@ function applyTupleExtension(typedef) {
   }
 }
 
+// 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, maxLength, validate } = typedef;
   if (minLength) {

package/src/search.js

@@ -4,15 +4,18 @@ import { pick, isEmpty, isPlainObject } from 'lodash';
 
 import { isDateField, isNumberField, resolveField } from './utils';
 import { SEARCH_DEFAULTS } from './const';
+import { OBJECT_ID_SCHEMA } from './validation';
 
 import warn from './warn';
 
 const { ObjectId } = mongoose.Types;
 
-const SORT_SCHEMA = yd.object({
-  field: yd.string().required(),
-  order: yd.string().allow('desc', 'asc').required(),
-});
+const SORT_SCHEMA = yd
+  .object({
+    field: yd.string().required(),
+    order: yd.string().allow('desc', 'asc').required(),
+  })
+  .description('An object describing the sort order of results.');
 
 export function applySearch(schema, definition) {
   validateDefinition(definition);
@@ -74,19 +77,27 @@ export function applySearch(schema, definition) {
 }
 
 export function searchValidation(definition, options = {}) {
-  const { limit, sort, ...rest } = {
+  options = {
     ...SEARCH_DEFAULTS,
     ...pick(definition.search, 'limit', 'sort'),
     ...options,
   };
 
+  const { limit, sort, ...rest } = options;
+
   return {
-    ids: yd.array(yd.string().mongo()),
-    keyword: yd.string(),
-    include: yd.string(),
-    skip: yd.number().default(0),
+    ids: yd.array(OBJECT_ID_SCHEMA),
+    keyword: yd
+      .string()
+      .description('A keyword to perform a text search against.'),
+    include: yd.string().description('Fields to be selected or populated.'),
+    skip: yd.number().default(0).description('Number of records to skip.'),
     sort: yd.allow(SORT_SCHEMA, yd.array(SORT_SCHEMA)).default(sort),
-    limit: yd.number().positive().default(limit),
+    limit: yd
+      .number()
+      .positive()
+      .default(limit)
+      .description('Limits the number of results.'),
     ...rest,
   };
 }

package/src/soft-delete.js

@@ -1,6 +1,11 @@
-import warn from './warn';
-
 export function applySoftDelete(schema) {
+  applyQueries(schema);
+  applyUniqueConstraints(schema);
+}
+
+// Soft Delete Querying
+
+function applyQueries(schema) {
   // Implementation
 
   schema.pre(/^find|count|exists/, function (next) {
@@ -17,12 +22,14 @@ export function applySoftDelete(schema) {
   schema.method('delete', function () {
     this.deleted = true;
     this.deletedAt = new Date();
+    // @ts-ignore
     return this.save();
   });
 
   schema.method('restore', function restore() {
     this.deleted = false;
     this.deletedAt = undefined;
+    // @ts-ignore
     return this.save();
   });
 
@@ -92,125 +99,100 @@ export function applySoftDelete(schema) {
     };
   });
 
-  schema.static('findDeleted', function findDeleted(filter) {
-    return this.find({
+  schema.static('findDeleted', function findDeleted(filter, ...rest) {
+    filter = {
       ...filter,
       deleted: true,
-    });
+    };
+    return this.find(filter, ...rest);
   });
 
-  schema.static('findOneDeleted', function findOneDeleted(filter) {
-    return this.findOne({
+  schema.static('findOneDeleted', function findOneDeleted(filter, ...rest) {
+    filter = {
       ...filter,
       deleted: true,
-    });
+    };
+    return this.findOne(filter, ...rest);
   });
 
-  schema.static('findByIdDeleted', function findByIdDeleted(id) {
-    return this.findOne({
+  schema.static('findByIdDeleted', function findByIdDeleted(id, ...rest) {
+    const filter = {
       _id: id,
       deleted: true,
-    });
+    };
+    return this.findOne(filter, ...rest);
   });
 
-  schema.static('existsDeleted', function existsDeleted() {
-    return this.exists({
+  schema.static('existsDeleted', function existsDeleted(filter, ...rest) {
+    filter = {
+      ...filter,
       deleted: true,
-    });
+    };
+    return this.exists(filter, ...rest);
   });
 
   schema.static(
     'countDocumentsDeleted',
-    function countDocumentsDeleted(filter) {
-      return this.countDocuments({
+    function countDocumentsDeleted(filter, ...rest) {
+      filter = {
         ...filter,
         deleted: true,
-      });
+      };
+      return this.countDocuments(filter, ...rest);
     }
   );
 
-  schema.static('findWithDeleted', function findWithDeleted(filter) {
-    return this.find({
-      ...filter,
-      ...getWithDeletedQuery(),
-    });
-  });
-
-  schema.static('findOneWithDeleted', function findOneWithDeleted(filter) {
-    return this.findOne({
+  schema.static('findWithDeleted', function findWithDeleted(filter, ...rest) {
+    filter = {
       ...filter,
       ...getWithDeletedQuery(),
-    });
-  });
-
-  schema.static('findByIdWithDeleted', function findByIdWithDeleted(id) {
-    return this.findOne({
-      _id: id,
-      ...getWithDeletedQuery(),
-    });
-  });
-
-  schema.static('existsWithDeleted', function existsWithDeleted() {
-    return this.exists({
-      ...getWithDeletedQuery(),
-    });
+    };
+    return this.find(filter, ...rest);
   });
 
   schema.static(
-    'countDocumentsWithDeleted',
-    function countDocumentsWithDeleted(filter) {
-      return this.countDocuments({
+    'findOneWithDeleted',
+    function findOneWithDeleted(filter, ...rest) {
+      filter = {
         ...filter,
         ...getWithDeletedQuery(),
-      });
+      };
+      return this.findOne(filter, ...rest);
     }
   );
 
-  schema.method(
-    'remove',
-    function () {
-      warn(
-        '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.static(
+    'findByIdWithDeleted',
+    function findByIdWithDeleted(id, ...rest) {
+      const filter = {
+        _id: id,
+        ...getWithDeletedQuery(),
+      };
+      return this.findOne(filter, ...rest);
     }
   );
 
-  schema.method('deleteOne', function () {
-    warn(
-      '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 () {
-    warn(
-      '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 () {
-    warn(
-      '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(
+    'existsWithDeleted',
+    function existsWithDeleted(filter, ...rest) {
+      filter = {
+        ...filter,
+        ...getWithDeletedQuery(),
+      };
+      return this.exists(filter, ...rest);
+    }
+  );
 
-  schema.static('findByIdAndRemove', function () {
-    warn(
-      '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(
+    'countDocumentsWithDeleted',
+    function countDocumentsWithDeleted(filter, ...rest) {
+      filter = {
+        ...filter,
+        ...getWithDeletedQuery(),
+      };
+      return this.countDocuments(filter, ...rest);
+    }
+  );
 }
 
 function getDelete() {
@@ -232,3 +214,174 @@ function getWithDeletedQuery() {
     deleted: { $in: [true, false] },
   };
 }
+
+// Unique Constraints
+
+function applyUniqueConstraints(schema) {
+  const hasUnique = hasUniqueConstraints(schema);
+
+  if (!hasUnique) {
+    return;
+  }
+
+  schema.pre('save', async function () {
+    await assertUnique(this.toObject(), {
+      operation: this.isNew ? 'create' : 'update',
+      model: this.constructor,
+      schema,
+    });
+  });
+
+  schema.pre(/^(update|replace)/, async function () {
+    await assertUniqueForQuery(this, {
+      schema,
+    });
+  });
+
+  schema.pre('insertMany', async function (next, obj) {
+    // Note that in order to access the objects to be inserted
+    // we must supply the hook with at least 2 arguments, the
+    // first of which is the next hook. This typically appears
+    // as the last argument, however as we are passing an async
+    // function it appears to not stop the middleware if we
+    // don't call it directly.
+    await assertUnique(obj, {
+      operation: 'create',
+      model: this,
+      schema,
+    });
+  });
+}
+
+export async function assertUnique(obj, options) {
+  const { operation, model, schema } = options;
+  const id = getId(obj);
+  const objFields = resolveUnique(schema, obj);
+  if (Object.keys(objFields).length === 0) {
+    return;
+  }
+  const query = {
+    $or: getUniqueQueries(objFields),
+    ...(id && {
+      _id: { $ne: id },
+    }),
+  };
+  const found = await model.findOne(query, {}, { lean: true });
+  if (found) {
+    const { modelName } = model;
+    const foundFields = resolveUnique(schema, found);
+    const collisions = getCollisions(objFields, foundFields).join(', ');
+    throw new Error(
+      `Cannot ${operation} ${modelName}. Duplicate fields exist: ${collisions}.`
+    );
+  }
+}
+
+function getId(arg) {
+  const id = arg.id || arg._id;
+  return id ? String(id) : null;
+}
+
+// Asserts than an update or insert query will not
+// result in duplicate unique fields being present
+// within non-deleted documents.
+async function assertUniqueForQuery(query, options) {
+  let update = query.getUpdate();
+  const operation = getOperationForQuery(update);
+  // Note: No need to check unique constraints
+  // if the operation is a delete.
+  if (operation === 'restore' || operation === 'update') {
+    const { model } = query;
+    const filter = query.getFilter();
+    if (operation === 'restore') {
+      // A restore operation is functionally identical to a new
+      // insert so we need to fetch the deleted documents with
+      // all fields available to check against.
+      const docs = await model.findWithDeleted(filter, {}, { lean: true });
+      update = docs.map((doc) => {
+        return {
+          ...doc,
+          ...update,
+        };
+      });
+    }
+    await assertUnique(update, {
+      ...options,
+      operation,
+      model,
+    });
+  }
+}
+
+function getOperationForQuery(update) {
+  if (update?.deleted === false) {
+    return 'restore';
+  } else if (update?.deleted === true) {
+    return 'delete';
+  } else {
+    return 'update';
+  }
+}
+
+export function hasUniqueConstraints(schema) {
+  const paths = [...Object.keys(schema.paths), ...Object.keys(schema.subpaths)];
+  return paths.some((key) => {
+    return isUniquePath(schema, key);
+  });
+}
+
+function isUniquePath(schema, key) {
+  return schema.path(key)?.options?.softUnique === true;
+}
+
+// Returns a flattened map of key -> [...values]
+// consisting of only paths defined as unique on the schema.
+function resolveUnique(schema, obj, map = {}, path = []) {
+  if (Array.isArray(obj)) {
+    for (let el of obj) {
+      resolveUnique(schema, el, map, path);
+    }
+  } else if (obj && typeof obj === 'object') {
+    for (let [key, val] of Object.entries(obj)) {
+      resolveUnique(schema, val, map, [...path, key]);
+    }
+  } else if (obj) {
+    const key = path.join('.');
+    if (isUniquePath(schema, key)) {
+      map[key] ||= [];
+      map[key].push(obj);
+    }
+  }
+  return map;
+}
+
+// Argument is guaranteed to be flattened.
+function getUniqueQueries(obj) {
+  return Object.entries(obj).map(([key, val]) => {
+    if (val.length > 1) {
+      return { [key]: { $in: val } };
+    } else {
+      return { [key]: val[0] };
+    }
+  });
+}
+
+// Both arguments here are guaranteed to be flattened
+// maps of key -> [values] of unique fields only.
+function getCollisions(obj1, obj2) {
+  const collisions = [];
+  for (let [key, arr1] of Object.entries(obj1)) {
+    const arr2 = obj2[key];
+    if (arr2) {
+      const hasCollision = arr1.some((val) => {
+        return arr2.includes(val);
+      });
+      if (hasCollision) {
+        collisions.push(key);
+      }
+    }
+  }
+  return collisions;
+}
+
+// Disallowed Methods

package/src/testing.js

@@ -5,6 +5,13 @@ import { isMongooseSchema } from './utils';
 
 let counter = 0;
 
+/**
+ * Helper to quickly create models for testing.
+ * Accepts a definition's `attributes` object and
+ * an optional model name as the first argument.
+ * [Link](https://github.com/bedrockio/model#testing)
+ * @returns mongoose.Model
+ */
 export function createTestModel(...args) {
   let modelName, attributes, schema;
   if (typeof args[0] === 'string') {