pfn
v1.1.0
Published
Possible Function. Wraps what might be a function, with fallback behavior in case it’s not. Perfect for use in functions that accept optional callback arguments.
Downloads
7,058
Maintainers
Readme
Possible Function (pfn)
Wraps what might be a function, with fallback behavior in case it’s not. Perfect for use in functions that accept optional callback arguments.
Installation
Requires Node.js 6.0.0 or above.
npm i pfn
API
There are two ways you can import the module: require('pfn')
or require('pfn/strict')
. Each exposes a single function with the same signature. The difference is that strict mode will throw an error if fn
is anything other than a function, null
, or undefined
. Normal mode will silently defer to or
if fn
is of an unexpected type.
Parameters
fn
(any): The value that may or may not be a function.- Optional:
or
(any): The function that will be called, or the value that will be returned, iffn
is not a function. Defaults to a passthrough function (a => a
).
Return Value
Always returns a Function.
fn
, iffn
is a Functionor
, ifor
is a Function- A Function that returns
or
, if neitherfn
noror
is a function
Examples
pfn
wraps a value that may or may not be a function. If the underlying value is not a function, then pfn
will execute one of the following fallback behaviors.
Passthrough Fallback
If the value turns out to not be a function, pfn
will, by default, pass through whatever is given as the first argument. This is useful for optional filters.
const pfn = require('pfn')
function sayHello (name, filter) {
filter = pfn(filter)
return filter('Hello, ' + name)
}
// No filter is provided, so the hello message is returned without change:
sayHello('world') // 'Hello, world'
// A filter is provided which changes the hello message:
sayHello('world', m => m + '!!') // 'Hello, world!!'
Return-Value Fallback
If the value turns out to not be a function, pfn
can be configured to return a value of your choosing.
const pfn = require('pfn')
function sayHello (nameCallback) {
nameCallback = pfn(nameCallback, 'world')
return 'Hello, ' + nameCallback()
}
sayHello() // 'Hello, world'
sayHello(() => 'Dolly') // 'Hello, Dolly'
Self Fallback
If you provide the possible function as its own fallback, then you can accept either a value or a function as an argument for your code. For example, the sayHello
function in the following example can accept either a string or a function.
Don’t use the module’s strict mode (require('pfn/strict')
) if you want self-fallback behavior, because strict mode will throw an error if the first parameter is anything other than a function, null
, or undefined
.
const pfn = require('pfn')
function sayHello (name) {
name = pfn(name, name)
return 'Hello, ' + name()
}
sayHello('world') // 'Hello, world'
sayHello(() => 'world') // 'Hello, world'
Custom Fallback
If the wrapped value turns out to not be a function, the wrapping function can execute a custom fallback function instead:
const pfn = require('pfn')
const mightBeAFunction = null
const callback = pfn(mightBeAFunction, (...args) => args.length)
callback('arg 1', 'arg 2') // 2
Related
This module is part of the fn
family of modules.