RFC: Exposing the generate-schema and generate-output actions from cli-utils as Node.js API's

[matthewvolk]

Summary

We maintain a CLI to help users bootstrap a new project on our platform (e.g., npm create ...), and as part of that process we would like to:

1. Run through our normal bootstrap process
2. Generate a GraphQL schema
3. Output the introspection file for gql.tada to use

While we could achieve this by using child_process.exec to call the gql.tada CLI from within our CLI, we have concerns around:

• Type safety: We prefer strongly typed method calls over string-based CLI commands
• Performance: Using exec spawns a new shell which adds overhead, but a direct API call can be executed within the same process space as our CLI
• Error handling: Parsing stdout and stderr from exec to determine success/failure can become complicated

Proposed Solution

1. Determine a reasonable API interface for the methods to be exposed (e.g., making cwd an optional parameter on the method)
2. Abstracting generate-schema and generate-output logic into two individual methods that live outside of the CLI action handler callbacks.
3. Exporting those methods as named exports from the @gql.tada/cli-utils package (we think importing these methods from @gql.tada/cli-utils makes the most sense so we don't have to install the entire gql.tada package in our CLI)

Requirements

N/A

Relevant Links

• More information on the CLI in reference: RFC: Implement a CLI for programmatic TS LSP & Checking tasks #76

[kitten]

@JoviDeCroock @matthewvolk: We're currently nearing the “beta/v1.0.0” release of the CLI, and I think we may have to revisit this.

The functions we expose currently may not match what the CLI is doing exactly and put some cosnstraints on us that make it more likely that we'll break them in the future, if we're not careful.

We could instead replace them with @gql.tada/internal however.

This does require us to move some substantial parts of @gql.tada/cli-utils` over, but may help with separating the two a little into a re-usable and non-reusable package.

The other option would be to clearly specify how we want to expose these methods, but I'm writing this note to basically say that in the next major release of the CLI (which is in theory imminent) some APIs may change or break, either way, on cli-utils or not 😅