Switch to a delayed transform function.

HISTORY.md

@@ -1,6 +1,10 @@
 History
 =======
 
+## 0.1.0
+
+* Add `transformMeta()` function. ([@zianwar][])
+
 ## 0.0.6
 
 * Permissively infer `error`, `warn|warning` levels for request logger. ([@slooker][])
@@ -34,3 +38,4 @@ History
 [@ryan-roemer]: https://github.com/ryan-roemer
 [@didebeach]: https://github.com/didebeach
 [@slooker]: https://github.com/slooker
+[@zianwar]: https://github.com/zianwar

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (C) 2013-2015 Formidable Labs, Inc.
+Copyright (C) 2013-2016 Formidable Labs, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -128,6 +128,7 @@ app.get("/foo", function (req, res) {
 * [`Log(opts, baseMeta)` - Logger class.](#-log-opts-basemeta-logger-class-)
 * [`Log.addMeta(meta)`](#-log-addmeta-meta-)
 * [`Log.addReq(req)`](#-log-addreq-req-)
+* [`Log.transformMeta(fn)`](#-log-transformmeta-fn-)
 * [`Log.addRes(res)`](#-log-addres-res-)
 * [`Log.addError(err)`](#-log-adderror-err-)
 
@@ -185,6 +186,19 @@ Add arbitrary meta to all subsequent log statements.
 
 Add request to meta.
 
+### `Log.transformMeta(fn)`
+
+Set a delayed single transform function to mutate a **copy** of the metadata
+_right before_ a logging event. You can only presently have **one** such
+function. And it is delayed so that for things like request end, you can
+effectively access **all** the metadata.
+
+The transform is applied on each log call and passes a copy of the mutated
+metadata to the actual log call.
+
+The function signature should be `fn(existingMeta)` and return mutated
+metadata.
+
 ### `Log.addRes(res)`
 
 Add response to meta.
@@ -208,7 +222,7 @@ We test all changes with [Travis CI][trav]. Here's our current
 [trav_site]: https://travis-ci.org/FormidableLabs/express-winston-middleware
 
 ## Licenses
-All code is 2013-2015 Formidable Labs.
+All code is 2013-2016 Formidable Labs.
 Released under the [MIT](./LICENSE.txt) License.
 
 [winston]: https://github.com/flatiron/winston

examples/server.js

@@ -35,6 +35,33 @@ app.get("/custom-logging", function (req, res) {
   });
   res.send("Custom message logged...");
 });
+app.get("/add-meta", function (req, res) {
+  res.locals._log
+    .addMeta({
+      extra: "addMeta-meta"
+    })
+    .info("This is the per-request logger object!");
+
+  res.send("Custom add-meta logged...");
+});
+app.get("/transform-meta", function (req, res) {
+  var log = res.locals._log
+    .transformMeta(function (meta) {
+      return {
+        oldReq: meta.req,
+        totallyNew: "totally new stuff"
+      };
+    });
+
+  log.info("This is the per-request logger object!");
+  log.warn("This is extra custom log with callback", function () {
+    // Do a console log so we don't have our logger everywhere...
+    console.log("CONSOLE: CALLED BACK");
+  });
+
+  res.send("Custom transform-meta logged...");
+});
+
 app.get("/error", function (req, res, next) {
   next(new Error("Error!"));
 });

index.html

@@ -120,6 +120,7 @@ <h2 id="api">API</h2>
 <li><a href="#-log-opts-basemeta-logger-class-"><code>Log(opts, baseMeta)</code> - Logger class.</a></li>
 <li><a href="#-log-addmeta-meta-"><code>Log.addMeta(meta)</code></a></li>
 <li><a href="#-log-addreq-req-"><code>Log.addReq(req)</code></a></li>
+<li><a href="#-log-transformmeta-fn-"><code>Log.transformMeta(fn)</code></a></li>
 <li><a href="#-log-addres-res-"><code>Log.addRes(res)</code></a></li>
 <li><a href="#-log-adderror-err-"><code>Log.addError(err)</code></a></li>
 </ul>
@@ -151,6 +152,15 @@ <h3 id="-log-addmeta-meta-"><code>Log.addMeta(meta)</code></h3>
 <p>Add arbitrary meta to all subsequent log statements.</p>
 <h3 id="-log-addreq-req-"><code>Log.addReq(req)</code></h3>
 <p>Add request to meta.</p>
+<h3 id="-log-transformmeta-fn-"><code>Log.transformMeta(fn)</code></h3>
+<p>Set a delayed single transform function to mutate a <strong>copy</strong> of the metadata
+<em>right before</em> a logging event. You can only presently have <strong>one</strong> such
+function. And it is delayed so that for things like request end, you can
+effectively access <strong>all</strong> the metadata.</p>
+<p>The transform is applied on each log call and passes a copy of the mutated
+metadata to the actual log call.</p>
+<p>The function signature should be <code>fn(existingMeta)</code> and return mutated
+metadata.</p>
 <h3 id="-log-addres-res-"><code>Log.addRes(res)</code></h3>
 <p>Add response to meta.</p>
 <h3 id="-log-adderror-err-"><code>Log.addError(err)</code></h3>
@@ -162,11 +172,15 @@ <h2 id="contributions">Contributions</h2>
 <a href="https://travis-ci.org/FormidableLabs/express-winston-middleware">build status</a>:</p>
 <p><a href="https://travis-ci.org/FormidableLabs/express-winston-middleware"><img src="https://api.travis-ci.org/FormidableLabs/express-winston-middleware.png" alt="Build Status"></a></p>
 <h2 id="licenses">Licenses</h2>
-<p>All code is 2013-2015 Formidable Labs.
+<p>All code is 2013-2016 Formidable Labs.
 Released under the <a href="./LICENSE.txt">MIT</a> License.</p>
 
         </div>
         <div id="history"><h1 id="history">History</h1>
+<h2 id="0-1-0">0.1.0</h2>
+<ul>
+<li>Add <code>transformMeta()</code> function. (<a href="https://github.com/zianwar">@zianwar</a>)</li>
+</ul>
 <h2 id="0-0-6">0.0.6</h2>
 <ul>
 <li>Permissively infer <code>error</code>, <code>warn|warning</code> levels for request logger. (<a href="https://github.com/slooker">@slooker</a>)

index.js

@@ -268,17 +268,25 @@ Log = function (opts, baseMeta) {
     }
   }, baseMeta);
 
+  // Passthrough transform function.
+  this._metaTransformFn = null;
+
   // Iterate and patch all log levels.
   _.each(this.levels, function (num, level) {
     self[level] = function (msg, metaOrCb, callback) {
       var meta = _.extend({ date: (new Date()).toISOString(), }, this._meta),
-        args = [msg, meta];
+        args;
 
       // Extend with user-passed meta, if applicable.
       if (_.isObject(metaOrCb)) {
         _.extend(meta, metaOrCb, {});
       }
 
+      // Apply final transform, if any.
+      if (self._metaTransformFn) {
+        meta = self._metaTransformFn(_.cloneDeep(meta));
+      }
+
       // Infer arguments per Winston calling conventions.
       if (arguments.length === 2 && _.isFunction(metaOrCb)) {
         // Push callback to end.
@@ -287,6 +295,10 @@ Log = function (opts, baseMeta) {
       } else if (arguments.length > 2) {
         // In order already.
         args = [msg, meta, callback];
+
+      } else {
+        // No callback.
+        args = [msg, meta];
       }
 
       // Call real logger.
@@ -339,13 +351,22 @@ Log.prototype.addReq = function (req) {
 /**
  * `Log.transformMeta(fn)`
  *
- * Transform meta.
+ * Set a delayed single transform function to mutate a **copy** of the metadata
+ * _right before_ a logging event. You can only presently have **one** such
+ * function. And it is delayed so that for things like request end, you can
+ * effectively access **all** the metadata.
+ *
+ * The transform is applied on each log call and passes a copy of the mutated
+ * metadata to the actual log call.
+ *
+ * The function signature should be `fn(existingMeta)` and return mutated
+ * metadata.
  *
  * @param {Function} fn Transform function.
  * @api public
  */
 Log.prototype.transformMeta = function (fn) {
-  this._meta = fn(this._meta);
+  this._metaTransformFn = fn;
 
   return this;
 };

test/log.spec.js

@@ -66,6 +66,10 @@ describe("Log", function () {
     it("should add tests here"); // TODO
   });
 
+  describe("#transformMeta", function () {
+    it("should add tests here"); // TODO
+  });
+
   describe("#addReq", function () {
     it("should add tests here"); // TODO
   });