Change signature of mapper in mapData to be consistent with `.finis…

…hed.*` _Events_

.changeset/eleven-tools-hammer.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Change signature of mapper in `mapData` to be consistent with `.finished.*` _Events_

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

@@ -23,6 +23,6 @@ Config fields:
   - `contract`: [_Contract_](/api/primitives/contract) allows you to validate the response and decide how your application should treat it — as a success response or as a failed one.
   - `validate?`: [_Validator_](/api/primitives/validator) allows you to dynamically validate received data.
   - `mapData?`: optional mapper for the response data, available overloads:
-    - `(data, params) => mapped`
-    - `{ source: Store, fn: (data, params, source) => mapped }`
+    - `({ result, params }) => mapped`
+    - `{ source: Store, fn: ({ result, params }, source) => mapped }`
   - `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

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

@@ -25,8 +25,8 @@ Config fields:
   - `contract`: [_Contract_](/api/primitives/contract) allows you to validate the response and decide how your application should treat it — as a success response or as a failed one.
   - `validate?`: [_Validator_](/api/primitives/validator) allows you to dynamically validate received data.
   - `mapData?`: optional mapper for the response data, available overloads:
-    - `(data, params) => mapped`
-    - `{ source: Store, fn: (data, params, source) => mapped }`
+    - `({ result, params }) => mapped`
+    - `{ source: Store, fn: (data, { result, params }) => mapped }`
 
 ## Showcases
 

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

@@ -83,7 +83,7 @@ A valid data is passed to `mapData` callback as well as original parameters of t
 const languagesQuery = createQuery({
   effect: fetchLanguagesFx,
   contract: languagesContract,
-  mapData(languages, params) {
+  mapData({ result: languages, params }) {
     return {
       availableLanguages: languages,
       languageCanBeSelected: languages.length > 1,
@@ -113,7 +113,7 @@ const languagesQuery = createQuery({
   mapData: {
     // Current value of $minimalLanguagesCount will be passed to `fn` as a third argument
     source: $minimalLanguagesCount,
-    fn(languages, params, minimalLanguagesCount) {
+    fn({ result: languages, params }, minimalLanguagesCount) {
       return {
         availableLanguages: languages,
         languageCanBeSelected: languages.length > minimalLanguagesCount,

apps/website/docs/recipes/graphql_query.md

@@ -127,7 +127,7 @@ const languageQuery = createJsonQuery({
     url: '/api/language',
     method: 'GET',
   },
-  response: { mapData: (data) => data.language.code },
+  response: { mapData: ({ result }) => result.language.code },
 });
 
 // Query is created by custom factory
@@ -147,7 +147,7 @@ const countriesQuery = createGraphQLQuery({
       }),
     },
   },
-  response: { mapData: (data) => data.countries },
+  response: { mapData: ({ result }) => result.countries },
 });
 
 // They can be used together

apps/website/docs/releases/0-4.md

@@ -245,3 +245,41 @@ const validator = {
   },
 };
 ```
+
+### Change signature of mappers in `mapParams`
+
+`mapParams` now accepts `{ result, params }` object instead of two separate arguments to be consistent with `.finished.*` [_Events_](https://effector.dev/docs/api/effector/event) and [_Validator_](/api/primitives/validator).
+
+#### Function form
+
+```ts
+// before
+const mapper = (result, params) => {
+  // ...
+};
+
+// after
+const mapper = ({ result, params }) => {
+  // ...
+};
+```
+
+#### Object form
+
+```ts
+// before
+const mapper = {
+  source: $externalStore,
+  fn: (result, params, externalSource) => {
+    // ...
+  },
+};
+
+// after
+const mapper = {
+  source: $externalStore,
+  fn: ({ result, params }, externalSource) => {
+    // ...
+  },
+};
+```

packages/core/src/misc/sourced.ts

@@ -9,6 +9,10 @@ export type CallbackWithSource<Data, Result, Source> = {
   fn: (data: Data, source: Source) => Result;
 };
 
+export type DynamicallySourcedField<Data, Result, Source> =
+  | Callback<Data, Result>
+  | CallbackWithSource<Data, Result, Source>;
+
 type SourcedField<Data, Result, Source> =
   | Result
   | Store<Result>

packages/core/src/mutation/__tests__/create_headless_mutation.spec.ts

@@ -4,13 +4,12 @@ import { describe, test, expect, vi } from 'vitest';
 
 import { createHeadlessMutation } from '../create_headless_mutation';
 import { unknownContract } from '../../contract/unknown_contract';
-import { identity } from '../../misc/identity';
 
 describe('createHeadlessMutation', () => {
   test('start triggers executeFx', async () => {
     const mutation = createHeadlessMutation({
       contract: unknownContract,
-      mapData: identity,
+      mapData: ({ result }) => result,
     });
 
     const mockFn = vi.fn();
@@ -26,7 +25,7 @@ describe('createHeadlessMutation', () => {
   test('finished.success triggers after executeFx.done', async () => {
     const mutation = createHeadlessMutation({
       contract: unknownContract,
-      mapData: identity,
+      mapData: ({ result }) => result,
     });
 
     const scope = fork({
@@ -55,7 +54,7 @@ describe('createHeadlessMutation', () => {
     const mutation = createHeadlessMutation({
       contract: unknownContract,
       enabled: false,
-      mapData: identity,
+      mapData: ({ result }) => result,
     });
 
     const scope = fork({
@@ -81,7 +80,7 @@ describe('createHeadlessMutation', () => {
         isData: (_: any): _ is any => false,
         getErrorMessages: () => ['Test error'],
       },
-      mapData: identity,
+      mapData: ({ result }) => result,
     });
 
     const scope = fork({
@@ -110,7 +109,7 @@ describe('createHeadlessMutation', () => {
     const mutation = createHeadlessMutation({
       contract: unknownContract,
       validate: (_: any) => ['Test error'],
-      mapData: identity,
+      mapData: ({ result }) => result,
     });
 
     const scope = fork({
@@ -138,7 +137,7 @@ describe('createHeadlessMutation', () => {
   test('use mapped data', async () => {
     const mutation = createHeadlessMutation({
       contract: unknownContract,
-      mapData: (data) => (data as any) + 1,
+      mapData: ({ result }) => (result as any) + 1,
     });
 
     const scope = fork({

packages/core/src/mutation/__tests__/create_json_mutation.type_spec.ts

@@ -212,8 +212,8 @@ mapData: {
       },
       response: {
         contract,
-        mapData: (data, params) => {
-          expectType<number>(data);
+        mapData: ({ result, params }) => {
+          expectType<number>(result);
           expectType<string>(params);
 
           return false;
@@ -235,8 +235,8 @@ mapData: {
         contract,
         mapData: {
           source: createStore(false),
-          fn: (data, params, soruce) => {
-            expectType<number>(data);
+          fn: ({ result, params }, soruce) => {
+            expectType<number>(result);
             expectType<string>(params);
             expectType<boolean>(soruce);
 
@@ -259,8 +259,8 @@ mapData: {
       },
       response: {
         contract,
-        mapData: (data, params) => {
-          expectType<number>(data);
+        mapData: ({ result, params }) => {
+          expectType<number>(result);
           expectType<void>(params);
 
           return false;
@@ -281,8 +281,8 @@ mapData: {
         contract,
         mapData: {
           source: createStore(false),
-          fn: (data, params, soruce) => {
-            expectType<number>(data);
+          fn: ({ result, params }, soruce) => {
+            expectType<number>(result);
             expectType<void>(params);
             expectType<boolean>(soruce);
 

packages/core/src/mutation/create_headless_mutation.ts

@@ -1,8 +1,5 @@
 import { createRemoteOperation } from '../remote_operation/create_remote_operation';
-import {
-  StaticOrReactive,
-  TwoArgsDynamicallySourcedField,
-} from '../misc/sourced';
+import { DynamicallySourcedField, StaticOrReactive } from '../misc/sourced';
 import { Mutation, MutationSymbol } from './type';
 import { Contract } from '../contract/type';
 import { InvalidDataError } from '../errors/type';
@@ -30,9 +27,8 @@ function createHeadlessMutation<
 }: SharedMutationFactoryConfig & {
   contract: Contract<Data, ContractData>;
   validate?: Validator<ContractData, Params, ValidationSource>;
-  mapData: TwoArgsDynamicallySourcedField<
-    ContractData,
-    Params,
+  mapData: DynamicallySourcedField<
+    { result: ContractData; params: Params },
     MappedData,
     MapDataSource
   >;

packages/core/src/mutation/create_json_mutation.ts

@@ -5,12 +5,11 @@ import { InvalidDataError } from '../errors/type';
 import { ApiRequestError, HttpMethod } from '../fetch/api';
 import { createJsonApiRequest, Json } from '../fetch/json';
 import { FetchApiRecord } from '../misc/fetch_api';
-import { identity } from '../misc/identity';
 import { ParamsDeclaration } from '../misc/params';
 import {
+  DynamicallySourcedField,
   normalizeSourced,
   SourcedField,
-  TwoArgsDynamicallySourcedField,
 } from '../misc/sourced';
 import { Validator } from '../validation/type';
 import {
@@ -95,9 +94,8 @@ function createJsonMutation<
   > & {
     response: {
       contract: Contract<unknown, Data>;
-      mapData: TwoArgsDynamicallySourcedField<
-        Data,
-        Params,
+      mapData: DynamicallySourcedField<
+        { result: Data; params: Params },
         TransformedData,
         DataSource
       >;
@@ -159,9 +157,8 @@ function createJsonMutation<
   > & {
     response: {
       contract: Contract<unknown, Data>;
-      mapData: TwoArgsDynamicallySourcedField<
-        Data,
-        void,
+      mapData: DynamicallySourcedField<
+        { result: Data; params: void },
         TransformedData,
         DataSource
       >;
@@ -207,7 +204,7 @@ function createJsonMutation(config: any): Mutation<any, any, any> {
 
   const headlessMutation = createHeadlessMutation({
     contract: config.response.contract ?? unknownContract,
-    mapData: config.response.mapData ?? identity,
+    mapData: config.response.mapData ?? (({ result }) => result),
     validate: config.response.validate,
     enabled: config.enabled,
     name: config.name,

packages/core/src/mutation/create_mutation.ts

@@ -9,7 +9,6 @@ import { Contract } from '../contract/type';
 import { Mutation } from './type';
 import { resolveExecuteEffect } from '../misc/execute_effect';
 import { unknownContract } from '../contract/unknown_contract';
-import { identity } from '../misc/identity';
 
 // Overload: Only handler
 function createMutation<Params, Data>(
@@ -42,7 +41,7 @@ function createMutation(
     name: config.name,
     enabled: config.enabled,
     contract: config.contract ?? unknownContract,
-    mapData: identity,
+    mapData: ({ result }) => result,
   });
 
   mutation.__.executeFx.use(resolveExecuteEffect(config));

packages/core/src/query/__tests__/connect_query.array.spec.ts

@@ -3,7 +3,6 @@ import { allSettled, fork } from 'effector';
 import { describe, test, expect, vi } from 'vitest';
 
 import { unknownContract } from '../../contract/unknown_contract';
-import { identity } from '../../misc/identity';
 import { withFactory } from '../../misc/sid';
 import { connectQuery } from '../connect_query';
 import { createHeadlessQuery } from '../create_headless_query';
@@ -14,8 +13,8 @@ describe('remote_data/connect_query', () => {
     fn: () =>
       createHeadlessQuery({
         contract: unknownContract,
-        mapData(data) {
-          return data as string;
+        mapData({ result }) {
+          return result as string;
         },
       }),
   });
@@ -25,8 +24,8 @@ describe('remote_data/connect_query', () => {
     fn: () =>
       createHeadlessQuery({
         contract: unknownContract,
-        mapData(data) {
-          return data as Array<string>;
+        mapData({ result }) {
+          return result as Array<string>;
         },
       }),
   });
@@ -44,7 +43,7 @@ describe('remote_data/connect_query', () => {
         unknown
       >({
         contract: unknownContract,
-        mapData: identity,
+        mapData: ({ result }) => result,
       }),
   });
 
@@ -61,7 +60,7 @@ describe('remote_data/connect_query', () => {
         unknown
       >({
         contract: unknownContract,
-        mapData: identity,
+        mapData: ({ result }) => result,
       }),
   });
 

packages/core/src/query/__tests__/connect_query.no_params.spec.ts

@@ -3,7 +3,6 @@ import { allSettled, fork } from 'effector';
 import { describe, test, expect, vi } from 'vitest';
 
 import { unknownContract } from '../../contract/unknown_contract';
-import { identity } from '../../misc/identity';
 import { withFactory } from '../../misc/sid';
 import { connectQuery } from '../connect_query';
 import { createHeadlessQuery } from '../create_headless_query';
@@ -22,7 +21,7 @@ describe('remote_data/connect_query', () => {
         unknown
       >({
         contract: unknownContract,
-        mapData: identity,
+        mapData: ({ result }) => result,
       }),
   });
 
@@ -39,7 +38,7 @@ describe('remote_data/connect_query', () => {
         unknown
       >({
         contract: unknownContract,
-        mapData: identity,
+        mapData: ({ result }) => result,
       }),
   });
 
@@ -56,7 +55,7 @@ describe('remote_data/connect_query', () => {
         unknown
       >({
         contract: unknownContract,
-        mapData: identity,
+        mapData: ({ result }) => result,
       }),
   });