feat: enable Go generics for jsii Go CDK code

[a-h]

Current situation

In Go, strings are not nullable by default like they are in TypeScript, C# etc.

There's also no pointer literal - you can't do something like &("string value") to create a pointer to a string literal, it's required to create a variable instead.

While there's discussion on having something built into the language in golang/go#45624 it hasn't concluded with a built-in as part of the language, or a standard library function.

The Go JSII library has worked around this by using the approach of creating functions that turn literals and variables into a pointer. Since Go < 1.18 didn't support generics, there's one for each supported JSII type. This means that you have to think about the type of any variables and use the right conversion function, while you're writing code.

stringPtr := jsii.String("literal value")
float64Ptr := jsii.Number(123.45)

Proposal

In Go 1.18, generics were added. These type parameters can be used to provide a single function that convert literals and variables into a pointer.

func Ptr[T any](v T) *T {
	return &v
} 

We can further restrict the allowed types of T by using a constraint.

type Type interface {
	bool | string | float64 | time.Time
}

func Ptr[T Type](v T) *T {
	return &v
}

If we adopt the name V instead of Ptr to save a further two characters (I'd still be happy with Ptr, Val etc. as a name), the previous example can be rewritten as:

stringPtr := jsii.V("literal value")
float64Ptr := jsii.V(123.45)
boolPtr := jsii.V(true)

This means that only one function is used to convert multiple types, and the function name can be a few characters shorter.

For the V function, integer literals can not be converted to float64, since the output would be a pointer to the input type, not to the allowed float64 type. Developers would be prompted that integer types are not in the set of allowed types (string, float64, bool, time.Time).

However, the Number function can be updated in place to use generics to accept any numeric type, which simplifies code that uses integer values from:

intPtrOK := jsii.Number(float64(123))
var x uint32
intPtrOK = jsii.Number(float64(x))

intPtrOK := jsii.Number(123) // Would automatically be converted to `float64`
var x uint32
intPtrOK = jsii.Number(x)

Impact

Since Go 1.18 is already required by the CDK, the use of generics is possible.

For backwards compatibility with existing code, the existing functions would be maintained, so no code would break.

Before

// DynamoDB.
slotMachineTable := awsdynamodb.NewTable(stack, jsii.String("slotMachineTable"), &awsdynamodb.TableProps{
	TableName:    jsii.String("slotMachine"),
	PartitionKey: &awsdynamodb.Attribute{Name: jsii.String("_pk"), Type: awsdynamodb.AttributeType_STRING},
	SortKey:      &awsdynamodb.Attribute{Name: jsii.String("_sk"), Type: awsdynamodb.AttributeType_STRING},
	BillingMode:  awsdynamodb.BillingMode_PAY_PER_REQUEST,
	Stream:       awsdynamodb.StreamViewType_NEW_IMAGE,
})

// Create an event bus.
eventBus := awsevents.NewEventBus(stack, jsii.String("slotMachineEventBus"), &awsevents.EventBusProps{
	EventBusName: jsii.String("slotMachineEventBus"),
})

// Process streams.
streamHandler := awslambdago.NewGoFunction(stack, jsii.String("streamHandler"), &awslambdago.GoFunctionProps{
	Runtime:      awslambda.Runtime_PROVIDED_AL2(),
	Architecture: awslambda.Architecture_ARM_64(),
	Entry:        jsii.String("../api/streamhandler/"),
	Environment: &map[string]*string{
		"EVENT_BUS_NAME":    eventBus.EventBusName(),
		"EVENT_SOURCE_NAME": jsii.String("slot-machine"),
	},
	Timeout:      awscdk.Duration_Minutes(jsii.Number(15)),
	LogRetention: awslogs.RetentionDays_ONE_YEAR,
})
slotMachineTable.GrantReadData(streamHandler)
eventBus.GrantPutEventsTo(streamHandler)

After

// DynamoDB.
slotMachineTable := awsdynamodb.NewTable(stack, jsii.V("slotMachineTable"), &awsdynamodb.TableProps{
	TableName:    jsii.V("slotMachine"),
	PartitionKey: &awsdynamodb.Attribute{Name: jsii.V("_pk"), Type: awsdynamodb.AttributeType_STRING},
	SortKey:      &awsdynamodb.Attribute{Name: jsii.V("_sk"), Type: awsdynamodb.AttributeType_STRING},
	BillingMode:  awsdynamodb.BillingMode_PAY_PER_REQUEST,
	Stream:       awsdynamodb.StreamViewType_NEW_IMAGE,
})

// Create an event bus.
eventBus := awsevents.NewEventBus(stack, jsii.V("slotMachineEventBus"), &awsevents.EventBusProps{
	EventBusName: jsii.V("slotMachineEventBus"),
})

// Process streams.
streamHandler := awslambdago.NewGoFunction(stack, jsii.V("streamHandler"), &awslambdago.GoFunctionProps{
	Runtime:      awslambda.Runtime_PROVIDED_AL2(),
	Architecture: awslambda.Architecture_ARM_64(),
	Entry:        jsii.V("../api/streamhandler/"),
	Environment: &map[string]*string{
		"EVENT_BUS_NAME":    eventBus.EventBusName(),
		"EVENT_SOURCE_NAME": jsii.V("slot-machine"),
	},
	Timeout:      awscdk.Duration_Minutes(jsii.V(15.0)),
	LogRetention: awslogs.RetentionDays_ONE_YEAR,
})
slotMachineTable.GrantReadData(streamHandler)
eventBus.GrantPutEventsTo(streamHandler)

Considerations

The name V is the shortest, but doesn't describe what it does.

The Go team might, at some point, introduce a change to automatically convert literals into pointers, in which case the jsii.V and jsii.String function calls would be redundant and could be stripped out of a codebase. However, this change doesn't make that potential outcome any worse.

---

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

Pull request has been modified.

[mergify]

Thank you for contributing! ❤️ I will now look into making sure the PR is up-to-date, then proceed to try and merge it!

[mergify]

Merging (with squash)...

[mergify]

Merging (with squash)...