Repository: TypeScript
Issue: A way to hide a property from completions
Labels: Suggestion,Awaiting More Feedback

# Suggestion

## 🔍 Search Terms

List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily and help provide feedback.

hide, private, internal, completions

The closest issue found was [this](https://github.com/microsoft/TypeScript/issues/28722) but while its title suggests that it may be related - its content seems to be entirely different.

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

It would be cool if I could annotate a member property as being "hidden" and effectively hide it from the completions list.

## 📃 Motivating Example

I've found out that extracting type params using a conditional type doesn't always behave the same way as getting that type from a property member.

When it comes to inference we might get different results from signatures resembling those ones:
```ts
type StateMachine<TContext> = {
  context: TContext;
  TContext: TContext;
}
// in a more complicated situation this might not infer the return type correctly
declare function useMachine<T extends StateMachine<any>>(machine: T): T extends StateMachine<infer C> ? State<C> : never
// but this might work just OK
declare function useMachine<T extends StateMachine<any>>(machine: T): State<T["TContext"]>
```

Obviously, my situation at hand is far more complicated. All type params are actually used, it's possible to extract the generic using a conditional type but when we call `useMachine` with the "concrete" machine then it fails to retrieve the embedded type using the first technique.

I've accidentally figured out that the latter improved the situation for us. I've seen this technique to be called in the past "phantom types". Obviously, though, we don't our users to access such a phantom property - it's merely used to help us out with the inference at the consuming call site. So it would be quite cool if we could just annotate those properties somehow so they could be removed from the completions list.

I'm pretty sure that this is such a generic feature that it could be useful to people in more contexts. For instance, in `react-navigation` we might find this beauty: 
https://github.com/react-navigation/react-navigation/blob/90874397e653a6db642822bff18014a3e5980fed/packages/core/src/types.tsx#L156-L168

I've tested out all of the JSdoc tags~ that I could think of but none of them work like that:
[TS playground](https://www.typescriptlang.org/play?#code/C4TwDgpgBAKhDOwoF4oG8BQVtQPQCp8oABMAJwEsA3AQ2Gn1yx3OoC4oByT57Ao4jQDGQhPCita9KI15Rho+PAAKlKRA7c5-EhQB29MnpoAbGUxxR9h4yc09LO4hQDmegPZkGFnK49f7DABfDAwAEwghExovKCF3PUQoYA44RFCgA)

It seem to me though that `@ptivate`/`@access private` should actually work as I've found some comments~ in the TypeScript codebase that private properties should be excluded. I see how JSDoc annotation is different from a "real" private property but it would be great if this could "just work".

I'm not sure how feasible implementing this is but maybe I could take a crack at this - it seems that the required changes would be limited to [`isValidPropertyAccessForCompletions`](https://github.com/microsoft/TypeScript/blob/3206df8e6d4580381cd3712e385574b0351c3ff0/src/compiler/checker.ts#L28978)

## 💻 Use Cases

It got kinda covered in the previous section.