Request for Better Type Definitions and Interfaces

[roiiiu]

I have found gsap to be the most convenient animation library I have used so far. However, its TypeScript support leaves room for improvement. Due to the lack of precise type definitions, I often find myself having to refer to the official documentation more frequently than I would like.
For instance, I wonder if it would be beneficial to add literal property union types for the ease attribute, instead of relying on strings. This would not only make the code more self-explanatory and easier to maintain, but also boost productivity and confidence in designing complex animation sequences.

[jackdoyle]

Thanks for the suggestion, @roiiiu

The ease must accommodate ANY string because you can create a CustomEase, CustomBounce, CustomWiggle, or even call gsap.registerEase() and assign an arbitrary string as the name. So do you think it'd still be helpful to do something like this?

type EaseName = "none"
            | "power1" | "power1.in" | "power1.out" | "power1.inOut"
            | "power2" | "power2.in" | "power2.out" | "power2.inOut"
            | "power3" | "power3.in" | "power3.out" | "power3.inOut"
            | "power4" | "power4.in" | "power4.out" | "power4.inOut"
            | "back" | "back.in" | "back.out" | "back.inOut"
            | "bounce" | "bounce.in" | "bounce.out" | "bounce.inOut"
            | "circ" | "circ.in" | "circ.out" | "circ.inOut"
            | "elastic" | "elastic.in" | "elastic.out" | "elastic.inOut"
            | "expo" | "expo.in" | "expo.out" | "expo.inOut"
            | "sine" | "sine.in" | "sine.out" | "sine.inOut"
            | "rough({template: none, strength: 1, points: 20, taper: none, randomize: true, clamp: false})" | "slow(0.7, 0.7, false)" | "steps(12)" | "expoScale(1, 2)";

And then:

ease?: EaseName | EaseFunction | string;

?

[roiiiu]

Thanks for the suggestion, @roiiiu

The ease must accommodate ANY string because you can create a CustomEase, CustomBounce, CustomWiggle, or even call gsap.registerEase() and assign an arbitrary string as the name. So do you think it'd still be helpful to do something like this?

type EaseName = "none"
            | "power1" | "power1.in" | "power1.out" | "power1.inOut"
            | "power2" | "power2.in" | "power2.out" | "power2.inOut"
            | "power3" | "power3.in" | "power3.out" | "power3.inOut"
            | "power4" | "power4.in" | "power4.out" | "power4.inOut"
            | "back" | "back.in" | "back.out" | "back.inOut"
            | "bounce" | "bounce.in" | "bounce.out" | "bounce.inOut"
            | "circ" | "circ.in" | "circ.out" | "circ.inOut"
            | "elastic" | "elastic.in" | "elastic.out" | "elastic.inOut"
            | "expo" | "expo.in" | "expo.out" | "expo.inOut"
            | "sine" | "sine.in" | "sine.out" | "sine.inOut"
            | "rough({template: none, strength: 1, points: 20, taper: none, randomize: true, clamp: false})" | "slow(0.7, 0.7, false)" | "steps(12)" | "expoScale(1, 2)";

And then:

ease?: EaseName | EaseFunction | string;

?

I am sorry for my limited knowledge about the library, but I still believe that using string to specify so many property variables is not the best practice. However, the cost of making changes may have some impact on the current users.😌

[jackdoyle]

Oh, we will definitely keep the named strings for eases. In the very old days, we had ease objects for all the eases which technically made strict typing easier but it was clunky because it required more imports/exports (file size tradeoff) and it wasn't conducive to custom eases.

Plus there are over 11 million sites that rely on GSAP and tons of developers are very accustom to using the named strings for easing, so if we suddenly moved away from that, it would be extremely annoying for those devs and would cause breaking changes. I see absolutely no reason to do that, sorry.

However, if there's something we could do in the TypeScript definitions to make your life easier, I'm very open to that. I'm not much of a TypeScript person, so my question to you was more about whether or not that structure I shared above would actually be helpful at all (like for code hinting in your editor). In other words, if the ease accepts an EaseName as well as a string, does that give you the code hinting you want or is there no benefit whatsoever to having that EaseName type since we must allow a type of string anyway?

[charnog]

For the official playground and VSCode, it doesn't make any difference. A-la 'asdf' and 'zxcv' are subtypes of string.

WebStorm understands it, and gives the hint (they have their own tuned implementation of TS language server):

I would say "yes, we need it" if it were consistent across all implementations, especially in VSCode, as many folks use it. I prefer to leave it as a string, at least for now.

By the way, there are a few things to remember; try to read them as one word:
"powerX" and "back" and "bounce", "circ", "elastic", "expo", "sine".

Then you can add . and change the type via "in" or "out" or "inOut".

[jackdoyle]

I would say "yes, we need it" if it were consistent across all implementations, especially in VSCode, as many folks use it. I prefer to leave it as a string, at least for now.

I read that a few times and am still fuzzy. You say that my proposed change DOES help in some editors like WebStorm, right? So "yes we need it"...and then you quickly follow that with "I prefer to leave it as a string" which sounds like "no, we don't need it...stick with a generic string as the type". Can you please clarify what you meant?

If there's benefit for some (and it doesn't hurt anyone), I'm inclined to do it.

By the way, there are a few things to remember; try to read them as one word: "powerX" and "back" and "bounce", "circ", "elastic", "expo", "sine".

Then you can add . and change the type via "in" or "out" or "inOut".

Again, this left me confused. Can you rephrase and make your suggestion very clear please? Sorry if I'm missing something obvious.

[charnog]

Oops, my bad.

The message has the following structure:

1. The first part shows where it works and where it doesn't (without implying whether it should be implemented or not).
2. The second part presents my opinion on whether it should be implemented or not

If there's benefit for some (and it doesn't hurt anyone), I'm inclined to do it.

If so then I suggest to use Template Literal Types

You can also inline Dir to template, if you don't want to create a distinct type for it.

type Ease = "none" | EaseName | `${EaseName}.${"in" | "out" | "inOut"}` | string;

[jackdoyle]

Thanks for the suggestion, @charnog

Do you know of any compatibility issues with using the template literal types? Should this be pretty universally compatible these days?:

  type EaseName = "power1" | "power2" | "power3" | "power4" | "back" | "bounce" | "circ" | "elastic" | "expo" | "sine";

  type EaseDirection = "in" | "out" | "inOut";

  type EaseString = "none" | "rough({template: none, strength: 1, points: 20, taper: none, randomize: true, clamp: false})" | "slow(0.7, 0.7, false)" | "steps(12)" | "expoScale(1, 2)" | EaseName | `${EaseName}.${EaseDirection}` | string;

ease?: EaseString | EaseFunction;

From a quick glance, they were added in TypeScript 4.1 in late 2020. I don't have a good feel for how dangerous it would be to add into our codebase (I don't want to cause problems in legacy projects for example).

[charnog]

I don't have a good feel for how dangerous it would be to add into our codebase (I don't want to cause problems in legacy projects for example).

If so, then yes, you are right, it may cause problems, and it's better to use a 'plain old string union' as mentioned in this message.

In that case, there are no concerns about 'broken types'. Previously, the type was just string. If you update the type to be more specific but still include string in the type definition, then nothing will actually change. Users who used 'myCustomEaseName' will still rely on a string within the updated type. WebStorm will show the suggestions for the new types (I don't know why VSCode doesn't).

By the way, I noticed that you wrote "rough({template: none, strength: 1, points: 20, taper: none, randomize: true, clamp: false})" | "slow(0.7, 0.7, false)" | "steps(12)" | "expoScale(1, 2)". Unfortunately, it won't be interpolated, and users will have to use it exactly as you wrote in the type. You can simply removed it, string part of the updated type will allow users to write whatever they want, but more specific 'power1.in' ... will allow IDEs to suggest the simple ones.

It would be possible with template literals though, like this: slow(${number}, ${number}, ${boolean})

[jackdoyle]

That's very helpful, thanks.

My goal with adding the "rough(...)", "slow(...)", etc. was to just help people who can't quite remember the syntax/parameters. I figured they'd just select it from the code hint suggestions and then go back in and edit whatever parts of the string they need to. Since it's still a string, it wouldn't get flagged as invalid. But am I wrong about that? Would users be forced to use that rough(...) string EXACTLY as it's defined in the type?

[charnog]

That's very helpful, thanks.

You're welcome!

I figured they'd just select it from the code hint suggestions and then go back in and edit whatever parts of the string they need to.

That's an interesting approach; I've never thought about it that way. In my opinion, the type system isn't quite the right place to store the hints. I would suggest implementing official snippets for VSCode, WebStorm (IDEA), or another IDE with a large user base. Click, click, click, click.

Would users be forced to use that rough(...) string EXACTLY as it's defined in the type?

No, they would not. You're right in saying, "Since it's still a string, it wouldn't get flagged as invalid."