Potential Types Updates

[icylace]

Hyperapp's TypeScript definitions are more or less solid at this point. However, a few topics remain that are a little more about philosophical positions rather than technical advancement.

Here they are in the priority I think they should be in.

1. Loosen the return type for effecters?
2. Is it worth adding a TypedText for text() as there is a TypedH for h?
3. Rename app()'s dispatch: property? (not just a types question)
4. Potentially inline more types the user isn't expected to use directly. Specifically: DispatchInitializer, Key, Subscriptions, Tag, Unsubscribe, and VDOMNodeType.
5. Is View a worthwhile type definition?
6. Must/should Unsubscribe be part of Subscriptions?

Here is some other stuff that is also important but probably doesn't need as much debate.

• Make more code examples.
• How many of the anys currently being used can be replaced by more type-safe unknowns while preserving DX?
• Complete the documentation for Hyperapp's TypeScript support.

Update (4/20/2021, 8:05 PM EST):

7. What types should be made private?

[icylace]

Here are my thoughts for the numbered ones:

1. I prefer the return type to remain void | Promise<void>. This lets effecters be async functions, which I find convenient, while emphasizing that effecters do indeed cause side-effects in general because void-returning functions are almost always like that. However, since Hyperapp takes a conceptually hands-off approach to effecters I can accept unknown or in the worst case any.

2. Maybe TypedText is worth it but not sure. I'm wondering if there's a situation where setting the state type parameter of h() or using a TypedH version of h() wouldn't be enough for TypeScript's inference to determine the state type for text(). Even if there isn't there's the DX to consider.

3. To leave it named as dispatch: would invite confusion for newcomers. I understand that going back to middleware: is not ideal. The name I'm currently thinking of is initDispatch:. Boring, yes, but the name expresses this function's role of initiating the dispatch function.

4. If the goal is to keep the initial number of types as small as possible based upon estimated chance of usage, then yes inline them all with the exception of Unsubscribe. That one would get used in the return type of users' subscriber functions. Even though Unsubscribe is easy for the user to make, it feels more like code-level documentation rather than a convenience type. Inlining it to () => void or () => undefined wouldn't help code comprehension.

5. Maybe not. Keeping it as-is (type View<S> = (state: S) => VDOM<S>) would preclude usage of returning multiple VNodes. On the other hand, using type View<S> = (state: S) => VDOM<S> | VDOM<S>[] would complicate nested views. Introducing additional view-related types instead would also complicate things. But const foo: View<State> = (state) => ... is not much smaller than the equivalent const foo = (state: State): VDOM<State> => ....

   In defense of View, it's probably at its best when used in the parameter list of view wrapping functions that act as decorators, or more involved higher-order components. Also, (state: S) => VDOM<S> | VDOM<S>[] and (state: S) => VDOM<S>[] can still be made regardless of View. They would just only be technically "view-like".

6. If it turns out that Unsubscribe can technically be left out of Subscriptions I would be okay leaving it out since it is an implementation detail. Also, I can't think of a scenario where directly putting an unsubscriber function in the subscriptions array makes sense from the user's perspective.

[zaceno]

Thanks for the explanation, I understand now. I agree that it is not always easy to know when you need to add the state specifier. I can see how this would be useful if you're making views with plain h/text. And it's complex enough it's worth offering rather than expecting people to write themselves.

So I'm ok leaving it in for the time being. But really I'd rather try to work out exactly how and when the inference fails and find some kind of general solution for it. Because the same problem occurs with my typed version of @hyperapp/html and I am also starting to look in to how to use the types with hyperlit & JSX (it's not looking good 😢 ...). But that's a whole other topic.

About TypedText I think if you are already using TypedH, I'm pretty sure you will never also need TypedText. So I think we're good.

[icylace]

Cool, I'm good with not having a TypedText.

I don't know exactly how TypeScript's inference engine works but I do know that having a sound type system isn't a priority for the language.

For better or worse we're not talking about something on the level of Haskell here 😅

[icylace]

Re: number 4, the benefit of having predefined canonical names is for communication with other people. The better the choice of what gets named and what the name is, the better the things like the following are:

• Discussing details with fellow team members during code reviews.
• Explaining how to use Hyperapp + TypeScript in blog posts.
• Posting Hyperapp-related questions on StackOverflow.
• etc.

[icylace]

I think it becomes something to consider when the type in question would get used by users, as is the case for Unsubscribe.

[icylace]

Re: number 5, I agree with inlining View. Letting go of it seems to let us sidestep a lot of awkwardness.

Also, that ViewComponent type looks pretty useful. I'll be borrowing it 😄

[zaceno]

I'm back to thinking about TypedH.

I was updating my types usage examples gist to show how to deal with inference troubles in view components. I first use the simple example where explitly declaring the return type as VDOM<S> solves the problem. Then I was going to use TypedH on a different example, but I couldn't come up with one. 🤔

I mean, TypedH could also have solved the problem, but in a less easy way. Do we have some example where just declaring the return type isn't enough?

For easy reference, here is the example I used:

import {h, text, Action, VDOM} from "hyperapp"

type MyComponentProps<S> = {
  foo: Action<S, any>, 
  bar: string
}

// In this version, typescript tries to infer the
// return type of the view component, but cannot,
// because only the first child has any actions 
// from which the state type can be inferred
// in the second child, the state type is inferred
// to be unknown.
const myComponent = <S>(props: MyComponentProps<S>) =>
  h('div', {}, [
    h('button', {onclick: props.foo}, text('click')),
    h('p', {}, text(props.bar)),
  ])

// The easiest way to solve this is to explicitly
// declare the return type:
const myComponent2 = <S>(props: MyComponentProps<S>):VDOM<S> => 
  h('div', {}, [
    h('button', {onclick: props.foo}, text('click')),
    h('p', {}, text(props.bar)),
  ])

playground

EDIT: The issue in #1048 doesn't seem to be solved quite so easily. Investigating further

[icylace]

I think it's great you found another solution but it's not necessarily easier. What you mention in #1048 (comment) as an alternative solution is to use a combination of explicitly stating the VDOM returns and using map in a certain way. Always stating the VDOM returns, while arguably good practice for different reasons, comes at the cost of verbosity and scales poorly compared to the TypedH solution. And that map usage is especially subtle and would otherwise be considered verbose as well.

I didn't know about the map thing, so thank you for mentioning it but that just reinforces my point about having to worry about such things. Perhaps reduce, filter, etc. are affected similarly? Maybe other types of methods need to be treated in a special way too?

In contrast,

import { TypedH, h as ha } from "hyperapp"

type State = { youGetTheIdea: boolean }

const h: TypedH<State> = ha

and now I'm done worrying about it without making further compromises.

[zaceno]

Sure I see. It's a neat way to "brute-force" inference issues typescript might get caught up on but shouldn't. I was mainly interested in an example where TypedH is the only "right way" to solve the problem. Now I understand TypedH is not about being the "right way" but a fallback when the right way is elusive or not worth the time. I could probably use an example with map to demonstrate the kind of pitfalls typescript throws at you, and that TypedH lets you sidestep.

I'm personally more interested in using other view-methods like for instance html-functions. As far as I can tell TypedH can't help me there. (I'd need to define a TypedA, TypedB, TypedEm, TypedSpan, TypedP.... ) So I'm still pretty interested in understanding more how and when the inference can fail, and how to solve it. It can't be completely random after all.

[icylace]

That's a good point about view methods. My solution to that, which I've just implemented in my ntml package, is to include an alternative version of my element factory function that requires a state type.

So, compare n versus typedN. Also check out my rudimentary test file which tries out both.

I'm sure you could do something similar for your own library.

[zaceno]

that's an interesting idea to have a typed factory. It means you have to create all the tag-functions using the typedN, but I'm sure it wouldn't be too hard to make something more expedient like:

const {div, span, p, a} = typedNMulti('div', 'span', 'p', 'a')

[zaceno]

Still personally more interested in working out the when and why inference fails. But I get that this technique is very useful for those who just want to move on with their lives and not worry about it 😅

[icylace]

I recently discovered that types can be private. I feel silly for not realizing this sooner !

Like I said in Discord, we can just move the types we want private outside of the declare module "hyperapp" block and also don't explicitly export them.

Now we don't need to feel pressured into inlining just for the sake of minimizing public exposure for the types. So, the question becomes, what to make private? Perhaps what would otherwise get inlined should instead be made private.

Also, should we reintroduce types that were inlined but make them private? Maybe their inclusion makes the the types file better structured.

At the moment I think VDOMNodeType and EventsMap are good as private types. I'll consider the rest as well.

[zaceno]

Oh and are we really sure Unsubscribe needs to be public? I haven't played much with typing subs yet, but seems that might be one to make private.

[icylace]

Well-formed subs return an unsubscribe function. Seems like a clear reason to have Unsubscribe public.

[zaceno]

I suppose. It isn't technically necessary from what I've found (I may have missed some situations) but if a person wanted to explicitly declare their subscriber's return value, then I can see how using Unsubscribe reads better than () => any

[icylace]

Yes, exactly. Every other inlining I've done had some sort of descriptive part to it. For example, inlining ActionWithPayload retained descriptiveness because of named tuples. I've also been experimenting with inlining View and that seems to be okay because its function signature is a decent hint at what it does. And in most cases it's associated with a view: property to further describe it.

[icylace]

So, in my further experimentations private types are working consistently.

The reason why I thought they were unreliable was because I was using an ugly hack at one point. I was using import type { ... } from "hyperapp" within the .d.ts file itself to ensure internal access to some types and that worked but made all the types public. Since then I arranged the types so that that imperfect hack was no longer necessary. I removed the hack and the private types became once again non-importable in user code.