saturon/toArray

The saturon/toArray subpath exports the toArray() function and the normalizeComponentValue() helper. It returns a color's component coordinates as a numeric array, with optional replacement of non-finite values, gamut fitting, and precision adjustments.

toArray()

Extracts component coordinates from a ColorData object. By default, it replaces non-finite channel values with component-appropriate values, applies gamut fitting and precision, and clamps alpha to [0, 1].

import { toArray } from "saturon/toArray";

const color = { model: "rgb", coords: [300, -20, 150, 0.8555] };
const array = toArray(color, { fit: "clip", precision: 2 });

console.log(array); // [255, 0, 150, 0.86]

Signature

function toArray(color: ColorData, options?: ComponentOptions): number[];

Parameters

Options (ComponentOptions)

Returns

An array of numbers containing fitted color coordinates in the model's native units, with alpha included when the model defines it (e.g., [r, g, b, alpha]). If alpha is absent from the input, it defaults to 1; the resulting alpha is clamped to [0, 1].

normalizeComponentValue()

A helper utility used internally by toArray() to resolve non-finite values into model-appropriate numeric bounds.

import { normalizeComponentValue } from "saturon/toArray";

// Resolves Infinity to max component value (360 for hue)
const maxHue = normalizeComponentValue(Infinity, "hue"); // 360

// Resolves NaN to 0
const fallback = normalizeComponentValue(NaN, "percentage"); // 0

// Opt out of non-finite value normalization
const unchanged = normalizeComponentValue(Infinity, "hue", false); // Infinity

Signature

function normalizeComponentValue(
    component: number,
    value: ComponentDefinition["value"],
    normalized?: boolean
): number;

Normalization Rules

• When normalized is false, returns the value unchanged, including NaN and infinities.
• Otherwise, finite numbers are returned unchanged and NaN (or a non-number at runtime) becomes 0.
• Infinity becomes the component's maximum: 360 for "hue", 100 for "percentage", 1 for "alpha-value", or the upper bound for an explicit range [min, max].
• -Infinity becomes the component's minimum: 0 for string-defined component types or the lower bound for an explicit range.

Behavior

1. Retrieves the component layout for the specified color model; throws if the model has no defined layout.
2. Normalizes each non-alpha coordinate when normalized is true (the default). This handles non-finite values; it does not convert coordinates from native units to a 0–1 scale.
3. Applies the selected fit method (or the engine default) to the color coordinates and rounds them according to precision or each component's default precision.
4. Defaults missing alpha to 1, normalizes it when requested, rounds it according to precision or the alpha component's default precision, then clamps it to [0, 1].

Usage Example

import { toArray } from "saturon/toArray";

const hslData = { model: "hsl", coords: [180, Infinity, 50] };

// Normalizes Infinity to 100% saturation and returns alpha as 1
const normalized = toArray(hslData);
console.log(normalized); // [180, 100, 50, 1]

Errors

• Throws an error if the specified color model has no component layout, or if the selected fit method is invalid.