graphql-anywhere

What is graphql-anywhere?

The graphql-anywhere package is a flexible utility for running GraphQL queries against any arbitrary data structure. It allows you to execute GraphQL queries on client-side data, making it useful for scenarios where you need to filter or transform data based on a GraphQL query.

What are graphql-anywhere's main functionalities?

Executing GraphQL queries on client-side data

This feature allows you to execute GraphQL queries on client-side data. The code sample demonstrates how to filter a data object based on a GraphQL query, returning only the fields specified in the query.

const { graphql } = require('graphql-anywhere');
const { filter } = require('graphql-anywhere/lib/async');

const query = `{
  user {
    name
    age
  }
}`;

const resolver = (fieldName, root, args, context, info) => {
  return root[fieldName];
};

const data = {
  user: {
    name: 'John Doe',
    age: 30,
    email: '[e-mail]'
  }
};

filter(resolver, query, data).then(result => {
  console.log(result);
  // Output: { user: { name: 'John Doe', age: 30 } }
});

Custom resolvers for handling data

This feature allows you to define custom resolvers to handle data in a specific way. The code sample shows how to use a custom resolver to modify the 'age' field before returning the result.

const { graphql } = require('graphql-anywhere');
const { filter } = require('graphql-anywhere/lib/async');

const query = `{
  user {
    name
    age
  }
}`;

const customResolver = (fieldName, root, args, context, info) => {
  if (fieldName === 'age') {
    return root[fieldName] + 1; // Custom logic to modify the age
  }
  return root[fieldName];
};

const data = {
  user: {
    name: 'John Doe',
    age: 30,
    email: '[e-mail]'
  }
};

filter(customResolver, query, data).then(result => {
  console.log(result);
  // Output: { user: { name: 'John Doe', age: 31 } }
});

Other packages similar to graphql-anywhere

graphql-tools

The graphql-tools package provides a set of utilities to build and manipulate GraphQL schemas in JavaScript. It includes features for schema stitching, mocking, and more. While graphql-tools focuses on schema creation and manipulation, graphql-anywhere is more about executing queries on arbitrary data structures.

apollo-client

Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. It includes features for caching, query batching, and more. While Apollo Client is a full-fledged GraphQL client, graphql-anywhere is a lightweight utility for executing queries on arbitrary data.

README

graphql-anywhere

Run a GraphQL query anywhere, without a GraphQL server or a schema. Just pass in one resolver. Use it together with graphql-tag.

npm install graphql-anywhere graphql-tag

I think there are a lot of potentially exciting use cases for a completely standalone and schema-less GraphQL execution engine. We use it in Apollo Client to read data from a Redux store with GraphQL.

Let's come up with some more ideas - below are some use cases to get you started!

API

import graphql from 'graphql-anywhere'

graphql(resolver, document, rootValue?, context?, variables?, options?)

• resolver: A single resolver, called for every field on the query.
  • Signature is: (fieldName, rootValue, args, context, info) => any
• document: A GraphQL document, as generated by the template literal from graphql-tag
• rootValue: The root value passed to the resolver when executing the root fields
• context: A context object passed to the resolver for every field
• variables: A dictionary of variables for the query
• options: Options for execution

Options

The last argument to the graphql function is a set of graphql-anywhere-specific options.

• resultMapper: Transform field results after execution.
  • Signature is: (resultFields, resultRoot) => any
• fragmentMatcher: Decide whether to execute a fragment. Default is to always execute all fragments.
  • Signature is: (rootValue, typeCondition, context) => boolean

Resolver info

info, the 5th argument to the resolver, is an object with supplementary information about execution. Send a PR or open an issue if you need additional information here.

• isLeaf: A boolean that is true if this resolver is for a leaf field of the query, i.e. one that doesn't have a sub-selection.

Utilities

See http://dev.apollodata.com/react/fragments.html for examples of how you might use these.

import { filter } from 'graphql-anywhere'

filter(doc, data);

• doc: a GraphQL document, as generated by the template literal from graphql-tag, typically either a query or a fragment.
• data: an object of data to be filtered by the doc

Filter data according to doc.

import { check } from 'graphql-anywhere'

check(doc, data);

• doc: a GraphQL document, as generated by the template literal from graphql-tag, typically either a query or a fragment.
• data: an object of data, as may have been filtered by doc.

Check that data is of the form defined by the query or fragment. Throw an exception if not.

import { propType } from 'graphql-anywhere'

X.propTypes = {
  foo: propType(doc),
  bar: propType(doc).isRequired,
}

• doc: a GraphQL document, as generated by the template literal from graphql-tag, typically either a query or a fragment.

Generate a React propType checking function to ensure that the passed prop is in the right form.

Supported GraphQL features

Why do you even need a library for this? Well, running a GraphQL query isn't as simple as just traversing the AST, since there are some pretty neat features that make the language a bit more complex to execute.

• Arguments
• Variables
• Aliases
• Fragments, both named and inline
• @skip and @include directives

If you come across a GraphQL feature not supported here, please file an issue.

Example: Filter a nested object

import gql from 'graphql-tag';
import graphql from 'graphql-anywhere';

// I don't need all this stuff!
const gitHubAPIResponse = {
  "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
  "title": "Found a bug",
  "body": "I'm having a problem with this.",
  "user": {
    "login": "octocat",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "url": "https://api.github.com/users/octocat",
  },
  "labels": [
    {
      "url": "https://api.github.com/repos/octocat/Hello-World/labels/bug",
      "name": "bug",
      "color": "f29513"
    }
  ],
};

// Write a query that gets just the fields we want
const query = gql`
  {
    title
    user {
      login
    }
    labels {
      name
    }
  }
`;

// Define a resolver that just returns a property
const resolver = (fieldName, root) => root[fieldName];

// Filter the data!
const result = graphql(
  resolver,
  query,
  gitHubAPIResponse
);

assert.deepEqual(result, {
  "title": "Found a bug",
  "user": {
    "login": "octocat",
  },
  "labels": [
    {
      "name": "bug",
    }
  ],
});

Example: Generate mock data

// Write a query where the fields are types, but we alias them
const query = gql`
  {
    author {
      name: string
      age: int
      address {
        state: string
      }
    }
  }
`;

// Define a resolver that uses the field name to determine the type
// Note that we get the actual name, not the alias, but the alias
// is used to determine the location in the response
const resolver = (fieldName) => ({
  string: 'This is a string',
  int: 5,
}[fieldName] || 'continue');

// Generate the object!
const result = graphql(
  resolver,
  query
);

assert.deepEqual(result, {
  author: {
    name: 'This is a string',
    age: 5,
    address: {
      state: 'This is a string',
    },
  },
});

Example: Read from a Redux store generated with Normalizr

const data = {
  result: [1, 2],
  entities: {
    articles: {
      1: { id: 1, title: 'Some Article', author: 1 },
      2: { id: 2, title: 'Other Article', author: 1 },
    },
    users: {
      1: { id: 1, name: 'Dan' },
    },
  },
};

const query = gql`
  {
    result {
      title
      author {
        name
      }
    }
  }
`;

const schema = {
  articles: {
    author: 'users',
  },
};

// This resolver is a bit more complex than others, since it has to
// correctly handle the root object, values by ID, and scalar leafs.
const resolver = (fieldName, rootValue, args, context): any => {
  if (!rootValue) {
    return context.result.map((id) => assign({}, context.entities.articles[id], {
      __typename: 'articles',
    }));
  }

  const typename = rootValue.__typename;
  // If this field is a reference according to the schema
  if (typename && schema[typename] && schema[typename][fieldName]) {
    // Get the target type, and get it from entities by ID
    const targetType: string = schema[typename][fieldName];
    return assign({}, context.entities[targetType][rootValue[fieldName]], {
      __typename: targetType,
    });
  }

  // This field is just a scalar
  return rootValue[fieldName];
};

const result = graphql(
  resolver,
  query,
  null,
  data // pass data as context since we have to access it all the time
);

// This is the non-normalized data, with only the fields we asked for in our query!
assert.deepEqual(result, {
  result: [
    {
      title: 'Some Article',
      author: {
        name: 'Dan',
      },
    },
    {
      title: 'Other Article',
      author: {
        name: 'Dan',
      },
    },
  ],
});

Example: Generate React components

You can use the resultMapper option to convert your results into anything you like. In this case, we convert the result fields into children for a React component:

const resolver = (fieldName, root, args) => {
  if (fieldName === 'text') {
    return args.value;
  }

  return createElement(fieldName, args);
};

const reactMapper = (childObj, root) => {
  const reactChildren = Object.keys(childObj).map(key => childObj[key]);

  if (root) {
    return cloneElement(root, root.props, ...reactChildren);
  }

  return reactChildren[0];
};

function gqlToReact(query): any {
  return graphql(
    resolver,
    query,
    '',
    null,
    null,
    { resultMapper: reactMapper },
  );
}

const query = gql`
  {
    div {
      s1: span(id: "my-id") {
        text(value: "This is text")
      }
      s2: span
    }
  }
`;

assert.equal(
  renderToStaticMarkup(gqlToReact(query)),
  '<div><span id="my-id">This is text</span><span></span></div>'
);

Changelog

Apollo Client 3.1.0

Bug Fixes

• Rework interdependencies between @apollo/client/* entry points, so that CommonJS and ESM modules are supported equally well, without any duplication of shared code. <br/> @benjamn in #6656 and #6657

• Tolerate !== callback functions (like onCompleted and onError) in useQuery options, since those functions are almost always freshly evaluated each time useQuery is called. <br/> @hwillson and @benjamn in #6588

• Respect context.queryDeduplication if provided, and otherwise fall back to client.deduplication (as before). <br/> @igaloly in #6261 and @Kujawadl in #6526

• Refactor ObservableQuery#getCurrentResult to reenable immediate delivery of warm cache results. As part of this refactoring, the ApolloCurrentQueryResult type was eliminated in favor of ApolloQueryResult. <br/> @benjamn in #6710

• Avoid clobbering defaultOptions with undefined values. <br/> @benjamn in #6715

Improvements

• Apollo Client will no longer modify options.fetchPolicy unless you pass options.nextFetchPolicy to request an explicit change in FetchPolicy after the current request. Although this is technically a breaking change, options.nextFieldPolicy makes it easy to restore the old behavior (by passing cache-first). <br/> @benjamn in #6712, reverting #6353

• Errors of the form Invariant Violation: 42 thrown in production can now be looked up much more easily, by consulting the auto-generated @apollo/client/invariantErrorCodes.js file specific to your @apollo/client version. <br/> @benjamn in #6665

• Make the client field of the MutationResult type non-optional, since it is always provided. <br/> @glasser in #6617

• Allow passing an asynchronous options.renderFunction to getMarkupFromTree. <br/> @richardscarrott in #6576

• Ergonomic improvements for merge and keyArgs functions in cache field policies. <br/> @benjamn in #6714