[api-extractor] Exposing whether an API item is readonly

[zelliott]

Motivation

From the perspective of an API consumer, it's useful to know whether an API item is "readonly". Consider the following example:

export class Example {
 a = 'hello';
 readonly b = 'hello'
}

const example = new Example();
example.a = 'goodbye';  // Allowed
example.b = 'goodbye';  // Not allowed

It's useful for an API consumer to know that example.b = 'goodbye'; results in a TypeScript compilation error.

However, determining whether something is readonly is not as simple as just looking for the TypeScript readonly keyword. Consider the following examples:

export class Example {
 readonly a = 'hello';
  
 get b() { return 'hello'; }

 get c() { return 'hello'; }

  /** @readonly */
 set c(value: string) { throw new Error('c is readonly'); }
}

export const d = 'hello';

The examples a - d above are all examples of "readonly" properties/variables for which it would make sense to include a readonly property in their respective doc model nodes. From the perspective of an API consumer, these items are all readonly in some way (and in particular, examples a, b, and c are essentially functionally equivalent from their perspective).

Brief design

We'll define an api-extractor-model mixin similar to ApiStaticMixin called ApiReadonlyMixin. This mixin will be applied to ApiVariable, ApiProperty, etc. Then, we'll update api-extractor to assign this property accordingly. Note that there are some open questions around when this assignment should be done.

References

For the original Zulip discussion behind this FR, please see https://rushstack.zulipchat.com/#narrow/stream/262521-api-extractor/topic/Checking.20if.20an.20item.20is.20readonly. Credit to @octogonz for coming up with the examples above as well as the brief design strategy.

[octogonz]

Just to clarify: For API documentation purposes, I think we're proposing that the definition of "readonly" will include these things:

• Class fields with the readonly keyword: declare class X { public readonly thing: string; }
• Interface members with the readonly keyword: declare interface X { readonly thing: string; }
• Class/interface properties that are missing a setter: declare class X { public get thing(): string; }
• Class/interface properties whose setter has the @readonly TSDoc tag: c from the example above.
• Variables declared with the const keyword, including both namespace exports and top-level module exports

No other forms will be considered "readonly". For example, declare interface X { thing: readonly string[]; } would NOT be considered a "readonly" property.

Let me know if I misunderstood anything. If anyone can think of other TypeScript expressions that should be considered "readonly", let us know. Thanks!

[octogonz]

Also: This is a proposal to add a field to the .api.json format, so that the API documentation page can show an visual indicator such as [readonly] for these API items.

[zelliott]

Will it be confusing to users for thing: readonly string[] to not be considered by API Extractor to be "readonly"? Examples:

declare interface A { foo: readonly string[]; }
let b: readonly number[] = [0, 1, 2];

b is partially readonly (I'm not quite sure how to describe it).