google / google/closure-compiler

Need a clearer story about non-renamed properties

Open
#2,591 3 comments 3 reactions 0 assignees View on GitHub
triage-done
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.