semver-ts / semver-ts

Defining Semantic Versioning for TypeScript types

Semantic Versioning for TypeScript Types Specification

This repository hosts www.semver-ts.org, which publishes a definition of Semantic Versioning for TypeScript types.

Working on the spec

The spec is currently a stable beta release after considerable iteration which involved input from both members of the TypeScript community at large and the Ember community specifically. We have intentionally not yet finalized it in view of gaining further feedback. Feel free to open a discussion, to note an error or to suggest a change!

To build the site locally, you need to install mdBook, mdbook-linkcheck, and mdbook-open-on-gh, mdbook-toc. Then run mdbook build or mdbook serve in the root of the repository.

History

This specification was originally authored by Chris Krycho at LinkedIn, in collaboration with Dan Freeman, Mike North, and James C. Davis, as part of the the Ember.js ecosystem's official TypeScript support effort. For development history spec prior to publication in this repository, see:

• an early draft and discussion in the ember-cli-typescript repository
• Ember RFC #730

semver-ts's Issues

Declaring supported TypeScript versions

It might be nice if it were possible for a package to declare the minimum TypeScript version that its consumers must use.

The closest I've come to that is to use typesVersions to conditionally serve type declarations that deliberately don't compile under TypeScript versions other than those I support. For example:

minimum-typescript-version.ts

/**
 * @module
 * This module is intended to enforce the minimum TypeScript version we support, by not compiling under earlier versions.
 */

/**
 * Const type parameters were introduced in TypeScript 5.0.
 *
 * Under TypeScript 4.9:
 *
 * > error TS1139: Type parameter declaration expected.
 */
export default function<const _>(_: "TypeScript 5.0 or later is required.") {}

package.json

{
  "name": "the-package",
  "typesVersions": {
    "<5.0": {
      "*": [
        "./dist/minimum-typescript-version.d.ts"
      ]
    },
    "*": {
      …
    }
  },
}

A TypeScript 4.9 consumer that attempts to import any export from the package in question, whether that export contains TypeScript 5.0-only syntax or not, will get this error:

Complete error message

node_modules/the-package/dist/minimum-typescript-version.d.ts:12:26 - error TS1139: Type parameter declaration expected.

12 export default function <const _>(_: "TypeScript 5.0 or later is required."): void;
                            ~~~~~

node_modules/the-package/dist/minimum-typescript-version.d.ts:12:33 - error TS1005: ',' expected.

12 export default function <const _>(_: "TypeScript 5.0 or later is required."): void;
                                   ~

node_modules/the-package/dist/minimum-typescript-version.d.ts:12:36 - error TS1005: ')' expected.

12 export default function <const _>(_: "TypeScript 5.0 or later is required."): void;
                                      ~

node_modules/the-package/dist/minimum-typescript-version.d.ts:12:76 - error TS1005: ';' expected.

12 export default function <const _>(_: "TypeScript 5.0 or later is required."): void;
                                                                              ~

node_modules/the-package/dist/minimum-typescript-version.d.ts:12:77 - error TS1128: Declaration or statement expected.

12 export default function <const _>(_: "TypeScript 5.0 or later is required."): void;
                                                                               ~

node_modules/the-package/dist/minimum-typescript-version.d.ts:12:83 - error TS1109: Expression expected.

12 export default function <const _>(_: "TypeScript 5.0 or later is required."): void;
                                                                                     ~

That means one can make it obvious to consumers if they have a non-supported TypeScript version, instead of flooding them with the wall of text that TypeScript tends to print in the presence of syntax errors.

This scenario is particularly interesting:

1. the-package drops support for TypeScript <5.0 in version 42.0.0, but doesn't yet use const type assertions, so the emitted code still happens to work under older TypeScript versions.
2. A consumer using TypeScript 4.9 upgrades the-package to version 42.0.0 and notices no breakage, so they think everything is fine.
3. the-package starts using const type assertions in version 42.1.0. Now the emitted code suddenly does need TypeScript 5.0 or later to work.
4. The consumer upgrades the-package to version 42.1.0 (maybe indirectly via a transitive dependency) and suddenly gets curious syntax errors.

To prevent that, it might be nice if version 42.0.0 really did break consumers' builds, in a clear and descriptive way.

On the other hand, the above approach is quite hacky, and it may mean that some consumers won't be able to use the package, even though it — or at least some of its exports — would have worked perfectly fine.

But I think it's worth having a discussion around this at least: is it possible to declare and/or enforce a minimum supported TypeScript version, and should packages do that?

I might just be overthinking this of course. Hopefully someone will enlighten me!

Add permanent anchor links in the semver-ts.org site

I love the effort, and am actually looking to link to this whenever I encounter API breaking changes. It would really help to have a site that is a bit easier to pin-point exactly what the breaking changes are. Perhaps we can have this scheme:

1. publish this doc to semver-ts with versions permanently - interestingly, you'll maybe need a semver principle for the doc itself!
2. add anchor links

I'm happy to contribute to the 2nd point above, but would love to solicit feedback on this description of an issue first!