feat: release first version

.babelrc

@@ -0,0 +1,33 @@
+{
+  "env": {
+    "development": {
+      "plugins": [
+        "transform-object-rest-spread",
+        "transform-flow-comments"
+      ]
+    },
+    "production": {
+      "plugins": [
+        "transform-object-rest-spread",
+        "transform-flow-comments"
+      ]
+    },
+    "test": {
+      "plugins": [
+        "transform-object-rest-spread",
+        "transform-flow-strip-types",
+        "istanbul"
+      ]
+    }
+  },
+  "presets": [
+    [
+      "env",
+      {
+        "browsers": [
+          ">1%"
+        ]
+      }
+    ]
+  ]
+}

.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2

.eslintrc

@@ -0,0 +1,7 @@
+{
+  "extends": [
+    "canonical",
+    "canonical/flowtype"
+  ],
+  "root": true
+}

.flowconfig

@@ -0,0 +1,7 @@
+[ignore]
+.*/node_modules/.*/test/.*
+.*/node_modules/babel-plugin-flow-runtime/.*
+.*/node_modules/config-chain/.*
+.*/node_modules/conventional-changelog-core/.*
+.*/node_modules/flow-runtime/.*
+.*/node_modules/npmconf/.*

.gitignore

@@ -0,0 +1,13 @@
+coverage
+dist
+node_modules
+*.log
+.*
+!.babelrc
+!.editorconfig
+!.eslintignore
+!.eslintrc
+!.flowconfig
+!.gitignore
+!.npmignore
+!.travis.yml

.npmignore

@@ -0,0 +1,5 @@
+src
+test
+coverage
+.*
+*.log

.travis.yml

@@ -0,0 +1,17 @@
+language: node_js
+node_js:
+  - 8
+script:
+  - npm run lint
+  - npm run test
+  - nyc --silent npm run test
+  - nyc report --reporter=text-lcov | coveralls
+  - nyc check-coverage --lines 90
+after_success:
+  - NODE_ENV=production npm run build
+  - semantic-release pre
+  - npm publish
+  - semantic-release post
+notifications:
+  email: false
+sudo: false

README.md

@@ -0,0 +1,203 @@
+# Roarr
+
+[![Travis build status](http://img.shields.io/travis/gajus/roarr/master.svg?style=flat-square)](https://travis-ci.org/gajus/roarr)
+[![Coveralls](https://img.shields.io/coveralls/gajus/roarr.svg?style=flat-square)](https://coveralls.io/github/gajus/roarr)
+[![NPM version](http://img.shields.io/npm/v/roarr.svg?style=flat-square)](https://www.npmjs.org/package/roarr)
+[![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
+[![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas)
+
+JSON logger for Node.js.
+
+* [Usage](#usage)
+  * [Prepending context using the global state](#prepending-context-using-the-global-state)
+  * [Filtering logs](#filtering-logs)
+    * [jq primer](#jq-primer)
+* [Transports](#transports)
+* [Environment variables](#environment-variables)
+
+## Usage
+
+Roarr logging is disabled by default. To enable logging, you must start program with an environment variable `ROARR_LOG` set to `true`, e.g.
+
+```bash
+ROARR_LOG=true node ./index.js
+
+```
+
+`roarr` package exports a function that accepts the following API:
+
+```js
+export type LoggerType =
+  (
+    context: MessageContextType,
+    message: string,
+    c?: SprintfArgumentType,
+    d?: SprintfArgumentType,
+    e?: SprintfArgumentType,
+    f?: SprintfArgumentType,
+    g?: SprintfArgumentType,
+    h?: SprintfArgumentType,
+    i?: SprintfArgumentType,
+    k?: SprintfArgumentType
+  ) => void |
+  (
+    message: string,
+    b?: SprintfArgumentType,
+    c?: SprintfArgumentType,
+    d?: SprintfArgumentType,
+    e?: SprintfArgumentType,
+    f?: SprintfArgumentType,
+    g?: SprintfArgumentType,
+    h?: SprintfArgumentType,
+    i?: SprintfArgumentType,
+    k?: SprintfArgumentType
+  ) => void;
+
+```
+
+To put it in words:
+
+1. First parameter can be either a string (message) or an object.
+  * If first parameter is an object (context), the second parameter must be a string (message).
+2. Arguments after the message parameter are used to enable [printf message formatting](https://en.wikipedia.org/wiki/Printf_format_string).
+  * Printf arguments must be of a primitive type (`string | number | boolean | null`).
+  * There can be up to 9 printf arguments (or 8 if the first parameter is the context object).
+
+```js
+import log from 'roarr';
+
+log('foo');
+
+log('bar %s', 'baz');
+
+// Creates a child logger appending the provided `context` object
+// to the previous logger context.
+const debug = log.child({
+  level: 'debug'
+});
+
+debug('qux');
+
+debug({
+  quuz: 'corge'
+}, 'quux');
+
+```
+
+Produces output:
+
+```
+{"context":{},"message":"foo","sequence":0,"time":1506776210001,"version":"1.0.0"}
+{"context":{},"message":"bar baz","sequence":1,"time":1506776210002,"version":"1.0.0"}
+{"context":{"level":"debug"},"message":"qux","sequence":2,"time":1506776210003,"version":"1.0.0"}
+{"context":{"level":"debug","quuz":"corge"},"sequence":3,"message":"quux","time":1506776210004,"version":"1.0.0"}
+
+```
+
+### Prepending context using the global state
+
+Prepending context using the global state will affect all `roarr` logs.
+
+```js
+import log from 'roarr';
+
+log('foo');
+
+global.ROARR.prepend = {
+  taskId: 1
+};
+
+log('bar');
+
+global.ROARR.prepend = {};
+
+log('baz');
+
+```
+
+Produces output:
+
+```
+{"context":{},"message":"foo","sequence":0,"time":1506776210001,"version":"1.0.0"}
+{"context":{"taskId":1},"message":"bar","sequence":1,"time":1506776210002,"version":"1.0.0"}
+{"context":{},"message":"baz","sequence":2,"time":1506776210003,"version":"1.0.0"}
+
+```
+
+Prepending context using the global state is useful when the desired result is to associate all logs with a specific context for a duration of an operation, e.g. to correlate the main process logs with the dependency logs.
+
+```js
+import log from 'roarr';
+import foo from 'foo';
+
+const taskIds = [
+  1,
+  2,
+  3
+];
+
+for (const taskId of taskIds) {
+  global.ROARR = global.ROARR || {};
+  global.ROARR.prepend = {
+    taskId
+  };
+
+  log('starting task ID %d', taskId);
+
+  // In this example, `foo` is an arbitrary third-party dependency that is using
+  // roarr logger.
+  foo(taskId);
+
+  log('successfully completed task ID %d', taskId);
+
+  global.ROARR.prepend = {};
+}
+
+```
+
+Produces output:
+
+```
+{"context":{"taskId":1},"message":"starting task ID 1","sequence":0,"time":1506776210001,"version":"1.0.0"}
+{"context":{"taskId":1},"message":"foo","sequence":1,"time":1506776210002,"version":"1.0.0"}
+{"context":{"taskId":1},"message":"successfully completed task ID 1","sequence":2,"time":1506776210003,"version":"1.0.0"}
+[...]
+
+```
+
+### Filtering logs
+
+Roarr is designed to print all or none logs (refer to the [`ROARR_LOG` environment variable](#environment-variables) documentation).
+
+To filter logs you need to use a JSON processor, e.g. [jq](https://stedolan.github.io/jq/).
+
+### jq primer
+
+`jq` allows you to filter JSON messages using [`select(boolean_expression)`](https://stedolan.github.io/jq/manual/#select(boolean_expression)), e.g.
+
+```
+ROARR_LOG=true node ./index.js | jq 'select(.context.level == "warning" or .context.level == "error")'
+
+```
+
+## Transports
+
+A transport in most logging libraries is something that runs in-process to perform some operation with the finalised log line. For example, a transport might send the log line to a standard syslog server after processing the log line and reformatting it.
+
+Roarr does not support in-process transports.
+
+Roarr does not support in-process transports because Node processes are single threaded processes (ignoring some technical details). Given this restriction, Roarr purposefully offloads handling of the logs to external processes so that the threading capabilities of the OS can be used (or other CPUs).
+
+Depending on your configuration, consider one of the following log transports:
+
+* [Beats](https://www.elastic.co/products/beats) for aggregating at a process level (written in Go).
+* [logagent](https://github.com/sematext/logagent-js) for aggregating at a process level (written in JavaScript).
+* [Fluentd](https://www.fluentd.org/) for aggregating logs at a container orchestration level (e.g. Kubernetes) (written in Ruby).
+
+## Environment variables
+
+When running the script in a Node.js environment, use environment variables to control `roarr` behaviour.
+
+|Name|Type|Function|Default|
+|---|---|---|---|
+|`ROARR_LOG`|Boolean|Enables/ disables logging.|`false`|

package.json

@@ -0,0 +1,72 @@
+{
+  "author": {
+    "email": "[email protected]",
+    "name": "Gajus Kuizinas",
+    "url": "http://gajus.com"
+  },
+  "ava": {
+    "babel": "inherit",
+    "require": [
+      "babel-register"
+    ]
+  },
+  "dependencies": {
+    "boolean": "^0.1.3",
+    "sprintf-js": "^1.1.1"
+  },
+  "description": "JSON logger for Node.js.",
+  "devDependencies": {
+    "ava": "^0.22.0",
+    "babel-cli": "^6.26.0",
+    "babel-plugin-istanbul": "^4.1.4",
+    "babel-plugin-transform-flow-comments": "^6.22.0",
+    "babel-plugin-transform-flow-strip-types": "^6.22.0",
+    "babel-plugin-transform-object-rest-spread": "^6.26.0",
+    "babel-preset-env": "^1.6.0",
+    "babel-register": "^6.26.0",
+    "coveralls": "^2.13.1",
+    "eslint": "^4.7.0",
+    "eslint-config-canonical": "^9.3.1",
+    "flow-bin": "^0.54.1",
+    "flow-copy-source": "^1.2.1",
+    "husky": "^0.14.3",
+    "nock": "^9.0.14",
+    "nyc": "^11.2.1",
+    "semantic-release": "^7.0.2",
+    "sinon": "^3.2.1"
+  },
+  "engines": {
+    "node": ">=8.0"
+  },
+  "keywords": [
+    "log",
+    "logger",
+    "json"
+  ],
+  "main": "./dist/log.js",
+  "name": "roarr",
+  "nyc": {
+    "include": [
+      "src/**/*.js"
+    ],
+    "instrument": false,
+    "reporter": [
+      "text-lcov"
+    ],
+    "require": [
+      "babel-register"
+    ],
+    "sourceMap": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "[email protected]:gajus/roarr.git"
+  },
+  "scripts": {
+    "build": "rm -fr ./dist && NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps && flow-copy-source src dist",
+    "generate-types": "babel-node ./src/bin/generate-types.js",
+    "lint": "eslint ./src ./test && flow",
+    "test": "NODE_ENV=test ava --serial --verbose"
+  },
+  "version": "1.0.0"
+}