Proposal: Token.toString()

[eladb]

References to runtime attributes of resources (the name of the bucket, the ARN of a topic, etc). At the moment, these are represented a Token objects. Tokens are objects that have a resolve method. When a stack is synthesized, every toke node in the JSON document is resolved and the result is plugged into the document.

One of the usability issues we are experiencing with tokens is that it is very common to need to format strings that reference them. For example:

const bucket = new s3.Bucket(this, 'MyBucket');
const rule = new cloudwatch.EventRule(this, 'Schedule', { scheduleExpression: 'rate(1 minute)' });
rule.addTarget(topic, {
  textTemplate: `Hello, bucket ${bucket.bucketName}`
});

Sadly, this code will not behave as expected. bucket.bucketName is an object of type BucketName, which extends Token, and not a string. The resulting string would be "Hello, bucket [Object]".

If we had a toString method for tokens, which would have been meaningful and substitutable during synthesis, the above code would behave as expected.

[rix0rrr]

At least it would help debuggability.

However, to make it do "the right thing" we'd need to change the context as well. We could make the Token stringify to ${Bucket}, but that would still require the containing string to be wrapped in a Fn::Sub.

As in, it would need to become this:

rule.addTarget(topic, {
  textTemplate: new FnSub(`Hello, bucket ${bucket.bucketName}`)
});

Still a pretty good addition because right now it's very inconvenient to use FnSub(), and this would go a long way towards making it "do the right thing" with zero extra effort. As a user, you wouldn't even know you were doing it wrong but we were fixing it for you :)

[eladb]

I would actually not use FnSub for the substitution but rather implement our own substitution scheme in resolve. It will give us way more flexibility. Also, we need to control when resolve is called on the token (which is during synthesis).

Here's some way we can implement this:

The first time a token is toStringed, we allocate a global key which maps to this object and return the key as a magic substitution. So, the above example "Hello, bucket ${bucket.bucketName}" will render to something like: Hello, bucket <<TOKEN#776#BucketName>>. Then during synthesis when we resolve(template), every time we see a string that contains /<<TOKEN#\d+#.+>>/ we go to the global map, find the object, call resolve on it and substitute the value.

[rix0rrr]

My point is, if it's a Token it most likely needs to resolve to a {Ref} or {Fn::GetAtt}. So do you plan to do wrapping of arbitrary strings in FnSub during resolve() to make those work?

Not saying it couldn't be done, but it might introduce some nasty edge cases.

[eladb]

Good point, but I would just use FnConcat(preString, resolvedToken, postString). This way we are not bound to substitutions supported by CloudFormation. resolvedToken can be anything.

[rix0rrr]

It would definitely be an interesting experiment.

Do we expose toString() through jsii? I guess the answer would have to be yes, right? And rename then appropriately for every jsii client language as well?