Shall we narrow the scope of the main index?

[spoenemann]

Currently we reexport most of Langium's API in the index.ts. As a consequence, we lose the context when users import a symbol from 'langium'. All symbols are available in this global pool regardless of our internal code structure.

A possible alternative would be to reduce the main index to reexport only from sources of the same directory level (dependency-injection, default-module etc.) and add index.ts files to all subdirectories. Then you would import everything grammar-related from 'langium/lib/grammar', everything LSP-related from 'langium/lib/lsp' and so on. This would nicely match the structure of services in our LangiumServices type. WDYT?

[msujew]

I'm quite torn on that matter. On one hand, the current approach keeps Langium more in line with other JS libraries that are only imported by their name. On the other hand, this would make imports a bit more structured, like I'm used from other programming languages/runtimes.

Either way, if we go trough with this idea, we should use package exports to modify the import path so that LSP services are imported from langium/lsp which kind of sounds nice. This would also enable us to export our injection module through a path like langium/module or something similiar.

What do other experienced JS devs think? @danieldietrich @brucou

[brucou]

I don't really have a strong opinion here. What are the advantages of both approaches from an API consumer point of view?

Exporting the whole API from one place may be simpler for the consumer of that API. They do not have to remember in which specific package was that specific function that they are using. I always had the issue with RxJS and LoDash, when I had to remember how to import a Subject and how to import a map operator etc. This is especially acute from new API users, who are not yet acquainted with the concepts. Having them figure if that is LSP or grammar or else is an additional hurdle in the learning path. A mitigating point is that some IDEs became good at helping the user with that. WebStorm from JetBrains will automatically add the relevant imports as you type, so the import maps is irrelevant to you. I don't know if VS Code has a similar feature.

On the other hand, splitting per route, say langium/lib/lsp, may help with tree shaking. That was the main driver behind lodash namespacing its (huge) API. Rather than importing the full lodash library (25K), developers could import just the function that they need (1-2K). As mitigating points, things are simpler now with ES modules uesd in connection with bundlers: the bundler will strive to pick up only the imported functions from the library automatically. Also tree-shaking is mostly relevant in a browser context (to not keep the user waiting on the parsing of KB of JS), less so in a Node.js context.

Also

This would nicely match the structure of services in our LangiumServices type

That matching may also be a coupling of LangiumServices with the API exports. When (if) LangiumServices changes, you may have to change the API exports accordingly to maintain the matching. This is neither good nor bad. The coupling may simply reflect a fundamental reality, or conversely it could be accidental. The mitigating point here is that the exports field in the package.json, as @msujew mentioned may help reduce that coupling anyways (from an API consumer point of view). The exports field also allows you to hide private APIs from public API consumers, whlie maintainers can continue to consume the private ones.

[danieldietrich]

Thanks for asking, Mark. Personally, I don't like imports from sub-packages. Here are my thoughts:

Importing from sub-modules exposes internal API

Ant Design is a good example for a bad user experience regarding sub-module imports. I would not recommend to do so because there is the risk that users import APIs that are meant to be internal. Especially we might need to export an API in a sub-module because other sub-modules make internally use of it.

See also no-submodule-imports as an example that sub-module imports are considered bad practice.

Importing from sub-modules is not approachable

With sub-module imports it is hard from the user perspective to find out which types/objects are available for importing. Only documentation helps to get the right pointers on how to do (read: import) things.

I would love to use the following API, it would be approachable because we could make use of content assist.

import * as langium from 'langium'

const { Foo } = langium.parser;

const { Bar } = langium.grammar;

Organizing exports

I suggest to define an index.ts file in each sub-module that explicitly declares (read: exports) the public API of the sub-module.

To get the status quo, the top-level index.ts could then re-export all sub-modules like this:

// same as `export * from './grammar/index.ts'`
export * from './documents';
export * from './generator';
export * from './grammar';
export * from './lsp';
...

To change the API in direction of const { Foo } = langium.parser, we could take a look at how vscode does it.

See also TypeScript: Namespaces and Modules.

[spoenemann]

If we agree on keeping the single 'langium' module where we export everything, we should review the naming of our API so it's descriptive enough to avoid ambiguities.

Example: a function name normalize may be ok when you import it from a specific submodule, but it's too generic when you import it from the single main module.