Custom scalars and types on the client (Typescript)

[craigrushforth]

I've been trying to get this to work all day yesterday and it sounds like it's possible but only with resolvers, they seem to be server side and I need to configure the scalars & types as they get parsed on the client side.

Here is my scenario.

Our schema and server is handled by a different team. And we have multiple graphql clients so it's sort of fixed. Codegen is working really well, but I'd like to tweak the parsed versions of what the client sees to make it more runtime-friendly.

In our schema we have a Money scalar. It's a string containing a decimal with currency.

Looks like this.

"0.00 USD"

What I'd like to be able to do it have switch out codegen type to be a custom type. Preferably with some constructor so I can split the string into a decimal/number and currency type.

something like this:

type Money {
   amount: number;
   currency: string;
}

I have tried the following config

 "graphql/copia-graphql.ts": {
      documents: "graphql/**/*.graphql",
      plugins: ["typescript", "typescript-operations"],
      config: {
        omitOperationSuffix: true,
        scalars: {
          Money: "../lib/money#Money",
        },
      },

And its sort of working in that the generated code knows about it and imports it

import { Money } from '../lib/money';
export type Maybe<T> = T | null;
export type InputMaybe<T> = Maybe<T>;
export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };
/** All built-in and custom scalars, mapped to their actual values */
export type Scalars = {
  ID: string;
  String: string;
  Boolean: boolean;
  Int: number;
  Float: number;
  Date: any;
  DateTime: any;
  Decimal: any;
  Money: Money;      <----  This used to be `any` and this is what I want to see
};

But it's still just a string at runtime.

Just still a string

Where am I going wrong? I'm missing the bit where I can hook into the parsing and do some manipulation and possibly construct a different object where I pass in a string and split it into its decimal value and currency.

I also plan to do a similar this with Date & DateTime scalars where I look at the contents of the date string and construct js Date objects based on if there is a time T component in the string.

Hopefully, this made some sense. Just to reiterate I need to do this all client side if that's possible.

[eddeee888]

Hi @craigrushforth 👋

scalars option only changes the type of a Scalar but not the implementation, which seems to be what you are looking for.

You GraphQL client may have ways to change a scalar value to match the type. For example, Apollo Client allows changing an object's field behaviour in the fetched data: https://www.apollographql.com/docs/react/caching/cache-field-behavior/
(I'm unclear if it can target all Scalars? 🤔 )

For example, if you were using Apollo Client, you may have to add it into InMemoryCache like this:

const cache = new InMemoryCache({
  typePolicies: {
    Holding: { // Object type name
      fields: {
        marketValue: { // Field name
          read(value) { // `value` is the value that comes from the Graph e.g. "0.00 USD"
            return {
              amount: getAmountFromString(value), // Just an example
              currency: getCurrencyFromString(value) // Just an example
            }
          }
        }
      },
    },
  },
});

[maxcan]

Unfortunately, this needs to be done manually for every field of that type. It would be great if there was a code gen plugin that could automatically create these type policies for Apollo or urql

[craigrushforth]

I ended up switching to Apollo GraphQL and using "graphql-scalars" with a client-side schema (with lots of data removed to make it smaller). It has been working really well and I was able to get the exact results I wanted.

this kind of thing

const schema = buildClientSchema(introspectionResult as unknown as IntrospectionQuery);

export const customScalarsLink = withScalars({
  schema,
  typesMap: {
    // Convert Date to CalendarDate
    Date: {
      serialize: (parsed: unknown): string | null => {
        if (parsed === null) return null;

        if (parsed instanceof CalendarDate) {
          return parsed.toString();
        }

        throw new Error("Serialize Date expected to serialize a CalendarDate");
      },
      parseValue: (raw: unknown): CalendarDate | null => {
        if (raw === null) return null;

        if (isString(raw)) {
          const date = new CalendarDate(raw as string);
          if (date) return date;
        }

        throw new Error("Parse Date expected to parse a string");
      },
    },
    // Convert DateTime to Date
    DateTime: {
      serialize: (parsed: unknown): string | null => {
        if (parsed === null) return null;
        throw new Error(
          "Serialize DateTime we probably shouldn't be serializing DateTime. Check that we really need to do this."
        );
      },
      parseValue: (raw: unknown): Date | null => {
        if (!raw) return null;

        if (isString(raw)) {
          const date = new Date(raw as string);
          if (date) return date;
        }

        throw new Error("Parse DateTime expected to parse a string.");
      },
    },
  },
});

and then linked in this way

const createGraphqlClient = (accessToken: string) => {
  return new ApolloClient({
    link: ApolloLink.from([
      customScalarsLink,
      new HttpLink({
        uri: graphQLUrl,
        headers: {
          authorization: `Bearer ${accessToken}`,
        },
      }),
    ]),
    cache: new InMemoryCache(),
  });
};

[burner]

@craigrushforth I saw your comment about the client side schema simplification. I have been searching for a while for something like this, and your comment is the first hint I found into that direction.

Can you provide any more information on your approach there please?

[willlockwood]

@craigrushforth I'm also very interested in learning more about your implementation here. Are there more details you can share about how exactly you were able to implement the withScalars and buildClientSchema pieces of your example there?

[craigrushforth]

We're still using this and it been working fine for a while. I'll try and go into some details now.

In our package.json we have

    "apollo-link-scalars": "^4.0.2",

We have this file gqlCustomScalars.ts. This is where the scalars are converted back and forth on the client. We don't use javascript on the server so everything we're doing is client side.

We're currently only using this for converting between javascript Date & DateTime strings from the server and javascript CalendarDate and ISO date strings like YYYY-MM-DD

gqlCustomScalars.ts

import { CalendarDate } from "calendar-date";
import { withScalars } from "apollo-link-scalars";
import introspectionResult from "client-schema.json";
import { buildClientSchema, IntrospectionQuery } from "graphql";
import { isString } from "./strings";

const schema = buildClientSchema(introspectionResult as unknown as IntrospectionQuery);

export const customScalarsLink = withScalars({
  schema,
  typesMap: {
    // Convert Date to CalendarDate
    Date: {
      serialize: (parsed: unknown): string | null => {
        if (parsed === null) return null;

        if (parsed instanceof CalendarDate) {
          return parsed.toString();
        }

        throw new Error("Serialize Date expected to serialize a CalendarDate");
      },
      parseValue: (raw: unknown): CalendarDate | null => {
        if (raw === null) return null;

        if (isString(raw)) {
          const date = new CalendarDate(raw as string);
          if (date) return date;
        }

        throw new Error("Parse Date expected to parse a string");
      },
    },
    // Convert DateTime to Date
    DateTime: {
      serialize: (parsed: unknown): string | null => {
        if (parsed === null) return null;

        if (parsed instanceof Date) {
          return parsed.toISOString();
        }

        throw new Error("Serialize DateTime expected to serialize a Javascript Date.");
      },
      parseValue: (raw: unknown): Date | null => {
        if (!raw) return null;

        if (isString(raw)) {
          const date = new Date(raw as string);
          if (date) return date;
        }

        throw new Error("Parse DateTime expected to parse a string.");
      },
    },
  },
});

The import bit here is our client side schema that gets bundled in with the app.

import introspectionResult from "client-schema.json";

Its the normal schema but we strip out a lot of the unnecessary bloat and create a version that is half its original size

codegen.ts

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  schema: "schema.json",
  generates: {
    // Generate a client side schema for use with apollo-link-scalars / apollo-link
    "client-schema.json": {
      documents: "graphql/**/*.graphql",
      plugins: ["introspection"],
      config: {
        minify: true,
        descriptions: false,
        schemaDescription: false,
      },
      hooks: {
        onWatchTriggered: "tsx optimize-client-schema.mts",
        afterAllFileWrite: "tsx optimize-client-schema.mts",
      },
    },
    // Generate existing types files
    "graphql/copia-graphql.ts": {
      documents: "graphql/**/*.graphql",
      plugins: [
        "typescript",
        "typescript-operations",
        // Use the `add` plugin to import calendar date
        {
          add: {
            content: 'import { CalendarDate } from "calendar-date";',
          },
        },
      ],
      config: {
        omitOperationSuffix: true,
        enumsAsConst: true,
        strictScalars: true,
        scalars: {
          Date: "CalendarDate",
          DateTime: "Date",
          Decimal: "string",
        },
      },
    },
    // Generate types file for the components
    "components/graphql/copia-graphql.ts": {
      documents: "components/**/*.graphql",
      plugins: [
        "typescript",
        // Use the `add` plugin to import calendar date
        {
          add: {
            content: 'import { CalendarDate } from "calendar-date";',
          },
        },
      ],
      config: {
        omitOperationSuffix: true,
        enumsAsConst: true,
        strictScalars: true,
        scalars: {
          Date: "CalendarDate",
          DateTime: "Date",
          Decimal: "string",
        },
      },
    },
    // Generate per operation files in the components folder
    "./": {
      documents: "components/**/*.graphql",
      plugins: [
        "typescript-operations",
        // Use the `add` plugin to import calendar date
        {
          add: {
            content: 'import { CalendarDate } from "calendar-date";',
          },
        },
      ],
      preset: "near-operation-file",
      presetConfig: {
        extension: "-graphql.ts",
        baseTypesPath: "components/graphql/copia-graphql.ts",
      },
      config: {
        omitOperationSuffix: true,
        enumsAsConst: true,
        strictScalars: true,
        scalars: {
          Date: "CalendarDate",
          DateTime: "Date",
          Decimal: "string",
        },
      },
    },
  },
  hooks: {
    afterAllFileWrite: "tsx optimize-client-schema.mts",
  },
};

export default config;

Essentially this converts the regular schema.json into a more optimized client-schema.json

hooks: {
        onWatchTriggered: "tsx optimize-client-schema.mts",
        afterAllFileWrite: "tsx optimize-client-schema.mts",
      },

This is the script that optimizes the schema.json

optimize-client-schema.mts

/* eslint-disable no-console */
import { readFile, writeFile, unlink, statSync } from "fs";

const inputFile = "./client-schema.json";
const outputFile = "./client-schema.json";
const outputFileSpacing = 0; // Set this to 2 to make the json readable (but makes the file about 3 times larger)

readFile(inputFile, "utf8", async (err, data) => {
  if (err) {
    console.error(err);
    return;
  }

  const inputStat = await statSync(inputFile);

  const schema = JSON.parse(data);
  if (!schema) {
    console.error("Failed to parse: client-schema.json");
  }

  const replacer = (key: string, value: unknown) => {
    // Remove anything that is deprecated
    if (key === "isDeprecated" || key === "deprecationReason" || value === "isDeprecated") {
      return undefined;
    }

    // Remove everything where the value is null
    if (value === null) {
      return undefined;
    }

    // Removing these things below break the schema. You get errors trying to load it with `buildClientSchema`
    // which is good because you can tell when you've gone too far and made the schema un-useable.

    // // Remove "args": []
    // if (key === "args" && Array.isArray(value) && value.length === 0) {
    //   return undefined;
    // }

    // // Remove all "kind":"NON_NULL"
    // if (key === "kind" && value === "NON_NULL") {
    //   return undefined;
    // }

    return value;
  };

  const minifiedSchema = JSON.stringify(schema, replacer, outputFileSpacing);

  writeFile(outputFile, minifiedSchema, async (err) => {
    if (err) {
      console.error(err);
      return;
    }

    const outputStat = await statSync(outputFile);

    const sizeInBytes = inputStat.size - outputStat.size;
    const percentage = (sizeInBytes / inputStat.size) * 100;

    console.log(
      `✔ Optimized and minified ${outputFile} - Saved ${Math.trunc(sizeInBytes / 1024)}k (${Math.trunc(percentage)}%)`
    );

    if (inputFile !== outputFile) {
      // Delete the input file
      unlink(inputFile, (err) => {
        if (err) {
          throw err;
        }

        console.log(`✔ Deleted the input file ${inputFile}`);
      });
    }
  });
});

This is the final but where everything is bought together and the customScalarLink is used and linked in with the ApolloClient

This goes where you create your ApolloClient

const createGraphqlClient = (accessToken: string) => {
  return new ApolloClient({
    link: ApolloLink.from([
      customScalarsLink,
      new HttpLink({
        uri: graphQLUrl,
        headers: {
          authorization: `Bearer ${accessToken}`,
        },
      }),
    ]),
    cache: new InMemoryCache(),
  });
};

In case it wasn't clear the creation of client-schema.json is a build step that happens when our graphql changes and the codegen happens. If you have a simple schema you may not need it. For us is ended up reducing the size of the file by about 200k which was worth it.

Let me know how you get on or if none of that made any sense.

For completeness

We run our code gen like

yarn graphql-codegen --watch "./**/*.graphql" &

Which triggers these hooks in codegen.ts

 hooks: {
        onWatchTriggered: "tsx optimize-client-schema.mts",
        afterAllFileWrite: "tsx optimize-client-schema.mts",
      },

Not really important though just explaining whats happening