feat: intersection types (#2325)

This adds support for intersection types to the jsii compiler.

There are a number of restrictions to the use of intersection types:

- They can only appear in argument position, or in structs that are
exclusively used as the input to functions.
    - Not as return values of functions
    - Not in structs that are returned by functions
    - Not as arguments to constructors
    - Not as property types
- They must intersect only (behavioral) interface types.
    - Not structs
    - Not primitives
    - Not class types
- All shared members of interfaces that are intersected must have the
same types and arguments as each other.



---

By submitting this pull request, I confirm that my contribution is made
under the terms of the [Apache 2.0 license].

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>

Author: rix0rrr

package.json

@@ -11,7 +11,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { PackageJson, loadAssemblyFromPath, writeAssembly } from '@jsii/spec';
 import * as spec from '@jsii/spec';
-import { DiagnosticCategory } from 'typescript';
+import { Diagnostic, DiagnosticCategory } from 'typescript';
 
 import { Compiler, CompilerOptions } from './compiler';
 import { loadProjectInfo, ProjectInfo } from './project-info';
@@ -25,6 +25,11 @@ export type MultipleSourceFiles = {
   [name: string]: string;
 };
 
+/**
+ * Assembly features supported by this compiler
+ */
+export const ASSEMBLY_FEATURES_SUPPORTED: spec.JsiiFeature[] = ['intersection-types'];
+
 /**
  * Compile a piece of source and return the JSII assembly for it
  *
@@ -39,10 +44,24 @@ export function sourceToAssemblyHelper(
   source: string | MultipleSourceFiles,
   options?: TestCompilationOptions | ((obj: PackageJson) => void),
 ): spec.Assembly {
-  return compileJsiiForTest(source, options).assembly;
+  const result = compileJsiiForTest(source, options);
+  if (result.type !== 'success') {
+    throw new Error('Compilation failed');
+  }
+  return result.assembly;
 }
 
+export type HelperCompilationOut = HelperCompilationResult | HelperCompilationFailure;
+
+/**
+ * Successful output of a compilation command (for testing)
+ *
+ * A better name would have been `HelperCompilationSuccess`, but the name is part of
+ * the public API surface, so we keep it like this.
+ */
 export interface HelperCompilationResult {
+  readonly type: 'success';
+
   /**
    * The generated assembly
    */
@@ -62,6 +81,22 @@ export interface HelperCompilationResult {
    * Whether to compress the assembly file
    */
   readonly compressAssembly: boolean;
+
+  /**
+   * Diagnostics that occurred during compilation
+   */
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+export interface HelperCompilationFailure {
+  readonly type: 'failure';
+
+  /**
+   * Diagnostics that occurred during compilation
+   *
+   * Contains at least one error.
+   */
+  readonly diagnostics: readonly Diagnostic[];
 }
 
 /**
@@ -74,11 +109,11 @@ export interface HelperCompilationResult {
  * @param options accepts a callback for historical reasons but really expects to
  *                take an options object.
  */
-export function compileJsiiForTest(
+export function compileJsiiForTest<O extends TestCompilationOptions>(
   source: string | { 'index.ts': string; [name: string]: string },
-  options?: TestCompilationOptions | ((obj: PackageJson) => void),
+  options?: O | ((obj: PackageJson) => void),
   compilerOptions?: Omit<CompilerOptions, 'projectInfo' | 'watch'>,
-): HelperCompilationResult {
+): ResultOrSuccess<O> {
   if (typeof source === 'string') {
     source = { 'index.ts': source };
   }
@@ -108,14 +143,25 @@ export function compileJsiiForTest(
     const emitResult = compiler.emit();
 
     const errors = emitResult.diagnostics.filter((d) => d.category === DiagnosticCategory.Error);
-    for (const error of errors) {
-      console.error(formatDiagnostic(error, projectInfo.projectRoot));
-      // logDiagnostic() doesn't work out of the box, so console.error() it is.
+
+    if (typeof options !== 'object' || !options?.captureDiagnostics) {
+      for (const error of errors) {
+        console.error(formatDiagnostic(error, projectInfo.projectRoot));
+        // logDiagnostic() doesn't work out of the box, so console.error() it is.
+      }
     }
+
     if (errors.length > 0 || emitResult.emitSkipped) {
+      if (typeof options === 'object' && options?.captureDiagnostics) {
+        return {
+          type: 'failure',
+          diagnostics: emitResult.diagnostics,
+        } satisfies HelperCompilationFailure;
+      }
       throw new JsiiError('There were compiler errors');
     }
-    const assembly = loadAssemblyFromPath(process.cwd(), false);
+
+    const assembly = loadAssemblyFromPath(process.cwd(), false, ASSEMBLY_FEATURES_SUPPORTED);
     const files: Record<string, string> = {};
 
     for (const filename of Object.keys(source)) {
@@ -141,14 +187,20 @@ export function compileJsiiForTest(
     }
 
     return {
+      type: 'success',
       assembly,
       files,
       packageJson,
       compressAssembly: isOptionsObject(options) && options.compressAssembly ? true : false,
-    } as HelperCompilationResult;
-  });
+      diagnostics: emitResult.diagnostics,
+    } satisfies HelperCompilationResult;
+  }) as ResultOrSuccess<O>;
 }
 
+type ResultOrSuccess<O extends TestCompilationOptions> = O['captureDiagnostics'] extends true
+  ? HelperCompilationOut
+  : HelperCompilationResult;
+
 function inTempDir<T>(block: () => T): T {
   const origDir = process.cwd();
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsii'));
@@ -236,6 +288,13 @@ export interface TestCompilationOptions {
    * @default false
    */
   readonly compressAssembly?: boolean;
+
+  /**
+   * Whether or not to print the diagnostics
+   *
+   * @default false
+   */
+  readonly captureDiagnostics?: boolean;
 }
 
 function isOptionsObject(
@@ -278,7 +337,11 @@ export class TestWorkspace {
   /**
    * Add a test-compiled jsii assembly as a dependency
    */
-  public addDependency(dependencyAssembly: HelperCompilationResult) {
+  public addDependency(dependencyAssembly: HelperCompilationOut) {
+    if (dependencyAssembly.type !== 'success') {
+      throw new JsiiError('Cannot add dependency: assembly compilation failed');
+    }
+
     if (this.installed.has(dependencyAssembly.assembly.name)) {
       throw new JsiiError(
         `A dependency with name '${dependencyAssembly.assembly.name}' was already installed. Give one a different name.`,

src/assembler.ts

@@ -294,6 +294,37 @@ export class JsiiDiagnostic implements ts.Diagnostic {
     name: 'typescript-restriction/generic-type',
   });
 
+  public static readonly JSII_1007_NEVER_TYPE = Code.error({
+    code: 1007,
+    formatter: () => 'The "never" type is not allowed because it cannot be represented in target languages.',
+    name: 'typescript-restriction/no-never-type',
+  });
+
+  public static readonly JSII_1008_ONLY_INTERFACE_INTERSECTION = Code.error({
+    code: 1008,
+    formatter: (type: string) => `Found non-interface type in type intersection: ${type}`,
+    name: 'typescript-restriction/only-interface-intersection',
+  });
+
+  public static readonly JSII_1009_INTERSECTION_ONLY_INPUT = Code.error({
+    code: 1009,
+    formatter: (location: string) => `Intersection types may only be used as inputs, but ${location} is used as output`,
+    name: 'typescript-restriction/intersection-only-input',
+  });
+
+  public static readonly JSII_1010_INTERSECTION_NOT_IN_CTOR = Code.error({
+    code: 1010,
+    formatter: () => `Intersection types cannot be used as constructor arguments`,
+    name: 'typescript-restriction/intersection-no-ctor',
+  });
+
+  public static readonly JSII_1011_INTERSECTION_MEMBER_DIFFERENT = Code.error({
+    code: 1011,
+    formatter: (member: string, type1: string, reason1: string, type2: string, reason2: string) =>
+      `Member ${member} is different between types in a type intersection: ${type1} (${reason1}) and ${type2} (${reason2})`,
+    name: 'typescript-restriction/intersection-member-different',
+  });
+
   public static readonly JSII_1999_UNSUPPORTED = Code.error({
     code: 1999,
     formatter: ({

src/helpers.ts

@@ -7,6 +7,7 @@ import * as semver from 'semver';
 import * as ts from 'typescript';
 
 import { findDependencyDirectory } from './common/find-utils';
+import { ASSEMBLY_FEATURES_SUPPORTED } from './helpers';
 import { JsiiDiagnostic } from './jsii-diagnostic';
 import { TypeScriptConfigValidationRuleSet } from './tsconfig';
 import { JsiiError, parsePerson, parseRepository } from './utils';
@@ -392,7 +393,7 @@ class DependencyResolver {
       return this.cache.get(jsiiFile)!;
     }
 
-    const assembly = loadAssemblyFromFile(jsiiFile);
+    const assembly = loadAssemblyFromFile(jsiiFile, true, ASSEMBLY_FEATURES_SUPPORTED);
 
     // Continue loading any dependencies declared in the asm
     const resolvedDependencies = assembly.dependencies

src/jsii-diagnostic.ts

@@ -0,0 +1,39 @@
+export abstract class Sets {
+  /**
+   * Return the intersection of N sets
+   */
+  public static intersection<T>(...xss: Array<Set<T>>): Set<T> {
+    if (xss.length === 0) {
+      return new Set();
+    }
+    const ret = new Set(xss[0]);
+    for (const x of xss[0]) {
+      if (!xss.every((xs) => xs.has(x))) {
+        ret.delete(x);
+      }
+    }
+    return ret;
+  }
+
+  /**
+   * Return the union of N sets
+   */
+  public static union<T>(...xss: Array<Set<T>>): Set<T> {
+    return new Set(xss.flatMap((xs) => Array.from(xs)));
+  }
+
+  /**
+   * Return the diff of 2 sets
+   */
+  public static diff<T>(xs: Set<T>, ys: Set<T>) {
+    return new Set(Array.from(xs).filter((x) => !ys.has(x)));
+  }
+
+  public static *intersect<T>(xs: Set<T>, ys: Set<T>) {
+    for (const x of xs) {
+      if (ys.has(x)) {
+        yield x;
+      }
+    }
+  }
+}

src/project-info.ts

@@ -0,0 +1,55 @@
+import * as spec from '@jsii/spec';
+import { visitTypeReference } from './type-visitor';
+
+/**
+ * Convert a type reference to a string
+ */
+export function typeReferenceToString(x: spec.TypeReference): string {
+  return visitTypeReference<string>(x, {
+    named: function (ref: spec.NamedTypeReference) {
+      return ref.fqn;
+    },
+    primitive: function (ref: spec.PrimitiveTypeReference) {
+      return ref.primitive;
+    },
+    collection: function (ref: spec.CollectionTypeReference) {
+      return `${ref.collection.kind}<${typeReferenceToString(ref.collection.elementtype)}>`;
+    },
+    union: function (ref: spec.UnionTypeReference) {
+      return ref.union.types.map(typeReferenceToString).join(' | ');
+    },
+    intersection: function (ref: spec.IntersectionTypeReference) {
+      return ref.intersection.types.map(typeReferenceToString).join(' & ');
+    },
+  });
+}
+
+/**
+ * Return whether the given type references are equal
+ */
+export function typeReferenceEqual(a: spec.TypeReference, b: spec.TypeReference): boolean {
+  if (spec.isNamedTypeReference(a) && spec.isNamedTypeReference(b)) {
+    return a.fqn === b.fqn;
+  }
+  if (spec.isPrimitiveTypeReference(a) && spec.isPrimitiveTypeReference(b)) {
+    return a.primitive === b.primitive;
+  }
+  if (spec.isCollectionTypeReference(a) && spec.isCollectionTypeReference(b)) {
+    return (
+      a.collection.kind === b.collection.kind && typeReferenceEqual(a.collection.elementtype, b.collection.elementtype)
+    );
+  }
+  if (spec.isUnionTypeReference(a) && spec.isUnionTypeReference(b)) {
+    return (
+      a.union.types.length === b.union.types.length &&
+      a.union.types.every((aType, i) => typeReferenceEqual(aType, b.union.types[i]))
+    );
+  }
+  if (spec.isIntersectionTypeReference(a) && spec.isIntersectionTypeReference(b)) {
+    return (
+      a.intersection.types.length === b.intersection.types.length &&
+      a.intersection.types.every((aType, i) => typeReferenceEqual(aType, b.intersection.types[i]))
+    );
+  }
+  return false;
+}

src/sets.ts

@@ -0,0 +1,54 @@
+import * as spec from '@jsii/spec';
+
+export interface TypeReferenceVisitor<A = void> {
+  named(ref: spec.NamedTypeReference): A;
+  primitive(ref: spec.PrimitiveTypeReference): A;
+  collection(ref: spec.CollectionTypeReference): A;
+  union(ref: spec.UnionTypeReference): A;
+  intersection(ref: spec.IntersectionTypeReference): A;
+}
+
+export function visitTypeReference<A>(typeRef: spec.TypeReference, visitor: TypeReferenceVisitor<A>) {
+  if (spec.isNamedTypeReference(typeRef)) {
+    return visitor.named(typeRef);
+  } else if (spec.isPrimitiveTypeReference(typeRef)) {
+    return visitor.primitive(typeRef);
+  } else if (spec.isCollectionTypeReference(typeRef)) {
+    return visitor.collection(typeRef);
+  } else if (spec.isUnionTypeReference(typeRef)) {
+    return visitor.union(typeRef);
+  } else if (spec.isIntersectionTypeReference(typeRef)) {
+    return visitor.intersection(typeRef);
+  } else {
+    throw new Error(`Unknown type reference: ${JSON.stringify(typeRef)}`);
+  }
+}
+
+export interface TypeVisitor<A = void> {
+  classType(t: spec.ClassType): A;
+  interfaceType(t: spec.InterfaceType): A;
+  dataType(t: spec.InterfaceType): A;
+  enumType(t: spec.EnumType): A;
+}
+
+export function visitType<A>(t: spec.Type, visitor: TypeVisitor<A>) {
+  if (spec.isClassType(t)) {
+    return visitor.classType(t);
+  } else if (spec.isInterfaceType(t) && t.datatype) {
+    return visitor.dataType(t);
+  } else if (spec.isInterfaceType(t)) {
+    return visitor.interfaceType(t);
+  } else if (spec.isEnumType(t)) {
+    return visitor.enumType(t);
+  } else {
+    throw new Error(`Unknown type: ${JSON.stringify(t)}`);
+  }
+}
+
+export function isDataType(t: spec.Type): t is spec.InterfaceType {
+  return spec.isInterfaceType(t) && !!t.datatype;
+}
+
+export function isBehavioralInterfaceType(t: spec.Type): t is spec.InterfaceType {
+  return spec.isInterfaceType(t) && !t.datatype;
+}

src/type-reference.ts

@@ -1,15 +1,16 @@
 import { PrimitiveType, Type, TypeKind } from '@jsii/spec';
 import { sourceToAssemblyHelper } from '../lib';
+import { compileJsiiForErrors } from './compiler-helpers';
 
 // ----------------------------------------------------------------------
 test('Abstract member cant be marked async', () => {
-  expect(() =>
-    sourceToAssemblyHelper(`
+  expect(
+    compileJsiiForErrors(`
       export abstract class AbstractClass {
         public abstract async abstractMethod(): Promise<void>;
     }
     `),
-  ).toThrow(/There were compiler errors/);
+  ).toContainEqual(expect.stringMatching(/'async' modifier cannot be used with 'abstract' modifier/));
 });
 
 test('Abstract member can have a Promise<void> return type', () => {