We have the power to restrict what types of Field's are returned (i.e "selected") from a Selector object's method.

Some possible implementation options:

• Inline define union of field names (as shown here)
• Define a union of the entire selection available to a type (ex. type UserSelection = Array<Field<'id', [], string> | Field<'friends', [], any>>>) (this might be the key to getting nullable / list type support)

• Note: This is also a critical piece for supporting "native" fragments

https://github.com/stephenh/ts-poet

Right now all of our Field types are inferred to be singular values.

@babel/types provides some nice TypeScript AST utils that we could use to make our Codegen class perhaps more maintainable.

We can use Proxy objects to support (non-typesafe) dynamic and generic operation builders. Would be useful for non-ts projects (like this library seems to support) and experimentation.

Interfaces and unions are powerful tools for modeling many domains and a full-featured GraphQL client should fully support them. Here are some ideas on how we accomplish that here.

Interfaces:

• Define special interface Selector objects that have __typename and on methods (as well as common interface fields)
• __typename returns a Field of type string literal (enumerating all of the interface implementations in the schema)
• on takes two arguments, a string literal (enumerating implementations) and a selector callback allowing selection on a concrete type
• Define exported guard functions for utility
• Somehow type return as discriminating union

Example:

query(“Example”, t => 
  t.accounts(t => 
     t.__typename(),
     t.on(“InvestmentAccount”, t => [ t.broker() ]),
     t.on(“RetirementAccount”, t => [ t.age() ]),
  )
)

Note: This will likely lead us to implementing fragments (to do properly at least).

https://mikro-orm.io/docs/usage-with-js

Relates to #27

Field typings, nested input objects, etc.

Seems like TypeScript type-inference is broken with the current way we have union types implemented (note it works fine for interfaces).

Typescript output:

[11:13:13 PM] Starting compilation in watch mode...

graphql-api.ts:5839:22 - error TS2552: Cannot find name 'Query'. Did you mean 'query'?

5839   select: (t: typeof Query) => T
                          ~~~~~

graphql-api.ts:5841:56 - error TS2552: Cannot find name 'Query'. Did you mean 'query'?

5841   new Operation(name, "query", new SelectionSet(select(Query)));
                                                            ~~~~~

graphql-api.ts:5845:22 - error TS2552: Cannot find name 'Mutation'. Did you mean 'mutation'?

5845   select: (t: typeof Mutation) => T
                          ~~~~~~~~

graphql-api.ts:5847:59 - error TS2552: Cannot find name 'Mutation'. Did you mean 'mutation'?

5847   new Operation(name, "mutation", new SelectionSet(select(Mutation)));
                                                               ~~~~~~~~

graphql-api.ts:5851:22 - error TS2552: Cannot find name 'Subscription'. Did you mean 'subscription'?

5851   select: (t: typeof Subscription) => T
                          ~~~~~~~~~~~~

graphql-api.ts:5853:63 - error TS2552: Cannot find name 'Subscription'. Did you mean 'subscription'?

5853   new Operation(name, "subscription", new SelectionSet(select(Subscription)));
                                                                   ~~~~~~~~~~~~

[11:13:20 PM] Found 6 errors. Watching for file changes.

Full graphql-api.ts: https://gist.github.com/ryb73/def4d02805995f953b37f3f8405df533

Generated using command:

yarn --silent tql http://localhost:8080/v1/graphql > graphql-api.ts

I'm using a GraphQL server generated by Hasura.

It looks like it didn't generate Query, Mutation, or Subscription? Is there some configuration I need to do before running tql?

https://github.com/cookpete/auto-changelog

Possible API:

// or class-based API

const userName = new Fragment({
  name: 'UserDetails',
  on: 'User',
  selection: (t) => [ t.name(t => [ t.first(), t.last() ]) ]
})

// higher-level functional API
const userName = on('User', t => [ t.name(t => [ t.first(), t.last() ])).named('UserNameFields')
// or
const userName = user(t => [ t.name(t => [ t.first(), t.last() ])).toFragment('UserNameFields')

• CLI documentation
• SDK building (including error handling)
• Standalone query writing

• Unwrap data object (i.e so we don't have to do data.hero...)
• HTTP Keep-alive by default
• Persisted query support
• Structured logging support
• Exponential backoff retry
• Log warning on deprecated field usage

Hey! 👋🏿

I couldn't find your email or Twitter link to reach out - sorry for opening an issue just for that.

I really like your project! I am working on something very, very similar (Kayu) - do you think we could maybe merge the projects? I don't think it's beneficial to solve the same problem twice. I really like the idea of using TS to define queries and especially your approach to using them with urql and Apollo client (as"not writing alternative clients").

Well, let me know if you want to chat! I think we could learn a lot from each other. 😄

We should make return types readonly and immutable (maybe even at runtime with Object.freeze) as a best practice (with the ability to opt-out and disable runtime Object.freeze).

For @deprecated fields render a @deprecated JSDoc comment that can be picked up by editor tooling for example.

https://ray.so/

• GitHub Actions
• Semantic versioning

Variable definitions allow operations to be reused.

query(v => [ v.definition(“id”, v.string) ], t => [ t.account({ id: new Variable(“id”) }, t => [ t.balance() ]))

Higher level API:

import { query, $, VariablesOf } from '@timkendall/tql'

const a = query<any>(t => [
  t.user({ id: $`id!` }, t => [ t.id() ])
])

type AVariables = VariablesOf<typeof a> // { string: any }

Right now we default to unknown types.

https://codesandbox.io/

Run some basic microbenchmarks agains graphql-tag and existing “fluent” libraries https://github.com/hasura/awesome-fluent-graphql

See if we can do some integration with graphql-nexus and typegraphql.

Gqty (formerly gqless) takes the approach of rendering straight to strings and skipping AST construction altogether.

Inline field arguments of input objects with enum fields are not serialized correctly.

Example:

mutation('MyMutation', t => [
  // @bug SomeEnum.FOO is serialized as a string!
  t.myMutation({ input: { someEnum: SomeEnum.FOO }, t => [ 
    t.__typename(),
  ])
])

See if there is any reasonable way to ship ES modules for runtimes (i.e browsers, Node 14+) that support them natively. Make sure it works with https://unpkg.com/

https://formidable.com/open-source/urql/docs/

• Node.js CPU and memory usage event-loop delay
• Operations per second (using benchmark.js/benny)
• Against other "fluent" GraphQL libraries

https://sergiodxa.com/articles/github-actions-npm-publish

As a runtime optimization it would be nice to have compiler plugins for TypeScript, Babel, ESBuild, etc. to replace the function invocations with static query text (to avoid both the cost of DSL function calls and GraphQL AST serialization).

We would need to account for cases where users are doing "bad things" and dynamically generating queries (perhaps a linter plugin and/or warning emitted from the compiler could be solutions).

We could also experiment with support for "Build-time APQ's"; i.e replace query text with a SHA and export operations to be pre-registered/whitelisted with an API server.

Examples:
-https://github.com/xialvjun/ts-sql-plugin
-https://dev.doctorevidence.com/how-to-write-a-typescript-transform-plugin-fc5308fdd943

• https://github.com/facebook/relay/tree/main/compiler

We should direct the output of tql to node_modules/@timkendall/tql and setup the appropriate exports so that users can use this library as portrayed in our README.

Riffing off of the new Selector API's let's clean-up the type-safe Query, Mutation, and Subscription selectors that we generate.

Examples:

import { query, mutation, subscription, t, $ } from './operations'

const a =  new Query({
  name: 'Foo',
  variables: { id: t.string },
  directives: [/* @todo */]
  selection: (t, v) => [
    t.user({ id: v.id }, t => [
      t.firstName(),
    ])
  ],
  extensions: [/* @todo */],
})

// or simpler...maybe just for anonymous + no-variables?

const b = query<'Example'>(t => [
  t.viewer(t => [
    t.id(),
    t.avatar()
  ]),

  // with a variable…
  t.user({ id: $`foo` }, t => [ t.id() ])
])

Need to run against more test schemas.

We should make this library and the code this library generates compatible with Deno.

Note: this may be useful https://github.com/bevry/make-deno-edition

Right now all of our Field returned types are inferred to be non-nullable.

Would be nice to publish to GitHub Package Registry as-well-as NPM for redundancy and ease-of-adoption.

From the README it is not immediately obvious how to build a type-safe SDK with this library/tool. Perhaps we should implement a separate CLI (create-graphql-sdk?) or command that drives this workflow?

Considerations for SDK-building workflows:

1. Generating of supporting files and structure (like package.json, src/, etc.)
2. Splitting up the generated code into separate modules for larger API's (for readability, build performance, and easier code-splitting)
3. Generating the appropriate semantic version for the SDK based on the previous graph and tql runtime version
4. (Optional) Generating a changelog
5. (Optional) Generating documentation (via. GitBook, Docusaurus, etc.)
6. (Optional) Publishing to package registries

We should run the TypeScript type-checker on the generated output (Prettier already runs the parser). Relates to #46

In-order-to help with ease of use, we could generate a thin Client class wrapper around our query, mutation, and subscription primitives. It would expose methods for each top-level operation (as well-as expose more flexible query and mutation methods).

Example (with Starwars schema):

import { Transport, Operation } from '@timkendall/tql'

export class Starwars {
  constructor(private readonly transport: Transport) {}
  
  public viewer(select: ViewerSelector) {}

  public addReview(variables: AddReviewInput, select: AddReviewSelector ) {}

  public query(name: string, select: QuerySelector) {}

  public mutate(name: string, select: MutationSelector) {}

  private execute<T>(operation: Operation<T>) {
    //  execute GraphQL operation against `this.transport`
  }
}

We should have a GitHub Action that takes a GraphQL schema reference and git ref and generates a new version of the SDK.

Might be nice to offer an integration with Fig for VSCode-style terminal autocompletion (distribution seems to be as easy as storing a new .js module in ~/.fig/autocomplete; it looks like they might have some package.json integration).

// To learn more about Fig's autocomplete standard visit: https://fig.io/docs/autocomplete/building-a-spec#building-your-first-autocomplete-spec

// The below is a dummy example for git. Make sure to change the file name!
export const completion: Fig.Spec = {
  name: "tql",
  description: "Generate a fluent TypeScript client for your GraphQL API.",
  args: [
    { 
      name: 'schema',
      description: 'GraphQL schema from HTTP endpoint or local .graphql file.',

      // @todo discover a local dir schema via. .graphqlconfig?
      // generators: [
      //   {
      //     script: "git branch -l",
      //     postProcess: function(out) {
      //       return out.split('\n').map(branch => {
      //         return { name: branch, description: "branch"}
      //       })
      //     }
      //   }
      // ]
    }
  ],
  subcommands: [],
  options: [
    {
      name: ["-v", "--version"],
      description: "View tql version",
    },
    {
      name: ["-c", "--client"],
      description: "Generate an SDK client for the API",
    },
    {
      name: ["-t", "--tag"],
      description: 'Semantic versioning tag, ex. "1.0.0" (defaults to "unversioned")'
    },
    {
      name: ['--mutableFields'],
      description: 'Generate schema types and results as mutable (default is read-only).',
    },
    {
      name: '--module-path',
      description: 'Optional path to the @timkendall/tql module to be included (CDN, private registry, etc.).'
    }
  ],
};

Short and sweet.

Didn't realize https://github.com/dotansimha/graphql-typed-document-node existed; could utilize.

Integrating with a library.

GraphQL JS v16+ exports a generic DocumentNode natively.

Our code generator incorrectly generates Selector objects for root-level (i.e Query, Mutation, Subscription) type scalar fields. Example:

 suspendDeposits: <T extends Array<Selection>>(
      variables: { suspended?: boolean },
      select: (t: VoidSelector) => T
    ) =>
      this.executor.execute<
        IMutation,
        Operation<
          SelectionSet<[Field<"suspendDeposits", any, SelectionSet<T>>]>
        >
      >(
        new Operation(
          "suspendDeposits",
          "mutation",
          new SelectionSet([Mutation.suspendDeposits<T>(variables, select)])
        )
      ),