artemis 0.2.0

Artemis

Build dart types from GraphQL schemas and queries

Pub Package

Artemis is a code generator that looks for *.schema.json (GraphQL Introspection Query response data) and *.query.graphql files and builds .dart files typing that query, based on the schema. That's similar to what Apollo does (Artemis is his sister anyway).


Installation #

Add the following to your pubspec.yaml file:

dev_dependencies:
  artemis: <1.0.0
  build_runner: ^1.5.0
  json_serializable: ^3.0.0

ℹ️ Note that build_runner and json_serializable are required!

Then run:

pub packages get

or

flutter packages get

Now Artemis will generate the API files for you by running:

pub run build_runner build

or

flutter pub run build_runner build

Configuration #

Artemis offers some configuration options to generate code. All options should be included on build.yaml file on the root of the project:

targets:
  $default:
    builders:
      artemis:
        options:
          # custom configuration options!
OptionDefault valueDescription
generate_helperstrueIf Artemis should generate query/mutation helper functions (with inputs and coercing).
custom_parser_importnullImport path to the file implementing coercer functions for custom scalars. See Custom scalars.
scalar_mapping[]Mapping of GraphQL and Dart types. See Custom scalars.
schema_mapping[]Mapping of queries and which schemas they will use for code generation. See Schema mapping.

Schema mapping #

By default, Artemis won't generate anything. That's because your queries/mutations should be linked to GraphQL schemas. To configure it, you need to point a schema_mapping to the path of those queries and schemas:

targets:
  $default:
    builders:
      artemis:
        options:
          schema_mapping:
            - schema: lib/my_graphql.schema.json
              queries_glob: lib/**.query.graphql

Each SchemaMap is configured this way:

OptionDefault valueDescription
schemaRelative path to the GraphQL schema. Its extension must be .schema.json.
queries_globGlob that selects all query files to be used with this schema. Their extension must be .query.graphql.
resolve_type_field__resolveTypeThe name of the field used to differentiatiate interfaces and union types (commonly __resolveType or __typename). Note that __resolveType field are not added automatically to the query. If you want interface/union type resolution, you need to manually add it to the query.

See examples for more information and configuration options.

Custom scalars #

If your schema uses custom scalars, they must be defined on build.yaml. If it needs a custom parser (to decode from/to json), the custom_parser_import path must be set and the file must implement both fromGraphQL___ToDart___ and fromDart___toGraphQL___ constant functions.

targets:
  $default:
    builders:
      artemis:
        options:
          custom_parser_import: 'package:graphbrainz_example/coercers.dart'
          scalar_mapping:
          - graphql_type: Date
            dart_type: DateTime

Each ScalarMap is configured this way:

OptionDefault valueDescription
graphql_typeThe GraphQL custom scalar name on schema.
dart_typeThe Dart type this custom scalar should be converted from/to.
use_custom_parserfalseWheter custom_parser_import should be imported on the beginning of the file.

See examples for more information and configuration options.

CHANGELOG #

0.2.0 BREAKING #

Completely overhaul how this works.

Artemis won't generate a full schema typing anymore. Instead, it will use the schema to generate typings from a specific query or mutation. It will also create helper functions to execute those queries. See README for more info.

This is totally a breaking change but as this library is still on alpha, I should keep it under 1.0.

0.1.3 #

  • Make objects that implement interfaces override resolveType

0.1.2 #

  • Improve package score

0.1.1 #

  • Enable tests on pipeline

0.1.0 #

  • "Fix" json_serializable dependency
  • Add tests
  • Generate union types as inheritance
  • Generate interface types as implementation
  • Make generated code choose inheritance

0.0.1 #

  • First release
  • No tests
  • No documentation
  • Parse complex GraphQL schemas (incorrectly, now I know)
  • Parse all GraphQL types types (union, interface, enum, input object, object, scalar, list, non null)
  • Consider custom scalars
  • Not even compile from scratch
  • Lot of bugs

example/README.md

Examples #

This folder contains some examples on how to use artemis.

pokemon #

A simple example, showing Pokémon GraphQL schema generation.

graphqbrainz #

A more complex example, for graphbrainz (a MusicBrainz GraphQL server). Featuring union types, interfaces and custom scalars.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  artemis: ^0.2.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:artemis/artemis.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
3
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
49
Learn more about scoring.

We analyzed this package on Jul 22, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:artemis/artemis.dart.

Maintenance issues and suggestions

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (analyzer).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
analyzer ^0.36.3 0.36.4 0.37.0
build ^1.1.4 1.1.5
build_config ^0.4.0 0.4.1
glob ^1.1.7 1.1.7
graphql_parser ^1.0.0 1.1.3
path ^1.6.2 1.6.2
recase ^2.0.1 2.0.1
source_gen ^0.9.4+2 0.9.4+3
Transitive dependencies
async 2.3.0
charcode 1.1.2
checked_yaml 1.0.1
collection 1.14.11
convert 2.1.1
crypto 2.0.6
csslib 0.16.1
dart_style 1.2.9
front_end 0.1.19 0.1.20
html 0.14.0+2
json_annotation 2.4.0
kernel 0.3.19 0.3.20
logging 0.11.3+2
meta 1.1.7
package_config 1.0.5
pub_semver 1.4.2
pubspec_parse 0.1.4
source_span 1.5.5
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
watcher 0.9.7+12
yaml 2.1.16
Dev dependencies
args ^1.5.2 1.5.2
build_runner ^1.5.0
build_test ^0.10.7+3
http ^0.12.0+2
json_serializable ^3.0.0
pedantic ^1.7.0 1.8.0+1
test ^1.6.3

Admin