From 5f6029bc6c75708175ade99f6c44beb1d0e2817a Mon Sep 17 00:00:00 2001
From: Justin Wind <justin.wind+git@gmail.com>
Date: Mon, 29 May 2023 11:08:55 -0700
Subject: [PATCH] update documentation

---
 README.md              | 28 ++++++++++++++++++----------
 lib/data-sanitizers.js | 23 +++++++++++++++--------
 package.json           |  7 ++++---
 3 files changed, 37 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 9188471..d517752 100644
--- a/README.md
+++ b/README.md
@@ -4,18 +4,26 @@ A simple logger class, which mostly just structures messages, data, and some met
 
 Supports basic scrubbing of well-defined sensitive fields, and an extensible set of JSON replacer functions for common objects.
 
-If provided with an asyncLocalStorage instance, it expects a stored object which will be spread over the resulting logged json, taking precedence.
+If provided with an asyncLocalStorage instance, it expects a stored object which will be spread over the resulting logged JSON.
 
-Intended to be specific to Squeep Framework Applications, this module has opinions.
+Intended to be specific to Squeep Framework Applications, this module has some opinions.
 
 ## API
 
-Expects these arguments in any log call:
-
-- `scope` - e.g. file:method
-- `message` - text
-- `data` - object
-- any additional arguments are included as an array, but not scrubbed
+- `new Logger(options, commonObject, asyncLocalStorage, backend)`
+  - `commonObject` will be merged into every log
+  - `asyncLocalStorage`, if provided, should store an object, which will also be merged into log
+  - `backend` is `console` by default, but may be anything implementing the same log-level functions
+
+- `error(scope, message, data, ...)`
+  - `scope` - identifies source of message, e.g. 'class:method'
+  - `message` - text to be logged
+  - `data` - object to be logged, can be scrubbed of sensitive fields, and will be serialized with provided replacers
+  - any additional arguments are included as an array
+- `warn(scope, message, data, ...)`
+- `info(scope, message, data, ...)`
+- `log(scope, message, data, ...)`
+- `debug(scope, message, data, ...)`
 
 ## JSON Replacers
 
@@ -27,11 +35,11 @@ Includes replacers for these objects:
 - http.OutgoingMessage
 - http.ServerResponse
 
-Custom replacers may be inserted into the logger instance's `jsonReplacers` array.
+Additional replacers may be inserted into the logger instance's `jsonReplacers` array.
 
 ## Data Sanitizers
 
-Custom sanitizers may be inserted into the logger instance's `dataSanitizers` array.
+Sanitizers may be inserted into the logger instance's `dataSanitizers` array.
 
 ## Example
 
diff --git a/lib/data-sanitizers.js b/lib/data-sanitizers.js
index e4d0f3c..bf04950 100644
--- a/lib/data-sanitizers.js
+++ b/lib/data-sanitizers.js
@@ -1,25 +1,32 @@
 'use strict';
 
 /**
- * Here are some sanitizers to replace data fields before logging.
- * Well, really, this just documents the expected format.
+ * Sanitizers replace data fields before logging.
+ * None are bundled, but here is an example of one.
  */
 
 /**
- * template for sanitizers
+ * Example sanitizer function.
+ * Sanitizers are called initially with `sanitize` false, to only determine
+ * whether the data object will be changed.  If so, the sanitizer is then
+ * called again with `sanitize` true, but provided with a clone of the
+ * original data to update, to avoid leaking any applied changes back to the
+ * application.
  * @param {Object} data
  * @param {Boolean} sanitize
- * @returns {Boolean}
+ * @returns {Boolean} whether sanitizer is applicable to data
  */
 /* istanbul ignore next */
 function _sanitizer(data, sanitize = true) {
   let unclean = false;
 
-  if (undefined) { // eslint-disable-line no-constant-condition
+  const sensitiveFieldLength = data?.sensitiveField?.length;
+  if (sensitiveFieldLength) {
     unclean = true;
-  }
-  if (unclean && sanitize) {
-    data;
+
+    if (sanitize) {
+      data.sensitiveField = '*'.repeat(sensitiveFieldLength);
+    }
   }
 
   return unclean;
diff --git a/package.json b/package.json
index 87af158..05b6981 100644
--- a/package.json
+++ b/package.json
@@ -4,10 +4,10 @@
   "engines": {
     "node": ">=14"
   },
-  "description": "A simple logger which spews JSON to stdout; intended for use in Squeep Framework Applications.",
+  "description": "A simple logger which spews formatted data and metadata as JSON to stdout; intended for use in Squeep Framework Applications.",
   "main": "index.js",
   "scripts": {
-    "coverage": "nyc npm test",
+    "coverage": "nyc --clean npm test",
     "coverage-check": "nyc check-coverage",
     "eslint": "eslint *.js lib",
     "test": "mocha --recursive"
@@ -18,7 +18,8 @@
   },
   "keywords": [
     "json",
-    "log"
+    "log",
+    "structured logging"
   ],
   "author": "Justin Wind <jwind-npm@squeep.com>",
   "license": "ISC",
-- 
2.45.2