├── .dockerignore
├── .github
└── FUNDING.yml
├── .gitignore
├── .prettierrc
├── Changelog.md
├── Dockerfile
├── LICENSE
├── README.md
├── docker-compose.yml
├── docs
├── _removed.md
├── assets
│ └── async-flow.png
├── async-action-use.md
├── async-actions-creating.md
├── async-actions-introduction.md
├── async-actions-other-options.md
├── async-cache-break-hook.md
├── async-cache-clearing.md
├── async-hooks-overview.md
├── async-post-action-hook.md
├── async-server-rendering.md
├── async-short-circuit-hook.md
├── inject-store-state.md
├── installation.md
├── quick-example-server-rendered.md
├── quick-example.md
├── reactions.md
├── redux-dev-tools.md
├── subscribe.md
├── update-store.md
└── use-store-state-hook.md
├── graphics
├── Icon on Light.png
├── Icon.png
├── logo-new.png
├── logo-newest.png
├── logo.png
└── pullstate-logo.png
├── package.json
├── rollup.config.js
├── src
├── InjectAsyncAction.ts
├── InjectStoreState.ts
├── InjectStoreStateOpt.ts
├── PullstateCore.tsx
├── Store.ts
├── async-types.ts
├── async.ts
├── batch.ts
├── fastDeepEqual.d.ts
├── globalClientState.ts
├── index.ts
├── reduxDevtools.ts
├── useLocalStore.ts
├── useStoreState.ts
├── useStoreStateOpt-types.ts
└── useStoreStateOpt.ts
├── test
├── benchmark
│ ├── BenchmarkUtils.ts
│ ├── all.ts
│ ├── benchmark-all-immer.ts
│ ├── benchmark-async-argument.ts
│ ├── benchmark-destructuring.ts
│ ├── benchmark-immer-with-stores.ts
│ ├── benchmark-immer-without-stores.ts
│ └── keyFromObjectImplementations.ts
├── dist-types
│ └── TestDistTypes.ts
├── jest.config.js
├── old_jest.config.js
├── package.json
├── rtl.setup.ts
├── test.umd.html
├── tests
│ ├── TestSetup.ts
│ ├── TestUtils.ts
│ ├── __snapshots__
│ │ ├── async.tests.tsx.snap
│ │ ├── client.tests.tsx.snap
│ │ └── ssr.tests.tsx.snap
│ ├── async.tests.tsx
│ ├── basic-store.tests.tsx
│ ├── client.tests.tsx
│ ├── core.tests.tsx
│ ├── opt-state-listeners.tests.tsx
│ ├── ssr.async.tests.tsx
│ ├── ssr.tests.tsx
│ └── testStores
│ │ └── TestUIStore.ts
├── tsconfig.json
└── yarn.lock
├── tsconfig.json
├── typedoc.json
├── typedoc.tsconfig.json
├── website
├── README.md
├── core
│ └── Footer.js
├── i18n
│ └── en.json
├── package.json
├── pages
│ └── en
│ │ └── index.js
├── sidebars.json
├── siteConfig.js
├── static
│ ├── css
│ │ └── custom.css
│ └── img
│ │ ├── async-flow.png
│ │ ├── docusaurus.svg
│ │ ├── favicon.png
│ │ ├── favicon
│ │ └── favicon.ico
│ │ ├── icon-transparent-ondark-new.png
│ │ ├── icon-transparent-ondark.png
│ │ ├── icon-transparent-onlight-new.png
│ │ ├── icon-transparent-onlight.png
│ │ ├── logo-new.png
│ │ ├── logo-newest.png
│ │ ├── logo-ondark-small.png
│ │ └── oss_logo.png
└── yarn.lock
└── yarn.lock
/.dockerignore:
--------------------------------------------------------------------------------
1 | */node_modules
2 | *.log
3 |
--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | # These are supported funding model platforms
2 |
3 | github: [lostpebble]
4 | patreon: # Replace with a single Patreon username
5 | open_collective: # Replace with a single Open Collective username
6 | ko_fi: # Replace with a single Ko-fi username
7 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
8 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
9 | liberapay: # Replace with a single Liberapay username
10 | issuehunt: # Replace with a single IssueHunt username
11 | otechie: # Replace with a single Otechie username
12 | custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
13 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | .idea
3 | dist
4 | yarn-error.log
5 | .rpt2_cache
6 | website/build
--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 | "printWidth": 120,
3 | "trailingComma": "es5"
4 | }
--------------------------------------------------------------------------------
/Changelog.md:
--------------------------------------------------------------------------------
1 | # See release tags for new changelog updates
2 |
3 | ---
4 |
5 | ## 1.15.0
6 |
7 | Added integration with Redux Devtools. Make use of `registerInDevtools(Stores)` to use it. Argument is an object of `{ [storeName: string]: Store }` - which will register your stores instanced according to the name provided.
8 |
9 | ### 1.13.2
10 |
11 | More fixes for run() when using `respectCache: true`. Prevents the cacheBreakHook from clearing the current async state, even if the action hasn't finished yet.
12 |
13 | ### 1.13.1
14 |
15 | Some fixes for run() when using `respectCache: true` that makes a second run wait for the result to any currently running action.
16 |
17 | A minor leak fix for `read()`.
18 |
19 | Much thanks to https://github.com/schummar for the fixes!
20 |
21 | ## 1.13.0
22 |
23 | Added in `createAsyncActionDirect()` - which allows you to simply directly wrap promises instead of using `successResult()` or `errorResult()` methods implicitly. Useful for scenarios that don't require such verbosity. It will directly return a `successResult()` - or otherwise, if an error is thrown, an `errorResult()`.
24 |
25 | Allow `use()` of an async action to be executed on the same arguments later on in the component, with the returned method `execute()`.
26 |
27 | ## 1.12.0
28 |
29 | Some TypeScript type updates - hopefully fixing some `strict: true` issues people were having.
30 |
31 | ### 1.11.3
32 |
33 | Patch fix for `run()` and `beckon()` with an action making use of cache hook in the same component causing infinite loops.
34 |
35 | ## 1.11.0
36 |
37 | Added `AsyncActionName.use(args, options)` - a new way to make use of your Async Actions. By default it acts just like `useBeckon()`, except it returns an object instead of an array.
38 |
39 | This returned object now includes more helpful flags, and is shaped like so:
40 |
41 | ```ts
42 | {
43 | isLoading: boolean;
44 | isFinished: boolean;
45 | isUpdating: boolean;
46 | isStarted: boolean;
47 | error: boolean;
48 | endTags: string[];
49 | message: string;
50 | payload: R;
51 | renderPayload: ((payload: R) => any) => any;
52 | }
53 | ```
54 |
55 | If you want `use()` to act like `useWatch()` (i.e. not initiating the action when the hook is first called), then pass in an options object as the second argument, containing `initiate: false`.
56 |
57 | `renderPayload` is a very useful function. You can use this in your React component to conditionally render stuff only when your action payload has returned successfully. You can use it like so:
58 |
59 | ```typescript jsx
60 | const userAction = LoadUserAction.use({ id: userId });
61 |
62 | return (
63 |
64 | {userAction.renderPayload((user) => (
65 | User Name: {user.name}
66 | ))}
67 |
68 | );
69 | ```
70 |
71 | The inner `` there will not render if our action hasn't resolved successfully.
72 |
73 | #### 1.10.5
74 |
75 | Imported modules `immer` and `fast-deep-equal` using ES6 Modules which might help with tree-shaking and bundling in consumer projects.
76 |
77 | #### 1.10.4
78 |
79 | Exported a bunch of TypeScript types (mostly Async stuff) for easier extending of library.
80 |
81 | #### 1.10.3
82 |
83 | Bugfix for when passing dependencies to `useStoreState` as a third argument. Should never re-vert to the previously set state now.
84 |
85 | Fixed Hot Reloading while using `useStoreState` by ensuring that registering of the listener is done within the `useEffect()` hook.
86 |
87 | #### 1.10.2
88 |
89 | Bugfix for `dormant` setting which wasn't re-triggering cached results when switching between dormant and an old cached value.
90 |
91 | #### 1.10.1
92 |
93 | Minor changes for https://github.com/lostpebble/pullstate/issues/25
94 |
95 | Added the ability to run `postActionHook` after doing a cache update with `AsyncAction.updateCache()`
96 |
97 | ### 1.10.0
98 |
99 | Updated `immer` to `^5.0.0` which has better support for `Map` and `Set`.
100 |
101 | Updated `fast-deep-equal` to use `^3.0.0`, which has support for `Map` and `Set` types, allowing you to use these without worry in your stores.
102 |
103 | ## 1.9.0
104 |
105 | - Added the ability to pass a third option to `useStoreState()` - this allows the our listener to be dynamically updated to listen to a different sub-state of our store. Similar to how the last argument in `useEffect()` and such work.
106 | - see https://github.com/lostpebble/pullstate/issues/22
107 |
108 | #### React Suspense!
109 |
110 | - You can now use Async Actions with React Suspense. Simply use them with the format: `myAction.read(args)` inside a component which is inside of `` respectively.
208 |
209 | Instead of passing a function, you now pass an array of path selections. The state returned will be an array of values per each state selection path. E.g:
210 |
211 | ```ts
212 | const [isDarkMode] = useStoreStateOpt(UIStore, [["isDarkMode"]]);
213 | ```
214 |
215 | The performance benefits stem from Pullstate not having to run equality checks on the results of your selected state and then re-render your component accordingly, but instead looks at the immer update patches directly for which paths changed in your state and re-renders the listeners on those paths.
216 |
217 | ## 1.1.0
218 |
219 | Fixed issue with postActionHook not being called on the server for Async Actions.
220 |
221 | Added the following methods on Async Actions:
222 |
223 | - `setCached()`
224 | - `updateCached()`
225 |
226 | For a more finer-grained control of async action cache.
227 |
228 | `updateCached()` functions exactly the same as `update()` on stores, except it only runs on a previously successfully returned cached value. If nothing is cached, nothing is run.
229 |
230 | ## 1.0.0-beta.7
231 |
232 | Replaced `shallowEqual` from `fbjs` with the tiny package `fast-deep-equal` for object comparisons in various parts of the lib.
233 |
234 | ## 1.0.0-beta.6
235 |
236 | Fixed the `postActionHook` to work correctly when hitting a cached value.
237 |
238 | ## 0.8.0.alpha-2
239 |
240 | Added `IPullstateInstanceConsumable` as an export to help people who want to create code using the Pullstate stores' instance.
241 |
242 | ## 0.8.0.alpha-1
243 |
244 | Some refactoring of the Async Actions and adding of hooks for much finer grained control:
245 |
246 | `shortCicuitHook()`: Run checks to resolve the action with a response before it even sets out.
247 |
248 | `breakCacheHook()`: When an action's state is being returned from the cache, this hook allows you to run checks on the current cache and your stores to decide whether this action should be run again (essentially flushing / breaking the cache).
249 |
250 | `postActionHook()`: This hook allows you to run some things after the action has resolved, and most importantly allows code to run after each time we hit the cached result of this action as well. This is very useful for interface changes which need to change / update outside of the action code.
251 |
252 | `postActionHook()` is run with a context variable which tells you in which context it was run, one of: CACHE, SHORT_CIRCUIT, DIRECT_RUN
253 |
254 | These hooks should hopefully allow even more boilerplate code to be eliminated while working in asynchronous state scenarios.
255 |
256 | ## 0.7.1
257 |
258 | - Made the `isResolved()` function safe from causing infinite loops (Async Action resolves, but the state of the store still makes `isResolved()` return false which causes a re-trigger when re-rendering - most likely happens when not checking for error states in `isResolved()`) - instead posting an error message to the console informing about the loop which needs to be fixed.
259 |
260 | ## 0.7.0
261 |
262 | **:warning: Replaced with async action hooks above in 0.8.0**
263 |
264 | Added the options of setting an `isResolve()` synchronous checking function on Async Actions. This allows for early escape hatching (we don't need to run this async action based on the current state) and cache busting (even though we ran this Async Action before and we have a cached result, the current state indicates we need to run it again).
265 |
266 | You can set it like so:
267 |
268 | ```typescript jsx
269 | const loadEntity = PullstateCore.createAsyncAction<{ id: string }>(
270 | async ({ id }, { EntityStore }) => {
271 | const resp = await endpoints.getEntity({ id });
272 |
273 | if (resp.positive) {
274 | EntityStore.update((s) => {
275 | s.viewingEntity = resp.payload;
276 | });
277 | return successResult();
278 | }
279 |
280 | return errorResult(resp.endTags, resp.endMessage);
281 | },
282 |
283 | // This second argument is the isResolved() function
284 |
285 | ({ id }, { EntityStore }) => {
286 | const { viewingEntity } = EntityStore.getRawState();
287 |
288 | if (viewingEntity !== null && viewingEntity.id === id) {
289 | return successResult();
290 | }
291 |
292 | return false;
293 | }
294 | );
295 | ```
296 |
297 | It has the same form as the regular Async Action function, injecting the arguments and the stores - but needs to return a synchronous result of either `false` or the expected end result (as if this function would have run asynchronously).
298 |
299 | ## 0.6.0
300 |
301 | - Added "reactions" to store state. Usable like so:
302 |
303 | ```typescript jsx
304 | UIStore.createReaction(
305 | (s) => s.valueToListenForChanges,
306 | (draft, original, watched) => {
307 | // do something here when s.valueToListenForChanges changes
308 | // alter draft as usual - like regular update()
309 | // watched = the value returned from the first function (the selector for what to watch)
310 | }
311 | );
312 | ```
313 |
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
1 | FROM node:8.11.4
2 |
3 | WORKDIR /app/website
4 |
5 | EXPOSE 3000 35729
6 | COPY ./docs /app/docs
7 | COPY ./website /app/website
8 | RUN yarn install
9 |
10 | CMD ["yarn", "start"]
11 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Copyright (c) 2018-present Paul Myburgh and contributors
2 |
3 | Permission is hereby granted, free of charge, to any person obtaining a copy
4 | of this software and associated documentation files (the "Software"), to deal
5 | in the Software without restriction, including without limitation the rights
6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7 | copies of the Software, and to permit persons to whom the Software is
8 | furnished to do so, subject to the following conditions:
9 |
10 | The above copyright notice and this permission notice shall be included in all
11 | copies or substantial portions of the Software.
12 |
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19 | SOFTWARE.
20 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
4 |
5 | ### pullstate
6 |
7 | > Ridiculously simple state stores with performant retrieval anywhere
8 | > in your React tree using the wonderful concept of React hooks!
9 |
10 | * ~7KB minified and gzipped! (excluding Immer and React)
11 | * Built with Typescript, providing a great dev experience if you're using it too
12 | * Uses [immer](https://github.com/mweststrate/immer) for state updates - easily and safely mutate your state directly!
13 | * **NEW** - [Create async actions](https://lostpebble.github.io/pullstate/docs/async-actions-introduction) and use React hooks or `
75 |
Hello Pullstate
76 |
77 | );
78 | };
79 | ```
80 |
81 | The argument to `useState()` over here (`s => s.isDarkMode`), is a selection function that ensures we select only the state that we actually need for this component. This is a big performance booster, as we only listen for changes (and if changed, re-render the component) on the exact returned values - in this case, simply the value of `isDarkMode`.
82 |
83 | ---
84 |
85 | ## Add interaction (update state)
86 |
87 | Great, so we are able to pull our state from `UIStore` into our App. Now lets add some basic interaction with a ``:
88 |
89 | ```tsx
90 | return (
91 |
96 |
Hello Pullstate
97 |
99 | UIStore.update(s => {
100 | s.isDarkMode = !isDarkMode;
101 | })
102 | }>
103 | Toggle Dark Mode
104 |
105 |
106 | );
107 | ```
108 |
109 | Notice how we call `update()` on `UIStore`, inside which we directly mutate the store's state. This is all thanks to the power of `immer`, which you can check out [here](https://github.com/immerjs/immer).
110 |
111 | Another pattern, which helps to illustrate this further, would be to actually define the action of toggling dark mode to a function on its own:
112 |
113 |
114 | ```tsx
115 | function toggleMode(s) {
116 | s.isDarkMode = !s.isDarkMode;
117 | }
118 |
119 | // ...in our code
120 | UIStore.update(toggleMode)}>Toggle Dark Mode
121 | ```
122 |
123 | Basically, to update our app's state all we need to do is create a function (inline arrow function or regular) which takes the current store's state and mutates it to whatever we'd like the next state to be.
124 |
125 | ## Omnipresent state updating
126 |
127 | Something interesting to notice at this point is that we are just importing `UIStore` directly and running `update()` on it:
128 |
129 | ```tsx
130 | import { UIStore } from "./UIStore";
131 |
132 | // ...in our code
133 | UIStore.update(toggleMode)}>Toggle Dark Mode
134 | ```
135 |
136 | And our components are being updated accordingly. We have freed our app's state from the confines of the component! This is one of the main advantages of Pullstate - allowing us to separate our state concerns from being locked in at the component level and manage things easily at a more global level from which our components listen and react (through our `useStoreState()` hooks).
137 |
--------------------------------------------------------------------------------
/docker-compose.yml:
--------------------------------------------------------------------------------
1 | version: "3"
2 |
3 | services:
4 | docusaurus:
5 | build: .
6 | ports:
7 | - 3000:3000
8 | - 35729:35729
9 | volumes:
10 | - ./docs:/app/docs
11 | - ./website/blog:/app/website/blog
12 | - ./website/core:/app/website/core
13 | - ./website/i18n:/app/website/i18n
14 | - ./website/pages:/app/website/pages
15 | - ./website/static:/app/website/static
16 | - ./website/sidebars.json:/app/website/sidebars.json
17 | - ./website/siteConfig.js:/app/website/siteConfig.js
18 | working_dir: /app/website
19 |
--------------------------------------------------------------------------------
/docs/_removed.md:
--------------------------------------------------------------------------------
1 |
2 | ```tsx
3 | // UIStore.ts
4 | import { Store } from "pullstate";
5 |
6 | interface IUIStore {
7 | isDarkMode: boolean;
8 | }
9 |
10 | export const UIStore = new Store({
11 | isDarkMode: true,
12 | });
13 | ```
14 |
15 | Server-rendering requires that we create a central place to reference all our stores, and we do this using `createPullstateCore()`:
16 |
17 | ```tsx
18 | // PullstateCore.ts
19 | import { UIStore } from "./stores/UIStore";
20 | import { createPullstateCore } from "pullstate";
21 |
22 | export const PullstateCore = createPullstateCore({
23 | UIStore
24 | });
25 |
26 | ```
27 |
28 | ---
29 |
30 | For example:
31 |
32 | ```tsx
33 | // a useEffect() hook in our functional component
34 |
35 | useEffect(() => {
36 | const tileLayer = L.tileLayer(tileTemplate.url, {
37 | minZoom: 3,
38 | maxZoom: 18,
39 | }).addTo(mapRef.current);
40 |
41 | const unsubscribeFromTileTemplate = GISStore.createReaction(
42 | s => s.tileLayerTemplate,
43 | newTemplate => {
44 | tileLayer.setUrl(newTemplate.url);
45 | }
46 | );
47 |
48 | return () => {
49 | unsubscribeFromTileTemplate();
50 | };
51 | }, []);
52 | ```
53 |
54 | As you can see we receive a function back from `createReaction()` which we have used here in the "cleanup" return function of `useEffect()` to unsubscribe from this reaction.
55 |
--------------------------------------------------------------------------------
/docs/assets/async-flow.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lostpebble/pullstate/2a4651a8e16f543b484298592cf894c281c98c16/docs/assets/async-flow.png
--------------------------------------------------------------------------------
/docs/async-action-use.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: async-action-use
3 | title: Ways to make use of Async Actions
4 | sidebar_label: Use Async Actions
5 | ---
6 |
7 | *For the sake of being complete in our examples, all possible return states are shown - in real application usage, you might only use a subset of these values.*
8 |
9 | **All examples make use of the previously created Async Action `searchPicturesForTag()`, you can [see more in action creation](async-actions-creating.md).**
10 |
11 | ## Watch an Async Action (React hook)
12 |
13 | ```ts
14 | const [started, finished, result, updating] = searchPicturesForTag.useWatch({ tag }, options);
15 | ```
16 |
17 | * This **React hook** "watches" the action. By watching we mean that we are not initiating this action, but only listening for when this action actually starts through some other means (tracked with `started` here), and then all its states after.
18 | * Possible action states (if `true`):
19 | * `started` : This action has begun its execution.
20 | * `finished`: This action has finished
21 | * `updating`: This is a special action state which can be instigated through `run()`, or when an update triggers and we had passed the option `holdPrevious: true`, which we will see further down.
22 | * `result` is the structured result object you return from your action ([see more in action creation](async-actions-creating.md#what-to-return-from-an-action)).
23 |
24 | `watch()` also takes an options object as the second argument.
25 |
26 | #### Options
27 |
28 | ```ts
29 | {
30 | postActionEnabled?: boolean;
31 | cacheBreakEnabled?: boolean;
32 | holdPrevious?: boolean;
33 | dormant?: boolean;
34 | }
35 | ```
36 |
37 | _(Explained in next paragraph)_
38 |
39 | ## Beckon an Async Action (React hook)
40 |
41 | ```tsx
42 | const [finished, result, updating] = searchPicturesForTag.useBeckon({ tag }, options);
43 | ```
44 |
45 | * Exactly the same as `useWatch()` above, except this time we instigate this action when this hook is first called.
46 |
47 | * Same action states, except for `started` since we are starting this action by default
48 |
49 | `beckon()` also takes an options object as the second argument.
50 |
51 | #### Options
52 |
53 | ```ts
54 | {
55 | postActionEnabled?: boolean;
56 | cacheBreakEnabled?: boolean;
57 | holdPrevious?: boolean;
58 | dormant?: boolean;
59 | ssr?: boolean;
60 | }
61 | ```
62 |
63 | * You can disable the `postActionHook` and / or `cacheBreakHook` for this interaction with this action by using the options here. See more about [`hooks`](async-hooks-overview.md).
64 |
65 | * `holdPrevious` is a special option that allows the result value from this calling of the Async Action to remain in place while we are currently executing the next set of arguments. (e.g. still displaying the previous search results while the system is querying for the next set)
66 |
67 | * `dormant` is a way by which you can basically make Async Actions conditional. If `dormant = true`, then this action will not listen / execute at all.
68 |
69 | ### Ignore `beckon()` for server-rendering
70 |
71 | * If you are server rendering and you would _not_ like a certain Async Action to be instigated on the server (i.e. you are fine with the action resolving itself client-side only), you can pass as an option to beckon `{ ssr: false }`.
72 |
73 | ## (React Suspense) Read an Async Action
74 |
75 | *You can read more about React Suspense on the [React website](https://reactjs.org/docs/concurrent-mode-suspense.html)*
76 |
77 | ```tsx
78 | const PicturesDisplay = ({ tag }) => {
79 | const pictures = searchPicturesForTag.read({ tag });
80 |
81 | // make use of the pictures data here as if it was regular, loaded state
82 | }
83 |
84 | const PicturesPage = () => {
85 | return (
86 | Loading Pictures....}>
87 |
89 | );
90 | }
91 | ```
92 |
93 | You can pass the following options to `read(args, options)`:
94 |
95 | ```ts
96 | interface Options {
97 | postActionEnabled?: boolean;
98 | cacheBreakEnabled?: boolean;
99 | }
100 | ```
101 |
102 | ## Run an Async Action directly
103 |
104 | ```tsx
105 | const result = await searchPicturesForTag.run({ tag });
106 | ```
107 |
108 | * Run's the async action directly, just like a regular promise. Any actions that are currently being watched by means of `useWatch()` will have `started = true` at this moment.
109 |
110 | The return value of `run()` is the action's result object. Generally it is unimportant, and `run()` is mostly used for initiating watched actions, or initiating updates.
111 |
112 | `run()` also takes an optional options object:
113 |
114 | ```jsx
115 | const result = await searchPicturesForTag.run({ tag }, options);
116 | ```
117 |
118 | The structure of the options:
119 |
120 | ```tsx
121 | interface Options {
122 | treatAsUpdate: boolean, // default = false
123 | respectCache: boolean, // default = false
124 | ignoreShortCircuit: boolean, // default = false
125 | }
126 | ```
127 |
128 | #### `treatAsUpdate`
129 |
130 | As seen in the hooks for `useWatch()` and `useBeckon()`, there is an extra return value called `updating` which will be set to `true` if these conditions are met:
131 |
132 | * The action is `run()` with `treatAsUpdate: true` passed as an option.
133 |
134 | * The action has previously completed
135 |
136 | If these conditions are met, then `finished` shall remain `true`, and the current cached result unchanged, and `updating` will now be `true` as well. This allows the edge case of updating your UI to show that updates to the already loaded data are incoming.
137 |
138 | #### `respectCache`
139 |
140 | By default, when you directly `run()` an action, we ignore the cached values and initiate an entire new action run from the beginning. You can think of a `run()` as if we're running our action like we would a regular promise.
141 |
142 | But there are times when you do actually want to hit the cache on a direct run, specifically when you are making use of a [post-action hook](async-post-action-hook.md) - where you just want your run of the action to trigger the relevant UI updates that are associated with this action's result, for example.
143 |
144 | #### `ignoreShortCircuit`
145 |
146 | If set to `true`, will not run the [short circuit hook](async-short-circuit-hook.md) for this run of the action.
147 |
148 | ## `InjectAsyncAction` component
149 |
150 | You could also inject Async Action state directly into your React app without a hook.
151 |
152 | This is particularly useful for things like watching the state of an image loading. If we take this Async Action as an example:
153 |
154 | ```tsx
155 | async function loadImageFully(src: string) {
156 | return new Promise((resolve, reject) => {
157 | let img = new Image();
158 | img.onload = resolve;
159 | img.onerror = reject;
160 | img.src = src;
161 | });
162 | }
163 |
164 | export const AsyncActionImageLoad = createAsyncAction<{ src: string }>(async ({ src }) => {
165 | await loadImageFully(src);
166 | return successResult();
167 | });
168 | ```
169 |
170 | We can inject the async state of loading an image directly into our App using ``:
171 |
172 | ```tsx
173 |
177 | {([finished]) => {
178 | return
186 |
187 | }}
188 |
189 | ```
190 |
191 | We've very quickly made our App have images which will fade in once completely loaded! (You'd probably want to turn this into a component of its own and simply use the hooks - but as an example its fine for now)
192 |
193 | You can make use of the exported `EAsyncActionInjectType` which provides you with `BECKON` or `WATCH` constant variables - or you can provide them as a strings directly `"beckon"` or `"watch"`.
194 |
195 | ## Clear an Async Action's cache
196 |
197 | ```tsx
198 | searchPicturesForTag.clearCache({ tag });
199 | ```
200 |
201 | Clears all known state about this action (specific to the passed arguments).
202 |
203 | * Any action that is still busy resolving will have its results ignored.
204 |
205 | * Any watched actions ( `useWatch()` ) will return to their neutral state (i.e. `started = false`)
206 |
207 | * Any beckoned actions (`useBeckon()`) will have their actions re-instigated anew.
208 |
209 | ## Clear the Async Action cache for *all* argument combinations
210 |
211 | ```tsx
212 | searchPicturesForTag.clearAllCache();
213 | ```
214 |
215 | This is the same as `clearCache()`, except it will clear the cache for every single argument combination (the "fingerprints" we spoke of before) that this action has seen.
216 |
217 | ## Clear the Async Action cache for unwatched argument combinations
218 |
219 | ```tsx
220 | searchPicturesForTag.clearAllUnwatchedCache();
221 | ```
222 |
223 | This will check which argument combinations are not being "watched' in your React app anymore (i.e. usages of `useWatch()` , `useBeckon()` or `Loading Pictures for tag "{props.tag}"
;
63 | }
64 |
65 | if (result.error) {
66 | return {result.message}
;
67 | }
68 |
69 | return (
87 | async ({ tag }) => {
88 | const result = await PictureApi.searchWithTag(tag);
89 |
90 | if (result.success) {
91 | return successResult({ pictures: result.pictures });
92 | }
93 |
94 | return errorResult([], `Couldn't get pictures: ${result.errorMessage}`);
95 | }
96 | );
97 |
98 | export const PictureExample = (props: { tag: string }) => {
99 | const [finished, result] = searchPicturesForTag.useBeckon({ tag: props.tag });
100 |
101 | if (!finished) {
102 | return Loading Pictures for tag "{props.tag}"
;
103 | }
104 |
105 | if (result.error) {
106 | return {result.message}
;
107 | }
108 |
109 | return Loading Pictures for tag "{props.tag}"
;
201 | }
202 |
203 | if (result.error) {
204 | return {result.message}
;
205 | }
206 |
207 | // Inside the Gallery component we will pull our state
208 | // from our stores directly instead of passing it as a prop
209 | return Loading Pictures for tag "{props.tag}"
;
242 | }
243 |
244 | if (result.error) {
245 | return {result.message}
;
246 | }
247 |
248 | // Inside the Gallery component we will pull our state
249 | // from our stores directly instead of passing it as a prop
250 | return ` in your app (server-side rendering).
14 |
15 | It should return `true` or `false`.
16 |
17 | This action will only run if a cached result is found for this action (i.e. this action has completed already in the past). If you return `true`, this will "break" the currently cached value for this action. This action will now run again.
18 |
19 | Be sure to check out the [async hooks flow diagram](async-hooks-overview.md#async-hooks-flow-diagram) to understand better where this hook fits in.
20 |
21 | ## Example of a cache break hook
22 |
23 | _Deciding to not used the cached result from a search API when the search results are more than 30 seconds old_
24 |
25 | ```tsx
26 | const THIRTY_SECONDS = 30 * 1000;
27 |
28 | // The cache break hook in your action creator
29 |
30 | cacheBreakHook: ({ result, timeCached }) =>
31 | !result.error && timeCached + THIRTY_SECONDS < Date.now(),
32 | ```
33 |
34 | In this example want to break the cached result if it is not an error, and the `timeCached` is older than 30 seconds from `Date.now()`. `timeCached` is passed in, and is the millisecond epoch time of when our action last completed.
35 |
36 | You can create customized caching techniques as you see fit. Here we simply check against `timeCached`. Potentially, you might want to check other variables set in your stores, something set on your response payload or even use one of the passed arguments to affect caching length.
37 |
38 | Be sure to check out [the section on cache clearing](async-cache-clearing.md) for other ways to deal with cache invalidation.
39 |
--------------------------------------------------------------------------------
/docs/async-cache-clearing.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: async-cache-clearing
3 | title: Async cache clearing
4 | sidebar_label: Cache clearing
5 | ---
6 |
7 | A big part of working with asynchronous data is being able to control the cache.
8 |
9 | There's even a famous quote for it:
10 |
11 | > _"There are only two hard things in Computer Science: cache invalidation and naming things."_
12 | >
13 | > -**Phil Karlton**
14 |
15 | To try and make at least one of those things a bit easier for you, Pullstate provides a few different ways of dealing with cache invalidation with your async actions.
16 |
17 | ## Direct cache invalidation
18 |
19 | There are three "direct" ways to invalidate the cache for an action:
20 |
21 | ### Clear the cache for specific arguments (fingerprint)
22 |
23 | [See more](async-action-use.md#clear-an-async-action-s-cache)
24 |
25 | ```tsx
26 | GetUserAction.clearCache({ userId });
27 | ```
28 |
29 | ### Clear the cache completely for an action (all combinations of arguments)
30 |
31 | [See more](async-action-use.md#clear-the-async-action-cache-for-all-argument-combinations)
32 |
33 | ```tsx
34 | GetUserAction.clearAllCache();
35 | ```
36 |
37 | ### Clear all unwatched cache for an action
38 |
39 | [See more](async-action-use.md#clear-the-async-action-cache-for-unwatched-argument-combinations)
40 |
41 | ```tsx
42 | GetUserAction.clearAllUnwatchedCache();
43 | ```
44 |
45 | ## Conditional cache invalidation
46 |
47 | There is also a way to check and clear the cache automatically, using something called a `cacheBreakHook` - which runs when an action is called which already has a cached result, and decides whether the current cached result is still worthy. Check out the [async hooks flow diagram](async-hooks-overview.md#async-hooks-flow-diagram) to better understand how this hook fits in.
48 |
49 | ### [Cache Break Hook](async-cache-break-hook.md)
50 |
51 | ```tsx
52 | cacheBreakHook: ({ result, args, timeCached }) => true | false
53 | ```
54 |
--------------------------------------------------------------------------------
/docs/async-hooks-overview.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: async-hooks-overview
3 | title: Async hooks overview
4 | sidebar_label: Hooks overview
5 | ---
6 |
7 | The second argument while creating Async Actions allows us to pass hooks for the action:
8 |
9 | ```tsx
10 | const searchPicturesForTag = createAsyncAction(async ({ tag }) => {
11 | // action code
12 | }, hooksGoHere);
13 | ```
14 |
15 | This `hooksGoHere` object has three hook types which we can set for this action, as follows:
16 |
17 | ```tsx
18 | {
19 | postActionHook,
20 | shortCircuitHook,
21 | cacheBreakHook
22 | }
23 | ```
24 |
25 | ## Async hooks flow diagram
26 |
27 | To try and give you a quick overview of how actions work with hooks, lets look at a top-down flow diagram of an Async Action's execution:
28 |
29 | 
30 |
31 | ## Quick overview of each
32 |
33 | ### `postActionHook({ args, result, stores, context })`
34 |
35 | Post action hook is for consistently running state updates after an action completes for the first time or hits a cached value.
36 |
37 | Read more on the [post action hook](async-post-action-hook.md).
38 |
39 | ### `shortCircuitHook({ args, stores })`
40 |
41 | The short circuit hook is for checking the current state of your app and manually deciding that an action does not actually need to be run, and returning a replacement resolved value yourself.
42 |
43 | Read more on the [short circuit hook](async-short-circuit-hook.md).
44 |
45 | ### `cacheBreakHook({ args, result, stores, timeCached })`
46 |
47 | This hook is run only when an action has already resolve at least once. It takes the currently cached value and decides whether we should "break" the cache and run the action again instead of returning it.
48 |
49 | Read more on the [cache break hook](async-cache-break-hook.md).
50 |
51 | ---
52 |
53 | **NOTE:** In all these hooks, `stores` is only available when you are doing server rendering and you have used your centralized Pullstate "Core" to create your Async Actions, and are making use of `` (see the server-rendering part [Creating an Async Action](async-actions-creating.md)). If you have a client-side only app, just import and use your stores directly.
54 |
--------------------------------------------------------------------------------
/docs/async-post-action-hook.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: async-post-action-hook
3 | title: Post action hook
4 | sidebar_label: Post action hook
5 | ---
6 |
7 | `postActionHook()` is a function which is run directly after your action has completed. **And most importantly**, this is also run after we hit an already resolved and cached value.
8 |
9 | This is useful for updating our app's state (mostly concerning views, organising action results into specific store state that's in the current app's focus) in a consistent manner after actions, whether we hit the cache or directly ran them for the first time.
10 |
11 | Be sure to check out the [async hooks flow diagram](async-hooks-overview.md#async-hooks-flow-diagram) to understand better where this hook fits in.
12 |
13 | ### Updating our regular state stores with Async Action data using `postActionHook`
14 |
15 | `postActionHook` is most often used to synchronise the asynchronous state returned after our Async Actions into our stores.
16 |
17 | Let's quickly look at our previously explored **naive** example from [Creating an Async Action](async-actions-creating.md):
18 |
19 | > If you are not server-rendering you can ignore `PullstateCore` here and create your actions directly with `createAsyncAction()` - you would then also be importing and using your stores directly as opposed to the stores parameter passed inside the action function
20 |
21 | **DO NOT DO THIS!**
22 |
23 | ```tsx
24 | const searchPicturesForTag = PullstateCore.createAsyncAction(async ({ tag }, stores) => {
25 | const result = await PictureApi.searchWithTag(tag);
26 |
27 | if (result.success) {
28 | stores.GalleryStore.update(s => {
29 | s.pictures = result.pictures;
30 | });
31 | return successResult();
32 | }
33 |
34 | return errorResult([], `Couldn't get pictures: ${result.errorMessage}`);
35 | });
36 | ```
37 |
38 | Here we are updating our `GalleryStore` inside the action. The problem with this is that upon hitting a cached value, this action will not be run again ([unless cache broken](async-cache-clearing.md)) - and hence the `pictures` state inside the store will not be replaced with the new pictures.
39 |
40 | In comes `postActionHook` to save the day:
41 |
42 | ```tsx
43 | const searchPicturesForTag = PullstateCore.createAsyncAction(
44 | async ({ tag }) => {
45 | const result = await PictureApi.searchWithTag(tag);
46 |
47 | if (result.success) {
48 | return successResult(result);
49 | }
50 |
51 | return errorResult([], `Couldn't get pictures: ${result.errorMessage}`);
52 | },
53 | {
54 | postActionHook: ({ result, stores }) => {
55 | if (!result.error) {
56 | stores.GalleryStore.update(s => {
57 | s.pictures = result.payload.pictures;
58 | });
59 | }
60 | },
61 | }
62 | );
63 | ```
64 |
65 | > _`stores` here is a server-rendering only argument. For client-side only rendering, import and update your stores directly_
66 |
67 | Notice how we removed the update logic from the action itself and moved it inside the post action hook. Now our state is guaranteed to be updated the same, no matter if we hit the cache or ran the action directly.
68 |
69 | ## API of `postActionHook`:
70 |
71 | ```tsx
72 | postActionHook(inputs) { // Do things with inputs for this async action run };
73 | ```
74 |
75 | `inputs` is the only argument passed to `postActionHook` and has a structure like so:
76 |
77 | ```tsx
78 | {
79 | args, result, stores, context;
80 | }
81 | ```
82 |
83 | > As per all Async Action things, `stores` here is only available as an option if you are making use of `` in your app (server-side rendering).
84 |
85 | - `args` are the arguments for this run of the Async Action
86 | - `result` is the result of the run
87 | - `stores` is an object with all your state stores (**server rendering only**)
88 | - `context` is the context of where this post action hook was run:
89 |
90 | `context` helps us know how we came to be running this post action hook, and allows us to block certain scenarios (and prevent duplicate runs in some scenarios). It all depends on your app and how you make use of async actions.
91 |
92 | `context` will be set to one of the following values:
93 |
94 | - `BECKON_HIT_CACHE`
95 | - Ran after a [`beckon`](async-action-use.md#beckon-an-async-action-react-hook) hit a cached value on this action (triggered after a UI change where old arguments put into `beckon()` again)
96 | - `WATCH_HIT_CACHE`
97 | - Ran after a [`watch`](async-action-use.md#watch-an-async-action-react-hook) hit a cached value on this action (triggered after a UI change where old arguments put into `watch()` again)
98 | - `RUN_HIT_CACHE`
99 | - Ran after we called [`run`](async-action-use.md#run-an-async-action-directly) on this action with `respectCache: true`, and the cache was hit on this action
100 | - `DIRECT_RUN`
101 | - Ran after we called [`run`](async-action-use.md#run-an-async-action-directly) on this action with `respectCache` not set to `true`
102 | - `SHORT_CIRCUIT`
103 | - Ran after the `shortCircuit` hook finished the action pre-maturely
104 | - `BECKON_RUN`
105 | - Ran after a [`beckon`](async-action-use.md#beckon-an-async-action-react-hook) instigated this action for the first time (or after cache break)
106 |
--------------------------------------------------------------------------------
/docs/async-server-rendering.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: async-server-rendering
3 | title: Resolving async state while server-rendering
4 | sidebar_label: Resolve async state on the server
5 | ---
6 |
7 | ## Universal fetching
8 |
9 | Any action that is making use of `useBeckon()` ([discussed in detail here](async-action-use.md)) in the current render tree can have its state resolved on the server before rendering to the client. This allows us to generate dynamic pages on the fly!
10 |
11 | As per our example in ["Creating an Async Action"](async-actions-creating.md)
12 |
13 | ```tsx
14 | // Create the action
15 | const searchPicturesForTag = PullstateCore.createAsyncAction(async ({ tag }) => {
16 | const result = await PictureApi.searchWithTag(tag);
17 |
18 | if (result.success) {
19 | return successResult(result.pictures);
20 | }
21 |
22 | return errorResult([], `Couldn't get pictures: ${result.errorMessage}`);
23 | });
24 |
25 | // Use the action state in our components
26 | export const PictureExample = (props: { tag: string }) => {
27 | const [finished, result] = searchPicturesForTag.useBeckon({ tag: props.tag });
28 |
29 | if (!finished) {
30 | return Loading Pictures for tag "{props.tag}"
;
31 | }
32 |
33 | if (result.error) {
34 | return {result.message}
;
35 | }
36 |
37 | // Inside the Gallery component we will pull our state
38 | // from our stores directly instead of passing it as a prop
39 | return
85 |
87 | )
88 |
89 | let reactHtml = ReactDOMServer.renderToString(app);
90 |
91 | // (2)
92 | while (instance.hasAsyncStateToResolve()) {
93 | await instance.resolveAsyncState();
94 | reactHtml = ReactDOMServer.renderToString(app);
95 | }
96 |
97 | // (3)
98 | const snapshot = instance.getPullstateSnapshot();
99 |
100 | const body = `
101 |
102 | ${reactHtml}`;
103 | ```
104 |
105 | As marked with numbers in the code:
106 |
107 | 1. Place your app into a variable for ease of use. After which, we do our initial rendering as usual - this will register the initial async actions which need to be resolved onto our Pullstate `instance`.
108 |
109 | 2. We enter into a `while()` loop using `instance.hasAsyncStateToResolve()`, which will return `true` unless there is no async state in our React tree to resolve. Inside this loop we immediately resolve all async state with `instance.resolveAsyncState()` before rendering again. This renders our React tree until all state is deeply resolved.
110 |
111 | 3. Once there is no more async state to resolve, we can pull out the snapshot of our Pullstate instance - and we stuff that into our HTML to be hydrated on the client.
112 |
113 | ### Resolve Async Actions outside of render
114 |
115 | If you really wish to avoid the re-rendering, Async Actions are runnable on your Pullstate `instance` directly as well. This will "pre-cache" these action responses and hence not require a re-render (`instance.hasAsyncStateToResolve()` will return false).
116 |
117 | We make use of the following API on our Pullstate instance:
118 |
119 | ```tsx
120 | await pullstateInstance.runAsyncAction(CreatedAsyncAction, args, options);
121 | ```
122 |
123 | The `options` parameter here is the same as that defined on the regular [`run()` method on an action](async-action-use.md#run-an-async-action-directly). The key options being, `ignoreShortCircuit` (default `false`) and `respectCache` (default `false`).
124 |
125 | If you are running actions on the client side again before rendering your app for the first time (perhaps using some kind of isomorphic routing library) - you should be passing the option `{ respectCache: true }` on the client so these actions do not run again.
126 |
127 | This example makes use of `koa` and `koa-router`, we inject our instance onto our request's `ctx.state` early on in the request so we can use it along the way until finally rendering our app.
128 |
129 | Put the Pullstate instance into the current context:
130 |
131 | ```tsx
132 | ServerReactRouter.get("/*", async (ctx, next) => {
133 | ctx.state.pullstateInstance = PullstateCore.instantiate({ ssr: true });
134 | await next();
135 | });
136 | ```
137 |
138 | Create the routes, which run the various required actions:
139 |
140 | ```tsx
141 | ServerReactRouter.get("/list-cron-jobs", async (ctx, next) => {
142 | await ctx.state.pullstateInstance.runAsyncAction(CronJobAsyncActions.getCronJobs, { limit: 30 });
143 | await next();
144 | });
145 |
146 | ServerReactRouter.get("/cron-job-detail/:cronJobId", async (ctx, next) => {
147 | const { cronJobId } = ctx.params;
148 | await ctx.state.pullstateInstance.runAsyncAction(CronJobAsyncActions.loadCronJob, { id: cronJobId });
149 | await next();
150 | });
151 |
152 | ServerReactRouter.get("/edit-cron-job/:cronJobId", async (ctx, next) => {
153 | const { cronJobId } = ctx.params;
154 | await ctx.state.pullstateInstance.runAsyncAction(CronJobAsyncActions.loadCronJob, { id: cronJobId });
155 | await next();
156 | });
157 | ```
158 |
159 | And render the app:
160 |
161 | ```tsx
162 | ServerReactRouter.get("*", async (ctx) => {
163 | const { pullstateInstance } = ctx.state;
164 |
165 | // render React app with pullstate instance
166 |
167 |
169 | ```
170 |
171 | > Even though you are resolving actions outside of the render cycle, **you still need to use** `` as its the only way to provide your pre-run action's state to your app during rendering. If you didn't put that instance into the provider, `useBeckon()` can't see the result and will have queued up another run the regular way (multiple renders required).
172 |
173 | The Async Actions you use on the server and the ones you use on the client are exactly the same - so they are really nice for server-rendered SPAs. Everything just runs and caches as needed.
174 |
175 | You could even pre-cache a few pages on the server at once if you like (depending on how big you want the initial page payload to be), and have instant page changes on the client (and Async Actions has custom [cache busting built in](async-cache-clearing.md) to invalidate async state which is too stale - such as the user taking too long to change the page).
--------------------------------------------------------------------------------
/docs/async-short-circuit-hook.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: async-short-circuit-hook
3 | title: Short circuit hook
4 | sidebar_label: Short circuit hook
5 | ---
6 |
7 | The short circuit hook has the following API:
8 |
9 | ```tsx
10 | shortCircuitHook({ args, stores }) => false | asyncActionResult
11 | ```
12 |
13 | > As per all Async Action things, `stores` here is only available as an option if you are making use of `` in your app (server-side rendering).
14 |
15 | It should either return `false` or an Async Action result.
16 |
17 | If you return an Async Action result, this will effectively "short-circuit" this action. The Promise for this action will not run, and the action will continue from the point directly after that: caching this result, running the [post-action hook](async-post-action-hook.md) and finishing.
18 |
19 | Be sure to check out the [async hooks flow diagram](async-hooks-overview.md#async-hooks-flow-diagram) to understand better where this hook fits in.
20 |
21 | ## Example of short circuit
22 |
23 | _Deciding not to run a search API when the current search term is less than 1 character - return an empty list straight away_
24 |
25 | ```tsx
26 | shortCircuitHook: ({ args }) => {
27 | if (args.text.length <= 1) {
28 | return successResult({ posts: [] });
29 | }
30 |
31 | return false;
32 | },
33 | ```
34 |
35 | In this example, if we have a term that's zero or one character's in length - we short-circuit a `successResult()`, an empty list, instead of wasting our connection on a likely useless query. If the text is 2 or more characters, we continue with the action.
--------------------------------------------------------------------------------
/docs/inject-store-state.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: inject-store-state
3 | title:
4 | sidebar_label:
5 | ---
6 |
7 | The entirety of the code for `` is as follows:
8 |
9 |
10 |
11 | ```jsx
12 | function InjectStoreState({ store, on, children }) {
13 | const state = useStoreState(store, on);
14 | return children(state);
15 | }
16 | ```
17 |
18 |
19 |
20 |
21 | `S` = Store State (entire store's state from which you select)
22 |
23 | `SS` = Sub State (which you are selecting to be returned in the child function):
24 |
25 | ```tsx
26 | interface IPropsInjectStoreState {
27 | store: Store;
28 | on?: (state: S) => SS;
29 | children: (output: SS) => React.ReactElement;
30 | }
31 |
32 | function InjectStoreState({
33 | store,
34 | on = s => s as any,
35 | children,
36 | }: IPropsInjectStoreState): React.ReactElement {
37 | const state: SS = useStoreState(store, on);
38 | return children(state);
39 | }
40 | ```
41 |
42 |
43 |
44 | ## Props
45 |
46 | As you can see from that, the component `` takes 3 props:
47 |
48 | * `store` - the store from which we are selecting the sub-state
49 | * `on` (optional) - a function which selects the sub-state you want from the store's state
50 | * If non provided, selects the entire store's state (not recommended generally, smaller selections result in less re-rendering)
51 | * The required `children` you pass inside the component is simply a function
52 | * The function executes with a single argument, the sub-state which you have selected
53 |
54 | ## Example
55 |
56 | ```tsx
57 | const GreetUser = () => {
58 | return (
59 |
60 | s.userName}>
61 | {userName => Hi, {userName}! }
62 |
63 |
64 | )
65 | }
66 | ```
67 |
--------------------------------------------------------------------------------
/docs/installation.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: installation
3 | title: Installation
4 | sidebar_label: Installation
5 | ---
6 |
7 | Let's get the installation out of the way:
8 |
9 | ```powershell
10 | yarn add pullstate
11 | ```
12 |
--------------------------------------------------------------------------------
/docs/quick-example-server-rendered.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: quick-example-server-rendered
3 | title: Quick example (server rendering)
4 | sidebar_label: Quick example (server rendering)
5 | ---
6 |
9 |
10 | ## Create a state store
11 |
12 | Let's dive right in and define and export our first **state store**, by passing an initial state to `new Store()`:
13 |
14 |
15 |
16 | ```jsx
17 | import { Store } from "pullstate";
18 |
19 | export const UIStore = new Store({
20 | isDarkMode: true,
21 | });
22 | ```
23 |
24 |
25 | ```tsx
26 | import { Store } from "pullstate";
27 |
28 | interface IUIStore {
29 | isDarkMode: boolean;
30 | }
31 |
32 | export const UIStore = new Store({
33 | isDarkMode: true,
34 | });
35 | ```
36 |
37 |
38 |
39 | ## Gather stores under a core collection
40 |
41 | Server-rendering requires that we create a central place to reference all our stores, and we do this using `createPullstateCore()`:
42 |
43 | ```tsx
44 | import { UIStore } from "./stores/UIStore";
45 | import { createPullstateCore } from "pullstate";
46 |
47 | export const PullstateCore = createPullstateCore({
48 | UIStore
49 | });
50 | ```
51 |
52 | In this example we only have a single store, but a regular app should have at least a few.
53 |
54 | ## Read our store's state
55 |
56 | Then, in React, we can start using the state of that store using a simple hook `useState()` on the store.
57 |
58 | For server-rendering we also need to make use of `useStores()` on`PullstateCore`, which we defined above.
59 |
60 | > If we were creating a client-only app, we would simply import `UIStore` directly and use it, but for server-rendering we need to get `UIStore` by calling `useStores()`, which uses React's context to get our unique stores for this render / server request
61 |
62 | ```tsx
63 | import * as React from "react";
64 | import { PullstateCore } from "./PullstateCore";
65 |
66 | export const App = () => {
67 | const { UIStore } = PullstateCore.useStores();
68 | const isDarkMode = UIStore.useState(s => s.isDarkMode);
69 |
70 | return (
71 |
76 |
Hello Pullstate
77 |
78 | );
79 | };
80 | ```
81 |
82 | The second argument to `useState()` over here (`s => s.isDarkMode`), is a selection function that ensures we select only the state that we actually need for this component. This is a big performance booster, as we only listen for changes (and if changed, re-render the component) on the exact returned values - in this case, simply the value of `isDarkMode`.
83 |
84 | If you are not using TypeScript, or want to forgo nice types, you could also pull in your store's using `useStores()` imported directly from `pullstate`:
85 |
86 | ```tsx
87 | import { useStores } from "pullstate";
88 |
89 | // in app component
90 | const { UIStore } = useStores();
91 | const isDarkMode = UIStore.useState(s => s.isDarkMode);
92 | ```
93 |
94 | ---
95 |
96 | ## Add interaction (update state)
97 |
98 | Great, so we are able to pull our state from `UIStore` into our App. Now lets add some basic interaction with a ``:
99 |
100 | ```tsx
101 | const { UIStore } = PullstateCore.useStores();
102 | const isDarkMode = UIStore.useState(s => s.isDarkMode);
103 |
104 | return (
105 |
110 |
Hello Pullstate
111 |
113 | UIStore.update(s => {
114 | s.isDarkMode = !isDarkMode;
115 | })
116 | }>
117 | Toggle Dark Mode
118 |
119 |
120 | );
121 | ```
122 |
123 | Notice how we call `update()` on `UIStore`, inside which we directly mutate the store's state. This is all thanks to the power of `immer`, which you can check out [here](https://github.com/immerjs/immer).
124 |
125 | Another pattern, which helps to illustrate this further, would be to actually define the action of toggling dark mode to a function on its own:
126 |
127 |
128 |
129 | ```tsx
130 | function toggleMode(s) {
131 | s.isDarkMode = !s.isDarkMode;
132 | }
133 |
134 | // ...in our code
135 | UIStore.update(toggleMode)}>Toggle Dark Mode
136 | ```
137 |
138 |
139 | ```tsx
140 | function toggleMode(s: IUIStore) {
141 | s.isDarkMode = !s.isDarkMode;
142 | }
143 |
144 | // ...in our code
145 | UIStore.update(toggleMode)}>Toggle Dark Mode
146 | ```
147 |
148 |
149 |
150 | Basically, to update our app's state all we need to do is create a function (inline arrow function or regular) which takes the current store's state and mutates it to whatever we'd like the next state to be.
151 |
152 | ## Server-rendering our app
153 |
154 | When server rendering we need to wrap our app with `` which is a context provider that passes down fresh stores to be used on each new client request. We get these fresh stores from our `PullstateCore` above, by calling `instantiate({ ssr: true })` on it:
155 |
156 | ```tsx
157 | import { PullstateCore } from "./state/PullstateCore";
158 | import ReactDOMServer from "react-dom/server";
159 | import { PullstateProvider } from "pullstate";
160 |
161 | // A server request
162 | async function someRequest(req) {
163 | const instance = PullstateCore.instantiate({ ssr: true });
164 |
165 | const preferences = await UserApi.getUserPreferences(id);
166 |
167 | instance.stores.UIStore.update(s => {
168 | s.isDarkMode = preferences.isDarkMode;
169 | });
170 |
171 | const reactHtml = ReactDOMServer.renderToString(
172 |
173 |
175 | );
176 |
177 | const body = `
178 |
179 | ${reactHtml}`;
180 |
181 | // do something with the generated html and send response
182 | }
183 | ```
184 |
185 | * Manipulate your state directly during your server's request by using the `stores` property of the instantiated object
186 |
187 | * Notice that we pass our Pullstate core instance into `` as `instance`
188 |
189 | * Lastly, we need to return this state to the client somehow. We call `getPullstateSnapshot()` on the instance, stringify it, escape a couple characters, and set it on `window.__PULLSTATE__`, to be parsed and hydrated on the client.
190 |
191 | ### Quick note
192 |
193 | This kind of code (pulling asynchronous state into your stores on the server and client):
194 |
195 | ```tsx
196 | const preferences = await UserApi.getUserPreferences(id);
197 |
198 | instance.stores.UIStore.update(s => {
199 | s.isDarkMode = preferences.isDarkMode;
200 | });
201 | ```
202 |
203 | Can be conceptually made much easier using Pullstate's [Async Actions](async-actions-introduction.md)!
204 |
205 | ## Client-side state hydration
206 |
207 | ```tsx
208 | const hydrateSnapshot = JSON.parse(window.__PULLSTATE__);
209 |
210 | const instance = PullstateCore.instantiate({ ssr: false, hydrateSnapshot });
211 |
212 | ReactDOM.render(
213 |
214 | ,
216 | document.getElementById("react-mount")
217 | );
218 | ```
219 |
220 | We create a new instance on the client using the same method as on the server, except this time we can pass the `hydrateSnapshot` and `ssr: false`, which will instantiate our new stores with the state where our server left off.
221 |
222 | ## Client-side only updates
223 |
224 | Something interesting to notice at this point, which can also apply with server-rendered apps, is that (for client-side only updates) we could just import `UIStore` directly and run `update()` on it:
225 |
226 | ```tsx
227 | import { UIStore } from "./UIStore";
228 |
229 | // ...in our code
230 | UIStore.update(toggleMode)}>Toggle Dark Mode
231 | ```
232 | And our components would be updated accordingly. We have freed our app's state from the confines of the component! This is one of the main advantages of Pullstate - allowing us to separate our state concerns from being locked in at the component level and manage things easily at a more global level from which our components listen and react (through our `useStoreState()` hooks).
233 |
234 | We still need to make use of the `PullstateCore.useStores()` hook and `` in order to pick up and render server-side updates and state, but once we have hydrated that state into our stores on the client side, we can interact with Pullstate stores just as we would if it were a client-only app - **but we must be sure that these actions are 100% client-side only**.
235 |
--------------------------------------------------------------------------------
/docs/quick-example.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: quick-example
3 | title: Quick example
4 | sidebar_label: Quick example
5 | ---
6 |
9 |
10 | ## Create a state store
11 |
12 | Let's dive right in and define and export our first **state store**, by passing an initial state to `new Store()`:
13 |
14 |
15 |
16 | ```jsx
17 | import { Store } from "pullstate";
18 |
19 | export const UIStore = new Store({
20 | isDarkMode: true,
21 | });
22 | ```
23 |
24 |
25 | ```tsx
26 | import { Store } from "pullstate";
27 |
28 | interface IUIStore {
29 | isDarkMode: boolean;
30 | }
31 |
32 | export const UIStore = new Store({
33 | isDarkMode: true,
34 | });
35 | ```
36 |
37 |
38 |
39 | ## Read our store's state
40 |
41 | Then, in React, we can start using the state of that store using a simple hook `useState()` on the store iteself:
42 |
43 | ```tsx
44 | import * as React from "react";
45 | import { UIStore } from "./UIStore";
46 |
47 | export const App = () => {
48 | const isDarkMode = UIStore.useState(s => s.isDarkMode);
49 |
50 | return (
51 |
56 |
Hello Pullstate
57 |
58 | );
59 | };
60 | ```
61 |
62 | The argument to `useState()` over here (`s => s.isDarkMode`), is a selection function that ensures we select only the state that we actually need for this component. This is a big performance booster, as we only listen for changes (and if changed, re-render the component) on the exact returned values - in this case, simply the value of `isDarkMode`.
63 |
64 | ---
65 |
66 | ## Add interaction (update state)
67 |
68 | Great, so we are able to pull our state from `UIStore` into our App. Now lets add some basic interaction with a ``:
69 |
70 | ```tsx
71 | return (
72 |
77 |
Hello Pullstate
78 |
80 | UIStore.update(s => {
81 | s.isDarkMode = !isDarkMode;
82 | })
83 | }>
84 | Toggle Dark Mode
85 |
86 |
87 | );
88 | ```
89 |
90 | Notice how we call `update()` on `UIStore`, inside which we directly mutate the store's state. This is all thanks to the power of `immer`, which you can check out [here](https://github.com/immerjs/immer).
91 |
92 | Another pattern, which helps to illustrate this further, would be to actually define the action of toggling dark mode to a function on its own:
93 |
94 |
95 |
96 | ```tsx
97 | function toggleMode(s) {
98 | s.isDarkMode = !s.isDarkMode;
99 | }
100 |
101 | // ...in our code
102 | UIStore.update(toggleMode)}>Toggle Dark Mode
103 | ```
104 |
105 |
106 | ```tsx
107 | function toggleMode(s: IUIStore) {
108 | s.isDarkMode = !s.isDarkMode;
109 | }
110 |
111 | // ...in our code
112 | UIStore.update(toggleMode)}>Toggle Dark Mode
113 | ```
114 |
115 |
116 |
117 | Basically, to update our app's state all we need to do is create a function (inline arrow function or regular) which takes the current store's state and mutates it to whatever we'd like the next state to be.
118 |
119 | ## Omnipresent state updating
120 |
121 | Something interesting to notice at this point is that we are just importing `UIStore` directly and running `update()` on it:
122 |
123 | ```tsx
124 | import { UIStore } from "./UIStore";
125 |
126 | // ...in our code
127 | UIStore.update(toggleMode)}>Toggle Dark Mode
128 | ```
129 |
130 | And our components are being updated accordingly. We have freed our app's state from the confines of the component! This is one of the main advantages of Pullstate - allowing us to separate our state concerns from being locked in at the component level and manage things easily at a more global level from which our components listen and react (through our `useState()` hooks).
131 |
--------------------------------------------------------------------------------
/docs/reactions.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: reactions
3 | title: Reactions
4 | sidebar_label: Reactions
5 | ---
6 |
7 | A reaction is very similar to running an `update()`, except that it's an update that runs when a certain value has changed in your store.
8 |
9 | Their API is very similar to [Subscriptions](subscribe.md) in the way they watch values, the difference being that Reactions allow you to react and change your store's state at the same time in a "batched" way. Subscriptions only send you the new values. The reason these two are separated is for performance reasons - if you do not need to react and change your store's state on an update, rather use [subscriptions](subscribe.md).
10 |
11 | Reactions on a store are run directly after a call to `update()` on that store. They check their watched value in the store, and if changed, react with further state updates as you define. This is all batched in one go before notifying our React components to re-render as needed.
12 |
13 | ## Creating a reaction
14 |
15 | You register a reaction by calling `createReaction()` on your store:
16 |
17 |
18 |
19 | ```jsx
20 | StoreName.createReaction(watch, reaction);
21 | ```
22 |
23 |
24 | ```tsx
25 | type TReactionFunction = (watched: T, draft: S, original: S, lastWatched: T) => void;
26 |
27 | StoreName.createReaction(watch: (state: S) => T, reaction: TReactionFunction): () => void
28 | ```
29 |
30 |
31 |
32 | Similar to how we select sub-state with `useStoreState()` and ``, the first argument, `watch`, is function which returns a sub-selection of the store's state. This is the value we will be watching for changes:
33 |
34 | ```
35 | storeState => storeState.watchedValue;
36 | ```
37 |
38 | The watched value is checked every time the store is updated. If the value has changed, the `reaction` function is run. This is done in a performant way - reactions are run directly after updates before notifying your React components to update.
39 |
40 | The `reaction` function:
41 |
42 | ```jsx
43 | (watched, draft, original, lastWatched) => { //do things };
44 | ```
45 |
46 | The new watched value will be passed as the first argument,`watched`
47 |
48 | The next two arguments are the same as those used whe running `update()` on a store:
49 |
50 | * You can mutate your store directly, using `draft`
51 |
52 | * `original` is passed as a performance consideration. It is exactly the same as `draft` but without all the `immer` magic. It's a plain object of your state.
53 | * **Why?** Referencing values directly on your `draft` object can be a performance hit in certain situations because of the way that immer works internally (JavaScript proxies) - so if you need to _reference_ the current store state, you should use `original`. But if you want to _change_ it, you use `draft`. [Read more in immer's docs](https://immerjs.github.io/immer/performance#for-expensive-search-operations-read-from-the-original-state-not-the-draft).
54 |
55 | The last argument is the last watched value, passed as a convenience for if you ever need to refer to it.
56 |
57 | ## Example
58 |
59 | Listening to a [Cron Tab](https://en.wikipedia.org/wiki/Cron#Overview) string value, `crontab`, and calculating other values such as a human readable time and the previous and next dates of the cron run:
60 |
61 | ```tsx
62 | CronJobStore.createReaction(s => s.crontab, (crontab, draft) => {
63 | if (crontab !== null) {
64 | const resp = utils.getTimesAndTextFromCronTab({ crontab });
65 | if (resp.positive) {
66 | draft.currentCronJobTimesAndText = resp.payload;
67 | } else {
68 | draft.currentCronJobTimesAndText = {
69 | text: `Bad crontab`,
70 | times: {
71 | prevTime: null,
72 | nextTime: null,
73 | },
74 | };
75 | }
76 | } else {
77 | draft.currentCronJobTimesAndText = {
78 | times: {
79 | prevTime: null,
80 | nextTime: null,
81 | },
82 | text: `No crontab`,
83 | };
84 | }
85 | }
86 | );
87 | ```
88 |
89 | ## Unsubscribe from a reaction (client-side only)
90 |
91 | You may unsubscribe from a reaction on the client side of your app by simply running the function which is returned when you created the reaction.
92 |
--------------------------------------------------------------------------------
/docs/redux-dev-tools.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: redux-dev-tools
3 | title: Redux Devtools
4 | sidebar_label: Redux Devtools
5 | ---
6 |
7 | Pullstate includes a simple way to plug into Redux's devtools, which are already well established and extensive.
8 |
9 | Simply include the following somewhere after your Store definitions:
10 |
11 | ```ts
12 | import { registerInDevtools, Store } from "pullstate";
13 |
14 | // Store definition
15 | const ExampleStore = new Store({
16 | //...
17 | });
18 |
19 | // Register as many or as few Stores as you would like to monitor in the devtools
20 | registerInDevtools({
21 | ExampleStore,
22 | });
23 | ```
24 |
25 | After this, you should be able to open the Redux devtools tab and see each Store registered and showing changes.
26 |
--------------------------------------------------------------------------------
/docs/subscribe.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: subscribe
3 | title: Subscribe
4 | sidebar_label: Subscribe
5 | ---
6 |
7 | Subscriptions are client-side only listeners to changes in your store's state.
8 |
9 | They are very similar to [Reactions](reactions.md), the difference being they only listen for state changes and send you the new state. Reactions allow you to react and change your store's state at the same time in a "batched" way. **Subscriptions only send you the new values.** The reason these two are separated is for performance reasons - if you do not need to react and change your store's state on an update, rather use subscriptions.
10 |
11 | Some uses include integrating with third-party tools, for times when you want to align your app's state changes with a change in the tool as well.
12 |
13 | ## Subscribe API
14 |
15 | ```tsx
16 | myStore.subscribe(watch, listener) => unsubscribe
17 | ```
18 |
19 | **First** argument `watch` - a function which selects the state you'd like to watch for changes:
20 |
21 | ```
22 | storeState => storeState.valueToWatch;
23 | ```
24 |
25 | **Second** argument `listener` - a callback function which is run when the watched value changes. The new watched value will be the first argument, and the entire store's state is the second. The third argument is the last watched value, passed as a convenience for if you ever need to refer to it.
26 |
27 | ```jsx
28 | (watched, allState, prevWatched) => { //do things };
29 | ```
30 |
31 | **Return** value `unsubscribe` is simply a function you can run in order to stop listening.
32 |
33 | ## Subscribe Examples
34 |
35 | ### Leaflet tile change
36 |
37 | _(Listening for an option change in our store to update a Leaflet tile layer's source)_
38 |
39 | ```tsx
40 | // a useEffect() hook in a functional component
41 |
42 | useEffect(() => {
43 | const tileLayer = L.tileLayer(tileTemplate.url, {
44 | minZoom: 3,
45 | maxZoom: 18,
46 | }).addTo(mapRef.current);
47 |
48 | const unsubscribeFromTileTemplate = GISStore.subscribe(
49 | s => s.tileLayerTemplate,
50 | newTemplate => {
51 | tileLayer.setUrl(newTemplate.url);
52 | }
53 | );
54 |
55 | return () => {
56 | unsubscribeFromTileTemplate();
57 | };
58 | }, []);
59 | ```
60 |
61 | As you can see from the example, we listen to the `tileLayerTemplate` value in `GISStore`. If that changes, we want to set our Leaflet `tileLayer` to the new url, which will change the source of images used for our map's tiles.
62 |
63 | Also note that the value returned from `subscribe()` is a function. We should call this function to remove the listener when we don't need it anymore - here in the "cleanup" returned function of `useEffect()`.
64 |
65 | ---
66 |
67 | ### Firebase Realtime Database
68 |
69 | Another interesting use-case could be subscribing to a Firebase realtime data node, based on a certain value in your store.
70 |
71 | ```tsx
72 | let previousCityUnsubscribe = () => null;
73 |
74 | function startWatchingCity(cityCode) {
75 | return db.collection("cities")
76 | .doc(cityCode)
77 | .onSnapshot(function(doc) {
78 | CityStore.update(s => {
79 | s.watchedCities[cityCode] = { updated: new Date(), data: doc.data() };
80 | });
81 | });
82 | }
83 |
84 | function getRealtimeUpdatesForCityCode(cityCode) {
85 | previousCityUnsubscribe();
86 | previousCityUnsubscribe = startWatchingCity(cityCode);
87 | }
88 |
89 | CityStore.subscribe(s => s.currentCityCode, getRealtimeUpdatesForCityCode);
90 |
91 | // inside some initialization code on the client (run after initial
92 | // store hydration, if any), start watching initial city
93 | function initializeClientThings() {
94 | getRealtimeUpdatesForCityCode(CityStore.getRawState().currentCityCode);
95 | }
96 | ```
97 |
98 | And now, any time you run an update somewhere in your app:
99 | ```tsx
100 | CityStore.update(s => {
101 | s.currentCityCode = newCode;
102 | })
103 | ```
104 |
105 | If the value has actually changed, the current realtime database listener should be unsubscribed and a new one created with the new `currentCityCode`.
--------------------------------------------------------------------------------
/docs/update-store.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: update-store
3 | title: update()
4 | sidebar_label: update()
5 | ---
6 |
7 | You can update your store's state by calling `update()` directly on your store with an updater function passed in:
8 |
9 | ```tsx
10 | MyStore.update(updater | updater[])
11 | ```
12 |
13 | The updater function is simply a function which takes the store's current state and allows you to mutate it directly to create the next state. This is thanks to the power of [immer](https://github.com/immerjs/immer).
14 |
15 | Notice here that you can also pass multiple updater functions to `update()`. This allows us to be more modular with our store updates, and combine different updates together in a single batch.
16 |
17 | ### patches callback
18 |
19 | ```tsx
20 | MyStore.update(updater | updater[], patches)
21 | ```
22 |
23 | An optional second argument to `update()` is a patch callback - this is a very useful API provided by `immer`, and since `update()` is pretty much just a wrapper around Immer's functionality, we provide a way for you to make use of it in your Pullstate updates too. Read more about patches in `immer` docs, [here](https://github.com/immerjs/immer#patches).
24 |
25 | Patches allow fun things such as undo / redo functionality and state time travel!
26 |
27 | ## Example for update()
28 |
29 | Add some basic interaction to your app with a ``:
30 |
31 | ```tsx
32 | return (
33 |
38 |
Hello Pullstate
39 |
41 | UIStore.update(s => {
42 | s.isDarkMode = !isDarkMode;
43 | })
44 | }>
45 | Toggle Dark Mode
46 |
47 |
48 | );
49 | ```
50 |
51 | Notice how we call `update()` on `UIStore` and pass the updater function in.
52 |
53 | Another pattern, which helps to illustrate this further, would be to actually define the action of toggling dark mode to a function on its own:
54 |
55 | ```tsx
56 | function toggleMode(s) {
57 | s.isDarkMode = !s.isDarkMode;
58 | }
59 |
60 | // ...in our code
61 | UIStore.update(toggleMode)}>Toggle Dark Mode
62 | ```
63 |
64 | Basically, to update our store's state all we need to do is create a function (inline arrow function or regular) which takes the current store's state and mutates it to whatever we'd like the next state to be.
65 |
66 | ## Example with Multiple Updaters
67 |
68 | As mentioned above, the `update()` method also allows you to pass in an array of multiple updaters. Allowing you to batch multiple, more modular, updates to your store:
69 |
70 | ```ts
71 | UIStore.update([setDarkMode, setTypography("Roboto)]);
72 | ```
73 |
--------------------------------------------------------------------------------
/docs/use-store-state-hook.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: use-store-state-hook
3 | title: useStoreState (hook)
4 | sidebar_label: useStoreState (hook)
5 | ---
6 |
7 | > **NB** This code can all be used in a slightly different (and perhaps more readable) way, with `YourStore.useState()`. It functions exactly the same as the methods below, except without the first `store` parameter (since we are already calling it on the store itself).
8 |
9 | The `useStoreState()` hook to be used in your functional components has the following API interface:
10 |
11 |
12 |
13 | ```jsx
14 | function useStoreState(store);
15 | function useStoreState(store, getSubState);
16 | function useStoreState(store, getSubState, dependencies);
17 | ```
18 |
19 |
20 | ```tsx
21 | function useStoreState(store: Store): S;
22 | function useStoreState(store: Store, getSubState: (state: S) => SS): SS;
23 | function useStoreState(store: Store, getSubState: (state: S) => SS, deps?: ReadonlyArray): SS;
24 | ```
25 |
26 | * `S` here is an interface that represents your entire store's state
27 | * `SS` is an interface which represents a selected sub-state from your store
28 |
29 |
30 |
31 | Let's go through each way of using it:
32 |
33 | ## Use a store's entire state
34 |
35 | Example:
36 |
37 | ```tsx
38 | const allUIState = useStoreState(UIStore);
39 |
40 | return (allUIState.isDarkMode ? {
17 | action: IOCreateAsyncActionOutput;
18 | args?: A;
19 | }
20 |
21 | export interface IPropsInjectAsyncActionBeckon
22 | extends IPropsInjectAsyncActionBase {
23 | type: EAsyncActionInjectType.BECKON;
24 | options?: IAsyncActionBeckonOptions;
25 | children: (response: TPullstateAsyncBeckonResponse) => React.ReactElement;
26 | }
27 |
28 | export interface IPropsInjectAsyncActionWatch
29 | extends IPropsInjectAsyncActionBase {
30 | type: EAsyncActionInjectType.WATCH;
31 | children: (response: TPullstateAsyncWatchResponse) => React.ReactElement;
32 | options?: IAsyncActionWatchOptions;
33 | }
34 |
35 | export type TInjectAsyncActionProps = IPropsInjectAsyncActionBeckon | IPropsInjectAsyncActionWatch;
36 |
37 | export function InjectAsyncAction(
38 | props: TInjectAsyncActionProps
39 | ): React.ReactElement {
40 | if (props.type === EAsyncActionInjectType.BECKON) {
41 | const response = props.action.useBeckon(props.args, props.options);
42 | return props.children(response);
43 | }
44 |
45 | const response = props.action.useWatch(props.args, props.options);
46 | return props.children(response);
47 | }
48 |
--------------------------------------------------------------------------------
/src/InjectStoreState.ts:
--------------------------------------------------------------------------------
1 | import React from "react";
2 | import { Store } from "./Store";
3 | import { useStoreState } from "./useStoreState";
4 |
5 | export interface IPropsInjectStoreState {
6 | store: Store;
7 | on?: (state: S) => SS;
8 | children: (output: SS) => React.ReactElement;
9 | }
10 |
11 | export function InjectStoreState({
12 | store,
13 | on = s => s as any,
14 | children,
15 | }: IPropsInjectStoreState): React.ReactElement {
16 | const state: SS = useStoreState(store, on);
17 | return children(state);
18 | }
19 |
--------------------------------------------------------------------------------
/src/InjectStoreStateOpt.ts:
--------------------------------------------------------------------------------
1 | import React from "react";
2 | import { Store } from "./Store";
3 | import { useStoreStateOpt } from "./useStoreStateOpt";
4 | import { ObjectPath } from "./useStoreStateOpt-types";
5 | import type { GetWithPath } from "type-fest/get";
6 |
7 | export interface IPropsInjectStoreStateOpt<
8 | T extends readonly unknown[],
9 | S extends object = object,
10 | P extends ObjectPath = T extends ObjectPath ? T : never
11 | > {
12 | store: Store;
13 | paths: P;
14 | children: (output: GetWithPath) => React.ReactElement;
15 | }
16 |
17 | /*
18 | import { DeepTypeOfArray, TAllPathsParameter } from "./useStoreStateOpt-types";
19 |
20 | export interface IPropsInjectStoreStateOpt<
21 | S extends object = object,
22 | P extends TAllPathsParameter = TAllPathsParameter,
23 | O extends [
24 | DeepTypeOfArray,
25 | DeepTypeOfArray,
26 | DeepTypeOfArray,
27 | DeepTypeOfArray,
28 | DeepTypeOfArray,
29 | DeepTypeOfArray,
30 | DeepTypeOfArray,
31 | DeepTypeOfArray,
32 | DeepTypeOfArray,
33 | DeepTypeOfArray,
34 | DeepTypeOfArray
35 | ] = [
36 | DeepTypeOfArray,
37 | DeepTypeOfArray,
38 | DeepTypeOfArray,
39 | DeepTypeOfArray,
40 | DeepTypeOfArray,
41 | DeepTypeOfArray,
42 | DeepTypeOfArray,
43 | DeepTypeOfArray,
44 | DeepTypeOfArray,
45 | DeepTypeOfArray,
46 | DeepTypeOfArray
47 | ]
48 | > {
49 | store: Store;
50 | paths: P;
51 | children: (output: O) => React.ReactElement;
52 | }*/
53 |
54 | export function InjectStoreStateOpt<
55 | T extends readonly unknown[],
56 | S extends object = object,
57 | P extends ObjectPath = T extends ObjectPath ? T : never
58 | >({ store, paths, children }: IPropsInjectStoreStateOpt): React.ReactElement {
59 | const state = useStoreStateOpt(store, paths) as GetWithPath;
60 | return children(state);
61 | }
62 |
--------------------------------------------------------------------------------
/src/PullstateCore.tsx:
--------------------------------------------------------------------------------
1 | import React, { useContext } from "react";
2 | import { Store, TUpdateFunction } from "./Store";
3 | import { clientAsyncCache, createAsyncAction, createAsyncActionDirect } from "./async";
4 | import {
5 | IAsyncActionRunOptions,
6 | ICreateAsyncActionOptions,
7 | IOCreateAsyncActionOutput,
8 | IPullstateAsyncActionOrdState,
9 | IPullstateAsyncCache,
10 | IPullstateAsyncResultState,
11 | TPullstateAsyncAction,
12 | TPullstateAsyncRunResponse
13 | } from "./async-types";
14 |
15 | export interface IPullstateAllStores {
16 | [storeName: string]: Store;
17 | }
18 |
19 | export const PullstateContext = React.createContext | null>(null);
20 |
21 | export const PullstateProvider = (
22 | {
23 | instance,
24 | children
25 | }: {
26 | instance: PullstateInstance;
27 | children?: any;
28 | }) => {
29 | return {children} ;
30 | };
31 |
32 | let singleton: PullstateSingleton | null = null;
33 |
34 | export const clientStores: {
35 | internalClientStores: true;
36 | stores: IPullstateAllStores;
37 | loaded: boolean;
38 | } = {
39 | internalClientStores: true,
40 | loaded: false,
41 | stores: {}
42 | };
43 |
44 | export type TMultiStoreAction,
45 | S extends IPullstateAllStores = P extends PullstateSingleton ? ST : any> = (update: TMultiStoreUpdateMap) => void;
46 |
47 | interface IPullstateSingletonOptions {
48 | asyncActions?: {
49 | defaultCachingSeconds?: number;
50 | };
51 | }
52 |
53 | export class PullstateSingleton {
54 | // private readonly originStores: S = {} as S;
55 | // private updatedStoresInAct = new Set();
56 | // private actUpdateMap: TMultiStoreUpdateMap | undefined;
57 | options: IPullstateSingletonOptions = {};
58 |
59 | constructor(allStores: S, options: IPullstateSingletonOptions = {}) {
60 | if (singleton !== null) {
61 | console.error(
62 | `Pullstate: createPullstate() - Should not be creating the core Pullstate class more than once! In order to re-use pull state, you need to call instantiate() on your already created object.`
63 | );
64 | }
65 |
66 | singleton = this;
67 | // this.originStores = allStores;
68 | clientStores.stores = allStores;
69 | clientStores.loaded = true;
70 | this.options = options;
71 | }
72 |
73 | instantiate(
74 | {
75 | hydrateSnapshot,
76 | ssr = false,
77 | customContext
78 | }: { hydrateSnapshot?: IPullstateSnapshot; ssr?: boolean, customContext?: any } = {}): PullstateInstance {
79 | if (!ssr) {
80 | const instantiated = new PullstateInstance(clientStores.stores as S, false, customContext);
81 |
82 | if (hydrateSnapshot != null) {
83 | instantiated.hydrateFromSnapshot(hydrateSnapshot);
84 | }
85 |
86 | instantiated.instantiateReactions();
87 | return instantiated as PullstateInstance;
88 | }
89 |
90 | const newStores: IPullstateAllStores = {};
91 |
92 | for (const storeName of Object.keys(clientStores.stores)) {
93 | if (hydrateSnapshot == null) {
94 | newStores[storeName] = new Store(clientStores.stores[storeName]._getInitialState());
95 | } else if (hydrateSnapshot.hasOwnProperty(storeName)) {
96 | newStores[storeName] = new Store(hydrateSnapshot.allState[storeName]);
97 | } else {
98 | newStores[storeName] = new Store(clientStores.stores[storeName]._getInitialState());
99 | console.warn(
100 | `Pullstate (instantiate): store [${storeName}] didn't hydrate any state (data was non-existent on hydration object)`
101 | );
102 | }
103 |
104 | newStores[storeName]._setInternalOptions({
105 | ssr,
106 | reactionCreators: clientStores.stores[storeName]._getReactionCreators()
107 | });
108 | }
109 |
110 | return new PullstateInstance(newStores as S, true, customContext);
111 | }
112 |
113 | useStores(): S {
114 | // return useContext(PullstateContext)!.stores as S;
115 | return useStores();
116 | }
117 |
118 | useInstance(): PullstateInstance {
119 | return useInstance();
120 | }
121 |
122 | /*actionSetup(): {
123 | action: (update: TMultiStoreAction, S>) => TMultiStoreAction, S>;
124 | act: (action: TMultiStoreAction, S>) => void;
125 | // act: (action: (update: TMultiStoreUpdateMap) => void) => void;
126 | } {
127 | const actUpdateMap = {} as TMultiStoreUpdateMap;
128 | const updatedStores = new Set();
129 |
130 | for (const store of Object.keys(clientStores.stores)) {
131 | actUpdateMap[store as keyof S] = (updater) => {
132 | updatedStores.add(store);
133 | clientStores.stores[store].batch(updater);
134 | };
135 | }
136 |
137 | const action: (
138 | update: TMultiStoreAction, S>
139 | ) => TMultiStoreAction, S> = (action) => action;
140 | const act = (action: TMultiStoreAction, S>): void => {
141 | updatedStores.clear();
142 | action(actUpdateMap);
143 | for (const store of updatedStores) {
144 | clientStores.stores[store].flushBatch(true);
145 | }
146 | };
147 |
148 | return {
149 | action,
150 | act,
151 | };
152 | }*/
153 |
154 | createAsyncActionDirect(
155 | action: (args: A) => Promise,
156 | options: ICreateAsyncActionOptions = {}
157 | ): IOCreateAsyncActionOutput {
158 | return createAsyncActionDirect(action, options);
159 | // return createAsyncAction(async (args: A) => {
160 | // return successResult(await action(args));
161 | // }, options);
162 | }
163 |
164 | createAsyncAction(
165 | action: TPullstateAsyncAction,
166 | // options: Omit, "clientStores"> = {}
167 | options: ICreateAsyncActionOptions = {}
168 | ): IOCreateAsyncActionOutput {
169 | // options.clientStores = this.originStores;
170 | if (this.options.asyncActions?.defaultCachingSeconds && !options.cacheBreakHook) {
171 | options.cacheBreakHook = (inputs) =>
172 | inputs.timeCached < Date.now() - this.options.asyncActions!.defaultCachingSeconds! * 1000;
173 | }
174 |
175 | return createAsyncAction(action, options);
176 | }
177 | }
178 |
179 | type TMultiStoreUpdateMap = {
180 | [K in keyof S]: (updater: TUpdateFunction ? T : any>) => void;
181 | };
182 |
183 | interface IPullstateSnapshot {
184 | allState: { [storeName: string]: any };
185 | asyncResults: IPullstateAsyncResultState;
186 | asyncActionOrd: IPullstateAsyncActionOrdState;
187 | }
188 |
189 | export interface IPullstateInstanceConsumable {
190 | stores: T;
191 |
192 | hasAsyncStateToResolve(): boolean;
193 |
194 | resolveAsyncState(): Promise;
195 |
196 | getPullstateSnapshot(): IPullstateSnapshot;
197 |
198 | hydrateFromSnapshot(snapshot: IPullstateSnapshot): void;
199 |
200 | runAsyncAction(
201 | asyncAction: IOCreateAsyncActionOutput,
202 | args?: A,
203 | runOptions?: Pick, "ignoreShortCircuit" | "respectCache">
204 | ): TPullstateAsyncRunResponse;
205 | }
206 |
207 | class PullstateInstance
208 | implements IPullstateInstanceConsumable {
209 | private _ssr: boolean = false;
210 | private _customContext: any;
211 | private readonly _stores: T = {} as T;
212 | _asyncCache: IPullstateAsyncCache = {
213 | listeners: {},
214 | results: {},
215 | actions: {},
216 | actionOrd: {}
217 | };
218 |
219 | constructor(allStores: T, ssr: boolean, customContext: any) {
220 | this._stores = allStores;
221 | this._ssr = ssr;
222 | this._customContext = customContext;
223 | /*if (!ssr) {
224 | // console.log(`Instantiating Stores`, allStores);
225 | clientStores.stores = allStores;
226 | clientStores.loaded = true;
227 | }*/
228 | }
229 |
230 | private getAllUnresolvedAsyncActions(): Array> {
231 | return Object.keys(this._asyncCache.actions).map((key) => this._asyncCache.actions[key]());
232 | }
233 |
234 | instantiateReactions() {
235 | for (const storeName of Object.keys(this._stores)) {
236 | this._stores[storeName]._instantiateReactions();
237 | }
238 | }
239 |
240 | getPullstateSnapshot(): IPullstateSnapshot {
241 | const allState = {} as IPullstateSnapshot["allState"];
242 |
243 | for (const storeName of Object.keys(this._stores)) {
244 | allState[storeName] = this._stores[storeName].getRawState();
245 | }
246 |
247 | return { allState, asyncResults: this._asyncCache.results, asyncActionOrd: this._asyncCache.actionOrd };
248 | }
249 |
250 | async resolveAsyncState() {
251 | const promises = this.getAllUnresolvedAsyncActions();
252 | await Promise.all(promises);
253 | }
254 |
255 | hasAsyncStateToResolve(): boolean {
256 | return Object.keys(this._asyncCache.actions).length > 0;
257 | }
258 |
259 | get stores(): T {
260 | return this._stores;
261 | }
262 |
263 | get customContext(): any {
264 | return this._customContext;
265 | }
266 |
267 | async runAsyncAction(
268 | asyncAction: IOCreateAsyncActionOutput,
269 | args: A = {} as A,
270 | runOptions: Pick, "ignoreShortCircuit" | "respectCache"> = {}
271 | ): TPullstateAsyncRunResponse {
272 | if (this._ssr) {
273 | (runOptions as IAsyncActionRunOptions)._asyncCache = this._asyncCache;
274 | (runOptions as IAsyncActionRunOptions)._stores = this._stores;
275 | (runOptions as IAsyncActionRunOptions)._customContext = this._customContext;
276 | }
277 |
278 | return await asyncAction.run(args, runOptions);
279 | }
280 |
281 | hydrateFromSnapshot(snapshot: IPullstateSnapshot) {
282 | for (const storeName of Object.keys(this._stores)) {
283 | if (snapshot.allState.hasOwnProperty(storeName)) {
284 | this._stores[storeName]._updateStateWithoutReaction(snapshot.allState[storeName]);
285 | } else {
286 | console.warn(`${storeName} didn't hydrate any state (data was non-existent on hydration object)`);
287 | }
288 | }
289 |
290 | clientAsyncCache.results = snapshot.asyncResults || {};
291 | clientAsyncCache.actionOrd = snapshot.asyncActionOrd || {};
292 | }
293 | }
294 |
295 | export function createPullstateCore(
296 | allStores: T = {} as T,
297 | options: IPullstateSingletonOptions = {}
298 | ) {
299 | return new PullstateSingleton(allStores, options);
300 | }
301 |
302 | export function useStores() {
303 | return useContext(PullstateContext)!.stores as T;
304 | }
305 |
306 | export function useInstance(): PullstateInstance {
307 | return useContext(PullstateContext)! as PullstateInstance;
308 | }
309 |
--------------------------------------------------------------------------------
/src/async-types.ts:
--------------------------------------------------------------------------------
1 | import { IPullstateAllStores } from "./PullstateCore";
2 | import { TUpdateFunction } from "./Store";
3 |
4 | type TPullstateAsyncUpdateListener = () => void;
5 |
6 | // [ started, finished, result, updating, timeCached ]
7 | export type TPullstateAsyncWatchResponse = [
8 | boolean,
9 | boolean,
10 | TAsyncActionResult,
11 | boolean,
12 | number
13 | ];
14 |
15 | // export type TPullstateAsync
16 |
17 | // [ started, finished, result, updating, postActionResult ]
18 | // export type TPullstateAsyncResponseCacheFull = [
19 | // boolean,
20 | // boolean,
21 | // TAsyncActionResult,
22 | // boolean,
23 | // TAsyncActionResult | true | null
24 | // ];
25 |
26 | // [finished, result, updating]
27 | export type TPullstateAsyncBeckonResponse = [
28 | boolean,
29 | TAsyncActionResult,
30 | boolean
31 | ];
32 | // [result]
33 | export type TPullstateAsyncRunResponse = Promise>;
34 |
35 | export interface IPullstateAsyncResultState {
36 | [key: string]: TPullstateAsyncWatchResponse;
37 | }
38 |
39 | export interface IPullstateAsyncActionOrdState {
40 | [key: string]: number;
41 | }
42 |
43 | export enum EAsyncEndTags {
44 | THREW_ERROR = "THREW_ERROR",
45 | RETURNED_ERROR = "RETURNED_ERROR",
46 | UNFINISHED = "UNFINISHED",
47 | DORMANT = "DORMANT",
48 | }
49 |
50 | interface IAsyncActionResultBase {
51 | message: string;
52 | tags: (EAsyncEndTags | T)[];
53 | }
54 |
55 | export interface IAsyncActionResultPositive extends IAsyncActionResultBase {
56 | error: false;
57 | payload: R;
58 | errorPayload: null;
59 | }
60 |
61 | export interface IAsyncActionResultNegative extends IAsyncActionResultBase {
62 | error: true;
63 | errorPayload: N;
64 | payload: null;
65 | }
66 |
67 | export type TAsyncActionResult =
68 | IAsyncActionResultPositive
69 | | IAsyncActionResultNegative;
70 |
71 | // Order of new hook functions:
72 |
73 | // shortCircuitHook = ({ args, stores }) => cachable response | false - happens only on uncached action
74 | // cacheBreakHook = ({ args, stores, result }) => true | false - happens only on cached action
75 | // postActionHook = ({ args, result, stores }) => void | new result - happens on all actions, after the async / short circuit has resolved
76 | // ----> postActionHook potentially needs a mechanism which allows it to run only once per new key change (another layer caching of some sorts expiring on key change)
77 |
78 | export type TPullstateAsyncShortCircuitHook = (inputs: {
79 | args: A;
80 | stores: S;
81 | }) => TAsyncActionResult | false;
82 |
83 | export type TPullstateAsyncCacheBreakHook = (inputs: {
84 | args: A;
85 | result: TAsyncActionResult;
86 | stores: S;
87 | timeCached: number;
88 | }) => boolean;
89 |
90 | export enum EPostActionContext {
91 | WATCH_HIT_CACHE = "WATCH_HIT_CACHE",
92 | BECKON_HIT_CACHE = "BECKON_HIT_CACHE",
93 | RUN_HIT_CACHE = "RUN_HIT_CACHE",
94 | READ_HIT_CACHE = "READ_HIT_CACHE",
95 | READ_RUN = "READ_RUN",
96 | SHORT_CIRCUIT = "SHORT_CIRCUIT",
97 | DIRECT_RUN = "DIRECT_RUN",
98 | BECKON_RUN = "BECKON_RUN",
99 | CACHE_UPDATE = "CACHE_UPDATE",
100 | }
101 |
102 | export type TPullstateAsyncPostActionHook = (inputs: {
103 | args: A;
104 | result: TAsyncActionResult;
105 | stores: S;
106 | context: EPostActionContext;
107 | }) => void;
108 |
109 | export interface IAsyncActionReadOptions {
110 | postActionEnabled?: boolean;
111 | cacheBreakEnabled?: boolean;
112 | key?: string;
113 | cacheBreak?: boolean | number | TPullstateAsyncCacheBreakHook
114 | }
115 |
116 | export interface IAsyncActionBeckonOptions extends IAsyncActionReadOptions {
117 | ssr?: boolean;
118 | holdPrevious?: boolean;
119 | dormant?: boolean;
120 | }
121 |
122 | export interface IAsyncActionWatchOptions extends IAsyncActionBeckonOptions {
123 | initiate?: boolean;
124 | }
125 |
126 | export interface IAsyncActionUseOptions extends IAsyncActionWatchOptions {
127 | onSuccess?: (result: R, args: A) => void;
128 | }
129 |
130 | export interface IAsyncActionUseDeferOptions extends Omit, "key"> {
131 | key?: string;
132 | holdPrevious?: boolean;
133 | onSuccess?: (result: R, args: A) => void;
134 | clearOnSuccess?: boolean;
135 | }
136 |
137 | export interface IAsyncActionRunOptions {
138 | treatAsUpdate?: boolean;
139 | ignoreShortCircuit?: boolean;
140 | respectCache?: boolean;
141 | key?: string;
142 | cacheBreak?: boolean | number | TPullstateAsyncCacheBreakHook
143 | _asyncCache?: IPullstateAsyncCache;
144 | _stores?: S;
145 | _customContext?: any;
146 | }
147 |
148 | export interface IAsyncActionGetCachedOptions {
149 | checkCacheBreak?: boolean;
150 | cacheBreak?: boolean | number | TPullstateAsyncCacheBreakHook;
151 | key?: string;
152 | }
153 |
154 | export interface IGetCachedResponse {
155 | started: boolean;
156 | finished: boolean;
157 | result: TAsyncActionResult;
158 | updating: boolean;
159 | existed: boolean;
160 | cacheBreakable: boolean;
161 | timeCached: number;
162 | }
163 |
164 | export interface IAsyncClearCacheOptions {
165 | notify?: boolean;
166 | }
167 |
168 | export interface IAsyncActionSetOrClearCachedValueOptions extends IAsyncClearCacheOptions {
169 | key?: string;
170 | }
171 |
172 | export interface IAsyncActionUpdateCachedOptions extends IAsyncActionSetOrClearCachedValueOptions {
173 | resetTimeCached?: boolean;
174 | runPostActionHook?: boolean;
175 | }
176 |
177 | export type TAsyncActionUse = (
178 | args?: A,
179 | options?: IAsyncActionUseOptions
180 | ) => TUseResponse;
181 |
182 | export type TAsyncActionUseDefer = (
183 | options?: IAsyncActionUseDeferOptions
184 | ) => TUseDeferResponse;
185 |
186 | export type TAsyncActionBeckon = (
187 | args?: A,
188 | options?: IAsyncActionBeckonOptions
189 | ) => TPullstateAsyncBeckonResponse;
190 |
191 | export type TAsyncActionWatch = (
192 | args?: A,
193 | options?: IAsyncActionWatchOptions
194 | ) => TPullstateAsyncWatchResponse;
195 |
196 | export type TAsyncActionRun = (
197 | args?: A,
198 | options?: IAsyncActionRunOptions
199 | ) => TPullstateAsyncRunResponse;
200 |
201 | export type TAsyncActionClearCache = (args?: A, options?: IAsyncActionSetOrClearCachedValueOptions) => void;
202 |
203 | export type TAsyncActionClearAllCache = (options?: IAsyncClearCacheOptions) => void;
204 |
205 | export type TAsyncActionClearAllUnwatchedCache = (options?: IAsyncClearCacheOptions) => void;
206 |
207 | export type TAsyncActionGetCached = (
208 | args?: A,
209 | options?: IAsyncActionGetCachedOptions
210 | ) => IGetCachedResponse;
211 |
212 | export type TAsyncActionSetCached = (
213 | args: A,
214 | result: TAsyncActionResult,
215 | options?: IAsyncActionSetOrClearCachedValueOptions
216 | ) => void;
217 |
218 | export type TAsyncActionSetCachedPayload = (args: A, payload: R, options?: IAsyncActionSetOrClearCachedValueOptions) => void;
219 |
220 | export type TAsyncActionUpdateCached = (
221 | args: A,
222 | updater: TUpdateFunction,
223 | options?: IAsyncActionUpdateCachedOptions
224 | ) => void;
225 | export type TAsyncActionRead = (args?: A, options?: IAsyncActionReadOptions) => R;
226 |
227 | export type TAsyncActionDelayedRun = (
228 | args: A,
229 | options: IAsyncActionRunOptions & { delay: number; clearOldRun?: boolean; immediateIfCached?: boolean }
230 | ) => () => void;
231 |
232 | export interface IOCreateAsyncActionOutput {
233 | use: TAsyncActionUse;
234 | useDefer: TAsyncActionUseDefer;
235 | read: TAsyncActionRead;
236 | useBeckon: TAsyncActionBeckon;
237 | useWatch: TAsyncActionWatch;
238 | run: TAsyncActionRun;
239 | delayedRun: TAsyncActionDelayedRun;
240 | getCached: TAsyncActionGetCached;
241 | setCached: TAsyncActionSetCached;
242 | setCachedPayload: TAsyncActionSetCachedPayload;
243 | updateCached: TAsyncActionUpdateCached;
244 | clearCache: TAsyncActionClearCache;
245 | clearAllCache: TAsyncActionClearAllCache;
246 | clearAllUnwatchedCache: TAsyncActionClearAllUnwatchedCache;
247 | }
248 |
249 | export interface IPullstateAsyncCache {
250 | results: IPullstateAsyncResultState;
251 | listeners: {
252 | [key: string]: {
253 | [watchId: string]: TPullstateAsyncUpdateListener;
254 | };
255 | };
256 | actions: {
257 | [key: string]: () => Promise>;
258 | };
259 | actionOrd: IPullstateAsyncActionOrdState;
260 | }
261 |
262 | export type TPullstateAsyncAction = (
263 | args: A,
264 | stores: S,
265 | customContext: any
266 | ) => Promise>;
267 |
268 | export interface ICreateAsyncActionOptions {
269 | forceContext?: boolean;
270 | // clientStores?: S;
271 | shortCircuitHook?: TPullstateAsyncShortCircuitHook;
272 | cacheBreakHook?: TPullstateAsyncCacheBreakHook;
273 | postActionHook?: TPullstateAsyncPostActionHook;
274 | subsetKey?: (args: A) => any;
275 | actionId?: string | number;
276 | }
277 |
278 | // action.use() types
279 |
280 | export interface IUseDebouncedExecutionOptions {
281 | validInput?: (args: A) => boolean;
282 | equality?: ((argsPrev: A, argsNew: A) => boolean) | any;
283 | executeOptions?: Omit, "key" | "cacheBreak">;
284 | watchLastValid?: boolean;
285 | }
286 |
287 | export type TRunWithPayload = (func: (payload: R) => any) => any;
288 |
289 | export interface IBaseObjResponseUse {
290 | execute: (runOptions?: IAsyncActionRunOptions) => TPullstateAsyncRunResponse;
291 | }
292 |
293 | export interface IBaseObjResponseUseDefer {
294 | execute: (args?: A, runOptions?: Omit, "key" | "cacheBreak">) => TPullstateAsyncRunResponse;
295 | hasCached: (args?: A, options?: { successOnly?: boolean } & Omit
3 |