Will TypL cover 100% of JS semantics?

[kee-oth]

Other projects like TypeScript struggle with providing ergonomic ways of typing code written in a functional style. And at least at some point, TypeScript wasn't expressive enough to type certain functional programming techniques at all. I'm not sure if this is still true but I suspect it is. TypL works a bit different though because it works on value-types instead of variables so I imagine it's more flexible.

1. Are there things in JS that you can do but are not possible for TypL to type?
2. How does TypL fair with regards to typing functional programming techniques?
3. Does TypL make tradeoffs that favor a particular style of coding?

I know TypL isn't done yet so I'm fine with the answers to refer to assumptions and goals for TypL.

Thanks!

[getify]

It is my goal for TypL to be the closest fit of how to type annotate JS in however it's written, as opposed to being a type system that openly admits to trying to change how people write their JS.

I think TS is actually a different language, not just a style of JS. That's fine, of course, and I'm glad it exists for those who like it. But I don't think it embraces JS, I think it actually resents JS (at least its types and coercions).

TypL stands for the opposite. It embraces JS and its built-in types and its coercions. TypL wants to augment how devs already use JS, and help them become more "type aware". It wants to validate type issues at compile time where possible, but critically, it believes that some type verifications cannot reasonably be verified until run-time (at least not without signification contortions and alterations to how you write code).

There are going to be patterns, especially in FP, that I think will be challenging to fully type. But as you said, yes, I believe the strategy of designing a system that types values/expressions first, rather than typing "containers" (variables, parameters, properties), should help a lot.

It is emphatically the goal of TypL that any valid JS value/expression be type-checkable, regardless of coding style. I hope we don't run into challenges where that's difficult (or seemingly impractical), but I will never de-prioritize such efforts from TypL's roadmap, because that is why it exists: to be the type-linter that embraces JS how it is rather than changing it into some other language.

[jzombie]

+1 if it could validate off of JSDoc types, then you'd encourage people to document their code as well.

[kee-oth]

@getify Thanks for the response!

I appreciate your stances on bringing typing to JS. Leaving JS as JS is important and will cause a lot less friction with tooling and the JS ecosystem in general, which is super important for developer adoption I think.

@jzombie

+1 if it could validate off of JSDoc types, then you'd encourage people to document their code as well.

I'm not sure if that idea is really compatible with TypL. @getify can correct me if I'm wrong but TypL would just have to support a completely separate type system which I don't think we would want to pursue. I think a complementary documentation system is worth looking into though. Kind of like how TSDoc handles it, it's like JSDoc but without the types. So it's just purely for documentation. A more ergonomic and less clunky documentation system than JSDoc would be amazing though. I'd really enjoy if that was a part of TypL but I assume that's a lot of work on top of TypL's core use case.

[getify]

It is my hope/plan for TypL to be able to ingest TS definitions (perhaps in .d.ts files) and "convert" them to a JSON serialized representation of TypL typing rules, at least the subset of them that make sense for TypL. Also, TypL may be able to generate/insert its own syntax (from those JSON definitions) into a plain JS file.

I don't know if I'd want to write the parser for TS syntax or TS-in-JSDoc syntax, as that might be out of scope for TypL. I certainly don't want it to be a "live" thing where TypL is also always TS... I'd want it to be a one-time conversion/import sort of thing to transition from TS to TypL.

I feel like the TS ecosystem has ways to "export" types, and it certainly has the transpiler to remove itself from code, so I would lean toward using those to perpare something that TypL could import.

[kee-oth]

@getify Thanks!

With regards to documentation, could you see TypL supporting it's own documentation style? It would be amazing to include these details for runtime debugging or integrations with IDEs. Something like this?

/*
 * Description
 * This function checks if a number is an even number.
 * 
 * Parameters
 * v - the value to check
 * 
 * Returns
 * isValueEven - whether the value is even or not
*/
function isEven(v = number) {
   return bool`${ v % 2 == 0 }`;
}

Or maybe more programmatically (if needed):

function isEven(v = number) {
   return bool`${ v % 2 == 0 }`;
}
documentation (isEven, {
  description: 'This function checks if a number is an even number.',
  parameters: {
    v: 'the value to check'
  },
  returns: {
    'isValueEven': 'whether the value is even or not'
  }
})

With documentation being supplied by TypL. A function-based approach would be able to harness all of JS's features (importing, exporting, modularizing config object parts, etc). And returns could be simplified if we don't want a named return value (could be optional):

returns: 'whether the value is even or not'

I assume this would be a fairly big lift so I understand if this idea is not desirable because of it. But I do think JS is hurting for a modern, non-JSDoc documentation system in general. Might help the case for relevancy for TypL.

If this is something of genuine interest to you, I can open a new issue specifically around this question.

[getify]

So we're talking about documentation more in terms of generating external documentation (like markdown pages or whatever) from the code than in terms of readability in the code itself?

I think having an extensible documentation system (one where automated documentation from code can be augmented by additional developer-supplied information) is useful. I'm not sure how much of that would be TypL specific, though. I mean, I could almost see that as its own project where it could ingest types (either TS or TypL or Flow or whatever) and then read additional documentation hints from the code, and produce nice customized documentation. That would be a really neat project.

I am not saying TypL couldn't tackle that, but I'm saying that I don't know if we should limit it to being only TypL. Perhaps that could be an interesting sub-project here, and then eventually spins out to its own thing.

[jzombie]

Regardless of the outcome, the two major pain points I see when using a lot of projects, regardless if they are TypeScript or JavaScript are:

• Lack of documentation (like, how does this thing even work?)
• Lack of testing (does it actually work?)

[kee-oth]

@getify I think generating external documentation should be possible but, at this moment, I'm mainly thinking of ways to support and enhance TypL with it so TypL has even more goodies to attract developers.

With that extra meta information about a function, could TypL augment its runtime error messaging to be more specific?

Given:

function getCommaSeparatedNumberStringPair (aBool = bool, aNumber = number, aString = string) {
  return aBool ? string`${aNumber}, ${aString}` : string`No bueno.` 
}
documentation (getCommaSeparatedNumberStringPair, {
  description: 'This function joins a number and string together to create a new string.',
  parameters: {
    aBool: 'some description of aBool',
    aNumber: 'some description of aNumber',
    aString: 'some description of aString',
  },
  returns: 'aNumber comma separated from aString if aBool is true, otherwise a default message.',
})

Usage somewhere:

getCommaSeparatedNumberStringPair(anArbitraryBool, anArbitraryString)

TypL Error: 
  Invalid types for getCommaSeparatedNumberStringPair.
  Received Arguments:
     1. VALID: a boolean value
     2. INVALID: a string value
     3. INVALID: no value given
  Function Parameters:
     1. aBool: boolean - some description of aBool
     2. aNumber: number - some description of aNumber
     3. aString: string - some description of aString
  Suggestion:
    Fix Received Argument types for #2 and #3 to match Function Parameters.

Function Parameters above is where we see the mixture of TypL's type information and the user-generated documentation. And documentation could be configurable to spit out more or less information. A developer could configure the output to include description and returns, unlike what you see above.

And of course, the other big use case is IDE auto-completion, tooltips, etc.

[getify]

This is an interesting and intriguing idea. I think we definitely need another issue thread to discuss/track it.

My inclination would be to try to invent a way for that documentation (stuff used to control error messages) inlined with the type annotations in some way. Maybe that wouldn't work, dunno. But the overall idea I like, just need to consider possible approaches carefully.

[kee-oth]

@getify Awesome! I'll create a ticket for this idea sometime this evening 👍

@jzombie Thanks for your input too! 💪

[jzombie]

@kee-oth Yep, I've been tracking this repo off and on for a couple of years now and interested to see where it goes.

@getify You do amazing work for the community. Thanks for everything you share.