allow returning file details in JSON

README.md

@@ -34,6 +34,7 @@ the express example).
 
 Serve index accepts these properties in the options object.
 
+
 ##### filter
 
 Apply this filter function to files. Defaults to `false`. The `filter` function
@@ -50,6 +51,17 @@ Display hidden (dot) files. Defaults to `false`.
 
 Display icons. Defaults to `false`.
 
+##### jsonStats
+
+Enables detailed information to be served via JSON when the request header includes `Accept: application/json`. Defaults to `false`.
+
+When this flag is disabled, JSON requests will return a simple array of filenames. With this flag enabled, JSON requests will return an array of objects, each containing objects with the following properties:
+
+ - `name` is the relative name for the file.
+ - `stat` is subset of the `fs.Stats` object for the file.
+
+The following "safe" properties will be present as file stats: `isFile`,`isDirectory`,`size`, `atime`, `mtime`, `ctime` and `birthtime`.
+
 ##### stylesheet
 
 Optional path to a CSS stylesheet. Defaults to a built-in stylesheet.

index.js

@@ -91,6 +91,7 @@ function serveIndex(root, options) {
  // resolve root to absolute and normalize
  var rootPath = normalize(resolve(root) + sep);
 
+ var jsonStats = opts.jsonStats || false;
  var filter = opts.filter;
  var hidden = opts.hidden;
  var icons = opts.icons;
@@ -160,7 +161,7 @@ function serveIndex(root, options) {
 
  // not acceptable
  if (!type) return next(createError(406));
- serveIndex[mediaType[type]](req, res, files, next, originalDir, showUp, icons, path, view, template, stylesheet);
+ serveIndex[mediaType[type]](req, res, files, next, originalDir, showUp, icons, path, view, template, stylesheet, jsonStats);
  });
  });
  };
@@ -222,13 +223,47 @@ serveIndex.html = function _html(req, res, files, next, dir, showUp, icons, path
  * Respond with application/json.
  */
 
-serveIndex.json = function _json(req, res, files) {
- var body = JSON.stringify(files);
- var buf = new Buffer(body, 'utf8');
+serveIndex.json = function _json(req, res, files, next, dir, showUp, icons, path, view, template, stylesheet, jsonStats) {
 
- res.setHeader('Content-Type', 'application/json; charset=utf-8');
- res.setHeader('Content-Length', buf.length);
- res.end(buf);
+ if (! jsonStats) {
+ //return the simple file list with no stats
+ var body = JSON.stringify(files);
+ var buf = new Buffer(body, 'utf8');
+ res.setHeader('Content-Type', 'application/json; charset=utf-8');
+ res.setHeader('Content-Length', buf.length);
+ res.end(buf);
+ }
+
+ else {
+ // stat all files
+ stat(path, files, function (err, stats) {
+ if (err) return next(err);
+
+ // combine the stats into the file list
+ var filesAndStats = files.map(function (file, i) {
+ var stat = {}; 
+
+ stat["isDirectory"] = stats[i].isDirectory();
+ stat["isFile"] = stats[i].isFile();
+
+ //next select only the safe and non-machine-specific fields from the stat
+ var safeFields = ["size", "atime", "mtime", "ctime", "birthtime"]
+ safeFields.forEach(function (field) {
+ stat[field] = stats[i][field];
+ });
+
+ return { name: file, stat: stat };
+ });
+
+
+ //return the file list with stats
+ var body = JSON.stringify(filesAndStats);
+ var buf = new Buffer(body, 'utf8');
+ res.setHeader('Content-Type', 'application/json; charset=utf-8');
+ res.setHeader('Content-Length', buf.length);
+ res.end(buf);
+ });
+ }
 };
 
 /**

test/test.js

@@ -677,6 +677,74 @@ describe('serveIndex(root)', function () {
  });
  });
 
+ describe('when Accept: application/json is given', function () {
+ describe('when requesting file stats via JSON', function() {
+ it('should correctly identify files and directories', function (done) {
+
+ var server = createServer(fixtures, {'jsonStats': true});
+
+ request(server)
+ .get('/')
+ .set('Accept', 'application/json')
+ .expect('Content-Type', /json/)
+ .expect(hasTodoStats)
+ .expect(hasUserStats)
+ .expect(200, done);
+
+ function hasTodoStats(res) {
+ //check the todo.txt record
+ var todo = res.body.find(function(value) {
+ return value.name == "todo.txt";
+ })
+
+ if (! todo.stat.size == 11)
+ throw new Error("'todo.txt' size should be 11");
+ if (! todo.stat.isFile)
+ throw new Error("'todo.txt' isFile should be true");
+ if (todo.stat.isDirectory)
+ throw new Error("'todo.txt' isDirectory should be false");
+ }
+
+ function hasUserStats(res) { 
+ //check the users record 
+ var users = res.body.find(function(value) {
+ return value.name == "users";
+ });
+
+ if (users.stat.isFile)
+ throw new Error("'users' isFile should be false");
+ if (!users.stat.isDirectory)
+ throw new Error("'users' isDirectory should be true");
+ }
+ });
+
+ it('should not return unsafe stats', function (done) {
+
+ var server = createServer(fixtures, {'jsonStats': true});
+
+ request(server)
+ .get('/')
+ .set('Accept', 'application/json')
+ .expect('Content-Type', /json/)
+ .expect(noUnsafeStats)
+ .expect(200, done);
+
+ function noUnsafeStats(res) { 
+ var safeFields = ["isFile","isDirectory","size", "atime", "mtime", "ctime", "birthtime"];
+
+ res.body.forEach(function (item) {
+ safeFields.forEach(function (field) {
+ delete item.stat[field];
+ });
+
+ if (Object.keys(item.stat).length>0)
+ throw new Error("stats contains unsafe keys");
+ });
+ }
+ });
+
+ });
+ });
  describe('when set with trailing slash', function () {
  var server;
  before(function () {