nitrogql 2.0 release: @oneOf, operation descriptions, Node.js 22+
Today, we are happy to announce release of nitrogql 2.0!
nitrogql is a toolchain for using GraphQL in TypeScript projects. In 2.0, we added support for recent additions to the GraphQL specification: the @oneOf directive, and descriptions on operations, fragments and variable definitions. Also, this release drops support for Node.js versions that reached their end of life, which is why this is a major version bump.
Node.js 22+ is now required
nitrogql packages now require Node.js 22 or later. Node.js 18 and 20 have both reached their end of life, and dropping them allows us to keep the codebase modern. This is the only breaking change in this release; if you are already on Node.js 22 or later, upgrading to nitrogql 2.0 should require no changes to your project.
Published packages now declare this requirement through the engines field, so npm will warn you if you install them on an older Node.js version. Relatedly, @nitrogql/esbuild-register is now distributed as an ES module.
Support for the @oneOf directive
The @oneOf directive is a recent addition to the GraphQL specification that lets you define a polymorphic input object: an input object in which exactly one of the fields must be provided.
input UserBy @oneOf {
id: ID
email: String
}nitrogql 2.0 fully understands such input objects. The static check validates that literal values and variables passed to a @oneOf input object provide exactly one field with a non-null value. And notably, the generated TypeScript type is a union that lets the type checker enforce the same constraint at the TypeScript level:
export type UserBy = {
readonly id: ID;
readonly email?: never;
} | {
readonly id?: never;
readonly email: String;
};With this type, providing both fields, or providing none of them, is a type error in your TypeScript code. This is another example of nitrogql's goal of maximizing type safety of GraphQL operations.
Descriptions on operations, fragments and variable definitions
The latest edition of the GraphQL specification allows descriptions to be attached to executable definitions (operations and fragments) and to variable definitions. nitrogql 2.0 supports parsing these descriptions:
"""
Query to get the current user.
"""
query getUser(
"ID of the user."
$id: ID!
) {
user(id: $id) {
name
}
}These descriptions are not just parsed; they are surfaced as JSDoc comments in the generated TypeScript code. Operation descriptions are attached to the generated result type and operation constant, fragment descriptions to the fragment type and constant, and variable descriptions to the corresponding properties of the variables type. This means that the descriptions you write in your GraphQL files will show up in your editor when you use the generated types.
Note that descriptions are intentionally not included in the runtime document (the TypedDocumentNode JSON), so the generated runtime output remains compatible with consumers that do not know about the new syntax.
Bug fixes
This release also contains several bug fixes:
- Fixed a parser panic on the shorthand (anonymous) query syntax.
- Fixed the GraphQL printer dropping default values and directives from variable definitions.
- Fixed handling of preopened directories in the WASI runtime shipped with
@nitrogql/wasi-preview1.
Conclusion
nitrogql 2.0 keeps up with the evolution of the GraphQL specification by supporting the @oneOf directive and descriptions on executable definitions, both of which are reflected in the generated TypeScript types. While this release is a major version bump, the only breaking change is the drop of old Node.js versions, so we expect the upgrade to be smooth for most projects.
nitrogql is developed by uhyo. Contribution is more than welcome!