[1.0] Finalize CLI API

[jlengstorf]

Per the discussion that started on #4, we need to finalize the actual API of this tool. We know what it should do, but need to agree on how to actually expose the commands.

I'm porting the last comment from #4 to here:

@corycook @ecwyne To try and consolidate things, let me do a recap of where we are so far:

Cory’s Proposal

API

gramps [<datasource> [<datasource> ...]] [--live | --mock] [--gateway=<gateway>]

Examples

# run the current data source with the built-in dev server
gramps

# run the current data source with the built-in dev server in live mode
gramps --live

# run the current data source + an additional data source
gramps ./ ../otherSource

# run the current source + a custom gateway
gramps --gateway ../gateway

Additional Recommendation from Cory: Don’t Transpile

I'm personally against this because it's moving us further and further from a plug-and-play solution, but I'd be down to have an opt-out flag (e.g. gramps --no-transpile). A requirement to set up additional tools (e.g. concurrently) for dev seems like more overhead than is necessary. For advanced users, I think an opt-out is fine, but for someone who's new to this I think they should be able to just run gramps dev and see some data in GraphiQL.

Eric’s Proposal

API

gramps dev [<datasource> [<datasource> ...]] [--live | --mock]
gramps serve <gateway> [--override=<datasource> [--override=<datasource> ...]] [--live | --mock]

Examples

# run the current data source with the built-in dev server
gramps dev

# run the current data source with the built-in dev server in live mode
gramps dev --live

# run the current data source + an additional data source
gramps dev . ../otherSource

# run the current source + a custom gateway
gramps serve ../gateway --override ./

Jason’s Proposal

API

gramps dev [<gateway>] [--data-source=<datasource> [--data-source=<datasource> ...]] [--live | --mock] [--gateway=<gateway>]

Examples

# run the current data source with the built-in dev server
gramps dev --data-source .

# run the current data source with the built-in dev server in live mode
gramps dev --data-source . --live

# run the current data source + an additional data source
gramps dev --data-source . --data-source ../otherSource

# run the current source + a custom gateway
gramps dev ../gateway --data-source .

The Good Stuff

I think we've all got good ideas and good rationale behind them, so I want to see if I can walk through our main points of contention

Positional vs. Explicit Args

My preference is to remain explicit. Positional arguments are confusing to me, because it's not clear if ./one ./two is an input > output arg, or a "use both of these" arg. I think it's easier to reason about code that tells you what it does with descriptive options.

Command Name

I think @ecwyne had a great idea to change the command from gramps to something more clear: gramps dev. We may want to add new commands in the future (e.g. new data source creation), plus it makes it more obvious that this is only intended for development.

Pulling It All Together

Based on the three options, I've got two suggestions:

1. An API with named args (my preference)
2. An API with positional args

Potential Named Args API

gramps dev [--data-source=<datasource> [--data-source=<datasource> ...]] [--live | --mock] [--gateway=<gateway>] [--no-transpile]

Examples

# run the built-in dev server with no data sources (for "hello world" testing)
gramps dev

# run the current data source with the built-in dev server
gramps dev --data-source .

# run the current data source with the built-in dev server in live mode
gramps dev --data-source . --live

# run the current data source + an additional data source
gramps dev --data-source . --data-source ../otherSource

# run the current source + a custom gateway
gramps dev --data-source . --gateway ../gateway

# run the current source + custom gateway in live mode with no transpilation
gramps dev --data-source . --gateway ../gateway --live --no-transpile

Potential Positional API

gramps dev [<datasource> [<datasource> ...]] [--live | --mock] [--gateway=<gateway>] [--no-transpile]

Examples

# run the built-in dev server with no data sources (for "hello world" testing)
gramps dev

# run the current data source with the built-in dev server
gramps dev .

# run the current data source with the built-in dev server in live mode
gramps dev . --live

# run the current data source + an additional data source
gramps dev . ../otherSource

# run the current source + a custom gateway
gramps dev . --gateway ../gateway

# run the current source + custom gateway in live mode with no transpilation
gramps dev . --gateway ../gateway --live --no-transpile

What does everyone think of this?

[Piefayth]

Glad to see this! As for my two cents, I prefer the named arguments, but think that specifying -data-source for every data source is somewhat unwieldy. A delimited input of paths would be great. Also +1 to namespacing to gramps dev

[jlengstorf]

@Piefayth To clarify, you'd want to see:

# one data source
gramps dev --data-source .

# two data sources
gramps dev --data-sources ../dataSource, ../otherSource

# w/shorthand alias
gramps dev -d ../dataSource, ../otherSource

--data-source, --data-sources, and -d would all alias to the same thing.

Is that correct?

[jlengstorf]

I ran an unofficial poll in all the Slack channels I'm in + Twitter, and the overwhelming consensus was this:

1. If the arguments are required, positional args are preferred.
2. If the arguments are optional, named args are preferred.

Because the dev command does not require a data source arg to operate (it will start a GraphQL gateway that exposes the grampsVersion query), I believe we should finalize the API as follows:

# No args — starts a GraphQL gateway with the grampsVersion query only
gramps dev

# One data source using live data
gramps dev --data-source ./one

# One data source using mock data
gramps dev --data-source ./one --mock

# Two data sources (using the plural alias of --data-source)
gramps dev --data-sources ./one ./two

# Data sources through a custom gateway
gramps dev --data-sources ./one ./two --gateway ../gateway

# Data sources through a custom gateway using mock data
gramps dev --data-sources ./one ./two --gateway ../gateway --mock

# Data sources through a custom gateway using mock data with no Babel step
gramps dev --data-sources ./one ./two --gateway ../gateway --mock --no-transpile

Does anyone object to this API? If not, I'm going to get to work porting over the code so we can get to 1.0.

[jlengstorf]

Since there aren't any objections, I'm going to call this final and move forward with dev.