apollo-link-scalars

TypeDoc generated docs in here

Github repo here

Custom Apollo Link to allow to parse custom scalars from responses, as well as serialize custom scalars in inputs. It can also validate enums, and cleanup __typename from inputs. (see Usage and Options).

Library Versions

Apollo Client v2 -> apollo-link-scalars v0.x

The deprecated Apollo Client v2 is used in the 0.x branch.

Of the 0.x family, the versions 0.1.x and 0.2.x are deprecated and a migration to 0.3.x is recommended

Apollo Client v3 -> apollo-link-scalars v2.x, v3.x, v4.x

The current Apollo Client v3 is used in the versions from 1.0

The 1.x family is considered deprecated and a migration to 2.x or greater is recommended

Breaking Change: removing makeExecutableSchema

The versions that included makeExecutableSchema from graphql-tools are deprecated. This are the versions:

• 0.1.x and 0.2.x => please migrate to 0.3.x (apollo client v2 line, deprecated)
• 1.x => please migrate to 2.x (apollo client v3 line)

If you are not using makeExecutableSchema from this library, the upgrade will be transparent.

If you are using makeExecutableSchema, you just need to replace it from the version of graphql-tools compatible with the version of Apollo Client that you are using. Please have a look at the Example of loading a schema

Disclaimer: Potential cache interaction

Parsing scalars at link level means that Apollo cache will receive them already parsed. Depending on what kind of parsing is performed, this may interact with the cache JSON serialization of, for example,apollo-cache-persist. While apollo-cache-persist has an option to turn that serialisation off, others may have similar issues.

In the original Apollo Client Github issue thread about scalar parsing, this situation was discussed.

At the time of this writing, Apollo Client still does not support this over 4 years after the original ticket was opened. A potential solution of parsing after the cache might have some other issues, like returning different instances for the cached data, which may not be ideal in some situations that rely on that (e.g. react re-render control). I think some users will benefit more from the automatic parsing and serializing than the cost of the potential cache interactions.

UPDATE: @woltob has a proposal related to this: https://github.com/eturino/apollo-link-scalars/issues/760

Installation

yarn add apollo-link-scalars graphql or npm install apollo-link-scalars graphql.

Usage

We need to pass a GraphQLSchema, and optionally we can also pass a map of custom serialization/parsing functions for specific types.

You can build the link by calling the withScalars() function, passing to it the schema and optionally a typesMap.

import { withScalars } from "apollo-link-scalars";
import { ApolloLink, HttpLink } from "@apollo/client/core";
import { schema } from "./my-schema";

const link = ApolloLink.from([withScalars({ schema }), new HttpLink({ uri: "http://example.org/graphql" })]);

// we can also pass a custom map of functions. These will have priority over the GraphQLTypes parsing and serializing functions from the Schema.
const typesMap = {
  CustomScalar: {
    serialize: (parsed: unknown): string | null => (parsed instanceof CustomScalar ? parsed.toString() : null),
    parseValue: (raw: unknown): CustomScalar | null => {
      if (!raw) return null; // if for some reason we want to treat empty string as null, for example
      if (isString(raw)) {
        return new CustomScalar(raw);
      }

      throw new Error("invalid value to parse");
    },
  },
};

const link2 = ApolloLink.from([withScalars({ schema, typesMap }), new HttpLink({ uri: "http://example.org/graphql" })]);

Options

We can pass extra options to withScalars() to modify the behaviour

• removeTypenameFromInputs (Boolean, default false): when enabled, it will remove from the inputs the __typename if it is found. This could be useful if we are using data received from a query as an input on another query.
• validateEnums (Boolean, default false): when enabled, it will validate the enums on parsing, throwing an error if it sees a value that is not one of the enum values.
• nullFunction (NullFunction, default null): by passing a set of transforms on how to box and unbox null types, you can automatically construct e.g. Maybe monads from the null types. See below for an example.

withScalars({
  schema,
  typesMap,
  validateEnums: true,
  removeTypenameFromInputs: true,
});

Example of loading a schema

import { gql } from "@apollo/client/core";
import { GraphQLScalarType, Kind } from "graphql";
import { makeExecutableSchema } from "@graphql-tools/schema";

// GraphQL Schema definition.
const typeDefs = gql`
  type Query {
    myList: [MyObject!]!
  }

  type MyObject {
    day: Date
    days: [Date]!
    nested: MyObject
  }

  "represents a Date with time"
  scalar Date
`;

const resolvers = {
  // example of scalar type, which will parse the string into a custom class CustomDate which receives a Date object
  Date: new GraphQLScalarType({
    name: "Date",
    serialize: (parsed: CustomDate | null) => parsed && parsed.toISOString(),
    parseValue: (raw: any) => raw && new CustomDate(new Date(raw)),
    parseLiteral(ast) {
      if (ast.kind === Kind.STRING || ast.kind === Kind.INT) {
        return new CustomDate(new Date(ast.value));
      }
      return null;
    },
  }),
};

// GraphQL Schema, required to use the link
const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
});

Synchronously creating a link instance with graphql-code-generator setup

Warning: Be sure to watch your bundle size and know what you are doing.

Codegen config to generate introspection data:

codegen.yml

---
generates:
  src/__generated__/graphql.schema.json:
    plugins:
      - "introspection"
    config:
      minify: true

Synchronous code to create link instance in common scenario:

import introspectionResult from "./__generated__/graphql.schema.json";
import { buildClientSchema, IntrospectionQuery } from "graphql";

const schema = buildClientSchema(introspectionResult)
// note: sometimes it seems to be needed to cast it as Introspection Query
// `const schema = buildClientSchema((introspectionResult as unknown) as IntrospectionQuery)`

const scalarsLink = withScalars({
  schema,
  typesMap: { … },
});

Changing the behaviour of nullable types

By passing the nullFunctions parameter to withScalar, you can change the way that nullable types are handled. The default implementation will leave them exactly as is, i.e. null => null and value => value. If instead, you e.g. wish to transform nulls into a Maybe monad, you can supply functions corresponding to the following type. The examples below are based on the Maybe monad from Seidr but any implementation will do.

type NullFunctions = {
  serialize(input: any): any | null;
  parseValue(raw: any | null): any;
};

const nullFunctions: NullFunctions = {
  parseValue(raw: any) {
    if (isNone(raw)) {
      return Nothing();
    } else {
      return Just(raw);
    }
  },
  serialize(input: any) {
    return input.caseOf({
      Just(value) {
        return value;
      },
      Nothing() {
        return null;
      },
    });
  },
};

The nullFunctions are executed after the normal parsing/serializing. The normal parsing/serializing functions are not called for null values.

Both in parsing and serializing, we have the following logic (in pseudocode):

if (isNone(value)) {
  return this.nullFunctions.serialize(value);
}

const serialized = serializeNonNullValue(value);
return this.nullFunctions.serialize(serialized);

if (isNone(value)) {
  return this.nullFunctions.parseValue(value);
}

const parsed = parseNonNullValue(value);
return this.nullFunctions.parseValue(parsed);

Acknowledgements

The link code is heavily based on apollo-link-response-resolver by will-heart.

While the approach in apollo-link-response-resolver is to apply resolvers based on the types taken from __typename, this follows the query and the schema to parse based on scalar types. Note that apollo-link-response-resolver is archived now

I started working on this after following the Apollo feature request https://github.com/apollographql/apollo-feature-requests/issues/2.

Development, Commits, versioning and publishing

See The Typescript-Starter docs.

Commits and CHANGELOG

For commits, you should use commitizen

yarn global add commitizen

#commit your changes:
git cz

As typescript-starter docs state:

This project is tooled for conventional changelog to make managing releases easier. See the standard-version documentation for more information on the workflow, or CHANGELOG.md for an example.

# bump package.json version, update CHANGELOG.md, git tag the release
yarn run version

You may find a tool like wip helpful for managing work in progress before you're ready to create a meaningful commit.

Creating the first version

Once you are ready to create the first version, run the following (note that reset is destructive and will remove all files not in the git repo from the directory).

# Reset the repo to the latest commit and build everything
yarn run reset && yarn run test && yarn run doc:html

# Then version it with standard-version options. e.g.:
# don't bump package.json version
yarn run version -- --first-release

# Other popular options include:

# PGP sign it:
# $ yarn run version -- --sign

# alpha release:
# $ yarn run version -- --prerelease alpha

And after that, remember to publish the docs.

And finally push the new tags to Github and publish the package to npm.

# Push to git
git push --follow-tags origin master

# Publish to NPM (allowing public access, required if the package name is namespaced like `@somewhere/some-lib`)
yarn publish --access public

Publish the Docs

yarn run doc:html && yarn run doc:publish

This will generate the docs and publish them in Github pages.

Generate a version

There is a single yarn command for preparing a new release. See One-step publish preparation script in TypeScript-Starter

# Prepare a standard release
yarn prepare-release

# Push to git
git push --follow-tags origin master

# Publish to NPM (allowing public access, required if the package name is namespaced like `@somewhere/some-lib`)
yarn publish --access public

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!