Canonical generic codegen

[comigor]

Proposal

This proposal aims to facilitate the use of generated code and enhance it with nnbd (non-nullable by default), available since Dart 2.9.

Problem

Currently,

• Users need to choose between simple/pathedWithFields naming schemes: simple generates easier to read code (smaller classes names) which will clash if the same class happen to be used in more than one place of the query (with different selection sets)[1.a], while pathedWithFields will not clash, but the generated classes won't be compatible[1.b], unless generated with fragments[2.a];
• We are not considering fields nullability (as until now Dart wouldn't support it natively), so generated classes will always be nullable, even though GraphQL marks them with ![3];

[1] Example:

type Person {
  name: String!
  parents: [Person!]
}

type Query {
  user: Person!
}

query {
  user { name, parents { name } }
}

[1.a] `simple` output:

  Two classes were generated with the same name `ClassName(name:r'Person')`
  but with different selection set.

  Class A
  ClassDefinition(name:ClassName(name:r'Person'), properties:[ClassProperty(type:TypeName(name:r'String'), name:ClassPropertyName(name:r'name'), isNonNull:true, isResolveType:false)], factoryPossibilities:{}, typeNameField:TypeName(name:r'__typename'), isInput:false)

  Class B
  ClassDefinition(name:ClassName(name:r'Person'), properties:[ClassProperty(type:TypeName(name:r'String'), name:ClassPropertyName(name:r'name'), isNonNull:true, isResolveType:false), ClassProperty(type:TypeName(name:r'List<Person>'), name:ClassPropertyName(name:r'parents'), isNonNull:false, isResolveType:false)], factoryPossibilities:{}, typeNameField:TypeName(name:r'__typename'), isInput:false)

[1.b] `pathedWithFields` output:

// GENERATED CODE - DO NOT MODIFY BY HAND

import 'package:json_annotation/json_annotation.dart';
import 'package:equatable/equatable.dart';
import 'package:gql/ast.dart';
part 'query.graphql.g.dart';

@JsonSerializable(explicitToJson: true)
class Query$Query$User$Parents with EquatableMixin {
  Query$Query$User$Parents();

  factory Query$Query$User$Parents.fromJson(Map<String, dynamic> json) =>
      _$Query$Query$User$ParentsFromJson(json);

  String name;

  @override
  List<Object> get props => [name];
  Map<String, dynamic> toJson() => _$Query$Query$User$ParentsToJson(this);
}

@JsonSerializable(explicitToJson: true)
class Query$Query$User with EquatableMixin {
  Query$Query$User();

  factory Query$Query$User.fromJson(Map<String, dynamic> json) =>
      _$Query$Query$UserFromJson(json);

  String name;

  List<Query$Query$User$Parents> parents;

  @override
  List<Object> get props => [name, parents];
  Map<String, dynamic> toJson() => _$Query$Query$UserToJson(this);
}

@JsonSerializable(explicitToJson: true)
class Query$Query with EquatableMixin {
  Query$Query();

  factory Query$Query.fromJson(Map<String, dynamic> json) =>
      _$Query$QueryFromJson(json);

  Query$Query$User user;

  @override
  List<Object> get props => [user];
  Map<String, dynamic> toJson() => _$Query$QueryToJson(this);
}

[2] Example:

type Person {
  name: String!
  parents: [Person!]
}

type Query {
  user: Person!
}

fragment Person on Person {
  name
}

query {
  user {
    ...Person
    parents {
      ...Person
    }
  }
}

`pathedWithFields` + fragment output:

// GENERATED CODE - DO NOT MODIFY BY HAND

import 'package:json_annotation/json_annotation.dart';
import 'package:equatable/equatable.dart';
import 'package:gql/ast.dart';
part 'query.graphql.g.dart';

mixin PersonMixin {
  String name;
}

@JsonSerializable(explicitToJson: true)
class Query$Query$User$Parents with EquatableMixin, PersonMixin {
  Query$Query$User$Parents();

  factory Query$Query$User$Parents.fromJson(Map<String, dynamic> json) =>
      _$Query$Query$User$ParentsFromJson(json);

  @override
  List<Object> get props => [name];
  Map<String, dynamic> toJson() => _$Query$Query$User$ParentsToJson(this);
}

@JsonSerializable(explicitToJson: true)
class Query$Query$User with EquatableMixin, PersonMixin {
  Query$Query$User();

  factory Query$Query$User.fromJson(Map<String, dynamic> json) =>
      _$Query$Query$UserFromJson(json);

  List<Query$Query$User$Parents> parents;

  @override
  List<Object> get props => [name, parents];
  Map<String, dynamic> toJson() => _$Query$Query$UserToJson(this);
}

@JsonSerializable(explicitToJson: true)
class Query$Query with EquatableMixin {
  Query$Query();

  factory Query$Query.fromJson(Map<String, dynamic> json) =>
      _$Query$QueryFromJson(json);

  Query$Query$User user;

  @override
  List<Object> get props => [user];
  Map<String, dynamic> toJson() => _$Query$QueryToJson(this);
}

[3] Example:

type Person {
  name: String!
}

type Query {
  user: Person!
  currentUser: Person
}

query {
  user { name }
  currentUser { name }
}

// GENERATED CODE - DO NOT MODIFY BY HAND

import 'package:json_annotation/json_annotation.dart';
import 'package:equatable/equatable.dart';
import 'package:gql/ast.dart';
part 'query.graphql.g.dart';

@JsonSerializable(explicitToJson: true)
class Person with EquatableMixin {
  Person();

  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);

  String name;

  @override
  List<Object> get props => [name];
  Map<String, dynamic> toJson() => _$PersonToJson(this);
}

@JsonSerializable(explicitToJson: true)
class Query$Query with EquatableMixin {
  Query$Query();

  factory Query$Query.fromJson(Map<String, dynamic> json) =>
      _$Query$QueryFromJson(json);

  Person user;

  Person currentUser;

  @override
  List<Object> get props => [user, currentUser];
  Map<String, dynamic> toJson() => _$Query$QueryToJson(this);
}

We also talk a lot about "canonicality" (i.e. Any Dart type generation with a 1:1 relationship with its GraphQL counterpart, where every field and property of canonical types should be applied into the class generation). In theory scalars, enums and input objects, as input values, are canonical. Also, query fragments can also be generated canonically.

It would be better to have objects classes also generated canonically, so users wouldn't have to use fragments or depend on class deduplication to have two or more entries of the same class compatible. However, if objects would've been generated as canonical, they'd include all GraphQL fields, even thought the query wouldn't select them.

Solution

The proposed solution aims to generate code based on canonical classes, mapping selection sets generically, and making them accessible via a $ shorthand. By doing this, we minimize breaking changes (as the "default" getter would still be valid, although nullable) and we won't need to deal with naming schemes anymore.

GraphQL schema:

type Query {
  blah: Business
  bleh: Business!
  mah: String
  meh: String!
  all: [NamedAndValuedEntity!]!
  uni: [MyUnion!]!
}

interface NamedAndValuedEntity {
  name: String!
  value: Int
}

type Business implements NamedAndValuedEntity {
  name: String!
  value: Int
  employeeCount: Int
  address: String!
}

type Other implements NamedAndValuedEntity {
  name: String!
  value: Int
  field: String
}

type A {
  a: String!
}

type B {
  b: Int!
}

union MyUnion = A | B

GraphQL query:

fragment Meh on Query {
  meh
}

query {
  blah { # Business
    employeeCount
    value
  }
  bleh { # Business
    address
    name
  }
  ...meh
  all {
    name
    value
    ... on Business {
      address
    }
    ... on Other {
      field
    }
  }
  uni {
    ... on A { a }
    ... on B { b }
  }
}

Suggested generated file (without ArtemisClient query/helpers). Keep in mind this code was done manually and is prone to typos and/or errors:

// @dart = 2.12
// ignore_for_file: public_member_api_docs
// ignore_for_file: unnecessary_cast
//// ignore_for_file: unused_element

// Generic by selection set, with interfaces, fragments, unions and interface/union type matching.

/// Creating this just so we can separate what's a selection set and what's not.
/// SelectionSet classes shouldn't be used/instantiated directly. Should we start them with underscores?
abstract class SelectionSet {}

//////////////////////////////// "Canonical" classes
/// Fragments are generated as mixins "on" their canonical class (and so must override the fields).
mixin MehFragment on Query {
  @override
  String? meh;
}

/// Interfaces are generated just like fragments, but don't have "on" specification.
mixin NamedAndValuedEntity {
  String? name;
  int? value;
}

/// Canonical classes implement interfaces, but not fragments, as the latter are bound to the query.
/// Objects are all generic to a selection set, and must have all possible fields they contain as nullable.
class Business<T extends SelectionSet> with NamedAndValuedEntity {
  Business(this.$);

  /// The actual selection. Always use this unless you're dealing with generics
  /// or don't mind about nullability. Could this also help to migrate without breaking changes?
  T $;

  /// Always nullable (because as this is a canonical class, and we
  /// can't know for sure if those fields will be selected by the queries)
  int? employeeCount;
  String? address;
}

class Other<T extends SelectionSet> with NamedAndValuedEntity {
  Other(this.$);

  T $;

  String? field;
}

class Query<T extends SelectionSet> {
  Query(this.$);

  T $;

  Business<_Business_SelectionSet_Query$Blah>? blah;
  Business<_Business_SelectionSet_Query$Bleh>? bleh;
  String? mah;
  String? meh;
  Iterable<NamedAndValuedEntity>? all;
  Iterable<MyUnion>? uni;
}

/// Union types are also generated as a simple mixin, without any field (as
/// Dart doesn't have union/sealed classes).
mixin MyUnion {}

class A<T extends SelectionSet> with MyUnion {
  A(this.$);

  T $;

  String? a;
}

class B<T extends SelectionSet> with MyUnion {
  B(this.$);

  T $;

  int? b;
}

//////////////////////////////// SelectionSets
/// Fragments have their selection sets defined as mixins, so won't need a constructor
/// and can be used in conjunction of other selection sets.
mixin _MehFragment_SelectionSet_Query implements SelectionSet {
  late String meh;
}

/// Regular selection sets follow GraphQL nullability and won't have the field
/// if the query doesn't select it.
class _Business_SelectionSet_Query$Blah implements SelectionSet {
  _Business_SelectionSet_Query$Blah({this.employeeCount, this.value});

  // Follows GraphQL nullability
  int? employeeCount;
  int? value;
}

class _Business_SelectionSet_Query$Bleh implements SelectionSet {
  _Business_SelectionSet_Query$Bleh(
      {required this.address, required this.name});

  // Follows GraphQL nullability
  String address;
  String name;
}

/// Fragments selection sets will spread into other selection sets.
class _Query_SelectionSet_Query
    with _MehFragment_SelectionSet_Query
    implements SelectionSet {
  _Query_SelectionSet_Query({
    this.blah,
    required this.bleh,
    required this.meh,
    required this.all,
    required this.uni,
  });

  // Follows GraphQL nullability
  Business<_Business_SelectionSet_Query$Blah>? blah;
  Business<_Business_SelectionSet_Query$Bleh> bleh;
  Iterable<_NamedAndValuedEntity_SelectionSet_Query$All> all;
  Iterable<MyUnion> uni;

  Iterable<_Business_SelectionSet_Query$All> get all$Business =>
      all.whereType<_Business_SelectionSet_Query$All>();
  Iterable<_Other_SelectionSet_Query$All> get all$Other =>
      all.whereType<_Other_SelectionSet_Query$All>();
  Iterable<_A_SelectionSet_Query$Uni> get uni$A =>
      uni.whereType<_A_SelectionSet_Query$Uni>();
  Iterable<_B_SelectionSet_Query$Uni> get uni$B =>
      uni.whereType<_B_SelectionSet_Query$Uni>();

  /// Inherited via fragments
  @override
  String meh;
}

/// Interface selection sets are also defined as mixins.
mixin _NamedAndValuedEntity_SelectionSet_Query$All implements SelectionSet {
  late String name;
  int? value;
}

class _Business_SelectionSet_Query$All
    with _NamedAndValuedEntity_SelectionSet_Query$All
    implements SelectionSet {
  _Business_SelectionSet_Query$All({required this.address});

  String address;
}

class _Other_SelectionSet_Query$All
    with _NamedAndValuedEntity_SelectionSet_Query$All
    implements SelectionSet {
  _Other_SelectionSet_Query$All({this.field});

  String? field;
}

class _A_SelectionSet_Query$Uni with MyUnion implements SelectionSet {
  _A_SelectionSet_Query$Uni({required this.a});

  String a;
}

class _B_SelectionSet_Query$Uni with MyUnion implements SelectionSet {
  _B_SelectionSet_Query$Uni({required this.b});

  String b;
}

//////////////////////////////// Query
/// so we can test types below
Query<_Query_SelectionSet_Query> run() {
  throw Exception('Not implemented');
}

void main() {
  final q = run();

  q.$.bleh.$.address;
  q.$.bleh.name;
  q.$.meh;
  q is MehFragment;

  q.$.all$Business.forEach((entity) {
    entity.address;
  });

  q.$.uni$B.forEach((entity) {
    entity.b;
  });
}

Drawbacks

• If we don't expose the SelectionSets, users won't be able to refer to the specific classes outside of the response context (eg. a function would return Business instead of Business<_Business_SelectionSet_Query$Blah> and the generic type would be lost. We could remove the _ making SelectionSets public, which wouldn't help with the long-naming problem.
• The "default" accessor here is the generic (canonical) class, but not the strongly typed one (SelectionSet). It seems wise to make it the other way around (still returning the strongly typed by default, as-of today, while exposing a non-default accessor to its canonical counterpart). I'll create an alternative example with this approach soon and post below. But, the same way as above, we'd still have long-naming problem (which a fellow engineer suggested me a package approach which I'm also thinking about).
• It won't be possible of (or at least I couldn't think in a way of) automatically return the correct SelectionSet type on interfaces/unions, so users would have to use the generated fieldName$FieldType getter (and so we can still avoid leaking/exposing the generated SelectionSet classes).
• Probably others (???)

[vasilich6107]

/// Always nullable (because as this is a canonical class, and we
/// can't know for sure if those fields will be selected by the queries)
int? employeeCount;
String? address;

Giving access to this fields will miss lead the user and could lead to long lasting debug.
As far as user could try to call employeeCount directly while it is missing in the actual selection set.

[comigor]

Yes, I agree, that's one of the reasons I'm working on inverse-wrapping it: having the classes being generated as-of today (and considering nullability), while capable to explicitly being converted to their canonical counterparts.

[vasilich6107]

Currently I can break my query on to fragments and refer to them in classes.

I can pass the UserMixin form user list into the form for editing.
In described implementation the mixins will become private and longnamed _Business_SelectionSet_Query$Bleh

[comigor]

You could still use fragments as-of today on this solution (mixin MehFragment on Query), but I agree with the second point!