]>
Dogcows Code - chaz/graphql-client/blob - lib/GraphQL/Client.pm
edbb64e4ddc05c6c9e185cdcfc46503bd5e2e3ae
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);
93 $self->{transport
} //= do {
94 my $class = $self->_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 _transport_class
{
122 return _expand_class
($self->{class}) if $self->{class};
124 my $protocol = $self->_url_protocol;
125 _croak
'Failed to determine transport from URL' if !$protocol;
127 my $class = lc($protocol);
128 $class =~ s/[^a-z]/_/g;
130 return _expand_class
($class);
135 $class = "GraphQL::Client::$class" unless $class =~ s/^\+//;
140 package GraphQL
::Client
::Error
;
145 use overload
'""' => \
&error
, fallback
=> 1;
147 sub new
{ bless {%{$_[2] || {}}, error
=> $_[1] || 'Something happened'}, $_[0] }
149 sub error
{ "$_[0]->{error}" }
150 sub type
{ "$_[0]->{type}" }
154 die $self if ref $self;
164 my $graphql = GraphQL::Client->new(url => 'http://localhost:4000/graphql');
166 # Example: Hello world!
168 my $response = $graphql->execute('{hello}');
170 # Example: Kitchen sink
174 human(id: $human_id) {
183 my $operation_name = 'GetHuman';
184 my $transport_options = {
186 authorization => 'Bearer s3cr3t',
189 my $response = $graphql->execute($query, $variables, $operation_name, $transport_options);
191 # Example: Asynchronous with Mojo::UserAgent (promisify requires Future::Mojo)
193 my $ua = Mojo::UserAgent->new;
194 my $graphql = GraphQL::Client->new(ua => $ua, url => 'http://localhost:4000/graphql');
196 my $future = $graphql->execute('{hello}');
198 $future->promisify->then(sub {
199 my $response = shift;
205 C<GraphQL::Client> provides a simple way to execute L<GraphQL|https://graphql.org/> queries and
206 mutations on a server.
208 This module is the programmatic interface. There is also a L<"CLI program"|graphql>.
210 GraphQL servers are usually served over HTTP. The provided transport, L<GraphQL::Client::http>, lets
211 you plug in your own user agent, so this client works naturally with L<HTTP::Tiny>,
212 L<Mojo::UserAgent>, and more. You can also use L<HTTP::AnyUA> middleware.
216 $graphql = GraphQL::Client->new(%attributes);
218 Construct a new client.
222 $response = $graphql->execute($query);
223 $response = $graphql->execute($query, \%variables);
224 $response = $graphql->execute($query, \%variables, $operation_name);
225 $response = $graphql->execute($query, \%variables, $operation_name, \%transport_options);
226 $response = $graphql->execute($query, \%variables, \%transport_options);
228 Execute a request on a GraphQL server, and get a response.
230 By default, the response will either be a hashref with the following structure or a L<Future> that
231 resolves to such a hashref, depending on the transport and how it is configured.
235 field1 => {...}, # or [...]
239 { message => 'some error message blah blah blah' },
244 Note: Setting the L</unpack> attribute affects the response shape.
248 The URL of a GraphQL endpoint, e.g. C<"http://myapiserver/graphql">.
252 The package name of a transport.
254 By default this is automatically determined from the protocol portion of the L</url>.
258 The transport object.
260 By default this is automatically constructed based on the L</class>.
264 Whether or not to "unpack" the response, which enables a different style for error-handling.
268 See L</ERROR HANDLING>.
270 =head1 ERROR HANDLING
272 There are two different styles for handling errors.
274 If L</unpack> is 0 (off), every response -- whether success or failure -- is enveloped like this:
281 where C<data> might be missing or undef if errors occurred (though not necessarily) and C<errors>
282 will be missing if the response completed without error.
284 It is up to you to check for errors in the response, so your code might look like this:
286 my $response = $graphql->execute(...);
287 if (my $errors = $response->{errors}) {
291 my $data = $response->{data};
292 # do something with $data
295 If C<unpack> is 1 (on), then L</execute> will return just the data if there were no errors,
296 otherwise it will throw an exception. So your code would instead look like this:
298 my $data = eval { $graphql->execute(...) };
299 if (my $error = $@) {
303 # do something with $data
306 Or if you want to handle errors in a different stack frame, your code is simply this:
308 my $data = $graphql->execute(...);
309 # do something with $data
311 Both styles map to L<Future> responses intuitively. If C<unpack> is 0, the response always resolves
312 to the envelope structure. If C<unpack> is 1, successful responses will resolve to just the data and
313 errors will fail/reject.
318 * L<graphql> - CLI program
319 * L<GraphQL> - Perl implementation of a GraphQL server
320 * L<https://graphql.org/> - GraphQL project website
This page took 0.043715 seconds and 4 git commands to generate.