buro26-strapi-graphql 0.0.19 → 0.0.21

package/README.md

@@ -35,9 +35,329 @@ 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:
+
+- init: Called when the extension is initialized
+- getTypes: Returns an array of GraphQL types
+- resolvers: Returns an object with resolvers
+- getResolverConfig: 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, stringArg, nonNull } 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']);
+  },
+
+  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
+        }
+      }
+    };
+  },
+
+  resolverConfig() {
+    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;
+            }
+          });
+        }
+      })
+
+    ];
+  }
+}));
+```
+
+### 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/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

@@ -19,11 +19,19 @@ exports.default = async ({ strapi }) => {
     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.resolverConfig) === null || _o === void 0 ? void 0 : _o.call(extension)) !== null && _p !== void 0 ? _p : {},
+                },
             });
         });
     }

package/dist/server/services/file-service.d.ts

@@ -1,5 +1,5 @@
-import { type Strapi } from '@strapi/strapi';
-import { GraphQLExtension } from '../types';
+import type { Strapi } from '@strapi/strapi';
+import type { GraphQLExtension } from '../types';
 declare const _default: ({ strapi }: {
     strapi: Strapi;
 }) => {

package/dist/server/services/file-service.js

@@ -44,7 +44,9 @@ exports.default = ({ strapi }) => ({
                 // Recursively get files from the directory
                 return this.getAllFilesInGraphQlDirectory(filePath, collectedExtensions);
             }
-            if (!directoryPath.endsWith('/graphql') && !directoryPath.includes('/graphql/')) {
+            const folderName = 'graphql';
+            if (!directoryPath.endsWith(path.sep + folderName) &&
+                !directoryPath.includes(path.sep + folderName + path.sep)) {
                 return;
             }
             const graphqlModule = require(filePath.replace('.js', ''));

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 resolverConfig() 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;
+    resolverConfig?: () => 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,5 @@
 export * from './types';
 export * from './single-type';
 export * from './collection-type';
+export * from './misc';
 export * from './override';

package/dist/server/utils/index.js

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

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

@@ -0,0 +1,4 @@
+export declare function transformArgs(args: Record<string, any>, { contentType, usePagination }: {
+    contentType: string;
+    usePagination?: boolean;
+}): Record<string, any>;

package/dist/server/utils/misc.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformArgs = void 0;
+function transformArgs(args, { contentType, usePagination }) {
+    const { transformArgs } = strapi.plugin('graphql').service('builders').utils;
+    return transformArgs(args, {
+        contentType,
+        usePagination: usePagination !== null && usePagination !== void 0 ? usePagination : true
+    });
+}
+exports.transformArgs = transformArgs;

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

@@ -1,5 +1,5 @@
 /**
- * Easily resolve a entity
+ * Easily resolve an entity
  *
  * Based on node_modules/@strapi/plugin-graphql/server/services/builders/type.js
  */
@@ -9,5 +9,16 @@ type ResolveEntityArgs = Omit<ResolveArgs, 'args'> & {
         id: string;
     };
 };
-export declare const resolveEntity: <T extends Object>(contentType: string, resolveArgs: ResolveEntityArgs) => Promise<Entity<T>>;
+export declare function resolveEntity<T extends Object>(contentType: string, resolveArgs: ResolveEntityArgs): Promise<Entity<T> | null>;
+type EntityResponse<T extends Object> = {
+    value: Entity<T> | null;
+    info: {
+        args: Record<string, any>;
+        resourceUID: string;
+    };
+};
+export declare function toEntityResponse<T extends Object>(item: T | null, { args, resourceUID }: {
+    args: Record<string, any>;
+    resourceUID: string;
+}): Promise<EntityResponse<T> | null>;
 export {};

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

@@ -1,12 +1,12 @@
 "use strict";
 /**
- * Easily resolve a entity
+ * Easily resolve an entity
  *
  * Based on node_modules/@strapi/plugin-graphql/server/services/builders/type.js
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEntity = void 0;
-const resolveEntity = async (contentType, resolveArgs) => {
+exports.toEntityResponse = exports.resolveEntity = void 0;
+async function resolveEntity(contentType, resolveArgs) {
     const { transformArgs } = strapi.plugin('graphql').service('builders').utils;
     const { toEntityResponse } = strapi.plugin('graphql').service('format').returnTypes;
     const { buildQueriesResolvers } = strapi.plugin('graphql').service('builders').get('content-api');
@@ -15,7 +15,15 @@ const resolveEntity = async (contentType, resolveArgs) => {
     const item = await findOne(resolveArgs.parent, transformedArgs, resolveArgs.context);
     return toEntityResponse(item, {
         args: resolveArgs.args,
-        resourceUID: contentType,
+        resourceUID: contentType
     });
-};
+}
 exports.resolveEntity = resolveEntity;
+async function toEntityResponse(item, { args, resourceUID }) {
+    const { toEntityResponse } = strapi.plugin('graphql').service('format').returnTypes;
+    return toEntityResponse(item, {
+        args,
+        resourceUID
+    });
+}
+exports.toEntityResponse = toEntityResponse;