use "graphql" term for examples over schema

[prisma-labs]

use "graphql" term for examples over schema

[jasonkuhrt]

Was working on this issue tonight. I didn't feel convinced. Problem was that GraphQL is a concept that includes context and schema. And while it is a transport agnostic technology it feels temping to say also includes server, in practice, when working on a real project.

Compare for example:

graphql/
  server.ts
  context.ts
  schema.ts
prisma/
  schema.prisma

vs

src/
  server.ts
  context.ts
  graphql.ts
prisma/
  schema.prisma

I currently prefer the former:

1. Root level graphql stands our more quickly when parsing project tree (e.g. a git repo where graphql would be visible without any navigation).
2. graphql/{context.ts,schema.ts} is accurate
3. graphql/ prisma/ feels like the right peer balance. When talking about the the stack, this is how it will often be seen: a graphql box and a prisma box
4. src/ prisma/ on the other hand is a bit odd––schema.prisma contains "source code" too, it's just a declarative data modelling language instead of TypeScript. Splitting hairs over what is src or not just seems a waste of time and energy, without really giving value to the mental model.

CC @Weakky

[Weakky]

The problem with having a top-level graphql, is that it assumes the users' codebase will only be about graphql although their codebase might be about thousand of other things.
And if we don't have a top-level folder to encapsulate graphql, we'll force users to have their rootDir be .

eg:

graphql/
  User.ts
  Post.ts
rest/
  user.ts
  post.ts
jobs/
  job1.ts
  job2.ts
prisma/
  schema.prisma

Therefore, I suggest the following:

src/
  graphql/
    User.ts
    Post.ts
  index.ts //or main.ts
prisma/
  schema.prisma

where one could evolve to:

src/
  graphql/
    User.ts
    Post.ts
  rest/
    user.ts
    post.ts
  jobs/
    job1.ts
    job2.ts
  index.ts //or main.ts
prisma/
  schema.prisma

Reasoning:

1. index|main.ts: Because we're "just an api", users might customize their codebase and do more stuff than just spawning a http server. I think we need to be more general so that people can do more stuff in the conventional entrypoint. It could evolve for example to:

src/
  graphql/
    User.ts
    Post.ts
    server.ts
  rest/
    user.ts
    post.ts
    server.ts
index.ts //or main.ts, where `index.ts` could require `src/graphql/server.ts`
prisma/
  schema.prisma

2. index|main.ts: I don't think we should allow both. I think we should choose one or the other, or even another one. index.ts might be more js idiomatic

3. Where is the context.ts: Not sure yet. probably in src/graphql/context.ts

And while it is a transport agnostic technology it feels temping to say also includes server, in practice, when working on a real project

I agree with your point. I think it feels less weird if it's something like index.ts or main.ts (instead of server.ts). It's no longer explicitely defined as being a server, but rather the entrypoint of your project (which... spawns the server)

[jasonkuhrt]

@Weakky good points. You're also making the case though for not treating graphql as an alias for schema. After all a rule about schema folder is that all sub-modules are assumed to be schema-contributing modules, auto-imported, which in your last code example server.ts would not be.

I still don't feel great about src/ prisma/. I would like something a bit higher level. api/ prisma/ or app/ prisma/ or pumpkins/ prisma/ for example.

The following is somewhat off-topic/new issue but somewhat related:

To further underscore the high-level-ness of project dir, I was thinking of outputting the build to node_modules/.build (.pumpkins_build pumpkins_app_build, ...?) and then revisiting the idea of $ pumpkins boot which 1) knows to look into node_modules/.build and 2) knows to call the start module $node node_modules/.pumpkins_app_build/start

[jasonkuhrt]

#174 (comment)

[jasonkuhrt]

Here is a case where it seems nice/ok. Currently it must be schema but imagine we did support graphql. Peer top-level folders prisma and graphql feels like it would be elegant and simple.

[jasonkuhrt]

In the minimal case when working with a single schema file, I can see how a singular graphql.ts module would be nice, versus what we currently support:

[jasonkuhrt]

Discussions with @schickling @Weakky this week. We will go ahead with the change!