feat: support multiple import styles from JS and TS; add morgan types (#165)

This updates the three @elastic/ecs-*-format packages to support the following
import styles from JS and TS code:
1. `const { ecsFormat } = require('@elastic/ecs-pino-format);` in JS and TS.
   The preferred import style for JS code using CommonJS.
2. `import { ecsFormat } from '@elastic/ecs-pino-format';` in JS and TS.
   ES module (ESM) import style. This is the preferred style for TypeScript
   code and for JS developers using ESM.
3. `const ecsFormat = require('@elastic/ecs-pino-format');` in JS.
   The old, deprecated import method. Still supported for backward compat.
4. `import ecsFormat from '@elastic/ecs-pino-format';` in JS and TS.
   This works, but is deprecated. Prefer #2 style.
5. `import * as EcsPinoFormat from '@elastic/ecs-pino-format';` in TS.
   One must then use `EcsPinoFormat.ecsFormat()`.

Note that this *excludes* support for this TS-only style:
`import escFormat = require('@elastic/ecs-pino-format');`

This also adds types for ecs-morgan-format, based on #119 and #90.
I'd had an earlier start on this in #96.

Replaces: #96
Closes: #90
Closes: #119

Author: trentm

docs/morgan.asciidoc

@@ -28,17 +28,17 @@ $ npm install @elastic/ecs-morgan-format
 
 [source,js]
 ----
-const app = require('express')()
-const morgan = require('morgan')
-const ecsFormat = require('@elastic/ecs-morgan-format')
+const app = require('express')();
+const morgan = require('morgan');
+const { ecsFormat } = require('@elastic/ecs-morgan-format');
 
-app.use(morgan(ecsFormat(/* options */))) <1>
+app.use(morgan(ecsFormat(/* options */))); <1>
 
 // ...
 app.get('/', function (req, res) {
-  res.send('hello, world!')
+  res.send('hello, world!');
 })
-app.listen(3000)
+app.listen(3000);
 ----
 <1> Pass the ECS formatter to `morgan()`.
 
@@ -58,17 +58,17 @@ include::{ecs-repo-dir}/setup.asciidoc[tag=configure-filebeat]
 
 [source,js]
 ----
-const app = require('express')()
-const morgan = require('morgan')
-const ecsFormat = require('@elastic/ecs-morgan-format')
+const app = require('express')();
+const morgan = require('morgan');
+const { ecsFormat } = require('@elastic/ecs-morgan-format');
 
-app.use(morgan(ecsFormat(/* options */))) <1>
+app.use(morgan(ecsFormat(/* options */))); <1>
 
 app.get('/', function (req, res) {
-  res.send('hello, world!')
+  res.send('hello, world!');
 })
 app.get('/error', function (req, res, next) {
-  next(new Error('boom'))
+  next(new Error('boom'));
 })
 
 app.listen(3000)
@@ -129,11 +129,11 @@ specified format. The default is https://github.com/expressjs/morgan#combined[`c
 
 [source,js]
 ----
-const app = require('express')()
-const morgan = require('morgan')
-const ecsFormat = require('@elastic/ecs-morgan-format')
+const app = require('express')();
+const morgan = require('morgan');
+const { ecsFormat } = require('@elastic/ecs-morgan-format');
 
-app.use(morgan(ecsFormat({ format: 'tiny' }))) <1>
+app.use(morgan(ecsFormat({ format: 'tiny' }))); <1>
 // ...
 ----
 <1> If "format" is the only option you are using, you may pass it as `ecsFormat('tiny')`.
@@ -201,7 +201,7 @@ Integration with Elastic APM can be explicitly disabled via the
 
 [source,js]
 ----
-app.use(morgan(ecsFormat({ apmIntegration: false })))
+app.use(morgan(ecsFormat({ apmIntegration: false })));
 ----
 
 

docs/pino.asciidoc

@@ -26,12 +26,12 @@ $ npm install @elastic/ecs-pino-format
 
 [source,js]
 ----
-const ecsFormat = require('@elastic/ecs-pino-format')
-const pino = require('pino')
+const { ecsFormat } = require('@elastic/ecs-pino-format');
+const pino = require('pino');
 
-const log = pino(ecsFormat(/* options */)) <1>
-log.info('hi')
-log.error({ err: new Error('boom') }, 'oops there is a problem')
+const log = pino(ecsFormat(/* options */)); <1>
+log.info('hi');
+log.error({ err: new Error('boom') }, 'oops there is a problem');
 // ...
 ----
 <1> This will https://getpino.io/#/docs/api?id=options[configure] Pino's `formatters`, `messageKey` and `timestamp` options.
@@ -53,14 +53,14 @@ include::{ecs-repo-dir}/setup.asciidoc[tag=configure-filebeat]
 
 [source,js]
 ----
-const ecsFormat = require('@elastic/ecs-pino-format')
-const pino = require('pino')
+const { ecsFormat } = require('@elastic/ecs-pino-format');
+const pino = require('pino');
 
-const log = pino(ecsFormat(/* options */)) <1>
-log.info('Hello world')
+const log = pino(ecsFormat(/* options */)); <1>
+log.info('Hello world');
 
-const child = log.child({ module: 'foo' })
-child.warn('From child')
+const child = log.child({ module: 'foo' });
+child.warn('From child');
 ----
 <1> See available options <<pino-ref,below>>.
 
@@ -82,12 +82,12 @@ For example:
 
 [source,js]
 ----
-const ecsFormat = require('@elastic/ecs-pino-format')
-const pino = require('pino')
-const log = pino(ecsFormat())
+const { ecsFormat } = require('@elastic/ecs-pino-format');
+const pino = require('pino');
+const log = pino(ecsFormat());
 
-const myErr = new Error('boom')
-log.info({ err: myErr }, 'oops')
+const myErr = new Error('boom');
+log.info({ err: myErr }, 'oops');
 ----
 
 will yield (pretty-printed for readability):
@@ -114,7 +114,7 @@ Special handling of the `err` field can be disabled via the `convertErr: false`
 
 [source,js]
 ----
-const log = pino(ecsFormat({ convertErr: false }))
+const log = pino(ecsFormat({ convertErr: false }));
 ----
 
 
@@ -130,20 +130,20 @@ objects when passed as the `req` and `res` fields, respectively.
 
 [source,js]
 ----
-const http = require('http')
-const ecsFormat = require('@elastic/ecs-pino-format')
-const pino = require('pino')
+const http = require('http');
+const { ecsFormat } = require('@elastic/ecs-pino-format');
+const pino = require('pino');
 
-const log = pino(ecsFormat({ convertReqRes: true })) <1>
+const log = pino(ecsFormat({ convertReqRes: true })); <1>
 
 const server = http.createServer(function handler (req, res) {
-  res.setHeader('Foo', 'Bar')
-  res.end('ok')
-  log.info({ req, res }, 'handled request') <2>
-})
+  res.setHeader('Foo', 'Bar');
+  res.end('ok');
+  log.info({ req, res }, 'handled request'); <2>
+});
 
 server.listen(3000, () => {
-  log.info('listening at http://localhost:3000')
+  log.info('listening at http://localhost:3000');
 }
 ----
 <1> use `convertReqRes` option
@@ -243,7 +243,7 @@ Integration with Elastic APM can be explicitly disabled via the
 
 [source,js]
 ----
-const log = pino(ecsFormat({ apmIntegration: false }))
+const log = pino(ecsFormat({ apmIntegration: false }));
 ----
 
 

packages/ecs-morgan-format/CHANGELOG.md

@@ -8,6 +8,26 @@
 
 - Set `http.request.id` field (see [ecs-helpers CHANGELOG](../ecs-helpers/CHANGELOG.md#v210)).
 
+- Changed to a named export. The preferred way to import is now:
+
+  ```js
+  const { ecsFormat } = require('@elastic/ecs-morgan-format'); // CommonJS
+  import { ecsFormat } from '@elastic/ecs-morgan-format'; // ESM
+  ```
+
+  The old way will be deprecated and removed in the future:
+
+  ```js
+  const ecsFormat = require('@elastic/ecs-morgan-format'); // OLD
+  ```
+
+  Changes in this version add support for default import in TypeScript, with or
+  without the `esModuleInterop` setting:
+
+  ```ts
+  import ecsFormat from '@elastic/ecs-morgan-format';
+  ```
+
 ## v1.4.0
 
 - Add `service.version`, `service.environment`, and `service.node.name` log

packages/ecs-morgan-format/README.md

@@ -27,7 +27,7 @@ npm install @elastic/ecs-morgan-format
 ```js
 const app = require('express')()
 const morgan = require('morgan')
-const ecsFormat = require('@elastic/ecs-morgan-format')
+const { ecsFormat } = require('@elastic/ecs-morgan-format')
 
 app.use(morgan(ecsFormat(/* options */)))
 

packages/ecs-morgan-format/examples/express-with-apm.js

@@ -38,7 +38,7 @@ const apm = require('elastic-apm-node').start({
 
 const app = require('express')()
 const morgan = require('morgan')
-const ecsFormat = require('../') // @elastic/ecs-morgan-format
+const { ecsFormat } = require('../') // @elastic/ecs-morgan-format
 
 app.use(morgan(ecsFormat()))
 

packages/ecs-morgan-format/examples/express.js

@@ -19,7 +19,7 @@
 
 const app = require('express')()
 const morgan = require('morgan')
-const ecsFormat = require('../') // @elastic/ecs-morgan-format
+const { ecsFormat } = require('../') // @elastic/ecs-morgan-format
 
 app.use(morgan(ecsFormat()))
 

packages/ecs-morgan-format/index.d.ts

@@ -0,0 +1,50 @@
+import type { FormatFn } from "morgan";
+
+interface Config {
+  /**
+   * A format *name* (e.g. 'combined'), format function (e.g. `morgan.combined`),
+   * or a format string (e.g. ':method :url :status').
+   *
+   * This is used to format the "message" field.
+   * @default `morgan.combined`
+   */
+  format: string;
+
+  /**
+   * Whether to automatically integrate with
+   * Elastic APM (https://github.com/elastic/apm-agent-nodejs). If a started
+   * APM agent is detected, then log records will include the following
+   * fields:
+   *
+   * - "trace.id", "transaction.id", and "span.id" - if there is a current
+   *   active trace when the log call is made
+   *
+   * and also the following fields, if not already specified in this config:
+   *
+   * - "service.name" - the configured `serviceName` in the agent
+   * - "service.version" - the configured `serviceVersion` in the agent
+   * - "service.environment" - the configured `environment` in the agent
+   * - "service.node.name" - the configured `serviceNodeName` in the agent
+   * - "event.dataset" - set to `${serviceName}` for correlation in Kibana
+   *
+   * @default true.
+   */
+  apmIntegration?: boolean;
+
+  /** Specify "service.name" field. Defaults to a value from the APM agent, if available. */
+  serviceName?: string;
+  /** Specify "service.version" field. Defaults to a value from the APM agent, if available. */
+  serviceVersion?: string;
+  /** Specify "service.environment" field. Defaults to a value from the APM agent, if available. */
+  serviceEnvironment?: string;
+  /** Specify "service.node.name" field. Defaults to a value from the APM agent, if available. */
+  serviceNodeName?: string;
+  /** Specify "event.dataset" field. Defaults `${serviceName}`. */
+  eventDataset?: string;
+
+}
+
+declare function ecsFormat(config?: Config): FormatFn;
+
+export default ecsFormat;
+export { ecsFormat }

packages/ecs-morgan-format/index.js

@@ -179,4 +179,8 @@ function ecsFormat (opts) {
   }
 }
 
+// For backwards compatibility with v1.0.0, the top-level export is `ecsFormat`,
+// though using the named export is preferred.
 module.exports = ecsFormat
+module.exports.ecsFormat = ecsFormat
+module.exports.default = ecsFormat

packages/ecs-morgan-format/package.json

@@ -3,6 +3,7 @@
   "version": "1.4.0",
   "description": "A formatter for the morgan logger compatible with Elastic Common Schema.",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "index.js"
   ],

packages/ecs-morgan-format/test/basic.test.js

@@ -26,7 +26,7 @@ const morgan = require('morgan')
 const split = require('split2')
 const test = require('tap').test
 
-const ecsFormat = require('../')
+const { ecsFormat } = require('../')
 const { ecsLoggingValidate } = require('../../../utils/lib/ecs-logging-validate')
 
 const ajv = new Ajv({