feat(tokens): enable type coercion

[eladb]

Relax restrictions on input types for Token.toXxx in order to allow flexible type coercion.

This may be needed in situations where users want to force a token typed as one type to be represented as another type and generally allow tokens to be used as "type-system escape hatches".

Previously, this did not work:

const port = new Token({ "Fn::GetAtt": [ "ResourceId", "Port" ] }).toString(); 
new TcpPort(new Token(port).toNumber());

Also, this did not work:

const port = new Token({ "Fn::GetAtt": [ "ResourceId", "Port" ]}).toNumber();

These were just examples. The point is that if a user reached the point where you actually need a token, they basically indicate to the framework that “I know what I am are doing”. It’s a sort of an “as any” at the framework level.

Fixes #2679

---

Pull Request Checklist

• Testing
  • Unit test added (prefer not to modify an existing test, otherwise, it's probably a breaking change)
  • CLI change?: coordinate update of integration tests with team
  • cdk-init template change?: coordinated update of integration tests with team
• Docs
  • jsdocs: All public APIs documented
  • README: README and/or documentation topic updated
  • Design: For significant features, design document added to design folder
• Title and Description
  • Change type: title prefixed with fix, feat and module name in parens, which will appear in changelog
  • Title: use lower-case and doesn't end with a period
  • Breaking?: last paragraph: "BREAKING CHANGE: <describe what changed + link for details>"
  • Issues: Indicate issues fixed via: "Fixes #xxx" or "Closes #xxx"
• Sensitive Modules (requires 2 PR approvers)
  • IAM Policy Document (in @aws-cdk/aws-iam)
  • EC2 Security Groups and ACLs (in @aws-cdk/aws-ec2)
  • Grant APIs (only if not based on official documentation with a reference)

---

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

[rix0rrr]

you need to instantiate a CfnReference instead of a Token.

[eladb]

you need to instantiate a CfnReference instead of a Token.

That was just an example. The point is that I think we don’t need to be defensive in Token.toXxxx methods. If you’ve reached the point where you actually need a token, you basically indicate to the framework that “you know what you are doing”. It’s a sort of an “as any” at the framework level.

[rix0rrr]

In my mind, there are 2 types of Tokens, both doing some kind of escape mechanism, but they're not the same escape mechanism:

• Represent CFN intrinsics. This bypasses the type system in that we have an opaque value that we want to use to represent a string, or whatever. Importantly: the intrinsic will ultimately render to an object structure, and there's no way for us to verify whether its declared type matches the actual (deploy-time) type.
• Represent laziness. This bypasses the type system in that we get a string value NOW, even though we will actually only have the actual string value available LATER. We could still do type validation on this, since we know (and can check) that the value returned at the LATER time is actually of type string.

I want to use different classes to represent different kinds of tokens, and so the code you wrote up there could not be written anymore (new Token({ Ref: "abc" }) will not be valid).

I'm okay to merge it now if you really want to, though.

[eladb]

@rix0rrr you are right that we are using tokens for those two use cases, and I am open to looking into differentiating these two use case using a higher-level API. Let's look into this as part of #1933, ok?

[mergify]

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

• PR title type(scope): text
  • type: fix, feat, refactor go into CHANGELOG, chore is hidden
  • scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
  • text: use all lower-case, do not end with a period, do not include issue refs
• PR Description
  • Rationale: describe rationale of change and approach taken
  • Issues: indicate issues fixed via: fixes #xxx or closes #xxx
  • Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
• Testing
  • Unit test added. Prefer to add a new test rather than modify existing tests
  • CLI or init templates change? Re-run/add CLI integration tests
• Documentation
  • README: update module README to describe new features
  • API docs: public APIs must be documented. Copy from official AWS docs when possible
  • Design: for significant features, follow design process