feat(schema): add alias() method that makes it easier to define multiple aliases for a given path

lib/schema.js

@@ -170,17 +170,50 @@ function Schema(obj, options) {
  * @api private
  */
 function aliasFields(schema, paths) {
-  paths = paths || Object.keys(schema.paths);
-  for (const path of paths) {
-    const options = get(schema.paths[path], 'options');
-    if (options == null) {
+  for (const path of Object.keys(paths)) {
+    let alias = null;
+    if (typeof paths[path] === 'string') {
+      alias = paths[path];
+    } else {
+      const options = get(schema.paths[path], 'options');
+      if (options == null) {
+        continue;
+      }
+
+      alias = options.alias;
+    }
+
+    if (!alias) {
       continue;
     }
 
     const prop = schema.paths[path].path;
-    const alias = options.alias;
 
-    if (!alias) {
+    if (Array.isArray(alias)) {
+      for (const a of alias) {
+        if (typeof a !== 'string') {
+          throw new Error('Invalid value for alias option on ' + prop + ', got ' + a);
+        }
+
+        schema.aliases[a] = prop;
+
+        schema.
+          virtual(a).
+          get((function(p) {
+            return function() {
+              if (typeof this.get === 'function') {
+                return this.get(p);
+              }
+              return this[p];
+            };
+          })(prop)).
+          set((function(p) {
+            return function(v) {
+              return this.$set(p, v);
+            };
+          })(prop));
+      }
+
       continue;
     }
 
@@ -659,9 +692,50 @@ Schema.prototype.add = function add(obj, prefix) {
     }
   }
 
-  const addedKeys = Object.keys(obj).
-    map(key => prefix ? prefix + key : key);
-  aliasFields(this, addedKeys);
+  const aliasObj = Object.fromEntries(
+    Object.entries(obj).map(([key]) => ([prefix + key, null]))
+  );
+  aliasFields(this, aliasObj);
+  return this;
+};
+
+/**
+ * Add an alias for `path`. This means getting or setting the `alias`
+ * is equivalent to getting or setting the `path`.
+ *
+ * #### Example:
+ *
+ *     const toySchema = new Schema({ n: String });
+ *
+ *     // Make 'name' an alias for 'n'
+ *     toySchema.alias('n', 'name');
+ *
+ *     const Toy = mongoose.model('Toy', toySchema);
+ *     const turboMan = new Toy({ n: 'Turbo Man' });
+ *
+ *     turboMan.name; // 'Turbo Man'
+ *     turboMan.n; // 'Turbo Man'
+ *
+ *     turboMan.name = 'Turbo Man Action Figure';
+ *     turboMan.n; // 'Turbo Man Action Figure'
+ *
+ *     await turboMan.save(); // Saves { _id: ..., n: 'Turbo Man Action Figure' }
+ *
+ *
+ * @param {String} path real path to alias
+ * @param {String|String[]} alias the path(s) to use as an alias for `path`
+ * @return {Schema} the Schema instance
+ * @api public
+ */
+
+Schema.prototype.alias = function alias(path, alias) {
+  if (Array.isArray(alias)) {
+    for (const a of alias) {
+      this.alias(path, a);
+    }
+    return this;
+  }
+  aliasFields(this, { [path]: alias });
   return this;
 };
 

test/schema.alias.test.js

@@ -159,4 +159,34 @@ describe('schema alias option', function() {
     done();
     // acquit:ignore:end
   });
+
+  it('array of aliases (gh-12368)', function() {
+    const productSchema = new Schema({
+      n: {
+        type: String,
+        alias: ['name', 'product_name']
+      }
+    });
+
+    const Product = db.model('Test', productSchema);
+    const doc = new Product({});
+
+    doc['product_name'] = 'Turbo Man';
+    assert.equal(doc.n, 'Turbo Man');
+    assert.equal(doc.name, 'Turbo Man');
+  });
+
+  it('alias() method (gh-12368)', function() {
+    const schema = new Schema({ name: String });
+
+    schema.alias('name', 'otherName');
+    assert.equal(schema.aliases['otherName'], 'name');
+    assert.ok(schema.virtuals['otherName']);
+
+    schema.alias('name', ['name1', 'name2']);
+    assert.equal(schema.aliases['name1'], 'name');
+    assert.equal(schema.aliases['name2'], 'name');
+    assert.ok(schema.virtuals['name1']);
+    assert.ok(schema.virtuals['name2']);
+  });
 });

types/index.d.ts

@@ -196,6 +196,12 @@ declare module 'mongoose' {
     /** Adds key path / schema type pairs to this schema. */
     add(obj: SchemaDefinition<SchemaDefinitionType<EnforcedDocType>> | Schema, prefix?: string): this;
 
+    /**
+     * Add an alias for `path`. This means getting or setting the `alias`
+     * is equivalent to getting or setting the `path`.
+     */
+    alias(path: string, alias: string | string[]): this;
+
     /**
      * Array of child schemas (from document arrays and single nested subdocs)
      * and their corresponding compiled models. Each element of the array is

types/schematypes.d.ts

@@ -57,7 +57,7 @@ declare module 'mongoose' {
                               T | typeof SchemaType | Schema<any, any, any> | SchemaDefinition<T> | Function | AnyArray<Function>;
 
     /** Defines a virtual with the given name that gets/sets this path. */
-    alias?: string;
+    alias?: string | string[];
 
     /** Function or object describing how to validate this schematype. See [validation docs](https://mongoosejs.com/docs/validation.html). */
     validate?: SchemaValidator<T> | AnyArray<SchemaValidator<T>>;