fluent-arguments
When simple arguments just don't cut it.
The problem
Let's assume you wrote a nice library my-rainbow
for creating rainbow-like patterns. To create a pattern with a
specific order of colors, you could have implemented something like this:
var createRainbow = createRainbowvar specialRainbow =
Now for the next version, you want colors to be able to have a special "sparkling" effect. How could you implement this API change while maintaining backward compatibility?
-
Double the number of color constants:
var specialRainbow =…probably does not scale very well (gradients anyone?).
-
Allow for special objects to be used as arguments alongside strings:
var specialRainbow =scales much better, but readability starts to suffer. And it is not obvious which would be valid options.
Fluent arguments
fluent-arguments
makes it trivial to implement the following API:
var sparkling = sparklingvar specialRainbow =
which is arguably as easily readable as approach 1 while being about as maintainable and modular as approach 2.
Fluent arguments can also be configured to describe previous arguments. To that end, let us assume you also want to specify that some colored areas occasionally flash in other colors:
var withFlashesIn = withFlashesInvar specialRainbow =
Nice, isn't it? A word of caution: Especially when using the second type of arguments, you should make sure from the
wording of your fluent argument that it actually further describes the previous argument :) To avoid confusion, it is
helpful to only stick to one type of arguments. So if you want to have sparkling AND flashing colors, fluent-arguments
allows you to specify your API like this:
var withSparkles = withSparklesvar specialRainbow =
How to build such an API
fluent-arguments
provides two exports, createArg
and createFunc
. With createFunc
, you create a function that
receives a variable number of arguments, each of which can be fluent arguments:
var fa = { // some implementation} var createRainbow = favar specialRainbow = // calls createRainbowHandler([{value: 'red'}, {value: 'green'}, {value: 'yellow'}, {value: 'blue'}])
As you can see, normal arguments become argument objects with the original value stored as value
. Now, createArg
allows you to create special fluent arguments which are parsed differently by createRainbow
:
var sparkling = favar withFlashesIn = favar withSparkles = fa
createArg
receives an object which can have any of the following fields, all of which are optional:
args: ['argument1' <,'argument2'…>]
Ifargs
is specified, the fluent argument will be a function; when invoked, the function arguments will be mapped to the provided keys of the argument object, e.g. the first argument will be mapped to'argument1'
etc.; ifargs
is not specified, the fluent argument will be a plain object.extendsPrevious: <false|true>
If this is set to true, this argument will not create a new argument object but extend the previous objectextra: {some: object}
If this option is specified, the given object will be merged into the current (or previous) argument object.
This has the following effect:
var specialRainbow = // calls createRainbowHandler([{value: 'red'}, {value: 'green', sparkling: true}, {value: 'yellow'}, {value: 'blue'}])specialRainbow = // calls createRainbowHandler([{value: 'red'}, {value: 'green', withFlashesIn: 'white'}, {value: 'yellow'}, {value: 'blue'}])specialRainbow = // calls createRainbowHandler([{value: 'red'}, {value: 'green', withFlashesIn: 'white', sparkling: true}, {value: 'yellow'}, {value: 'blue'}])