@bedrockio/model 0.1.0

package/src/soft-delete.js

@@ -0,0 +1,234 @@
+import warn from './warn';
+
+export function applySoftDelete(schema) {
+  // Implementation
+
+  schema.pre(/^find|count|exists/, function (next) {
+    const filter = this.getFilter();
+    if (filter.deleted === undefined) {
+      // Search non-deleted docs by default
+      filter.deleted = false;
+    }
+    return next();
+  });
+
+  // Instance Methods
+
+  schema.method('delete', function () {
+    this.deleted = true;
+    this.deletedAt = new Date();
+    return this.save();
+  });
+
+  schema.method('restore', function restore() {
+    this.deleted = false;
+    this.deletedAt = undefined;
+    return this.save();
+  });
+
+  schema.method('destroy', function destroy(...args) {
+    const filter = { _id: this._id };
+    return this.constructor.destroyOne(filter, ...args);
+  });
+
+  // Static Methods
+
+  schema.static('deleteOne', async function deleteOne(filter, ...rest) {
+    const update = getDelete();
+    const res = await this.updateOne(filter, update, ...rest);
+    return {
+      acknowledged: res.acknowledged,
+      deletedCount: res.modifiedCount,
+    };
+  });
+
+  schema.static('deleteMany', async function deleteMany(filter, ...rest) {
+    const update = getDelete();
+    const res = await this.updateMany(filter, update, ...rest);
+    return {
+      acknowledged: res.acknowledged,
+      deletedCount: res.modifiedCount,
+    };
+  });
+
+  schema.static(
+    'findOneAndDelete',
+    async function findOneAndDelete(filter, ...args) {
+      return await this.findOneAndUpdate(filter, getDelete(), ...args);
+    }
+  );
+
+  schema.static('restoreOne', async function restoreOne(filter, ...rest) {
+    const update = getRestore();
+    const res = await this.updateOne(filter, update, ...rest);
+    return {
+      acknowledged: res.acknowledged,
+      restoredCount: res.modifiedCount,
+    };
+  });
+
+  schema.static('restoreMany', async function restoreMany(filter, ...rest) {
+    const update = getRestore();
+    const res = await this.updateMany(filter, update, ...rest);
+    return {
+      acknowledged: res.acknowledged,
+      restoredCount: res.modifiedCount,
+    };
+  });
+
+  schema.static('destroyOne', async function destroyOne(...args) {
+    const res = await this.collection.deleteOne(...args);
+    return {
+      acknowledged: res.acknowledged,
+      destroyedCount: res.deletedCount,
+    };
+  });
+
+  schema.static('destroyMany', async function destroyMany(...args) {
+    const res = await this.collection.deleteMany(...args);
+    return {
+      acknowledged: res.acknowledged,
+      destroyedCount: res.deletedCount,
+    };
+  });
+
+  schema.static('findDeleted', function findDeleted(filter) {
+    return this.find({
+      ...filter,
+      deleted: true,
+    });
+  });
+
+  schema.static('findOneDeleted', function findOneDeleted(filter) {
+    return this.findOne({
+      ...filter,
+      deleted: true,
+    });
+  });
+
+  schema.static('findByIdDeleted', function findByIdDeleted(id) {
+    return this.findOne({
+      _id: id,
+      deleted: true,
+    });
+  });
+
+  schema.static('existsDeleted', function existsDeleted() {
+    return this.exists({
+      deleted: true,
+    });
+  });
+
+  schema.static(
+    'countDocumentsDeleted',
+    function countDocumentsDeleted(filter) {
+      return this.countDocuments({
+        ...filter,
+        deleted: true,
+      });
+    }
+  );
+
+  schema.static('findWithDeleted', function findWithDeleted(filter) {
+    return this.find({
+      ...filter,
+      ...getWithDeletedQuery(),
+    });
+  });
+
+  schema.static('findOneWithDeleted', function findOneWithDeleted(filter) {
+    return this.findOne({
+      ...filter,
+      ...getWithDeletedQuery(),
+    });
+  });
+
+  schema.static('findByIdWithDeleted', function findByIdWithDeleted(id) {
+    return this.findOne({
+      _id: id,
+      ...getWithDeletedQuery(),
+    });
+  });
+
+  schema.static('existsWithDeleted', function existsWithDeleted() {
+    return this.exists({
+      ...getWithDeletedQuery(),
+    });
+  });
+
+  schema.static(
+    'countDocumentsWithDeleted',
+    function countDocumentsWithDeleted(filter) {
+      return this.countDocuments({
+        ...filter,
+        ...getWithDeletedQuery(),
+      });
+    }
+  );
+
+  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('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.');
+  });
+}
+
+function getDelete() {
+  return {
+    deleted: true,
+    deletedAt: new Date(),
+  };
+}
+
+function getRestore() {
+  return {
+    deleted: false,
+    $unset: { deletedAt: true },
+  };
+}
+
+function getWithDeletedQuery() {
+  return {
+    deleted: { $in: [true, false] },
+  };
+}

package/src/testing.js

@@ -0,0 +1,29 @@
+import mongoose from 'mongoose';
+
+import { createSchema } from './schema';
+import { isMongooseSchema } from './utils';
+
+let counter = 0;
+
+export function createTestModel(...args) {
+  let modelName, attributes, schema;
+  if (typeof args[0] === 'string') {
+    modelName = args[0];
+    attributes = args[1];
+  } else {
+    attributes = args[0];
+  }
+  if (isMongooseSchema(attributes)) {
+    schema = attributes;
+  } else {
+    schema = createSchema({
+      attributes,
+    });
+  }
+  modelName ||= getTestModelName();
+  return mongoose.model(modelName, schema);
+}
+
+export function getTestModelName() {
+  return `TestModel${counter++}`;
+}

package/src/utils.js

@@ -0,0 +1,63 @@
+import mongoose from 'mongoose';
+
+export function isMongooseSchema(obj) {
+  return obj instanceof mongoose.Schema;
+}
+
+export function isReferenceField(obj, path) {
+  return isType(obj, path, 'ObjectId');
+}
+
+export function isDateField(obj, path) {
+  return isType(obj, path, 'Date');
+}
+
+export function isNumberField(obj, path) {
+  return isType(obj, path, 'Number');
+}
+
+function isType(obj, path, test) {
+  const { type } = resolveInnerField(obj, path);
+  return type === test || type === mongoose.Schema.Types[test];
+}
+
+export function isSchemaTypedef(arg) {
+  // Has a type defined and is not a literal type field.
+  return arg?.type && !arg.type?.type;
+}
+
+// Note: Resolved field may be an object or a function
+// from mongoose.Schema.Types that is resolved from the
+// shorthand: field: 'String'.
+export function resolveField(obj, path) {
+  let typedef = obj;
+  for (let key of path.split('.')) {
+    typedef = resolveFieldForKey(typedef, key);
+  }
+  return typedef;
+}
+
+// The same as resolveField but gets the element
+// typedef in the case of arrays.
+export function resolveInnerField(obj, path) {
+  let typedef = resolveField(obj, path);
+  if (Array.isArray(typedef.type)) {
+    typedef = typedef.type[0];
+  }
+  return typedef;
+}
+
+function resolveFieldForKey(obj, key) {
+  let typedef;
+  if (isSchemaTypedef(obj)) {
+    const { type } = obj;
+    if (Array.isArray(type)) {
+      typedef = type[0][key];
+    } else {
+      typedef = type[key];
+    }
+  } else {
+    typedef = obj[key];
+  }
+  return typedef || {};
+}

package/src/validation.js

@@ -0,0 +1,329 @@
+import mongoose from 'mongoose';
+import yd from '@bedrockio/yada';
+
+import { get, omit, lowerFirst } from 'lodash';
+
+import { hasAccess } from './access';
+import { searchValidation } from './search';
+import { PermissionsError } from './errors';
+import { isMongooseSchema, isSchemaTypedef } from './utils';
+import { RESERVED_FIELDS } from './schema';
+
+const namedSchemas = {
+  // Email is special as we are assuming that in
+  // all cases lowercase should be allowed but coerced.
+  email: yd.string().lowercase().email(),
+  // Force "ObjectId" to have parity with refs.
+  // "mongo" is notably excluded here for this reason.
+  ObjectId: yd.string().mongo(),
+
+  ascii: yd.string().ascii(),
+  base64: yd.string().base64(),
+  btc: yd.string().btc(),
+  country: yd.string().country(),
+  creditCard: yd.string().creditCard(),
+  domain: yd.string().domain(),
+  eth: yd.string().eth(),
+  hex: yd.string().hex(),
+  ip: yd.string().ip(),
+  jwt: yd.string().jwt(),
+  latlng: yd.string().latlng(),
+  locale: yd.string().locale(),
+  md5: yd.string().md5(),
+  phone: yd.string().phone(),
+  postalCode: yd.string().postalCode(),
+  sha1: yd.string().sha1(),
+  slug: yd.string().slug(),
+  swift: yd.string().swift(),
+  url: yd.string().url(),
+  uuid: yd.string().uuid(),
+};
+
+export function addValidators(schemas) {
+  Object.assign(namedSchemas, schemas);
+}
+
+export function applyValidation(schema, definition) {
+  schema.static(
+    'getCreateValidation',
+    function getCreateValidation(appendSchema) {
+      return getSchemaFromMongoose(schema, {
+        appendSchema,
+        stripReserved: true,
+        requireWriteAccess: true,
+        modelName: this.modelName,
+      });
+    }
+  );
+
+  schema.static(
+    'getUpdateValidation',
+    function getUpdateValidation(appendSchema) {
+      return getSchemaFromMongoose(schema, {
+        appendSchema,
+        skipRequired: true,
+        stripReserved: true,
+        stripUnknown: true,
+        requireWriteAccess: true,
+        modelName: this.modelName,
+      });
+    }
+  );
+
+  schema.static(
+    'getSearchValidation',
+    function getSearchValidation(searchOptions) {
+      return getSchemaFromMongoose(schema, {
+        allowRanges: true,
+        skipRequired: true,
+        allowMultiple: true,
+        unwindArrayFields: true,
+        requireReadAccess: true,
+        appendSchema: searchValidation(definition, searchOptions),
+        modelName: this.modelName,
+      });
+    }
+  );
+}
+
+// Yada schemas
+
+function getSchemaFromMongoose(schema, options) {
+  let { obj } = schema;
+  if (options.stripReserved) {
+    obj = omit(obj, RESERVED_FIELDS);
+  }
+  return getValidationSchema(obj, options);
+}
+
+// Exported for testing
+export function getValidationSchema(attributes, options = {}) {
+  const { appendSchema } = options;
+  let schema = getObjectSchema(attributes, options);
+  if (appendSchema) {
+    schema = schema.append(appendSchema);
+  }
+  return schema;
+}
+
+function getObjectSchema(arg, options) {
+  const { stripUnknown } = options;
+  if (isSchemaTypedef(arg)) {
+    return getSchemaForTypedef(arg, options);
+  } else if (arg instanceof mongoose.Schema) {
+    return getObjectSchema(arg.obj, options);
+  } else if (Array.isArray(arg)) {
+    return getArraySchema(arg, options);
+  } else if (typeof arg === 'object') {
+    const map = {};
+    for (let [key, field] of Object.entries(arg)) {
+      if (!isExcludedField(field, options)) {
+        map[key] = getObjectSchema(field, options);
+      }
+    }
+
+    let schema = yd.object(map);
+
+    if (stripUnknown) {
+      schema = schema.options({
+        stripUnknown: true,
+      });
+    }
+
+    return schema;
+  } else {
+    return getSchemaForType(arg);
+  }
+}
+
+function getArraySchema(obj, options) {
+  // Nested array fields may not skip required
+  // validations as they are a new context.
+  let schema = getObjectSchema(obj[0], {
+    ...options,
+    skipRequired: false,
+  });
+  if (!options.unwindArrayFields) {
+    schema = yd.array(schema);
+  }
+  return schema;
+}
+
+function getSchemaForTypedef(typedef, options = {}) {
+  let { type } = typedef;
+
+  let schema;
+
+  if (isMongooseSchema(type)) {
+    schema = getSchemaFromMongoose(type, options);
+  } else if (Array.isArray(type)) {
+    schema = getArraySchema(type, options);
+  } else if (typeof type === 'object') {
+    schema = getObjectSchema(type, options);
+  } else {
+    schema = getSchemaForType(type);
+  }
+
+  if (isRequired(typedef, options)) {
+    schema = schema.required();
+  }
+  if (typedef.validate?.schema) {
+    schema = schema.append(typedef.validate.schema);
+  }
+  if (typedef.enum) {
+    schema = schema.allow(...typedef.enum);
+  }
+  if (typedef.match) {
+    schema = schema.match(RegExp(typedef.match));
+  }
+  if (typedef.min != null || typedef.minLength != null) {
+    schema = schema.min(typedef.min ?? typedef.minLength);
+  }
+  if (typedef.max != null || typedef.maxLength != null) {
+    schema = schema.max(typedef.max ?? typedef.maxLength);
+  }
+  if (options.allowRanges) {
+    schema = getRangeSchema(schema, type);
+  }
+  if (options.allowMultiple) {
+    schema = yd.allow(schema, yd.array(schema));
+  }
+  if (typedef.readAccess && options.requireReadAccess) {
+    schema = validateReadAccess(schema, typedef.readAccess, options);
+  }
+  if (typedef.writeAccess && options.requireWriteAccess) {
+    schema = validateWriteAccess(schema, typedef.writeAccess, options);
+  }
+  return schema;
+}
+
+function getSchemaForType(type) {
+  switch (type) {
+    case 'String':
+      return yd.string();
+    case 'Number':
+      return yd.number();
+    case 'Boolean':
+      return yd.boolean();
+    case 'Date':
+      return yd.date().iso();
+    case 'Mixed':
+    case 'Object':
+      return yd.object();
+    case 'Array':
+      return yd.array();
+    case 'ObjectId':
+      return yd.custom(async (val) => {
+        const id = String(val.id || val);
+        await namedSchemas['ObjectId'].validate(id);
+        return id;
+      });
+    default:
+      throw new TypeError(`Unknown schema type ${type}`);
+  }
+}
+
+function getRangeSchema(schema, type) {
+  if (type === 'Number') {
+    schema = yd.allow(
+      schema,
+      yd.object({
+        lt: yd.number(),
+        gt: yd.number(),
+        lte: yd.number(),
+        gte: yd.number(),
+      })
+    );
+  } else if (type === 'Date') {
+    return yd.allow(
+      schema,
+      yd.object({
+        lt: yd.date().iso(),
+        gt: yd.date().iso(),
+        lte: yd.date().iso(),
+        gte: yd.date().iso(),
+      })
+    );
+  }
+  return schema;
+}
+
+function isRequired(typedef, options) {
+  return typedef.required && !typedef.default && !options.skipRequired;
+}
+
+function isExcludedField(field, options) {
+  if (isSchemaTypedef(field)) {
+    const { requireWriteAccess } = options;
+    return requireWriteAccess && field.writeAccess === 'none';
+  } else {
+    return false;
+  }
+}
+
+function validateReadAccess(schema, allowed, options) {
+  return validateAccess('read', schema, allowed, options);
+}
+
+function validateWriteAccess(schema, allowed, options) {
+  return validateAccess('write', schema, allowed, options);
+}
+
+function validateAccess(type, schema, allowed, options) {
+  const { modelName } = options;
+  return schema.custom((val, options) => {
+    const document = options[lowerFirst(modelName)] || options['document'];
+    const isAllowed = hasAccess(type, allowed, {
+      ...options,
+      document,
+    });
+    if (!isAllowed) {
+      const currentValue = get(document, options.path);
+      if (val !== currentValue) {
+        throw new PermissionsError('requires write permissions.');
+      }
+    }
+  });
+}
+
+// Mongoose Validators
+
+export function getNamedValidator(name) {
+  return wrapMongooseValidator(getNamedSchema(name));
+}
+
+export function getTupleValidator(types) {
+  types = types.map((type) => {
+    return getSchemaForTypedef(type);
+  });
+  return wrapMongooseValidator(yd.array(types).length(types.length));
+}
+
+// Returns an async function that will error on failure.
+//
+// Note that mongoose validator functions will not be called
+// if the field is optional and not set or unset with undefined.
+// If the field is not optional the "required" field will also
+// perform valdation so no additional checks are necessary.
+//
+// Also note that throwing an error inside a validator and passing
+// the "message" field result in an identical error message. In this
+// case we want the schema error messages to trickle down so using
+// the first style here.
+//
+// https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-validate
+function wrapMongooseValidator(schema) {
+  const validator = async (val) => {
+    await schema.validate(val);
+  };
+  validator.schema = schema;
+  return validator;
+}
+
+function getNamedSchema(name) {
+  const schema = namedSchemas[name];
+  if (!schema) {
+    throw new Error(`Cannot find schema for "${name}".`);
+  }
+  return schema;
+}

package/src/warn.js

@@ -0,0 +1,7 @@
+import logger from '@bedrockio/logger';
+
+export default function warn(...lines) {
+  if (process.env.ENV_NAME !== 'test') {
+    logger.warn(lines.join('\n'));
+  }
+}