D3 Helpers

0.3.0 · abandoned · verified Sun Apr 19

d3-helpers is a collection of small, functional utility functions designed to streamline common D3 callback patterns, particularly for D3.js version 3.0. It aims to improve code readability by allowing a left-to-right composition style for data property access and function application within D3's data-driven methods, such as `d3.svg.line().x()`. The package, currently at version 0.3.0, was last published in 2014 and is not actively maintained. It was developed to abstract away repetitive callback definitions like `function (d) { return x(new Date(d.date)); }` into more concise and explicit chains like `d3h('date', d3h.newDate, x)`. Its primary differentiator was simplifying D3's functional programming aspects at a time when D3's API encouraged verbose callback structures. It offers utilities for property access, type conversion, and handling data `d` and index `i` arguments in a declarative manner.

Common errors

```
TypeError: d3.svg is undefined
```
cause Attempting to use `d3-helpers` with D3.js v4 or newer, where `d3.svg` was removed.

fix Downgrade D3.js to version 3.x or rewrite your D3 code to use modern D3 APIs (e.g., `d3.line()` instead of `d3.svg.line()`) and remove `d3-helpers`.
```
d3h is not defined
```
cause The `d3-helpers` library was not correctly imported or loaded. In Node.js, `require('d3-helpers')` was skipped. In a browser, the `<script>` tag was missing or the file failed to load.

fix For Node.js, add `const d3h = require('d3-helpers');`. For browsers, ensure `<script src="bower_components/d3-helpers/index.js"></script>` is present and loads successfully before `d3h` is accessed.
```
TypeError: Cannot read properties of undefined (reading 'line')
```
cause This error often occurs if `d3.svg` is undefined, typically because a modern D3 version (v4+) is loaded, or D3 itself isn't loaded correctly before `d3-helpers` attempts to access `d3.svg.line`.

fix Verify that you are using D3.js version 3.x, and that `d3` is loaded and accessible globally or via CommonJS `require` before `d3-helpers` is initialized.

Warnings

breaking This package is fundamentally incompatible with D3.js versions 4.0 and later. D3.js underwent a major rewrite in v4, modularizing its API and changing core functions like `d3.svg.line()` to `d3.line()`. Using `d3-helpers` with modern D3 will result in `TypeError: d3.svg is undefined` or similar errors.
Fix: Migrate your D3 codebase to D3.js v4+ and rewrite data access and transformation logic using modern D3 patterns, which often involve `d3.map`, `d3.extent`, and direct function application, or consider other maintained D3 helper libraries.
gotcha The `d3-helpers` package is no longer maintained. Its last update was 11 years ago, and it targets an obsolete version of D3 (v3). Using an unmaintained package can pose security risks, lack support for modern JavaScript features, and will not receive bug fixes or performance improvements.
Fix: Avoid using this package in new projects. For existing projects, evaluate if its functionality is still critical and consider refactoring to native D3 methods or newer, maintained utility libraries.
gotcha `d3-helpers` assumes a D3v3 context, particularly around global `d3` object and specific API calls like `d3.svg.line`. Attempting to use it in environments without `d3` (v3) globally available or with a different D3 version will lead to errors.
Fix: Ensure D3.js v3 is loaded globally if using `d3-helpers` in a browser environment, or ensure `d3` (v3) is correctly `require`d in a CommonJS Node.js environment before `d3-helpers`.

Install

npm install d3-helpers npm
yarn add d3-helpers yarn
pnpm add d3-helpers pnpm

Imports

d3h
wrong:
```
import d3h from 'd3-helpers';
```
correct:
```
const d3h = require('d3-helpers');
```
This package is for CommonJS environments or browser globals. ESM imports are not supported.

d3h

wrong:

import { d3h } from 'd3-helpers';

correct:

// In a browser, after loading via <script src="bower_components/d3-helpers/index.js"></script>
const d3h = window.d3h;

Attaches as a global `window.d3h` object in browser environments.

d3h.newDate
wrong:
```
import { newDate } from 'd3-helpers';
```
correct:
```
const d3h = require('d3-helpers');
// ... then use d3h.newDate
```
`newDate` is a property of the main `d3h` object, not a direct named export.

Quickstart

Demonstrates using `d3h` to compose property access and function application for D3 line generator callbacks, mimicking its original usage with D3v3.

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

// Mock D3 and scale functions for demonstration
const d3 = {
  svg: {
    line: () => ({
      _x: null,
      _y: null,
      x: function(fn) { this._x = fn; return this; },
      y: function(fn) { this._y = fn; return this; },
      // Simulate line generation
      generate: function(data) {
        return data.map(d => ({ x: this._x(d), y: this._y(d) }));
      }
    })
  }
};

const xScale = d => d * 10;
const yScale = d => d * 5;

// Sample data
const data = [
  { date: '2024-01-01', y: 10 },
  { date: '2024-01-02', y: 20 },
  { date: '2024-01-03', y: 15 }
];

// Original D3 code style (simulated)
// const lineBefore = d3.svg.line()
//   .x(function (d) { return xScale(new Date(d.date).getTime()); })
//   .y(function (d) { return yScale(+d.y); });
// console.log('Before:', lineBefore.generate(data));

// D3 code with d3-helpers
const line = d3.svg.line()
  .x(d3h('date', d3h.newDate, d => d.getTime(), xScale))
  .y(d3h('y', Number, yScale));

const generatedPoints = line.generate(data);
console.log('Generated line points with d3-helpers:');
console.log(generatedPoints);
// Expected output: 
// [
//   { x: <timestamp for 2024-01-01> * 10, y: 50 },
//   { x: <timestamp for 2024-01-02> * 10, y: 100 },
//   { x: <timestamp for 2024-01-03> * 10, y: 75 }
// ]

view raw JSON →