API difference between parse() and to() (convert()) is unwieldy

[drwpow]

This is more of a question than a suggestion, but I’m using the programmatic API (colorjs.io/fn). There are 2 main functions I’m using that have different return signatures:

import { parse, to } from 'colorjs.io/fn';

// (setup, etc.) 

const rebeccaPurple = "#663399";

parse(rebeccaPurple);      // { spaceId: 'srgb' … } ❌ This is different from to()!
to(rebeccaPurple, 'srgb'); // { space: { id: 'srgb' … }, … } ❌ This is different from parse()!

Update: updated the example to highlight my question a little better

When working back-and-forth between these two APIs, I have to write helper functions that combine these shapes together so I’m working with the same type. Otherwise I have to write code like this, which gets verbose and boilerplate-y:

const spaceId = 'spaceId' in someColor ? someColor.spaceId : someColor.space.id;

My question is, is there another API I’m missing that could help? Or would it be possible to merge the shapes of ColorConstructor and PlainColorObject? This may either be a suggestion for an API change or it may just be a docs request.

---

As an aside, the docs for the procedural API have a typo (at least according to the types), which I can make a ticket for separately:

  // Directly creating object literal
- const p3_lime = {space: "p3", coords: [0, 1, 0]};
+ const p3_lime = {spaceId: "p3", coords: [0, 1, 0]};

  const p3_lime_srgb = convert(p3_lime, "srgb");

[LeaVerou]

There should not be any API difference. When using object literals as input you provide spaceId so that you don't have to fetch the color space yourself. You can also provide space with a color space object. Any output colors will have a resolved color space in the space property.

My question is, is there another API I’m missing that could help?

The OO API is more high level and takes care of these things for you. The procedural API is mainly meant for high performance cases or where tree-shaking is desired.

[drwpow]

When using object literals as input you provide spaceId so that you don't have to fetch the color space yourself. You can also provide space with a color space object.

Thanks! My question was more around the outputs of each function, not the inputs. parse() will ONLY return the {spaceId: "p3" … } format, whereas to() ONLY returns {space: P3 … } format. So I have to coerce the two different types to agree.

There should not be any API difference.

So would it be worthwhile to explore parse() instead returning the {space: P3 … } format instead? This would be a breaking change.

The OO API is more high level and takes care of these things for you. The procedural API is mainly meant for high performance cases or where tree-shaking is desired.

I don’t mind doing work, but I more wanted to understand the API design between the two. I do have a high-performance case AND tree-shaking is required.

[LeaVerou]

Oh, I see. Yes, space should be in the output, since parse() needs access to the color space object to read its formats so there's no reason to throw that away.