Variant 3.0

[paarthenon]

I've begun work on version 3.0 which will be a mild to moderate rewrite of some of variant's core.

---

Changes now accessible with variant@dev

---

Changes

Name swap.

Right now the variant() function is used to construct a single case, while variantModule() and variantList are used to construct a variant from an object or a list, respectively. This leads to the function that I almost never use (single case of a variant) holding prime real estate. To that end, variant() is becoming variation() and the variant() function will be an overload that functions as both variantModule and variantList. This is a notable breaking change, hence the tick to 3.0.

Less dependence on "type"

The type field is used as the primary discriminant. This is causing an implicit divide in the library and its functionality as I tend to write things to initially account for "type" and then generalize. However, this is not ideal. My plan is to take the approach with variant actually being variantFactory('type').

The result will be an entire package of variant functions specifically working with tag or __typename.

export const {isType, match, variant, variation} = variantCosmos({key: 'type'});

// simply change the key type.
export const {isType, match, variant, variation} = variantCosmos({key: '__typename'});

This should handily resolve #12 .

Better documentation and error handling (UX as a whole)

I've received feedback that larger variants can be tough to read when missing or extraneous cases are present. I will be using conditional types and overloads to better express more specific errors.

I will also be rewriting the mapped types so that documentation added to the template object of variantModule will be present on the final constructors.

Assorted cleanup

This will officially get rid of partialMatch now that it's no longer necessary. I'm not sure, but lookup may go as well. It's on the edge of being useful. I personally almost never use it. I've thought about allowing match to accept single values as entries but am worried about ambiguity in the case where a match handler attempts to "return" a function. How is that different from a handler branch, which should be processed.

Also I will probably be removing the default export of this package (the variant function). Creating a variant, especially with the associated type, involves several imports by itself. What would be the point of a default export? Perhaps variantCosmos, but even that is a bit sketchy.

I finagled with the match types and now the assumed case is that match() will be exhaustive. There is an optional property called default, but actually attempting to use said property moves to the second overload, flipping expectations and making default required and every other property optional. This results in a better UX because as an optional property default is at the bottom of the list when entering names for the exhaustive match.

[paarthenon]

matchLiteral will also be removed, replaced with an onLiteral helper.

Instead of calling a separate function, simply call the helper inside the match expression.

declare const animal: Animal;

const aniType = animal.type; // type: 'cat' | 'dog' | 'snake';

const result = match(onLiteral(aniType), {
    cat: ({type}) => type,
    default: constant(6),
});

[paarthenon]

I've made progress on improved error reporting. Here is the message regarding missing keys on the matcher's complete() function.

[paarthenon]

I've put effort into a new generics implementation. The interface is much improved!

Instead of needing to call a separate function and store the object in two different variables, we can simply use the helper function onTerms() that makes variant() generic-aware.

By that same token, GTypeNames is no longer necessary.

Examples

Option<T>

The option (a.k.a. maybe) type is very simple to define and use.

const Option = variant(onTerms(({T}) => ({
    Some: payload(T),
    None: {},
})));
type Option<T, TType extends TypeNames<typeof Option> = undefined>
    = GVariantOf<typeof Option, TType, {T: T}>;

const num = Option.Some(4);
const name = Option.Some('Steve');

As you might expect, name cannot be assigned to num, as the types of payload will not match.

It is just as elegant to write the extract function:

Note that I did not annotate the return type. TS will infer from the match statement.

Tree<T>

Trees will need to be defined type-first like all recursive variants.

const Tree = variant(onTerms(({T}) => {
    type Tree<T> =
        | Variant<'Branch', {payload: T, left: Tree<T>, right: Tree<T>}>
        | Variant<'Leaf', {payload: T}>
    ;
    return {
        Branch: fields<{left: Tree<typeof T>, right: Tree<typeof T>, payload: typeof T}>(),
        Leaf: payload(T),
    }
}));
type Tree<T, TType extends TypeNames<typeof Tree> = undefined> 
    = GVariantOf<typeof Tree, TType, {T: T}>;

but otherwise follow the same process.

const binTree = Tree.Branch({
    payload: 1,
    left: Tree.Branch({
        payload: 2,
        left: Tree.Leaf(4),
        right: Tree.Leaf(5),
    }),
    right: Tree.Leaf(3),
})

function depthFirst<T>(node: Tree<T>): T[] {
    return match(node, {
        Leaf: ({payload}) => [payload],
        Branch: ({payload, left, right}) => {
            return [payload, ...depthFirst(left), ...depthFirst(right)];
        }
    })
}

const [d1, d2, d3, d4, d5] = depthFirst(binTree);
expect(d1).toBe(1);
expect(d2).toBe(2);
expect(d3).toBe(4);
expect(d4).toBe(5);
expect(d5).toBe(3);

[paarthenon]

Variant constructors and variants themselves now follow behavior that I want to call monadic, but I don't want to fight pedants, so let's say instead they work like Promises in that a variant is only ever one "level" deep. Now,

variant() can now accept arbitrary variant creators, not just template functions. Since a variant is just an object of these constructors, you can clone the variant Animal via const Animal2 = variant(Animal)

variant(variant(variant({}))) simply evaluates to {}.

variant(augmented(_ => ({nameLength: _.name.length}), Animal) is a cute little one-liner that creates a new variant, based on Animal (so it will have a cat, dog, and snake), that will have a new property called "nameLength" that corresponds to the name of the animal. If I create cerberus as BetterAnimal.dog({name: 'Cerberus'}), the resulting object will have a nameLength: 8 property.

The most common way I expect this to come up is also the simplest. You can now override the friendly name and the underlying type by passing the variation function. For example,

const Animalish = variant({
    dog: variation('DOG', fields<{name: string}>()),
    cat: fields<{name: string, furnitureDamaged?: number}>(),
    snake: (name: string, pattern = 'striped') => ({name, pattern}),
}),

creates a version of Animal much like the original except that the "dog" underlying type is now "DOG".

[m-rutter]

The error reporting on the complete is a very welcome change.

[m-rutter]

I'm wondering if there should be some consolidation between matcher and match. Maybe the matcher API should be the successor of match should be deprecated or removed in v3?

I know the builder pattern can be a little offputting, but I think its the superior API overall.

[m-rutter]

Also with a builder pattern you can remove the "default" variant and rely on an .otherwise(() => someDefaultValue) to handle the wildcard case.

[paarthenon]

Hello Michael! It's good to see you.

I'm wondering if there should be some consolidation between matcher and match. Maybe the matcher API should be the successor of match should be deprecated or removed in v3?

Funny you should say that. I've been spending time trying to consolidate the APIs, but at the moment my suspicion is that it won't work out so cleanly. First I tried to add a similar sort of VariantError approach to the match() function, but ran into issues. I attempted it as another overload, but that didn't yield good results—the error appeared as you might expect, but it was nested inside of a larger No overload matches this call error that made it difficult to scan the dump and find the relevant issue. I looked at retooling match to be a more complex single interface with no overloads, but I couldn't quite manage that without abandoning some existing features and making documentation worse.

I actually got it working by returning a VariantError but I am not sure if that's good enough. I worry that it may make debugging more difficult as match is so often the item used in a return statement or inside jsx. Functions that have an implicit return type would raise an error some distance from the actual problem, though I suppose an informative error message may assuage that concern.

I know the builder pattern can be a little offputting, but I think its the superior API overall.

Hehe, yeah, I think you might have been there when Retsam complained about my little sample on discord. I guess to be fair, it is slightly less clean when used inline:

{matcher(thing).when({
    caseOne: _ => {},
}.complete())

{match(thing, {
    caseOne: _ => {},
})}

I know the builder pattern can be a little offputting, but I think its the superior API overall.

I like the builder pattern too! It was definitely the most sensible way to support multi-match which gives it a leg up on the competition (and the regular match). Lack of brevity aside, I think the downside of the builder is that when using an object in the .when() call, compiler services cannot offer autocomplete for keys (at least, not past the first type). While using match() on the other hand, I have the experience of handling a variant by matching against it and typing ctrl+enter to iteratively resolve each case. The default keyword became rather intrusive when typing terms that started with a letter after 'd', but should not longer be an issue in 3.0.

However, the .when() calls that correspond to a single term .when('type', ({payload}) => {}) or array .when(['type1' 'type2'], ({payload}) => {}) don't have this autocomplete issue. So especially if you don't use the object syntax, the matcher is probably just better :).

on 'default'

Also with a builder pattern you can remove the "default" variant and rely on an .otherwise(() => someDefaultValue) to handle the wildcard case.

That's true! Has default been causing you difficulties? I thought it would be relatively safe since it's a keyword and wouldn't likely collide. Now that it's considered optional until used, it should do a much better job of staying out of the way. I was actually considering adding it to the matcher to enable the same kind of ergonomics, but I may not if you have negative feedback on that. With 3.0,

I finagled with the match types and now the assumed case is that match() will be exhaustive. There is an optional property called default, but actually attempting to use said property moves to the second overload, flipping expectations and making default required and every other property optional. This results in a better UX because as an optional property default is at the bottom of the list when entering names for the exhaustive match.

---

I hesitate to post this as a suggested improvement because it's not very different from the matcher, but I'm playing around with a prematch function that will create a handler on a given type ready to take in some input. This may allow error reporting similar to .complete() because in much the same way, the handler is built before the actual call is evaluated. Instead of the .complete() function erroring, it will be when the handler is passed a specific instance to evaluate. That should place the error a bit closer to the problem. This only widens the pool of options, though, so I'll be evaluating how useful it ends up being.

I hope some of that was interesting. Thanks for your comments! I may be overlooking some options, I'd welcome any suggestions.

[mikecann]

Hey I have been using your experimental code shared in #12 for some time now and it has been working great.

I have been thinking tho that it might be great if we could get a "point free" / curryed version of the match function so that we can simplify promise callbacks.

e.g:

const { match } = matchImpl(`kind`);

export const matchKind = match;

const fetchUser = async (id: string): Promise<Response> => {
 // ...
}

fetchUser("abc123").then(match({
  "success": ({ user })  => {},
  "error" ({error}) => {}
}))

rather than

fetchUser("abc123").then(resp => match(resp, {
 "success": ({ user })  => {},
 "error" ({error}) => {}
})

Thoughts?

NOTE: Edited the example code because it was incorrect, see one of my posts below.