view release on metacpan or  search on metacpan

lib/Dancer2/Plugin/GraphQL.pm  view on Meta::CPAN

=head1 NAME

Dancer2::Plugin::GraphQL - a plugin for adding GraphQL route handlers

=head1 SYNOPSIS

  package MyWebApp;

  use Dancer2;
  use Dancer2::Plugin::GraphQL;
  use GraphQL::Schema;

  my $schema = GraphQL::Schema->from_doc(<<'EOF');
  schema {
    query: QueryRoot
  }
  type QueryRoot {
    helloWorld: String
  }
  EOF
  graphql '/graphql' => $schema, { helloWorld => 'Hello, world!' };

  dance;

  # OR, equivalently:
  graphql '/graphql' => $schema => sub {
    my ($app, $body, $execute) = @_;
    # returns JSON-able Perl data
    $execute->(
      $schema,
      $body->{query},
      undef, # $root_value
      $app->request->headers,
      $body->{variables},
      $body->{operationName},
      undef, # $field_resolver
    );
  };

  # OR, with bespoke user-lookup and caching:
  graphql '/graphql' => sub {
    my ($app, $body, $execute) = @_;
    my $user = MyStuff::User->lookup($app->request->headers->header('X-Token'));
    die "Invalid user\n" if !$user; # turned into GraphQL { errors => [ ... ] }
    my $cached_result = MyStuff::RequestCache->lookup($user, $body->{query});
    return $cached_result if $cached_result;
    MyStuff::RequestCache->cache_and_return($execute->(
      $schema,
      $body->{query},
      undef, # $root_value
      $user, # per-request info
      $body->{variables},
      $body->{operationName},
      undef, # $field_resolver
    ));
  };

=head1 DESCRIPTION

The C<graphql> keyword which is exported by this plugin allow you to
define a route handler implementing a GraphQL endpoint.

Parameters, after the route pattern.
The first three can be replaced with a single array-ref. If so,
the first element is a classname-part, which will be prepended with
"L<GraphQL::Plugin::Convert>::". The other values will be passed to
that class's L<GraphQL::Plugin::Convert/to_graphql> method. The returned
hash-ref will be used to set options.

E.g.

  graphql '/graphql' => [ 'Test' ]; # uses GraphQL::Plugin::Convert::Test

=over 4

=item $schema

A L<GraphQL::Schema> object.

=item $root_value

An optional root value, passed to top-level resolvers.

=item $field_resolver

An optional field resolver, replacing the GraphQL default.

=item $route_handler

An optional route-handler, replacing the plugin's default - see example
above for possibilities.

It must return JSON-able Perl data in the GraphQL format, which is a hash
with at least one of a C<data> key and/or an C<errors> key.

If it throws an exception, that will be turned into a GraphQL-formatted
error.

=back

If you supply two code-refs, they will be the C<$resolver> and
C<$handler>. If you only supply one, it will be C<$handler>. To be
certain, pass all four post-pattern arguments.

The route handler code will be compiled to behave like the following:

=over 4

=item *

Passes to the L<GraphQL> execute, possibly via your supplied handler,
the given schema, C<$root_value> and C<$field_resolver>.

=item *

The action built matches POST / GET requests.

=item *

Returns GraphQL results in JSON form.