@nftx/query
v4.0.1
Published
This library offers some simple, standalone, methods for querying both restful endpoints (or any endpoints, actually) as well as constructing and querying graphql endpoints.
Downloads
406
Readme
@nftx/query
This library offers some simple, standalone, methods for querying both restful endpoints (or any endpoints, actually) as well as constructing and querying graphql endpoints.
query
<T>(args: {
url: string,
data?: Record<string, any> | string,
method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
}): Promise<T>
query
is a very simple wrapper around the native fetch
api. It will handle serializing post data, creating query params, parsing response data, and handling failed responses.
const data = await query<{ items: Item[] }>({
url: '/api/items',
data: { myQueryParam: 'foo' },
method: 'GET',
});
In addition to the base arguments, you can also pass additional arguments:
<T>(args: {
...baseArgs,
maxAttempts?: number,
fetch?: Fetch,
parse?: (text:string, reviver?: (key: string, value: any) => any): any,
stringify?: (value: any, replacer?: (key: string, value: any) => any, space?: number): string
}): Promise<T>
maxAttempts
determines how many times a failed response will be retried. (Only repsonses with a 5xx status are considered retryable)
fetch
, parse
, and stringify
allow you to pass in a custom implementation of fetch
, JSON.parse
, and JSON.stringify
respectively.
Finally, you can also pass in any additional arguments available in the RequestInit
type, such as headers
or credentials
.
If a non-2xx response is received, a special error will be thrown that contains the response
object and the parsed response data.
try {
await query({ url: '/api/will-fail' });
} catch (e) {
if (e.response.status === 400) {
// do something
}
if (e.data.someContextInfo) {
// do something
}
}
gql
(query: string): string
Accepts and returns a graphql string. In reality this method does absolutely nothing except flags to various syntax highlighters that the string is a graphql query!
queryGraph
<T>(args: {
url: string | string[],
query: string | Query,
variables?: Record<string, any>
}): Promise<T>
Sends a graphql query and returns the resulting data. This is mostly just a wrapper around the query
method with a few extras:
url
can be an array of urls. If the first url fails, it will attempt the next until all have been tried. This means you can have "backup" graphs to fall back on.data
is replaced byquery
which can either be a string containing your graphql query, or the result of callingcreateQuery
variables
argument can be used to inject variables into your query string- you can still pass in all
RequestInit
args, a customfetch
,stringify
, andparse
, as well assendQuery
which lets you pass in a custom implementation of thequery
method.
createQuery
<QuerySchema>(): Query
returns an interface for creating a graphql query string, inspired by LINQ
style syntax. The most useful feature of createQuery
is its ability to infer fields, filters, and data types.
createQuery was created with a specific schema format in mind. Single entities expect an
id
arg. List entities acceptfirst
,orderBy
,orderDirection
, andwhere
args.
The resulting query contains the possible entities to query:
createQuery<Query>().pools;
and each entitiy has the following properies:
{
// for single entity
id(id: string): Query,
// for lists
first(limit: number): Query,
orderBy(field: string): Query,
orderDirection(direction: 'asc' | 'desc'): Query,
where(fn: (w: W) => W[]): Query,
// common
as(name: string): Query, // alias the entity
select(fn: (s: S) => S[]): Query
}
where and select work by passing in a callback function and returning a list of fields:
where((w) => [
w.fieldA('value'),
w.fieldB.gt(100),
w.childEntity((c) => [c.childField.is('x')]),
]);
select((s) => [
s.fieldA,
s.fieldB.as('alias'),
s.childEntity((c) => [c.childField]),
]);