buro26-strapi-graphql 0.0.20 → 0.0.22

package/README.md

@@ -35,9 +35,403 @@ export default () => ({
 
 ### Create a new GraphQL Extension
 
+To create a new GraphQL extension, create a folder named `graphql` in the content-type directory or within the
+extensions folder (in case of extending a plugin).
+Inside the `graphql` folder you can create files with any name. This plugin will scan the `graphql` folder register your
+extensions with Strapi.
+
+From each file create a default export that uses th `createGraphQLExtension` factory function. This function takes a
+function as an argument that will receive the Strapi instance and should return an object with the following methods:
+
+| Method          | Description                                      |
+|-----------------|--------------------------------------------------|
+| init            | Called when the extension is initialized         |
+| types           | Returns an array of GraphQL types                |
+| typeDefs        | Returns a string with the type definition in SDL |
+| resolvers       | Returns an object with resolvers                 |
+| resolversConfig | Returns an object with resolver configuration    |
+
+The functions you can implement follow the pattern of the Strapi customization
+options: https://docs.strapi.io/dev-docs/plugins/graphql#customization. The return values here will be registered as-is
+with Strapi in the register hook.
+
+```typescript
+import { createGraphQLExtension } from 'buro26-strapi-graphql';
+import { extendType, nonNull, stringArg } from 'nexus';
+
+export default createGraphQLExtension(strapi => ({
+
+  init() {
+    // e.g. disable actions
+    strapi
+      .plugin('graphql')
+      .service('extension')
+      .shadowCRUD('api::my-type.my-type')
+      .disableActions(['find', 'findOne', 'create', 'update', 'delete']);
+  },
+
+  typeDefs() {
+    return `
+      type HelloWorldResponse {
+        greeting: String!
+      }
+    `;
+  },
+
+  types() {
+    return [
+      // Extend an existing type
+      extendType({
+        type: 'MyType',
+        definition(t) {
+          t.field('foo', {
+            type: 'Boolean',
+            resolve: async (root) => {
+              return false;
+            }
+          });
+          t.field('bar', {
+            type: 'Boolean',
+            resolve: async (root) => {
+              return false;
+            }
+          });
+        }
+      }),
+
+      // Create a new query
+      extendType({
+        type: 'Query',
+        definition(t) {
+          t.field('helloWorld', {
+            type: 'HelloWorldResponse',
+            args: {
+              greeting: nonNull(stringArg())
+            },
+            // either resolve here or add it in resolvers method
+            resolve: async (root, args) => {
+              // resolve logic
+            }
+          });
+        }
+      })
+    ];
+  },
+
+  resolvers() {
+    return {
+      Query: {
+        // Override an existing query
+        helloWorld: async (root, args) => {
+          // resolve logic
+        }
+      },
+      Mutation: {
+        // Override an existing mutation
+        updateMyType: async (root, args) => {
+          // resolve logic
+        }
+      }
+    };
+  },
+
+  resolversConfig() {
+    return {
+      'Query.helloWorld': {
+        policies: [
+          async ({ state, args }, { strapi }) => {
+            // Validate request
+          }
+        ],
+        middlewares: [
+          async (next, root, args, context, info) => {
+            // Do something here
+
+            return next(root, args, context, info);
+          }
+        ]
+      }
+    };
+  }
+}));
+```
+
 ### Overriding a field
 
-### Add authorization to a field
+Sometimes you will need to override a field in an existing type. You can do this by extending the type and adding the
+field again. The field will be overridden with the new field definition. To make this easier we added a helper function
+`overrideField` that will make this easier. The helper method also automatically generates a resolver for the field.
+
+The overrideField function needs the content type and fieldName to be able to resolve the field type and the resolver.
+The authorize function is optional and can be used to authorize the field. The resolve function is also optional and can
+be used to resolve the field.
+
+```typescript
+import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
+import { extendType } from 'nexus';
+
+export default createGraphQLExtension(strapi => ({
+  types() {
+    return [
+      // Extend an existing type
+      extendType({
+        type: 'MyType',
+        definition(t) {
+          overrideField<MyContentType>(t, {
+            contentTypeName: 'api::my-type.my-type',
+            fieldName: 'myField',
+            description: 'My field description',
+            authorize: async (root, args, context) => {
+              // Authorization logic
+              return true;
+            },
+            resolve: async (root) => {
+              // Resolver is optional
+              return false;
+            }
+          });
+        }
+      })
+
+    ];
+  }
+}));
+```
+
+### Add authorization to an existing field
+
+By default Strapi GraphQL does not support field level authorization. This plugin adds support for field level
+authorization. You can add authorization to an existing field by using the before mentioned `overrideField` function.
+The authorize function will be called before the field is resolved. If the authorize function returns false the field
+will not be resolved and an error will be thrown.
+
+If you decide not to pass the resolve function and only the authorize function, the field will be resolved by the
+default resolver generated by the plugin.
+
+```typescript
+import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
+import { extendType } from 'nexus';
+
+export default createGraphQLExtension(strapi => ({
+  types() {
+    return [
+      // Extend an existing type
+      extendType({
+        type: 'MyType',
+        definition(t) {
+          overrideField<MyContentType>(t, {
+            contentTypeName: 'api::my-type.my-type',
+            fieldName: 'myField',
+            authorize: async (root, args, context) => {
+              // Decide if the user is authorized to access the field
+              return true;
+            }
+          });
+        }
+      })
+
+    ];
+  }
+}));
+```
+
+### Field middleware
+
+You can add middleware to a specific field, similarly to adding authorization. Each field can have multiple middlewares.
+
+This can be useful when you want to add some logic before or after the field is resolved. E.g. logging, caching,
+response parsing, etc.
+
+```typescript
+import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
+import { extendType } from 'nexus';
+
+export default createGraphQLExtension(strapi => ({
+  types() {
+    return [
+      // Extend an existing type
+      extendType({
+        type: 'MyType',
+        definition(t) {
+          t.field('myField', {
+            type: 'MyFieldType',
+            extensions: {
+              middlewares: [
+                next => async (root, args, context, info) => {
+                  // Do something before the field is resolved
+
+                  const res = next(root, args, context, info);
+
+                  // Do something after the field is resolved
+
+                  return res;
+                }
+              ]
+            },
+            resolve: async (root) => {
+              // Resolver is optional
+            }
+          })
+          overrideField<MyContentType>(t, {
+            contentTypeName: 'api::my-type.my-type',
+            fieldName: 'myField',
+            extensions: {
+              middlewares: [
+                next => async (root, args, context, info) => {
+                  // Do something before the field is resolved
+
+                  const res = next(root, args, context, info);
+
+                  // Do something after the field is resolved
+
+                  return res;
+                }
+              ]
+            }
+          });
+        }
+      })
+
+    ];
+  }
+}));
+```
+
+### Utility functions
+
+The plugin also provides utility functions to help you resolve entities and collections. These functions are useful when
+you need to resolve entities and collections in your resolvers.
+
+#### resolveEntity
+
+The `resolveEntity` function can be used to resolve an entity by id. The function takes the content type name and an
+object with all the resolve args passed the resolver function. The function will return the resolved entity as
+EntityResponse.
+
+```typescript
+import { createGraphQLExtension, overrideField, resolveEntity } from 'buro26-strapi-graphql';
+import { extendType } from 'nexus';
+
+export default createGraphQLExtension(strapi => ({
+  types() {
+    return [
+      // Extend an existing type
+      extendType({
+        type: 'MyType',
+        definition(t) {
+          t.field('myFields', {
+            type: 'MyFieldEntityResponse',
+            resolve: async (parent, args, context, info) => {
+              // Do something, and resolve the entit
+              return resolveEntity<MyContentType>('api::my-content-type.my-content-type', {
+                args: {
+                  id: 'the id here',
+                },
+                parent,
+                context,
+                info,
+              })
+            }
+          });
+          overrideField<MyContentType>(t, {
+            contentTypeName: 'api::my-type.my-type',
+            fieldName: 'myOtherField',
+            resolve: async (parent, args, context, info) => {
+              // Do something, and resolve the entit
+              return resolveEntity<MyContentType>('api::my-content-type.my-content-type', {
+                args: {
+                  id: 'the id here',
+                },
+                parent,
+                context,
+                info,
+              })
+            }
+          });
+        }
+      })
+
+    ];
+  }
+}));
+```
+
+#### resolveEntityCollection
+
+The `resolveEntityCollection` function can be used to resolve a collection of entities. The function takes the content
+type name and an object with all the resolve args passed the resolver function. The function will return the resolved
+collection as EntityCollectionResponse.
+
+```typescript
+import { createGraphQLExtension, overrideField, resolveEntityCollection } from 'buro26-strapi-graphql';
+import { extendType } from 'nexus';
+
+export default createGraphQLExtension(strapi => ({
+  types() {
+    return [
+      // Extend an existing type
+      extendType({
+        type: 'MyType',
+        definition(t) {
+          t.field('myFields', {
+            type: 'MyFieldEntityResponseCollection',
+            resolve: async (parent, args, context, info) => {
+              // Do something, and resolve the entit
+              return resolveEntityCollection<MyContentType>('api::my-content-type.my-content-type', {
+                args,
+                parent,
+                context,
+                info,
+              })
+            }
+          });
+          overrideField<MyContentType>(t, {
+            contentTypeName: 'api::my-type.my-type',
+            fieldName: 'myOtherField',
+            resolve: async (parent, args, context, info) => {
+              // Do something, and resolve the entit
+              return resolveEntityCollection<MyContentType>('api::my-content-type.my-content-type', {
+                args,
+                parent,
+                context,
+                info,
+              })
+            }
+          });
+        }
+      })
+
+    ];
+  }
+}));
+```
+
+#### resolveEntityRelationCollection
+
+This function has the same API as `resolveEntityCollection` but is used to resolve a collection of entities from a
+relational field on the provided content type.
+
+#### toEntityResponse
+
+This function is a typesafe response builder for a single entity. It takes the entity and the content type name and will
+return an EntityResponse.
+
+This function is re-exported from the Strapi GraphQL plugin.
+
+#### toEntityCollectionResponse
+
+This function is a typesafe response builder for a collection of entities. It takes the entities and the content type
+name and will return an EntityCollectionResponse.
+
+This function is re-exported from the Strapi GraphQL plugin.
+
+#### resolveArgs
+
+This function is a typesafe utility function to resolve the args passed to the resolver function. It will transform the
+graphql
+args into args that can be passed to the entityManager.
+
+This function is re-exported from the Strapi GraphQL plugin.
 
 ## Test and Deploy
 

package/dist/server/index.d.ts

@@ -1,5 +1,8 @@
-import { type Strapi } from '@strapi/strapi';
-import { type GraphQLExtension } from './types';
+import type { Strapi } from '@strapi/strapi';
+import type { GraphQLExtension } from './types';
+import type { Middleware, ResolveContext } from './utils';
+import type { GraphQLResolveInfo } from 'graphql';
+import type { GraphQLFieldConfig } from 'graphql/type';
 declare const _default: {
     register: ({ strapi }: {
         strapi: Strapi;
@@ -43,3 +46,31 @@ declare module '@strapi/strapi' {
         createGraphQLExtension: (factory: (strapi: Strapi) => GraphQLExtension) => GraphQLExtension;
     }
 }
+/**
+ * Extend Nexus's field definition to include a middleware array.
+ */
+declare module 'nexus/dist/core' {
+    /**
+     * Extends Nexus's OutputFieldConfig to include a `middleware` property.
+     */
+    interface NexusOutputFieldConfig<TypeName extends string, FieldName extends string> {
+        extensions?: {
+            middlewares?: Middleware[];
+        } & GraphQLFieldConfig<any, any>['extensions'];
+        /**
+         * A function that determines if the current user is authorized to access this field.
+         *
+         * @param parent The parent object.
+         * @param args The arguments passed to the field.
+         * @param context The context object.
+         * @param info The GraphQLResolveInfo object.
+         */
+        authorize?: <Parent extends Object, Args extends Object, Context = ResolveContext>(parent: Parent, args: Args, context: Context, info: GraphQLResolveInfo) => boolean | Promise<boolean>;
+    }
+    interface GraphQLFieldExtensions<_TSource, _TContext, _TArgs> {
+        /**
+         * An array of middleware functions to apply to this field.
+         */
+        middleware?: Middleware[];
+    }
+}

package/dist/server/register.d.ts

@@ -1,4 +1,4 @@
-import { type Strapi } from '@strapi/strapi';
+import type { Strapi } from '@strapi/strapi';
 declare const _default: ({ strapi }: {
     strapi: Strapi;
 }) => Promise<void>;

package/dist/server/register.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const nexus_1 = require("nexus");
+const utils_1 = require("./utils");
 exports.default = async ({ strapi }) => {
     const fileService = strapi
         .plugin('burotwosix-graphql-plugin')
@@ -13,17 +14,26 @@ exports.default = async ({ strapi }) => {
     ];
     graphQlExtensionService.use(() => ({
         plugins: [
-            (0, nexus_1.fieldAuthorizePlugin)()
+            (0, nexus_1.fieldAuthorizePlugin)(),
+            (0, utils_1.nexusMiddlewarePlugin)(),
         ]
     }));
     for (const extension of extensions) {
         (extension === null || extension === void 0 ? void 0 : extension.init) && extension.init();
         graphQlExtensionService.use(() => {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
             return ({
-                types: (_b = (_a = extension === null || extension === void 0 ? void 0 : extension.getTypes) === null || _a === void 0 ? void 0 : _a.call(extension)) !== null && _b !== void 0 ? _b : [],
-                resolvers: (_d = (_c = extension === null || extension === void 0 ? void 0 : extension.resolvers) === null || _c === void 0 ? void 0 : _c.call(extension)) !== null && _d !== void 0 ? _d : { Query: {}, Mutation: {} },
-                resolversConfig: (_f = (_e = extension === null || extension === void 0 ? void 0 : extension.getResolverConfig) === null || _e === void 0 ? void 0 : _e.call(extension)) !== null && _f !== void 0 ? _f : {}
+                typeDefs: (_b = (_a = extension === null || extension === void 0 ? void 0 : extension.typeDefs) === null || _a === void 0 ? void 0 : _a.call(extension)) !== null && _b !== void 0 ? _b : '',
+                types: [
+                    ...((_d = (_c = extension === null || extension === void 0 ? void 0 : extension.getTypes) === null || _c === void 0 ? void 0 : _c.call(extension)) !== null && _d !== void 0 ? _d : []),
+                    ...((_f = (_e = extension === null || extension === void 0 ? void 0 : extension.types) === null || _e === void 0 ? void 0 : _e.call(extension)) !== null && _f !== void 0 ? _f : []),
+                ],
+                plugins: (_h = (_g = extension === null || extension === void 0 ? void 0 : extension.plugins) === null || _g === void 0 ? void 0 : _g.call(extension)) !== null && _h !== void 0 ? _h : [],
+                resolvers: (_k = (_j = extension === null || extension === void 0 ? void 0 : extension.resolvers) === null || _j === void 0 ? void 0 : _j.call(extension)) !== null && _k !== void 0 ? _k : { Query: {}, Mutation: {} },
+                resolversConfig: {
+                    ...(_m = (_l = extension === null || extension === void 0 ? void 0 : extension.getResolverConfig) === null || _l === void 0 ? void 0 : _l.call(extension)) !== null && _m !== void 0 ? _m : {},
+                    ...(_p = (_o = extension === null || extension === void 0 ? void 0 : extension.resolversConfig) === null || _o === void 0 ? void 0 : _o.call(extension)) !== null && _p !== void 0 ? _p : {},
+                },
             });
         });
     }

package/dist/server/types.d.ts

@@ -1,3 +1,6 @@
+import type { ResolveContext } from './utils';
+import type { GraphQLResolveInfo } from 'graphql';
+import type { Strapi } from '@strapi/strapi';
 export interface GraphQLExtension {
     /**
      * Called when the extension is initialized, use this to perform any initialization logic
@@ -5,23 +8,69 @@ export interface GraphQLExtension {
      * @see https://docs.strapi.io/developer-docs/latest/plugins/graphql.html#disabling-operations-in-the-shadow-crud
      */
     init?: () => void;
+    /**
+     * Return the type definitions for the extension as GraphQL SDL
+     */
+    typeDefs?: () => string;
     /**
      * Return array the types for the extension
      * Use Nexus to define types
+     *
+     * @deprecated Use types() instead
      */
-    getTypes: () => any[];
+    getTypes?: () => any[];
+    /**
+     * Return array the types for the extension
+     * Use Nexus to define types
+     */
+    types?: () => any[];
+    /**
+     * Return optional array of nexus plugins
+     *
+     * @see https://nexusjs.org/docs/plugins
+     */
+    plugins?: () => any[];
     /**
      * Return resolvers for the extension
      * Return an object with Query and Mutation resolvers
      */
-    resolvers: () => {
-        Query: any;
-        Mutation: any;
+    resolvers?: () => {
+        Query?: Record<string, ResolverFunction>;
+        Mutation?: Record<string, ResolverFunction>;
     };
+    /**
+     * Return resolver config for the extension
+     * This is used to configure middlewares and other resolver options
+     * @see https://docs.strapi.io/developer-docs/latest/plugins/graphql.html#extending-the-schema
+     *
+     * @deprecated Use resolversConfig() instead
+     */
+    getResolverConfig?: () => any;
     /**
      * Return resolver config for the extension
      * This is used to configure middlewares and other resolver options
      * @see https://docs.strapi.io/developer-docs/latest/plugins/graphql.html#extending-the-schema
      */
-    getResolverConfig: () => any;
+    resolversConfig?: () => Record<string, ResolverConfigOption>;
 }
+type ResolverConfigOption = {
+    auth?: boolean | undefined;
+    policies?: string[] | PolicyFunction[];
+    middlewares?: MiddlewareFunction[];
+};
+type PolicyFunctionContext = {
+    parent: any;
+    args: any;
+    context: ResolveContext;
+    info: GraphQLResolveInfo;
+    state: ResolveContext['state'];
+    http: any;
+};
+type PolicyFunctionOptions = {
+    strapi: Strapi;
+};
+type PolicyFunction = (context: PolicyFunctionContext, config: any, opts: PolicyFunctionOptions) => boolean | Promise<boolean>;
+type MiddlewareFunction = (next: MiddlewareNextFunction, parent: any, args: any, context: ResolveContext, info: GraphQLResolveInfo) => any | Promise<any>;
+type MiddlewareNextFunction = (parent: any, args: any, context: ResolveContext, info: GraphQLResolveInfo) => Promise<any>;
+type ResolverFunction = (parent: any, args: any, context: ResolveContext, info: GraphQLResolveInfo) => any | Promise<any>;
+export {};

package/dist/server/utils/collection-type.d.ts

@@ -6,3 +6,15 @@
 import { Entity, type ResolveArgs } from './types';
 export declare const resolveEntityCollection: <T extends Object>(contentType: string, resolveArgs: ResolveArgs) => Promise<Entity<T>[]>;
 export declare const resolveEntityRelationCollection: <T extends Object>(contentType: string, relationFieldName: keyof T, resolveArgs: ResolveArgs) => Promise<Entity<T>[]>;
+type EntityResponse<T extends Object> = {
+    value: Entity<T> | null;
+    info: {
+        args: Record<string, any>;
+        resourceUID: string;
+    };
+};
+export default function toEntityResponseCollection<T extends Object>(items: T[], { args, resourceUID }: {
+    args: Record<string, any>;
+    resourceUID: string;
+}): EntityResponse<T>[];
+export {};

package/dist/server/utils/collection-type.js

@@ -33,3 +33,11 @@ const resolveEntityRelationCollection = async (contentType, relationFieldName, r
     return find(resolveArgs.parent, resolveArgs.args, resolveArgs.context);
 };
 exports.resolveEntityRelationCollection = resolveEntityRelationCollection;
+function toEntityResponseCollection(items, { args, resourceUID }) {
+    const { toEntityResponseCollection } = strapi.plugin('graphql').service('format').returnTypes;
+    return toEntityResponseCollection(items, {
+        args,
+        resourceUID
+    });
+}
+exports.default = toEntityResponseCollection;

package/dist/server/utils/index.d.ts

@@ -1,4 +1,6 @@
 export * from './types';
 export * from './single-type';
 export * from './collection-type';
+export * from './middleware';
+export * from './misc';
 export * from './override';

package/dist/server/utils/index.js

@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./single-type"), exports);
 __exportStar(require("./collection-type"), exports);
+__exportStar(require("./middleware"), exports);
+__exportStar(require("./misc"), exports);
 __exportStar(require("./override"), exports);

package/dist/server/utils/middleware.d.ts

@@ -0,0 +1,17 @@
+import 'nexus';
+import { GraphQLResolveInfo } from 'graphql';
+import { ResolveContext } from './types';
+/**
+ * The Resolver type represents a GraphQL resolver function.
+ */
+export type Resolver = <Parent extends Object, Args extends Object, Context = ResolveContext>(parent: Parent, args: Args, context: Context, info: GraphQLResolveInfo) => any | Promise<any>;
+/**
+ * Middleware is a function that takes a resolver and returns a new resolver.
+ */
+export type Middleware = (resolver: Resolver) => Resolver;
+export declare const nexusMiddlewarePlugin: () => import("nexus/dist/plugin").NexusPlugin;
+/**
+ * Logging Middleware
+ * Logs the execution of the resolver.
+ */
+export declare const loggingMiddleware: Middleware;