GraphQL Mutations

Learn how to create and use GraphQL mutations in EverShop

Introduction

GraphQL mutations allow you to modify data in your EverShop application. Unlike queries which are read-only, mutations perform write operations such as creating, updating, or deleting data.

Mutation Structure

Mutations in EverShop follow the standard GraphQL mutation syntax:

mutation MutationName {
  mutationField(argument: value) {
    field1
    field2
  }
}

Defining Mutations

Mutations are defined in your GraphQL schema files alongside queries:

Schema Definition

type Foo {
  id: ID!
  name: String!
  description: String
}

type Mutation {
  createFoo(name: String!, description: String): Foo
  updateFoo(id: ID!, name: String, description: String): Foo
  deleteFoo(id: ID!): Boolean
}

let fooList = [
  { id: 1, name: 'Foo', description: 'This is a Foo object' },
  { id: 2, name: 'Bar', description: 'This is a Bar object' }
];

let nextId = 3;

export default {
  Mutation: {
    createFoo: (root, { name, description }, context) => {
      const newFoo = {
        id: nextId++,
        name,
        description: description || null
      };
      fooList.push(newFoo);
      return newFoo;
    },
    
    updateFoo: (root, { id, name, description }, context) => {
      const foo = fooList.find(f => f.id === parseInt(id));
      if (!foo) {
        throw new Error(`Foo with id ${id} not found`);
      }
      
      if (name !== undefined) foo.name = name;
      if (description !== undefined) foo.description = description;
      
      return foo;
    },
    
    deleteFoo: (root, { id }, context) => {
      const index = fooList.findIndex(f => f.id === parseInt(id));
      if (index === -1) {
        throw new Error(`Foo with id ${id} not found`);
      }
      
      fooList.splice(index, 1);
      return true;
    }
  }
};

Mutation Examples

Create Mutation

Create a new resource in the system.

name · String! · required

The name of the new Foo object

description · String

Optional description for the Foo object

createFoo · Foo

Returns the newly created Foo object

Show Foo fields

id · ID!

Auto-generated unique identifier

name · String!

Name of the created object

description · String

Description if provided

Mutation

mutation CreateNewFoo {
  createFoo(name: "New Foo", description: "A newly created object") {
    id
    name
    description
  }
}

{
  "data": {
    "createFoo": {
      "id": "4",
      "name": "New Foo",
      "description": "A newly created object"
    }
  }
}

mutation CreateNewFoo($name: String!, $description: String) {
  createFoo(name: $name, description: $description) {
    id
    name
    description
  }
}

{
  "name": "New Foo",
  "description": "A newly created object"
}

Update Mutation

Update an existing resource.

id · ID! · required

The ID of the Foo object to update

name · String

New name for the object (optional)

description · String

New description for the object (optional)

updateFoo · Foo

Returns the updated Foo object

Mutation

mutation UpdateFoo {
  updateFoo(id: "1", name: "Updated Foo") {
    id
    name
    description
  }
}

{
  "data": {
    "updateFoo": {
      "id": "1",
      "name": "Updated Foo",
      "description": "This is a Foo object"
    }
  }
}

mutation UpdateDescription {
  updateFoo(id: "1", description: "New description only") {
    id
    name
    description
  }
}

Delete Mutation

Remove a resource from the system.

id · ID! · required

The ID of the Foo object to delete

deleteFoo · Boolean

Returns true if the deletion was successful

Mutation

mutation DeleteFoo {
  deleteFoo(id: "3")
}

{
  "data": {
    "deleteFoo": true
  }
}

{
  "data": {
    "deleteFoo": null
  },
  "errors": [
    {
      "message": "Foo with id 999 not found",
      "path": ["deleteFoo"]
    }
  ]
}

Input Types

For complex mutations, use input types to group related fields:

Schema with Input Type

input CreateFooInput {
  name: String!
  description: String
  category: String
  tags: [String!]
}

type Mutation {
  createFoo(input: CreateFooInput!): Foo
}

mutation CreateFoo($input: CreateFooInput!) {
  createFoo(input: $input) {
    id
    name
    description
  }
}

{
  "input": {
    "name": "New Foo",
    "description": "Description here",
    "category": "example",
    "tags": ["tag1", "tag2"]
  }
}

Mutation Context

Mutations have access to the same context object as queries:

export default {
  Mutation: {
    createFoo: (root, { name, description }, context) => {
      // Access authenticated user
      const userId = context.user?.id;
      
      // Access database connection
      const db = context.db;
      
      // Access request object
      const headers = context.request.headers;
      
      // Implementation
      return newFoo;
    }
  }
};

Authorization

Implement authorization checks in your mutation resolvers:

export default {
  Mutation: {
    createFoo: (root, { name, description }, context) => {
      // Check if user is authenticated
      if (!context.user) {
        throw new Error('Authentication required');
      }
      
      // Check if user has permission
      if (!context.user.hasPermission('create_foo')) {
        throw new Error('Insufficient permissions');
      }
      
      // Proceed with mutation
      return createNewFoo(name, description);
    }
  }
};

Validation

Validate input data before processing:

export default {
  Mutation: {
    createFoo: (root, { name, description }, context) => {
      // Validate required fields
      if (!name || name.trim().length === 0) {
        throw new Error('Name is required and cannot be empty');
      }
      
      // Validate length
      if (name.length > 100) {
        throw new Error('Name must be 100 characters or less');
      }
      
      // Validate format
      if (!/^[a-zA-Z0-9\s]+$/.test(name)) {
        throw new Error('Name can only contain letters, numbers, and spaces');
      }
      
      // Create the resource
      return createNewFoo(name, description);
    }
  }
};

Database Integration

Integrate mutations with database operations:

export default {
  Mutation: {
    createFoo: async (root, { name, description }, context) => {
      const db = context.db;
      
      try {
        // Insert into database
        const result = await db.query(
          'INSERT INTO foos (name, description) VALUES ($1, $2) RETURNING *',
          [name, description]
        );
        
        return result.rows[0];
      } catch (error) {
        throw new Error(`Failed to create Foo: ${error.message}`);
      }
    },
    
    updateFoo: async (root, { id, name, description }, context) => {
      const db = context.db;
      
      const updates = [];
      const values = [];
      let paramIndex = 1;
      
      if (name !== undefined) {
        updates.push(`name = $${paramIndex++}`);
        values.push(name);
      }
      
      if (description !== undefined) {
        updates.push(`description = $${paramIndex++}`);
        values.push(description);
      }
      
      values.push(id);
      
      const query = `
        UPDATE foos 
        SET ${updates.join(', ')} 
        WHERE id = $${paramIndex}
        RETURNING *
      `;
      
      const result = await db.query(query, values);
      
      if (result.rows.length === 0) {
        throw new Error(`Foo with id ${id} not found`);
      }
      
      return result.rows[0];
    }
  }
};

Best Practices

Use Descriptive Names

Name your mutations clearly: createProduct, updateUser, deleteOrder

Return Created Objects

Return the full object after creation/update for immediate use

Validate Input

Always validate input data before processing mutations

Handle Errors

Provide clear, actionable error messages

Use Transactions

Wrap related database operations in transactions

Check Authorization

Verify user permissions before allowing mutations

Error Handling

Mutations should provide clear error messages:

export default {
  Mutation: {
    createFoo: (root, { name, description }, context) => {
      try {
        // Validation
        if (!name) {
          throw new Error('Name is required');
        }
        
        // Business logic validation
        if (isDuplicateName(name)) {
          throw new Error(`A Foo with name "${name}" already exists`);
        }
        
        // Create the resource
        return createNewFoo(name, description);
      } catch (error) {
        // Log error for debugging
        console.error('Error creating Foo:', error);
        
        // Re-throw with user-friendly message
        throw error;
      }
    }
  }
};

Testing Mutations

Test your mutations thoroughly:

// Example test
describe('createFoo mutation', () => {
  it('should create a new Foo', async () => {
    const result = await graphql({
      schema,
      source: `
        mutation {
          createFoo(name: "Test Foo", description: "Test description") {
            id
            name
            description
          }
        }
      `,
      contextValue: { user: mockUser }
    });
    
    expect(result.data.createFoo).toBeDefined();
    expect(result.data.createFoo.name).toBe('Test Foo');
  });
  
  it('should reject creation without authentication', async () => {
    const result = await graphql({
      schema,
      source: `
        mutation {
          createFoo(name: "Test Foo") {
            id
          }
        }
      `,
      contextValue: {}
    });
    
    expect(result.errors).toBeDefined();
    expect(result.errors[0].message).toContain('Authentication required');
  });
});

Next Steps

GraphQL Queries

Learn about querying data with GraphQL

GraphQL Overview

Review GraphQL architecture and concepts