DEV Community

A JSDoc in TypeScript's Clothing

Adam Nathaniel Davis on June 30, 2020

My recent journey into the Land of the TypeScripts has led me to some odd realizations about what it does - and what it doesn't do. Specifically, ...

Read full post

John Peters • Jun 30 '20 • Edited

Mr. Davis,

Nice comparisons here. I too realized after using Typescript for a while that it is nothing more than a metadata generator allowing IDEs to do nice things with the metadata. All the metadata being stripped off at compile time shows us plain ole JavaScript.

But even JavaScript on its own can't detect a null parm being sent in and won't without AOP. The traditional place to validate for last 50 years is in entry to the function. Shoot, Marshall Dillon did it.

But even AOP once thought impossible may have new life with the new decorator standards appearing. A recent article here showed how that works. Which is cool but will present debugging challenges to those unaware.

JavaScript is OK but nothing super over the top. I've never told my own Mother about it. Its major attribute is it's ubiquitous adoption. As it matures; we are seeing Typescript like adaptions, like the class, arrow functions, constructors and now decorators.

The JavaScript of today is nothing like it was and that's a good sign of a thriving language.

Maybe soon it will overtake Typescript's innovation like Rust overtook C++. The only problem is MSFT knows languages extremely well. I don't see them letting up on Typescript innovation. To do so, would leave them nowhere close to JavaScript. They have no language entry in the JavaScript world without Typescript.

Hey, is that your shed on fire over there in your background?

Mike Talbot ⭐ • Jun 30 '20

At the beginning TS was a way of being able to code with fancy new features for sure. Then JS got better as Adam has pointed out in other articles. I guess I've been burned by following the Microsoft "hype" - we built a lot of stuff in XAML and SilverLight and were left hanging. I find myself distrusting anything that is powered by an advertising machine and that is significantly perpetuated by it.

AOP would be fantastic though. I'd dearly love to be using metadata in frameworks.

Adam Nathaniel Davis • Jun 30 '20 • Edited

Great points!

I've been quite intrigued by decorators. The only thing holding them back, at the moment, is the fact that they're still "experimental". And as you point out, even when they're adopted, they also present some new challenges. Nevertheless, I think it's my C# experience that makes me so fond of them. IMHO, they're both incredibly useful and they create rather "clean" code (as opposed to, say, doing it manually by literally wrapping a function/method in another function/method).

I'm also encouraged by the rapid pace of JS's development. In fact, I wrote a whole article about that earlier (dev.to/bytebodger/why-javascript-i...).

I imagine that, as time goes on, TS will continue to evolve. But I also think that some of TS's features will also end up being absorbed into JS. I'm not implying that they'll eventually become the same thing. But jQuery is, IMHO, a useful example.

Nowadays, there's much about the jQuery model of querying DOM elements that you can do without ever loading up jQuery. I can imagine a similar path for TS features in core JS.

Thanks again for the feedback. I'm gonna go check on that shed now...

John Peters • Jun 30 '20

Yes, just think of JavaScript adopting type annotations. That could kill Typescript. Who knows maybe Typescript will introduce LINQ.

Mike Talbot ⭐ • Jun 30 '20

When I first came to JS from C# I used (what is now) github.com/mihaifm/linq . In the end I felt that map/filter/reduce was enough and slowly it dropped out of my daily practices.

John Peters • Jun 30 '20

me too, I just loved linq so much, it was the best thing since chewing gum!

John Peters • Jun 30 '20

I love your articles and great sense of humor! Have a good day my friend.

Mike Talbot ⭐ • Jun 30 '20

See in Webstorm/IntelliJ JSDoc is just autofolded away for me. It's just a single line above the function. Plus I'd only ever bother on library stuff that is going to be called by someone else at some point, internal functions etc just don't need it.

Adam Nathaniel Davis • Jun 30 '20

Ahhh, that's a good point. I don't have my WebStorm settings configured to fold those comment blocks. But that would really relieve a lotta scrolling in those places where JSDoc is being used.

But yeah, on internal stuff, it's really not necessary at all.

The Jared Wilcurt • Jul 14 '20 • Edited

A while back I had an idea (mostly inspired by Vue's prop type approach) of a runtime version of type checking. Here is a quick sketch of it:

const typeError = function (err) {
  throw err;
};

const hString = new Interface({
  type: String,
  required: false,
  default: 'Hello',
  validation: function (value) {
    return value.startsWith('H');
  }
});

function greetTarget (greeting, target) {
  Interface.validate(greeting, hString, typeError);
  try {
    Interface.validate(target, {
      type: String,
      required: false,
      default: 'World'
    });
  } catch (err) {
    console.log('The value supplied for target does not match interface. Falling back to default: ', err.default);
  }

  return greeting + ' ' + target;
}

greetTarget('Hey', 'buddy');

Pros:

Allows for runtime checking
Allows for defaulting values
Allows for custom validation
Allows for multiple types via type: [Number, String] or type: [Array, Set]
Easily extensible. For example you could add a strip: true to the object to tell WebPack or whatever to strip out all type checks of that Interface. Or to strip out all by default unless they have a keep: true. Meaning you can define compile-time-only and run-time specific uses to reduce bloat of your builds.
Can take a defined interface or an object. So object definitions could be reused and ... rest/destructured
Easily reusable. You could have an entire file of validators like export const H_STRING =. Interface validation libraries could be pulled in and used and easily tree-shaken
Can be applied to arguments in a function, or just any one-off variable
Because this is just plain JS it is compatible with everything (JSDoc, TS, React, Vue, Node, IE, whatever).
Linting could be used to enforce usage (like with JSDocs linting), or to require either required or default be set (like in Vue's proptypes linting)
The functions used in the validation could be unit tested easily with tools like Jest.
Could be adopted by TC39 for ES20XX without ANY NEW SYNTAX CHANGED, and easily polyfilled to any previous browser or Node version.
Even if built in to the browser, it would be easily modified or tweaked due to JS's prototypal nature, to add unique features for specific use cases.
Codemods could be used to convert existing TS or JSDoc projects over to this approach

My sketch is rough, but you get the idea. If you want to take a stab at creating a proof of concept let me know and I'll be a beta tester. The function names used can be completely different too. It's not a blueprint, just an idea.