Support TypeScript 3.7 Assertions

[cartolari]

TypeScript 3.7 introduces the assert keyword https://github.com/microsoft/TypeScript/pull/32695, it allows code to be written this way:

import { assertType } from 'typescript-is';

try {
    assertType<string>(object); // No need to reassign
    object.toUpperCasse();
} catch (error) {
    // ...
}

instead of this:

import { assertType } from 'typescript-is';

try {
    const asString = assertType<string>(object);
    asString.toUpperCasse();
} catch (error) {
    // ...
}

It'd be good if the library provided support for it, maybe using a new function if backwards compatibility is required.

[woutervh-]

Hi @cartolari

This is a great idea. I will add this. The only worry I have is backwards compatibility in the type definitions (index.d.ts). If someone is using an older version of TypeScript, then I don't know what the compiler will do when it finds the assert syntax. I might have to keep two versions in parallel while people migrate.

Any opinions from users of typescript-is would be appreciated about how they plan to use it and with what versions of TypeScript.

[joshAg]

We're just starting to use the library to validate what we pull out of the database or redis matches what we expect to get. Right now we've been dropping it into our lowest level wrappers like

async function bar(): SomeComplicatedPODS {
  const result = await grabFromdatabase();
  return assertType<ReturnType<typeof bar>>(result);
}

It wouldn't be too hard to switch over to to the newer style. We'd probably prefer it because we try to stay no more than 1 version off of the newest minor typescript release.

[woutervh-]

Hi @joshAg

Thanks for sharing your situation. It helps me gauge the need for assert signatures.

One thing that still concerns me is that people who are sticking with older versions of TS will probably run into compiler errors with the new syntax.

Maybe one solution is to keep two versions of typescript-is in parallel, one with assert syntax and one without? At some point in the future however I'd like to converge to one version, once there has been enough time to migrate for everyone.

I'm pretty new to managing open source projects so I'd like some opinions on how to move forward :)

[joshAg]

I don't have a lot of experience for open source as well, but at least for commercial/internal projects, for a breaking change, we've done it in two steps of the major version.

The first step will deprecate the older usage but keep functionality at least at par with the previous version. It's usually not worth the hassle to add functionality/features to match the new usage, nor is it worth it to remove functionality/features that are added as a result of improving something shared between new and old. It is worth it to add functionality that makes it easier to switch from the old style tot he new style. Both old and new should get security updates, too.The second will actually remove the old usage from the code base.

You can move as quickly or as slowly as you want between those two steps (even releasing both versions the same day), but the important bit is having at least one version where both are supported so that downstream projects can use that version to migrate the code from the old to the new version, and verify that everything still works correctly. If there are missing features in the new functionality that prevent a full migration from old to new style, you'll want to add them to the intermediate major version if at all possible and not just add them to the latest version, because the missing feature prevents seamless upgrades (which means they'll be opening issue for a code workaround until they get to the actual feature they need by upgrading). The easier it is for users to transition from old to new, the less time you'll spend convincing people to migrate or helping them figure out how to migrate.

It looks like there already exist ways to specify which version of typescript are supported too: https://github.com/microsoft/TypeScript/issues/32166

[woutervh-]

Thanks for linking this issue microsoft/TypeScript#32166 Looks like a promising solution :) I will take a look