@janiscommerce/log - npm Package Compare versions

Comparing version 3.3.0 to 3.4.0

CHANGELOG.md

@@ -10,2 +10,10 @@ # Changelog
 
+## [3.4.0] - 2021-04-27
+### Added
+- `Log.createTracker()` to generate an incremental log
+- TS typings
+
+### Changed
+- CI is now done using github actions
+
 ## [3.3.0] - 2020-07-29
@@ -12,0 +20,0 @@ ### Added

lib/helpers/validator.js

@@ -10,10 +10,10 @@ 'use strict';
 const logStruct = {
-	id: 'string',
-	service: 'string',
-	entity: 'string',
+	id: 'string&!empty',
+	service: 'string&!empty',
+	entity: 'string&!empty',
 	entityId: 'string?|number?',
-	type: 'string',
+	type: 'string&!empty',
 	log: 'object?|array?',
 	message: 'string?',
-	client: 'string',
+	client: 'string&!empty',
 	userCreated: 'string?'
@@ -20,0 +20,0 @@ };

lib/log.js

 'use strict';
 
-const EventEmmiter = require('events');
+/**
+ * @typedef {object} LogData
+ * @property {string} type
+ * @property {string} entity
+ * @property {string} entityId
+ * @property {string} [message]
+ * @property {object} log
+ */
+
+/**
+ * This callback is displayed as part of the Requester class.
+ * @callback LogEventEmitterCallback
+ * @param {Array<LogData>} failedLogs
+ * @param {LogError} error
+ * @returns {void}
+ */
+
+const { ApiSession } = require('@janiscommerce/api-session');
+
+const EventEmitter = require('events');
 const { arrayChunk } = require('./helpers/utils');
@@ -9,4 +28,4 @@ const Validator = require('./helpers/validator');
 const FirehoseInstance = require('./firehose-instance');
+const LogTracker = require('./log-tracker');
 
-
 const MAX_ATTEMPTS = 3;
@@ -16,7 +35,11 @@ const DELIVERY_STREAM_PREFIX = 'JanisTraceFirehose';
 
+const emitter = new EventEmitter();
 
-const emitter = new EventEmmiter();
-
 class Log {
 
+	/**
+	 * @readonly
+	 * @static
+	 * @returns {string} The service name as defined in the env var JANIS_SERVICE_NAME
+	 */
 	static get serviceName() {
@@ -26,2 +49,7 @@ return process.env.JANIS_SERVICE_NAME;
 
+	/**
+	 * @readonly
+	 * @static
+	 * @returns {string} The environment name as defined in the env var JANIS_ENV
+	 */
 	static get env() {
@@ -31,2 +59,7 @@ return process.env.JANIS_ENV;
 
+	/**
+	 * @readonly
+	 * @static
+	 * @returns{object<string, string>} A key-value object of environments and their friendly name
+	 */
 	static get envs() {
@@ -42,2 +75,7 @@
 
+	/**
+	 * @readonly
+	 * @static
+	 * @returns {string} The AWS CloudWatch Logs stream name based on current env
+	 */
 	static get deliveryStreamName() {
@@ -51,2 +89,8 @@
 
+	/**
+	 * @readonly
+	 * @static
+	 * @returns {string} The friendly name of the current env
+	 * @throws {LogError} If current env is not defined or it's invalid
+	 */
 	static get formattedEnv() {
@@ -62,6 +106,8 @@
 	 * Sets a callback for the specified event name
-	 * @param {String} event The event name
-	 * @param {Function} callback The event callback
+	 *
+	 * @static
+	 * @param {string} event The event name
+	 * @param {LogEventEmitterCallback} callback The event callback
 	 * @example
-	 * on('create-error', (log, err) => {...});
+	 * Log.on('create-error', (logs, err) => {...});
 	 */
@@ -74,6 +120,10 @@ static on(event, callback) {
 	 * Put logs into Firehose
-	 * @param {String} client The client code who created the log
-	 * @param {Object|Array.<object>} logs The log object or log objects array
+	 *
+	 * @static
+	 * @param {string} client The client code who created the log
+	 * @param {LogData|Array.<LogData>} logs The log object or log objects array
+	 * @returns {Promise<void>}
+	 *
 	 * @example
-	 * add('some-client', {
+	 * Log.add('some-client', {
 	 * 	type: 'some-type',
@@ -111,2 +161,9 @@ * 	entity: 'some-entity',
 
+	/**
+	 * @private
+	 * @static
+	 * @param {LogData} log
+	 * @param {string} client
+	 * @returns
+	 */
 	static validateLog(log, client) {
@@ -116,2 +173,8 @@ return Validator.validate(log, client, this.serviceName);
 
+	/**
+	 * @private
+	 * @static
+	 * @param {Array<LogData>} logs
+	 * @returns {Array<Array<LogData>>}
+	 */
 	static createLogsBatches(logs) {
@@ -121,2 +184,9 @@ return arrayChunk(logs, LOGS_BATCH_LIMIT);
 
+	/**
+	 * @private
+	 * @static
+	 * @param {Array<Array<LogData>>} logsBatches
+	 * @param {number} [attempts = 0]
+	 * @returns
+	 */
 	static async _add(logsBatches, attempts = 0) {
@@ -157,3 +227,3 @@
 	 * @static
-	 * @memberof Log
+	 * @returns {Array}
 	 */
@@ -163,4 +233,14 @@ static get serverlessConfiguration() {
 	}
+
+	/**
+	 * @static
+	 * @param {string} clientCode The client code who created the log
+	 * @returns {import('./log-tracker')}
+	 */
+	static createTracker(clientCode) {
+		const apiSession = new ApiSession({ clientCode });
+		return apiSession.getSessionInstance(LogTracker, this);
+	}
 }
 
 module.exports = Log;

package.json

 {
   "name": "@janiscommerce/log",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "A package for creating logs in Firehose",
-  "main": "lib/log.js",
+  "main": "lib/index.js",
   "scripts": {
-    "test": "export TEST_ENV=true; mocha --exit -R nyan --recursive tests/",
-    "test-ci": "nyc --reporter=html --reporter=text mocha --recursive tests/",
-    "watch-test": "export TEST_ENV=true; mocha --exit -R nyan -w --recursive tests/",
+    "test": "export TEST_ENV=true; mocha --exit -R nyan --recursive tests/ --require tests/bootstrap",
+    "coverage-ci": "nyc --reporter=lcov --reporter=text-summary mocha --exit --recursive tests/",
+    "watch-test": "export TEST_ENV=true; mocha --exit -R nyan -w --recursive tests/ --require tests/bootstrap",
     "coverage": "nyc npm test",
-    "lint": "eslint lib/ tests/"
+    "lint": "eslint lib/ tests/",
+    "build-types": "tsc lib/index.js --declaration --allowJs --emitDeclarationOnly --outDir types"
   },
@@ -21,2 +22,3 @@ "repository": {
   "devDependencies": {
+    "@types/node": "^15.0.0",
     "eslint": "^7.5.0",
@@ -26,10 +28,12 @@ "eslint-config-airbnb-base": "^13.1.0",
     "husky": "^4.2.5",
-    "md5": "^2.2.1",
     "mocha": "^7.1.1",
     "nyc": "^15.1.0",
-    "sinon": "^9.0.2"
+    "sinon": "^9.0.2",
+    "typescript": "^4.2.4"
   },
   "files": [
-    "lib/"
+    "lib/",
+    "types/"
   ],
+  "types": "types/index.d.ts",
   "directories": {
@@ -39,2 +43,3 @@ "test": "tests"
   "dependencies": {
+    "@janiscommerce/api-session": "^3.1.1",
     "@janiscommerce/settings": "^1.0.1",
@@ -41,0 +46,0 @@ "@janiscommerce/superstruct": "^1.1.1",

README.md

@@ -60,2 +60,26 @@ # log
 
+### **`createTracker(clientCode)`**
+Parameters: `clientCode [String]`
+Create a new tracker to build an incremental log. It returns a [LogTracker](#log-tracker) instance
+
+## Log Tracker
+
+A log tracker is an object used to build an incremental log to track multiple states of a process. For example, if when you publish a product you can track the initial state of the product, then request that will be made and the response received. Finally you save everything in a log to keep track for debugging purposes.
+
+To use a log tracker, you have to call the `Log.createTracker()` method, which will return an instance of a tracker.
+Then you can make as much calls to `logTracker.add()` as you want.
+When you're ready to save the log, simply call the `logTracker.log()` method.
+
+Each time you call the `log()` method, the internal state is reset so you can re-use the instance in case you want to.
+
+See the Log Tracker API below:
+
+### **`add(name, data)`**
+Parameters: `name [String]`, `data [Object]`
+Saves the `data` object associated with a `name` that explains what it is.
+
+### **`log(logData)`**
+Parameters: `logData [LogData]`.
+Saves the log with the properties passed as LogData. These are the same that are passed to `Log.add()`, except for the `log` property that will be overriden.
+
 ## Errors
@@ -150,5 +174,25 @@
 
+// Log creation error handling
 Log.on('create-error', (log, err) => {
 	console.error(`An error occurred while creating the log ${err.message}`);
 });
+
+// Incremental logs, during a map-reduce operation
+const logTracker = Log.createTracker('some-client');
+
+const numbers = [1, 2, 3];
+logTracker.add('initialState', numbers);
+
+const doubledNumbers = numbers.map(n => n * 2);
+logTracker.add('intermediateState', doubledNumbers);
+
+const sum = doubledNumbers.reduce((total, n) => total + n, 0);
+logTracker.add('finalState', sum);
+
+await logTracker.log({
+  entity: 'math',
+  entityId: 'someId',
+  type: 'map-reduce',
+  message: 'Map reduced to sum the double of some numbers'
+});
 ```
@@ -155,0 +199,0 @@

No alert changes

Improved metrics

Total package byte prevSize

26337

increased by67.66%

Number of package files

21

increased by110%

Lines of code

606

increased by115.66%

Number of lines in readme file

216

increased by25.58%

Worsened metrics

Dependency count

5

increased by25%

Dev dependency count

9

increased by12.5%

Dependency changes

• + Added@janiscommerce/api-session@^3.1.1

• + Added@janiscommerce/api-session@3.4.0(transitive)

• + Addedlllog@1.1.2(transitive)