feat(tokens): enable type coercion

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();

Fixes #2679

packages/@aws-cdk/cdk/lib/token.ts

@@ -93,16 +93,16 @@ export class Token {
  * on the string.
  */
  public toString(): string {
- const valueType = typeof this.valueOrFunction;
  // Optimization: if we can immediately resolve this, don't bother
- // registering a Token.
- if (valueType === 'string' || valueType === 'number' || valueType === 'boolean') {
- return this.valueOrFunction.toString();
+ // registering a Token (unless it's already a token).
+ if (typeof(this.valueOrFunction) === 'string') {
+ return this.valueOrFunction;
  }
 
  if (this.tokenStringification === undefined) {
  this.tokenStringification = TokenMap.instance().registerString(this, this.displayName);
  }
+
  return this.tokenStringification;
  }
 
@@ -139,9 +139,8 @@ export class Token {
  * is constructing a `FnJoin` or a `FnSelect` on it.
  */
  public toList(): string[] {
- const valueType = typeof this.valueOrFunction;
- if (valueType === 'string' || valueType === 'number' || valueType === 'boolean') {
- throw this.newError('Got a literal Token value; only intrinsics can ever evaluate to lists.');
+ if (Array.isArray(this.valueOrFunction)) {
+ return this.valueOrFunction;
  }
 
  if (this.tokenListification === undefined) {
@@ -160,14 +159,13 @@ export class Token {
  * other operations can and probably will destroy the token-ness of the value.
  */
  public toNumber(): number {
+ // Optimization: if we can immediately resolve this, don't bother
+ // registering a Token.
+ if (typeof(this.valueOrFunction) === 'number') {
+ return this.valueOrFunction;
+ }
+
  if (this.tokenNumberification === undefined) {
- const valueType = typeof this.valueOrFunction;
- // Optimization: if we can immediately resolve this, don't bother
- // registering a Token.
- if (valueType === 'number') { return this.valueOrFunction; }
- if (valueType !== 'function') {
- throw this.newError(`Token value is not number or lazy, can't represent as number: ${this.valueOrFunction}`);
- }
  this.tokenNumberification = TokenMap.instance().registerNumber(this);
  }
 

packages/@aws-cdk/cdk/test/test.tokens.ts

@@ -3,6 +3,7 @@ import { App as Root, findTokens, Fn, Stack, Token } from '../lib';
 import { createTokenDouble, extractTokenDouble } from '../lib/encoding';
 import { TokenMap } from '../lib/token-map';
 import { evaluateCFN } from './evaluate-cfn';
+import { func } from 'fast-check/*';
 
 export = {
  'resolve a plain old object should just return the object'(test: Test) {
@@ -467,15 +468,14 @@ export = {
 
  'can number-encode and resolve Token objects'(test: Test) {
  // GIVEN
- const stack = new Stack();
  const x = new Token(() => 123);
 
  // THEN
  const encoded = x.toNumber();
  test.equal(true, Token.isToken(encoded), 'encoded number does not test as token');
 
  // THEN
- const resolved = stack.node.resolve({ value: encoded });
+ const resolved = resolve({ value: encoded });
  test.deepEqual(resolved, { value: 123 });
 
  test.done();
@@ -522,6 +522,91 @@ export = {
  const token = fn1();
  test.throws(() => token.throwError('message!'), /Token created:/);
  test.done();
+ },
+
+ 'type coercion': (() => {
+ const tests: any = { };
+
+ const inputs = [
+ () => 'lazy',
+ 'a string',
+ 1234,
+ { an_object: 1234 },
+ [ 1, 2, 3 ],
+ false
+ ];
+
+ for (const input of inputs) {
+ // GIVEN
+ const stringToken = new Token(input).toString();
+ const numberToken = new Token(input).toNumber();
+ const listToken = new Token(input).toList();
+
+ // THEN
+ const expected = typeof(input) === 'function' ? input() : input;
+
+ tests[`${input}<string>.toNumber()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(stringToken).toNumber()), expected);
+ test.done();
+ };
+
+ tests[`${input}<list>.toNumber()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(listToken).toNumber()), expected);
+ test.done();
+ };
+
+ tests[`${input}<number>.toNumber()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(numberToken).toNumber()), expected);
+ test.done();
+ };
+
+ tests[`${input}<string>.toString()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(stringToken).toString()), expected);
+ test.done();
+ };
+
+ tests[`${input}<list>.toString()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(listToken).toString()), expected);
+ test.done();
+ };
+
+ tests[`${input}<number>.toString()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(numberToken).toString()), expected);
+ test.done();
+ };
+
+ tests[`${input}<string>.toList()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(stringToken).toList()), expected);
+ test.done();
+ };
+
+ tests[`${input}<list>.toList()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(listToken).toList()), expected);
+ test.done();
+ };
+
+ tests[`${input}<number>.toList()`] = (test: Test) => {
+ test.deepEqual(resolve(new Token(numberToken).toList()), expected);
+ test.done();
+ };
+ }
+
+ return tests;
+ })(),
+
+ 'toXxx short circuts if the input is of the same type': {
+ 'toNumber(number)'(test: Test) {
+ test.deepEqual(new Token(123).toNumber(), 123);
+ test.done();
+ },
+ 'toList(list)'(test: Test) {
+ test.deepEqual(new Token([1, 2, 3]).toList(), [1, 2, 3]);
+ test.done();
+ },
+ 'toString(string)'(test: Test) {
+ test.deepEqual(new Token('string').toString(), 'string'),
+ test.done();
+ }
  }
 };