Skip to content

Commit

Permalink
Types incorrectly marked as @internal
Browse files Browse the repository at this point in the history
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`
  • Loading branch information
corymhall committed Feb 20, 2025
1 parent 152957e commit 017f250
Show file tree
Hide file tree
Showing 12 changed files with 94 additions and 114 deletions.
12 changes: 6 additions & 6 deletions api-docs/Namespace.interop.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)

***

Expand All @@ -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)

***

Expand All @@ -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

Expand All @@ -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)
12 changes: 6 additions & 6 deletions api-docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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) |

***

Expand All @@ -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

Expand Down Expand Up @@ -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)

***

Expand All @@ -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) |

***

Expand Down
12 changes: 2 additions & 10 deletions src/converters/app-converter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -545,9 +540,6 @@ export class StackConverter extends ArtifactConverter implements intrinsics.Intr
return obj?.Ref === 'AWS::NoValue';
}

/**
* @internal
*/
public resolveOutput(repr: OutputRepr): pulumi.Output<any> {
const result = OutputMap.instance().lookupOutput(repr);
if (result === undefined) {
Expand Down
12 changes: 0 additions & 12 deletions src/converters/intrinsics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand All @@ -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<T>; this is currently somewhat
* difficult to test, so the essentials of pulumi.Output<T> are abstracted into a Result<T>.
*
* @internal
*/
// eslint-disable-next-line
export interface Result<T> {}

/**
* 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;
Expand All @@ -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 {
/**
Expand Down Expand Up @@ -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',
Expand Down
76 changes: 76 additions & 0 deletions src/internal/interop.ts
Original file line number Diff line number Diff line change
@@ -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 });
}
}
65 changes: 0 additions & 65 deletions src/interop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 });
}
}
8 changes: 0 additions & 8 deletions src/output-map.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ const glob = global as any;

/**
* A serializable reference to an output.
*
* @internal
*/
export interface OutputRef {
/**
Expand All @@ -31,8 +29,6 @@ export interface OutputRef {

/**
* See `OutputRef`.
*
* @internal
*/
export interface OutputRepr {
/**
Expand All @@ -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');
Expand All @@ -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 {
/**
Expand Down
2 changes: 0 additions & 2 deletions src/pulumi-metadata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,6 @@ export interface PulumiResource {

/**
* Metadata predicting the behavior of CF Ref intrinsic for a given resource.
*
* @internal
*/
export interface CfRefBehavior {
/**
Expand Down
2 changes: 0 additions & 2 deletions src/stack-map.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<T> implements Map<StackAddress, T> {
// Map of stackPath -> Map of id -> value
Expand Down
2 changes: 1 addition & 1 deletion src/stack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Loading

0 comments on commit 017f250

Please sign in to comment.