@axinom/mosaic-graphql-common 0.1.0-rc.0

package/src/plugins/generic-bulk-plugin-factory.ts

@@ -0,0 +1,313 @@
+import { PgClass } from 'graphile-build-pg';
+import { gql as gqlExtended } from 'graphile-utils';
+import GraphQL from 'graphql';
+import { Build, Plugin } from 'postgraphile';
+import { assertDictionary } from '../common';
+
+/**
+ * A collection of parameters to decide on which entities and by which criteria bulk operation should be performed.
+ */
+export interface BulkFilter {
+  tableName: string;
+  primaryKeyName: string;
+  primaryKeyType: string;
+  filterType: GraphQL.GraphQLInputType;
+  filterName: string;
+  queryName: string;
+  typeName: string;
+}
+
+/**
+ * Interface for specifying bulk action endpoint name
+ */
+export interface CustomBulkSettings {
+  graphQLEndpointName: string;
+}
+
+/**
+ * Callback that decides for which filters a bulk action is defined
+ */
+export interface DefinePlugin {
+  (filter: BulkFilter): CustomBulkSettings | undefined;
+}
+
+/**
+ * Parameters that GenericBulkPluginFactory will provide to the callback, so that the actual bulk operation can be performed.
+ */
+export interface BulkIdParameters {
+  entityIds: number[] | string[];
+  entityType: string;
+  primaryKeyName: string;
+  tableName: string;
+  graphQLAdditionalInput: unknown;
+  graphQLContext: { [str: string]: unknown };
+}
+
+interface BulkFilterMap {
+  [key: string]: BulkFilter;
+}
+
+interface BulkOperationBuild extends Build {
+  availableBulkFilters: BulkFilterMap;
+}
+
+interface BulkInputParameters {
+  filter: {
+    type: GraphQL.GraphQLInputType;
+  };
+  input?: {
+    type: GraphQL.GraphQLInputType;
+  };
+}
+
+/**
+ * Get all the database IDs from the entities that were selected via the GraphQL filter
+ */
+const getEntityIds = async (
+  filter: BulkFilter,
+  graphql: typeof GraphQL,
+  args: { [argName: string]: unknown },
+  context: unknown,
+  schema: GraphQL.GraphQLSchema,
+): Promise<number[] | string[]> => {
+  if (filter.queryName === undefined) {
+    throw new Error(
+      `No query found for the filter of type '${filter.filterName}'.`,
+    );
+  }
+  const queryResult = await graphql.execute(
+    schema,
+    gqlExtended`
+      query getEntityIds($filter: ${filter.filterName}) {
+        entities: ${filter.queryName}(filter: $filter) {
+          nodes {
+            ${filter.primaryKeyName}
+          }
+        }
+      }
+    `,
+    undefined,
+    context,
+    args,
+  );
+
+  return queryResult?.data?.entities?.nodes.map((entity: unknown) => {
+    assertDictionary(entity);
+    return entity[filter.primaryKeyName];
+  });
+};
+
+const getEntityTypeFromCollectionType = (
+  type: GraphQL.GraphQLOutputType,
+): string | undefined => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const fields = (type as any)._fields();
+  let tempType = fields?.nodes?.type;
+  if (tempType !== undefined) {
+    while (tempType?.ofType) {
+      tempType = tempType?.ofType;
+    }
+    return tempType?.name;
+  }
+  return;
+};
+
+const setPayloadGqlType = (
+  build: Build,
+  pkDbType: string,
+): GraphQL.GraphQLType => {
+  let pkGqlType: GraphQL.GraphQLType;
+  let bulkMutationPayloadName: string;
+  switch (pkDbType) {
+    case 'uuid': {
+      bulkMutationPayloadName = 'BulkMutationUuidPayload';
+      pkGqlType = build.getTypeByName('UUID');
+      break;
+    }
+    case 'int4':
+    default: {
+      bulkMutationPayloadName = 'BulkMutationIntPayload';
+      pkGqlType = build.graphql.GraphQLInt;
+      break;
+    }
+  }
+
+  const existingPayloadType = build.getTypeByName(bulkMutationPayloadName);
+  if (existingPayloadType !== undefined) {
+    return existingPayloadType;
+  }
+
+  build.addType(
+    new build.graphql.GraphQLObjectType({
+      name: bulkMutationPayloadName,
+      description: 'Bulk mutation payload type.',
+      fields: () => ({
+        affectedIds: {
+          type: build.graphql.GraphQLList(pkGqlType),
+        },
+        totalCount: { type: build.graphql.GraphQLInt },
+      }),
+    }),
+  );
+
+  return build.getTypeByName(bulkMutationPayloadName);
+};
+
+/**
+ * Plugin factory to create bulk mutations based on query filters
+ * @param callback The callback that shall perform the actual bulk operation. It
+ * receives different parameters from the base plugin to assist with the
+ * operation, e.g. a list of ids for which the bulk operation shall be performed.
+ * @param definePlugin The callback that decides for which filters a bulk action is defined.
+ * @param inputType Defines additional input parameters for the bulk action. The values are forwarded as part of the message payload.
+ */
+export const GenericBulkPluginFactory = (
+  callback: { (parameters: BulkIdParameters): Promise<void> },
+  definePlugin: DefinePlugin,
+  inputType?: GraphQL.GraphQLInputObjectType,
+): Plugin => {
+  return async (builder) => {
+    // initialize the availableBulkFilters to collect all filters usable for bulk mutations
+    builder.hook('build', (build) => {
+      (build as BulkOperationBuild).availableBulkFilters = {};
+
+      if (
+        inputType !== undefined &&
+        build.getTypeByName(inputType.name) === undefined
+      ) {
+        build.addType(inputType);
+      }
+
+      return build;
+    });
+
+    builder.hook(
+      'GraphQLInputObjectType:fields',
+      (
+        fields,
+        build,
+        { scope: { isPgConnectionFilter, pgIntrospection }, Self },
+      ) => {
+        if (
+          isPgConnectionFilter &&
+          pgIntrospection?.kind === 'class' &&
+          pgIntrospection?.classKind !== 'c' && // c represents composite types which doesn't have primary keys.
+          pgIntrospection?.primaryKeyConstraint?.type === 'p' &&
+          pgIntrospection?.primaryKeyConstraint.keyAttributes.length === 1
+        ) {
+          const { name, type } =
+            pgIntrospection.primaryKeyConstraint.keyAttributes[0];
+          const availableBulkFilters = (build as BulkOperationBuild)
+            .availableBulkFilters;
+
+          const table: PgClass = pgIntrospection;
+          availableBulkFilters[Self.name] = {
+            tableName: table.name,
+            primaryKeyName: name,
+            primaryKeyType: type.name,
+            filterName: Self.name,
+            filterType: Self,
+            queryName: 'set-later',
+            typeName: 'set-later',
+          };
+        }
+        return fields;
+      },
+    );
+
+    // Add the query endpoints to the corresponding filters
+    // Add the bulk mutations based on what the plugin needs
+    builder.hook(
+      'GraphQLObjectType:fields',
+      (fields, build, { scope: { isRootQuery, isRootMutation } }) => {
+        const bulkFilters = build.availableBulkFilters as BulkFilterMap;
+        if (isRootQuery) {
+          // Root query is called first - gather the query operation names
+          for (const queryName in fields) {
+            const element = fields[queryName];
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const filterName = (element?.args?.filter?.type as any)?.name;
+            if (
+              Object.prototype.hasOwnProperty.call(fields, queryName) &&
+              element !== undefined &&
+              filterName !== undefined &&
+              bulkFilters[filterName] !== undefined
+            ) {
+              // we found a query which is using a connection filter property that is usable for bulk mutations
+              const filter = bulkFilters[filterName];
+              filter.queryName = queryName;
+              filter.typeName =
+                getEntityTypeFromCollectionType(element.type) ??
+                filterName.slice(0, -1 * 'Filter'.length);
+            }
+          }
+        }
+
+        if (isRootMutation) {
+          // Root mutation is called after root query - actually add mutations
+          for (const filterName in bulkFilters) {
+            const filter = bulkFilters[filterName];
+
+            const settings = definePlugin(filter);
+
+            if (settings !== undefined) {
+              const args: BulkInputParameters = {
+                filter: {
+                  type: filter.filterType,
+                },
+                ...(inputType !== undefined && {
+                  input: { type: inputType },
+                }),
+              };
+
+              const payloadType = setPayloadGqlType(
+                build,
+                filter.primaryKeyType,
+              );
+
+              const operation = {
+                type: payloadType,
+                args,
+                async resolve(
+                  _parent: unknown,
+                  input: { [argName: string]: unknown },
+                  context: { [str: string]: unknown },
+                  resolveInfo: GraphQL.GraphQLResolveInfo,
+                ) {
+                  const ids = await getEntityIds(
+                    filter,
+                    build.graphql,
+                    input,
+                    context,
+                    resolveInfo.schema,
+                  );
+                  const { input: additionalInput } = input;
+
+                  await callback({
+                    entityIds: ids,
+                    entityType: filter.typeName,
+                    primaryKeyName: filter.primaryKeyName,
+                    tableName: filter.tableName,
+                    graphQLAdditionalInput: additionalInput,
+                    graphQLContext: context,
+                  });
+
+                  return {
+                    affectedIds: ids,
+                    totalCount: ids.length,
+                  };
+                },
+              };
+
+              build.extend(fields, {
+                [settings.graphQLEndpointName]: operation,
+              });
+            }
+          }
+        }
+
+        return fields;
+      },
+    );
+  };
+};

package/src/plugins/graphiql-management-mode-plugin-hook.ts

@@ -0,0 +1,46 @@
+/**
+ * Based on:
+ *
+ * https://gist.github.com/bkeating/cfe0d5e72bd3f9f1f77e1a2ff2309972
+ *
+ * with some additions for the PostGraphiQL extension.
+ */
+
+import { PostGraphilePlugin } from 'postgraphile';
+
+/**
+ * This plugin override changes the branding piece of graphiql.
+ */
+export const GraphiqlManagementModePluginHook: PostGraphilePlugin = {
+  ['postgraphile:graphiql:html'](html: string): string {
+    return html.replace(
+      '</head>',
+      `
+        <style>
+          /* GraphiQL Management Styles */
+          #root .graphiql-container .doc-explorer-title-bar,
+          #root .graphiql-container .historyPaneWrap > section,
+          #secondary-editor-title {
+            background: #aaa;
+          }
+          #root .graphiql-container .topBar,
+          #root .graphiql-container .docExplorerShow {
+            background: #888;
+          }
+          #root .graphiql-container .topBar .toolbar-button,
+          #root .graphiql-container .topBar .toolbar-button > svg,
+          #root .graphiql-container .topBar .execute-button {
+            box-shadow: none;
+            background: #555;
+            color: #ddd;
+            fill: #ddd;
+          }
+          #root .graphiql-container .topBar .toolbar-button {
+            border-radius: 0;
+          }
+         </style>
+       </head>
+       `,
+    );
+  },
+};

package/src/plugins/index.ts

@@ -0,0 +1,9 @@
+export * from './add-error-codes-enum-plugin';
+export * from './annotate-types-with-permissions-plugin';
+export * from './deprecate-stray-node-id-fields-plugin';
+export * from './generic-bulk-plugin-factory';
+export * from './graphiql-management-mode-plugin-hook';
+export * from './omit-from-query-root-plugin';
+export * from './operations-enum-generator-plugin-factory';
+export * from './subscriptions-plugin-factory';
+export * from './validation-directives-plugin';

package/src/plugins/omit-from-query-root-plugin.ts

@@ -0,0 +1,69 @@
+import { PgIntrospectionResultsByKind } from 'graphile-build-pg';
+import { GraphQLFieldConfigMap } from 'graphql';
+import { Inflection, Plugin } from 'postgraphile';
+
+/**
+ * Type safe interface for unpacking the relevant bits of hook context.
+ */
+interface HookContext {
+  Self: {
+    name: string;
+  };
+  scope: {
+    isRootQuery: boolean;
+  };
+}
+
+/**
+ * Plugin for omitting tables from query root but keeping them still accessible
+ * from entities through relations.
+ *
+ * Add `omitFromQueryRoot: true,` to `tags` object of postgraphile smart tags
+ * for table you want to omit.
+ *
+ * @remarks
+ * This is different from `@omit all many` as the tables are still accessible
+ * through relations.
+ *
+ * References:
+ * - https://discord.com/channels/489127045289476126/498852330754801666/578654093963427860
+ */
+export const OmitFromQueryRootPlugin: Plugin = (builder) => {
+  builder.hook('GraphQLObjectType:fields', (fields, build, context) => {
+    const hookContext: HookContext = context as HookContext;
+    const introspection: PgIntrospectionResultsByKind =
+      build.pgIntrospectionResultsByKind;
+    const inflection: Inflection = build.inflection;
+
+    if (hookContext.Self.name !== 'Query' || !hookContext.scope.isRootQuery) {
+      return fields;
+    }
+
+    const tablesToExclude = introspection.class.filter(
+      (cls) => cls.tags.omitFromQueryRoot === true,
+    );
+
+    // Remove both single item query and paginated query.
+    const fieldNamesToExclude = ([] as string[]).concat(
+      ...tablesToExclude.map((cls) => [
+        inflection.camelCase(`${inflection._singularizedTableName(cls)}`),
+        inflection.camelCase(
+          inflection.distinctPluralize(inflection._singularizedTableName(cls)),
+        ),
+      ]),
+    );
+
+    return removeProperties(fields, fieldNamesToExclude);
+  });
+};
+
+function removeProperties(
+  obj: GraphQLFieldConfigMap<unknown, unknown>,
+  keysToRemove: string[],
+): GraphQLFieldConfigMap<unknown, unknown> {
+  const result = { ...obj };
+  for (const key of keysToRemove) {
+    delete result[key];
+  }
+  return result;
+}

package/src/plugins/operations-enum-generator-plugin-factory.ts

@@ -0,0 +1,130 @@
+import endent from 'endent';
+import fs from 'fs';
+import path from 'path';
+import { Plugin } from 'postgraphile';
+
+interface OperationsEnumGeneratorOptions {
+  /** Target root directory where the source files will be written. */
+  outRoot: string;
+}
+
+// TODO: Generate *all* operations, even those that are omitted with smart tags. We need them to allow subqueries.
+// TODO: Consider adding functionality to group operations also by tables, not only queries/mutations.
+/**
+ * PostGraphile plugin factory that will create a plugin for generating operation (queries and mutations) enums for the EnforceStrictPermissionsPlugin.
+ * - Make sure to register this after all schema modifying plugins and before EnforceStrictPermissionsPlugin.
+ * - This plugin does not modify the schema.
+ * - Enums will be generated under `src/generated/security/operations`.
+ * @param options - Plugin configuration options.
+ */
+export function OperationsEnumGeneratorPluginFactory(
+  options: OperationsEnumGeneratorOptions = {
+    outRoot: './src/generated/security/operations',
+  },
+): Plugin {
+  return (builder, _options) => {
+    const operations = {
+      Queries: new Set<string>(),
+      Mutations: new Set<string>(),
+      Relations: new Set<string>(),
+      Subscriptions: new Set<string>(),
+    };
+
+    //Enumerates all relations/subqueries
+    builder.hook(
+      'GraphQLObjectType:fields:field',
+      (field, _build, { scope }) => {
+        if (
+          scope.fieldName !== 'query' &&
+          (scope.isPgForwardRelationField || scope.isPgBackwardRelationField)
+        ) {
+          operations.Relations.add(scope.fieldName);
+        }
+
+        return field;
+      },
+    );
+    // Enumerate all queries, mutations and subscriptions
+    builder.hook('GraphQLObjectType:fields', (fields, _build, context) => {
+      if (context.Self.name === 'Query') {
+        Object.keys(fields).forEach((q) => {
+          if (q !== 'query') {
+            operations.Queries.add(q);
+          }
+        });
+      }
+
+      if (context.Self.name === 'Mutation') {
+        Object.keys(fields).forEach((m) => operations.Mutations.add(m));
+      }
+
+      if (context.Self.name === 'Subscription') {
+        Object.keys(fields).forEach((s) => operations.Subscriptions.add(s));
+      }
+
+      return fields;
+    });
+
+    // Write enums to file when the schema is built.
+    builder.hook('finalize', (schema, _build, _context) => {
+      const operationsToEnum: string[] = [];
+      for (const [key, value] of Object.entries(operations)) {
+        const outputEnumPath = path.join(
+          options.outRoot,
+          `${key.toLowerCase()}.ts`,
+        );
+        // Exit early if expected operations are not there and assume there was an error during GQL schema generation.
+        // Do not write any files, keep whatever was already on the disk.
+        if (value.size === 0) {
+          if (fs.existsSync(outputEnumPath)) {
+            operationsToEnum.push(key);
+          }
+          continue;
+        }
+
+        writeSourceFile(outputEnumPath, generateEnum(key, [...value]));
+        operationsToEnum.push(key);
+      }
+      writeSourceFile(
+        path.join(options.outRoot, 'index.ts'),
+        generateIndex(operationsToEnum.map((o) => o.toLowerCase())),
+      );
+      return schema;
+    });
+  };
+}
+
+/**
+ * Writes generated source code to file but compares with the content of the existing file first to avoid triggering compilation in watch mode.
+ * @param outPath - Path where to write the source file.
+ * @param contents - Contents of the source file.
+ */
+function writeSourceFile(outPath: string, contents: string): void {
+  if (!fs.existsSync(path.dirname(outPath))) {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  }
+  // Don't write file if the contents are the same, avoid triggering a build in watch mode.
+  if (fs.existsSync(outPath)) {
+    const currentContents = fs.readFileSync(outPath, { encoding: 'utf-8' });
+    if (currentContents.toString() === contents) {
+      return;
+    }
+  }
+  fs.writeFileSync(outPath, contents, 'utf-8');
+}
+
+function generateEnum(name: string, members: string[]): string {
+  return endent`export enum ${name} {
+    ${members
+      .sort()
+      .map((m) => `${m} = '${m}'`)
+      .join(',\n')}
+  }`;
+}
+
+function generateIndex(modules: string[]): string {
+  return modules
+    .sort()
+    .map((m) => `export * from './${m}';`)
+    .join('\n');
+}

package/src/plugins/subscriptions-plugin-factory.ts

@@ -0,0 +1,114 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { QueryBuilder, SQL } from 'graphile-build-pg';
+import {
+  ExtensionDefinition,
+  gql,
+  makeExtendSchemaPlugin,
+} from 'graphile-utils';
+// graphile-utils doesn't export this yet
+import { GraphQLResolveInfo } from 'graphql';
+import inflection from 'inflection';
+import { Build, Plugin } from 'postgraphile';
+
+type GraphileHelpers = any;
+type AugmentedGraphQLFieldResolver<
+  TSource,
+  TContext,
+  TArgs = { [argName: string]: any },
+> = (
+  parent: TSource,
+  args: TArgs,
+  context: TContext,
+  info: GraphQLResolveInfo & {
+    graphile: GraphileHelpers;
+  },
+) => any;
+/* The JSON object that `tg__graphql_subscription()` delivers via NOTIFY */
+interface ITgGraphQLSubscriptionPayload {
+  event: string;
+  subject: string | null;
+}
+
+/*
+ * This function handles the boilerplate of fetching a record from the database
+ * which has the 'id' equal to the 'subject' from the PG NOTIFY event payload
+ * (see `tg__graphql_subscription()` trigger function in the database).
+ */
+function recordByIdFromTable(
+  build: Build,
+  sqlTable: SQL,
+): AugmentedGraphQLFieldResolver<ITgGraphQLSubscriptionPayload, any> {
+  const { pgSql: sql } = build;
+  return async (
+    event: ITgGraphQLSubscriptionPayload,
+    _args: Record<string, unknown>,
+    _context: any,
+    // eslint-disable-next-line @typescript-eslint/typedef
+    { graphile: { selectGraphQLResultFromTable } },
+  ) => {
+    const rows = await selectGraphQLResultFromTable(
+      sqlTable,
+      (tableAlias: SQL, sqlBuilder: QueryBuilder) => {
+        sqlBuilder.where(
+          sql.fragment`${tableAlias}.id = ${sql.value(event.subject)}`,
+        );
+      },
+    );
+    return rows[0];
+  };
+}
+
+function getId(): AugmentedGraphQLFieldResolver<
+  ITgGraphQLSubscriptionPayload,
+  any
+> {
+  return async (event: ITgGraphQLSubscriptionPayload) => event.subject;
+}
+
+/**
+ * Factory function to create a makeExtendSchemaPlugin that adds a subscription endpoint for specific entity.
+ * @param mainTableName name of the table in the database without schema
+ * @param typeName name of the GraphQL type that is generated by postgraphile for `mainTableName` table
+ * @param gqlIdDataType optional parameter to set an ID type for the endpoint. Supported types are `Int` and `UUID`. Default is `Int`.
+ */
+export const SubscriptionsPluginFactory = (
+  mainTableName: string,
+  typeName: string,
+  gqlIdDataType: 'Int' | 'UUID' = 'Int',
+): Plugin =>
+  makeExtendSchemaPlugin((build: Build) => {
+    const { pgSql: sql } = build;
+    const variableName = inflection.camelize(typeName, true);
+    const payloadName =
+      inflection.camelize(typeName, false) + 'SubscriptionPayload';
+    const topicName = 'graphql:' + mainTableName;
+    return {
+      typeDefs: gql`
+      type ${payloadName} {
+        id: ${gqlIdDataType}! # Populated by our resolver below 
+        ${variableName}: ${typeName} # Populated by our resolver below
+        event: String # Part of the NOTIFY payload
+      }
+
+      extend type Subscription {
+        """
+        Triggered when a ${typeName} is mutated (insert, update or delete). 
+        """
+        ${variableName}Mutated: ${payloadName}
+          @pgSubscription(topic: "${topicName}")
+      }
+    `,
+      resolvers: {
+        [payloadName]: {
+          id: getId(),
+          [variableName]: recordByIdFromTable(
+            build,
+            sql.fragment([`app_public.${mainTableName}`]),
+          ),
+        },
+        Subscription: {
+          [`${variableName}Mutated`]: (event) => event,
+        },
+      },
+    } as ExtensionDefinition;
+  });