tessl/npm-d3-interpolate

Interpolate numbers, colors, strings, arrays, objects, whatever!

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Basic Data Types

Name: tessl/npm-d3-interpolate
Author: tessl

Core interpolators for primitive data types including numbers, strings, and dates.

Capabilities

Number Interpolation

Linear interpolation between two numbers.

/**
 * Returns an interpolator between the two numbers a and b.
 * Equivalent to: function(t) { return a * (1 - t) + b * t; }
 * @param a - Starting number
 * @param b - Ending number
 * @returns Interpolator function returning interpolated number
 */
function interpolateNumber(a: number, b: number): (t: number) => number;

Usage Examples:

import { interpolateNumber } from "d3-interpolate";

const interp = interpolateNumber(10, 20);
console.log(interp(0.0)); // 10
console.log(interp(0.2)); // 12
console.log(interp(0.5)); // 15
console.log(interp(1.0)); // 20

// Works with negative numbers
const negInterp = interpolateNumber(-5, 5);
console.log(negInterp(0.5)); // 0

// Works with decimal numbers
const decimalInterp = interpolateNumber(1.5, 2.5);
console.log(decimalInterp(0.5)); // 2.0

Caution: Avoid interpolating to or from zero when the result will be stringified, as very small values may be converted to scientific notation (e.g., 1e-7), which is invalid in CSS. Use 1e-6 as the minimum value to avoid scientific notation.

Rounded Number Interpolation

Number interpolation with automatic rounding to nearest integer.

/**
 * Returns an interpolator between two numbers that rounds to nearest integer.
 * Similar to interpolateNumber but rounds the result.
 * @param a - Starting number
 * @param b - Ending number
 * @returns Interpolator function returning rounded integer
 */
function interpolateRound(a: number, b: number): (t: number) => number;

Usage Examples:

import { interpolateRound } from "d3-interpolate";

const roundInterp = interpolateRound(10, 20);
console.log(roundInterp(0.1)); // 11
console.log(roundInterp(0.3)); // 13
console.log(roundInterp(0.7)); // 17
console.log(roundInterp(0.9)); // 19

// Useful for pixel values or indices
const pixelInterp = interpolateRound(0, 100);
console.log(pixelInterp(0.333)); // 33 (rounded from 33.3)

String Interpolation

Interpolation between strings with embedded number detection.

/**
 * Returns an interpolator between two strings with embedded number interpolation.
 * Detects numbers within strings and interpolates them while keeping static parts.
 * @param a - Starting string
 * @param b - Ending string (template)
 * @returns Interpolator function returning interpolated string
 */
function interpolateString(a: string, b: string): (t: number) => string;

Number Detection:

The interpolator finds numbers embedded in both strings, including:

Integers: -1, 42
Decimals: 3.14159
Scientific notation: 6.0221413e+23

Usage Examples:

import { interpolateString } from "d3-interpolate";

// CSS property interpolation
const cssInterp = interpolateString("300 12px sans-serif", "500 36px Comic-Sans");
console.log(cssInterp(0.0)); // "300 12px sans-serif"
console.log(cssInterp(0.5)); // "400 24px Comic-Sans"
console.log(cssInterp(1.0)); // "500 36px Comic-Sans"

// Multiple numbers in string
const multiInterp = interpolateString("M10,20 L30,40", "M50,60 L70,80");
console.log(multiInterp(0.5)); // "M30,40 L50,60"

// Percentage values
const percentInterp = interpolateString("width: 10%", "width: 90%");
console.log(percentInterp(0.5)); // "width: 50%"

// No matching numbers (returns template)
const noMatchInterp = interpolateString("foo", "bar");
console.log(noMatchInterp(0.5)); // "bar"

// Scientific notation
const sciInterp = interpolateString("1e-6", "1e-3");
console.log(sciInterp(0.5)); // "0.0005005" (approximately)

Date Interpolation

Linear interpolation between Date objects.

/**
 * Returns an interpolator between two Date objects.
 * Interpolates the underlying timestamp values.
 * @param a - Starting Date
 * @param b - Ending Date
 * @returns Interpolator function returning Date object
 */
function interpolateDate(a: Date, b: Date): (t: number) => Date;

Performance Note: No defensive copy is created; the same Date instance is returned for every evaluation. This is optimized for performance in animation loops but means the returned Date should not be mutated.

Usage Examples:

import { interpolateDate } from "d3-interpolate";

const startDate = new Date(2020, 0, 1); // January 1, 2020
const endDate = new Date(2021, 0, 1);   // January 1, 2021

const dateInterp = interpolateDate(startDate, endDate);

console.log(dateInterp(0.0)); // January 1, 2020
console.log(dateInterp(0.5)); // ~July 2, 2020 (mid-year)
console.log(dateInterp(1.0)); // January 1, 2021

// Time-of-day interpolation
const morning = new Date(2023, 5, 15, 9, 0, 0);  // 9:00 AM
const evening = new Date(2023, 5, 15, 17, 0, 0); // 5:00 PM

const timeInterp = interpolateDate(morning, evening);
console.log(timeInterp(0.5)); // 1:00 PM same day

// Cross-timezone interpolation (works with timestamps)
const utcStart = new Date("2023-01-01T00:00:00Z");
const utcEnd = new Date("2023-01-02T00:00:00Z");

const utcInterp = interpolateDate(utcStart, utcEnd);
console.log(utcInterp(0.5)); // Noon on January 1, 2023 UTC

Install with Tessl CLI