derf
v3.0.2
Published
A javascript performance debugger.
Downloads
2,977
Readme
derf
debug. perf. derf?
Simple wrappers for debugging function performance.
- based on the
debug
module - handles most common function patterns
- no performance hit in production
Example
Wrap Functions
// DEBUG=sync:* node script.js
import * as derf from 'derf';
const fn = derf.sync('sync:fn', function(a, b) {
// slow operation
return value;
});
Wrap Async Functions
// DEBUG=async:* node script.js
import * as derf from 'derf';
const fn1 = derf.callback('async:fn1', function(foo, bar, cb) {
// slow operation
callback(null, value);
});
const fn2 = derf.promise('async:fn2', function(foo, bar) {
// slow operation
return Promise.resolve(value);
});
Wrap Express Middleware
// DEBUG=middleware:* node script.js
import * as derf from 'derf';
const fn1 = derf.middleware('middleware:fn1', function(req, res, next) {
// slow operation
res.send('foo');
});
const fn2 = derf.middleware('middleware:fn2', function(req, res, next) {
// slow operation
next();
});
const fn3 = derf.middleware('middleware:fn3', function(err, req, res, next) {
// slow operation
request('/something').pipe(res);
});
API
Every function wrapper takes in the following arguments:
namespace
- Required. A string to pass todebug
or a debug function.fn
- Required. A function to wrap.printer
- Optional. A function to customize what is logged.
derf.sync(namespace, fn, [printer])
Wraps a synchronous function.
derf.callback(namespace, fn, [printer])
Wraps a node-style async function. derf will intercept the last function passed in. Meaning it can work with the following types of argument orders.
const fn1 = derf.callback('namespace1', function(a, b, callback) { });
const fn2 = derf.callback('namespace1', function(a, callback, b) { });
const fn1 = derf.callback('namespace1', function(callback, a, b) { });
derf.promise(namespace, fn, [printer])
Wraps a function that returns a promise.
derf.middleware(namespace, fn, [printer])
Wraps express middleware, route handlers, and error handlers.
derf.isWrapped(fn) -> boolean
Returns true if a given function has already been wrapped by derf.
Custom Logging
You can pass in a function as the last argument of each derf wrapper to customize what is logged. The function must return a string and is passed the following arguments:
debug
- function. the debug instance.time
- number. the time in nanoseconds it took the function to to run.args
- array. the arguments the function was called with.retArgs
- array. the error/value the function was resolved with.
For example, a simple printer could look like this:
function simplePrinter(debug, time, callArgs, retArgs) {
const [err, res] = retArgs; // not available for middleware
if (err) {
debug('failed in %s nanoseconds', time);
} else {
debug('finished in %s nanoseconds', time);
}
}
Decorators
In addition to exporting the standard wrapping functions, derf also provides functions that work with the experimental decorator syntax.
import { timeSync, timePromise, timeCallback } from 'derf';
import createDebug from 'debug';
const debug = createDebug('test');
export default class TimedClass {
@timeSync('test')
sync(val) {
return val;
}
@timePromise(debug)
promise(val) {
return Promise.resolve(val);
}
@timeCallback('test')
callback(val, cb) {
setTimeout(cb, 0, val);
}
}
You can create decorators with custom logging logic by importing the createDecorator
function.
import { createDecorator, callback as callbackWrapper } from 'derf';
const myDecorator = createDecorator(
callbackWrapper,
function simplePrinter(debug, time, callArgs, retArgs) {
debug('it\'s done');
}
);
Caveats
Because derf wraps your function calls with it's own. There is a performance hit when the
DEBUG
environment variable is enabled. But you shouldn't have that enabled in production anyways.Try not to miswrap Functions (e.g. don't do
derf.promise(someCallbackFunction)
). While derf won't break your code by throwing an error, it will not be able to print the timings of that function, it may also cause the function to run slower. Run your code withDEBUG=derf,your:namespace:*
to view derf's own debug statements.