buro26-strapi-graphql 0.0.26 → 0.1.0

package/README.md

@@ -1,589 +1,496 @@
 # Strapi GraphQL Extension
 
-Extension and utilities for Strapi GraphQL API. This plugin adds additional features to the Strapi GraphQL plugin such
-as co-location of GraphQL schema and resolvers, field overriding, and field authorization.
+**Buro26’s Strapi GraphQL Extension** supercharges your Strapi GraphQL API with:
 
-This let's you define your GraphQL schema and resolvers in the content-type directory, making it easier to manage and
-maintain your GraphQL API.
+- Field-level authorization and middleware
+- Co-location of schema and resolvers
+- Fluent, type-safe builder APIs
+- Powerful testing, validation, and tracing utilities
 
-This plugin is compatible with both Strapi v4 and Strapi v5.
+> **Supports Strapi v4 and v5**
 
-## Getting started
+---
+
+## 🚀 Getting Started
 
 ```bash
 npm i buro26-strapi-graphql
 ```
 
-## Usage
-
-### Configure Strapi GraphQL plugin
+---
 
-To be able to use this plugin, you will first need to configure
-the [Strapi GraphQL plugin](https://docs.strapi.io/dev-docs/plugins/graphql).
+## 🏗️ Recommended: The Field Builder Pattern
 
-### Enable plugin
+The **recommended way** to build GraphQL fields is with `createGraphQLFieldBuilder()`.  
+This fluent, type-safe builder gives you the best DX, composability, and testability.
 
-Add plugin in `./config/plugins.[js/ts]` in your Strapi project.
+### **Example: A Custom Query Field**
 
 ```typescript
-export default () => ({
-  // ...
-  'burotwosix-graphql-plugin': {
-    enabled: true
-  }
-  // ...
-})
+import { createGraphQLFieldBuilder } from 'buro26-strapi-graphql';
+import { nonNull, stringArg } from 'nexus';
+
+export default createGraphQLFieldBuilder('Query')
+  .fieldName('helloWorld')
+  .args({ name: nonNull(stringArg()) })
+  .outputType(nonNull('String'))
+  .description('Returns a personalized greeting')
+  .resolver(async (parent, args) => `Hello World ${args.name}`)
+  .resolverConfig({ auth: false });
 ```
 
-### 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.
+### **Why use the Field Builder?**
 
-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:
+- **Chainable, immutable API** for safe, readable code
+- **Type-safe context and args** for resolvers, middleware, and auth
+- **Built-in support for:**
+  - Middleware and authorization (local and global)
+  - Argument validation (Zod)
+  - Tracing/profiling
+  - Deprecation and description
+  - Field hooks (before/after resolve)
+  - Testing in isolation
+  - Batch/group registration
+  - Composable presets (`.use()`)
 
-| 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.
+### **Composable Presets**
 
-```typescript
-import { createGraphQLExtension } from 'buro26-strapi-graphql';
-import { extendType, nonNull, stringArg } from 'nexus';
+Create reusable sets of middleware/auth logic and apply them to any field:
 
-export default createGraphQLExtension(strapi => ({
+```typescript
+const adminPreset = createGraphQLFieldPreset(builder =>
+  builder
+    .middleware(requireAdmin)
+    .authorize(adminAuth)
+);
 
-  init() {
-    // e.g. disable actions
-    strapi
-      .plugin('graphql')
-      .service('extension')
-      .shadowCRUD('api::my-type.my-type')
-      .disableActions(['find', 'findOne', 'create', 'update', 'delete']);
-  },
+export default createGraphQLFieldBuilder('Query')
+  .use(adminPreset)
+  .fieldName('adminHello')
+  .outputType('String')
+  .resolver(() => 'Hello, admin!');
+```
 
-  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;
-            }
-          });
-        }
-      }),
+## 🔒 Field-Level Authorization and Middleware
 
-      // 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
-            }
-          });
-        }
-      })
-    ];
-  },
+Every field defined with `createGraphQLFieldBuilder()` or via Nexus’s `t.field` can use the `extensions` property to
+attach **authorization** and **middleware** 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
-        }
-      }
-    };
-  },
+### **Field-Level Authorization**
 
-  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);
-          }
-        ]
-      }
-    };
-  }
-}));
-```
+- Use the `authorize` field in `extensions` to add per-field authorization logic.
+- The function should return `true` (allow), `false` (deny), or throw an error.
 
-### Fluent Builder Pattern
-The plugin also supports a builder pattern so that you can configure your extension using a fluent API. This is achieved by calling createGraphQLExtension() with no arguments. For example, you can write:
+**Example:**
 
 ```typescript
-export default createGraphQLExtension()
-  .init(() => {
-    // Initialization logic here...
-  })
-  .typeDefs(`
-    extend type Query {
-      hello: String
+t.field('myField', {
+  type: 'String',
+  extensions: {
+    authorize: async (parent, args, ctx, info) => {
+      // Only allow admins
+      return ctx.state.user?.role === 'admin';
     }
-  `)
-  .resolvers({
-    Query: {
-      hello: () => 'Hello from builder!'
-    }
-  });
+  },
+  resolve: () => 'Secret data'
+});
 ```
 
-In this pattern, `createGraphQLExtension()` detects that no argument was passed and returns a builder. The builder exposes methods like `.init()`, `.typeDefs()`, `.types()`, `.plugins()`, `.resolvers()`, and `.resolversConfig()` so you can chain calls and define your extension inline.
+> **Note:**  
+> If you use the builder, `.authorize()` will automatically set this property for you.
 
-### Shorter way to define a new field
+---
 
-The `createGraphQLFieldBuilder()` function provides a fluent builder API to create a single GraphQL field extension using Nexus. It simplifies the process of extending the GraphQL schema by letting you define the field's name, arguments, output type, resolver, and resolver configuration in a chainable way.
+### **Field-Level Middleware**
 
-The builder pattern ensures that you only need to specify the necessary parts, and the extension is automatically registered using the provided settings. This approach minimizes boilerplate code while ensuring consistency across your GraphQL extensions.
+- Use the `middlewares` field in `extensions` to add one or more middleware functions to a field.
+- Middleware functions wrap the resolver and can perform logic before/after, modify args, or short-circuit the resolver.
 
-Below is an example of how to define a new field using the builder pattern. This example creates a new query field called `helloWorld` that takes a non-null `name` argument and returns a non-null `String`.
+**Example:**
 
 ```typescript
-import { createGraphQLFieldBuilder } from "buro26-strapi-graphql";
-import { nonNull, stringArg } from 'nexus';
-
-export default createGraphQLFieldBuilder('Query')
-  .fieldName('helloWorld')
-  .args({
-    name: nonNull(stringArg()),
-  })
-  .outputType(nonNull('String'))
-  .resolver(async (parent, args, ctx) => {
-    return `Hello World ${args.name}`;
-  })
-  .resolverConfig({
-    auth: false,
-  });
+t.field('myField', {
+  type: 'String',
+  extensions: {
+    middlewares: [
+      next => async (root, args, ctx, info) => {
+        console.log('Before');
+        const result = await next(root, args, ctx, info);
+        console.log('After');
+        return result;
+      }
+    ]
+  },
+  resolve: () => 'With middleware'
+});
 ```
 
-### Overriding a field
+> **Note:**  
+> If you use the builder, `.middleware()` will automatically set this property for you.
 
-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.
+## 🌍 Global Middleware and Authorization
 
-```typescript
-import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+You can register **global middleware** and **global authorization** that apply to multiple fields based on type, field
+name, or tags.
 
-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;
-            }
-          });
-        }
-      })
+**Important:**
+> **Global middleware and authorization must be registered _before_ any fields that consume them are built or
+registered.**  
+> This ensures that all relevant fields will pick up the global logic.
 
-    ];
+**Example:**
+
+```typescript
+import { registerGlobalMiddleware, registerGlobalAuthorize } from 'buro26-strapi-graphql';
+
+// Register global middleware for all admin-tagged Query fields
+registerGlobalMiddleware(
+  ({ type, tags }) => type === 'Query' && tags.includes('admin'),
+  next => async (root, args, ctx, info) => {
+    // ...admin logic...
+    return next(root, args, ctx, info);
   }
-}));
+);
+
+// Register global authorization for a specific field
+registerGlobalAuthorize(
+  ({ fieldName }) => fieldName === 'deleteUser',
+  async (parent, args, ctx) => ctx.state.user?.isAdmin
+);
+
+// Now define fields that will use these global middlewares/authorizations
+export default createGraphQLFieldBuilder('Query')
+  .fieldName('deleteUser')
+  .outputType('Boolean')
+  .tag('admin')
+  .resolver(() => true);
 ```
 
-### Add authorization to an existing field
+**Best Practice:**
+
+- Always register global middleware and authorization at the top of your entry file (before any field or extension
+  exports).
+- This guarantees that all fields will be able to consume the global logic.
+
+---
+
+## 📝 Best Practices
+
+- Use the **builder’s `.authorize()` and `.middleware()`** methods for most use-cases—they automatically set the correct
+  `extensions` properties.
+- Use the `extensions` property directly for advanced or manual Nexus usage.
+- Register **global middleware and authorization before** any fields that should use them.
+- Use **tags** to target groups of fields for global logic.
 
-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.
+### **Validation, Tracing, and Testing**
+
+**Argument validation with Zod:**
 
 ```typescript
-import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+import { z } from 'zod';
 
-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;
-            }
-          });
-        }
-      })
+const nameSchema = z.object({ name: z.string().min(1) });
 
-    ];
-  }
-}));
+export default createGraphQLFieldBuilder('Query')
+  .fieldName('hello')
+  .args({ name: 'String!' })
+  .outputType('String')
+  .validateArgs(nameSchema)
+  .resolver((parent, args) => `Hello, ${args.name}!`);
 ```
 
-### Field middleware
+**Tracing/profiling:**
 
-You can add middleware to a specific field, similarly to adding authorization. Each field can have multiple middlewares.
+```typescript
+export default createGraphQLFieldBuilder('Query')
+  .fieldName('profiledHello')
+  .outputType('String')
+  .trace() // Pretty console log by default
+  .resolver(async () => {
+    await new Promise(r => setTimeout(r, 100));
+    return 'Hello, profiled!';
+  });
+```
 
-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.
+**Testing in isolation:**
 
 ```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 field = createGraphQLFieldBuilder('Query')
+  .fieldName('hello')
+  .outputType('String')
+  .resolver((parent, args, ctx) => `Hello, ${args.name}!`);
+
+const result = await field.test({
+  args: { name: 'Henri' },
+  context: { user: { id: '123' } }
+});
+console.log(result); // "Hello, Henri!"
+```
 
-                  const res = await next(root, args, context, info);
+---
 
-                  // Do something after the field is resolved
+### **Batch Registration and Field Groups**
 
-                  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
+**Register multiple fields at once:**
 
-                  const res = await next(root, args, context, info);
+```typescript
+import { createGraphQLFieldBuilder, registerFields } from 'buro26-strapi-graphql';
 
-                  // Do something after the field is resolved
+const fieldA = createGraphQLFieldBuilder('Query')
+  .fieldName('foo')
+  .outputType('String')
+  .resolver(() => 'Foo');
 
-                  return res;
-                }
-              ]
-            }
-          });
-        }
-      })
+const fieldB = createGraphQLFieldBuilder('Query')
+  .fieldName('bar')
+  .outputType('String')
+  .resolver(() => 'Bar');
 
-    ];
-  }
-}));
+export default registerFields(fieldA, fieldB);
 ```
 
-### Utility functions
+**Apply shared logic to a group:**
 
-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.
+```typescript
+import { createFieldGroup } from 'buro26-strapi-graphql';
+
+const requireUser = builder =>
+  builder.middleware(next => async (root, args, ctx, info) => {
+    if (!ctx.user) throw new Error('Not authenticated');
+    return next(root, args, ctx, info);
+  });
+
+export default createFieldGroup([fieldA, fieldB], requireUser);
+```
+
+---
 
-#### resolveEntity
+## 🛠️ Advanced: The Extension Builder
 
-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.
+For advanced use-cases, you can use `createGraphQLExtension()` to build a full extension with custom types, resolvers,
+plugins, and more.
 
 ```typescript
-import { createGraphQLExtension, overrideField, resolveEntity } from 'buro26-strapi-graphql';
+import { createGraphQLExtension } 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,
-              })
-            }
-          });
-        }
-      })
-
-    ];
-  }
-}));
+export default createGraphQLExtension()
+  .typeDefs(`
+    type HelloWorldResponse {
+      greeting: String!
+    }
+  `)
+  .types([
+    extendType({
+      type: 'Query',
+      definition(t) {
+        t.field('helloWorld', {
+          type: 'HelloWorldResponse',
+          resolve: () => ({ greeting: 'Hello, world!' })
+        });
+      }
+    })
+  ])
+  .resolvers({
+    Query: {
+      helloWorld: () => ({ greeting: 'Hello, world!' })
+    }
+  });
 ```
 
-#### resolveEntityRelation
+> **Note:**  
+> For most use-cases, prefer the field builder.  
+> Use the extension builder for advanced scenarios (custom plugins, full type overrides, etc).
+
+---
 
-The `resolveEntityRelation` 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.
+## 🧩 Overriding and Extending Fields
+
+You can override or extend fields in existing types using the `overrideField` helper:
 
 ```typescript
-import { createGraphQLExtension, overrideField, resolveEntityRelation } from 'buro26-strapi-graphql';
+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('myFields', {
-            type: 'MyFieldEntityResponse',
-            resolve: async (parent, args, context, info) => {
-              // Do something, and resolve the entit
-              return resolveEntityRelation<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 resolveEntityRelation<MyContentType>('api::my-content-type.my-content-type', 'myRelationField', {
-                args,
-                parent, // needs to have the id field populated
-                context,
-                info,
-              })
+            fieldName: 'myField',
+            authorize: async (root, args, context) => {
+              // Authorization logic
+              return true;
+            },
+            resolve: async (root) => {
+              // Resolver is optional
+              return false;
             }
           });
         }
       })
-
     ];
   }
 }));
 ```
 
-#### 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.
+## 🧰 Utility Functions
 
-```typescript
-import { createGraphQLExtension, overrideField, createEntityCollectionResolver } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+This package provides a set of utility functions to make working with Strapi GraphQL resolvers easier and more typesafe:
 
-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 entity
-              const resolver = createEntityCollectionResolver<MyContentType>('api::my-content-type.my-content-type');
-              return resolver({
-                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 entity
-              const resolver = createEntityCollectionResolver<MyContentType>('api::my-content-type.my-content-type');
-              return resolver({
-                args,
-                parent,
-                context,
-                info,
-              })
-            }
-          });
-        }
-      })
+### **Entity and Collection Resolvers**
 
-    ];
-  }
-}));
-```
+- **`resolveEntity`**  
+  Resolve a single entity by ID.
 
-#### resolveEntityRelationCollection
+  ```typescript
+  import { resolveEntity } from 'buro26-strapi-graphql';
 
-This function has a similar API as `createEntityRelationCollectionResolver` but is used to resolve a collection of entities from a
-relational field on the provided content type. The only difference is that the resolvers first argument is the relation field name that should be resolved.
+  // Inside a resolver:
+  return resolveEntity<MyContentType>('api::my-content-type.my-content-type', {
+    args: { id: 'the id here' },
+    parent,
+    context,
+    info,
+  });
+  ```
 
-#### toEntityResponse
+- **`resolveEntityRelation`**  
+  Resolve a related entity from a relation field.
 
-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.
+  ```typescript
+  import { resolveEntityRelation } from 'buro26-strapi-graphql';
 
-This function is re-exported from the Strapi GraphQL plugin.
+  return resolveEntityRelation<MyContentType>(
+    'api::my-content-type.my-content-type',
+    'relationFieldName',
+    { args, parent, context, info }
+  );
+  ```
 
-#### toEntityCollectionResponse
+- **`resolveEntityCollection`**  
+  Resolve a collection of entities.
 
-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.
+  ```typescript
+  import { createEntityCollectionResolver } from 'buro26-strapi-graphql';
 
-This function is re-exported from the Strapi GraphQL plugin.
+  const resolver = createEntityCollectionResolver<MyContentType>('api::my-content-type.my-content-type');
+  return resolver({ args, parent, context, info });
+  ```
 
-#### resolveArgs
+- **`resolveEntityRelationCollection`**  
+  Resolve a collection of related entities from a relation field.
 
-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.
+  ```typescript
+  import { resolveEntityRelationCollection } from 'buro26-strapi-graphql';
 
-This function is re-exported from the Strapi GraphQL plugin.
+  return resolveEntityRelationCollection<MyContentType>(
+    'api::my-content-type.my-content-type',
+    'relationFieldName',
+    { args, parent, context, info }
+  );
+  ```
 
-#### shadowCRUD
+### **Response Builders**
 
-This function is a typesafe utility function to create shadow CRUD operations for a content type. It will create the CRUD operations for the content type and return the shadow CRUD object.
+- **`toEntityResponse`**  
+  Typesafe builder for a single entity response.
 
-```typescript
-import { createGraphQLExtension, shadowCRUD } from 'buro26-strapi-graphql';
+  ```typescript
+  import { toEntityResponse } from 'buro26-strapi-graphql';
 
-export default createGraphQLExtension((strapi) => ({
+  return toEntityResponse(entity, 'api::my-content-type.my-content-type');
+  ```
 
-  init() {
-    shadowCRUD('api::article.article')
-      .disableActions(['create', 'update', 'delete']);
+- **`toEntityCollectionResponse`**  
+  Typesafe builder for a collection response.
 
-    shadowCRUD('api::category.category')
-      .field('title')
-      .disable();
-  }
+  ```typescript
+  import { toEntityCollectionResponse } from 'buro26-strapi-graphql';
 
-}));
-```
+  return toEntityCollectionResponse(entities, 'api::my-content-type.my-content-type');
+  ```
+
+### **Argument and CRUD Utilities**
 
-## Test and Deploy
+- **`resolveArgs`**  
+  Typesafe utility to transform GraphQL args for use with Strapi’s entity manager.
 
-### Running tests
+  ```typescript
+  import { resolveArgs } from 'buro26-strapi-graphql';
 
-To run tests, run the following command:
+  const entityManagerArgs = resolveArgs(graphqlArgs);
+  ```
+
+- **`shadowCRUD`**  
+  Typesafe utility to create shadow CRUD operations for a content type.
+
+  ```typescript
+  import { shadowCRUD } from 'buro26-strapi-graphql';
+
+  shadowCRUD('api::article.article')
+    .disableActions(['create', 'update', 'delete']);
+
+  shadowCRUD('api::category.category')
+    .field('title')
+    .disable();
+  ```
+
+---
+
+## 🧪 Testing
+
+To run tests:
 
 ```bash
 bun test
 ```
 
-## Contributing
+---
 
-Wish to contribute to this project? Pull the project from the repository and create a merge request.
+## 🤝 Contributing
 
-## Authors and acknowledgment
+Pull requests and contributions are welcome!  
+See the repo for details.
+
+---
+
+## 👥 Authors and Acknowledgment
+
+**Buro26** – [https://buro26.digital](https://buro26.digital)
 
-Buro26 - https://buro26.digital  
 Special thanks to all contributors and the open-source community for their support and contributions.
 
-## License
+---
+
+## 📄 License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
 
-## Project status
+---
+
+## 🚦 Project Status
+
+Active development.  
+Check issues for updates and planned features.
+
+---
 
-The project is currently in active development. We are continuously working on adding new features and improving the
-existing ones. Check the issues section for the latest updates and planned features.
+**Questions or suggestions?**  
+Open an issue or reach out to [Buro26](https://buro26.digital).
 
-Feel free to reach out if you have any questions or suggestions!