buro26-strapi-graphql 0.0.26 → 0.2.0

package/README.md

@@ -1,589 +1,608 @@
 # 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
+---
+
+## 🏗️ Recommended: The Field Builder Pattern
+
+The **recommended way** to build GraphQL fields is with `createGraphQLFieldBuilder()`.  
+This fluent, type-safe builder gives you the best DX, composability, and testability.
 
-### Configure Strapi GraphQL plugin
+### **Example: A Custom Query Field**
 
-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).
+```typescript
+import { createGraphQLFieldBuilder } from 'buro26-strapi-graphql';
+import { nonNull, stringArg } from 'nexus';
+
+export default createGraphQLFieldBuilder()
+  .rootType('Query')
+  .fieldName('helloWorld')
+  .args({ name: nonNull(stringArg()) })
+  .outputType(nonNull('String'))
+  .description('Returns a personalized greeting')
+  .withAuth(false)
+  .resolver(async (parent, args) => `Hello World ${args.name}`);
+```
 
-### Enable plugin
+> **Canonical style:** `createGraphQLFieldBuilder().rootType(...)`, `.withAuth(...)` for authentication and
+> `.authorize(...)` for authorization. `createGraphQLFieldBuilder('Query')` and `.resolverConfig({ auth })`
+> still work but are not used in new code.
 
-Add plugin in `./config/plugins.[js/ts]` in your Strapi project.
+---
+
+## 🔗 Relations
+
+Use `.relation()` to define (or protect) a relation field. It produces exactly the field Strapi generates:
+the same output type, filter/pagination arguments, resolver (with query validation and output sanitizing)
+and `<target>.find` permission scope, on **Strapi v4 and v5**.
 
 ```typescript
-export default () => ({
-  // ...
-  'burotwosix-graphql-plugin': {
-    enabled: true
-  }
-  // ...
-})
+export default createGraphQLFieldBuilder()
+  .rootType('Order')
+  .relation('api::order.order', 'customer')
+  .authorize(isOrderCustomer);
 ```
 
-### Create a new GraphQL Extension
+| | Strapi v4 | Strapi v5 |
+|---|---|---|
+| to-one | `XEntityResponse` | `X` |
+| to-many | `XRelationResponseCollection` | `[X]!` **and** `<field>_connection` (both get the same auth/middleware) |
 
-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.
+For to-one relations you can pass `{ batch: true }` to load the relation of all parents in the request with a
+single query (see [Data loading](#-data-loading)).
 
-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    |
+## 🛡️ Protecting Strapi's Generated Fields
 
-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.
+`protectFields()` adds authorization and/or middleware to fields Strapi generates for a content type —
+scalars, enums, media, components and relations — **without redefining them**. Strapi's types, arguments and
+resolvers stay untouched, so it behaves the same on v4 and v5 (for v5 to-many relations the
+`<field>_connection` field is protected too).
 
 ```typescript
-import { createGraphQLExtension } from 'buro26-strapi-graphql';
-import { extendType, nonNull, stringArg } from 'nexus';
+// e.g. src/api/customer/graphql/_protect.ts
+import { protectFields } from 'buro26-strapi-graphql';
 
-export default createGraphQLExtension(strapi => ({
+protectFields<Customer>('api::customer.customer', ['street', 'postalCode', 'iban', 'orders'])
+  .authorize((customer, _args, ctx) => isSelf(customer, ctx.state.user))
+  .middleware(auditLog);
+```
 
-  init() {
-    // e.g. disable actions
-    strapi
-      .plugin('graphql')
-      .service('extension')
-      .shadowCRUD('api::my-type.my-type')
-      .disableActions(['find', 'findOne', 'create', 'update', 'delete']);
-  },
+The checks are attached by the package's Nexus plugins when the schema is built, so the file only needs to be
+loaded from a `graphql` folder; it does not have to export anything.
 
-  typeDefs() {
-    return `
-      type HelloWorldResponse {
-        greeting: String!
-      }
-    `;
-  },
+> **Non-null fields:** a denied non-null field makes GraphQL null its parent object (standard error propagation).
+> Strapi generates required attributes and v5 to-many relations (`[X]!`) as non-null, so protecting those hides the
+> whole parent for users without access. A warning is logged when the schema is built. Prefer this over `overrideField` when you
+only want to restrict access.
 
-  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
-            }
-          });
-        }
-      })
-    ];
-  },
+## ⚡ Data Loading
 
-  resolvers() {
-    return {
-      Query: {
-        // Override an existing query
-        helloWorld: async (root, args) => {
-          // resolve logic
-        }
-      },
-      Mutation: {
-        // Override an existing mutation
-        updateMyType: async (root, args) => {
-          // resolve logic
-        }
-      }
-    };
-  },
+`loaders(ctx)` gives every request its own batching cache (DataLoader-style, no extra dependency). Loads from the
+same tick are combined into one query; results are cached until the request ends.
 
-  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);
-          }
-        ]
-      }
-    };
-  }
-}));
+```typescript
+import { loaders, sanitizeOutput } from 'buro26-strapi-graphql';
+
+// One findMany ... where id IN (...) for all parents in the request
+const order = await loaders(ctx).entity(ORDER, { populate: { customer: true } }).load(parent.id);
+
+// The relation of many parents in one query (raw rows, sanitize before returning them)
+const customer = await loaders(ctx).relation(ORDER, 'customer').load(parent.id);
+
+// Your own batch function, e.g. for an external API
+const profile = await loaders(ctx).custom('profile', (ids: readonly number[]) => fetchProfiles(ids)).load(parent.id);
 ```
 
-### 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:
+Loaders use `strapi.db.query()` (identical in v4 and v5) and return **unsanitized** database rows. For draft &
+publish content types they load the published version unless `status: 'draft'` is passed.
+
+---
+
+## 🏷️ Typing Your Project
+
+Register your user type and entity types once, so `context.state.user` and `parent` are typed everywhere:
 
 ```typescript
-export default createGraphQLExtension()
-  .init(() => {
-    // Initialization logic here...
-  })
-  .typeDefs(`
-    extend type Query {
-      hello: String
-    }
-  `)
-  .resolvers({
-    Query: {
-      hello: () => 'Hello from builder!'
-    }
-  });
+declare module 'buro26-strapi-graphql' {
+  interface Register {
+    user: User;
+    types: { Customer: Customer; Order: Order };
+  }
+}
+
+createGraphQLFieldBuilder()
+  .rootType('Customer')          // parent is now typed as Customer
+  .fieldName('fullName')
+  .outputType('String')
+  .resolver((customer) => `${customer?.firstName} ${customer?.lastName}`);
+```
+
+For registered entity types, `parent` is `Partial<Entity>` with `id` required: Strapi always passes the entity,
+but relations are only present when populated. Unregistered `Query`/`Mutation` fields keep `parent: any`.
 ```
 
-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.
+---
 
-### Shorter way to define a new field
+### **Why use the Field Builder?**
 
-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.
+- **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()`)
 
-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.
+---
 
-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`.
+### **Composable Presets**
+
+Create reusable sets of middleware/auth logic and apply them to any field:
 
 ```typescript
-import { createGraphQLFieldBuilder } from "buro26-strapi-graphql";
-import { nonNull, stringArg } from 'nexus';
+const adminPreset = createGraphQLFieldPreset(builder =>
+  builder
+    .middleware(requireAdmin)
+    .authorize(adminAuth)
+);
 
 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,
-  });
+  .use(adminPreset)
+  .fieldName('adminHello')
+  .outputType('String')
+  .resolver(() => 'Hello, admin!');
 ```
 
-### Overriding 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.
+## 🔒 Field-Level Authorization and Middleware
 
-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.
+Every field defined with `createGraphQLFieldBuilder()` or via Nexus’s `t.field` can use the `extensions` property to
+attach **authorization** and **middleware** logic.
+
+### **Field-Level Authorization**
+
+- Use the `authorize` field in `extensions` to add per-field authorization logic.
+- The function should return `true` (allow), `false` (deny), or throw an error.
+
+**Example:**
 
 ```typescript
-import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+t.field('myField', {
+  type: 'String',
+  extensions: {
+    authorize: async (parent, args, ctx, info) => {
+      // Only allow admins
+      return ctx.state.user?.role === 'admin';
+    }
+  },
+  resolve: () => 'Secret data'
+});
+```
 
-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;
-            }
-          });
-        }
-      })
+> **Note:**  
+> If you use the builder, `.authorize()` will automatically set this property for you.
 
-    ];
-  }
-}));
+---
+
+### **Field-Level Middleware**
+
+- 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.
+
+**Example:**
+
+```typescript
+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'
+});
 ```
 
-### Add authorization to an existing field
+> **Note:**  
+> If you use the builder, `.middleware()` will automatically set this property for you.
+
+---
+
+## 🌍 Global Middleware and Authorization
+
+You can register **global middleware** and **global authorization** that apply to multiple fields based on type, field
+name, or tags.
 
-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.
+Global middleware and authorization are matched when the GraphQL schema is built, so they apply regardless of
+the order in which files are loaded. The matcher receives `{ type, fieldName, tags, contentType, isBuilderField }`.
 
-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.
+By default globals only apply to fields created with the field builder. Pass `{ includeNonBuilderFields: true }`
+to also apply them to Strapi's generated fields and plain Nexus fields:
 
 ```typescript
-import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+registerGlobalAuthorize(() => true, rateLimit, { includeNonBuilderFields: true });
+```
 
-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;
-            }
-          });
-        }
-      })
+**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);
 ```
 
-### Field middleware
+**Order of execution per field:** authentication (`withAuth(true)`) → global authorizes → the field's own
+`authorize` → `protectFields` authorizes → global middlewares → the field's own middlewares → `protectFields`
+middlewares → resolver (argument validation, hooks, tracing).
 
-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.
+## 📝 Best Practices
 
-```typescript
-import { createGraphQLExtension, overrideField } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+- 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.
+- Use **`protectFields()`** to restrict Strapi's generated fields and **`.relation()`** for relation fields.
+- Use **tags** to target groups of fields for global logic.
 
-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 = await next(root, args, context, info);
+### **Validation, Tracing, and Testing**
 
-                  // Do something after the field is resolved
+**Argument validation with Zod** (also types the resolver's `args` as the parsed schema output):
 
-                  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
+```typescript
+import { z } from 'zod';
 
-                  const res = await next(root, args, context, info);
+const nameSchema = z.object({ name: z.string().min(1) });
 
-                  // Do something after the field is resolved
+export default createGraphQLFieldBuilder('Query')
+  .fieldName('hello')
+  .args({ name: 'String!' })
+  .outputType('String')
+  .validateArgs(nameSchema)
+  .resolver((parent, args) => `Hello, ${args.name}!`);
+```
 
-                  return res;
-                }
-              ]
-            }
-          });
-        }
-      })
+**Tracing/profiling:**
 
-    ];
-  }
-}));
+```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!';
+  });
 ```
 
-### Utility functions
+**Testing in isolation** (runs the same pipeline as in production: global and field authorization, `withAuth`,
+middlewares, argument validation and hooks; pass `skipAuth` / `skipMiddleware` to leave parts out):
 
-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
+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!"
+```
+
+---
 
-#### resolveEntity
+### **Batch Registration and Field Groups**
 
-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.
+**Register multiple fields at once:**
 
 ```typescript
-import { createGraphQLExtension, overrideField, resolveEntity } from 'buro26-strapi-graphql';
-import { extendType } from 'nexus';
+import { createGraphQLFieldBuilder, registerFields } from 'buro26-strapi-graphql';
 
-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,
-              })
-            }
-          });
-        }
-      })
+const fieldA = createGraphQLFieldBuilder('Query')
+  .fieldName('foo')
+  .outputType('String')
+  .resolver(() => 'Foo');
 
-    ];
-  }
-}));
+const fieldB = createGraphQLFieldBuilder('Query')
+  .fieldName('bar')
+  .outputType('String')
+  .resolver(() => 'Bar');
+
+export default registerFields(fieldA, fieldB);
+```
+
+**Apply shared logic to a group:**
+
+```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);
 ```
 
-#### resolveEntityRelation
+---
 
-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.
+## 🛠️ Advanced: The Extension Builder
+
+For advanced use-cases, you can use `createGraphQLExtension()` to build a full extension with custom types, resolvers,
+plugins, and more.
 
 ```typescript
-import { createGraphQLExtension, overrideField, resolveEntityRelation } 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 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,
-              })
-            }
-          });
-        }
-      })
-
-    ];
-  }
-}));
+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!' })
+    }
+  });
 ```
 
-#### resolveEntityCollection
+> **Note:**  
+> For most use-cases, prefer the field builder.  
+> Use the extension builder for advanced scenarios (custom plugins, full type overrides, etc).
 
-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.
+---
+
+## 🧩 Overriding and Extending Fields
+
+> To only restrict access to generated fields, use [`protectFields()`](#️-protecting-strapis-generated-fields);
+> for relations, use [`.relation()`](#-relations). Use `overrideField` when you need to replace a field's resolver.
+
+You can override or extend fields in existing types using the `overrideField` helper. Pass authorization via
+`authorize` (or `extensions.authorize`); relation fields are generated for both Strapi v4 and v5:
 
 ```typescript
-import { createGraphQLExtension, overrideField, createEntityCollectionResolver } 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: '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,
-              })
+            fieldName: 'myField',
+            authorize: async (root, args, context) => {
+              // Authorization logic
+              return true;
+            },
+            resolve: async (root) => {
+              // Resolver is optional
+              return false;
             }
           });
         }
       })
-
     ];
   }
 }));
 ```
 
-#### resolveEntityRelationCollection
+---
 
-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.
+## 🧰 Utility Functions
 
-#### toEntityResponse
+This package provides a set of utility functions to make working with Strapi GraphQL resolvers easier and more typesafe:
 
-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.
+### **Entity and Collection Resolvers**
 
-This function is re-exported from the Strapi GraphQL plugin.
+- **`resolveEntity`**  
+  Resolve a single entity by ID.
 
-#### toEntityCollectionResponse
+  ```typescript
+  import { resolveEntity } from 'buro26-strapi-graphql';
 
-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.
+  // Inside a resolver:
+  return resolveEntity<MyContentType>('api::my-content-type.my-content-type', {
+    args: { id: 'the id here' },
+    parent,
+    context,
+    info,
+  });
+  ```
 
-This function is re-exported from the Strapi GraphQL plugin.
+- **`resolveEntityRelation`**  
+  Resolve a related entity from a relation field.
 
-#### resolveArgs
+  ```typescript
+  import { resolveEntityRelation } from 'buro26-strapi-graphql';
 
-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.
+  return resolveEntityRelation<MyContentType>(
+    'api::my-content-type.my-content-type',
+    'relationFieldName',
+    { args, parent, context, info }
+  );
+  ```
 
-This function is re-exported from the Strapi GraphQL plugin.
+- **`resolveEntityCollection`**  
+  Resolve a collection of entities.
 
-#### shadowCRUD
+  ```typescript
+  import { createEntityCollectionResolver } from 'buro26-strapi-graphql';
 
-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.
+  const resolver = createEntityCollectionResolver<MyContentType>('api::my-content-type.my-content-type');
+  return resolver({ args, parent, context, info });
+  ```
 
-```typescript
-import { createGraphQLExtension, shadowCRUD } from 'buro26-strapi-graphql';
+- **`resolveEntityRelationCollection`**  
+  Resolve a collection of related entities from a relation field.
 
-export default createGraphQLExtension((strapi) => ({
+  ```typescript
+  import { resolveEntityRelationCollection } from 'buro26-strapi-graphql';
 
-  init() {
-    shadowCRUD('api::article.article')
-      .disableActions(['create', 'update', 'delete']);
+  return resolveEntityRelationCollection<MyContentType>(
+    'api::my-content-type.my-content-type',
+    'relationFieldName',
+    { args, parent, context, info }
+  );
+  ```
 
-    shadowCRUD('api::category.category')
-      .field('title')
-      .disable();
-  }
+### **Response Builders**
 
-}));
-```
+- **`toEntityResponse`**  
+  Typesafe builder for a single entity response.
+
+  ```typescript
+  import { toEntityResponse } from 'buro26-strapi-graphql';
+
+  return toEntityResponse(entity, 'api::my-content-type.my-content-type');
+  ```
+
+- **`toEntityCollectionResponse`**  
+  Typesafe builder for a collection response.
+
+  ```typescript
+  import { toEntityCollectionResponse } from 'buro26-strapi-graphql';
+
+  return toEntityCollectionResponse(entities, 'api::my-content-type.my-content-type');
+  ```
 
-## Test and Deploy
+### **Argument and CRUD Utilities**
 
-### Running tests
+- **`resolveArgs`**  
+  Typesafe utility to transform GraphQL args for use with Strapi’s entity manager.
 
-To run tests, run the following command:
+  ```typescript
+  import { resolveArgs } from 'buro26-strapi-graphql';
+
+  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
+Tests live in `test/` and run against real Nexus/GraphQL schemas with a minimal `strapi` mock.
 
-Wish to contribute to this project? Pull the project from the repository and create a merge request.
+---
 
-## Authors and acknowledgment
+## 🤝 Contributing
+
+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!