A complete implementation of the official GraphQL specification in the Dart programming language.
Inspired by graphql-js, async-graphql and type-graphql. First version of the codebase was forked from angel-graphql. Many tests and utilities (DataLoader, printSchema) were ported from graphql-js.
If your prefer to read the documentation in a web page, you can try the documentation page built with Docusaurus.
- Quickstart
- Examples
- Packages
- Web integrations
- Documentation
- GraphQL Schema Types
- Resolvers
- Validation
- Miscellaneous
- Solving the N+1 problem
- Extensions
- Directives
- Attachments
- Utilities
- Contributing
This provides a simple introduction to Leto, you can explore more in the following sections of this README or by looking at the tests, documentation and examples for each package. A fullstack Dart example with Flutter client and Leto/Shelf server can be found in https://github.com/juancastillo0/leto/tree/main/chat_example
The source code for this quickstart can be found in https://github.com/juancastillo0/leto/blob/main/leto_shelf/example/lib/quickstart_server.dart.
Add dependencies to your pubspec.yaml
dependencies:
leto_schema: ^0.0.1-dev.3
leto: ^0.0.1-dev.1
leto_shelf: ^0.0.1-dev.1
shelf: ^1.0.0
shelf_router: ^1.0.0
# Not nessary for the server, just for testing it
http: ^1.0.0
dev_dependencies:
# Only if you use code generation
leto_generator: ^0.0.1-dev.3
build_runner: ^2.0.0
Specify the logic for your server, this could be anything such as accessing a database, reading a file or sending an http request. We will use a controller class with a stream that emits events on mutation to support subscriptions.
// this annotations is only necessary for code generation
@GraphQLObject()
class Model {
final String state;
final DateTime createdAt;
const Model(this.state, this.createdAt);
}
/// Set up your state.
/// This could be anything such as a database connection.
///
/// Global means that there will only be one instance of [ModelController]
/// for this reference. As opposed to [ScopedRef.local] where there will be
/// one [ModelController] for each request (for saving user information
/// or a [DataLoader], for example).
final stateRef = ScopedRef<ModelController>.global(
(scope) => ModelController(
Model('InitialState', DateTime.now()),
),
);
class ModelController {
Model? _value;
Model? get value => _value;
final _streamController = StreamController<Model>.broadcast();
Stream<Model> get stream => _streamController.stream;
ModelController(this._value);
void setValue(Model newValue) {
if (newValue.state == 'InvalidState') {
// This will appear as an GraphQLError in the response.
// You can pass more information using custom extensions.
throw GraphQLError(
"Can't be in InvalidState.",
extensions: {'errorCodeExtension': 'INVALID_STATE'},
);
}
_value = newValue;
_streamController.add(newValue);
}
}
With the logic that you want to expose, you can create the GraphQLSchema instance and access the controller state using the Ctx
for each resolver and the ScopedRef.get
method. The following is a schema with Query, Mutation and Subscription with a simple model. However, GraphQL is a very expressive language with Unions, Enums, complex Input Objects, collections and more. For more documentation on writing GraphQL Schemas with Leto you can read the following sections, tests and examples for each package.
To expose this logic, we could implement the following GraphQL API:
type Query {
"""Get the current state"""
getState: Model
}
type Model {
state: String!
createdAt: Date!
}
"""An ISO-8601 Date."""
scalar Date
type Mutation {
setState(
"""The new state, can't be 'WrongState'!."""
newState: String!
): Boolean!
}
type Subscription {
onStateChange: Model!
}
This could be exposed by using package:leto_schema
API as shown in the following code sample or more simply by using code generation.
/// Create a [GraphQLSchema].
/// All of this can be generated automatically using `package:leto_generator`
GraphQLSchema makeGraphQLSchema() {
// The [Model] GraphQL Object type. It will be used in the schema
final GraphQLObjectType<Model> modelGraphQLType = objectType<Model>(
'Model',
fields: [
// All the fields that you what to expose
graphQLString.nonNull().field(
'state',
resolve: (Model model, Ctx ctx) => model.state,
),
graphQLDate.nonNull().field(
'createdAt',
resolve: (Model model, Ctx ctx) => model.createdAt,
),
],
);
// The executable schema. The `queryType`, `mutationType`
// and `subscriptionType` are should be GraphQL Object types
final schema = GraphQLSchema(
queryType: objectType('Query', fields: [
// Use the created [modelGraphQLType] as the return type for the
// "getState" root Query field
modelGraphQLType.field(
'getState',
description: 'Get the current state',
resolve: (Object? rootValue, Ctx ctx) => stateRef.get(ctx).value,
),
]),
mutationType: objectType('Mutation', fields: [
graphQLBoolean.nonNull().field(
'setState',
// set up the input field. could also be done with
// `graphQLString.nonNull().inputField('newState')`
inputs: [
GraphQLFieldInput(
'newState',
graphQLString.nonNull(),
description: "The new state, can't be 'WrongState'!.",
),
],
// execute the mutation
resolve: (Object? rootValue, Ctx ctx) {
final newState = ctx.args['newState']! as String;
if (newState == 'WrongState') {
return false;
}
stateRef.get(ctx).setValue(Model(newState, DateTime.now()));
return true;
},
),
]),
subscriptionType: objectType('Subscription', fields: [
// The Subscriptions are the same as Queries and Mutations as above,
// but should use `subscribe` instead of `resolve` and return a `Steam`
modelGraphQLType.nonNull().field(
'onStateChange',
subscribe: (Object? rootValue, Ctx ctx) => stateRef.get(ctx).stream,
)
]),
);
assert(schema.schemaStr == schemaString.trim());
return schema;
}
You can use code generation to create a function similar to makeGraphQLSchema
with the following resolver definitions with annotations.
/// Code Generation
/// Using leto_generator, [makeGraphQLSchema] could be generated
/// with the following annotated functions and the [GraphQLObject]
/// annotation over [Model]
/// Get the current state
@Query()
Model? getState(Ctx ctx) {
return stateRef.get(ctx).value;
}
@Mutation()
bool setState(
Ctx ctx,
// The new state, can't be 'WrongState'!.
String newState,
) {
if (newState == 'WrongState') {
return false;
}
stateRef.get(ctx).setValue(Model(newState, DateTime.now()));
return true;
}
@Subscription()
Stream<Model> onStateChange(Ctx ctx) {
return stateRef.get(ctx).stream;
}
This generates the same modelGraphQLType
in <file>.g.dart
and graphqlApiSchema
in 'lib/graphql_api.schema.dart' (TODO: 1G configurable). The documentation comments will be used as description in the generated schema. More information on code generation can be found in the following sections, in the package:leto_generator
's README or in the code generation example.
With the GraphQLSchema
and the resolver logic implemented, we can set up the shelf handlers for each route. In this case we will use the graphQLHttp
handlers for the "/graphql" endpoint and graphQLWebSocket
for "/graphql-subscription" which supports subscriptions. You could provide custom extensions, document validations or a ScopedMap
to override the state in the GraphQL
executor constructor.
Future<HttpServer> runServer({int? serverPort, ScopedMap? globals}) async {
// you can override state with ScopedMap.setGlobal/setScoped
final ScopedMap scopedMap = globals ?? ScopedMap();
if (globals == null) {
// if it wasn't overridden it should be the default
assert(stateRef.get(scopedMap).value?.state == 'InitialState');
}
// Instantiate the GraphQLSchema
final schema = makeGraphQLSchema();
// Instantiate the GraphQL executor, you can pass extensions and
// decide whether you want to introspect the schema
// and validate the requests
final letoGraphQL = GraphQL(
schema,
extensions: [],
introspect: true,
globalVariables: scopedMap,
);
final port =
serverPort ?? const int.fromEnvironment('PORT', defaultValue: 8080);
const graphqlPath = 'graphql';
const graphqlSubscriptionPath = 'graphql-subscription';
final endpoint = 'http://localhost:$port/$graphqlPath';
final subscriptionEndpoint = 'ws://localhost:$port/$graphqlSubscriptionPath';
// Setup server endpoints
final app = Router();
// GraphQL HTTP handler
app.all(
'/$graphqlPath',
graphQLHttp(letoGraphQL),
);
// GraphQL WebSocket handler
app.all(
'/$graphqlSubscriptionPath',
graphQLWebSocket(
letoGraphQL,
pingInterval: const Duration(seconds: 10),
validateIncomingConnection: (
Map<String, Object?>? initialPayload,
GraphQLWebSocketShelfServer wsServer,
) {
if (initialPayload != null) {
// you can authenticated an user with the initialPayload:
// final token = initialPayload['token']! as String;
// ...
}
return true;
},
),
);
In the shelf router you can specify other handlers such as static files or other utilities. In the following code we set up a GraphQL UI explorer in the "/playground" route using the playgroundHandler
handler and a "/graphql-schema" endpoint that returns the GraphQL schema String in the body of the response.
// GraphQL schema and endpoint explorer web UI.
// Available UI handlers: playgroundHandler, graphiqlHandler and altairHandler
app.get(
'/playground',
playgroundHandler(
config: PlaygroundConfig(
endpoint: endpoint,
subscriptionEndpoint: subscriptionEndpoint,
),
),
);
// Simple endpoint to download the GraphQLSchema as a SDL file.
// $ curl http://localhost:8080/graphql-schema > schema.graphql
const downloadSchemaOnOpen = true;
const schemaFilename = 'schema.graphql';
app.get('/graphql-schema', (Request request) {
return Response.ok(
schema.schemaStr,
headers: {
'content-type': 'text/plain',
'content-disposition': downloadSchemaOnOpen
? 'attachment; filename="$schemaFilename"'
: 'inline',
},
);
});
Once you set up all the handlers, you can start the server adding middlewares if necessary. In this example, we will use the etag
and cors
middlewares from package:leto_shelf
. You can read more about them in the package's README.
// Set up other shelf handlers such as static files
// Start the server
final server = await shelf_io.serve(
const Pipeline()
// Configure middlewares
.addMiddleware(customLog(log: (msg) {
// TODO: 2A detect an introspection query.
// Add more structured logs and headers
if (!msg.contains('IntrospectionQuery')) {
print(msg);
}
}))
.addMiddleware(cors())
.addMiddleware(etag())
.addMiddleware(jsonParse())
// Add Router handler
.addHandler(app),
'0.0.0.0',
port,
);
print(
'GraphQL Endpoint at $endpoint\n'
'GraphQL Subscriptions at $subscriptionEndpoint\n'
'GraphQL Playground UI at http://localhost:$port/playground',
);
return server;
}
With the runServer
function finished, we can now create a main function that executes it and servers the implemented logic in a GraphQL server. This function can also be used for test as shown in the testServer
function from the next section.
Future<void> main() async {
final server = await runServer();
final url = Uri.parse('http://${server.address.host}:${server.port}/graphql');
await testServer(url);
}
You can test the server programmatically by sending HTTP requests to the server. You could also test the GraphQL executor directly using the GraphQL.parseAndExecute
function without running the shelf server.
/// For a complete GraphQL client you probably want to use
/// Ferry (https://github.com/gql-dart/ferry)
/// Artemis (https://github.com/comigor/artemis)
/// or raw GQL Links (https://github.com/gql-dart/gql/tree/master/links)
Future<void> testServer(Uri url) async {
final before = DateTime.now();
const newState = 'NewState';
// POST request which sets the state
final response = await http.post(
url,
body: jsonEncode({
'query':
r'mutation setState ($state: String!) { setState(newState: $state) }',
'variables': {'state': newState}
}),
headers: {'content-type': 'application/json'},
);
assert(response.statusCode == 200);
final body = jsonDecode(response.body) as Map<String, Object?>;
final data = body['data']! as Map<String, Object?>;
assert(data['setState'] == true);
// Also works with GET
final responseGet = await http.get(url.replace(
queryParameters: <String, String>{
'query': '{ getState { state createdAt } }'
},
));
assert(responseGet.statusCode == 200);
final bodyGet = jsonDecode(responseGet.body) as Map<String, Object?>;
final dataGet = bodyGet['data']! as Map<String, dynamic>;
assert(dataGet['getState']['state'] == newState);
final createdAt = DateTime.parse(dataGet['getState']['createdAt'] as String);
assert(createdAt.isAfter(before));
assert(createdAt.isBefore(DateTime.now()));
// To test subscriptions you can open the playground web UI at /playground
// or programmatically using https://github.com/gql-dart/gql/tree/master/links/gql_websocket_link,
// an example can be found in test/mutation_and_subscription_test.dart
}
Test and explore the server manually in the explorer interface "http://localhost:8080/playground". It supports subscriptions, subscribe in one tab and send a mutation request in another to test it. There are other UI explorers that you can set up (for example, GraphiQL and Altair), for more information Web UI explorers section.
We also set up a "http://localhost:8080/graphql-schema" endpoint which returns the GraphQL schema String in the schema definition language, this could be useful for other tools such as client side code generators.
Beside the tests from each package, you can find some usage example in the following directories and external repositories:
An example with multiple ways of creating a GraphQLSchema with different GraphQL types and resolvers from code generation can be found in https://github.com/juancastillo0/leto/tree/main/leto_generator/example.
A fullstack Dart example with Flutter client and Leto/Shelf server can be found in https://github.com/juancastillo0/leto/tree/main/chat_example. The server is in the server folder.
- Sqlite3 and Postgres database integrations
- Subscriptions
- Authentication/Authorization
- Sessions
- Tests
- File uploads
- Client/Server GraphQL extensions integration
- Docker
- Send/receive/delete messages in realtime
- File uploads
- Link metadata
- Reply to other messages
- Client cache through Ferry and Hive
- Create chat rooms, add/remove users and share authorized invite links
- View complete usage history with events for the most important mutations
- View all user sessions
A Leto/Shelf server example with multiple models, code generation, some utilities and tests can be found in https://github.com/juancastillo0/leto/tree/main/leto_shelf/example
A service with room and messages, an user can subscribe to a room to listen to messages and send private or group-wide messages. Useful for simple messages or setting up peer-to-peer protocols like WebRTC. The service uses web sockets and in the source code repository there are three projects:
- The Leto Shelf GraphQL server. Everything is saved in memory
- A Dart client using Artemis
- A Web Dart client using
package:rad
You can view the code in the Github repo. The client UI and some links to the different GraphQL Schema UI explorer is deployed in this page.
Work in Progress
A service for compiling, executing and tracking the build process and deployment. With a git repository, one can set up a CLI pipeline for continuous integration and delivery. All the commands are tracked in realtime. This is a simple personal project for deploying in a VM. The service uses web sockets and the source code repository has three projects:
- The Leto Shelf GraphQL server. Everything is saved in memory
- A Dart client using
package:graphql
andpackage:graphql_codegen
- A Web Dart client using
package:jaspr
You can view the code in the Github repo. The client UI and some links to the different GraphQL Schema UI explorer is deployed in this page.
This repository is a monorepo with the following packages
Pub | Source | Description |
---|---|---|
leto | GraphQL server (executor) implementation, GraphQL extensions and DataLoader | |
leto_schema | Define GraphQL executable schemas, validate GraphQL documents and multiple utilities | |
leto_generator | Generate GraphQL schemas, types and fields from Dart code annotations | |
leto_shelf | GraphQL web server bindings and utilities for shelf | |
leto_links | Client gql links, support for GraphQL extensions defined in package:leto |
Although you can use package:leto_schema
to create and validate schemas and package:leto
to execute GraphQL requests in any Dart application, GraphQL servers are usually deployed to the web. We provide a couple of utilities and integrations for creating and using GraphQL web servers powered by Leto.
Using the shelf package.
- HTTP POST and GET
- Mutipart requests for file Upload.
- Subscriptions through WebSockets. Supporting graphql-ws and graphql-transport-ws subprotocols
- Batched queries
- TODO: HTTP/2 example
- TODO: Server-Sent Events
These web pages will allow you to explore your GraphQL Schema, view all the types and fields, read each element's documentation, and execute requests against a GraphQL server.
Usually exposed as static HTML in your deployed server. Each has multiple configurations for determining the default tabs, queries and variables, the GraphQL HTTP and WebSocket (subscription) endpoints, the UI's theme and more.
All of the static HTML files and configurations can be found in the graphql_ui folder.
Documentation. Use graphiqlHandler
. The classic GraphQL explorer
Documentation. Use playgroundHandler
. Support for multiple tabs, subscriptions.
Documentation. Use altairHandler
. Support for file Upload, multiple tabs, subscriptions, plugins.
For a complete GraphQL client you probably want to use:
-
Artemis (https://github.com/comigor/artemis)
-
package:graphql
(https://pub.dev/packages/graphql) withpackage:graphql_codegen
(https://pub.dev/packages/graphql_codegen) -
or raw gql Links (https://github.com/gql-dart/gql/tree/master/links)
gql Links are used by Ferry and Artemis, both of which provide additional functionalities over raw gql Links like serialization and deserialization, code generation, type safety, normalized caching and more.
The following sections introduce most of the concepts and small examples of building GraphQL executable schemas and servers with Leto. Please, if there is something that may be missing from the documentation or you have any question you can make an issue, that would help us a lot.
If your prefer to read the documentation in a web page, you can try the documentation page built with Docusaurus.
The GraphQL language provides multiple types for representing your exposed API and the required data structures for the input values. In the following sections we explain their usage within Leto and, in general, for GraphQL. Each section contains a link to the official GraphQL specification for more information.
The fundamental building-block in the type system. Standard GraphQLScalarType
s: String, Int, Float, Boolean and ID types are already implemented and provided by Leto.
Other scalar types are also provided:
- Json: A raw JSON value with no type schema. Could be a Map<String, Json>, List<Json>, num, String, bool or null.
- Uri: Dart's Uri class, serialized using
Uri.toString
and deserialized withUri.parse
- Date: Uses the
DateTime
Dart class. Serialized as an ISO-8601 String and deserialized withDateTime.parse
. - Timestamp: Same as Date, but serialized as an UNIX timestamp.
- Time: // TODO: 1A
- Duration: // TODO: 1A
- BigInt: An arbitrarily large integer from
dart:core
serialized as a String and deserialized withBigInt.parse
. - Upload: A file upload. Following the multipart request spec.
To provide your own or support types from other packages you can use Custom Scalars.
Enums are text values which are restricted to a set of predefined variants. Their behavior is similar to scalars and they don't have a nested fields.
They require a unique name and a set of entries mapping their string representation to the Dart value obtained after parsing.
"""The error reason on a failed sign up attempt"""
enum SignUpError {
usernameTooShort,
usernameNotFound,
wrongPassword,
passwordTooSimple,
}
import 'package:leto/leto.dart';
final signUpErrorGraphQLType = enumTypeFromStrings(
'SignUpError',
[
'usernameTooShort',
'usernameNotFound',
'wrongPassword',
'passwordTooSimple',
],
description: 'The error reason on a failed sign up attempt',
);
// Or with code generation
/// The error reason on a failed sign up attempt
@GraphQLEnum()
enum SignUpError {
usernameTooShort,
usernameNotFound,
wrongPassword,
passwordTooSimple,
}
GraphQL objects allow you to specify a type with a set of fields or properties. Objects can only be outputs in a resolver. Each field can be of any output type.
The Query, Mutation and Subscription types in the schema are specified using GraphQL objects.
final type = objectType(
'ObjectTypeName',
fields: [],
);
- With code generation
@GraphQLObject()
@JsonSerializable()
class Model {
final String stringField;
final int intField;
final List<Model>? optionalModels;
const Model({
required this.stringField,
required this.intField,
required this.optionalModels,
});
}
@Query
Future<Model> getModel(Ctx ctx) {
}
This would generate graphql_api.schema.dart
- inheritFrom
The inheritFrom
function in GraphQLObjectType
receives an Interface and assigns it's argument as
a super type, now the Object will implement the Interface passed as parameter.
Input types specify the structure of the values that inputs to resolvers should have. Scalars and Enums can be passed as input to resolvers. Wrapper types such as List and NonNull types of Scalars and Enums, also can be passed, however for more complex Objects with nested fields you will need to use GraphQLInputObjectType
. Similar GraphQLObjectType
, a GraphQLInputObjectType
can have fields.
// TODO: 1A customDeserialize with SerdeCtx deserializers
final inputModel = GraphQLInputObjectType(
'ModelInput',
description: '',
inputs: [
],
);
Field inputs (or Arguments) can be used in multiple places:
-
GraphQLObjectType.fields.inputs
: Inputs in field resolvers -
GraphQLInputObjectType.fields
: Fields in Input Objects -
GraphQLDirective.inputs
: Inputs in directives
Not all types can be input types, in particular, object types and union types can't be input types nor part of a GraphQLInputObjectType
.
static bool isInputType(GraphQLType type) {
return type.when(
enum_: (type) => true,
scalar: (type) => true,
input: (type) => true,
object: (type) => false,
union: (type) => false,
list: (type) => isInputType(type.ofType),
nonNullable: (type) => isInputType(type.ofType),
);
}
input ComplexInput {
value: String!
}
# The fields:
(
"""The amount"""
@deprecated
amount: Int = 2
names: [String!]
complex: ComplexInput!
)
@GraphQLInput()
class ComplexInput {
const ComplexInput({required this.value});
/// The value
final String value;
factory ComplexInput.fromJson(Map<String, Object?> json) =>
ComplexInput(
value: json['value']! as String,
);
}
final fields = [
GraphQLFieldInput(
'amount',
graphQLInt,
defaultValue: 2,
description: 'The amount',
// an empty String will use the default deprecation reason
deprecationReason: '',
),
GraphQLFieldInput(
'names',
listOf(graphQLString.nonNull()),
),
GraphQLFieldInput(
'complex',
complexInputGraphQLInputType.nonNull(),
),
];
// can be used in:
// - `GraphQLObjectType.fields.inputs`
// - `GraphQLInputObjectType.fields`
// - 'GraphQLDirective.inputs'
final object = GraphQLObjectType(
'ObjectName',
fields: [
stringGraphQLType.field(
'someField',
inputs: fields,
resolve: (_, Ctx ctx) {
final Map<String, Object?> args = ctx.args;
assert(args.containKey('complex'));
assert(args['names'] is List<String>?);
assert(args['amount'] is int?);
return '';
}
)
]
);
final objectInput = GraphQLInputObjectType(
'InputObjectName',
fields: fields,
// ...
);
final directive = GraphQLDirective(
name: 'DirectiveName',
inputs: fields,
// ...
);
oneOf input object types allow you to specify that an object should contain only one of the provided fields. The fields should be nullable and should not have a default value. This is similar to union types. However, oneOf input types can be used as inputs and their variants (or fields) can be any input type such as a custom scalar, they are not constrained to object types.
input EmailPassword {
email: String!
password: String!
}
input LogInOption @oneOf {
email: EmailPassword
token: String
}
type Mutation {
login(option: LogInOption!): Boolean!
}
mutation loginMut {
login(option: { email: { email: "email@example.com" password: "pass" } })
}
For code generation, each class annotated as GraphQLInput
should have a factory constructor or static method name fromJson
in its class definition. This will be used as the method for deserializing instances of this class.
Similar to enums, Unions are restricted to a set of predefined variants, however the possible types are always the more complex GraphQLObjectType
.
Per the GraphQL spec, Unions can't be (or be part of) Input types and their possible types is a non empty collection of unique GraphQLObjectType
.
To have the following GraphQL type definitions:
union ModelEvent = ModelAdded | ModelRemoved
type ModelRemoved {
"The removed model id"
modelId: ID!
}
type ModelAdded {
model: Model!
}
type Model {
id: ID!
}
You could provide this definitions:
import 'package:leto_schema/leto_schema.dart';
final model = objectType(
'Model',
fields: [
graphQLIdType.nonNull().field('id'),
],
);
final modelAddedGraphQLType = objectType(
'ModelAdded',
fields: [model.nonNull().field('model')],
);
final modelRemovedGraphQLType = objectType(
'ModelRemoved',
fields: [graphQLIdType.nonNull().field('modelId')],
);
final union = GraphQLUnionType(
// name
'ModelEvent',
// possibleTypes
[
modelAddedGraphQLType,
modelRemovedGraphQLType,
],
);
extractInner
When the members of the union type are not
With code generation, Unions with freezed also work without trouble.
import 'package:leto_schema/leto_schema.dart';
import 'package:freezed_annotation/freezed_annotation.dart';
@GraphQLObject()
class Model {
final String id;
const Model(this.id);
}
@GraphQLObject()
@freezed
class ModelEvent with _$ModelEvent {
const factory ModelEvent.added(Model model) = ModelAdded;
const factory ModelEvent.removed(
@GraphQLDocumentation(type: 'graphQLIdType', description: 'The removed model id')
String modelId,
// you can also provide a private class
) = _ModelRemoved;
}
GraphQLAttachments unionNoFreezedAttachments() => const [ElementComplexity(50)];
@AttachFn(unionNoFreezedAttachments)
@GraphQLDocumentation(
description: '''
Description from annotation.
Union generated from raw Dart classes''',
)
@GraphQLUnion(name: 'UnionNoFreezedRenamed')
class UnionNoFreezed {
const factory UnionNoFreezed.a(String value) = UnionNoFreezedA.named;
const factory UnionNoFreezed.b(int value) = UnionNoFreezedB;
}
@GraphQLObject()
class UnionNoFreezedA implements UnionNoFreezed {
final String value;
const UnionNoFreezedA.named(this.value);
}
@GraphQLObject()
class UnionNoFreezedB implements UnionNoFreezed {
final int value;
const UnionNoFreezedB(this.value);
}
@Query()
List<UnionNoFreezed> getUnionNoFrezzed() {
return const [UnionNoFreezed.a('value'), UnionNoFreezed.b(12)];
}
Wrapping types allow to modify the behavior of the inner (wrapped) type. The inner types can be of any GraphQLType
and wrapping types can be Output or Input Types if the wrapped type is an Output or Input type. GraphQL has two wrapping types, GraphQLNonNullType
and GraphQLListType
.
GraphQLNonNullType
allows you to represent a non-nullable or required value. By default, all GraphQL Types are nullable or optional, if you want to represent a required input or specify that a given output is always present (non-null), you want to use the GraphQLNonNullType
wrapping type.
In GraphQL this is represented using the !
exclamation mark after a given type expression. In Dart you can use the nonNull()
method present in each GraphQLType
, which will return a non-nullable GraphQLNonNullType
with it's inner type, the type from which nonNull
was called. For example, graphQLString.nonNull()
will be a String!
in GraphQL.
GraphQLListType
allows you to represent a collection of values.
This values can be of any GraphQLType
and List types can be Output or Input Types if the Wrapped type is an Output or Input type. For example, a List of Union types is an Output type while a List of Strings (scalar types) can be an Output or Input type. You can use the <type>.list()
method present in each GraphQLType
or the listOf(<type>)
global utility function to create a GraphQLListType
. For example, graphQLString.list()
will be a [String]
in GraphQL.
In GraphQL, you can represent it like this:
type Model {
listField(listInput: [String]!): [InterfaceModel!]
}
interface InterfaceModel {
name: String
}
Using Dart:
import 'package:leto_schema/leto_schema.dart';
abstract class InterfaceModel {
String get name;
}
class Model {
List<InterfaceModel>? list(List<String?> listInput) {
throw Unimplemented();
}
}
final interfaceModel = objectType<InterfaceModel>(
'InterfaceModel',
fields: [
graphQLString.field(
'name',
resolve: (InterfaceModel obj, Ctx ctx) => obj.name,
)
],
isInterface: true,
);
final model = objectType<Model>(
'Model',
fields: [
interfaceModel.nonNull().list().field(
'listField',
inputs: [
listOf(graphQLString).nonNull().inputField('listInput'),
],
resolve: (Model obj, Ctx ctx) =>
obj.listField(ctx.args['listInput'] as List<String?>)
)
]
);
With code generation, you just annotate the different classes with @GraphQLObject()
(or the expected annotation) and the fields and models containing Dart Lists or non-nullable types will be generated using GraphQLListType
or GraphQLNonNullType
as required.
import 'package:leto_schema/leto_schema.dart';
@GraphQLObject()
abstract class InterfaceModel {
String get name;
}
@GraphQLObject()
class Model {
List<InterfaceModel>? list(List<String?> listInput) {
throw Unimplemented();
}
}
Abstract types like Interfaces and Unions, require type resolution of its variants on execution. For that, we provide a couple of tools explained in the following sections. You can read the code that executes the following logic in package:leto's GraphQL.resolveAbstractType
method.
A parameter of Interface and Union types is a function with the signature: String Function(Object result, T abstractType, ResolveObjectCtx ctx)
. Given a resolved result, the abstract type itself and the ObjectCtx, return the name of the type associated with the result value.
We compare the resolved result's Dart type with the possible types generic type parameter, if there is only one match (withing the possible types), that will be the resolved type. This happens very often, specially with code generation or when providing a distinct class for each GraphQLObjectType
.
This can't be used with Union types which are wrappers over the inner types (like Result<V, E>
or Either<L, R>
), since generic type of the possible types (V
and E
) will not match the wrapper type (Result
). For this cases you will need to provide a resolveType
and extractInner
callbacks. With freezed-like unions you don't have to do that since the variants extend the union type.
If any of the previous fail, you can provide a isTypeOf
callback for objects, which determine whether a given value is an instance of that GraphQLObjectType
.
If the resolved result is a Map
and contains a key "__typename", we will use it to resolve the type by comparing it with possible types names. If there is a match, we use the matched type in the next steps of execution.
- PageInfo: Following the relay connections spec.
Types which use themselves in their definition have to reuse previously created instances. The type's field lists are mutable, which allow you to instantiate the type and then modify the fields of the type. For example, an User with friends:
class User {
const User(this.friends);
final List<User> friends;
}
GraphQLObjectType<User>? _type;
GraphQLObjectType<User> get userGraphQLType {
if (_type != null) return _type; // return a previous instance
final type = objectType<User>(
'User',
// leave fields empty (or don't pass them)
fields: [],
);
_type = type; // set the cached value
type.fields.addAll([ // add the fields
listOf(userGraphQLType.nonNull()).nonNull().field(
'friends',
resolve: (obj, _) => obj.friends,
),
]);
return type;
}
Code generation already does it, so you don't have to worry about it when using it.
You can extend the GraphQLScalarType
or create an instance directly with GraphQLScalarTypeValue
. For example, to support the Decimal
type from https://github.com/a14n/dart-decimal you can use the following code:
import 'package:decimal/decimal.dart';
import 'package:leto_schema/leto_schema.dart';
export 'package:decimal/decimal.dart';
final decimalGraphQLType = GraphQLScalarTypeValue<Decimal, String>(
name: 'Decimal',
deserialize: (_, serialized) => decimalFromJson(serialized)!,
serialize: (value) => decimalToJson(value)!,
validate: (key, input) => (input is num || input is String) &&
Decimal.tryParse(input.toString()) != null
? ValidationResult.ok(input.toString())
: ValidationResult.failure(
['Expected $key to be a number or a numeric String.'],
),
description: 'A number that allows computation without losing precision.',
specifiedByURL: null,
);
Decimal? decimalFromJson(Object? value) =>
value == null ? null : Decimal.parse(value as String);
String? decimalToJson(Decimal? value) => value?.toString();
For code generation you need to provide customTypes
in the build.yaml file of you project:
target:
default:
builders:
leto_generator:graphql_types:
options:
customTypes:
- name: "Decimal"
import: "package:<your_package_name>/<path_to_implementation>.dart"
getter: "decimalGraphQLType"
leto_generator:graphql_resolvers:
options:
customTypes:
- name: "Decimal"
import: "package:<your_package_name>/<path_to_implementation>.dart"
getter: "decimalGraphQLType"
Work in progress
class ErrC<T> {
final String? message;
final T value;
const ErrC(this.value, [this.message]);
}
GraphQLObjectType<ErrC<T?>> errCGraphQlType<T extends Object>(
GraphQLType<T, Object> tGraphQlType, {
String? name,
}
) {
return objectType(
name ?? 'ErrC${tGraphQlType is GraphQLTypeWrapper ? (tGraphQlType as GraphQLTypeWrapper).ofType : tGraphQlType}',
isInterface: false,
interfaces: [],
description: null,
fields: [
field('message', graphQLString,
resolve: (obj, ctx) => obj.message,),
field('value', tGraphQlType,
resolve: (obj, ctx) => obj.value,)
],
);
}
- With code generation
import 'package:leto/leto.dart';
part 'errc.g.dart';
@GraphQLObject()
class ErrC<T> {
final String? message;
final T value;
const ErrC(this.value, [this.message]);
}
Which generates in 'errc.g.dart':
Map<String, GraphQLObjectType<ErrC>> _errCGraphQlType = {};
/// Auto-generated from [ErrC].
GraphQLObjectType<ErrC<T>> errCGraphQlType<T extends Object>(
GraphQLType<T, Object> tGraphQlType,
) {
final __name =
'ErrC${tGraphQlType is GraphQLTypeWrapper ? (tGraphQlType as GraphQLTypeWrapper).ofType : tGraphQlType}';
if (_errCGraphQlType[__name] != null)
return _errCGraphQlType[__name]! as GraphQLObjectType<ErrC<T>>;
final __errCGraphQlType = objectType<ErrC<T>>(
'ErrC${tGraphQlType is GraphQLTypeWrapper ? (tGraphQlType as GraphQLTypeWrapper).ofType : tGraphQlType}',
isInterface: false,
interfaces: [],
description: null);
_errCGraphQlType[__name] = __errCGraphQlType;
__errCGraphQlType.fields.addAll(
[
field('message', graphQLString,
resolve: (obj, ctx) => obj.message,
inputs: [],
description: null,
deprecationReason: null),
field('value', tGraphQlType.nonNull(),
resolve: (obj, ctx) => obj.value,
inputs: [],
description: null,
deprecationReason: null)
],
);
return __errCGraphQlType;
}
GraphQL resolvers execute the logic for each field and return the expected value typed according to the schema. In Dart this are functions that receive the parent's object value and the field's Ctx
, and return the execution result. Simple fields may only return a property of the parent object value. However, there may also be complex resolvers, such as mutations, that validate the input data and create rows in a database, or queries that retrieve multiple rows according to complex authorization logic.
Each field (GraphQLObjectField
) in an object type (GraphQLObjectType
) contains a resolve
parameter, this will be used to resolve all fields. The first argument to resolve
with be the parent object, if this field is in the root Query or Mutation Object, the value will be the the root value passed as an argument to GraphQL.parseAndExecute
and a SubscriptionEvent
if this is a subscription field (more in the subscription section). The second argument will be the field's Ctx
, with it you can access defined Refs with Ref.get(ctx)
and view more information about the resolved field or GraphQL request. When using package:leto_shelf
, you can access the HTTP request and modify the HTTP response, more information in the package's README.
type Query {
someField: String
}
type CustomMutation {
updateSomething(arg1: Float): Date
}
"""An ISO-8601 Date."""
scalar Date
type schema {
query: Query
mutation: CustomMutation
}
In Dart:
final query = objectType(
'Query',
fields: [
graphQLString.field(
'someField',
resolve: (Object? rootObject, Ctx ctx) => 'someFieldOutput',
),
],
);
final customMutation = objectType(
'CustomMutation',
fields: [
graphQLDate.field(
'updateSomething',
inputs: [
graphQLFloat.inputField('arg1')
],
resolve: (Object? rootObject, Ctx ctx) {
final arg1 = ctx.args['arg1'] as double?;
return DateTime.now();
},
),
],
);
final schema = GraphQLSchema(
queryType: query,
mutation: customMutation,
);
When using package:leto_shelf
, POST requests can be used for Queries or Mutations. However, GET requests can only be used for Queries, if a Mutation operation is sent using a GET request, the server will return a 405 status code (MethodNotAllowed) following the GraphQL over HTTP specification.
Each field (GraphQLObjectField
) in an object type (GraphQLObjectType
) contains a subscribe
parameter that receives the root value and a Ctx
, and returns a Stream of values of the field's type Stream<T> Function(Ctx<P> ctx, P parent)
. The Stream of values will be returned in the data
field of the GraphQLResult
returned on execution.
If using a WebSocket server, the client should support either graphql-transport-ws
or graphql-ws
sub-protocols.
final apiSchema = GraphQLSchema(
queryType: objectType('Query'),
subscriptionType: objectType(
'Subscription',
fields: [
graphQLInt.nonNull().fields(
'secondsSinceSubscription',
subscribe: (Ctx ctx, Object rootValue) {
return Stream.periodic(const Duration(seconds: 1), (secs) {
return secs;
});
}
),
]
),
);
Future<void> main() async {
final GraphQLResult result = await GraphQL(apiSchema).parseAndExecute(
'subscription { secondsSinceSubscription }',
);
assert(result.isSubscription);
final Stream<GraphQLResult> stream = result.subscriptionStream!;
stream.listen((event) {
final data = event.data as Map<String, Object?>;
assert(data['secondsSinceSubscription'] is int);
print(data['secondsSinceSubscription']);
});
}
The resolve
callback in a subscription field will always receive a SubscriptionEvent
as it's parent.
From that you can access the event value with SubscriptionEvent.value
which will be the emitted by the Stream returned in the subscribe
callback. The error handling in each callback is different, if an error is thrown in the subscribe
callback, the Stream will end with an error. But if you throw an error in the resolve
callback it will continue sending events, just the event resolved with a thrown Object will have GraphQLError
s as a result of processing the thrown Object (More information in Error Handling).
For usage in a web server you can use any of the web server integrations which support WebSocket subscriptions (For example, leto_shelf).
For a complete subscriptions example with events from a database please see the chat_example, in particular the events directory.
All Ctx
s implement ScopedHolder
, so that then can be used to retrieve values from the scoped map, more in ScopedMap
.
A unique context for each field resolver
- args: the arguments passed as inputs to this field
- object: the parent Object's value, same as the first parameter of
resolve
. - objectCtx: the parent Object's execution context (ObjectExecutionCtx)
- field: The
GraphQLObjectField
being resolved - path: The path to this field
- executionCtx: The request's execution context (ExecutionCtx)
- lookahead: A function for retrieving nested selected fields. More in the LookAhead section
This is the context associated with an object execution, can be retrieved through Ctx.objectCtx
. There will be as many instances as there are objects to execute in the request. Contains the value of the object, the field selections and the path in the GraphQL request to this object.
This is the context associated with the execution phase of the request, created after the validation phase.
Contains validated and coerced (parsed) input values and the specific validated operation within the request's document to execute. It has an errors
list with the encountered errors during execution. Can be retrieved with ObjectExecutionCtx.executionCtx
.
This is the base context associated with the request, contains the raw information about the GraphQL document, the raw (not validated nor parsed) input values, input extensions, the schema, root value and the scoped map for this request. Can be retrieved with ExecutionCtx.requestCtx
.
Implements the "Type Validation" sub-sections of the specification's "Type System" section.
Guaranties that the GraphQLSchema
instance is valid, verifies the Type System validations in the specification. For example, an Object field's type can only be an Output Type or an Union should have at least one possible type and all of them have to be Object types.
This will be executed before stating a GraphQL server. Leto implements all of the Specification's schema validation. The code for all rules can be found in the validate_schema.dart file in package:leto_schema
.
This will be executed before executing any request. Leto implements all of the Specification's document validation. The code for all rules can be found in the validate folder in package:leto_schema
.
You can add custom validation rules to a server with the GraphQL.customValidationRules
parameter, they will be added on top of the specifiedValidationRules
. One example of a custom validation rule is the Query Complexity validation.
This document validation rule allows you to restrict the complexity of a GraphQL request.
The provided queryComplexityRuleBuilder
returns a ValidationRule
that reports errors when the maxComplexity
or maxDepth
configuration parameters are reached.
maxComplexity
Specifies the maximum complexity for a given operation. The complexity is measured based on the selected fields and should be. If this complexity is surpassed (is greater) a validation error will be reported.
maxDepth
Specifies the maximum depth for a given operation. The depth is defined as the number of objects (including the root operation object) that have to be traversed to arrive to a given field. If this depth is surpassed (is greater) a validation error will be reported.
The complexity for each fieldNode is given by:
complexity = fieldComplexity + (childrenComplexity + fieldTypeComplexity) * complexityMultiplier
Where fieldComplexity is the ElementComplexity
in
GraphQLObjectField.attachments
or defaultFieldComplexity
if there aren't any.
childrenComplexity is:
- scalar or enum (leaf types): 0
- object or interface: sum(objectFieldsComplexities)
- union: max(possibleTypesComplexities)
fieldTypeComplexity will be taken as the ElementComplexity
from GraphQLNamedType.attachments
or 0 if there aren't any.
If the fieldType is a GraphQLListType
, complexityMultiplier
will be the provided listComplexityMultiplier
, otherwise 1.
TODO: 1A
Using the PersistedQueriesExtensions
you can set the skipValidation
parameter so that the validation is skipped for already cached (and validated) documents.
Input validation refers to the verification of the values or structure of the payload sent as input in a request. It could, of coursed, be performed manually before the execution of each request. However, we provide a couple of tools to help with the process, in particular using code generation and the valida
package.
The following example shows an input object ConnectionArguments
with the annotations @Valida()
and its fields first
and last
with the annotation @ValidaNum(min: 1)
. If the ConnectionArguments
object is used as input in a resolver, the validation is performed over the input value on execution and an error will be thrown if either first
or last
are less than 1. For more information on the supported annotations and validations, view the valida
package.
@JsonSerializable()
@Valida()
@GraphQLInput()
class ConnectionArguments {
/// Returns the items in the list that come before the specified cursor.
final String? before;
/// Returns the items in the list that come after the specified cursor.
final String? after;
/// Returns the first n items from the list.
@ValidaNum(min: 1)
final int? first;
/// Returns the last n items from the list.
@ValidaNum(min: 1)
final int? last;
const ConnectionArguments({
this.before,
this.after,
this.first,
this.last,
});
factory ConnectionArguments.fromJson(Map<String, Object?> json) =>
_$ConnectionArgumentsFromJson(json);
Map<String, Object?> toJson() => _$ConnectionArgumentsToJson(this);
}
The returned GraphQLResult
is the output of the execution of a GraphQL request it contains the encountered GraphQLError
s, the output extensions
and the data
payload. The GraphQLResult.toJson
Map is used by package:leto_shelf
when constructing an HTTP response's body.
-
The
data
is aMap<String, Object?>?
for Queries and Mutations or aStream<GraphQLResult>
for subscriptions. It has the payload returned by the resolvers during execution. Will be null if there was an error in validation or in the execution of a non-nullable root field. If there was an error in validation, thedata
property will not be set in theGraphQLResult.toJson
Map following the spec. -
The
errors
contain theGraphQLError
s encountered during validation or execution. If a resolver throws an error, it will appear in this error list. If the field's return type is nullable, a null value will be set as the output for that field. If the type is non-nullable the resolver will continue to throw an exception until a nullable field is reached or the root resolver is reached (in this case theGraphQLResult.data
property will be null). -
The
extensions
is aMap<String, Object?>?
with custom values that you may want to provide to the client. All values should be serializable since they may be returned as part of an HTTP response. MostGraphQLExtensions
modify this values to provide additional functionalities. The keys for theextensions
Map should be unique, you may want to prefix them with an identifier such as a package name.
An ScopedMap
allows you to pass and use dependencies or services within your resolvers or extensions. It consists of multiple maps, one for each scope, and a set of immutable references (or keys) with overridable defaults.
To retrieve a value from a reference, the map checks whether a value was already instantiated for the scope or in any of its parents. If it has not been instantiated, the default is returned and saved in the scope.
This forms a tree of scopes, where one node scope has access to its parent values.
To override the value of a reference for a given scope you instantiate a ScopedMap
with the values to override, if it is a child, you can pass the parent as a parameter to the constructor.
A ScopedHolder
is simply an object that contains a ScopedMap get globals;
getter. This map represents the scope associated with the object. As discussed in the Request Contexts section, all contexts are (implement) ScopedHolder
s and therefore have access to the values in the scope.
You can specify the behavior and the default values of references using ScopedRef
. As explained in the source code docs, a "global" ref will instantiate a value accessible to all scopes in a scope tree. A "local" ref will instantiate the value (and make it accessible) only to children scopes in which the value is instantiated.
Example usage with the GraphQL
executor and different ways to override the values is shown in the following code snippet:
final ScopedRef<int> ref = ScopedRef.global((ScopedMap scope) => 4);
final schema = GraphQLSchema(
queryObject: objectType(
'Query',
fields: [
graphQLint.field('fieldName', (ctx) => ref.get(ctx)),
],
),
);
final executorWithDefault = GraphQL(schema);
var result = await executorWithDefault.parseAndExecute('{fieldName}');
var data = result.data as Map<String, Object?>;
assert(data['fieldName'] == 4);
result = await executorWithDefault.parseAndExecute(
'{fieldName}',
globalVariables: {
ref: 6,
},
);
data = result.data as Map<String, Object?>;
assert(data['fieldName'] == 6);
final executorWithOverride = GraphQL(
schema,
globalVariables: ScopedMap(
{
ref: 5,
},
),
);
result = await executorWithOverride.parseAndExecute('{fieldName}');
data = result.data as Map<String, Object?>;
assert(data['fieldName'] == 5);
One typically has multiple options to represent and let the client know that there was an error in the request.
If using HTTP (or WebSockets) fatal errors such as a malformed query string are already handled and follow the spec in each case.
If an error does not require a different type to be expressed and a more implicit approach is preferable, perhaps for errors that happen in most endpoints (authentication, authorization, input validation), one can use exceptions and send the necessary information through custom extensions in the payload.
@Query()
Future<int> userChats(Ctx ctx) async {
final user = await userFromCtx(ctx);
if (user == null) {
throw GraphQLError(
'This endpoint requires an authenticated user.', // message
extensions: {
'appError': {
'code': 'UNAUTHENTICATED',
},
},
// You can also pass a `sourceError` and `stackTrace` if the given error
// was generated from an exception
// sourceError,
// stackTrace,
);
}
// You could also throw a list of errors with GraphQLException
final errors = [
if (!user.emailVerified)
GraphQLError(
'This functionality requires that you verify your email.', // message
extensions: {
'appError': {
'code': 'UNVERIFIED_EMAIL',
},
},
),
if (!user.canReadUserChats)
GraphQLError(
'You do not have access to this functionality.', // message
extensions: {
'appError': {
'code': 'UNAUTHORIZED',
},
},
),
];
if (errors.isNotEmpty) throw GraphQLException(errors);
// AUTHORIZED, now get the userChats
}
Of course, this could be abstracted and structured in a better way. For example, the "UNAUTHENTICATED" error could be a constant or it could be thrown inside userFromCtx(ctx)
call. The appError
key could be anything you want, but is has to be unique to avoid overriding other extensions.
- Result
"""
SomethingT! when the operation was successful or SomethingE! when an error was encountered.
"""
type ResultSomethingTSomethingE {
ok: SomethingT
err: SomethingE
isOk: Boolean!
}
- ResultU
"""
SomethingT when the operation was successful or SomethingE when an error was encountered.
"""
union ResultUSomethingTSomethingE = SomethingT | SomethingE
The error in the result union or object could be a simple object specific to the resolver. However, it could also by an union, an object that implements an "ApplicationError" interface or a list of errors, where the errors could also be of union type or objects that implement interfaces, or both. For a more thorough discussion on the topic, this guide to GraphQL errors may help you.
Since type and field schema definitions should probably be reused, this may pose a conflict to the beautifully hot reload capabilities of Dart. The cached instances will not change unless you execute the more expensive hot restart, which may also cause you to lose other state when developing.
Because of this, we provide an utility class HotReloadableDefinition
that handles definition caching, helps with cycles in instantiation and controls the re-instantiation of values. It receives a create
function that should return a new instance of the value. This value will be cached and reused throughout the schema's construction. To retrieve the current instance you can use the HotReloadableDefinition.value
getter.
The provided create
function receives a setValue
callback that should be called right after the instance's creation (with the newly constructed instance as argument), this is only necessary if the instance definition may contain cycles.
To re-instantiate all values that use HotReloadableDefinition
you can execute the static HotReloadableDefinition.incrementCounter
which will invalidate previously created instances, if you call HotReloadableDefinition.value
again, a new instance will be created with the, potentially new, hot reloaded code.
When using code generation all schema definitions use the HotReloadableDefinition
class to create type and field instances, you only need to call the generated recreateGraphQLApiSchema
function to instantiate the GraphQLSchema
each time the application hot reloads.
You can use other packages to hot reload the dart virtual machine (vm), for example:
-
If using shelf you may want to try https://pub.dev/packages/shelf_hotreload. Most shelf examples in this repository already use this package.
-
You could also search in https://pub.dev or try https://pub.dev/packages/hotreloader, which is used by
package:shelf_hotreload
.
When fetching nested fields, a specific resolvers could be executed multiple times for each request since the parent object will execute it for all its children. This may pose a problem when the resolver has to do non-trivial work for each execution. For example, retrieving a row from a database. To solve this problem, Leto provides you with two tools: LookAhead and DataLoader.
You can mitigate the N+1 problem by fetching all the necessary information from the parent's resolver so that when the nested fields are executed they just return the previously fetch items. This would prevent all SQL queries for nested fields since the parent resolver has all the information about the selected nested fields and can use this to execute a request that fetches the necessary columns or joins.
@GraphQLObject()
class Model {
final String id;
final String name;
final NestedModel? nested;
const Model(this.id, this.name, this.nested);
}
@GraphQLObject()
class NestedModel {
final String id;
final String name;
const NestedModel(this.id, this.name);
}
final modelRepo = ScopedRef.global(
(ScopedHolder scope) => ModelRepo();
);
class ModelRepo {
List<Model> getModels({bool withNested = false}) {
// request the database
// if `withNested` = true, join with the `nestedModel` table
throw Unimplemented();
}
}
@Query()
FutureOr<List<Model>> getModels(Ctx ctx) {
final PossibleSelections lookahead = ctx.lookahead();
assert(!lookahead.isUnion);
final PossibleSelectionsObject lookaheadObj = lookahead.asObject;
final withNested = lookaheadObj.contains('nested');
final ModelRepo repo = modelRepo.get(ctx);
return repo.getModels(withNested: withNested);
}
With this implementation and given the following queries:
query getModelsWithNested {
getModels {
id
name
nested {
id
name
}
}
}
query getModelsBase {
getModels {
id
name
}
}
ModelRepo.getModels
will receive true
in the withNested
param for the getModelsWithNested
query since lookaheadObj.contains('nested')
will be true
. On the other hand, the withNested
param will be false
for the getModelsBase
query since the "nested" field was not selected.
In this way, ModelRepo.getModels
knows what nested fields it should return. It could add additional joins in a SQL query, for example.
The PossibleSelections
class has the information about all the nested selected fields when the type of the field is a Composite Type (Object, Interface or Union). When it's an Union, it will provide a map from the type name Object variants to the given variant selections. The @skip and @include directives are already taken into account. You can read more about the PossibleSelections
class in the source code.
The code in Leto is a port of graphql/dataloader.
An easier to implement but probably less performant way of solving the N+1 problem is by using a DataLoader
. It allows you to batch multiple requests and execute the complete batch in a single function call.
@GraphQLObject()
class Model {
final String id;
final String name;
final int nestedId;
const Model(this.id, this.name, this.nestedId);
NestedModel nested(Ctx ctx) {
return modelNestedRepo.get(ctx).getNestedModel(nestedId);
}
}
class NestedModelRepo {
late final dataLoader = DataLoader.unmapped<String, NestedModel>(getNestedModelsFromIds);
Future<List<NestedModel>> getNestedModel(String id) {
// Batch the id, eventually `dataLoader` will execute
// `getNestedModelsFromIds` with a list of batched ids
return dataLoader.load(id);
}
Future<List<NestedModel>> getNestedModelsFromIds(List<String> ids) {
// Multiple calls to `Model.nested` will be batched and
// all ids will be passed in the `ids` argument
// request the database
final List<NestedModel> models = throw Unimplemented();
// Make a map from id to model instance
final Map<String, NestedModel> modelsMap = models.fold(
{}, (map, model) => map..[model.id] = model
);
// Return the models in the same order as the `ids` argument
return List.of(ids.map((id) => modelsMap[id]!));
}
}
final modelNestedRepo = ScopedRef.local(
(scope) => NestedModelRepo()
);
@Query()
List<Model> getModels(Ctx ctx) {
return modelRepo.get(ctx).getModels();
}
The DataLoader has some options for configuring it. For example you can specify the maximum size of the batch (default: 2^53
or the maximum javascript integer), whether to batch requests or not (default: true
) and provide a custom batch schedule function, by default it will use Future.delayed(Duration.zero, executeBatch)
.
You can also configure caching by providing a custom cache implementation, a custom function that maps the key passed to DataLoader.load
to the cache's key or disabling caching in the DataLoader.
You can use both, LookAhead and DataLoader at the same time. The keys provided to the DataLoader.load
function can be anything, so you could send the PossibleSelection
information, for example.
Extensions implement additional functionalities to the server's parsing, validation and execution. For example, extensions for tracing (GraphQLTracingExtension), logging (GraphQLLoggingExtension), error handling or caching (GraphQLPersistedQueries and GraphQLCacheExtension). All extension implementations can be found in the extensions folder in package:leto
. The main API with all the methods that can be overridden is found in this file.
Save network bandwidth by storing GraphQL documents on the server and not requiring the Client to send the full document String on each request.
More information: https://www.apollographql.com/docs/apollo-server/performance/apq/
Trace the parsing, validation and execution of your GraphQL server to monitor execution times of all GraphQL requests.
More information: https://github.com/apollographql/apollo-tracing
Utility for caching responses in your GraphQL server and client.
Client GQL Link implementation in: // TODO: 2E
-
Hash: Similar to HTTP If-None-Match and Etag headers. Computes a hash of the payload (sha1 by default) and returns it to the Client when requested. If the Client makes a request with a hash (computed locally or saved from a previous server response), the extension compares the hash and only returns the full body when the hash do not match. If the hash match, the client already has the last version of the payload.
-
MaxAge: If passed a
Cache
object, it will save the responses and compare the saved date with the current date, if the maxAge para is greater than the difference, it returns the cached value without executing the field's resolver. -
UpdatedAt: Similar to HTTP If-Modified-Since and Last-Modified headers.
// TODO: 2E retrieve hash, updatedAt and maxAge in resolvers.
The logging extension allows you monitor requests and responses executed by your server.
Provides some utilities for printing and retrieving information from execution, logging errors and provides a default GraphQLLog
class that contains aggregated information about the request.
Simple extension for mapping an error catched on resolver execution.
With a function that receives the thrown error and some context as parameter and returns a GraphQLException?
, this extension will override the error and pass it to the executor, which will eventually return it to the user as an error in the response's errors
list.
To create a custom extension you can extend GraphQLExtension
and override the necessary functions, all of which are executed throughout a request's parsing, validation and execution.
To save state scoped to a single request you can use the ScopedMap.setScoped(key, value)
and retrieve the state in a different method with final value = ScopedMap.get(key);
. Where the ScopedMap
can be accessed with ctx.globals
.
All extensions are implemented in this way, so you can look at the source code for some examples.
For more information: GraphQL specification
GraphQLDirective
allows you to provide more information about different elements of your schema and queries.
The default skip, include, deprecated and specifiedBy directives are provided. Fields in the different type system definition classes allow you to include the deprecated reason for fields or enum values, and a url of the specification for scalar types. This information will be printed when using the printSchema
utility, can be retrieved in Dart through GraphQL extension for modifying the behavior of request execution or, if introspection is enabled, will be exposed by the GraphQL server.
The skip and include directives are supported during document execution following the spec. Right now, custom directives on execution can be obtained by using the parsed DocumentNode
from package:gql, in the future better support could be implemented.
Provide custom directives supported by your server through the
GraphQLSchema.directives
field.
You can retrieve custom directives values in your GraphQL Schema definition when using the buildSchema
utility, which will parse all directives and leave them accessible through the astNode
Dart fields in the different GraphQL elements. Setting custom directives values through the GraphQL Schema Dart classes is a work in progress. Right now, you can add DirectiveNode
s to the element's attachments if you want to print it with printSchema
, however the API will probably change. See graphql/graphql-js#1343
Specifies that a given Object can be identified by the fields passed as argument to the directive
It is repeatable, there can be multiple keys per Object.
The following example shows an Object that can be identified by two keys, the "id" field and the combination "type" and "nested.value" fields.
type Model @key(fields: "id") @key(fields: "type nested { value } ") {
id: String!
type: String!
nested {
value: int!
}
}
Using package:valida
, the valida directive represents the validation configuration. At the moment the ValidaField
annotation over arguments and input fields is used to populated the valida directive. For example, the following annotated GraphQLInput
that verifies that all lengths inside the strs
field have at least 1 byte length:
@Valida()
@GraphQLInput()
class ValidaArgModel {
@ValidaList(each: ValidaString(minLength: 1))
final List<String> strs;
final ValidaArgModel? inner;
ValidaArgModel({
required this.strs,
this.inner,
});
Map<String, Object?> toJson() {
return {
'strs': strs,
'inner': inner?.toJson(),
};
}
factory ValidaArgModel.fromJson(Map<String, Object?> map) {
return ValidaArgModel(
strs: List<String>.from(map['strs']! as List),
inner: map['inner'] != null
? ValidaArgModel.fromJson((map['inner']! as Map).cast())
: null,
);
}
}
Will generate the following GraphQL definition with valida directive.
input ValidaArgModel {
strs: [String!]! @valida(jsonSpec: """
{"variantType":"list","each":{"variantType":"string","minLength":1}}
""")
inner: ValidaArgModel
}
In this case the JSON '{"variantType":"list","each":{"variantType":"string","minLength":1}}' is the result of executing the annotation's (ValidaList(each: ValidaString(minLength: 1))
) toJson method.
This API is experimental.
All GraphQL elements in the schema can have addition custom attachments. This can be used by other libraries or extensions to change the behavior of execution. For example, for supporting custom input validations or configuring the max age for some fields in an extension that caches responses.
An attachment can register validation logic by implementing AttachmentWithValidation
. The required validation method validateElement
will be executed when the GraphQLSchema is validated, as an argument it will receive the Schema validation context and the GraphQLElement
associated with the attachment.
Implementing this interface allows the GraphQLSchema's SDL String to contain the attachment's information by adding directives over the specific element associated with the attachment. Attachments that implement ToDirectiveValue
require the following getters:
/// The directive value represented by this object
DirectiveNode get directiveValue;
/// The directive definition of the [directiveValue]
GraphQLDirective get directiveDefinition;
We provide two attachments, both of which implement AttachmentWithValidation
and ToDirectiveValue
.
Implements the key directive over a given object. The fields
String is required.
Implements the valida directive over a given input field or argument. The annotation
argument should be the ValidaField
specified for the element. You probably should use it manually, when using code generation the validation will be performed for any @Valida()
annotated class or resolver and the attachment will be placed at the appropriate location.
To use associate a GraphQLElement (type, field or directive) with attachments, you may pass them as arguments to each of the GraphQLElements constructor.
To add attachments to types or fields when using code generation you can use the AttachFn
decorator. An example of this is the following, using the KeyAttachment
for KeyDirective
and the ValidaAttachment
for ValidaDirective
(which is set up in the generated code).
@Valida()
@AttachFn(KeyedAttachment.attachments)
@GraphQLObject()
class KeyedAttachment {
final String id;
final String name;
@ValidaDate(max: 'now')
final DateTime createdAt;
final NestedAttachment nested;
KeyedAttachment({
required this.id,
required this.name,
required this.createdAt,
required this.nested,
});
static List<AttachmentWithValidation> attachments() {
return const [
KeyAttachment('id'),
KeyAttachment('name nested {id}'),
];
}
}
@AttachFn(NestedAttachment.attachments)
@GraphQLObject()
class NestedAttachment {
final int id;
NestedAttachment({
required this.id,
});
static List<AttachmentWithValidation> attachments() {
return const [
KeyAttachment('id'),
];
}
}
Will generate the following GraphQL schema:
type KeyedAttachment @key(fields: "id") @key(fields: "name nested {id}") {
id: ID!
name: String!
createdAt: Date! @valida(jsonSpec: """
{"variantType":"date","max":"now"}
""")
nested: NestedAttachment!
}''',
'''
type NestedAttachment @key(fields: "id") {
id: Int!
Most GraphQL utilities can be found in the utilities
folder in package:leto_schema.
Create a GraphQLSchema
from a GraphQL Schema Definition (SDL) document String.
Transform a GraphQLSchema
into a String in the GraphQL Schema Definition Language (SDL).
Experimental. Extend a GraphQLSchema
with an SDL document. This will return an extended GraphQLSchema
with the additional types, fields, inputs and directives provided in the document.
Create an introspection document query for retrieving Schema information from a GraphQL server.
Experimental. Merge multiple GraphQLSchema
. The output GraphQLSchema
contains all the query, mutations and subscription fields from the input schemas. Nested objects are also merged.
Experimental. Build a GraphQLSchema from a JSON value, will add query, mutation, subscription and custom events on top of the provided JSON value. Will try to infer the types from the JSON structure.
Thanks for considering making a contribution! Every issue or question helps!
This package uses melos to manage dependencies. To install it run:
pub global activate melos
Then, to link the local packages run:
melos bootstrap
If using fvm, you may need to run:
fvm flutter pub global run melos bootstrap
You can view most of the commands that you will need in the melos.yaml
file. However, melos can be used to do other stuff like executing any command you want using melos exec
, for more information please view the melos Github repo.
The following scripts are used in CI and can be used thought development. At the moment, both of them are related to generating documentation.
This script allows you to include documentation in the README files (or any Markdown file) from comments in Dart code. In the future, we will probably support sharing documentation between Dart files.
For example, by placing this comment annotations in a section of a Dart file:
// @example-start{name-of-example,extension:graphql,start:1,end:-2}
const graphQLTypeSection = '''
type ObjectName {
objectField: String
}
''';
// @example-end{name-of-example}
And adding this comment in the Markdown (.md
) file:
<!-- include{name-of-example} -->
You can copy the same Dart snippet by executing dart run script/collect_examples.dart
. The Markdown file will be updated to:
<!-- include{name-of-example} -->
```graphql
type ObjectName {
objectField: String
}
```
<!-- include-end{name-of-example} -->
You can find many examples in the source code of this README with Dart examples annotated through out the repository's Dart files.
The scripts has a couple of arguments, in particular --check
is used in CI to verify the the code snippets are synchronized between the Dart files and Markdown files. --generate-dart-file
will generate Dart code with the snippet Strings and --generate-md-dir
will generate one .md
file for each example within the directory passed as argument.
Generates the Docusaurus documentation page. Basically, it copies the README file sections into the /docusaurus/docs/
directory in a format that Docusaurus understands. This is used in CI to build the documentation page.
Small pieces of configuration can be included within the README files. For example, to assign tags to a section (which will be converted to a page, perhaps /docs/leto_shelf/section-title
if it is in leto_shelf
's README) you can use.
# Section Title <!-- docusaurus{"tags":["tagName1","tagName2"]} -->
The content with the brackets should be a JSON string.