DOMRGBAColor.ts

namespace DOMRGBAColor {
    /**
     * Float64Array of length 4: [R, G, B, A]. Each is normalized to range [0 .. 1]
     * [Bikeshed] or Float32Array?
     */
    export type FVec4 = Float64Array & { length: 4 };
    /**
     * Uint8ClampedArray of length 4: [R, G, B, A]
     */
    export type IVec4 = Uint8ClampedArray & { length: 4 };

    export interface Options {
        premultipliedAlpha?: boolean;
    }
}

declare class DOMRGBAColor {
    /**
     * Same as new DOMRGBAColor(colorString).toString();
     * Normalize the color string into a caninical rgba() representation.
     * Two identical colors should have the same canonical representation,
     * This static method is primarily intended to imporve caching.
     * ex.: `#FF0000FF`, `#F00`, `rgb(100%, 0%, -0.0e+0%)`, hsl(0, 100%, 50%)
     * all should be formatted as `rgba(255, 0, 0, 1)`
     * [Bikeshed] the format.
     * @throws SyntaxError 
     */
    static normalize(colorString: string): string; // 'rgba(255, 127, 0, 0.5)'

    /**
     * @throws TypeError if `channels` is not FVec4 of Ivec4.
     * [?] @throws RangeError if any of the FVec4 values are not normalized in ranage [0..1].
     */
    static from(channels: DOMRGBAColor.FVec4 | DOMRGBAColor.IVec4, options?: DOMRGBAColor.Options): DOMRGBAColor;

    /**
     * Compare if two colors are essentially the same color.
     * Comparing with { premultipliedAlpha: true } can be used to check
     * if the colors are the same when rendered.
     */
    static equals(colorA: string | DOMRGBAColor, colorB: string | DOMRGBAColor, options?: DOMRGBAColor.Options): boolean;

    /**
     * @throws SyntaxError 
     */
    constructor(colorString: string);

    /**
     * Returns the canonical representation.
     * There is now way to get the rgba string with premult alpha.
     */
    public toString(): string; // 'rgba(255, 127, 0, 0.5)'

    public toFvec4(options?: DOMRGBAColor.Options): DOMRGBAColor.FVec4; // [1.0, 0.5, 0.0, 0.5]
    public toIvec4(options?: DOMRGBAColor.Options): DOMRGBAColor.IVec4; // [255, 127, 0, 127]
}


// Premultiplied alpha is often used to optimize blending computations
new DOMRGBAColor('rgba(100%, 50%, 0%, 50%)').toFvec4(); // [1.0, 0.5, 0.0, 0.5]
new DOMRGBAColor('rgba(100%, 50%, 0%, 50%)').toFvec4({ premultipliedAlpha: true }); // [0.5, 0.25, 0.0, 0.5]

// Nomalization of rgba strings may improve caching:
const cacheKey1 = DOMRGBAColor.normalize('#FF0000FF'); // rgba(255, 0, 0, 1)
const cacheKey2 = DOMRGBAColor.normalize('hsla(+000.000e+0000, 100000%, 50%)'); // rgba(255, 0, 0, 1)

// By comparting two normalized values we can tell if colors are essentially the same.
// However it can be more easy to call the .equals() static method:
DOMRGBAColor.equals('rgba(0, 0, 0, 0)', 'rgba(0, 0, 0, 1)'); // false

// When comparing with the premult alpha we can tell if the colors are essentially the same *when rendered*:
DOMRGBAColor.equals('rgba(0, 0, 0, 0)', 'rgba(0, 0, 0, 1)', { premultipliedAlpha: true }); // true
DOMRGBAColor.equals('rgba(255, 127, 0, 0)', 'transparent', { premultipliedAlpha: true }); // true