report-toolkit for Node.js

RxJS Observable-based API. Used interally, but can also be used by consumers.

Index

Type aliases

Functions

Type aliases

Config

Ƭ Config: any

A “normalized” configuration object.

DiffOptions

Ƭ DiffOptions: object

Options for diff.

Type declaration:

excludeProperties: string[]
includeAll: boolean
includeProperties: string[]
showSecretsUnsafe: boolean

DiffResult

Ƭ DiffResult: object

A single difference between two reports. Emitted from diff.

Type declaration:

oldValue: string | number | boolean
op: “replace” | “add” | “remove”
path: string
value: string | number | boolean

InspectOptions

Ƭ InspectOptions: object

Options for inspect.

Type declaration:

ruleConfig: any
severity: string
showSecretsUnsafe: boolean
sort: boolean
sortDirection: “desc” | “asc”
sortField: string

RTKPlugin

Ƭ RTKPlugin: object

Represents a “plugin”. As of this writing, plugins may only contain rule definitions for inspect; it would make sense to add support for transformers, as well.

Type declaration:

rules: object[]

ToReportFromObjectOptions

Ƭ ToReportFromObjectOptions: object

Options for toReportFromObject.

Type declaration:

showSecretsUnsafe: boolean

TransformOptions

Ƭ TransformOptions: object

Options for transform.

Type declaration:

beginWith: string
defaultTransformer: string
defaultTransformerConfig: any
endWith: string

TransformerBlueprint

Ƭ TransformerBlueprint: object

A pairing of a transformer ID and a configuration of that transformer, to be ingested by transform.

Type declaration:

config: any
id: string

Functions

deregisterPlugins

▸ deregisterPlugins(): boolean

De-register (“unload”) all plugins.

Example:

const {deregisterPlugins} = require('@report-toolkit/core').observable;
console.log(deregisterPlugins()); // `true` or `false`, depending.

Returns: boolean

true if plugins were cleared; false if none registered

diff

Returns the difference between two reports.

Example:

const {diff} = require('@report-toolkit/core').observable;
const report1 = process.report.getReport();
const report2 = process.report.getReport();
diff(report1, report2, {
  filterProperties: ['header', 'javascriptStack', 'nativeStack'],
  showSecretsUnsafe: false
}).subscribe(({op, path, newValue, oldValue}) => {
  console.log(`[${op}] <${path}> ${oldValue} => ${newValue}`);
})

todo support JSON reports

Parameters:

Name	Type	Description
`report1`	DiagnosticReport \| Report \| Observable‹DiagnosticReport \| Report›	First report to diff
`report2`	DiagnosticReport \| Report \| Observable‹DiagnosticReport \| Report›	Second report to diff
`opts?`	Partial‹DiffOptions›	-

Returns: Observable‹DiffResult›

Results, one per difference

fromTransformerChain

▸ fromTransformerChain(transformerIds: string | string[], config?: Partial‹any›): Observable‹TransformerBlueprint›

Given a list of transformer IDs, create an Observable which emits TransformerBlueprint objects. Output should be piped to transform.

Example:

const {fromTransformerChain} = require('@report-toolkit/core').observable;
fromTransformerChain(['filter', 'csv'], {
  transformers: {
    filter: {include: 'header'},
    csv: {flatten: true}
  }
}); // pipe to transform()

Parameters:

Name	Type	Description
`transformerIds`	string \| string[]	List of Transformer IDs
`config?`	Partial‹any›	-

Returns: Observable‹TransformerBlueprint›

inspect

▸ inspect(reports: DiagnosticReport | Report | Observable‹DiagnosticReport | Report›, opts?: Partial‹InspectOptions›): Observable‹Message›

Inspect one or more reports, running rules against each. Resolves with an array of zero or more Messages.

Example:

const {inspect} = require('@report-toolkit/core').observable
const report = process.report.getReport();
inspect(report, {
  severity: 'info',
  sort: true,
  sortDirection: 'asc',
  sortField: 'header.dumpEventTimestamp',
  showSecretsUnsafe: false,
  ruleConfig: {
    'long-timeout': {
      timeout: '2s'
    }
  }
}).subscribe({message, filename} => {
  console.log(`${filename}: ${message}`);
});

Parameters:

Name	Type	Description
`reports`	DiagnosticReport \| Report \| Observable‹DiagnosticReport \| Report›	One or more Reports
`opts?`	Partial‹InspectOptions›	-

Returns: Observable‹Message›

isPluginRegistered

▸ isPluginRegistered(pluginId: string): boolean

Returns true if plugin with id pluginId has already been registered.

const {isPluginRegistered} = require('@report-toolkit/core').observable;
console.log(isPluginRegistered('my-plugin')); // `true` or `false`, depending.

Parameters:

Name	Type	Description
`pluginId`	string	A unique module ID

Returns: boolean

loadConfig

▸ loadConfig(config: any): Observable‹any›

Emits normalized config objects from raw config objects. Only a single input config should be necessary.

Example:

const {loadConfig} = require('@report-toolkit/core').observable;
// or require('./path/to/.rtkrc.js')
const rawConfig = [
  'report-toolkit:recommended',
  {
    rules: {
      'long-timeout': {
        timeout: '2s'
      }
    }
  }
];
loadConfig(rawConfig).subscribe(normalizedConfig => {
  // `normalizedConfig` contains contents of "recommended" settings,
  // with our override of custom rule config
});

todo ALWAYS load builtin plugin(s)

todo Document config shape

Parameters:

Name	Type	Description
`config`	any	Raw config object

Returns: Observable‹any›

Normalized config object(s)

registeredRuleDefinitions

▸ registeredRuleDefinitions(): object[]

Get a list of rule definitions contained within registered plugins.

Example:

const {registeredRuleDefinitions} = require('@report-toolkit/core').observable;
registeredRuleDefinitions().forEach(ruleDef => {
  console.log(ruleDef.meta.id);
})

Returns: object[]

toReportFromObject

▸ toReportFromObject(opts?: Partial‹ToReportFromObjectOptions›): OperatorFunction‹any, Readonly‹Report››

Creates a target Observable of Report objects from a source Observable of plain objects (usually parsed from a JSON report).

Example:

const {toReportFromObject} = require('@report-toolkit/core').observable;
const json = fs.readFileSync('./report-xxxxx.json');
toReportFromObject(json, {
  showSecretsUnsafe: false
}).subscribe(report => {
 // `Report` instance with secrets redacted
});

Parameters:

Name	Type
`opts?`	Partial‹ToReportFromObjectOptions›

Returns: OperatorFunction‹any, Readonly‹Report››

transform

▸ transform(source: Observable‹any›, opts?: Partial‹TransformOptions›): OperatorFunction‹TransformerBlueprint, any›

Run source through chain of one or more transformers. Pipe fromTransformerChain into this. Performs validation before piping. While most other functions here will automatically convert a raw report into a Report instance for further processing, this one does not (since transformers don’t necessarily accept them). You’ll need to do this manually, as seen in the below example. If the final transformer does not output the desired endType, the defaultTransformer will be appended to the chain; otherwise it is ignored.

Example:

const {fromTransformerChain, transform, toReportFromObject} = require('@report-toolkit/core').observable;
const report$ = toReportFromObject(process.report.getReport());
fromTransformerChain(['filter', 'csv'], {
  transformers: {
    filter: {include: 'header'},
    csv: {flatten: true}
  }
}).pipe(transform(report$)).subscribe(line => {
  console.log(line);
});

Parameters:

Name	Type	Description
`source`	Observable‹any›	Source data to transform. Objects, Reports, etc.
`opts?`	Partial‹TransformOptions›	-

Returns: OperatorFunction‹TransformerBlueprint, any›

Result of running source through the transformer chains.

use

▸ use(pluginId: string): Observable‹RTKPlugin›

Example:

const {use} = require('@report-toolkit/core').observable;
use('some-plugin-in-node_modules').subscribe();

Parameters:

Name	Type	Description
`pluginId`	string	ID of plugin to register; a resolvable path to a module

Returns: Observable‹RTKPlugin›

A plugin instance, but YAGNI.

Edit this page on GitHub