google / google/closure-compiler
Need a clearer story about non-renamed properties
- Dominant language
- JavaScript
- Stars
- 7.7k
- Forks
- 1.2k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 6
Description
This seems to cause confusion at least monthly, either internally or externally (most recently, #2587). People expect that `@export` should prevent renaming, but are surprised when that's not how it works. We tell them to move the definition to an extern, but they complain that either (a) it's too much repetition and/or leads to weird separation, or (b) it doesn't work correctly with enums, etc.
The root of the issue is that there's more different use cases than there are different solutions. `@export` (and equivalently `goog.exportSymbol`) is designed for building an exported API that a caller can call into, but since it's implemented with aliasing, it supports neither (a) defining expected object structures for inputs to the API (i.e. a contravariance issue), nor (b) mutation of the underlying API objects. On the other hand, externs are designed for clients of third-party APIs. Confusing the issue further is the `--generate_externs_from_exports` flag, which *does* provide a partial solution (i.e. a two-stage compilation where the first stage generates the externs and the second passes the generated externs back in), though it's not the most practical.
The case that seems to be primarily left out is that of providing an implementable API, which primarily amounts to a request that the compiler not rename a certain field. Another way to look at it is to allow type declarations in source files to be treated as externs. Am I missing anything here?
We should look at all the use cases and come up with a clearer story for how to actually handle each one.
Contributor guide
Assessment
This issue has not been assessed yet.