mlrawlings / complain

a tool to complain about deprecated method calls

complain

Mark methods as deprecated and warn the user when they're called. Forked from brianc/node-deprecate.

api

var complain = require('complain');

complain()

^{`complain([String message1 [, String message2 [,...]]], [Object options])`}

Call complain within a function you are deprecating. It will spit out all the messages to the console the first time and only the first time the method is called.

1  │ var complain = require('complain');
2  │
3  │ var someDeprecatedFunction = function() {
4  │   complain('someDeprecatedFunction() is deprecated');
5  │ };
6  │
…  │ // …
30 │
31 │ someDeprecatedFunction();

program output:

Options

• location: a string in the format ${filepath}:${line}:${column} indicating where the deprecated function was called from. Setting this to false disables outputting the location and will only log the message once.
• locationIndex: a number indicating the distance (in stack frames) from the call to complain to use as the deprecated location. 0 is the call to complain. By default, it is 1, which is typically the call to the deprecated function.
• level: a number indicating the log level. 1 = notice. 2 = warning (default).
• heading: a string that will be printed in color above the message. By default, "WARNING" when level === 2 or "NOTICE" when level === 1.
• headingColor: a string that is an ansi color/format. By default, colors.warning when level === 2 or colors.notice when level === 1.

complain.method()

^{`complain.method(Object proto, String methodName, [String message1 [, String message2 [,...]]], [Object options])`}

Deprecates a method on an object:

complain.method(console, 'log', 'You should not log.');

complain.fn()

^{`complain.fn(Function func, [String message1 [, String message2 [,...]]], [Object options])`}

Deprecates a function and returns it:

console.log = complain.fn(console.log, 'You should not log.');

complain.color

Set to false to disable color output. Set to true to force color output. Defaults to the value of complain.stream.isTTY.

complain.colors

Controls the colors used when logging. Default value:

{
  warning: '\x1b[31;1m', // red, bold
  notice: '\x1b[33;1m', // yellow, bold
  message: false, // use system color
  location: '\u001b[90m' // gray
}

How the default looks on a dark background vs. a light background:

complain.silence

When true, do nothing when the complain method is called.

complain.stream

The to which output is written. Defaults to process.stderr.

complain.log(message)

The function used to log, by default this function writes to complain.stream and falls back to console.warn.

You can replace this with your own logging method.

complain.getModuleName(location)

The function that determines if a warning is coming from a node_module. If the location for a warning is inside a dependent module, a single generic warning is logged once per module. You can replace this with your own function for environments (like browsers) that might not have node_modules in the path.

environment variables

SHOW_MODULE_COMPLAINS

By default, deprecation warnings whose caller location is in a dependent module will not be logged. A single module-level warning will be logged per module that is using deprecated apis. If you wish to view the individual warnings, set this variable to a truthy value.

SHOW_MODULE_COMPLAINS=1 node app.js

SHOW_NESTED_COMPLAINS

By default, if a deprecated function is using other deprecated apis, there will only be a warning for the top-level call to the deprecated function. If you wish to view the nested warnings, set this variable to a truthy value.

SHOW_NESTED_COMPLAINS=1 node app.js

license

MIT

complain's Issues

Hide deprecation warnings for calls made inside node_modules?

@patrick-steele-idem
Would it make sense to not show a warning for calls that aren't made directly from the application?

For example, if async-writer were to add a deprecation warning for captureString, obviously we should log that if the user's application directly requires the module and calls the deprecated method. But if, for example, the user's application depends on marko@2 which calls captureString from helpers.c, it probably doesn't benefit the user to see that deprecation warning when helpers.c is called from a compiled template.

complain.property - deprecate a property using getters and setters