d3-scale

d3-scale is the scale module of D3.js, providing the functions that map a dimension of abstract data — numbers, dates, categories — onto a visual representation such as pixel position, color, or stroke width. It implements the full family of scale types used across data visualization: continuous scales (linear, power, log, symlog, radial, time/UTC) that interpolate smoothly between a domain and range, and discrete scales (ordinal, band, point, quantile, quantize, threshold) that bucket or index values instead of interpolating them. Sequential and diverging scales extend the same machinery to color encoding, commonly paired with d3-scale-chromatic’s color schemes.

Each scale is a small, composable function built on a shared continuous()/transformer() core (in src/continuous.js), so behavior like clamping, custom interpolation, and nice() domain rounding is implemented once and reused by every continuous scale type rather than duplicated per scale. The module depends on other single-purpose D3 packages (d3-array, d3-interpolate, d3-time, d3-format) instead of bundling their logic, keeping it usable standalone or as part of the full D3 bundle.

What You Get

• Continuous scales — linear, power/sqrt, log, symlog, and radial — for mapping numeric domains to numeric ranges with optional clamping and custom interpolation
• Time and UTC scales that map Date domains to a range, with calendar-aware tick generation and formatting
• Discrete scales — ordinal, band, and point — for mapping categorical domains to colors, bar positions, or fixed points
• Quantile, quantize, and threshold scales for bucketing continuous input into a fixed set of discrete outputs
• Sequential and diverging scales for one- and two-hued color encodings, including quantile-based variants
• Built-in nice(), ticks(), and tickFormat() helpers for producing human-readable axis gridlines from any continuous scale

Common Use Cases

• Mapping a numeric or time-series column to horizontal/vertical pixel position in a scatterplot or line chart
• Encoding a categorical field as color or bar position using an ordinal or band scale
• Building a choropleth or heatmap by feeding a numeric domain through a sequential or quantile color scale
• Generating axis ticks and labels automatically from a chart’s data domain via ticks()/tickFormat()
• Converting a continuous data range into a fixed number of visual buckets with quantize or threshold scales

Under The Hood

Architecture The module is organized as one small file per scale type (linear.js, log.js, time.js, ordinal.js, band.js, quantile.js, sequential.js, diverging.js, etc.), all re-exported through a flat src/index.js. Continuous numeric scales share a single core: continuous.js exposes a transformer() closure that holds domain/range/interpolate/clamp state and produces the actual scale function via bimap/polymap piecewise interpolation, plus an invert path built the same way in reverse. Scale-specific files like linear.js, log.js, and pow.js wrap this core with a transform/untransform pair (identity, log, power) rather than reimplementing interpolation, so adding a new continuous scale type is a matter of supplying two functions. Time scales (time.js) reuse the same continuous core through a calendar() wrapper that swaps in calendar-aware tick and nice logic from d3-time. Discrete scales (ordinal.js, band.js) are structurally separate, built around an InternMap-backed index rather than the continuous transformer, since they classify rather than interpolate.

Tech Stack Plain ES modules with no build-time framework dependency — type: module in package.json, published as both raw src/**/*.js and a Rollup-built UMD/minified dist bundle for unpkg/jsdelivr. It composes rather than reimplements the rest of the D3 ecosystem: d3-array for bisect/ticks/InternMap, d3-interpolate for value interpolation, d3-time/d3-time-format for calendar scales, and d3-format for tick formatting. Tests run under Mocha with plain assert, and ESLint lints both src and test; there is no TypeScript — types ship from DefinitelyTyped separately.

Code Quality Every scale type has a dedicated *-test.js file exercising defaults, edge cases (reversed domains, degenerate zero-width domains, clamping), and copy() independence, run via TZ=America/Los_Angeles mocha 'test/**/*-test.js' so time-scale tests are timezone-deterministic. Code style favors terse, functional closures over classes — mutable state is closed over in local vars and every scale returns a plain function object with methods attached, a longstanding D3 idiom rather than an ES class. No runtime type checking; correctness leans entirely on the test suite and ESLint rather than TypeScript. CI (GitHub Actions) runs the Node test matrix plus lint on every push and PR.

What Makes It Unique Rather than one monolithic scale abstraction, d3-scale factors the numeric-continuous case into a single reusable transformer shared by seven+ scale types (linear, pow, sqrt, log, symlog, radial, time), while keeping genuinely different behavior (ordinal/band’s index-based classification, quantile/quantize/threshold’s bucketing) as separate implementations — avoiding both a bloated one-size-fits-all scale class and needless duplication across the continuous family. This is a deliberate, narrow design choice rather than a novel algorithm, consistent with D3’s broader philosophy of small, focused, composable modules.