go-colorful

A TypeScript port of the go-colorful package providing comprehensive color space manipulation and conversion functions.

Features

This library provides 100% API compatibility with the original Go package, including:

Color Space Support

• RGB: Standard Red, Green, Blue color space
• HSL: Hue, Saturation, Lightness
• HSV: Hue, Saturation, Value
• Hex: HTML hex colors like #FF0080
• Linear RGB: Gamma-corrected RGB space
• CIE XYZ: CIE standard color space
• CIE xyY: Chromaticity + luminance representation
• CIE Lab*: Perceptually uniform color space
• CIE Luv*: Alternative perceptual color space
• CIE LCh° (HCL): Polar coordinates of Lab* (better HSV)
• CIE LCh(uv): Polar coordinates of Luv*
• OkLab: Improved perceptual color space
• OkLch: Polar coordinates of OkLab
• HSLuv: Better alternative to HSL
• HPLuv: Variant of HSLuv for pastel colors

Color Operations

• Distance calculations: RGB, Lab, Luv, CIE76, CIE94, CIEDE2000, Riemersma
• Color blending: In RGB, Linear RGB, HSV, Lab, Luv, HCL, LuvLCh, OkLab, OkLch
• Color validation: Check if colors are in valid RGB gamut
• Color clamping: Force colors into valid RGB range

Color Generation

• Random colors: Generate warm, happy, or random colors
• Palette generation: Create harmonious color palettes
• Color sorting: Sort colors for smooth visual transitions

Installation

bun add @tsports/go-colorful

Two API Styles

This package provides two identical APIs with different naming conventions:

1. TypeScript Style (default) - Uses camelCase methods and TypeScript conventions
2. Go Style - Uses exact Go naming conventions (PascalCase) for easy porting

Both APIs are functionally identical and produce the exact same results.

Usage

TypeScript Style API (Default)

import { Color, Hex, HSV, Lab, HCL } from '@tsports/go-colorful';

// Create colors in different ways
const c1 = new Color(0.313725, 0.478431, 0.721569); // Direct RGB
const c2 = Hex("#517AB8");        // From hex string
const c3 = HSV(216.0, 0.56, 0.722); // From HSV
const c4 = Lab(0.507850, 0.040585, -0.370945); // From Lab
const c5 = HCL(276.2440, 0.373160, 0.507849);  // From HCL

console.log(c1.hex()); // "#517ab8"
// camelCase methods: isValid(), rgb255(), hsv(), lab(), etc.

Go Style API (For Go Developers)

import * as GoStyle from '@tsports/go-colorful/go-style';

// Same functionality, Go naming conventions
const c1 = new GoStyle.Color(0.313725, 0.478431, 0.721569); // R, G, B fields
const c2 = GoStyle.Hex("#517AB8");        // From hex string
const c3 = GoStyle.Hsv(216.0, 0.56, 0.722); // From HSV
const c4 = GoStyle.Lab(0.507850, 0.040585, -0.370945); // From Lab
const c5 = GoStyle.Hcl(276.2440, 0.373160, 0.507849);  // From HCL

console.log(c1.Hex()); // "#517ab8"
// PascalCase methods: IsValid(), RGB255(), Hsv(), Lab(), etc.

Color Space Conversions

// TypeScript Style
const color = Hex("#517AB8");
const [h, s, v] = color.hsv();
const [l, a, b] = color.lab();
const [hcl_h, c, hcl_l] = color.hcl();
const [r, g, b_255] = color.rgb255();

// Go Style - same results, different method names
const goColor = GoStyle.Hex("#517AB8");
const [h2, s2, v2] = goColor.Hsv();    // Note: Hsv not hsv
const [l2, a2, b2] = goColor.Lab();    // Note: Lab not lab
const [r2, g2, b2_255] = goColor.RGB255(); // Note: RGB255 not rgb255

console.log(`HSV: ${h.toFixed(1)}, ${s.toFixed(3)}, ${v.toFixed(3)}`);

Color Distance & Comparison

import { Color } from '@tsports/go-colorful';

const c1 = new Color(0.5, 0.1, 0.8);
const c2 = new Color(0.3, 0.2, 0.6);

// Different distance metrics
console.log('RGB distance:', c1.distanceRgb(c2));
console.log('Lab distance:', c1.distanceLab(c2)); // Perceptually accurate
console.log('CIEDE2000 distance:', c1.distanceCIEDE2000(c2)); // Most accurate

Color Blending

import { Hex } from '@tsports/go-colorful';

const warm = Hex("#fdffcc");
const cool = Hex("#242a42");

// Blend in different color spaces
const blended_rgb = warm.blendRgb(cool, 0.5);
const blended_lab = warm.blendLab(cool, 0.5);     // Better for gradients
const blended_hcl = warm.blendHcl(cool, 0.5);     // Best for most uses

Random Color Generation

import {
  FastWarmColor,
  WarmColor,
  FastHappyColor,
  HappyColor
} from '@tsports/go-colorful';

// Generate random colors
const warmColor = WarmColor();     // Slow but consistent
const fastWarm = FastWarmColor();  // Fast but less consistent

const happyColor = HappyColor();   // Bright colors
const fastHappy = FastHappyColor(); // Fast bright colors

Palette Generation

import {
  SoftPalette,
  WarmPalette,
  HappyPalette,
  FastWarmPalette
} from '@tsports/go-colorful';

// Generate color palettes
const [softColors, error] = SoftPalette(5);
const [warmColors, warmError] = WarmPalette(8);
const [happyColors, happyError] = HappyPalette(6);
const fastWarmColors = FastWarmPalette(10);

if (!error) {
  console.log('Generated', softColors.length, 'colors');
}

Color Sorting

import { Sorted, FastHappyPalette } from '@tsports/go-colorful';

// Generate random colors and sort them for smooth transitions
const randomColors = FastHappyPalette(20);
const sortedColors = Sorted(randomColors);

console.log('Colors sorted for smooth visual transition');

API Compatibility

This TypeScript port provides 100% API compatibility with the original Go package:

TypeScript Style API

• Modern TypeScript conventions: camelCase methods, lowercase properties
• Best for new projects: Follows TypeScript/JavaScript community standards
• Examples: color.isValid(), color.distanceLab(), color.rgb255()

Go Style API

• Identical to Go: Exact method names, PascalCase, same signatures
• Perfect for porting: Copy Go code with minimal changes
• Examples: color.IsValid(), color.DistanceLab(), color.RGB255()

Key Features of Both APIs:

• Classes instead of structs (Color class vs Color struct)
• Error handling uses exceptions for invalid inputs instead of Go's error return pattern
• Some functions return tuples [result, error] to match Go's multiple return values
• 100% identical results - both APIs produce exactly the same output

Performance

The library includes both fast and accurate versions of many operations:

• FastLinearRgb vs LinearRgb
• FastWarmColor vs WarmColor
• FastHappyPalette vs HappyPalette

Fast versions use approximations and simpler color spaces (like HSV) while accurate versions use perceptually uniform spaces (like HCL) but are slower.

Development

To install dependencies:

bun install

To run tests:

bun test

To build:

bun run build

License

MIT License - same as the original go-colorful package.

Credits

This is a port of the excellent go-colorful library by Lucas Beyer and contributors. All color science and algorithms are from the original implementation.