update readme

Author: zavvdev

README.md

@@ -6,7 +6,7 @@ You might have written code that uses redux and redux-saga to implement data fet
 
 All you need to do now, is to instantiate redux-saga-query and use functions that it provides: _reducer_ - that you just need to connect to your store and it will manage data, _query_ - for requesting data that needs to be cached, _mutation_ - for requesting data without caching, and more.
 
-The main idea is that you can request your data from anywhere in your sagas and not to worry about managing it's state.
+The main idea is that you can request your data from anywhere in your sagas and not worry about managing its state.
 
 This package has only one dependency - [redux-saga](https://github.com/redux-saga/redux-sag) which needs to be installed in your project.
 
@@ -32,9 +32,9 @@ $ pnpm add redux-saga-query
 
 ## Usage Example
 
-Suppose you have a redux in your project. It can be vanilla redux or [redux-toolkit](https://redux-toolkit.js.org/), doesn't matter. It can be even custom I/O environment like redux, since redux-saga [allows you to do that](https://redux-saga.js.org/docs/advanced/UsingRunSaga).
+Suppose you have a redux in your project. It can be vanilla redux or [redux-toolkit](https://redux-toolkit.js.org/), doesn't matter. It can even be a custom I/O environment like redux, since redux-saga [allows you to do that](https://redux-saga.js.org/docs/advanced/UsingRunSaga).
 
-Since you have storage, you have some data that needs to be derived from some place, for example, from some API. This package gives you an `initSagaQuery` function which needs to be called ones per domain. Domain is like a record in store that will be responsible for managing its data.
+Since you have storage, you have some data that needs to be derived from some place, for example, from some API. This package gives you an `initSagaQuery` function which needs to be called once per domain. Domain is like a record in store that will be responsible for managing its data.
 
 ```
 import { initSagaQuery } from "redux-saga-query";
@@ -66,7 +66,7 @@ export var rootReducer = {
 };
 ```
 
-Now you ready to use other functions provided by `initSagaQuery` in your application.
+Now you are ready to use other functions provided by `initSagaQuery` in your application.
 
 ```
 function* fetchBooks() {
@@ -83,15 +83,15 @@ function* fetchBooks() {
 }
 ```
 
-Here we used `query` function to retrieve a list of books from external api. Under the hood this function dispatches `REQUEST` action if data is stale, makes a new call using your function, caches the result to storage and returns it back where you called it. If data is not stale, it doesn't make new request and returns back cached data from storage. More information in [Documentation](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#documentation) and [Example](https://github.com/zavvdev/redux-saga-query/tree/main/example).
+Here we used a `query` function to retrieve a list of books from an external api. Under the hood this function dispatches `REQUEST` action if data is stale, makes a new call using your function, caches the result to storage and returns it back where you called it. If data is not stale, it doesn't make new requests and returns back cached data from storage. More information in [Documentation](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#documentation) and [Example](https://github.com/zavvdev/redux-saga-query/tree/main/example).
 
 # Documentation
 
 ## API
 
 ### initSagaQuery
 
-Use this function to initialize redux-saga-query. You should call it once per domain. Domain is responsible for storing cached data. It's just an object with keys that store you data. You can have one or multiple domains. For example, one common `api` domain.
+Use this function to initialize redux-saga-query. You should call it once per domain. Domain is responsible for storing cached data. It's just an object with keys that store your data. You can have one or multiple domains. For example, one common `api` domain.
 
 **Arguments**
 
@@ -118,7 +118,7 @@ Use this function to initialize redux-saga-query. You should call it once per do
 
 - **Required**: No
 - **Type**: Number
-- **Description**: Amount of time in milliseconds that should pass until next retry will be executed it case `fn` function of query or mutation throws an error
+- **Description**: Amount of time in milliseconds that should pass until next retry will be executed in case `fn` function of query or mutation throws an error
 
 `query`
 
@@ -189,7 +189,7 @@ Use this function to initialize redux-saga-query. You should call it once per do
 ### Key
 
 - **Type**: [Array<string | number | bigint | boolean>](https://github.com/zavvdev/redux-saga-query/blob/3cc865dafe4194b1caccb39574e4a87c2ca18962/src/index.d.ts#L14)
-- **Description**: Unique identifier for each query or mutation which used as part of dispatched action type by redux-saga-query
+- **Description**: Unique identifier for each query and mutation
 
 ### QueryRecord
 
@@ -209,7 +209,7 @@ Use this function to initialize redux-saga-query. You should call it once per do
 `isLoaded`
 
 - **Type**: Boolean
-- **Description**: Has value `true` if `fn` function of query has been successfully derived its data
+- **Description**: Has value `true` if `fn` function of query has successfully derived its data
 
 `isError`
 
@@ -219,17 +219,17 @@ Use this function to initialize redux-saga-query. You should call it once per do
 `isValid`
 
 - **Type**: Boolean
-- **Description**: Has value `true` if `fn` query data doesn't need to be requested again. In other words, it's not stale because `staleTime` milliseconds has not been passed yet. But keep in mind that this value won't be updated automatically if nothing is being requested yet using its query Key. For example, if you have data that is valid and you don't request it again after it has become invalid, this field will still show you that it's valid event if it's staleTime has already passed. The only way to update state and get fresh status of this field is to trigger request again somewhere
+- **Description**: Has value `true` if query data doesn't need to be requested again. In other words, it's not stale because `staleTime` milliseconds has not passed yet. But keep in mind that this value won't be updated automatically if nothing is being requested yet using the respective query Key. For example, if you have data that is valid and you didn't request it again after it had become invalid, this field will still show you that it's valid even if its staleTime had already passed. The only way to update state and get fresh status of this field is to trigger request again somewhere
 
 `isReset`
 
 - **Type**: Boolean
-- **Description**: Has value `true` if `fn` query data is in reset state. Technically, reset state is when you have no data but query record is present in domain state. Redux-saga-query does not make reset of your data. It can only be reset by you manually by calling `reset` function
+- **Description**: Has value `true` if fn query data is in reset state. Technically, a reset state is when you have no data but a query record is present in the domain state. Redux-saga-query does not reset your data. It can only be reset by you manually by calling [reset](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#initsagaquery) function
 
 `timestamp`
 
 - **Type**: Number | Undefined
-- **Description**: Has the last timestamp when `fn` function of query has been successfully derived its data
+- **Description**: Has the last timestamp when `fn` function of query has successfully derived its data
 
 `data`
 
@@ -239,7 +239,7 @@ Use this function to initialize redux-saga-query. You should call it once per do
 `error`
 
 - **Type**: Unknown | Null
-- **Description**: Value returned by `extractError` function (default or custom)
+- **Description**: Value returned by `extractError` function
 
 ### MutationRecord
 
@@ -254,7 +254,7 @@ Use this function to initialize redux-saga-query. You should call it once per do
 `isLoaded`
 
 - **Type**: Boolean
-- **Description**: Has value `true` if `fn` function of mutation has been successfully derived its data
+- **Description**: Has value `true` if `fn` function of mutation has successfully derived its data
 
 `isError`
 
@@ -269,4 +269,74 @@ Use this function to initialize redux-saga-query. You should call it once per do
 `error`
 
 - **Type**: Unknown | Null
-- **Description**: Value returned by `extractError` function (default or custom)
+- **Description**: Value returned by `extractError` function
+
+### reducer
+
+- **Type**: Function
+- **Description**: Used for managing your query and mutation data. You only need to connect this function to your store
+- **Arguments**:
+
+  `state` - previous state
+
+  `action` - dispatched action
+
+- **Returns**: Next state
+
+### selector
+
+- **Type**: Function
+- **Description**: Selects QueryRecord or Mutation Record from the storage
+- **Arguments**:
+
+  `key` - [Key](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#key) that represents specific query. Should not be partial.
+
+- **Returns**: [QueryRecord](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#queryrecord), [MutationRecord](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#mutationrecord) or null
+
+### query
+
+- **Type**: Function
+- **Arguments**: Object with next fields:
+
+  `key` - [Key](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#key) that represents this query. Should be unique for each query
+
+  `fn` - Any function that returns some serializable data
+
+  `options` - Fully partial [options](https://github.com/zavvdev/redux-saga-query/blob/272e83e5e8038f11e0231e6f4700f56e8d096b94/src/index.d.ts#L1) that will be applied only for this specific query. Represented as an object the same as in `initSagaQuery` _query_ argument but fully partial
+
+- **Returns**: Generator function which yields redux-saga effects. Returns the result of `fn` if it has successfully derived data or throws an error with value returned from `extractError` function
+- **Description**: Caches the data returned from `fn` function
+
+### mutation
+
+- **Type**: Function
+- **Arguments**: Object with next fields:
+
+  `key` - [Key](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#key) that represents this mutation. Should be unique for each mutation
+
+  `fn` - Any function that returns some serializable data
+
+  `options` - [Options](https://github.com/zavvdev/redux-saga-query/blob/272e83e5e8038f11e0231e6f4700f56e8d096b94/src/index.d.ts#L8) that will be applied only for this specific mutation. Represented as an object the same as in `initSagaQuery` _mutation_ argument
+
+- **Returns**: Generator function which yields redux-saga effects. Returns the result of `fn` if it has successfully derived data or throws an error with value returned from `extractError` function
+- **Description**: Does not cache the data returned from `fn` function
+
+### invalidate
+
+- **Type**: Function
+- **Arguments**:
+
+  `key` - [Key](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#key) that represents any query with exact or partial match
+
+- **Returns**: Void
+- **Description**: Searches in domain for any partially matched keys. If found any - invalidates their data if its valid and not currently in progress (isLoading or isFetching)
+
+### reset
+
+- **Type**: Function
+- **Arguments**:
+
+  `key` - [Key](https://github.com/zavvdev/redux-saga-query/tree/main?tab=readme-ov-file#key) that represents any query with exact or partial match
+
+- **Returns**: Void
+- **Description**: Searches in domain for any partially matched keys. If found any - resets their data if it hasn't been reset yet. Reset means that domain still has a record for this specific query but without any data

src/index.d.ts

@@ -46,7 +46,7 @@ interface Modules {
 
   selector: (
     key: Key,
-  ) => (state: State) => QueryRecord | MutationRecord;
+  ) => (state: State) => QueryRecord | MutationRecord | null;
 
   query: <T extends unknown>(args: {
     key: Key;

src/modules/selector.js

@@ -3,7 +3,7 @@ import { Key } from "../entities/Key";
 var getSelector = function (domain) {
   return (key) => (state) => {
     var createdKey = Key.from(key);
-    return state?.[domain]?.[createdKey];
+    return state?.[domain]?.[createdKey] || null;
   };
 };