Merge branch 'main' into rosetta-python-nested-structs-bug

.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

.github/workflows/yarn-upgrade.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/setup-node@v3
         with:
           cache: yarn
-          node-version: 14
+          node-version: 16
 
       - name: Install Tools
         run: |-

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.85.0](https://github.com/aws/jsii/compare/v1.84.0...v1.85.0) (2023-07-17)
+
+
+### Bug Fixes
+
+* export transliterateAssembly and fix bug with transliterate cli (backport) ([#4166](https://github.com/aws/jsii/issues/4166)) ([6b7eb02](https://github.com/aws/jsii/commit/6b7eb02f3a822941185e8c74be71d677285c741e))
+* **go-runtime:** use fatih/color instead of ANSI Escape Code ([#4109](https://github.com/aws/jsii/issues/4109)) ([28b192a](https://github.com/aws/jsii/commit/28b192aa1a3ecdd3b3ce6ee49a5efd32db01e695))
+
 ## [1.84.0](https://github.com/aws/jsii/compare/v1.83.0...v1.84.0) (2023-06-13)
 
 

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:

lerna.json

@@ -12,6 +12,6 @@
       "rejectCycles": true
     }
   },
-  "version": "1.84.0",
+  "version": "1.85.0",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }

package.json

@@ -16,23 +16,23 @@
   },
   "devDependencies": {
     "@jest/types": "^28.1.3",
-    "@types/jest": "^29.5.2",
-    "@types/node": "^14.18.51",
-    "@typescript-eslint/eslint-plugin": "^5.59.11",
-    "@typescript-eslint/parser": "^5.59.11",
-    "all-contributors-cli": "^6.26.0",
-    "eslint": "^8.42.0",
+    "@types/jest": "^29.5.3",
+    "@types/node": "^14.18.53",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "all-contributors-cli": "^6.26.1",
+    "eslint": "^8.44.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-import-resolver-node": "^0.3.7",
     "eslint-import-resolver-typescript": "^3.5.5",
     "eslint-plugin-import": "2.26.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "jest": "^29.5.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "jest": "^29.6.1",
     "jest-circus": "^28.1.3",
     "jest-config": "^28.1.3",
     "jest-expect-message": "^1.1.3",
-    "lerna": "^7.0.1",
-    "prettier": "^2.8.8",
+    "lerna": "^7.1.3",
+    "prettier": "^3.0.0",
     "standard-version": "^9.5.0",
     "ts-node": "^10.9.1",
     "typescript": "~4.7.4"

packages/@jsii/Directory.Build.targets

@@ -12,9 +12,9 @@
 
     <PackageReference Update="Microsoft.NET.Test.Sdk" Version="17.6.3" />
     <PackageReference Update="NSubstitute" Version="5.0.0" />
-    <PackageReference Update="xunit" Version="2.4.2" />
-    <PackageReference Update="xunit.runner.visualstudio" Version="2.4.5" />
-    <PackageReference Update="XunitXml.TestLogger" Version="3.0.78" />
+    <PackageReference Update="xunit" Version="2.5.0" />
+    <PackageReference Update="xunit.runner.visualstudio" Version="2.5.0" />
+    <PackageReference Update="XunitXml.TestLogger" Version="3.1.11" />
 
     <PackageReference Update="Newtonsoft.Json" Version="13.0.3" />
   </ItemGroup>

packages/@jsii/benchmarks/lib/benchmark.ts

@@ -66,7 +66,7 @@ export class Benchmark<C> {
   #profile = false;
 
   public constructor(private readonly name: string) {}
-  #setup: () => C | Promise<C> = () => ({} as C);
+  #setup: () => C | Promise<C> = () => ({}) as C;
   #subject: (ctx: C) => void | Promise<void> = () => undefined;
   #beforeEach: (ctx: C) => void | Promise<void> = () => undefined;
   #afterEach: (ctx: C) => void | Promise<void> = () => undefined;

packages/@jsii/benchmarks/package.json

@@ -14,7 +14,7 @@
   },
   "devDependencies": {
     "@types/glob": "^8.1.0",
-    "glob": "^10.2.7"
+    "glob": "^10.3.3"
   },
   "scripts": {
     "build": "yarn --silent tsc --build && npm run lint",

packages/@jsii/check-node/package.json

@@ -37,6 +37,6 @@
   },
   "dependencies": {
     "chalk": "^4.1.2",
-    "semver": "^7.5.1"
+    "semver": "^7.5.4"
   }
 }

packages/@jsii/dotnet-runtime/package.json

@@ -41,6 +41,6 @@
     "@jsii/runtime": "^0.0.0",
     "@types/semver": "^7.5.0",
     "jsii-build-tools": "^0.0.0",
-    "semver": "^7.5.1"
+    "semver": "^7.5.4"
   }
 }