Support mapError for Mutations

Author: AlexandrHoroshih

apps/website/docs/api/factories/create_json_mutation.md

@@ -38,6 +38,17 @@ Config fields:
     - `params`: params which were passed to the [_Mutation_](/api/primitives/mutation)
     - `headers`: <Badge type="tip" text="since v0.13" /> raw response headers
 
+  - `mapError?`: <Badge type="tip" text="since v0.14" /> optional mapper for the error, available overloads:
+
+    - `(err) => mapped`
+    - `{ source: Store, fn: (err, sourceValue) => mapped }`
+
+    `err` object contains:
+
+    - `error`: the original error that occurred
+    - `params`: params which were passed to the [_Mutation_](/api/primitives/mutation)
+    - `headers`: raw response headers (available for HTTP errors and contract/validation errors where the response was received, not available for network errors)
+
   - `status.expected`: `number` or `Array<number>` of expected HTTP status codes, if the response status code is not in the list, the mutation will be treated as failed
 
 - `concurrency?`: concurrency settings for the [_Mutation_](/api/primitives/mutation)
@@ -50,3 +61,77 @@ Config fields:
   :::
 
   - `abort?`: [_Event_](https://effector.dev/en/api/effector/event/) after calling which all in-flight requests will be aborted
+
+## Examples
+
+### Error mapping
+
+You can transform errors before they are passed to the [_Mutation_](/api/primitives/mutation) using `mapError`:
+
+```ts
+const loginMutation = createJsonMutation({
+  params: declareParams<{ login: string; password: string }>(),
+  request: {
+    method: 'POST',
+    url: 'https://api.salo.com/login',
+    body: ({ login, password }) => ({ login, password }),
+  },
+  response: {
+    contract: loginContract,
+    mapError({ error, params, headers }) {
+      if (isHttpError({ status: 401, error })) {
+        return {
+          type: 'unauthorized',
+          message: 'Invalid credentials',
+          requestId: headers?.get('X-Request-Id'),
+        };
+      }
+      if (isHttpError({ status: 429, error })) {
+        return {
+          type: 'rate_limited',
+          message: 'Too many attempts, please try again later',
+          requestId: headers?.get('X-Request-Id'),
+        };
+      }
+      return {
+        type: 'unknown',
+        message: 'Something went wrong',
+        requestId: headers?.get('X-Request-Id'),
+      };
+    },
+  },
+});
+```
+
+With a sourced mapper:
+
+```ts
+const $errorMessages = createStore({
+  401: 'Invalid credentials',
+  429: 'Too many attempts',
+});
+
+const loginMutation = createJsonMutation({
+  params: declareParams<{ login: string; password: string }>(),
+  request: {
+    method: 'POST',
+    url: 'https://api.salo.com/login',
+    body: ({ login, password }) => ({ login, password }),
+  },
+  response: {
+    contract: loginContract,
+    mapError: {
+      source: $errorMessages,
+      fn({ error, headers }, messages) {
+        if (isHttpError({ error })) {
+          return {
+            message: messages[error.status] ?? 'Unknown error',
+            requestId: headers?.get('X-Request-Id'),
+          };
+        }
+        return { message: 'Network error', requestId: null };
+      },
+    },
+  },
+});
+```

apps/website/docs/api/factories/create_mutation.md

@@ -71,3 +71,54 @@ const loginMutation = createMutation({
 //   params: { login: string, password: string }
 // }>
 ```
+
+### `createMutation({ effect, contract?, mapError: Function })` <Badge type="tip" text="since v0.14" />
+
+Creates [_Mutation_](/api/primitives/mutation) based on given [_Effect_](https://effector.dev/en/api/effector/effect/). When the [_Mutation_](/api/primitives/mutation) fails, the error is passed to `mapError` callback, and the result of the callback will be treated as the error of the [_Mutation_](/api/primitives/mutation).
+
+```ts
+const loginMutation = createMutation({
+  effect: loginFx,
+  contract: loginContract,
+  mapError({ error, params }) {
+    // Transform any error into a user-friendly message
+    if (isHttpError({ status: 401, error })) {
+      return { code: 'UNAUTHORIZED', message: 'Invalid credentials' };
+    }
+    return { code: 'UNKNOWN', message: 'Failed to login' };
+  },
+});
+
+// typeof loginMutation.finished.failure === Event<{
+//   error: { code: string, message: string },
+//   params: { login: string, password: string }
+// }>
+```
+
+### `createMutation({ effect, contract?, mapError: { source, fn } })` <Badge type="tip" text="since v0.14" />
+
+Creates [_Mutation_](/api/primitives/mutation) based on given [_Effect_](https://effector.dev/en/api/effector/effect/). When the [_Mutation_](/api/primitives/mutation) fails, the error is passed to `mapError.fn` callback as well as original parameters of the [_Mutation_](/api/primitives/mutation) and current value of `mapError.source` [_Store_](https://effector.dev/en/api/effector/store/), result of the callback will be treated as the error of the [_Mutation_](/api/primitives/mutation).
+
+```ts
+const $errorMessages = createStore({
+  401: 'Invalid credentials',
+  403: 'Access denied',
+});
+
+const loginMutation = createMutation({
+  effect: loginFx,
+  contract: loginContract,
+  mapError: {
+    source: $errorMessages,
+    fn({ error, params }, errorMessages) {
+      if (isHttpError({ error })) {
+        return {
+          message: errorMessages[error.status] ?? 'Unknown error',
+          status: error.status,
+        };
+      }
+      return { message: 'Network error', status: null };
+    },
+  },
+});
+```

apps/website/docs/recipes/data_flow.md

@@ -175,9 +175,36 @@ const userQuery = createJsonQuery({
 The error mapper receives the following data:
 
 - `error`: the original error that occurred
-- `params`: the parameters that were passed to the [_Query_](/api/primitives/query)
+- `params`: the parameters that were passed to the [_Query_](/api/primitives/query) or [_Mutation_](/api/primitives/mutation)
 - `headers`: raw response headers (available for HTTP errors and contract/validation errors where the response was received, not available for network errors)
 
+The same `mapError` option is available for [_Mutations_](/api/primitives/mutation):
+
+```ts
+const $errorMessages = createStore({
+  401: 'Invalid credentials',
+  429: 'Too many attempts',
+});
+
+const loginMutation = createJsonMutation({
+  //...
+  response: {
+    mapError: {
+      source: $errorMessages,
+      fn: ({ error, headers }, messages) => {
+        if (isHttpError({ error })) {
+          return {
+            message: messages[error.status] ?? 'Unknown error',
+            requestId: headers?.get('X-Request-Id'),
+          };
+        }
+        return { message: 'Network error', requestId: null };
+      },
+    },
+  },
+});
+```
+
 ## Data-flow in basic factories
 
 **Basic factories** are used to create _Remote Operations_ with a more control of data-flow in user-land. In this case, the user-land code have to describe **request-response cycle** and **response parsing** stages. Other stages could be handled by the library, but it is not required for **basic factories**.