feat(hooks): add hooks for HTTP results and GraphiQL HTML (#970)

Fixes #962
Fixes #969

Author: benjie

src/postgraphile/cli.ts

@@ -24,6 +24,11 @@ import { mixed } from '../interfaces';
 import * as manifest from '../../package.json';
 import sponsors = require('../../sponsors.json');
 
+// tslint:disable-next-line no-any
+function isString(str: any): str is string {
+  return typeof str === 'string';
+}
+
 const sponsor = sponsors[Math.floor(sponsors.length * Math.random())];
 
 const debugCli = debugFactory('postgraphile:cli');
@@ -703,7 +708,7 @@ if (noServer) {
               pgPort !== 5432 ? `:${pgConfig.port || 5432}` : ''
             }${pgDatabase ? `/${pgDatabase}` : ''}`;
 
-        const information = pluginHook(
+        const information: Array<string> = pluginHook(
           'cli:greeting',
           [
             `GraphQL API:         ${chalk.underline.bold.blue(
@@ -718,20 +723,21 @@ if (noServer) {
             `Documentation:       ${chalk.underline(
               `https://graphile.org/postgraphile/introduction/`,
             )}`,
-            extractedPlugins.length === 0 &&
-              `Join ${chalk.bold(
-                sponsor,
-              )} in supporting PostGraphile development: ${chalk.underline.bold.blue(
-                `https://graphile.org/sponsor/`,
-              )}`,
+            extractedPlugins.length === 0
+              ? `Join ${chalk.bold(
+                  sponsor,
+                )} in supporting PostGraphile development: ${chalk.underline.bold.blue(
+                  `https://graphile.org/sponsor/`,
+                )}`
+              : null,
           ],
           {
             options: postgraphileOptions,
             middleware,
             port: actualPort,
             chalk,
           },
-        ).filter(Boolean);
+        ).filter(isString);
         console.log(information.map(msg => `  ‣ ${msg}`).join('\n'));
 
         console.log('');

src/postgraphile/http/createPostGraphileHttpRequestHandler.ts

@@ -43,7 +43,7 @@ import favicon from '../../assets/favicon.ico';
  * The GraphiQL HTML file as a string. We need it to be a string, because we
  * will use a regular expression to replace some variables.
  */
-import origGraphiqlHtml from '../../assets/graphiql.html';
+import baseGraphiqlHtml from '../../assets/graphiql.html';
 
 /**
  * When writing JSON to the browser, we need to be careful that it doesn't get
@@ -165,6 +165,8 @@ export default function createPostGraphileHttpRequestHandler(
 
   const pluginHook = pluginHookFromOptions(options);
 
+  const origGraphiqlHtml = pluginHook('postgraphile:graphiql:html', baseGraphiqlHtml, { options });
+
   if (pgDefaultRole && typeof pgSettings === 'function') {
     throw new Error(
       'pgDefaultRole cannot be combined with pgSettings(req) - please remove pgDefaultRole and instead always return a `role` key from pgSettings(req).',
@@ -325,7 +327,7 @@ export default function createPostGraphileHttpRequestHandler(
       return result;
     } else {
       const source = new Source(queryString, 'GraphQL Http Request');
-      let queryDocumentAst;
+      let queryDocumentAst: DocumentNode | void;
 
       // Catch an errors while parsing so that we can set the `statusCode` to
       // 400. Otherwise we don’t need to parse this way.
@@ -721,6 +723,14 @@ export default function createPostGraphileHttpRequestHandler(
             if (!isEmpty(meta)) {
               result.meta = meta;
             }
+            result = pluginHook('postgraphile:http:result', result, {
+              options,
+              returnArray,
+              queryDocumentAst: queryDocumentAst!,
+              req,
+              // We don't pass `res` here because this is for just a single
+              // result; if you need that, use postgraphile:http:end.
+            });
             // Log the query. If this debugger isn’t enabled, don’t run it.
             if (
               !options.disableQueryLog &&
@@ -783,8 +793,24 @@ export default function createPostGraphileHttpRequestHandler(
       }
 
       res.setHeader('Content-Type', 'application/json; charset=utf-8');
+      const { statusCode, result } = pluginHook(
+        'postgraphile:http:end',
+        {
+          statusCode: res.statusCode,
+          result: returnArray ? results : results[0]!,
+        },
+        {
+          options,
+          returnArray,
+          req,
+          res,
+        },
+      );
 
-      res.end(JSON.stringify(returnArray ? results : results[0]!));
+      if (statusCode) {
+        res.statusCode = statusCode;
+      }
+      res.end(JSON.stringify(result));
 
       if (debugRequest.enabled)
         debugRequest('GraphQL ' + (returnArray ? 'queries' : 'query') + ' request finished.');

src/postgraphile/pluginHook.ts

@@ -6,7 +6,22 @@ import { version } from '../../package.json';
 import * as graphql from 'graphql';
 
 export type HookFn<T> = (arg: T, context: {}) => T;
-export type PluginHookFn = <T>(hookName: string, argument: T, context?: {}) => T;
+export type PluginHookFn = <TArgument, TContext = {}>(
+  hookName: string,
+  argument: TArgument,
+  context?: TContext,
+) => TArgument;
+
+export interface PostGraphileHTTPResult {
+  statusCode?: number;
+  result?: object;
+  errors?: Array<object>;
+  meta?: object;
+}
+export interface PostGraphileHTTPEnd {
+  statusCode?: number;
+  result: object | Array<object>;
+}
 export interface PostGraphilePlugin {
   init?: HookFn<null>;
 
@@ -25,11 +40,14 @@ export interface PostGraphilePlugin {
   'cli:library:options'?: HookFn<{}>;
   'cli:server:middleware'?: HookFn<HttpRequestHandler>;
   'cli:server:created'?: HookFn<Server>;
-  'cli:greeting'?: HookFn<Array<string | void>>;
+  'cli:greeting'?: HookFn<Array<string | null | void>>;
 
   'postgraphile:options'?: HookFn<PostGraphileOptions>;
   'postgraphile:validationRules:static'?: HookFn<ReadonlyArray<typeof graphql.specifiedRules>>;
+  'postgraphile:graphiql:html'?: HookFn<string>;
   'postgraphile:http:handler'?: HookFn<IncomingMessage>;
+  'postgraphile:http:result'?: HookFn<PostGraphileHTTPResult>;
+  'postgraphile:http:end'?: HookFn<PostGraphileHTTPEnd>;
   'postgraphile:httpParamsList'?: HookFn<Array<object>>;
   'postgraphile:validationRules'?: HookFn<ReadonlyArray<typeof graphql.specifiedRules>>; // AVOID THIS where possible; use 'postgraphile:validationRules:static' instead.
   'postgraphile:middleware'?: HookFn<HttpRequestHandler>;
@@ -89,18 +107,25 @@ function memoizeHook<T>(hook: HookFn<T>): HookFn<T> {
   };
 }
 
+function shouldMemoizeHook(hookName: HookName) {
+  return hookName === 'withPostGraphileContext';
+}
+
 function makeHook<T>(plugins: Array<PostGraphilePlugin>, hookName: HookName): HookFn<T> {
-  return memoizeHook<T>(
-    plugins.reduce((previousHook: HookFn<T>, plugin: {}) => {
-      if (typeof plugin[hookName] === 'function') {
-        return (argument: T, context: {}) => {
-          return plugin[hookName](previousHook(argument, context), context);
-        };
-      } else {
-        return previousHook;
-      }
-    }, identityHook),
-  );
+  const combinedHook = plugins.reduce((previousHook: HookFn<T>, plugin: {}) => {
+    if (typeof plugin[hookName] === 'function') {
+      return (argument: T, context: {}) => {
+        return plugin[hookName](previousHook(argument, context), context);
+      };
+    } else {
+      return previousHook;
+    }
+  }, identityHook);
+  if (shouldMemoizeHook(hookName)) {
+    return memoizeHook<T>(combinedHook);
+  } else {
+    return combinedHook;
+  }
 }
 
 export function makePluginHook(plugins: Array<PostGraphilePlugin>): PluginHookFn {