Typescript support

[Olian04]

Are there any plans to support typescript when version 1.0 releases?

[LeaVerou]

We'd welcome PRs to add typings files, but it's pretty low priority to write such files ourselves.

[Olian04]

@LeaVerou may I ask why TypeScript support isn't a priority? It seems odd for a library of this proportion not to prioritize interoperability with other JavaScript "dialects", such as TypeScript. Especially seeing how popular TypeScript has become over the past few years.

[LeaVerou]

Only because time is finite 😊

[Olian04]

@LeaVerou would you be willing to document your code using jsdoc? Because if you did then you could generate typescript declaration files from those jsdoc strings using the typescript compiler. See https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html

[benmccann]

More discussion about this in #168 (comment)

[NatoBoram]

Personally, I'd vote for a full TypeScript makeover since it would benefit all JavaScript flavours, text editors, IDEs, linters and language servers simultaneously, but that's just me.

Is this something that you would find interesting?

---

Also why this?

https://github.com/LeaVerou/color.js/blob/6ed9499e69a3f1fa2f3e105fb925e36add930b55/src/color.js#L186-L209

Even if someone were to auto-generate .d.ts files, they would need to do so much work to manually assemble the generated functions and properties with the ones that are injected at run time...

... and I've done that so I could use it in my personal project. It's a nice starting point, but it would be nicer if the library itself could provide its types.

/* eslint-disable @typescript-eslint/no-explicit-any */
/* eslint-disable @typescript-eslint/explicit-module-boundary-types */

declare module "colorjs.io" {
  /**
   * Class that represents a color
   */
  export default class Color {
    #private
    alpha: any
    coords: any

    /**
     * Creates an instance of Color.
     * Signatures:
     * - `new Color(stringToParse)`
     * - `new Color(otherColor)`
     * - `new Color({space, coords, alpha})`
     * - `new Color(space, coords, alpha)`
     * - `new Color(spaceId, coords, alpha)`
     */
    constructor(...args: unknown[])

    get space(): any
    get spaceId(): any

    static defineFunction(name: any, code: any, o?: any, ...args: any[]): void
    static defineFunctions(o: any): void
    static extend(exports: any): void

    /**
     * Get a color from the argument passed
     * Basically gets us the same result as new Color(color) but doesn't clone an existing color object
     */
    static get(color: any, ...args: any[]): Color

    clone(): Color
    display(...args: any[]): string

    /**
     * Euclidean distance of colors in an arbitrary color space
     */
    distance(color2: Color, space?: string): number
    equals(color1: any, color2: any): any
    get(color: any, prop: any): number

    /**
     * Get the coordinates of a color in another color space
     *
     * @param {string | ColorSpace} space
     * @returns {number[]}
     */
    getAll(color: any, space: ColorSpace | string): number[]

    /**
     * Check if a color is in gamut of either its own or another color space
     * @return {Boolean} Is the color in gamut?
     */
    inGamut(
      color: any,
      space?: any,
      { epsilon }?: { epsilon?: number }
    ): boolean

    set(color: any, prop: any, value: any, ...args: any[]): any
    setAll(color: any, space: any, coords: any): any

    /**
     * Convert to color space and return a new color
     * @param {Object|string} space - Color space object or id
     * @param {Object} options
     * @param {boolean} options.inGamut - Whether to force resulting color in gamut
     * @returns {Color}
     */
    to(color: any, space: any | string, { inGamut }?: { inGamut: any }): Color

    /**
     * Force coordinates to be in gamut of a certain color space.
     * Mutates the color it is passed.
     * @param {Object} options
     * @param {string} options.method - How to force into gamut.
     *        If "clip", coordinates are just clipped to their reference range.
     *        If in the form [colorSpaceId].[coordName], that coordinate is reduced
     *        until the color is in gamut. Please note that this may produce nonsensical
     *        results for certain coordinates (e.g. hue) or infinite loops if reducing the coordinate never brings the color in gamut.
     * @param {ColorSpace|string} options.space - The space whose gamut we want to map to
     */
    toGamut(
      color: any,
      { method, space }?: { method?: string; space?: any },
      ...args: any[]
    ): any
    toJSON(): { spaceId: any; coords: any; alpha: any }

    /**
     * Generic toString() method, outputs a color(spaceId ...coords) function, a functional syntax, or custom formats defined by the color space
     * @param {Object} options
     * @param {number} options.precision - Significant digits
     * @param {boolean} options.inGamut - Adjust coordinates to fit in gamut first? [default: false]
     */
    toString(
      color: any,
      {
        precision,
        format,
        inGamut,
        ...customOptions
      }?: { precision?: number; format?: string; inGamut?: boolean }
    ): any
  }
}

[MysteryBlokHed]

I'm working on types for color.js right now on DefinitelyTyped/DefinitelyTyped#62510. I prefer DefinitelyTyped for definitions files because I think they have good infrastructure to test and maintain, but I could make a PR here instead if people want that.

If I continue on DefinitelyTyped, I could add any contributors here who are interested in maintaining those types to the list of owners. That way, you'd be automatically notified about changes to the types and be able to merge them.

[benmccann]

Including them here is much better because you can make sure they stay in sync. The types on DefinitelyTyped frequently don't get updated when the main package does. It's easy enough to setup the small amount of infrastructure required here

[MysteryBlokHed]

I'll work on moving the types to a PR over here. If maintainers are interested, I'll also try to configure a CI job to test the types with dtslint the way DefinitelyTyped does.

[MysteryBlokHed]

I just opened #221 to bring the types over from DefinitelyTyped, but I'm having trouble getting TypeScript and dtslint to work properly, at least on my local setup.