Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bahmutov/d3-helpers

Little utility D3 functions
https://github.com/bahmutov/d3-helpers

Last synced: 15 days ago
JSON representation

Little utility D3 functions

Awesome Lists containing this project

README 

        
# d3-helpers



> Little utility D3 functions



[![NPM][d3-helpers-icon] ][d3-helpers-url]



[![Build status][d3-helpers-ci-image] ][d3-helpers-ci-url]

[![Coverage Status][d3-helpers-coverage-image]][d3-helpers-coverage-url]

[![dependencies][d3-helpers-dependencies-image] ][d3-helpers-dependencies-url]

[![devdependencies][d3-helpers-devdependencies-image] ][d3-helpers-devdependencies-url]



## Example



D3 code before



```js

// x and y are scale functions

var line = d3.svg.line()

  .x(function (d) { return x(new Date(d.date)); })

  .y(function (d) { return y(+d.y); });

```



This is very common D3 callback code. Here is the same code with callbacks refactored

with *d3-helpers*



```js

var line = d3.svg.line()

  .x(d3h('date', d3h.newDate, x))

  .y(d3h('y', Number, y));

```



Notice several benefits:



1. The `.x` callback is easier to read from left to right:

grab property *date*, then call *d3h.newDate* function on it, then call *x* function.

No more inside out composition flow as in `x(new Date(d.date))`

2. Allowing only property names and functions to apply makes the author's intention clear.

`+d.y` is always ambiguous: did the author forget to add something or was this the

intention? Writing `d3h('y', Number, ...)` makes it explicit.

3. By eliminating writing each callback function, we eliminate potential sources of errors.

In addition, since every function passed as argument is external, they becoming testable.



## Install



Node:



```

npm install d3-helpers --save

var d3h = require('d3-helpers');

```



Browser:



```

bower install d3-helpers



// attaches as window.d3h object

```



## Api



```

// index

d3h (alias d3h.d)

d3h.i

d3h.noop

d3h.undef

d3h.pass (alias d3.datum)

d3h.property

d3h.yes / no

d3h.index

d3h.value

d3h.newDate

d3h.hermit

```



**d3-helpers** is a [well-tested](test/helpers.spec.js) function

augmented by other tiny functions. First the *d3h* function itself



### d3h = d3h.d



Returns a function that can chain property access and function composition.



`d3h('propertyName', fnToApply, 'method name to call', 'anotherPropertyName', orAnotherFn, ...);`



```js

var foo = {

  getName: function() { return this.name; },

  name: 'foo'

};

function concatSelf(x) { return x + x; }

function add2(x) { return x + 2; }

var f = d3h('getName', concatSelf, 'length', add2);

f(foo) // returns 8



// f is the same as

function (obj) {

  return add2(concatSelf(obj.getName()).length);

}

```



Use on `d` argument:



```js

  .x(d3h('length', xScale));

  // d3h.d is an alias

  .(d3h.d('length', xScale));

```



When calling a method on the object, `this` is bound to the

object, and it is passed itself as first argument.



### d3h.i



Same chaining as `d3h.d` but operates on the second argument, usually the index



```js

.y(d3h.i(yScale))

// same as

.y(function (d, i) {

  return yScale(i);

});

```



If you want to return the index element, you need to execute the function to create the callback



```js

.y(d3h.i())

// same as

.y(function (d, i) {

  return i;

});

```



### d3h.noop



Same as `function () {}`



### d3h.undef



Same as `function () { return; }` if you need a function that

always returns *undefined*.



### d3h.pass = d3.datum



Same as `function (d) { return d; }`



You can pass a function as argument, then it works as a wrapped

function for any value passed next. For example to scale by function

*triple* we can replace



```

function triple(x) { return 3 * x; }

.attr('left', function (d) { return triple(d); })

// with

.attr('left', d3h.pass(triple));

```



### d3h.property



```js

function property(name) {

  return function (obj) {

    return obj[name];

  };

}

// if passed function(s) as additional arguments

function property(name, f, g, ...) {

  return function (obj) {

    return g(f(obj[name]));

  };

}

```



Logically, read this from left to right. First grab named property,

then apply function *f*, then apply to the result *g*, etc.



Useful to extract a property and convert type, for example for D3 selections



```js

.text(d3h.property('name'))

.width(d3h.property('age', Number))

.text(d3h.property('date', String))

```



or scale property from datum



```js

var x = d3.time.scale(), y = d3.scale.linear();

var line = d3.svg.line()

  .x(function (d) { return x(d.date); })

  .y(function (d) { return y(d.y); });

// same using d3-helpers

var line = d3.svg.line()

  .x(d3h.property('date', x))

  .y(d3h.property('y', y))

```



### d3h.yes / no



*d3h.yes* function always returns `true`,

*d3h.no* function always returns `false`.



### d3h.index



Same as `function (d, i) { return i; }`



### d3h.value



Same as



```js

function (val) {

  return function () {

    return val;

  };

}

```



Value could be anything: number, string, undefined, even another function.



### d3h.newDate



Same as `function (d) { return new Date(d); }` to get around

the `new` keyword requirement in JavaScript for Dates. Useful

for constructing Date instances inside *d3h.property*



```js

var x = d3.time.scale();

var line = d3.svg.line()

  .x(function (d) { return x(new Date(d.date)); })

// same using d3-helpers

var line = d3.svg.line()

  .x(d3h.property('date', d3h.newDate, x))

```



### d3h.hermit



Wraps a function that should not receive any arguments. Returned function just

calls the original without any arguments.



```js

function failIfArguments() {

  if (arguments.length) {

    throw new Error('I cannot handle arguments');

  }

  return 42;

}

d3h.hermit(failIfArguments)(100); // 42

```



## Related



I have another tiny library with single exported function called

[functional-pipeline](https://github.com/bahmutov/functional-pipeline).

It is very similar to *d3h* function for building a left to right

pipelines, but has better debug mode.



### Small print



Author: Gleb Bahmutov © 2014



* [@bahmutov](https://twitter.com/bahmutov)

* [glebbahmutov.com](http://glebbahmutov.com)

* [blog](http://bahmutov.calepin.co/)



License: MIT - do anything with the code, but don't blame me if it does not work.



Spread the word: tweet, star on github, etc.



Support: if you find any problems with this module, email / tweet /

[open issue](https://github.com/bahmutov/d3-helpers/issues) on Github



## MIT License



Copyright (c) 2014 Gleb Bahmutov



Permission is hereby granted, free of charge, to any person

obtaining a copy of this software and associated documentation

files (the "Software"), to deal in the Software without

restriction, including without limitation the rights to use,

copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the

Software is furnished to do so, subject to the following

conditions:



The above copyright notice and this permission notice shall be

included in all copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES

OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,

WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR

OTHER DEALINGS IN THE SOFTWARE.



[d3-helpers-icon]: https://nodei.co/npm/d3-helpers.png?downloads=true

[d3-helpers-url]: https://npmjs.org/package/d3-helpers

[d3-helpers-ci-image]: https://travis-ci.org/bahmutov/d3-helpers.png?branch=master

[d3-helpers-ci-url]: https://travis-ci.org/bahmutov/d3-helpers

[d3-helpers-coverage-image]: https://coveralls.io/repos/bahmutov/d3-helpers/badge.png

[d3-helpers-coverage-url]: https://coveralls.io/r/bahmutov/d3-helpers

[d3-helpers-dependencies-image]: https://david-dm.org/bahmutov/d3-helpers.png

[d3-helpers-dependencies-url]: https://david-dm.org/bahmutov/d3-helpers

[d3-helpers-devdependencies-image]: https://david-dm.org/bahmutov/d3-helpers/dev-status.png

[d3-helpers-devdependencies-url]: https://david-dm.org/bahmutov/d3-helpers#info=devDependencies