Design Meeting Notes, 10/1/2024

[DanielRosenwasser]

The internal Modifier

#5228

• We've discussed an internal modifier on-and-off since 2015.
• High 👍 count, but haven't pursued it.
• Today you can use /** @internal */ JSDoc comments to mark things as internal, and --stripInternal.
• Previously, --stripInternal was not even publicly documented.
• Also, have to do hacks to make .d.ts bundling work with this.
• Would be nice to have something more formal.
  • Also, internal allows you to know whether something is getting overridden in a subtype.
• Idea:
  • internal stays in .d.ts output.
  • Project package or project boundary.
    • Only operates in the same compilation.
  • Not allowed to import an export internal.
  • At the tsconfig.json level, internal access might be granted and asserted in a few ways:

    • Maybe an option for specific packages

      {
          "compilerOptions": {
              // Grant access to 'consuming-package':
              "internalsVisibleTo": ["consuming-package"],
      
              // Assert access to 'dependency-package':
              "internalsVisibleFrom": ["dependency-package"],
          }
      }

    • Possibly just something on each reference

      {
          "references": [
              { "path": "../package", "allowInternals": true }
          ]
      }

• What are the rules?
  • Can't mix (e.g. no public and internal in the same declaration).
• Why not JSDoc?
  • Relatively expensive for this.
• What should tools do with internal?
  • Should bundlers limit access to an internal member that's export *'d?
    • We'd sort of hope "no".
  • Does the declaration emitter have to worry about this now?
  • What happens when you run keyof on a type with internal?
    • Probably should do the same thing that private does.
    • But does that mean that keyof means something different depending on where it's written.
  • How does this work for overload resolution?
    • Do overloads get skipped?
    • Do they get related appropriately?
• The "someone subclassed this" issue is not something we've heard a ton of.
• Do most people use .d.ts bundlers that can do this post-processing?
  • No, mostly not.
• Some of our build tooling would be simpler if we had this.
• But doesn't it mean that we're just making other stuff more complex?
  • For example, public and private overloads can't be mixed today.
  • Well maybe we do need to explore that restriction.
• Also, some of the point of --stripInternal is to not make things publicly known and avoid documenting functions to prevent usage.
• Back to this question again - what do you do when you have a mapped type?
  • internal is inaccessible depending on where it's used.
  • private and protected has this, but it's not witnessable in the majority of code (which is outside of the class).
• Coming back to keyof - is this now a location-sensitive operation?
  • The idea that you will get different types based on instantiation location is not something we've done before.
    • Really don't like that.
• What do you want?
  • Scope visibility to peers.
  • Keep existence undocumented.
• Do we really want an ergonomic way for people to import something marked internal?
  • We don't have to do everything listed above.
• Can do this just on the module level.
  • Maybe even just that and the property level.
  • "Good enough" as readonly.
• Cautious but curious around a solution.
  • Not convinced that we would have a solution that we'd entirely be happy with.
  • Must preserve existing invariants around how type information appears.
• One opinion: sympathetic to a package-like modifier, but doesn't entirely solve the problem for our own usage for hiding entities in the resulting declaration file.

[INeedJobToStartWork]

Not allowed to import an export internal.

We are talking here about whole codebase or just entry file?

I think good idea would be have option or just apply this to entry file.

Or is it mentioned at

At the tsconfig.json level, internal access might be granted and asserted in a few ways:

I am not sure i full understand this.