Giters

sam-goodwin / punchcard

Type-safe AWS infrastructure.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

`enumerable` is a bad name

sam-goodwin opened this issue · comments

commented

An enumerable is an infinite "stream" of data. Is it the wrong name?

Some alternatives:

  • Stream - the perfect name IMO, but problematic because it collides with a Kinesis Stream.
    • Maybe CloudStream?
    • Maybe rename the Kinesis Stream to KinesisStream?
  • EventSource - enumerables are built on AWS's event sources, so this kinda makes sense, but does it make sense for chains (map, flatMap, filter, etc.)?
  • Traversable - borrowed from scala's library. It sounds wrong because we're not traversing anything - we're responding to new data in an endless stream.
  • Iterable - does it collide with node.js standard library? Similarly to Traversable, the name doesn't perfectly represent a stream.

I'm leaning towards renaming Stream to KinesisStream and renaming Enumerable to Stream, but we then run into some consistency issues. We call SQS Queues Queue, and SNS Topics Topic - we don't include the service name. Is it weird to do that for Kinesis as an edge case? Based on feedback, we may also want to rename the Glue Table to GlueTable to avoid collisions with a DynamoDB Table, so those two issues align well.

Another option is to use namespaces:

  • Enumerable => Stream
  • Kinesis.Stream
  • SQS.Queue
  • Glue.Table
  • DynamoDB.Table

I like it because makes everything consistent, but is it a bit noisy?

commented

namespaces seems to be the way to go! if needed, can provide the TS interfaces inside them as well. not sure about the noisy part, both AWS SDK and CDK itself is namespaced like that, I don't see an issue IMHO. the name clashing will sure happen since everything is flattened in the index file

commented

I'm not opposed to the namespaces, but I was hoping to avoid them because Punchcard thinks of resources as data structures. Queue is a nicer name than SQS.Queue. But, given the amount of overlap in AWS, and the problem of enumerables, it is likely cleaner to be explicit and consistent.

Thoughts on prefix vs namespace? e.g. SQSQueue vs SQS.Queue. I've had problems with declaration merging and namespaces - not sure if we could construct a namespace from multiple files.

The CDK namespaces by module, not with TypeScript namespaces. E.g. @aws-cdk/aws-s3.Bucket vs require('aws-sdk').S3.

commented

Working on a PR (#26). Going ahead with the namespace approach for now - I think I can use module augmentation to build up namespaces across multiple files.