feat(model): add applyTimestamps() function to apply all schema timestamps, including subdocuments, to a given POJO

lib/helpers/document/applyTimestamps.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const handleTimestampOption = require('../schema/handleTimestampOption');
+const mpath = require('mpath');
+
+module.exports = applyTimestamps;
+
+/**
+ * Apply a given schema's timestamps to the given POJO
+ *
+ * @param {Schema} schema
+ * @param {Object} obj
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ */
+
+function applyTimestamps(schema, obj, options) {
+  if (obj == null) {
+    return obj;
+  }
+
+  applyTimestampsToChildren(schema, obj, options);
+  return applyTimestampsToDoc(schema, obj, options);
+}
+
+/**
+ * Apply timestamps to any subdocuments
+ *
+ * @param {Schema} schema subdocument schema
+ * @param {Object} res subdocument
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ */
+
+function applyTimestampsToChildren(schema, res, options) {
+  for (const childSchema of schema.childSchemas) {
+    const _path = childSchema.model.path;
+    const _schema = childSchema.schema;
+    if (!_path) {
+      continue;
+    }
+    const _obj = mpath.get(_path, res);
+    if (_obj == null || (Array.isArray(_obj) && _obj.flat(Infinity).length === 0)) {
+      continue;
+    }
+
+    applyTimestamps(_schema, _obj, options);
+  }
+}
+
+/**
+ * Apply timestamps to a given document. Does not apply timestamps to subdocuments: use `applyTimestampsToChildren` instead
+ *
+ * @param {Schema} schema
+ * @param {Object} obj
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ */
+
+function applyTimestampsToDoc(schema, obj, options) {
+  if (obj == null || typeof obj !== 'object') {
+    return;
+  }
+  if (Array.isArray(obj)) {
+    for (const el of obj) {
+      applyTimestampsToDoc(schema, el, options);
+    }
+    return;
+  }
+
+  if (schema.discriminators && Object.keys(schema.discriminators).length > 0) {
+    for (const discriminatorKey of Object.keys(schema.discriminators)) {
+      const discriminator = schema.discriminators[discriminatorKey];
+      const key = discriminator.discriminatorMapping.key;
+      const value = discriminator.discriminatorMapping.value;
+      if (obj[key] == value) {
+        schema = discriminator;
+        break;
+      }
+    }
+  }
+
+  const createdAt = handleTimestampOption(schema.options.timestamps, 'createdAt');
+  const updatedAt = handleTimestampOption(schema.options.timestamps, 'updatedAt');
+  const currentTime = options?.currentTime;
+
+  let ts = null;
+  if (currentTime != null) {
+    ts = currentTime();
+  } else if (schema.base?.now) {
+    ts = schema.base.now();
+  } else {
+    ts = new Date();
+  }
+
+  if (createdAt && obj[createdAt] == null && !options?.isUpdate) {
+    obj[createdAt] = ts;
+  }
+  if (updatedAt) {
+    obj[updatedAt] = ts;
+  }
+}

lib/model.js

@@ -30,6 +30,7 @@ const applyReadConcern = require('./helpers/schema/applyReadConcern');
 const applySchemaCollation = require('./helpers/indexes/applySchemaCollation');
 const applyStaticHooks = require('./helpers/model/applyStaticHooks');
 const applyStatics = require('./helpers/model/applyStatics');
+const applyTimestampsHelper = require('./helpers/document/applyTimestamps');
 const applyWriteConcern = require('./helpers/schema/applyWriteConcern');
 const applyVirtualsHelper = require('./helpers/document/applyVirtuals');
 const assignVals = require('./helpers/populate/assignVals');
@@ -3541,6 +3542,41 @@ Model.applyVirtuals = function applyVirtuals(obj, virtualsToApply) {
   return obj;
 };
 
+/**
+ * Apply this model's timestamps to a given POJO, including subdocument timestamps
+ *
+ * #### Example:
+ *
+ *     const userSchema = new Schema({ name: String }, { timestamps: true });
+ *     const User = mongoose.model('User', userSchema);
+ *
+ *     const obj = { name: 'John' };
+ *     User.applyTimestamps(obj);
+ *     obj.createdAt; // 2024-06-01T18:00:00.000Z
+ *     obj.updatedAt; // 2024-06-01T18:00:00.000Z
+ *
+ * @param {Object} obj object or document to apply virtuals on
+ * @param {Object} [options]
+ * @param {Boolean} [options.isUpdate=false] if true, treat this as an update: just set updatedAt, skip setting createdAt. If false, set both createdAt and updatedAt
+ * @param {Function} [options.currentTime] if set, Mongoose will call this function to get the current time.
+ * @returns {Object} obj
+ * @api public
+ */
+
+Model.applyTimestamps = function applyTimestamps(obj, options) {
+  if (obj == null) {
+    return obj;
+  }
+  // Nothing to do if this is already a hydrated document - it should already have timestamps
+  if (obj.$__ != null) {
+    return obj;
+  }
+
+  applyTimestampsHelper(this.schema, obj, options);
+
+  return obj;
+};
+
 /**
  * Cast the given POJO to the model's schema
  *

test/model.test.js

@@ -8018,6 +8018,110 @@ describe('Model', function() {
       assert.strictEqual(res.friend, null);
     });
   });
+
+  describe('applyTimestamps', function() {
+    it('handles basic top-level timestamps', async function() {
+      const startTime = new Date();
+      const userSchema = new Schema({
+        name: String
+      }, { timestamps: true });
+      const User = db.model('User', userSchema);
+
+      const obj = { name: 'test' };
+      User.applyTimestamps(obj);
+      assert.equal(obj.name, 'test');
+      assert.ok(obj.createdAt instanceof Date);
+      assert.ok(obj.updatedAt instanceof Date);
+      assert.ok(obj.createdAt.valueOf() >= startTime.valueOf());
+      assert.ok(obj.updatedAt.valueOf() >= startTime.valueOf());
+    });
+
+    it('no-op if timestamps not set', async function() {
+      const userSchema = new Schema({
+        name: String
+      });
+      const User = db.model('User', userSchema);
+
+      const obj = { name: 'test' };
+      User.applyTimestamps(obj);
+      assert.equal(obj.name, 'test');
+      assert.ok(!('createdAt' in obj));
+      assert.ok(!('updatedAt' in obj));
+    });
+
+    it('handles custom timestamp property names', async function() {
+      const startTime = new Date();
+      const userSchema = new Schema({
+        name: String
+      }, { timestamps: { createdAt: 'createdOn', updatedAt: 'updatedOn' } });
+      const User = db.model('User', userSchema);
+
+      const obj = { name: 'test' };
+      User.applyTimestamps(obj);
+      assert.equal(obj.name, 'test');
+      assert.ok(obj.createdOn instanceof Date);
+      assert.ok(obj.updatedOn instanceof Date);
+      assert.ok(obj.createdOn.valueOf() >= startTime.valueOf());
+      assert.ok(obj.updatedOn.valueOf() >= startTime.valueOf());
+      assert.ok(!('createdAt' in obj));
+      assert.ok(!('updatedAt' in obj));
+    });
+
+    it('applies timestamps to subdocs', async function() {
+      const startTime = new Date();
+      const userSchema = new Schema({
+        name: String,
+        posts: [new Schema({
+          title: String,
+          content: String
+        }, { timestamps: true })],
+        address: new Schema({
+          city: String,
+          country: String
+        }, { timestamps: true })
+      }, { timestamps: true });
+      const User = db.model('User', userSchema);
+
+      const obj = {
+        name: 'test',
+        posts: [{ title: 'Post 1', content: 'Content 1' }],
+        address: { city: 'New York', country: 'USA' }
+      };
+      User.applyTimestamps(obj);
+      assert.equal(obj.name, 'test');
+      assert.ok(obj.createdAt instanceof Date);
+      assert.ok(obj.updatedAt instanceof Date);
+      assert.ok(obj.createdAt.valueOf() >= startTime.valueOf());
+      assert.ok(obj.updatedAt.valueOf() >= startTime.valueOf());
+      assert.ok(obj.posts[0].createdAt instanceof Date);
+      assert.ok(obj.posts[0].updatedAt instanceof Date);
+      assert.ok(obj.address.createdAt instanceof Date);
+      assert.ok(obj.address.updatedAt instanceof Date);
+    });
+
+    it('supports isUpdate and currentTime options', async function() {
+      const userSchema = new Schema({
+        name: String,
+        post: new Schema({
+          title: String,
+          content: String
+        }, { timestamps: true })
+      }, { timestamps: true });
+      const User = db.model('User', userSchema);
+
+      const obj = {
+        name: 'test',
+        post: { title: 'Post 1', content: 'Content 1' }
+      };
+      User.applyTimestamps(obj, { isUpdate: true, currentTime: () => new Date('2023-06-01T18:00:00.000Z') });
+      assert.equal(obj.name, 'test');
+      assert.ok(!('createdAt' in obj));
+      assert.ok(obj.updatedAt instanceof Date);
+      assert.equal(obj.updatedAt.valueOf(), new Date('2023-06-01T18:00:00.000Z').valueOf());
+      assert.ok(!('createdAt' in obj.post));
+      assert.ok(obj.post.updatedAt.valueOf(), new Date('2023-06-01T18:00:00.000Z').valueOf());
+    });
+  });
 });
 
 

types/models.d.ts

@@ -293,6 +293,11 @@ declare module 'mongoose' {
     /* Apply virtuals to the given POJO. */
     applyVirtuals(obj: AnyObject, virtalsToApply?: string[]): AnyObject;
 
+    /**
+     * Apply this model's timestamps to a given POJO, including subdocument timestamps
+     */
+    applyTimestamps(obj: AnyObject, options?: { isUpdate?: boolean, currentTime?: () => Date }): AnyObject;
+
     /**
      * Sends multiple `insertOne`, `updateOne`, `updateMany`, `replaceOne`,
      * `deleteOne`, and/or `deleteMany` operations to the MongoDB server in one