From 017f2507f622af1f13ebc2825ca01f42fa6c298d Mon Sep 17 00:00:00 2001 From: corymhall <43035978+corymhall@users.noreply.github.com> Date: Thu, 20 Feb 2025 06:05:54 -0500 Subject: [PATCH] Types incorrectly marked as @internal Types only need to be marked as `@internal` if they would be exported from the top level `index.ts` file, but you don't want them to. Marking something as `@internal` means they are stripped from the compiled type files and this causes type errors because some files will try to reference types that do not exist anymore. Example error when running `tsc` in a project where `@pulumi/cdk` is installed. ``` node_modules/@pulumi/cdk/lib/converters/app-converter.d.ts:6:10 - error TS2305: Module '"../interop"' has no exported member 'CdkConstruct'. 6 import { CdkConstruct } from '../interop'; ~~~~~~~~~~~~ ``` I've unmarked things as `@internal` that are not exported and moved some things to a new `interna/interop.ts` file that were in an exported file. Now that they are not in an exported file we don't have to mark them as `@internal` --- api-docs/Namespace.interop.md | 12 +++--- api-docs/README.md | 12 +++--- src/converters/app-converter.ts | 12 +----- src/converters/intrinsics.ts | 12 ------ src/internal/interop.ts | 76 +++++++++++++++++++++++++++++++++ src/interop.ts | 65 ---------------------------- src/output-map.ts | 8 ---- src/pulumi-metadata.ts | 2 - src/stack-map.ts | 2 - src/stack.ts | 2 +- src/synthesizer.ts | 2 +- src/types.ts | 3 +- 12 files changed, 94 insertions(+), 114 deletions(-) create mode 100644 src/internal/interop.ts diff --git a/api-docs/Namespace.interop.md b/api-docs/Namespace.interop.md index 450e71d2..b897cc67 100644 --- a/api-docs/Namespace.interop.md +++ b/api-docs/Namespace.interop.md @@ -21,8 +21,8 @@ attribute | Name | Type | Defined in | | ------ | ------ | ------ | -| `attributes`? | `object` | [interop.ts:88](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L88) | -| `resource` | `pulumi.Resource` | [interop.ts:87](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L87) | +| `attributes`? | `object` | [interop.ts:78](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L78) | +| `resource` | `pulumi.Resource` | [interop.ts:77](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L77) | #### Example @@ -37,7 +37,7 @@ return { #### Defined in -[interop.ts:86](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L86) +[interop.ts:76](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L76) *** @@ -49,7 +49,7 @@ Use this type if a single CFN resource maps to multiple AWS resources #### Defined in -[interop.ts:94](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L94) +[interop.ts:84](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L84) *** @@ -59,7 +59,7 @@ Use this type if a single CFN resource maps to multiple AWS resources #### Defined in -[interop.ts:96](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L96) +[interop.ts:86](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L86) ## Functions @@ -86,4 +86,4 @@ The normalized resource properties #### Defined in -[interop.ts:41](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L41) +[interop.ts:31](https://github.com/pulumi/pulumi-cdk/blob/main/src/interop.ts#L31) diff --git a/api-docs/README.md b/api-docs/README.md index 36af97fb..54f097d1 100644 --- a/api-docs/README.md +++ b/api-docs/README.md @@ -14,7 +14,7 @@ The Pulumi provider to read the schema from | Enumeration Member | Value | Defined in | | ------ | ------ | ------ | -| `AWS_NATIVE` | `"aws-native"` | [types.ts:62](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L62) | +| `AWS_NATIVE` | `"aws-native"` | [types.ts:63](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L63) | ## Classes @@ -194,7 +194,7 @@ AppComponent is the interface representing the Pulumi CDK App Component Resource | Property | Modifier | Type | Description | Defined in | | ------ | ------ | ------ | ------ | ------ | -| `name` | `readonly` | `string` | The name of the component | [types.ts:72](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L72) | +| `name` | `readonly` | `string` | The name of the component | [types.ts:73](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L73) | *** @@ -206,8 +206,8 @@ Options for creating a Pulumi CDK App Component | Property | Type | Description | Defined in | | ------ | ------ | ------ | ------ | -| `appId?` | `string` | A unique identifier for the application that the asset staging stack belongs to. This identifier will be used in the name of staging resources created for this application, and should be unique across apps. The identifier should include lowercase characters, numbers, periods (.) and dashes ('-') only and have a maximum of 17 characters. **Default** `- generated from the pulumi project and stack name` | [types.ts:25](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L25) | -| `props?` | `AppProps` | Specify the CDK Stack properties to asociate with the stack. | [types.ts:12](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L12) | +| `appId?` | `string` | A unique identifier for the application that the asset staging stack belongs to. This identifier will be used in the name of staging resources created for this application, and should be unique across apps. The identifier should include lowercase characters, numbers, periods (.) and dashes ('-') only and have a maximum of 17 characters. **Default** `- generated from the pulumi project and stack name` | [types.ts:26](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L26) | +| `props?` | `AppProps` | Specify the CDK Stack properties to asociate with the stack. | [types.ts:13](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L13) | #### Methods @@ -240,7 +240,7 @@ implemented. ###### Defined in -[types.ts:42](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L42) +[types.ts:43](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L43) *** @@ -256,7 +256,7 @@ Options specific to the Pulumi CDK App component. | Property | Type | Defined in | | ------ | ------ | ------ | -| `appOptions?` | [`AppOptions`](README.md#appoptions) | [types.ts:54](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L54) | +| `appOptions?` | [`AppOptions`](README.md#appoptions) | [types.ts:55](https://github.com/pulumi/pulumi-cdk/blob/main/src/types.ts#L55) | *** diff --git a/src/converters/app-converter.ts b/src/converters/app-converter.ts index 97628297..5b11b1a0 100644 --- a/src/converters/app-converter.ts +++ b/src/converters/app-converter.ts @@ -5,13 +5,7 @@ import { AssemblyManifestReader, StackAddress, StackManifest } from '../assembly import { ConstructInfo, Graph, GraphBuilder, GraphNode } from '../graph'; import { ArtifactConverter } from './artifact-converter'; import { lift, Mapping, AppComponent, CdkAdapterError } from '../types'; -import { - CdkConstruct, - NestedStackConstruct, - ResourceAttributeMapping, - ResourceMapping, - resourcesFromResourceMapping, -} from '../interop'; +import { ResourceAttributeMapping, ResourceMapping } from '../interop'; import { debug, warn } from '@pulumi/pulumi/log'; import { cidr, @@ -36,6 +30,7 @@ import { PulumiProvider } from '../types'; import { parseDynamicValue } from './dynamic-references'; import { StackMap } from '../stack-map'; import { NestedStackParameter } from './intrinsics'; +import { CdkConstruct, NestedStackConstruct, resourcesFromResourceMapping } from '../internal/interop'; /** * AppConverter will convert all CDK resources into Pulumi resources. @@ -545,9 +540,6 @@ export class StackConverter extends ArtifactConverter implements intrinsics.Intr return obj?.Ref === 'AWS::NoValue'; } - /** - * @internal - */ public resolveOutput(repr: OutputRepr): pulumi.Output { const result = OutputMap.instance().lookupOutput(repr); if (result === undefined) { diff --git a/src/converters/intrinsics.ts b/src/converters/intrinsics.ts index 8b05983a..a291bf63 100644 --- a/src/converters/intrinsics.ts +++ b/src/converters/intrinsics.ts @@ -30,8 +30,6 @@ import { StackAddress } from '../assembly'; * synthesized CF template. * * See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html - * - * @internal */ export interface Intrinsic { /** @@ -56,24 +54,18 @@ export interface Intrinsic { * See also CfnParse for inspiration: * * https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/core/lib/helpers-internal/cfn-parse.ts#L347 - * - * @internal */ export interface Expression {} /** * Production code may have intermediate values occasionally wrapped in pulumi.Output; this is currently somewhat * difficult to test, so the essentials of pulumi.Output are abstracted into a Result. - * - * @internal */ // eslint-disable-next-line export interface Result {} /** * A nested stack parameter is a parameter that is defined in a nested stack and configured in the parent stack. - * - * @internal */ export interface NestedStackParameter { expression: Expression; @@ -85,8 +77,6 @@ export interface NestedStackParameter { * * Note that `succeed`, `fail`, `apply` and `Result` expressions are abstracting the use of `pulumi.Input` to facilitate * testing over a simpler structure without dealing with async evaluation. - * - * @internal */ export interface IntrinsicContext { /** @@ -179,8 +169,6 @@ export interface IntrinsicContext { * "Fn::If": [condition_name, value_if_true, value_if_false] * * https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-i - * - * @internal */ export const fnIf: Intrinsic = { name: 'Fn::If', diff --git a/src/internal/interop.ts b/src/internal/interop.ts new file mode 100644 index 00000000..1036bebb --- /dev/null +++ b/src/internal/interop.ts @@ -0,0 +1,76 @@ +// Copyright 2016-2024, Pulumi Corporation. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +import * as pulumi from '@pulumi/pulumi'; +import { PulumiResourceType } from '../graph'; +import { ResourceMapping } from '../interop'; + +export function firstToLower(str: string) { + return str.replace(/\w\S*/g, function (txt) { + return txt.charAt(0).toLowerCase() + txt.substring(1); + }); +} + +/** + * extract a list of pulumi resources from a ResourceMapping + */ +export function resourcesFromResourceMapping(mapping: ResourceMapping): pulumi.Resource[] { + if (Array.isArray(mapping)) { + return mapping.map((m) => m.resource); + } else if (pulumi.Resource.isInstance(mapping)) { + return [mapping]; + } else { + return [mapping.resource]; + } +} + +/** + * @hidden + */ +export class CdkConstruct extends pulumi.ComponentResource { + constructor(public readonly name: PulumiResourceType, type?: string, options?: pulumi.ComponentResourceOptions) { + const constructType = type ?? 'Construct'; + const constructName = name; + + super(`cdk:construct:${constructType}`, constructName, {}, options); + } + + public done() { + this.registerOutputs({}); + } +} + +const NESTED_STACK_CONSTRUCT_SYMBOL = Symbol.for('@pulumi/cdk.NestedStackConstruct'); + +/** + * The NestedStackConstruct is a special construct that is used to represent a nested stack + * and namespace the resources within it. It achieves this by including the stack path in the + * resource type. + */ +export class NestedStackConstruct extends pulumi.ComponentResource { + /** + * Return whether the given object is a NestedStackConstruct. + * + * We do attribute detection in order to reliably detect nested stack constructs. + * @internal + */ + public static isNestedStackConstruct(x: any): x is NestedStackConstruct { + return x !== null && typeof x === 'object' && NESTED_STACK_CONSTRUCT_SYMBOL in x; + } + + constructor(stackPath: string, options?: pulumi.ComponentResourceOptions) { + super(`cdk:construct:nested-stack/${stackPath}`, stackPath, {}, options); + Object.defineProperty(this, NESTED_STACK_CONSTRUCT_SYMBOL, { value: true }); + } +} diff --git a/src/interop.ts b/src/interop.ts index a81b636e..364571f8 100644 --- a/src/interop.ts +++ b/src/interop.ts @@ -16,16 +16,6 @@ import * as pulumi from '@pulumi/pulumi'; import { normalizeObject } from './pulumi-metadata'; import { toSdkName } from './naming'; import { PulumiProvider } from './types'; -import { PulumiResourceType } from './graph'; - -/** - * @internal - */ -export function firstToLower(str: string) { - return str.replace(/\w\S*/g, function (txt) { - return txt.charAt(0).toLowerCase() + txt.substring(1); - }); -} /** * normalize will take the resource properties for a specific CloudFormation resource and @@ -94,58 +84,3 @@ export type ResourceAttributeMapping = { export type ResourceAttributeMappingArray = (ResourceAttributeMapping & { logicalId: string })[]; export type ResourceMapping = ResourceAttributeMapping | pulumi.Resource | ResourceAttributeMappingArray; - -/** - * extract a list of pulumi resources from a ResourceMapping - * @internal - */ -export function resourcesFromResourceMapping(mapping: ResourceMapping): pulumi.Resource[] { - if (Array.isArray(mapping)) { - return mapping.map((m) => m.resource); - } else if (pulumi.Resource.isInstance(mapping)) { - return [mapping]; - } else { - return [mapping.resource]; - } -} - -/** - * @internal - */ -export class CdkConstruct extends pulumi.ComponentResource { - constructor(public readonly name: PulumiResourceType, type?: string, options?: pulumi.ComponentResourceOptions) { - const constructType = type ?? 'Construct'; - const constructName = name; - - super(`cdk:construct:${constructType}`, constructName, {}, options); - } - - public done() { - this.registerOutputs({}); - } -} - -const NESTED_STACK_CONSTRUCT_SYMBOL = Symbol.for('@pulumi/cdk.NestedStackConstruct'); - -/** - * The NestedStackConstruct is a special construct that is used to represent a nested stack - * and namespace the resources within it. It achieves this by including the stack path in the - * resource type. - * @internal - */ -export class NestedStackConstruct extends pulumi.ComponentResource { - /** - * Return whether the given object is a NestedStackConstruct. - * - * We do attribute detection in order to reliably detect nested stack constructs. - * @internal - */ - public static isNestedStackConstruct(x: any): x is NestedStackConstruct { - return x !== null && typeof x === 'object' && NESTED_STACK_CONSTRUCT_SYMBOL in x; - } - - constructor(stackPath: string, options?: pulumi.ComponentResourceOptions) { - super(`cdk:construct:nested-stack/${stackPath}`, stackPath, {}, options); - Object.defineProperty(this, NESTED_STACK_CONSTRUCT_SYMBOL, { value: true }); - } -} diff --git a/src/output-map.ts b/src/output-map.ts index f3d25a6e..f55a0bf6 100644 --- a/src/output-map.ts +++ b/src/output-map.ts @@ -17,8 +17,6 @@ const glob = global as any; /** * A serializable reference to an output. - * - * @internal */ export interface OutputRef { /** @@ -31,8 +29,6 @@ export interface OutputRef { /** * See `OutputRef`. - * - * @internal */ export interface OutputRepr { /** @@ -43,8 +39,6 @@ export interface OutputRepr { /** * Recognize if something is an `OutputRepr`. - * - * @internal */ export function isOutputReprInstance(x: any): boolean { return typeof x === 'object' && Object.prototype.hasOwnProperty.call(x, 'PulumiOutput'); @@ -53,8 +47,6 @@ export function isOutputReprInstance(x: any): boolean { /** * Stores Pulumi Output values in memory so that they can be encoded into serializable `OutputRef` values with unique * integers for CDK interop. - * - * @internal */ export class OutputMap { /** diff --git a/src/pulumi-metadata.ts b/src/pulumi-metadata.ts index 59292b97..f2f505ee 100644 --- a/src/pulumi-metadata.ts +++ b/src/pulumi-metadata.ts @@ -142,8 +142,6 @@ export interface PulumiResource { /** * Metadata predicting the behavior of CF Ref intrinsic for a given resource. - * - * @internal */ export interface CfRefBehavior { /** diff --git a/src/stack-map.ts b/src/stack-map.ts index d6d22f3b..c982a03d 100644 --- a/src/stack-map.ts +++ b/src/stack-map.ts @@ -19,8 +19,6 @@ import { StackAddress } from './assembly'; * It internally uses nested maps to store values by stackPath and id. * * @typeparam T The type of values stored in the map - * - * @internal */ export class StackMap implements Map { // Map of stackPath -> Map of id -> value diff --git a/src/stack.ts b/src/stack.ts index 24bae4e6..7696c99f 100644 --- a/src/stack.ts +++ b/src/stack.ts @@ -18,7 +18,7 @@ import { AppComponent, AppOptions, AppResourceOptions, CdkAdapterError } from '. import { AppConverter, StackConverter } from './converters/app-converter'; import { PulumiSynthesizer, PulumiSynthesizerBase } from './synthesizer'; import { AwsCdkCli, ICloudAssemblyDirectoryProducer } from '@aws-cdk/cli-lib-alpha'; -import { CdkConstruct } from './interop'; +import { CdkConstruct } from './internal/interop'; import { makeUniqueId } from './cdk-logical-id'; import * as native from '@pulumi/aws-native'; import { warn } from '@pulumi/pulumi/log'; diff --git a/src/synthesizer.ts b/src/synthesizer.ts index 575ea280..985043e3 100644 --- a/src/synthesizer.ts +++ b/src/synthesizer.ts @@ -6,7 +6,7 @@ import * as ccapi from '@pulumi/aws-native'; import * as cdk from 'aws-cdk-lib/core'; import { translateCfnTokenToAssetToken } from 'aws-cdk-lib/core/lib/helpers-internal'; import * as aws from '@pulumi/aws'; -import { CdkConstruct } from './interop'; +import { CdkConstruct } from './internal/interop'; import { zipDirectory } from './zip'; import { asString } from './output'; import { CdkAdapterError } from './types'; diff --git a/src/types.ts b/src/types.ts index 35e5163c..cab8398d 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,6 +1,7 @@ import * as pulumi from '@pulumi/pulumi'; import { Stack, AppProps } from 'aws-cdk-lib/core'; -import { CdkConstruct, ResourceMapping } from './interop'; +import { ResourceMapping } from './interop'; +import { CdkConstruct } from './internal/interop'; /** * Options for creating a Pulumi CDK App Component