Tokens: be able to represent as numbers

[eladb]

We are able to represent tokens as strings (token.toString()) and as string arrays (token.toList()), but in certain cases, there's a need to represent them as numbers. Introduce token.toNumber().

We need to somehow encode the fact that this is a token into a number. It's not going to be elegant (e.g. -66737346654.<random> can be the key to the token map).

Related to #744
Related to #1453

[rix0rrr]

Agreed. This requires VERY careful thought and testing at the jsii serialization border. For example, numbers are PROBABLY represented as doubles in jsii client languages, but now they HAVE to be or we'll lose bits that we use to encode a token number. Also, our stringification and parsing on both sides shouldn't lose any precision and be reversible in all languages.

My original (most future-proofed) idea was to store the token identifier in the unused bits of a NaN, but that definitely requires additional JSII implementation effort on both sides (to detect the case of special NaNs, extract and transport the hidden bits explicitly, on both sides), so just picking a decimal number that "just" happens to stringify and parse correctly may be a more expedient solution.

[rix0rrr]

We could for example say that a sign of 1 and an exponent of 00000000001 means a Token and then we have 53 bits left to store a Token number in. That would mean we take a range of very very small negative numbers out of commission, which seems okay to lose.

[rix0rrr]

Use case: @mipearson for example wants to use a CloudFormation parameter as the input to minSize and maxSize of an AutoScalingGroup.

This would also require changing the source of ASG to check for "real" values and only do the validation then.

[mipearson]

This would also require changing the source of ASG to check for "real" values and only do the validation then.

So .. this isn't a real use case, so much as something I thought would work but didn't.

I was working out how to integrate CDK with existing tooling that can use external tools to compile CFN templates. What I ended up doing instead was using that tool's "compile time parameters" feature to pass the parameters in via JSON to javascript.

IMO properly supporting this use case would complicate most constructs - what I'd prefer is that the construct instead insist on "real" values and throw a descriptive error if it's passed references when it can't work with them.

[mipearson]

In my own code I'm going to be optimising for providers instead and writing my own - eg if minSize needs to be dynamic, write a provider to pull that value from the relevant source so that it's available at synth time and cached in the context.

[rix0rrr]

IMO properly supporting this use case would complicate most constructs

Sure, but I think we can add some utilities to make this easier to write for TypeScript construct authors. Something like:

cdk.validate(props.minSize, props.maxSize, (minSize, maxSize) => {
  // Callback only executed if neither minSize nor maxSize are unresolved
  if (!(minSize <= maxSize)) {
    throw new Error('...');
  }
});

Or even this:

cdk.validate('minSize should be <= maxSize', props.minSize, props.maxSize, (minSize, maxSize) =>minSize <= maxSize);
});

// Will throw something like:
// "minSize should be <= maxSize, got: 23, 5"

[eladb]

This does bring up a more general concern around input validation which exists not only for numbers and I suspect we are violating already in a few places.

[rix0rrr]

var buf = new ArrayBuffer(8);
var bytes = new Uint8Array(buf);

// IEEE double in LE
// [mmmmmmm][mmmmmmm][mmmmmmm][mmmmmmm][mmmmmmm][mmmmmmm][eeeeemm][Seeeeee]
// \------------------- mantissa 52 bits ------------------/\----expo---/^sign

bytes[7] = 0x80;
bytes[6] = 0x04;
bytes[5] = 0x01;

const f = (new Float64Array(buf))[0];
const fs = JSON.stringify(f);
console.log(fs);
g = JSON.parse(fs);

console.log(f == g);

-5.568116955492875e-309
true

[rix0rrr]

Java:

    Double f = Double.parseDouble("-5.568116955492875e-309");    
    System.out.println(f);

-5.568116955492875E-309

[rix0rrr]

Python

>>> json.dumps(json.loads("-5.568116955492875E-309"))
'-5.568116955492875e-309'

[rix0rrr]

A finite binary number can never need an infinite decimal representation, says someone smarter than me on StackExchange:

https://math.stackexchange.com/questions/261988/number-with-finite-binary-representation-and-infinite-decimal-representation

[rix0rrr]

By the way, I just realized something. We should make the number VERY LARGE as opposed to VERY SMALL, so that if users manipulate it by accident it'll reduce the opportunity for it to break the token:

tiny_token + 1 === 1
huge_token + 1 === huge_token