Example: how to create dedicated email and URL types

@app/client/src/graphql/AddEmail.graphql

@@ -1,6 +1,6 @@
 #import "./EmailsForm_UserEmail.graphql"
 
-mutation AddEmail($email: String!) {
+mutation AddEmail($email: Email!) {
   createUserEmail(input: { userEmail: { email: $email } }) {
     user {
       id

@app/client/src/graphql/ForgotPassword.graphql

@@ -1,4 +1,4 @@
-mutation ForgotPassword($email: String!) {
+mutation ForgotPassword($email: Email!) {
   forgotPassword(input: { email: $email }) {
     # This mutation does not return any meaningful result,
     # but we still need to request _something_...

@app/client/src/graphql/Register.graphql

@@ -1,7 +1,7 @@
 mutation Register(
   $username: String!
   $password: String!
-  $email: String!
+  $email: Email!
   $name: String
 ) {
   register(

@app/db/migrations/committed/000001.sql

@@ -1,5 +1,5 @@
 --! Previous: -
---! Hash: sha1:4be49e527161e4b03af6630d795e00271405d754
+--! Hash: sha1:269a8e30333545dd7d76a2591aa8637a27603ebb
 
 drop schema if exists app_public cascade;
 
@@ -34,6 +34,11 @@ create schema app_private;
 
 /**********/
 
+create domain app_public."URL" as text check(VALUE ~ '^https?://[^/]+');
+create domain app_public.email as citext check(VALUE ~ '[^@]+@[^@]+\.[^@]+');
+
+/**********/
+
 create function app_private.tg__add_job() returns trigger as $$
 begin
   perform graphile_worker.add_job(tg_argv[0], json_build_object('id', NEW.id), coalesce(tg_argv[1], public.gen_random_uuid()::text));
@@ -121,7 +126,7 @@ create table app_public.users (
   id serial primary key,
   username citext not null unique check(length(username) >= 2 and length(username) <= 24 and username ~ '^[a-zA-Z]([a-zA-Z0-9][_]?)+$'),
   name text,
-  avatar_url text check(avatar_url ~ '^https?://[^/]+'),
+  avatar_url app_public."URL",
   is_admin boolean not null default false,
   is_verified boolean not null default false,
   created_at timestamptz not null default now(),
@@ -220,7 +225,7 @@ $$ language sql stable security definer set search_path to pg_catalog, public, p
 create table app_public.user_emails (
   id serial primary key,
   user_id int not null default app_public.current_user_id() references app_public.users on delete cascade,
-  email citext not null check (email ~ '[^@]+@[^@]+\.[^@]+'),
+  email app_public.email not null,
   is_verified boolean not null default false,
   is_primary boolean not null default false,
   created_at timestamptz not null default now(),
@@ -457,7 +462,7 @@ $$ language plpgsql security definer volatile set search_path to pg_catalog, pub
 /**********/
 
 create table app_private.unregistered_email_password_resets (
-  email citext constraint unregistered_email_pkey primary key,
+  email app_public.email constraint unregistered_email_pkey primary key,
   attempts int not null default 1,
   latest_attempt timestamptz not null
 );
@@ -470,7 +475,7 @@ comment on column app_private.unregistered_email_password_resets.latest_attempt
 
 /**********/
 
-create function app_public.forgot_password(email citext) returns void as $$
+create function app_public.forgot_password(email app_public.email) returns void as $$
 declare
   v_user_email app_public.user_emails;
   v_token text;
@@ -558,7 +563,7 @@ begin
 end;
 $$ language plpgsql strict security definer volatile set search_path to pg_catalog, public, pg_temp;
 
-comment on function app_public.forgot_password(email public.citext) is
+comment on function app_public.forgot_password(email app_public.email) is
   E'If you''ve forgotten your password, give us one of your email addresses and we''ll send you a reset token. Note this only works if you have added an email address!';
 
 /**********/
@@ -747,10 +752,10 @@ grant execute on function app_public.change_password(text, text) to :DATABASE_VI
 
 create function app_private.really_create_user(
   username citext,
-  email text,
+  email app_public.email,
   email_is_verified bool,
   name text,
-  avatar_url text,
+  avatar_url app_public."URL",
   password text default null
 ) returns app_public.users as $$
 declare
@@ -787,7 +792,7 @@ begin
 end;
 $$ language plpgsql volatile set search_path to pg_catalog, public, pg_temp;
 
-comment on function app_private.really_create_user(username citext, email text, email_is_verified bool, name text, avatar_url text, password text) is
+comment on function app_private.really_create_user(username citext, email app_public.email, email_is_verified bool, name text, avatar_url app_public."URL", password text) is
   E'Creates a user account. All arguments are optional, it trusts the calling method to perform sanitisation.';
 
 /**********/
@@ -801,10 +806,10 @@ create function app_private.register_user(
 ) returns app_public.users as $$
 declare
   v_user app_public.users;
-  v_email citext;
+  v_email app_public.email;
   v_name text;
   v_username citext;
-  v_avatar_url text;
+  v_avatar_url app_public."URL";
   v_user_authentication_id int;
 begin
   -- Extract data from the user’s OAuth profile data.
@@ -874,9 +879,9 @@ create function app_private.link_or_register_user(
 declare
   v_matched_user_id int;
   v_matched_authentication_id int;
-  v_email citext;
+  v_email app_public.email;
   v_name text;
-  v_avatar_url text;
+  v_avatar_url app_public."URL";
   v_user app_public.users;
   v_user_email app_public.user_emails;
 begin

@app/graphql/codegen.yml

@@ -4,6 +4,8 @@ documents: "../client/src/**/*.graphql"
 config:
   scalars:
     Datetime: "string"
+    Email: "string"
+    URL: "string"
     JSON: "{ [key: string]: any }"
   noGraphQLTag: false
   withHOC: false
@@ -12,7 +14,9 @@ config:
 generates:
   index.tsx:
     plugins:
-      - add: "/* DO NOT EDIT! This file is auto-generated by graphql-code-generator - see `codegen.yml` */"
+      - add:
+          "/* DO NOT EDIT! This file is auto-generated by graphql-code-generator
+          - see `codegen.yml` */"
       - "typescript"
       - "typescript-operations"
       - "typescript-react-apollo"

@app/server/src/middleware/installPostGraphile.ts

@@ -12,6 +12,8 @@ import { Express, Request, Response } from "express";
 import PgPubsub from "@graphile/pg-pubsub";
 import PgSimplifyInflectorPlugin from "@graphile-contrib/pg-simplify-inflector";
 import GraphilePro from "@graphile/pro"; // Requires license key
+import PgTypeEmailPlugin from "../plugins/PgTypeEmailPlugin";
+import PgTypeUrlPlugin from "../plugins/PgTypeUrlPlugin";
 import PassportLoginPlugin from "../plugins/PassportLoginPlugin";
 import PrimaryKeyMutationsOnlyPlugin from "../plugins/PrimaryKeyMutationsOnlyPlugin";
 import SubscriptionsPlugin from "../plugins/SubscriptionsPlugin";
@@ -151,6 +153,10 @@ export function getPostGraphileOptions({
      *   https://www.graphile.org/postgraphile/extending/
      */
     appendPlugins: [
+      // Exposes `Email` and `URL` types in the GraphQL schema
+      PgTypeEmailPlugin,
+      PgTypeUrlPlugin,
+
       // Adds support for our `postgraphile.tags.json5` file
       TagsFilePlugin,
 

@app/server/src/plugins/PassportLoginPlugin.ts

@@ -5,10 +5,10 @@ const PassportLoginPlugin = makeExtendSchemaPlugin(build => ({
   typeDefs: gql`
     input RegisterInput {
       username: String!
-      email: String!
+      email: Email!
       password: String!
       name: String
-      avatarUrl: String
+      avatarUrl: URL
     }
 
     type RegisterPayload {

@app/server/src/plugins/PgTypeEmailPlugin.ts

@@ -0,0 +1,149 @@
+import { Plugin, Build, ScopeGraphQLScalarType } from "graphile-build";
+import { PgType } from "graphile-build-pg";
+
+declare module "graphile-build" {
+  interface ScopeGraphQLScalarType {
+    isEmailScalar?: boolean;
+  }
+}
+
+function isValidEmail(email: string) {
+  return /[^@]+@[^@]+\.[^@]+/.test(email);
+}
+
+export default (function PgTypeEmailPlugin(builder) {
+  builder.hook(
+    "build",
+    build => {
+      // This hook tells graphile-build-pg about the email database type so it
+      // knows how to express it in input/output.
+      const {
+        pgIntrospectionResultsByKind: rawIntrospectionResultsByKind,
+        pgRegisterGqlTypeByTypeId,
+        pgRegisterGqlInputTypeByTypeId,
+        pg2GqlMapper,
+        pgSql: sql,
+      } = build;
+
+      if (
+        !rawIntrospectionResultsByKind ||
+        !sql ||
+        !pgRegisterGqlTypeByTypeId ||
+        !pgRegisterGqlInputTypeByTypeId ||
+        !pg2GqlMapper
+      ) {
+        throw new Error("Required helpers were not found on Build.");
+      }
+
+      const introspectionResultsByKind = rawIntrospectionResultsByKind;
+
+      // Get the 'email' type:
+      const emailType = introspectionResultsByKind.type.find(
+        (t: PgType) => t.name === "email"
+      );
+
+      if (!emailType) {
+        return build;
+      }
+
+      const emailTypeName = build.inflection.builtin("Email");
+
+      const GraphQLEmailType = makeGraphQLEmailType(
+        build as Build,
+        emailTypeName
+      );
+
+      // Now register the Email type with the type system for both output and input.
+      pgRegisterGqlTypeByTypeId(emailType.id, () => GraphQLEmailType);
+      pgRegisterGqlInputTypeByTypeId(emailType.id, () => GraphQLEmailType);
+
+      // Finally we must tell the system how to translate the data between PG-land and JS-land:
+      pg2GqlMapper[emailType.id] = {
+        // Turn string (from node-postgres) into email: no-op
+        map: (email: string) => email,
+        // When unmapping we need to convert back to SQL framgent
+        unmap: (email: string) =>
+          sql.fragment`(${sql.value(email)}::${sql.identifier(
+            emailType.namespaceName,
+            emailType.name
+          )})`,
+      };
+
+      return build;
+    },
+    ["PgTypeEmail"],
+    [],
+    ["PgTypes"]
+  );
+
+  /* End of email type */
+} as Plugin);
+
+function makeGraphQLEmailType(build: Build, emailTypeName: string) {
+  const {
+    graphql: { GraphQLScalarType, Kind },
+  } = build;
+  function parseValue(obj: unknown): string {
+    if (!(typeof obj === "string")) {
+      throw new TypeError(
+        `This is not a valid ${emailTypeName} object, it must be a string.`
+      );
+    }
+    if (!isValidEmail(obj)) {
+      throw new TypeError(
+        `This is not a properly formatted ${emailTypeName} object.`
+      );
+    }
+    return obj;
+  }
+
+  const parseLiteral: import("graphql").GraphQLScalarLiteralParser<any> = (
+    ast,
+    variables
+  ) => {
+    switch (ast.kind) {
+      case Kind.STRING: {
+        const email = ast.value;
+        if (!isValidEmail(email)) {
+          throw new TypeError(
+            `This is not a properly formatted ${emailTypeName} object.`
+          );
+        }
+        return email;
+      }
+
+      case Kind.NULL:
+        return null;
+
+      case Kind.VARIABLE: {
+        const name = ast.name.value;
+        const email = variables ? variables[name] : undefined;
+        if (!isValidEmail(email)) {
+          throw new TypeError(
+            `This is not a properly formatted ${emailTypeName} object.`
+          );
+        }
+        return email;
+      }
+
+      default:
+        return undefined;
+    }
+  };
+
+  const scope: ScopeGraphQLScalarType = { isEmailScalar: true };
+  const GraphQLEmailType = build.newWithHooks(
+    GraphQLScalarType,
+    {
+      name: emailTypeName,
+      description:
+        "An address in the electronic mail system. Email addresses such as `John.Smith@example.com` are made up of a local-part, followed by an `@` symbol, followed by a domain.",
+      serialize: (email: string) => email,
+      parseValue,
+      parseLiteral,
+    },
+    scope
+  );
+
+  return GraphQLEmailType;
+}