chore: Update TypeScript from v4.3.5 to v5.1.3 (#1105)

crates/stc_ts_builtin_types/lib/README.md

@@ -1,8 +1,26 @@
 # Read this!
 
-The files within this directory are used to generate `lib.d.ts` and `lib.es6.d.ts`.
+The files within this directory are copied and deployed with TypeScript as the set of APIs available as a part of the JavaScript language.
+
+There are three main domains of APIs in `src/lib`:
+
+ - **ECMAScript language features** - e.g. JavaScript APIs like functions on Array etc which are documented in [ECMA-262](https://tc39.es/ecma262/)
+ - **DOM APIs** - e.g. APIs which are available in web browsers
+ - **Intl APIs** - e.g. APIs scoped to `Intl` which are documented in [ECMA-402](https://www.ecma-international.org/publications-and-standards/standards/ecma-402/)
+
+## How do we figure out when to add something?
+
+TypeScript has a rule-of-thumb to only add something when it has got far enough through the standards process that it is more or less confirmed. For JavaScript APIs and language features, that means the proposal is at stage 3 or later.
+
+You can find the source of truth for modern language features and Intl APIs in these completed proposal lists:
+
+ - [JavaScript](https://github.com/tc39/proposals/blob/master/finished-proposals.md)
+ - [Intl](https://github.com/tc39/proposals/blob/master/ecma402/finished-proposals.md)
+
+For the DOM APIs, which are a bit more free-form, we have asked that APIs are available un-prefixed/flagged in at least 2 browser _engines_ (i.e. not just 2 chromium browsers.) 
 
 ## Generated files
 
-Any files ending in `.generated.d.ts` aren't meant to be edited by hand.
-If you need to make changes to such files, make a change to the input files for [**our library generator**](https://github.com/Microsoft/TSJS-lib-generator).
+The DOM files ending in `.generated.d.ts` aren't meant to be edited by hand.
+
+If you need to make changes to such files, make a change to the input files for [**our library generator**](https://github.com/microsoft/TypeScript-DOM-lib-generator).

crates/stc_ts_builtin_types/lib/decorators.d.ts

@@ -1,5 +1,5 @@
 /**
- * The decorator context types provided to class member decorators.
+ * The decorator context types provided to class element decorators.
  */
 type ClassMemberDecoratorContext =
  | ClassMethodDecoratorContext
@@ -60,34 +60,37 @@ interface ClassMethodDecoratorContext<
  This = unknown,
  Value extends (this: This, ...args: any) => any = (this: This, ...args: any) => any,
 > {
- /** The kind of class member that was decorated. */
+ /** The kind of class element that was decorated. */
  readonly kind: "method";
 
- /** The name of the decorated class member. */
+ /** The name of the decorated class element. */
  readonly name: string | symbol;
 
- /** A value indicating whether the class member is a static (`true`) or instance (`false`) member. */
+ /** A value indicating whether the class element is a static (`true`) or instance (`false`) element. */
  readonly static: boolean;
 
- /** A value indicating whether the class member has a private name. */
+ /** A value indicating whether the class element has a private name. */
  readonly private: boolean;
 
- // NOTE: Disabled, pending the outcome of https://github.com/tc39/proposal-decorators/issues/494
- // /** An object that can be used to access the current value of the class member at runtime. */
- // readonly access: {
- // /**
- // * Gets the current value of the method from the provided receiver.
- // *
- // * @example
- // * let fn = context.access.get.call(instance);
- // */
- // get(this: This): Value;
- // };
+ /** An object that can be used to access the current value of the class element at runtime. */
+ readonly access: {
+ /**
+ * Determines whether an object has a property with the same name as the decorated element.
+ */
+ has(object: This): boolean;
+ /**
+ * Gets the current value of the method from the provided object.
+ *
+ * @example
+ * let fn = context.access.get(instance);
+ */
+ get(object: This): Value;
+ };
 
  /**
  * Adds a callback to be invoked either before static initializers are run (when
- * decorating a `static` member), or before instance initializers are run (when
- * decorating a non-`static` member).
+ * decorating a `static` element), or before instance initializers are run (when
+ * decorating a non-`static` element).
  *
  * @example
  * ```ts
@@ -121,34 +124,37 @@ interface ClassGetterDecoratorContext<
  This = unknown,
  Value = unknown,
 > {
- /** The kind of class member that was decorated. */
+ /** The kind of class element that was decorated. */
  readonly kind: "getter";
 
- /** The name of the decorated class member. */
+ /** The name of the decorated class element. */
  readonly name: string | symbol;
 
- /** A value indicating whether the class member is a static (`true`) or instance (`false`) member. */
+ /** A value indicating whether the class element is a static (`true`) or instance (`false`) element. */
  readonly static: boolean;
 
- /** A value indicating whether the class member has a private name. */
+ /** A value indicating whether the class element has a private name. */
  readonly private: boolean;
 
- // NOTE: Disabled, pending the outcome of https://github.com/tc39/proposal-decorators/issues/494
- // /** An object that can be used to access the current value of the class member at runtime. */
- // readonly access: {
- // /**
- // * Invokes the getter on the provided receiver.
- // *
- // * @example
- // * let value = context.access.get.call(instance);
- // */
- // get(this: This): Value;
- // };
+ /** An object that can be used to access the current value of the class element at runtime. */
+ readonly access: {
+ /**
+ * Determines whether an object has a property with the same name as the decorated element.
+ */
+ has(object: This): boolean;
+ /**
+ * Invokes the getter on the provided object.
+ *
+ * @example
+ * let value = context.access.get(instance);
+ */
+ get(object: This): Value;
+ };
 
  /**
  * Adds a callback to be invoked either before static initializers are run (when
- * decorating a `static` member), or before instance initializers are run (when
- * decorating a non-`static` member).
+ * decorating a `static` element), or before instance initializers are run (when
+ * decorating a non-`static` element).
  */
  addInitializer(initializer: (this: This) => void): void;
 }
@@ -163,34 +169,37 @@ interface ClassSetterDecoratorContext<
  This = unknown,
  Value = unknown,
 > {
- /** The kind of class member that was decorated. */
+ /** The kind of class element that was decorated. */
  readonly kind: "setter";
 
- /** The name of the decorated class member. */
+ /** The name of the decorated class element. */
  readonly name: string | symbol;
 
- /** A value indicating whether the class member is a static (`true`) or instance (`false`) member. */
+ /** A value indicating whether the class element is a static (`true`) or instance (`false`) element. */
  readonly static: boolean;
 
- /** A value indicating whether the class member has a private name. */
+ /** A value indicating whether the class element has a private name. */
  readonly private: boolean;
 
- // NOTE: Disabled, pending the outcome of https://github.com/tc39/proposal-decorators/issues/494
- /** An object that can be used to access the current value of the class member at runtime. */
- // readonly access: {
- // /**
- // * Invokes the setter on the provided receiver.
- // *
- // * @example
- // * context.access.set.call(instance, value);
- // */
- // set(this: This, value: Value): void;
- // };
+ /** An object that can be used to access the current value of the class element at runtime. */
+ readonly access: {
+ /**
+ * Determines whether an object has a property with the same name as the decorated element.
+ */
+ has(object: This): boolean;
+ /**
+ * Invokes the setter on the provided object.
+ *
+ * @example
+ * context.access.set(instance, value);
+ */
+ set(object: This, value: Value): void;
+ };
 
  /**
  * Adds a callback to be invoked either before static initializers are run (when
- * decorating a `static` member), or before instance initializers are run (when
- * decorating a non-`static` member).
+ * decorating a `static` element), or before instance initializers are run (when
+ * decorating a non-`static` element).
  */
  addInitializer(initializer: (this: This) => void): void;
 }
@@ -205,42 +214,46 @@ interface ClassAccessorDecoratorContext<
  This = unknown,
  Value = unknown,
 > {
- /** The kind of class member that was decorated. */
+ /** The kind of class element that was decorated. */
  readonly kind: "accessor";
 
- /** The name of the decorated class member. */
+ /** The name of the decorated class element. */
  readonly name: string | symbol;
 
- /** A value indicating whether the class member is a static (`true`) or instance (`false`) member. */
+ /** A value indicating whether the class element is a static (`true`) or instance (`false`) element. */
  readonly static: boolean;
 
- /** A value indicating whether the class member has a private name. */
+ /** A value indicating whether the class element has a private name. */
  readonly private: boolean;
 
- // NOTE: Disabled, pending the outcome of https://github.com/tc39/proposal-decorators/issues/494
- // /** An object that can be used to access the current value of the class member at runtime. */
- // readonly access: {
- // /**
- // * Invokes the getter on the provided receiver.
- // *
- // * @example
- // * let value = context.access.get.call(instance);
- // */
- // get(this: This): Value;
-
- // /**
- // * Invokes the setter on the provided receiver.
- // *
- // * @example
- // * context.access.set.call(instance, value);
- // */
- // set(this: This, value: Value): void;
- // };
+ /** An object that can be used to access the current value of the class element at runtime. */
+ readonly access: {
+ /**
+ * Determines whether an object has a property with the same name as the decorated element.
+ */
+ has(object: This): boolean;
+
+ /**
+ * Invokes the getter on the provided object.
+ *
+ * @example
+ * let value = context.access.get(instance);
+ */
+ get(object: This): Value;
+
+ /**
+ * Invokes the setter on the provided object.
+ *
+ * @example
+ * context.access.set(instance, value);
+ */
+ set(object: This, value: Value): void;
+ };
 
  /**
  * Adds a callback to be invoked either before static initializers are run (when
- * decorating a `static` member), or before instance initializers are run (when
- * decorating a non-`static` member).
+ * decorating a `static` element), or before instance initializers are run (when
+ * decorating a non-`static` element).
  */
  addInitializer(initializer: (this: This) => void): void;
 }
@@ -302,36 +315,40 @@ interface ClassFieldDecoratorContext<
  This = unknown,
  Value = unknown,
 > {
- /** The kind of class member that was decorated. */
+ /** The kind of class element that was decorated. */
  readonly kind: "field";
 
- /** The name of the decorated class member. */
+ /** The name of the decorated class element. */
  readonly name: string | symbol;
 
- /** A value indicating whether the class member is a static (`true`) or instance (`false`) member. */
+ /** A value indicating whether the class element is a static (`true`) or instance (`false`) element. */
  readonly static: boolean;
 
- /** A value indicating whether the class member has a private name. */
+ /** A value indicating whether the class element has a private name. */
  readonly private: boolean;
 
- // NOTE: Disabled, pending the outcome of https://github.com/tc39/proposal-decorators/issues/494
- // /** An object that can be used to access the current value of the class member at runtime. */
- // readonly access: {
- // /**
- // * Gets the value of the field on the provided receiver.
- // */
- // get(this: This): Value;
+ /** An object that can be used to access the current value of the class element at runtime. */
+ readonly access: {
+ /**
+ * Determines whether an object has a property with the same name as the decorated element.
+ */
+ has(object: This): boolean;
 
- // /**
- // * Sets the value of the field on the provided receiver.
- // */
- // set(this: This, value: Value): void;
- // };
+ /**
+ * Gets the value of the field on the provided object.
+ */
+ get(object: This): Value;
+
+ /**
+ * Sets the value of the field on the provided object.
+ */
+ set(object: This, value: Value): void;
+ };
 
  /**
  * Adds a callback to be invoked either before static initializers are run (when
- * decorating a `static` member), or before instance initializers are run (when
- * decorating a non-`static` member).
+ * decorating a `static` element), or before instance initializers are run (when
+ * decorating a non-`static` element).
  */
  addInitializer(initializer: (this: This) => void): void;
 }

crates/stc_ts_builtin_types/lib/decorators.legacy.d.ts

@@ -1,4 +1,4 @@
 declare type ClassDecorator = <TFunction extends Function>(target: TFunction) => TFunction | void;
 declare type PropertyDecorator = (target: Object, propertyKey: string | symbol) => void;
 declare type MethodDecorator = <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
-declare type ParameterDecorator = (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+declare type ParameterDecorator = (target: Object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;