Design Meeting Notes, 5/25/2022

[DanielRosenwasser]

cts files should be modules?

#49207

• Historically, TS detects if a file is a module depending on import/export syntax present.
• moduleDetection flag allows you to control that.
  • Has a force option that makes it so that everything except .d.ts files are modules.
  • Also has auto, which says mts and mjs are supposed to be modules
    • BUT we didn't do this for cts and cjs
    • Idea was consistency with ts and js files
• Should we...
  • Update --moduleDetection auto to recognize cts and cjs
  • Make --moduleDetection force in Node16+?
• cts and cjs will always be processed as (CJS) modules by Node.js, so we should always recognize them as (CJS) modules
  • Sure, but --module node16 implies you're going to be running in Node16 too?
• Team is leaning towards both.
• It's a break, but we'd need to do this in a patch and ASAP because it's not desirable long-term behavior.
• We want to do both. May need to consider API breaks though. 😕

/** @suggest */ JSDoc Tag

#49220

• Want to suggest well-known values to users for a more open-ended field (e.g. GET, POST, DELETE... but the field is open-ended so it's just a string).

  /**
   * @suggest {"GET" | "POST" | "DELETE} e
   */
  function f(e: string) {
    // ...
  }

• Bikeshed time

  /** @suggest {"a" | "b"} */
  let foo: string;
  
  /**
   * @param e @suggest {"GET" | "POST" | "DELETE}
   */
  function f(e: string) {
    // ...
  }

• Is the @suggest part of the value or part of the type?

  • Tying to the usage site, but it's intending to "replace" the type itself.
  • How does this get funneled along? What if you throw the type of a property through a mapped/conditional type? Do you then generate an @suggest whose contents were processed by said conditional or mapped type?

• Lots of people ask for stuff like "GET" | "POST" | ... | string to achieve this. It doesn't make sense from a set theory perspective, but they want it for tooling.

  • People often want this to
    • Spell check literals that are "similar", but is at odds with supporting any string.
    • Completions.

• We've heard Python is adding a type constructor for these purposes, but it is a little strange? Rejects unrecognized literals, allows all strings.

• Tagging work we've done in the past (link @weswigham?) is one way to achieve this.

• [[Something about leveraging]]

  type Completions<TKey extends PropertyKey> = {
    completions?: { [K in TKey]?: any }
  };

• Need to better understand this. CSS Types, look on DT for unions with string.

• Ideally, this completion data is associated with the type and traverses along.

  • Union origins achieve this almost - we preserve the non-normalized origin of a union if the type itself is a union.

• Could have multiple string types with completion info associated, but then have to subtype-reduce them to a new string type with a "unioned" completion info.

• Type system should tell you about sets of values and what are reasonable sets of values. This is entirely about editor experience and documentation.

• Feels like we need to prove things out here.