Idea: Variation helper type to extract a variant

[hellos3b]

I've been rereading the docs as I switch over to variant@dev, and have a suggestion in reference to "That type annotation"

Complexity

The type has been a sore spot in using the library. Along with having to find and copy and paste the definition for each variation (I use it everywere), hovering over the type actually does expose a fair bit of complexity:

type Animal<T extends TypeNames<{ 
cat: VariantCreator<"cat", (input: { name: string; furnitureDamaged: number; }) => { name: string; furnitureDamaged: number; }, "type">; 
dog: VariantCreator<"dog", (input: { name: string; favoriteBall?: string | undefined; }) => { name: string; favoriteBall?: string | undefined; }, "type">; 
snake: VariantCreator<...>; }> = undefined> = T extends undefined ? {
    type: "cat";
    name: string;
    furnitureDamaged: number;
} | {} /** (.... plus many more lines) */

Meanwhile the early example of using just VariantOf<typeof Animal> looks like the union that you would expect:

type Animal = {
    type: "cat";
    name: string;
    furnitureDamaged: number;
} | {
    type: "dog";
    name: string;
    favoriteBall?: string | undefined;
} | {
    type: "snake";
    name: string;
    pattern: any;
}

As I'm looking at the docs, it seems the main reason for the complicated type is to enable the type Animal<'dog'>

Suggestion

Make a small helper wrapper around Extract to that simplifies getting variations

type Variation<V extends { type: string }, T extends V["type"]> =
    Extract<V, { type: T }>

Usage:

export type Animal = VariantOf<typeof Animal>
const bark = (dog: Variation<Animal, 'dog'>) => {}

export type Snake = Variation<Animal, 'snake'>

Playground Link

1. API is very simplified and the type definition looks standard
2. It still autocompletes for the tag ('dog')
3. Get an error if the tag does not exist in the variant
4. (opinion) As a consumer it'd be better to reference a type of Dog instead of Animal<'dog'>

[paarthenon]

Overall I like the suggestion. I do see a problem, though, when you use discriminants other than type.

type Variation<V extends { type: string }, T extends V["type"]> =
    Extract<V, { type: T }>

In order to make this agnostic, you could introduce K like the lib used to do in 2.0

type Variation<V extends Record<K, string>, T extends V[K], K extends string = 'type'> =
    Extract<V, Record<K, T>>

But at that point you are typing Variation<Animal, 'dog', 'kind'> and that's not too much better than Extract<Animal, {kind: 'dog'}>. And unfortunately I don't think we can write GetVariation<'kind'> in TypeScript.

I'm thinking the best place for this may be the documentation since the package would suffer from TS's limitations. As I've been retooling the 3.0 docs I've been leading with the simpler form in those examples anyway. If this code is listed then when a user defines Variation following that pattern, they can change 'type' to whatever property they use and enjoy the same benefits.

---

As far as the type goes, I find myself using this VSCode snippet. It sets up multiple cursors as well, which saves some keystrokes.

  "Variant type definition": {
    "prefix": "vt",
    "body": "export type $1<T extends TypeNames<typeof $1> = undefined> = VariantOf<typeof $1, T>",
    "description": "Define a type for a variant."
  },

But you're more than welcome to use type Animal = VariantOf<typeof Animal> and your implementation of Variation. That should work perfectly.