Merge branch 'main' into dependabot/nuget/packages/jsii/dotnet-runtim…

…e-test/test/XunitXml.TestLogger-3.1.11

.github/dependabot.yml

@@ -8,6 +8,7 @@ updates:
     labels:
       - dependencies
       - language/dotnet
+      - auto-approve
 
   - package-ecosystem: nuget
     directory: '/packages/@jsii/dotnet-runtime-test/test'
@@ -16,6 +17,7 @@ updates:
     labels:
       - dependencies
       - language/dotnet
+      - auto-approve
 
   - package-ecosystem: pip
     directory: '/packages/@jsii/python-runtime'
@@ -24,6 +26,7 @@ updates:
     labels:
       - dependencies
       - language/python
+      - auto-approve
 
   - package-ecosystem: pip
     directory: '/gh-pages'
@@ -32,6 +35,7 @@ updates:
     labels:
       - dependencies
       - language/python
+      - auto-approve
 
   - package-ecosystem: pip
     directory: '/packages/jsii-pacmak/test/generated-code'
@@ -40,6 +44,7 @@ updates:
     labels:
       - dependencies
       - language/python
+      - auto-approve
 
   - package-ecosystem: pip
     directory: '/packages/jsii-pacmak/lib/targets/python'
@@ -48,6 +53,7 @@ updates:
     labels:
       - dependencies
       - language/python
+      - auto-approve
     ignore:
       - dependency-name: "setuptools"
 
@@ -58,6 +64,7 @@ updates:
     labels:
       - dependencies
       - language/go
+      - auto-approve
 
   - package-ecosystem: gomod
     directory: '/packages/@jsii/go-runtime-test/project'
@@ -66,6 +73,7 @@ updates:
     labels:
       - dependencies
       - language/go
+      - auto-approve
     ignore:
       - dependency-name: github.com/aws/jsii-runtime-go
       - dependency-name: github.com/aws/jsii-runtime-go/*
@@ -77,3 +85,4 @@ updates:
       interval: daily
     labels:
       - dependencies
+      - auto-approve

gh-pages/content/overview/features.md

@@ -1,5 +1,24 @@
 # Features
 
+## Use-Cases & Limitations
+
+The _jsii_ toolchain allows developers to author class libraries once in TypeScript, while allowing their customers to
+consume them in various [other languages](#target-languages). This is used for libraries such as the AWS CDK (
+[`aws-cdk-lib`](https://npmjs.com/package/aws-cdk-lib)), and is intended for use in similar contexts: client-side,
+design-time SDKs that do not require long-running processes and is not in the path to serve time-sensitive requests.
+
+Due to limitations of its [runtime architecture](./runtime-architecture.md), _jsii libraries_ for languages other than
+Javascript/TypeScript are best suited for inclusion in short-running processes, outside of performance-sensitive or
+memory-constrained contexts.
+
+While `async` APIs are supported by the _jsii_ type system, support for these should be treated as highly experimental.
+In particular, support in the various [target languages](#target-languages) varies greatly, and users may encounter a
+variety of bugs or surprising behaviors. The current JavaScript-based cross-language interoperability kernel is also
+known to block execution of background micro-tasks when it's waiting for commands from the host process.
+
+The runtime libraries used by _jsii libraries_ are not currently designed for thread safety, and using _jsii libraries_
+in multi-thread contexts is unsupported at the moment.
+
 ## TypeScript Support
 
 The `jsii` compiler leverages the original [TypeScript] compiler API to compile **TypeScript** source files and produce
@@ -11,7 +30,7 @@ To determine the version of **TypeScript** that is in use by the installed relea
 
 ```console
 # jsii --version
-1.15.0 (build 585166b), typescript 3.9.7
+5.1.6 (build d8f400c), typescript 5.1.6
 ```
 
 You can then refer to the [TypeScript] documentation to determine which language features are available in that specific

gh-pages/content/specification/3-kernel-api.md

@@ -471,10 +471,18 @@ such values.
 
 #### Asynchronous method invocation
 
+!!! bug "Largely un-tested"
+    Asynchronous operations are only partially supported in the various target languages, and is currently not widely
+    used. As such, support is not as "battle-tested" as the rest of the jsii interoperability features, and customers
+    may run into usability issues, unexpected bugs, or surprising behaviors when using async.
+
+    In particular, outstanding `Promise`s may not be able to make progress as expected due to specific implementation
+    details of the `@jsii/runtime` event loop, which can result in deadlock situations.
+
 The `invoke` call can only be used to invoke _synchronous_ methods. In order to invoke _asynchronous_ methods, the
-`begin` and `end` calls must be used instead. Once the _host_ app has entered an asynchronous workflow (after it makes
-the first `begin` call), and until it has completed all asynchronous operations (after all `begin` class are matched
-with an `end` call), no _synchronous_ operation (including synchronous callbacks) may be initiated.
+`begin` and `end` calls must be used instead. Once the _host_ app has entered a synchronous workflow (after it makes
+an `invoke` call), and until it has completed that synchronous operation (after all callbacks have been handled and the
+`InvokeResponse` has been received), no _asynchronous_ operation may be initiated by the host app.
 
 ```ts
 interface BeginRequest {

gh-pages/content/user-guides/lib-author/.pages.yml

@@ -4,6 +4,6 @@ nav:
   - index.md
   - quick-start
   - typescript-restrictions.md
-  - configuration
   - hints.md
+  - configuration
   - toolchain

gh-pages/content/user-guides/lib-author/hints.md

@@ -1,4 +1,4 @@
-# Type system hints
+# Special TSDoc tags
 
 The `jsii` compiler interprets some documentation tags as hints that influence
 the type system represented in the `.jsii` assembly files.
@@ -13,7 +13,7 @@ another capital letter (which normally would make them be treated as
 [struct]: ../../specification/2-type-system.md#structs
 [interface]: ../../specification/2-type-system.md#behavioral-interfaces
 
-```ts
+```ts hl_lines="2"
 /**
  * @struct
  */
@@ -25,3 +25,27 @@ export interface IPRange {
 !!! important
     The `@struct` hint can only be used on interface declarations. Attempting to
     use them on any other declaration will result in a compilation error.
+
+## Excluding a declaration from multi-language support
+
+The `@jsii ignore` tag causes the documented declaration to be ignored by the
+`jsii` compiler. This has the effect of making the declaration invisible to
+languages other than **TypeScript** and **Javascript**. Developers using this
+tag should consider the implications on the usability of their library in other
+languages.
+
+```ts hl_lines="9"
+export interface Props {
+  public readonly name: string;
+
+  /**
+   * TypeScript/Javascript customers may pass additional properties with this
+   * struct, however this will not be possible in other languages, as jsii does
+   * not support index signatures.
+   *
+   * @jsii ignore
+   */
+  public readonly [key: string]: unknown;
+}
+
+```

gh-pages/content/user-guides/lib-author/typescript-restrictions.md

@@ -160,14 +160,36 @@ export class Child extends Base {
 }
 ```
 
-## Parameterized Types (aka: Generics)
+## Index Signatures
 
-Parameterized types are not consistently supported in all supported target languages. **Go** does not currently support
-generics, and the differences in generic semantics between **TypeScript**, **C#** and **Java** make it difficult to
-correctly represent such types in all those languages. As a consequence, `jsii` does not support declaring parameterized
-types.
+**TypeScript** allows declaring _additional properties_ through the use of index signatures. These are however not
+supported by the _jsii type system_ and are rejected by the compiler.
 
-Only certain *built-in* parameterized types can be used in `jsii` modules:
+!!! info
+    Version `1.x` of the compiler _silently ignores_ index signatures instead of reporting a compilation error. Users
+    with offending APIs migrating from `jsii@1.x` to `jsii@5.0` or newer need to either remove those declarations, or
+    explicitly ignore them using the [`@jsii ignore` tag](./hints.md#excluding-a-declaration-from-multi-language-support).
+
+```ts hl_lines="4-5"
+export interface WithIndexSignature {
+  public readonly name: string;
+
+  // 💥 Index signatures are not supported
+  public [key: string]: unknown;
+}
+```
+
+## TypeScript Mapped Types
+
+!!! info
+    These are also referred to as "Generics", "Parameterized Types", "Utility Types", ...
+
+Parameterized types are not consistently supported in all supported target languages. **Go** support for generics is
+relatively limited (for good reasons) compared to TypeScript and most Object-Oriented languages, and the differences in
+generic semantics between **TypeScript**, **C#** and **Java** make it difficult to correctly represent such types in all
+those languages. As a consequence, `jsii` does not support declaring parameterized types.
+
+Certain *built-in* TypeScript types can however be used in `jsii` modules:
 
 - `Array<T>`, which is equivalent to `T[]`
 - `Record<string, T>`, which is equivalent to `{ [key: string]: T }`
@@ -187,7 +209,35 @@ export interface IAsyncFooMaker {
 }
 ```
 
-# Soft-Reserved Words
+!!! danger "`#!ts Pick<T, Keys>` and `#!ts Omit<T, Keys>`"
+    Users are often tempted to use `#!ts Pick<T, Keys>` and `#!ts Omit<T, Keys>` when creating higher level abstractions
+    of types exposed by their dependencies, and they want to expose all configuration options from the upstream
+    implementation except for some specific properties which are determined fully by the new abstraction.
+
+    `#!ts Pick<T, Keys>` and `#!ts Omit<T, Keys>` are not supported as they would result in open-ended implementation
+    requirements to exist in languages such as **Java** and **C#** where such things are not possible.
+
+    Users with this particular use-case should investigate generating code in order to reproduce the upstream type
+    without the filtered out fields. For example, this can be done with [`projen`](http://npmjs.com/package/projen)
+    using [`jsii-struct-builder`](https://github.com/mrgrain/jsii-struct-builder).
+
+## Type Aliases
+
+TypeScript supports type aliasing using the `#!ts export type Name = ...` syntax. While this is not considered a
+compilation error by the `jsii` compiler, those types are implicitly de-sugared by the compiler for all language targets
+except for **TypeScript**.
+
+```ts hl_lines="1-2 5-6"
+// 👻 Only visible in TypeScript
+export type FooOrBar = Foo | Bar;
+
+export interface Props {
+  // ⚠️ Effectively `readonly fooOrBar: Foo | Bar;` in non-TypeScript
+  readonly fooOrBar: FooOrBar;
+}
+```
+
+## Soft-Reserved Words
 
 In order to guarantee a consistent developer experience across all supported languages, `jsii` emits warnings whenever
 a declaration is named after any target language's *reserved words*, as those will need renaming in target languages:

packages/@jsii/go-runtime-test/project/go.mod

@@ -9,18 +9,20 @@ require (
 	github.com/aws/jsii/jsii-calc/go/scopejsiicalclib v0.0.0-devpreview
 	github.com/stretchr/testify v1.8.4
 	golang.org/x/lint v0.0.0-20210508222113-6edffad5e616
-	golang.org/x/tools v0.10.0
+	golang.org/x/tools v0.11.0
 )
 
 require (
 	github.com/Masterminds/semver/v3 v3.2.1 // indirect
 	github.com/aws/jsii/jsii-calc/go/scopejsiicalcbaseofbase/v2 v2.1.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/fatih/color v1.15.0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.19 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/yuin/goldmark v1.4.13 // indirect
-	golang.org/x/mod v0.11.0 // indirect
-	golang.org/x/sys v0.9.0 // indirect
+	golang.org/x/mod v0.12.0 // indirect
+	golang.org/x/sys v0.10.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 

packages/@jsii/go-runtime-test/project/go.sum

@@ -2,6 +2,11 @@ github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fatih/color v1.15.0 h1:kOqh6YHBtK8aywxGerMG2Eq3H6Qgoqeo13Bk2Mv/nBs=
+github.com/fatih/color v1.15.0/go.mod h1:0h5ZqXfHYED7Bhv2ZJamyIOUej9KtShiJESRwBDUSsw=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
 github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA=
 github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -19,24 +24,31 @@ golang.org/x/mod v0.10.0 h1:lFO9qtOdlre5W1jxS3r/4szv2/6iXxScdzjoBMXNhYk=
 golang.org/x/mod v0.10.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.11.0 h1:bUO06HqtnRcc/7l71XBe4WcqTZ+3AH1J59zWDDwLKgU=
 golang.org/x/mod v0.11.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/mod v0.12.0 h1:rmsUpXtvNzj340zd98LZ4KntptpfRHwpFOHG188oHXc=
+golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.2.0 h1:PUR+T4wwASmuSTYdKjYHI5TD22Wy5ogLU5qZCOLxBrI=
 golang.org/x/sync v0.3.0 h1:ftCYgMx6zT/asHUrPw8BLLscYtGznsLAnjq5RH9P66E=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0 h1:EBmGv8NaZBZTWvrbjNoL6HVt+IVy3QDQpJs7VRIw3tU=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.9.0 h1:KS/R3tvhPqvJvwcKfnBHJwwthS11LRhmM5D59eEXa0s=
 golang.org/x/sys v0.9.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.10.0 h1:SqMFp9UcQJZa+pmYuAKjd9xq1f0j5rLcDIk0mj4qAsA=
+golang.org/x/sys v0.10.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/tools v0.0.0-20200130002326-2f3ba24bd6e7/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/tools v0.9.3 h1:Gn1I8+64MsuTb/HpH+LmQtNas23LhUVr3rYZ0eKuaMM=
 golang.org/x/tools v0.9.3/go.mod h1:owI94Op576fPu3cIGQeHs3joujW/2Oc6MtlxbF5dfNc=
 golang.org/x/tools v0.10.0 h1:tvDr/iQoUqNdohiYm0LmmKcBk+q86lb9EprIUFhHHGg=
 golang.org/x/tools v0.10.0/go.mod h1:UJwyiVBsOA2uwvK/e5OY3GTpDUJriEd+/YlqAwLPmyM=
+golang.org/x/tools v0.11.0 h1:EMCa6U9S2LtZXLAMoWiR/R8dAQFRqbAitmbJ2UKhoi8=
+golang.org/x/tools v0.11.0/go.mod h1:anzJrxPjNtfgiYQYirP2CPGzGLxrH2u2QBhn6Bf3qY8=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=