npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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

834

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 by query which can either be a string containing your graphql query, or the result of calling createQuery
  • variables argument can be used to inject variables into your query string
  • you can still pass in all RequestInit args, a custom fetch, stringify, and parse, as well as sendQuery which lets you pass in a custom implementation of the query 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 accept first, orderBy, orderDirection, and where 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]),
]);