SDL as an Artifact: Code-First Schemas and GraphQL Nexus

GraphQLConf '19

Transcript

1. SDL as an Artifact: Code-first Schemas and GraphQL Nexus @tgriesser
2. Tim Griesser @tgriesser “Fast, reliable testing for anything that runs in a browser”
3. ❤
4. ❤ A Brief Timeline
5. 2015: graphql-js
8. Later 2015 graph.ql 2015: graphql-js
9. Original “SDL First” Library: Released November 2015
13. vs
14. Later 2015 - 2016: graph.ql graphql-tools 2015: graphql-js
15. 2015: graphql-js Later 2015 - 2016: graph.ql graphql-tools 2017: Graphene (Python)
17. – Me, when beginning to use Graphene “Oh no, this library doesn’t develop the SDL first”
18. …a few months pass
19. – Me, after spending a few more months in Graphene “Hey, this is actually pretty nice… scales really well to multiple teams”
20. Stats from Generated SDL: 307 object types 129 input types 89 enum types 10 interfaces 5 custom scalars 1 union type 0 custom directives 2542 output fields 581 input fields 717 enum members 35 deprecations ~ 18 developers, 4 teams contributing to the same schema
21. GitHub Public API SDL: 326 object types 90 input types 70 enum types 25 interfaces 8 custom scalars 20 union types 0 custom directives 2085 output fields 307 input fields 299 enum members 6 deprecations https://github.com/octokit/graphql-schema
22. 2015: graphql-js Later 2015 - 2016: graph.ql graphql-tools 2017: Graphene (Python) 2018: GraphQL Ruby
24. 2015: graphql-js Later 2015 - 2016: graph.ql graphql-tools 2017: Graphene (Python) 2018: GraphQL Ruby Also 2018: graphql-tools + graphql-code-generator
26. – Marc-André Giroux during Q&A after at GraphQL NYC “…I’m not sure - SDL first seems to be unique to the JavaScript community”
27. …it feels like the JavaScript ecosystem is missing out
29. Maybe we’re doing it wrong?
30. What might a better “code first” approach look like?
31. GraphQL Nexus: An improved experience building code-first schemas in JavaScript & TypeScript
32. Why not SDL first?
33. GraphQL Nexus Why not SDL first?
34. Related Tooling in the Ecosystem GraphQL Nexus Why not SDL first?
35. Why not SDL first? Related Tooling in the Ecosystem GraphQL Nexus How SDL is Still Incredibly Useful
36. Why not SDL first?
37. Code Duplication
39. “Double Declaration Problem”
40. Implemented 16 times in GitHub’s Public API… Adding a new field with SDL first would mean finding all 16 locations and adding the new field
41. Code Duplication Documentation / Type Ordering
42. Code Duplication Documentation / Type Ordering Building For Larger Teams
43. Code Duplication Documentation / Type Ordering Building For Larger Teams Tooling Complexity
44. Code Duplication Documentation / Type Ordering Building For Larger Teams Tooling Complexity Microservices??
46. https://nexus.js.org
47. Code First
48. Code First Declarative
51. Code First Declarative Type-Safe
52. Code First Declarative Type-Safe JavaScript Friendly
53. Code First Declarative Type-Safe JavaScript Friendly Opinionated
54. Code First Declarative Type-Safe JavaScript Friendly Opinionated** **but only slightly, configurable, and hopefully not too controversial
55. What makes it different??
56. Development Feedback Loop
57. “makeSchema”
 Generates Types
58. “makeSchema”
 Generates Types Generated types are 
 Inferred by
 TypeScript Outputs SDL Schema Artifact Creates GraphQL schema Outputs TypeScript Types Imported type “registry” wired up
59. “makeSchema”
 Generates Types Generated types are 
 Inferred by
 TypeScript Changes to
 Schema, Restart 
 the Server IDE Auto-Completion & Type Checking Optional for JS development
60. “makeSchema”
 Generates Types Generated types are 
 Inferred by
 TypeScript Changes to
 Schema, Restart 
 the Server Regenerates SDL & Types files
62. Type-Safety
64. Generated in Development
65. Generates a normal schema
66. How? Conditional Types + Global Declaration Merging
70. What’s the resolver return type?
71. What’s the resolver return type? "Droid", "primaryFunction"
72. What’s the resolver return type (continued)?
73. What’s the resolver return type (continued)? You don’t need to worry about this…
74. Does the field need a resolver?
75. End Result: Type-safety with less typing
76. Dynamic Methods: Building custom, type-safe abstractions
77. Connections:
78. Customize object construction for your use cases
79. Customize object construction for your use cases
80. Auto-generated
82. Makes something previously complicated simple
83. Nexus Plugins: User-defined, type-safe additions
86. Augmenting library behavior (runtime and types) based on user defined constructs
87. Example: nexus-prisma +
88. Opinions: Nullability
89. – GraphQL Documentation “... in a GraphQL type system, every field is nullable by default. This is because there are many things which can go awry in a networked service backed by databases and other services. A database could go down, an asynchronous action could fail, an exception could be thrown. Beyond simply system failures, authorization can often be granular, where individual fields within a request can have different authorization rules.”
90. Exceptional States Should be Exceptional: “null” to indicate network failure should be declared & documented
91. – GraphQL Documentation “... in a GraphQL type system, every field is nullable by default. This is because there are many things which can go awry in a networked service backed by databases and other services. A database could go down, an asynchronous action could fail, an exception could be thrown. Beyond simply system failures, authorization can often be granular, where individual fields within a request can have different authorization rules.”
93. Configurable, schema level or type level
94. The SDL Converter
96. Paste your SDL endpoint thanks @swcarlosrj
97. The Bad Parts Rough Edges
98. “makeSchema”
 Generates Types Generated types are 
 Inferred by
 TypeScript Changes to
 Code, Restarts
 the Server Requires Some Configuration ?? Chicken / Egg Problem TypeScript errors are sometimes cryptic Dynamic Types & Jump To Code
99. Other Code-First Tooling
103. What’s Next?
104. “Dynamic Methods” Type-Safe “Plugin” System Progammatic Directives Better interop with SDL snippets
105. SDL is Still Incredibly Useful
106. Prototyping New Features
107. Common Language
108. Users don’t see our code, they just want a good experience on the web
109. Pick whichever tools help you solve problems
110. Thanks! https://nexus.js.org @tgriesser