# useMutateRefdataCategory

## Reference Data Mutation Hook
A specialized abstraction of [`useMutateGeneric`](./useMutateGeneric.md) optimized for managing reference data categories with automatic cache invalidation. Part of the reference data management ecosystem.

```mermaid
graph TD
  A[CRUD Operation] --> B[Invalidate Refdata Cache]
  B --> C[Trigger UI Refresh]
```

## Key Features
- **Automatic Cache Busting:** Invalidates reference data cache after mutations
- **Payload Safeguards:** Enforces empty `values` array for new categories
- **Query Key Standardization:** Pre-configured cache key structure

## Usage Pattern
```jsx
const RefdataCategoryManager = () => {
  const { post } = useMutateRefdataCategory({
    endpoint: 'license/refdata',
    afterQueryCalls: {
      post: (newCategory) => showToast(`Created ${newCategory.desc}`)
    }
  });

  const handleCreate = (categoryData) => post({
    desc: 'Publication Types',
    id: 'publication_type'
  });

  return <Button onClick={handleCreate}>Create Category</Button>;
};
```

## Core Enhancements

### 1. Cache Invalidation Pipeline
Automatic refresh flow after mutations:
1. Execute mutation (create/update/delete)
2. Invalidate reference data cache
3. Trigger dependent queries refresh
4. Execute custom `afterQuery` handlers

### 2. Payload Enforcement
New categories receive empty values array:
```js
// Input payload
{ desc: 'Media Formats', id: 'media_format' }

// Actual POST body
{
  desc: 'Media Formats',
  id: 'media_format',
  values: []
}
```

## Configuration

### Inherited Props
Supports all [`useMutateGeneric` props](../useMutateGeneric/README.md#configuration-options) except:

| Prop                   | Override | Reason                   |
|------------------------|----------|--------------------------|
| `payloadMutators.post` | Yes      | Values array enforcement |
| `queryKey`             | Yes      | Standardized refdata key |

### Special Handling
```js
// To bypass empty values array (advanced)
useMutateRefdataCategory({
  payloadMutators: {
    post: (data) => ({ json: data }) // Not recommended
  }
});
```

## Error Handling
Maintains base hook's [error handling characteristics](./useMutateGeneric.md#error-handling-philosophy) with added complexity:
- Cache invalidation occurs **before** custom `afterQuery` handlers
- Failed invalidations log to console but don't block operations

## Integration Requirements
Uses [`useInvalidateRefdata`](../useInvalidateRefdata/README.md) to handle refdata query cache invalidation automatically.