fs: expose Stats times as Numbers

PR-URL: #13173Fixes: #8276 Refs: #12607 Refs: #12818 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Brian White <[email protected]>

Author: refack

doc/api/fs.md

@@ -301,10 +301,14 @@ argument to `fs.createReadStream()`. If `path` is passed as a string, then
 ## Class: fs.Stats
 <!-- YAML
 added: v0.1.21
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/13173
+ description: Added times as numbers.
 -->
 
-Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and their
-synchronous counterparts are of this type.
+Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and
+their synchronous counterparts are of this type.
 
 -`stats.isFile()`
 -`stats.isDirectory()`
@@ -329,20 +333,23 @@ Stats{
  size: 527,
  blksize: 4096,
  blocks: 8,
+ atimeMs: 1318289051000.1,
+ mtimeMs: 1318289051000.1,
+ ctimeMs: 1318289051000.1,
+ birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
 ```
 
-Please note that `atime`, `mtime`, `birthtime`, and `ctime` are
-instances of [`Date`][MDN-Date] object and appropriate methods should be used
-to compare the values of these objects. For most general uses
-[`getTime()`][MDN-Date-getTime] will return the number of milliseconds elapsed
-since _1 January 1970 00:00:00 UTC_ and this integer should be sufficient for
-any comparison, however there are additional methods which can be used for
-displaying fuzzy information. More details can be found in the
-[MDN JavaScript Reference][MDN-Date] page.
+*Note*: `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs` are [numbers][MDN-Number]
+that hold the corresponding times in milliseconds. Their precision is platform
+specific. `atime`, `mtime`, `ctime`, and `birthtime` are [`Date`][MDN-Date]
+object alternate representations of the various times. The `Date` and number
+values are not connected. Assigning a new number value, or mutating the `Date`
+value, will not be reflected in the corresponding alternate representation.
+
 
 ### Stat Time Values
 
@@ -2841,6 +2848,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [FS Constants]: #fs_fs_constants_1
 [MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
 [MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
+[MDN-Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
 [MSDN-Rel-Path]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx#fully_qualified_vs._relative_paths
 [Readable Stream]: stream.html#stream_class_stream_readable
 [Writable Stream]: stream.html#stream_class_stream_writable

lib/fs.js

@@ -196,6 +196,10 @@ function Stats(
 this.ino=ino;
 this.size=size;
 this.blocks=blocks;
+this.atimeMs=atim_msec;
+this.mtimeMs=mtim_msec;
+this.ctimeMs=ctim_msec;
+this.birthtimeMs=birthtim_msec;
 this.atime=newDate(atim_msec+0.5);
 this.mtime=newDate(mtim_msec+0.5);
 this.ctime=newDate(ctim_msec+0.5);

test/parallel/test-fs-stat.js

@@ -65,38 +65,55 @@ fs.open('.', 'r', undefined, common.mustCall(function(err, fd){
 assert.fail(err);
 }
 if(stats){
-console.dir(stats);
 assert.ok(stats.mtimeinstanceofDate);
 }
 fs.close(fd,assert.ifError);
 }));
 
-console.log(`stating: ${__filename}`);
 fs.stat(__filename,common.mustCall(function(err,s){
 assert.ifError(err);
-
-console.dir(s);
-
-console.log(`isDirectory: ${JSON.stringify(s.isDirectory())}`);
 assert.strictEqual(false,s.isDirectory());
-
-console.log(`isFile: ${JSON.stringify(s.isFile())}`);
 assert.strictEqual(true,s.isFile());
-
-console.log(`isSocket: ${JSON.stringify(s.isSocket())}`);
 assert.strictEqual(false,s.isSocket());
-
-console.log(`isBlockDevice: ${JSON.stringify(s.isBlockDevice())}`);
 assert.strictEqual(false,s.isBlockDevice());
-
-console.log(`isCharacterDevice: ${JSON.stringify(s.isCharacterDevice())}`);
 assert.strictEqual(false,s.isCharacterDevice());
-
-console.log(`isFIFO: ${JSON.stringify(s.isFIFO())}`);
 assert.strictEqual(false,s.isFIFO());
-
-console.log(`isSymbolicLink: ${JSON.stringify(s.isSymbolicLink())}`);
 assert.strictEqual(false,s.isSymbolicLink());
-
-assert.ok(s.mtimeinstanceofDate);
+constkeys=[
+'dev','mode','nlink','uid',
+'gid','rdev','ino','size',
+'atime','mtime','ctime','birthtime',
+'atimeMs','mtimeMs','ctimeMs','birthtimeMs'
+];
+if(!common.isWindows){
+keys.push('blocks','blksize');
+}
+constnumberFields=[
+'dev','mode','nlink','uid','gid','rdev','ino','size',
+'atimeMs','mtimeMs','ctimeMs','birthtimeMs'
+];
+constdateFields=['atime','mtime','ctime','birthtime'];
+keys.forEach(function(k){
+assert.ok(kins,`${k} should be in Stats`);
+assert.notStrictEqual(s[k],undefined,`${k} should not be undefined`);
+assert.notStrictEqual(s[k],null,`${k} should not be null`);
+});
+numberFields.forEach((k)=>{
+assert.strictEqual(typeofs[k],'number',`${k} should be a number`);
+});
+dateFields.forEach((k)=>{
+assert.ok(s[k]instanceofDate,`${k} should be a Date`);
+});
+constjsonString=JSON.stringify(s);
+constparsed=JSON.parse(jsonString);
+keys.forEach(function(k){
+assert.notStrictEqual(parsed[k],undefined,`${k} should not be undefined`);
+assert.notStrictEqual(parsed[k],null,`${k} should not be null`);
+});
+numberFields.forEach((k)=>{
+assert.strictEqual(typeofparsed[k],'number',`${k} should be a number`);
+});
+dateFields.forEach((k)=>{
+assert.strictEqual(typeofparsed[k],'string',`${k} should be a string`);
+});
 }));