Next 0.9

.changeset/bright-laws-relax.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Allow passing array of codes to `isHttpErrorCode`

.changeset/cuddly-walls-rule.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Add _Event_ `.started` to _Query_ and _Mutation_

.changeset/eighty-numbers-promise.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Support custom serialization in `localStorageCache` and `sessionStorageCache`

.changeset/hot-carrots-whisper.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Add _Event_ `aborted` to _Query_

.changeset/poor-ligers-kick.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': patch
+---
+
+Rework internal structure of sourced fields to fix race-condition in `attachOperation`

.changeset/shy-avocados-love.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Mark read-only _Events_ and _Stores_ with `readonly`

.changeset/six-peas-grab.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Add _Store_ `.$finished` to _Remote Operation_

.changeset/spicy-kiwis-wonder.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Delete `externalCache`

.changeset/spotty-poems-play.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Add option `supressIntermediateErrors` to `retry` operator

.changeset/twelve-days-move.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Add info about _Query_ status and corresponding data to `.finished.finally` _Event_

.changeset/wicked-baboons-burn.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': patch
+---
+
+Add `ExecutionMeta` to `otherwise` _Event_ in `retry` operator

apps/website/docs/.vitepress/config.js

@@ -364,6 +364,7 @@ export default withMermaid(
           {
             text: 'Releases',
             items: [
+              { text: 'v0.9', link: '/releases/0-9' },
               { text: 'v0.8 Saphan Hin', link: '/releases/0-8' },
               { text: 'v0.7 Nam Phu Chet Si', link: '/releases/0-7' },
               { text: 'v0.6 Huai Nam Dang', link: '/releases/0-6' },

apps/website/docs/api/operators/cache.md

@@ -1,3 +1,7 @@
+---
+outline: [2, 3]
+---
+
 # `cache` <Badge type="tip" text="since v0.3.0" />
 
 Saves result of the [_Query_](/api/primitives/query) to some storage and allows to restore it back.
@@ -103,3 +107,28 @@ function myCustomAdapter({
 ```
 
 However, we still need to trigger `itemEvicted` and `itemExpired` events in our adapter.
+
+### Custom serialization <Badge type="tip" text="since v0.9.0" />
+
+Adapters that use `localStorage` and `sessionStorage` as a storage for cached results use `JSON.stringify` and `JSON.parse` to serialize and deserialize data. If you need to use custom serialization, you can use `serialize` field in the adapter config:
+
+```ts
+import { cache, localStorageCache } from '@farfetched/core';
+
+cache(query, {
+  adapter: localStorageCache({
+    serialize: {
+      read: (data) => {
+        // Do your custom deserialization here
+
+        return parsedData;
+      },
+      write: (data) => {
+        // Do your custom serialization here
+
+        return serializedData;
+      },
+    },
+  }),
+});
+```

apps/website/docs/api/operators/retry.md

@@ -17,6 +17,7 @@ Config fields:
   - `(params, { attempt }) => mapped`
   - `{ source: Store, fn: (params, { attempt }, source) => mapped }`
 - `otherwise?`: [_Event_](https://effector.dev/docs/api/effector/event) or [_Effect_](https://effector.dev/docs/api/effector/effect), that will be called after the last attempt if the [_Query_](/api/primitives/query) is still failed
+- `supressIntermediateErrors?`: <Badge type="tip" text="since v0.9.0" /> _boolean_ whether to suppress intermediate errors or not, defaults to `false`. If `true`, then the [_Query_](/api/primitives/query) will not be marked as failed until the last attempt is failed.
 
 ## Build-in delays
 

apps/website/docs/api/primitives/mutation.md

@@ -1,30 +1,79 @@
+---
+outline: [2, 3]
+---
+
 # Mutation <Badge type="tip" text="since v0.2.0" />
 
 Representation of a mutation of remote data.
 
-## API reference
+## Commands
+
+This section describes the [_Event_](https://effector.dev/docs/api/effector/event) that can be used to perform actions on the _Mutation_. Commands should be called in application code.
+
+### `start`
+
+Unconditionally starts the _Mutation_ with the given parameters.
+
+## Stores
+
+This section describes the [_Stores_](https://effector.dev/docs/api/effector/store) that can be used to read the _Mutation_ state.
+
+### `$status`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the current status of the _Mutation_. It must not be changed directly. Can be one of the following values: `"initial"`, `"pending"`, `"done"`, `"fail"`.
+
+For convenience, there are also the following [_Stores_](https://effector.dev/docs/api/effector/store):
+
+- `$idle` <Badge type="tip" text="since v0.8.0" /> — `true` if the _Mutation_ is in the `"initial"` state, `false` otherwise.
+- `$pending` — `true` if the _Mutation_ is in the `"pending"` state, `false` otherwise.
+- `$failed` — `true` if the _Mutation_ is in the `"fail"` state, `false` otherwise.
+- `$succeeded` — `true` if the _Mutation_ is in the `"done"` state, `false` otherwise.
+- `$finished` <Badge type="tip" text="since v0.9.0" /> — `true` if the _Mutation_ is in the `"done"` or `"fail"` state, `false` otherwise.
+
+### `$enabled`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the current enabled state of the _Mutation_. Disabled _Mutations_ will not be executed, instead, they will be treated as skipped. It must not be changed directly. Can be `true` or `false`.
+
+## Events
+
+This section describes the [_Event_](https://effector.dev/docs/api/effector/event) that can be used to listen to the _Mutation_ state changes. Events must not be called in application code.
+
+### `finished.success`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Mutation_ is finished with success. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Mutation_
+- `result` with the result of the _Mutation_
+- `meta` with the execution metadata
+
+### `finished.failure`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Mutation_ is finished with failure. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Mutation_
+- `error` with the error of the _Mutation_
+- `meta` with the execution metadata
+
+### `finished.skip`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Mutation_ is skipped. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Mutation_
+- `meta` with the execution metadata
 
-```ts
-const mutation: Mutation<Params, Data, Error>;
+### `finished.finally`
 
-// Stores
-mutation.$status; // Store<'initial' | 'pending' | 'done' | 'fail'>
-mutation.$idle; // Store<boolean>, since v0.8.0
-mutation.$pending; // Store<boolean>
-mutation.$failed; // Store<boolean>
-mutation.$succeeded; // Store<boolean>
-mutation.$enabled; // Store<boolean>
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Mutation_ is finished with success, failure or skip. Payload will contain the object with the following fields:
 
-// Commands
-mutation.start; // Event<Params>;
+- `params` with the parameters that were used to start the _Mutation_
+- `meta` with the execution metadata
+- `status` <Badge type="tip" text="since v0.9.0" /> with a string `"done"`, `"fail"` or `"skip"` for success, failure or skip respectively
+- `result` <Badge type="tip" text="since v0.9.0" /> if the `status` is `"done"` with the result of the _Mutation_
+- `error` <Badge type="tip" text="since v0.9.0" /> if the `status` is `"fail"` with the error of the _Mutation_
 
-// Events
-mutation.finished.success; // Event<Data>;
-mutation.finished.failure; // Event<Error>;
-mutation.finished.skip; // Event<void>;
-mutation.finished.finally; // Event<void>;
+## `started` <Badge type="tip" text="since v0.9.0" />
 
-// Note: Store and Event are imported from 'effector' package
-```
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Mutation_ is started. Payload will contain the object with the following fields:
 
-More information about API can be found in [the source code](https://github.com/igorkamyshev/farfetched/blob/master/packages/core/src/mutation/type.ts).
+- `params` with the parameters that were used to start the _Mutation_
+- `meta` with the execution metadata

apps/website/docs/api/primitives/query.md

@@ -1,36 +1,110 @@
+---
+outline: [2, 3]
+---
+
 # Query
 
 Representation of a piece of remote data.
 
-## API reference
-
-```ts
-const query: Query<Params, Data, Error>;
-const query: Query<Params, Data, Error, InitialData>; // InitialData is allowed since v0.3.0
-
-// Stores
-query.$data; // Store<Data | InitialData>
-query.$error; // Store<Error | null>
-query.$status; // Store<'initial' | 'pending' | 'done' | 'fail'>
-query.$idle; // Store<boolean>, since v0.8.0
-query.$pending; // Store<boolean>
-query.$failed; // Store<boolean>, since v0.2.0
-query.$succeeded; // Store<boolean>, since v0.2.0
-query.$enabled; // Store<boolean>
-query.$stale; // Store<boolean>
-
-// Commands
-query.start; // Event<Params>
-query.reset; // Event<void>, since v0.2.0
-query.refresh; // Event<Params>. since v0.8.0
-
-// Events
-query.finished.success; // Event<{ result: Data, params: Params }>
-query.finished.failure; // Event<{ error: Error, params: Params }>
-query.finished.skip; // Event<{ params: Params }>
-query.finished.finally; // Event<{ params: Params }>
-
-// Note: Store and Event are imported from 'effector' package
-```
-
-More information about API can be found in [the source code](https://github.com/igorkamyshev/farfetched/blob/master/packages/core/src/query/type.ts).
+## Commands
+
+This section describes the [_Event_](https://effector.dev/docs/api/effector/event) that can be used to perform actions on the _Query_. Commands should be called in application code.
+
+### `start`
+
+Unconditionally starts the _Query_ with the given parameters.
+
+### `refresh` <Badge type="tip" text="since v0.8.0" />
+
+Starts the _Query_ with the given parameters if it is `$stale`. Otherwise, it will be treated as skipped.
+
+### `reset` <Badge type="tip" text="since v0.2.0" />
+
+Resets the _Query_ to the initial state.
+
+## Stores
+
+This section describes the [_Stores_](https://effector.dev/docs/api/effector/store) that can be used to read the _Query_ state.
+
+### `$data`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the latest data. It must not be changed directly. In case of error, it will contain the initial data.
+
+### `$error`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the latest error. It must not be changed directly. In case of success, it will contain `null`.
+
+### `$status`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the current status of the _Query_. It must not be changed directly. Can be one of the following values: `"initial"`, `"pending"`, `"done"`, `"fail"`.
+
+For convenience, there are also the following [_Stores_](https://effector.dev/docs/api/effector/store):
+
+- `$idle` <Badge type="tip" text="since v0.8.0" /> — `true` if the _Query_ is in the `"initial"` state, `false` otherwise.
+- `$pending` — `true` if the _Query_ is in the `"pending"` state, `false` otherwise.
+- `$failed` <Badge type="tip" text="since v0.2.0" /> — `true` if the _Query_ is in the `"fail"` state, `false` otherwise.
+- `$succeeded` <Badge type="tip" text="since v0.2.0" /> — `true` if the _Query_ is in the `"done"` state, `false` otherwise.
+- `$finished` <Badge type="tip" text="since v0.9.0" /> — `true` if the _Query_ is in the `"done"` or `"fail"` state, `false` otherwise.
+
+### `$enabled`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the current enabled state of the _Query_. Disabled queries will not be executed, instead, they will be treated as skipped. It must not be changed directly. Can be `true` or `false`.
+
+### `$stale`
+
+[_Store_](https://effector.dev/docs/api/effector/store) with the current stale state of the _Query_. Stale queries will be executed on the next call to `refresh` [_Event_](https://effector.dev/docs/api/effector/event). It must not be changed directly. Can be `true` or `false`.
+
+## Events
+
+This section describes the [_Event_](https://effector.dev/docs/api/effector/event) that can be used to listen to the _Query_ state changes. Events must not be called in application code.
+
+### `finished.success`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Query_ is finished with success. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Query_
+- `result` with the result of the _Query_
+- `meta` with the execution metadata
+
+### `finished.failure`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Query_ is finished with failure. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Query_
+- `error` with the error of the _Query_
+- `meta` with the execution metadata
+
+### `finished.skip`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Query_ is skipped. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Query_
+- `meta` with the execution metadata
+
+### `finished.finally`
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Query_ is finished with success, failure or skip. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Query_
+- `meta` with the execution metadata
+- `status` <Badge type="tip" text="since v0.9.0" /> with a string `"done"`, `"fail"` or `"skip"` for success, failure or skip respectively
+- `result` <Badge type="tip" text="since v0.9.0" /> if the `status` is `"done"` with the result of the _Query_
+- `error` <Badge type="tip" text="since v0.9.0" /> if the `status` is `"fail"` with the error of the _Query_
+
+## `aborted` <Badge type="tip" text="since v0.9.0" />
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Query_ is aborted. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Query_
+- `meta` with the execution metadata
+
+::: tip
+Now, aborted _Queries_ are treated as failed. This means that `.finished.failure` will be triggered as well as `.aborted`. In v0.10 we will change this behavior and `.aborted` will not trigger `.finished.failure` and _Query_ will not be moved to the `"fail"` state.
+:::
+
+## `started` <Badge type="tip" text="since v0.9.0" />
+
+[_Event_](https://effector.dev/docs/api/effector/event) that will be triggered when the _Query_ is started. Payload will contain the object with the following fields:
+
+- `params` with the parameters that were used to start the _Query_
+- `meta` with the execution metadata

apps/website/docs/api/utils/error_guards.md

@@ -71,7 +71,11 @@ const httpError = sample({
 
 ### `isHttpErrorCode`
 
-This function is a more specific version of `isHttpError`. It takes a number as an argument and returns a function that checks if the error is a `HttpError` with the given status code.
+This function is a more specific version of `isHttpError`.
+
+#### `isHttpErrorCode(statusCode: number)`
+
+It takes a number as an argument and returns a function that checks if the error is a `HttpError` with the given status code.
 
 ```ts
 import { isHttpErrorCode } from '@farfetched/core';
@@ -82,6 +86,19 @@ const notFound = sample({
 });
 ```
 
+#### `isHttpErrorCode(statusCodes: number[])` <Badge type="tip" text="since v0.9.0" />
+
+It takes an array of numbers as an argument and returns a function that checks if the error is a `HttpError` with one of the given status codes.
+
+```ts
+import { isHttpErrorCode } from '@farfetched/core';
+
+const notFoundOrForbidden = sample({
+  clock: query.finished.failure,
+  filter: isHttpErrorCode([404, 403]),
+});
+```
+
 ## `isNetworkError`
 
 `NetworkError` is thrown when the query fails because of network problems.