aws / aws/jsii

Type definitions that only exist in TypeScript (don't get translated)

Open
#2,886 3 comments 1 reaction 1 assignee Claimed by @RomainMuller View on GitHub
feature-request language/typescript p1
Dominant language
TypeScript
Stars
2.9k
Forks
267
Avg merge
1d 25m
Merged PRs (30d)
14

Description

## :rocket: Feature Request

### Affected Languages

- [x] `TypeScript` or `Javascript`
- [ ] `Python`
- [ ] `Java`
- [ ] .NET (`C#`, `F#`, ...)
- [ ] `Go`

### Description

Here's a funky feature request:

**Type definitions that stay in TypeScript, and don't get translated by jsii**

In other languages, we would translate them like `any`.

Motivating example here is a CodeBuild buildspec: https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html

We'd like to type this structure so that we can model it and type-check it in TypeScript:

```ts
BuildSpec.fromObject({
phasse: { // <---- ERROR! TYPO!
// ...
}
})
```

### FAQ

#### Why can't it just be a regular type definition?

Well, there are funky fields in there that probably don't play well with jsii and translation. Example:

![image](https://user-images.githubusercontent.com/524162/122788411-99bb4580-d2b6-11eb-986d-66681fbd1f6c.png)

JSII wouldn't like these field names. Yet, they are what they are and we cannot change them.

#### Why can't you just re-model everything and fix the names?

Well we could, but:

1. We can't change it in-place:
* It would be backwards breaking (so that's already right out the door); but also
* Users would lose the ability to copy/paste an existing JSON blob into their code, and it's pretty important to be able to do that.
2. We could add a new constructor, so we have `BuildSpec.fromObject(object: any)` and `BuildSpec.fromBuildSpec(spec: BuildSpecProps)`.
* However, now it will be confusing to casual users which one they would want, and they might accidentally copy/paste snippets meant for `BuildSpec.fromBuildSpec()` into `BuildSpec.fromObject()`, which will happily type check but not do what they want.

### Proposed Solution

I feel a good additional feature to jsii (which would allow us to add reasonable type checking for TS users ), would be to have a feature like this:

```ts
/**
* Type definition only exists in TypeScript
*
* @nojsii
*/
export interface BuildSpecProps {
// ...
}

class BuildSpec {
// The following gets translated as if it were written as 'public static fromObject(object: any)'
public static fromObject(object: BuildSpecProps) {
}
}
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.