1 package GraphQL
::Client
;
2 # ABSTRACT: A GraphQL client
7 use Module
::Load
qw(load);
8 use Scalar
::Util
qw(reftype);
11 our $VERSION = '999.999'; # VERSION
13 sub _croak
{ require Carp
; goto &Carp
::croak
}
14 sub _throw
{ GraphQL
::Client
::Error-
>throw(@_) }
23 my ($query, $variables, $operation_name, $options) = @_;
25 if ((reftype
($operation_name) || '') eq 'HASH') {
26 $options = $operation_name;
27 $operation_name = undef;
32 ($variables && %$variables) ? (variables
=> $variables) : (),
33 $operation_name ? (operationName
=> $operation_name) : (),
36 return $self->_handle_result($self->transport->execute($request, $options));
43 my $handle_result = sub {
45 my $resp = $result->{response
};
46 if (my $exception = $result->{error
}) {
47 unshift @{$resp->{errors
}}, {
48 message
=> "$exception",
52 if ($resp->{errors
}) {
53 _throw
$resp->{errors
}[0]{message
}, {
56 details
=> $result->{details
},
64 if (eval { $result->isa('Future') }) {
65 return $result->transform(
68 my $resp = eval { $handle_result->($result) };
70 Future
::Exception-
>throw("$err", $err->{type
}, $err->{response
}, $err->{details
});
77 return $handle_result->($result);
88 $self->{transport_class
};
93 $self->{transport
} //= do {
94 my $class = $self->_autodetermine_transport_class;
96 if ((my $err = $@) || !$class->can('execute')) {
97 $err ||= "Loaded $class, but it doesn't look like a proper transport.\n";
98 warn $err if $ENV{GRAPHQL_CLIENT_DEBUG
};
99 _croak
"Failed to load transport for \"${class}\"";
107 $self->{unpack} //= 0;
113 my $url = $self->url;
114 my ($protocol) = $url =~ /^([^+:]+)/;
119 sub _autodetermine_transport_class
{
122 my $class = $self->transport_class;
123 return _expand_class
($class) if $class;
125 my $protocol = $self->_url_protocol;
126 _croak
'Failed to determine transport from URL' if !$protocol;
128 $class = lc($protocol);
129 $class =~ s/[^a-z]/_/g;
131 return _expand_class
($class);
136 $class = "GraphQL::Client::$class" unless $class =~ s/^\+//;
141 package GraphQL
::Client
::Error
;
146 use overload
'""' => \
&error
, fallback
=> 1;
148 sub new
{ bless {%{$_[2] || {}}, error
=> $_[1] || 'Something happened'}, $_[0] }
150 sub error
{ "$_[0]->{error}" }
151 sub type
{ "$_[0]->{type}" }
155 die $self if ref $self;
165 my $graphql = GraphQL::Client->new(url => 'http://localhost:4000/graphql');
167 # Example: Hello world!
169 my $response = $graphql->execute('{hello}');
171 # Example: Kitchen sink
175 human(id: $human_id) {
184 my $operation_name = 'GetHuman';
185 my $transport_options = {
187 authorization => 'Bearer s3cr3t',
190 my $response = $graphql->execute($query, $variables, $operation_name, $transport_options);
192 # Example: Asynchronous with Mojo::UserAgent (promisify requires Future::Mojo)
194 my $ua = Mojo::UserAgent->new;
195 my $graphql = GraphQL::Client->new(ua => $ua, url => 'http://localhost:4000/graphql');
197 my $future = $graphql->execute('{hello}');
199 $future->promisify->then(sub {
200 my $response = shift;
206 C<GraphQL::Client> provides a simple way to execute L<GraphQL|https://graphql.org/> queries and
207 mutations on a server.
209 This module is the programmatic interface. There is also a L<"CLI program"|graphql>.
211 GraphQL servers are usually served over HTTP. The provided transport, L<GraphQL::Client::http>, lets
212 you plug in your own user agent, so this client works naturally with L<HTTP::Tiny>,
213 L<Mojo::UserAgent>, and more. You can also use L<HTTP::AnyUA> middleware.
217 $graphql = GraphQL::Client->new(%attributes);
219 Construct a new client.
223 $response = $graphql->execute($query);
224 $response = $graphql->execute($query, \%variables);
225 $response = $graphql->execute($query, \%variables, $operation_name);
226 $response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
227 $response = $graphql->execute($query, \%variables, \%transport_options);
229 Execute a request on a GraphQL server, and get a response.
231 By default, the response will either be a hashref with the following structure or a L<Future> that
232 resolves to such a hashref, depending on the transport and how it is configured.
236 field1 => {...}, # or [...]
240 { message => 'some error message blah blah blah' },
245 Note: Setting the L</unpack> attribute affects the response shape.
249 The URL of a GraphQL endpoint, e.g. C<"http://myapiserver/graphql">.
253 Whether or not to "unpack" the response, which enables a different style for error-handling.
257 See L</ERROR HANDLING>.
259 =attr transport_class
261 The package name of a transport.
263 This is optional if the correct transport can be correctly determined from the L</url>.
267 The transport object.
269 By default this is automatically constructed based on L</transport_class> or L</url>.
271 =head1 ERROR HANDLING
273 There are two different styles for handling errors.
275 If L</unpack> is 0 (off), every response -- whether success or failure -- is enveloped like this:
282 where C<data> might be missing or undef if errors occurred (though not necessarily) and C<errors>
283 will be missing if the response completed without error.
285 It is up to you to check for errors in the response, so your code might look like this:
287 my $response = $graphql->execute(...);
288 if (my $errors = $response->{errors}) {
292 my $data = $response->{data};
293 # do something with $data
296 If C<unpack> is 1 (on), then L</execute> will return just the data if there were no errors,
297 otherwise it will throw an exception. So your code would instead look like this:
299 my $data = eval { $graphql->execute(...) };
300 if (my $error = $@) {
304 # do something with $data
307 Or if you want to handle errors in a different stack frame, your code is simply this:
309 my $data = $graphql->execute(...);
310 # do something with $data
312 Both styles map to L<Future> responses intuitively. If C<unpack> is 0, the response always resolves
313 to the envelope structure. If C<unpack> is 1, successful responses will resolve to just the data and
314 errors will fail/reject.
319 * L<graphql> - CLI program
320 * L<GraphQL> - Perl implementation of a GraphQL server
321 * L<https://graphql.org/> - GraphQL project website