Publish unist packages and friends

[remcohaszing]

Problem

Type definitions for various *st packages are published using DefinitelyTyped. Having these types packages without an accompanying source package on DefinitelyTypes has caused various issues for me when working with unist ASTs. Just some examples:

The following are some issues related to resolving packages:

• eslint-plugin-import doesn’t just work. It requires the need to use eslint-import-resolver-typescript.
• Even if eslint-import-resolver-typescript is configured, some rules from eslint-plugin-node don’t just work either.

Also TypeScript itself has issues with this. For example, the following code:

import { Node } from 'unist';

class Foo {
  @Bar
  node: Node;
}

Gets transpiled to:

var __decorate = /* truncated */;
var __metadata = /* truncated */;
var _a;
import { Node } from 'unist';
class Foo {
}
__decorate([
    Bar,
    __metadata("design:type", typeof (_a = typeof Node !== "undefined" && Node) === "function" ? _a : Object)
], Foo.prototype, "node", void 0);

So Node will be imported from unist, even though the unist package doesn’t exist.

This can be worked around by using a type import, but the generated error will be unclear.

These are just the sutiations I recall from the top of my head. There are more situations.

Solution

I propose to publish all syntax tree AST type definition packages using their own name, pulling them from DefinitelyTypes. This will resolve some of the issues.

To resolve more issues, I propose to add an empty index.cjs and index.mjs file to each package. I.e. import { Node } from 'unist' will just result in Node being undefined, not in an import error.

Versioning

Some packages haven’t even been published to npm (https://www.npmjs.com/package/xast). For these packages it the version doesn’t really matter.

Side note: This also means anyone could just publish a package named xast.

Other packages have been published before (https://www.npmjs.com/package/mdast). The new version should have the major version bumped compared to the last release.

[ChristianMurphy]

Speaking to this specific issue

import { Node } from 'unist';

transpiled to try to import a value

https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export resolves this

[remcohaszing]

True, but still I’d prefer Node to be undefined over having an import error.

[wooorm]

It sounds like TS has a suggested way to solve type-only things. Why should we deviate from that?

[wooorm]

I don’t think TS-only unist/mdast/hast/xast/nlcst/esast packages makes sense: they’re a contract on an interface.
But types are accepted in all other unified packages though

[remcohaszing]

This isn’t unique to unist. More types-only packages exist.

• https://www.npmjs.com/package/openapi-types
• https://www.npmjs.com/package/type-fest
• https://www.npmjs.com/package/@fortawesome/fontawesome-common-types
• https://www.npmjs.com/package/@sentry/types

[ChristianMurphy]

this was somewhat explored in https://github.com/syntax-tree/unist-ts
but never came to fruition syntax-tree/unist-ts#4

[ChristianMurphy]

To resolve more issues, I propose to add an empty index.cjs and index.mjs file to each package. I.e. import { Node } from 'unist' will just result in Node being undefined, not in an import error.

I think @wooorm has mdast https://www.npmjs.com/package/mdast and hast https://www.npmjs.com/package/hast published to npm with an index.js file, since the content doesn't seem to matter in this case, would that be enough?
(unist, xast, and dotast are still unpublished and an open question)

[remcohaszing]

1. publishing directly to unist, mdast, and hast

This has my preference. This causes the least amount of issues for working with these types.

1. The drawback here is that I feel unist etc are specs/documentation. That could also work in other type or programming languages. So typescript types are one implementation, but there could be more. So I feel that it’s a bit weird to tie their names to typescript types.

This assumes the types packages would belong in the existing repositories. A package is not the same as a repository. I.e. a package named unist can exist in a repository named https://github.com/syntax-tree/unist-types

2. re-exporting unist, mdast, and hast under another name like unist-types, etc

I think this indirection confusing at most, and it just adds another dependency in the user’s node_module directory for no real benefit.

3. move the packages and refactor all the unified typings

This has my preference, however, considering the required refactors I don’t know if this is worth the trouble.

4. create an ESLint preset which ignores these module names

I don’t think this can be solved this way.

5. update the eslint plugin upstream to handle a package with a definitely typed package, but no unscoped package

Perhaps this is the right thing to do. I.e. even if mdast is moved and some errors are gone, still https://github.com/remcohaszing/remark-mermaidjs/blob/master/src/index.ts#L5 would cause eslint-plugin-import/no-extraneous-dependencies to complain, even though this import is nowhere to be found in the transpiled JavaScript or types definitions.

[ChristianMurphy]

The drawback here is that I feel unist etc are specs/documentation

I agree, but I also tend to see typescript as specs/documentation. 🙂

1 publishing directly to unist, mdast, and hast
5 update the eslint plugin upstream to handle a package with a definitely typed package, but no unscoped package

these two are the ones I lean toward

3 move the packages and refactor all the unified typings

I'd really like to avoid this, there are a lot of packages with typings within unified.
and even more within the community that would need to migrate.
It might be okay as part of a larger effort like unifiedjs/rfcs#5, but by itself, it seems like a lot of work for not a lot of benefit.

4 create an ESLint preset which ignores these module names

I don’t think this can be solved this way.

I think it can, https://github.com/benmosher/eslint-plugin-import/blob/HEAD/docs/rules/no-unresolved.md#ignore
That doesn't mean it should be solved this way, but it is possible.

[remcohaszing]

I think it can, https://github.com/benmosher/eslint-plugin-import/blob/HEAD/docs/rules/no-unresolved.md#ignore

I totally missed this somehow!

I don’t think it makes sense to create an ESLint configuration just for this purpose. but I’ll add it to my own shareable config then. I think this solves the biggest issue I’m having currently.

[wooorm]

Oh nice!

Well, uhmm, does that mean we can close this issue, because DT is fine if ESLint is configured?

[remcohaszing]

Yup 👍

[wooorm]

Could this be solved in DT? Can index.js files be added there?

[remcohaszing]

No. If the TypeScript decorator causes the import to stay, then the runtime (NodeJS) will try to import mdast, which doesn’t resolve to @types/mdast.