\n );\n}\n\nfunction loadDataAsProps({ store, ownProps }) {\n return {\n ComponentA: () => iguazuReduce(ComponentA.loadDataAsProps)({\n store, ownProps: { someParam: 'someParam' }\n }),\n ComponentB: () => iguazuReduce(ComponentB.loadDataAsProps)({ store, ownProps: {} })\n }\n}\n```\n\n### Sequencing\n\nQuite often you need the results of one asynchronous call to get the inputs for another call. One way to do this is by simply using components.\n\nExample:\n\n```javascript\nimport React from 'react';\nimport { connectAsync } from 'iguazu';\n\nfunction Parent({ isLoading, parent }) {\n if (isLoading()) {\n return \n \n {\n buttonClicked && \n )\n }\n};\n\n/* ComponentB.jsx */\nimport React from 'react';\nimport { connectAsync } from 'iguazu';\n\nfunction ComponentB({ isLoading, loadedWithErrors, myData, myOtherData }) {\n if (isLoading()) {\n return \n
\n\n[](https://badge.fury.io/js/iguazu)\n\n\n> Iguazu is a simple Redux-powered Async Query engine. By using a\n> Higher-Order Component, Iguazu transparently manages dispatching async\n> requests and injecting into React props. Iguazu has an ecosystem of\n> adapters for various querying + caching strategies: [Iguazu RPC](https://github.com/americanexpress/iguazu-rpc), [Iguazu GraphQL](https://github.com/americanexpress/iguazu-graphql) and [Iguazu REST](https://github.com/americanexpress/iguazu-rest).\n\n## ๐ฉโ๐ป Hiring ๐จโ๐ป\n\nWant to get paid for your contributions to `iguazu`?\n> Send your resume to oneamex.careers@aexp.com\n\n## ๐ Table of Contents\n\n* [Features](#-features)\n* [Usage](#-usage)\n* [Upgrading](#-upgrading)\n* [Contributing](#-contributing)\n\n## โจ Features\n\n* Streamlines dispatching, load states, and injecting into React props\n* Parallel and sequential async requests\n* Server-side rendering ready\n\n### Motivation\n\n[react-redux](https://github.com/reduxjs/react-redux) works great for when you want to take data that already exists in state and inject it as props into a React component, but it doesn't help you at all with the flow of loading asynchronous data into state. If a react component relies on asynchronous data you typically have to do three things:\n\n1. Define a load action responsible for fetching the asynchronous data, which should be triggered on mount and when the component receives new props that change what data should be loaded\n2. Define a `mapStateToProps` function and use selectors to get the data out of state\n3. Determine whether the state is actually loaded based on the props the selectors return\n\nIguazu seeks to simplify this flow into one step.\n\n## ๐คนโ Usage\n\n### Installation\n\n```bash\nnpm install --save iguazu\n```\n\n### Base Concepts\n\nIguazu exports a Higher Order Component (HOC) `connectAsync` similar to React Redux's `connect`. Instead of taking a `mapStateToProps` function, it takes a `loadDataAsProps` function. It should return a map where each key is the name of a prop that will contain some asynchronous data and the value is the load function that will load that data if it is not already loaded. The load function must synchronously return an object with the keys `data`, `status`, `error`, and `promise`. The key `data` should be the data returned from the asynchronous call. The key `status` should be either `loading` to signal the asynchronous call is in flight or `complete` to signal it has returned. The key `error` should be a truthy value if there was an error while loading. The key `promise` should be the promise of the asynchronous call.\n\nFor each key defined in the `loadDataAsProps` function, the HOC will pass a prop to the wrapped component that contains the data. It will also pass two function props, `isLoading` and `loadedWithErrors`, which will tell you if any of the async props are still loading or loaded with errors respectively. If you are only interested in a subset of async props, you can pass an array of the props names as the first argument. There will also be a prop named `loadErrors` that maps the load error, if there is one, for each prop. You can use this if you want to more granularly dig into what failed.\n\nExample:\n\n```javascript\n/* actions.js */\nimport React from 'react';\nimport { connectAsync } from 'iguazu';\n\nexport function queryMyData(param) {\n return (dispatch, getState) => {\n const data = getState().path.to.myData[param];\n const status = data ? 'complete' : 'loading';\n const promise = data ? Promise.resolve : dispatch(fetchMyData(param));\n\n return { data, status, promise };\n };\n}\n\nexport function queryMyOtherData(param) { /* Essentially the same as queryMyData */ }\n\n/* MyContainer.jsx */\nfunction MyContainer({\n isLoading,\n loadedWithErrors,\n myData,\n myOtherData,\n}) {\n if (isLoading()) {\n return \n {message}\n \n \n );\n }\n}\n\n// Hook up action creator functions to props to call later\nfunction mapDispatchToProps(dispatch) {\n return {\n // Update some remote resource\n updateMyData: (someParam) => dispatch(updateMyDataAction(someParam)),\n // Fetch some remote resource\n getMyData: () => dispatch(getMyDataAction()),\n };\n}\n\n// Hook up data dispatches on component load\nfunction loadDataAsProps({ store }) {\n const { dispatch } = store;\n return {\n // Fetch some remote resource and inject it into props as myData\n myData: () => dispatch(getMyDataAction()),\n };\n}\n\nexport default compose(\n connect(undefined, mapDispatchToProps),\n connectAsync({ loadDataAsProps })\n)(MyUpdatingComponent);\n```\n\n#### Global Configuration\n\nIguazu is also capable of consuming global configuration that will be applied to all instances of `connectAsync`. These options will be applied unless otherwise overridden by providing the equivalent setting in the `connectAsync` call.\n\n```javascript\nimport { shallowEqual, deepEqual } from 'fast-equals';\nimport { configureIguazu } from 'iguazu';\n\nconfigureIguazu({\n stateChangeComparator: shallowEqual, // applied globally.\n stateChangeLimiter: (onStateChange) => debounce(onStateChange, 100), // applied globally.\n});\n\n/* ... */\n\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(queryToDeeplyNestedData(ownProps.someParam)),\n myOtherData: () => dispatch(expensiveQueryToData(ownProps.someParam)),\n };\n}\n\nexport default connectAsync({\n loadDataAsProps,\n stateChangeComparator: deepEqual, // override global setting.\n stateChangeLimiter: (onStateChange) => debounce(onStateChange, 500), // override global setting.\n})(MyContainer);\n```\n\n#### Known Issues\n\n- Using `iguazuReduce` within a `sequence` returns the response to the next handler as an array if the data is not loaded. Pass in `promiseAsObject` to `iguazuReduce` to resolve until next major version.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n {\n key: 'first',\n handler: () => iguazuReduce(ComponentA.loadDataAsProps, { promiseAsObject: true })({\n store, ownProps: { someParam: 'someParam' },\n }),\n },\n { key: 'second', handler: ({ first }) => dispatch(loadSecond(first.someParam)) },\n]);\n```\n\n## ๐ Upgrading\n\n### v2.x.x to v3.x.x\n\n- Upgraded to React Redux 7.x.x, Redux 4.x.x, and Redux Thunk 2.x.x\n- Using new [React Context](https://reactjs.org/docs/context.html) Consumer for retrieving Redux store.\n- Added a `ReduxConsumer` wrapping component to `connectAsync` which, may break jest snapshots.\n- Removed `enableSSR`, `disableSSR`, and `isSSR` methods in favor of checking for `window` to determine Server versus Client in SSR mode\n- `loadDataAsProps` functions receive `isServer` as an argument rather than `ssr` now.\n- Moved `react`, `react-dom`, `react-redux`, `redux`, and `redux-thunk` to `peerDependencies`\n- Removed `lodash` and decreased gzip bundle size from `~9.6kb` to `~4.5kb` gzipped.\n- Iguazu adapters remain compatible, just upgrade dependency on `iguazu` to `^3.0.0`.\n\n## ๐ Contributing\n\nWe welcome Your interest in the American Express Open Source Community on Github.\nAny Contributor to any Open Source Project managed by the American Express Open\nSource Community must accept and sign an Agreement indicating agreement to the\nterms below. Except for the rights granted in this Agreement to American Express\nand to recipients of software distributed by American Express, You reserve all\nright, title, and interest, if any, in and to Your Contributions. Please [fill\nout the Agreement](https://cla-assistant.io/americanexpress/iguazu).\n\nPlease feel free to open pull requests and see [CONTRIBUTING.md](./CONTRIBUTING.md) to learn how to get started contributing.\n\n## ๐๏ธ License\n\nAny contributions made under this project will be governed by the [Apache License\n2.0](./LICENSE.txt).\n\n## ๐ฃ๏ธ Code of Conduct\n\nThis project adheres to the [American Express Community Guidelines](./CODE_OF_CONDUCT.md).\nBy participating, you are expected to honor these guidelines.\n","maintainers":[{"name":"pixnbits","email":"i@pixnbits.org"},{"name":"anescobar1991","email":"anescobar1991@gmail.com"},{"name":"jsmartfo","email":"j_smart_foster@hotmail.com"},{"name":"amexopensource","email":"open-source-ops@aexp.com"},{"name":"mtomcal","email":"michael@twoeyetech.com"},{"name":"10xlacroixdrinker","email":"hello@jaimeking.me"}],"time":{"modified":"2022-06-19T00:23:22.313Z","created":"2017-07-04T18:39:35.882Z","0.0.0":"2017-07-04T18:39:35.882Z","2.2.0":"2018-08-16T01:34:21.709Z","2.3.0":"2018-11-07T21:57:42.932Z","2.3.1":"2019-02-05T16:47:26.292Z","2.4.0":"2019-04-11T21:53:15.206Z","2.5.0":"2019-08-29T19:12:55.989Z","2.5.1":"2019-09-09T19:23:11.790Z","2.5.2":"2019-10-22T18:35:07.778Z","3.0.0-0":"2019-11-11T18:12:31.342Z","3.0.0-3":"2019-11-15T16:41:31.342Z","2.6.2":"2019-11-26T21:54:33.007Z","2.6.0":"2019-12-23T13:59:15.808Z","3.0.0":"2020-01-08T18:35:23.993Z","2.6.3":"2020-02-27T18:53:48.103Z","2.6.4":"2020-03-02T20:46:57.398Z","3.0.1":"2020-03-02T20:47:34.067Z","3.0.2":"2020-03-02T21:08:26.968Z","3.1.0":"2020-08-14T16:38:16.025Z","2.7.0":"2020-08-14T19:13:50.504Z","2.8.0":"2020-08-17T19:09:19.319Z","3.2.0":"2021-12-17T16:59:53.996Z"},"license":"Apache-2.0","readmeFilename":"README.md","description":"An asynchronous data flow solution for React/Redux applications","author":{"name":"Maia Teegarden"},"contributors":[{"name":"Andres Escobar","email":"Andres.Escobar@aexp.com","url":"https://github.com/anescobar1991"},{"name":"James Singleton","email":"James.Singleton1@aexp.com"},{"name":"Jimmy King","email":"Jimmy.King@aexp.com","url":"https://github.com/10xLaCroixDrinker"},{"name":"Jonathan Adshead","email":"Jonathan.Adshead@aexp.com","url":"https://github.com/JAdshead"},{"name":"Michael Tobia","email":"Michael.M.Tobia@aexp.com","url":"https://github.com/Francois-Esquire"},{"name":"Michael Tomcal","email":"Michael.A.Tomcal@aexp.com","url":"https://github.com/mtomcal"},{"name":"Stephanie Coates","email":"Stephanie.Coates1@aexp.com","url":"https://github.com/stephaniecoates"},{"name":"Nelly Kiboi","email":"Nelly.J.Kiboi@aexp.com","url":"https://github.com/nellyk"},{"name":"Nickolas Oliver","email":"nickolas.oliver@aexp.com","url":"https://github.com/PixnBits"},{"name":"Andrew Curtis","email":"andrew.curtis@aexp.com","url":"https://github.com/drewcur"},{"name":"Scott McIntyre","email":"scott.mcintyre@aexp.com","url":"https://github.com/smackfu"}],"homepage":"https://github.com/americanexpress/iguazu","repository":{"type":"git","url":"git+https://github.com/americanexpress/iguazu.git"},"bugs":{"url":"https://github.com/americanexpress/iguazu/issues"},"keywords":["async","react","redux","react-redux","fetch","data","query","promise"]}
Loading Your Profile...
;\n }\n\n return (\n \n
\n );\n}\n\nfunction parentLoadDataAsProps({ store: { dispatch } }) {\n return {\n parents: dispatch(loadLoggedInParent()),\n };\n}\n\nconst ParentContainer = connectAsync({ loadDataAsProps: parentLoadDataAsProps })(Parent)\n\nfunction Kids({ isLoading, kids }) {\n if (isLoading()) {\n return \n You:\n
\n Loading Kids...
;\n }\n\n return (\n \n Kids:\n {kids.map((kid) => (
\n );\n}\n\nfunction kidsLoadDataAsProps({ store: { dispatch }, ownProps: { parentId } }) {\n return {\n kids: dispatch(loadKidsByParent(parentId)),\n };\n}\n\nconst KidsContainer = connectAsync({ loadDataAsProps: kidsLoadDataAsProps })(Kids)\n\nfunction PersonInfo({ info: { name, age } }) {\n return {\n \n name: {name}\n age: {age}\n
\n }\n}\n```\n\nSuppose you want to synchronize the parent and kid components so that you show a loading spinner until they are both done loading their data. Or maybe you only have one component that needs some sequenced data and it doesn't make sense to create a new component for each nested piece of data. In these cases you can use the load helper, `sequence`. You can pass it an array of load functions that need to run in order and depend on data returned from previous functions.\n\nExample:\n\n```javascript\nimport React from 'react';\nimport { connectAsync, sequence } from 'iguazu';\n\nfunction Parent({ isLoading, parent, kids }) {\n if (isLoading()) {\n return Loading Your Profile...
;\n }\n\n return (\n \n
\n );\n}\n\nfunction parentLoadDataAsProps({ store: { dispatch } }) {\n const sequenceLoadFunctions = sequence([\n { key: 'parent', handler: () => dispatch(loadLoggedInParent()) },\n { key: 'kids', handler: ({ parent }) => dispatch(loadKidsByParent(parent.id)) }\n ]);\n\n return {\n ...sequenceLoadFunctions\n };\n}\n\nconst ParentContainer = connectAsync({ loadDataAsProps: parentLoadDataAsProps })(Parent)\n\nfunction Kids({ kids }) {\n return (\n \n You:\n
\n \n Kids:\n {kids.map((kid) => (
\n );\n}\n\nfunction PersonInfo({ info: { name, age } }) {\n return {\n \n name: {name}\n age: {age}\n
\n }\n}\n\n```\n\nSequenced function handlers are called with the results from all previous functions in case your inputs need to be derived from more than one previous call.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n { key: 'first', handler: () => dispatch(loadFirst()) },\n { key: 'second', handler: ({ first }) => dispatch(loadSecond(first.someParam)) },\n { key: 'third', handler: ({ first, second }) => dispatch(loadThird(first.someParam, second.anotherParam)) }\n]);\n```\n\nIf you need to make two calls in parallel before you make a third, you can use a combination of `iguazuReduce` and `sequence` to accomplish your goal.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n {\n key: 'first',\n handler: iguazuReduce(() => ({\n firstA: () => dispatch(loadFirstA()),\n firstB: () => dispatch(loadFirstB())\n }))\n },\n {\n key: 'second', handler: ({ first: { firstA, firstB } }) => dispatch(loadSecond(firstA, firstB))\n }\n]);\n```\n\nFunction handlers require the previous calls to succeed to continue to the next by default. In the\nevent a request returns with an error all remaining calls are flagged with the same error. To bypass\nthis default behavior, you can wrap the function handler in `noncritical` to continue without the\nprevious results.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n { key: 'first', handler: () => dispatch(loadFirst()) },\n { key: 'second', handler: ({ first }) => dispatch(loadSecond(first.someParam)) },\n { key: 'unrelated', handler: noncritical(() => dispatch(loadUnrelated())) },\n]);\n````\n\n### Updating\n\nIguazu processes updates on Redux state changes by comparing the previous and next responses from `loadDataAsProps` using\n[shallowequal](https://www.npmjs.com/package/shallowequal) by default. You are able to declare a comparator function when\ncalling `connectAsync` to manage how the previous and next responses from `loadDataAsProps` are compared.\n\n```javascript\nimport { deepEqual } from 'fast-equals';\n\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(queryToDeeplyNestedData(ownProps.someParam)),\n myOtherData: () => dispatch(queryMyOtherData(getState().someOtherParam))\n }\n}\n\nexport default connectAsync({\n loadDataAsProps,\n stateChangeComparator: deepEqual,\n})(MyContainer);\n```\n\n### Limiting\n\nAs some functions called within `loadDataAsProps` can be expensive when ran on every Redux state change, you are able to declare a limiter function when calling `connectAsync`. Calls to `loadDataAsProps` are not limited by default.\n\n```javascript\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(expensiveQueryToData(ownProps.someParam)),\n myOtherData: () => dispatch(queryMyOtherData(getState().someOtherParam))\n }\n}\n\nexport default connectAsync({\n loadDataAsProps,\n stateChangeLimiter: onStateChange => debounce(onStateChange, 100),\n})(MyContainer);\n```\n\n### Fetching On User Action\n\nIn the case that `loadDataAsProps` needs to be called on a user action, the initial render can be controlled by the result of the expected user input.\n\n```javascript\n/* ComponentA.jsx */\nimport React, { Component, Fragment } from 'react';\nimport ComponentB from './ComponentB';\n\nexport default class ComponentA extends Component {\n constructor(props) {\n super(props);\n this.state = { buttonClicked: false };\n }\n\n handleClick = () => this.setState({ buttonClicked: true });\n\n render() {\n const { buttonClicked } = this.state;\n return (\n Loading...
\n }\n\n if (loadedWithErrors()) {\n return Oh no! Something went wrong
\n }\n\n return myData = {myData} myOtherData = {myOtherData}
\n};\n\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => {\n if (!ownProps.someParam) {\n return { status: 'complete', promise: Promise.resolve() }; // data & error should be undefined.\n }\n return dispatch(queryMyData(ownProps.someParam));\n },\n myOtherData: () => dispatch(queryMyOtherData(getState().someOtherParam))\n }\n};\n\nexport default connectAsync({ loadDataAsProps })(ComponentB);\n```\n\n## Global Configuration\n\nIguazu is also capable of consuming global configuration that will be applied to all instances of `connectAsync`. These options will be applied unless otherwise overridden by providing the equivalent setting in the `connectAsync` call.\n\n```javascript\nimport { shallowEqual, deepEqual } from 'fast-equals';\nimport { configureIguazu } from 'iguazu';\n\nconfigureIguazu({\n stateChangeComparator: shallowEqual, // applied globally.\n stateChangeLimiter: onStateChange => debounce(onStateChange, 100), // applied globally.\n});\n\n...\n\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(queryToDeeplyNestedData(ownProps.someParam)),,\n myOtherData: () => dispatch(expensiveQueryToData(ownProps.someParam))\n }\n}\n\nexport default connectAsync({\n loadDataAsProps,\n stateChangeComparator: deepEqual, // override global setting.\n stateChangeLimiter: onStateChange => debounce(onStateChange, 500), // override global setting.\n})(MyContainer);\n```\n\n## Known Issues\n\n- Using `iguazuReduce` within a `sequence` returns the response to the next handler as an array if the data is not loaded. Pass in `promiseAsObject` to `iguazuReduce` to resolve until next major version.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n { key: 'first', handler: () => iguazuReduce(ComponentA.loadDataAsProps, { promiseAsObject: true })({\n store, ownProps: { someParam: 'someParam' }\n }) },\n { key: 'second', handler: ({ first }) => dispatch(loadSecond(first.someParam)) },\n]);\n```\n\n## Why is it called Iguazu?\nThis library is all about helping you manage data flow from many different sources. Data flow -> water -> waterfalls -> Iguazu falls - the largest waterfalls system in the world. It could have been named something like react-redux-async, but Iguazu also expects a certain pattern, which means there could potentially be many libraries that follow this pattern that could plug in to Iguazu. A unique name will make them more discoverable. Also it sounds cool.\n\n## Contributing\nWe welcome Your interest in the American Express Open Source Community on Github.\nAny Contributor to any Open Source Project managed by the American Express Open\nSource Community must accept and sign an Agreement indicating agreement to the\nterms below. Except for the rights granted in this Agreement to American Express\nand to recipients of software distributed by American Express, You reserve all\nright, title, and interest, if any, in and to Your Contributions. Please [fill\nout the Agreement](https://cla-assistant.io/americanexpress/iguazu).\n\nPlease feel free to open pull requests and see [CONTRIBUTING.md](./CONTRIBUTING.md) for commit formatting details.\n\n## License\nAny contributions made under this project will be governed by the [Apache License\n2.0](https://github.com/americanexpress/iguazu/blob/master/LICENSE.txt).\n\n## Code of Conduct\nThis project adheres to the [American Express Community Guidelines](./CODE_OF_CONDUCT.md).\nBy participating, you are expected to honor these guidelines.\n","readmeFilename":"README.md","gitHead":"ea12b8a8dd99603ee1ac47cdaae17e9140f0f9ce","bugs":{"url":"https://github.com/americanexpress/iguazu/issues"},"homepage":"https://github.com/americanexpress/iguazu#readme","_id":"iguazu@2.8.0","_nodeVersion":"12.18.3","_npmVersion":"6.14.7","dist":{"integrity":"sha512-OCLJ0cePLehMMMlVY9aGY2ari9ycE44jZmxSfpxnf6wkF09MqJagibfejni60PSYhfDXEgNl0eP9qZ+RSt6pKQ==","shasum":"c5724ea032f4ef39e84092e0cc74dd9a34900f21","tarball":"https://registry.npmjs.org/iguazu/-/iguazu-2.8.0.tgz","fileCount":16,"unpackedSize":61678,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfOtXfCRA9TVsSAnZWagAAhxUP/3M3HCvbwPy8Y51R0M5v\nzUJCEi0Hzp/tLuPgWA112jnF/md8Lk30mth6+qUG2l8lMXnccOJwuI4/nqCh\nXXsKf8ETGEz+MvWIdmy3l2N/hgkWcEgs3v1Mwm3xaTOUIgQY+3YwyJZdXlkN\nBs57ahQqDYDri5p3a2Tp4KoFPg8m+kWdgFTN+PzUvMtwYwjM5Qfref+ubvAt\nkdM6zmmFLX54iB54MLOb+GvxyTt79i1ewoPVVv5VPwQK/3PhIlBRqSRN/aJz\nbj+K7YwgP2da+XcemNLcVgGnoZTtQzRA90qlO5KZQcAdWTF9VN3bR3AqRCFn\nE/+OJ+BEOcMuLKZqiyIn/I+CaQnvW8XyoJzFfUzLYQzJi2zEGRBhDjvm2a5M\nwlaZAuEZHMdvSUwmPMAAGthxSUnU3DbcDH7CnEgTdF9Cbhc17G1U0zqKYF4G\nxh1x6cF/84Qp5oZh7qIs7BT+6KjUBRlsVAY3OGlO374E8wzaPqm/DUVDQdOs\nGQCG8GdtgR30qce+68pAtoNNEJEJ183EPhkk14MjzZV72SG91Bk2xMuDZ2se\nS9KsyuFH5fb6iKi1J5icw/xfgDudccB11EOIOvsaVZOUpiPKH5iTnftbzn1W\nlW/e22OldWN6oLz7JSBOtGEM/OsBb4ValH/a2EG9Y6ytZWlJ4OcjKkRr58ZC\n5how\r\n=4p7l\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCVEH/i5Wm16+KQRRwqcQJxSqLRL+74CPMsV3DQ4W9oXQIgVbF5jM2S0o7C9ENM0uxvKKVmx1ZBsyJ8A10H3mX+eYI="}]},"maintainers":[{"email":"open-source-ops@aexp.com","name":"amexopensource"},{"email":"anescobar1991@gmail.com","name":"anescobar1991"},{"email":"hello@jimmyking.me","name":"jimmyking"},{"email":"j_smart_foster@hotmail.com","name":"jsmartfo"},{"email":"michael@twoeyetech.com","name":"mtomcal"},{"email":"i@pixnbits.org","name":"pixnbits"}],"_npmUser":{"name":"amexopensource","email":"open-source-ops@aexp.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/iguazu_2.8.0_1597691359147_0.9045218185222592"},"_hasShrinkwrap":false},"3.2.0":{"name":"iguazu","version":"3.2.0","description":"An asynchronous data flow solution for React/Redux applications","author":{"name":"Maia Teegarden"},"contributors":[{"name":"Andres Escobar","email":"Andres.Escobar@aexp.com","url":"https://github.com/anescobar1991"},{"name":"James Singleton","email":"James.Singleton1@aexp.com"},{"name":"Jimmy King","email":"Jimmy.King@aexp.com","url":"https://github.com/10xLaCroixDrinker"},{"name":"Jonathan Adshead","email":"Jonathan.Adshead@aexp.com","url":"https://github.com/JAdshead"},{"name":"Michael Tobia","email":"Michael.M.Tobia@aexp.com","url":"https://github.com/Francois-Esquire"},{"name":"Michael Tomcal","email":"Michael.A.Tomcal@aexp.com","url":"https://github.com/mtomcal"},{"name":"Stephanie Coates","email":"Stephanie.Coates1@aexp.com","url":"https://github.com/stephaniecoates"},{"name":"Nelly Kiboi","email":"Nelly.J.Kiboi@aexp.com","url":"https://github.com/nellyk"},{"name":"Nickolas Oliver","email":"nickolas.oliver@aexp.com","url":"https://github.com/PixnBits"},{"name":"Andrew Curtis","email":"andrew.curtis@aexp.com","url":"https://github.com/drewcur"},{"name":"Scott McIntyre","email":"scott.mcintyre@aexp.com","url":"https://github.com/smackfu"}],"keywords":["async","react","redux","react-redux","fetch","data","query","promise"],"homepage":"https://github.com/americanexpress/iguazu","bugs":{"url":"https://github.com/americanexpress/iguazu/issues"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/americanexpress/iguazu.git"},"main":"lib/index.js","scripts":{"build":"babel src --out-dir lib","lint":"eslint --ignore-path .gitignore --ext js,jsx,md .","prepublish":"npm run build","test":"jest && npm run test:git-history","test:git-history":"commitlint --from origin/main --to HEAD","test:lockfile":"lockfile-lint -p package-lock.json -t npm -a npm -o https: -c -i","posttest":"npm run lint && npm run test:lockfile"},"jest":{"preset":"amex-jest-preset-react","setupFiles":["./test-setup.js"]},"dependencies":{"hoist-non-react-statics":"^3.3.0","prop-types":"^15.5.10","shallowequal":"^1.0.1"},"devDependencies":{"@babel/cli":"^7.16.0","@babel/core":"^7.16.5","@commitlint/cli":"^15.0.0","@commitlint/config-conventional":"^15.0.0","@semantic-release/changelog":"^5.0.1","@semantic-release/commit-analyzer":"^8.0.1","@semantic-release/git":"^9.0.0","@semantic-release/npm":"^7.0.6","@semantic-release/release-notes-generator":"^9.0.1","amex-jest-preset-react":"^6.1.0","babel-jest":"^27.4.5","babel-preset-amex":"^3.5.1","core-js":"^3.20.0","core-js-compat":"3.4.5","enzyme":"^3.1.1","enzyme-to-json":"^3.2.1","eslint":"^7.32.0","eslint-config-amex":"^15.0.1","eslint-plugin-jest":"^24.7.0","eslint-plugin-jest-dom":"^3.9.2","husky":"^3.0.9","jest":"^27.4.5","jest-fetch-mock":"^1.2.0","lockfile-lint":"^4.3.6","react":"^16.0.0","react-dom":"^16.0.0","react-redux":"^7.1.1","react-test-renderer":"^16.0.0","redux":"^4.0.4","redux-thunk":"^2.3.0","regenerator-runtime":"^0.13.9","semantic-release":"^17.2.1"},"peerDependencies":{"react":">=16.0.0","react-dom":">=16.0.0","react-redux":"^7.1.1","redux":"^4.0.4","redux-thunk":"^2.3.0"},"release":{"branches":["+([0-9])?(.{+([0-9]),x}).x","main","next","next-major",{"name":"beta","prerelease":true},{"name":"alpha","prerelease":true}],"plugins":["@semantic-release/commit-analyzer","@semantic-release/release-notes-generator","@semantic-release/changelog","@semantic-release/npm","@semantic-release/git","@semantic-release/github"]},"husky":{"hooks":{"pre-commit":"npm test","commit-msg":"commitlint -E HUSKY_GIT_PARAMS"}},"gitHead":"dc3671ae4c15ee11647a77946c5e87485ed1589a","_id":"iguazu@3.2.0","_nodeVersion":"16.13.1","_npmVersion":"7.24.2","dist":{"integrity":"sha512-Uoio5+U9Vr0n33MFTFLw1rPMQZEvRjy95aid6tNTXUwZsyaoOf8Pu6DBsgv2iagp9VeuvG82GUwr/Z2KrNP5ng==","shasum":"395f0ed93a349c53a481f60a87e1c22e999bcb41","tarball":"https://registry.npmjs.org/iguazu/-/iguazu-3.2.0.tgz","fileCount":15,"unpackedSize":92642,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJhvMIJCRA9TVsSAnZWagAAuCUP/RivIt8fRPW6MrNjekC/\ncvj9cgZ8SQjedqfsqPy5LBiXZn8GslzD+ipol3Jeoa80f5Z+VpqteW1VdsRZ\nYuFPQ1u3NgIpHBwfxdato5/Aq2Ol+yXnkJEp9ch75qGND4tq1Fzu6OWg1r5v\n4fdvvSZRnleVp0fzeCiEq8S8NpF3+/JIiYBv1TNRDwjiFWkX7B+8cn53XcLC\nzV9X5yiJEdNjm06DYI7tIO8TfT9iiAkKASmv4Bf6y0p1QpwY6K5k+xLMDx92\nEaDCtmAIpDKvSfv6krNRKpQmOIBWCJdelpx0K92I9hB7pCMEYfjR71I1QdCz\nDaydMfxfjLaIGnqWX5XlXHDAPvMNiCAmaDJ/emBtUSGPqpMryI4tdpkgUNr0\nYTS3gjk3RLEZPDJ1cnA5DcQsQXXV+3vbKkJiV9uXrGmlQqdDXaHve+xOn5w1\neamH0iVUABtSWJ9k0hJQtvJwd7OPbbVMHlIYkIGz72Xoltnp5lFEQfh4R9C7\nAzK3kqpWh+qe5EkqSbG+DyDy49oj91Zis+SaMz/MqBYNbrs/o/GPw4tUuJiS\nSWwlMwka7zj7wuug69zgSc/KuMgg4LzwgC1ZH/cvYz+Fd4M/PZBquoC+SOqp\nG4tiJgsGcON1r185HCCNIy0j+aIok67NGEBwFn1ky25nQzeNSUmaAcDl/Lvj\nR/s6\r\n=lxS/\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHmAgR+dudWWcispYzb1nxbRjUfvkYFE6fBrnVRo9OKWAiBa16hQ91j61w5ypoGeNeiNmF/H7lb1lxKbhzuVlO+wEA=="}]},"_npmUser":{"name":"amexopensource","email":"open-source-ops@aexp.com"},"directories":{},"maintainers":[{"name":"pixnbits","email":"i@pixnbits.org"},{"name":"anescobar1991","email":"anescobar1991@gmail.com"},{"name":"jsmartfo","email":"j_smart_foster@hotmail.com"},{"name":"amexopensource","email":"open-source-ops@aexp.com"},{"name":"mtomcal","email":"michael@twoeyetech.com"},{"name":"10xlacroixdrinker","email":"hello@jaimeking.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/iguazu_3.2.0_1639760393832_0.06416745963936821"},"_hasShrinkwrap":false}},"readme":"\n \n
\n ![\"iguazu](\"./iguazu.png\")
\n
\n \n
\n\n[](https://badge.fury.io/js/iguazu)\n\n\n> Iguazu is a simple Redux-powered Async Query engine. By using a\n> Higher-Order Component, Iguazu transparently manages dispatching async\n> requests and injecting into React props. Iguazu has an ecosystem of\n> adapters for various querying + caching strategies: [Iguazu RPC](https://github.com/americanexpress/iguazu-rpc), [Iguazu GraphQL](https://github.com/americanexpress/iguazu-graphql) and [Iguazu REST](https://github.com/americanexpress/iguazu-rest).\n\n## ๐ฉโ๐ป Hiring ๐จโ๐ป\n\nWant to get paid for your contributions to `iguazu`?\n> Send your resume to oneamex.careers@aexp.com\n\n## ๐ Table of Contents\n\n* [Features](#-features)\n* [Usage](#-usage)\n* [Upgrading](#-upgrading)\n* [Contributing](#-contributing)\n\n## โจ Features\n\n* Streamlines dispatching, load states, and injecting into React props\n* Parallel and sequential async requests\n* Server-side rendering ready\n\n### Motivation\n\n[react-redux](https://github.com/reduxjs/react-redux) works great for when you want to take data that already exists in state and inject it as props into a React component, but it doesn't help you at all with the flow of loading asynchronous data into state. If a react component relies on asynchronous data you typically have to do three things:\n\n1. Define a load action responsible for fetching the asynchronous data, which should be triggered on mount and when the component receives new props that change what data should be loaded\n2. Define a `mapStateToProps` function and use selectors to get the data out of state\n3. Determine whether the state is actually loaded based on the props the selectors return\n\nIguazu seeks to simplify this flow into one step.\n\n## ๐คนโ Usage\n\n### Installation\n\n```bash\nnpm install --save iguazu\n```\n\n### Base Concepts\n\nIguazu exports a Higher Order Component (HOC) `connectAsync` similar to React Redux's `connect`. Instead of taking a `mapStateToProps` function, it takes a `loadDataAsProps` function. It should return a map where each key is the name of a prop that will contain some asynchronous data and the value is the load function that will load that data if it is not already loaded. The load function must synchronously return an object with the keys `data`, `status`, `error`, and `promise`. The key `data` should be the data returned from the asynchronous call. The key `status` should be either `loading` to signal the asynchronous call is in flight or `complete` to signal it has returned. The key `error` should be a truthy value if there was an error while loading. The key `promise` should be the promise of the asynchronous call.\n\nFor each key defined in the `loadDataAsProps` function, the HOC will pass a prop to the wrapped component that contains the data. It will also pass two function props, `isLoading` and `loadedWithErrors`, which will tell you if any of the async props are still loading or loaded with errors respectively. If you are only interested in a subset of async props, you can pass an array of the props names as the first argument. There will also be a prop named `loadErrors` that maps the load error, if there is one, for each prop. You can use this if you want to more granularly dig into what failed.\n\nExample:\n\n```javascript\n/* actions.js */\nimport React from 'react';\nimport { connectAsync } from 'iguazu';\n\nexport function queryMyData(param) {\n return (dispatch, getState) => {\n const data = getState().path.to.myData[param];\n const status = data ? 'complete' : 'loading';\n const promise = data ? Promise.resolve : dispatch(fetchMyData(param));\n\n return { data, status, promise };\n };\n}\n\nexport function queryMyOtherData(param) { /* Essentially the same as queryMyData */ }\n\n/* MyContainer.jsx */\nfunction MyContainer({\n isLoading,\n loadedWithErrors,\n myData,\n myOtherData,\n}) {\n if (isLoading()) {\n return \n
\n \n
Loading...
;\n }\n\n if (loadedWithErrors()) {\n return Oh no! Something went wrong
;\n }\n\n return (\n \n myData =\n {' '}\n {myData}\n myOtherData =\n {' '}\n {myOtherData}\n
\n );\n}\n\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(queryMyData(ownProps.someParam)),\n myOtherData: () => dispatch(queryMyOtherData(getState().someOtherParam)),\n };\n}\n\nexport default connectAsync({ loadDataAsProps })(MyContainer);\n```\n\nYou can see that by moving the logic responsible for selecting out the cached data and triggering a fetch if needed into the actions makes the components much simpler.\n\n### Advanced Concepts\n\n#### SSR\nThe main benefits of server side rendering are improved perceived speed and SEO. With perceived speed, the general best practice is to get something in front of the user's eyes as fast as possible. Typically that means you shouldn't wait for any data before rendering to string. For SEO, it's more important that you render the full content, and if that content is dynamic, you'll need to wait on some data. Usually not every view is important for SEO, such as logged in views, so the best option is to only preload data you absolutely have to for SEO. For this reason, Iguazu makes SSR data preloading opt in. If you would like a component's data to be loaded prior to rendering on the server, you can add a property named `ssr` with the value of true.\n\nExample:\n\n```javascript\n/* server.js */\nimport express from 'express';\n\nconst app = express();\n/* Component.jsx */\nfunction loadDataAsProps() { /* ... */ }\nloadDataAsProps.ssr = true;\n```\n\n#### Helper methods\nSometimes you might want to enable SSR preloading for a component, but only for some of its data. Iguazu provides some helper methods, `defer` and `noncritical`, to more granularly load data on the server. If you wrap a load function with `defer`, it will not execute the load function at all and will just return a status of `loading`. If you wrap a function with `noncritical`, the load function will execute, but its promise will be caught so that if it rejects it won't cause the Promise.all to reject and return before the other more critical pieces of data have returned.\n\nExample:\n\n```javascript\nimport { defer, noncritical } from 'iguazu';\n\nfunction loadDataAsProps() {\n return {\n clientOnlyData: defer(() => dispatch(loadClientData())),\n tryToLoadOnServerData: noncritical(() => dispatch(loadIffyData())),\n };\n}\n```\n\nIguazu will also pass a parameter to the load function that tells it whether it is running on the server or not. You might want to use this if you expect data to have a specific shape when it is not loaded, because `defer` will just return data as undefined.\n\nExample:\n\n```javascript\nfunction MyComponent({ someData }) {\n return - {someData.list.map((item) =>
- {item} )}
Loading...
);\n }\n\n return (\n \n
\n );\n}\n\nfunction loadDataAsProps({ store, ownProps }) {\n return {\n ComponentA: () => iguazuReduce(ComponentA.loadDataAsProps)({\n store, ownProps: { someParam: 'someParam' },\n }),\n ComponentB: () => iguazuReduce(ComponentB.loadDataAsProps)({ store, ownProps: {} }),\n };\n}\n```\n\n#### Sequencing\n\nQuite often you need the results of one asynchronous call to get the inputs for another call. One way to do this is by simply using components.\n\nExample:\n\n```javascript\nimport React from 'react';\nimport { connectAsync } from 'iguazu';\n\nfunction Parent({ isLoading, parent }) {\n if (isLoading()) {\n return Loading Your Profile...
;\n }\n\n return (\n \n
\n );\n}\n\nfunction parentLoadDataAsProps({ store: { dispatch } }) {\n return {\n parents: () => dispatch(loadLoggedInParent()),\n };\n}\n\nconst ParentContainer = connectAsync({ loadDataAsProps: parentLoadDataAsProps })(Parent);\n\nfunction Kids({ isLoading, kids }) {\n if (isLoading()) {\n return \n You:\n
\n Loading Kids...
;\n }\n\n return (\n \n Kids:\n {kids.map((kid) => (
\n );\n}\n\nfunction kidsLoadDataAsProps({ store: { dispatch }, ownProps: { parentId } }) {\n return {\n kids: () => dispatch(loadKidsByParent(parentId)),\n };\n}\n\nconst KidsContainer = connectAsync({ loadDataAsProps: kidsLoadDataAsProps })(Kids);\n\nfunction PersonInfo({ info: { name, age } }) {\n return (\n \n \n name:\n {' '}\n {name}\n \n \n age:\n {' '}\n {age}\n \n
\n );\n}\n```\n\nSuppose you want to synchronize the parent and kid components so that you show a loading spinner until they are both done loading their data. Or maybe you only have one component that needs some sequenced data and it doesn't make sense to create a new component for each nested piece of data. In these cases you can use the load helper, `sequence`. You can pass it an array of load functions that need to run in order and depend on data returned from previous functions.\n\nExample:\n\n```javascript\nimport React from 'react';\nimport { connectAsync, sequence } from 'iguazu';\n\nfunction Parent({ isLoading, parent, kids }) {\n if (isLoading()) {\n return Loading Your Profile...
;\n }\n\n return (\n \n
\n );\n}\n\nfunction parentLoadDataAsProps({ store: { dispatch } }) {\n const sequenceLoadFunctions = sequence([\n { key: 'parent', handler: () => dispatch(loadLoggedInParent()) },\n { key: 'kids', handler: ({ parent }) => dispatch(loadKidsByParent(parent.id)) },\n ]);\n\n return {\n ...sequenceLoadFunctions,\n };\n}\n\nconst ParentContainer = connectAsync({ loadDataAsProps: parentLoadDataAsProps })(Parent);\n\nfunction Kids({ kids }) {\n return (\n \n You:\n
\n \n Kids:\n {kids.map((kid) => (
\n );\n}\n\nfunction PersonInfo({ info: { name, age } }) {\n return (\n \n \n name:\n {name}\n \n \n age:\n {age}\n \n
\n );\n}\n\n```\n\nSequenced function handlers are called with the results from all previous functions in case your inputs need to be derived from more than one previous call.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n { key: 'first', handler: () => dispatch(loadFirst()) },\n { key: 'second', handler: ({ first }) => dispatch(loadSecond(first.someParam)) },\n { key: 'third', handler: ({ first, second }) => dispatch(loadThird(first.someParam, second.anotherParam)) },\n]);\n```\n\nIf you need to make two calls in parallel before you make a third, you can use a combination of `iguazuReduce` and `sequence` to accomplish your goal.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n {\n key: 'first',\n handler: iguazuReduce(() => ({\n firstA: () => dispatch(loadFirstA()),\n firstB: () => dispatch(loadFirstB()),\n })),\n },\n {\n key: 'second', handler: ({ first: { firstA, firstB } }) => dispatch(loadSecond(firstA, firstB)),\n },\n]);\n```\n\nFunction handlers require the previous calls to succeed to continue to the next by default. In the\nevent a request returns with an error all remaining calls are flagged with the same error. To bypass\nthis default behavior, you can wrap the function handler in `noncritical` to continue without the\nprevious results.\n\n```javascript\nconst sequenceLoadFunctions = sequence([\n { key: 'first', handler: () => dispatch(loadFirst()) },\n { key: 'second', handler: noncritical(({ first }) => dispatch(loadSecond(first.someParam))) },\n { key: 'unrelated', handler: () => dispatch(loadUnrelated()) },\n]);\n```\n\n#### Updating\n\nIguazu processes updates on Redux state changes by comparing the previous and next responses from `loadDataAsProps` using\n[shallowequal](https://www.npmjs.com/package/shallowequal) by default. You are able to declare a comparator function when\ncalling `connectAsync` to manage how the previous and next responses from `loadDataAsProps` are compared.\n\n```javascript\nimport { deepEqual } from 'fast-equals';\n\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(queryToDeeplyNestedData(ownProps.someParam)),\n myOtherData: () => dispatch(queryMyOtherData(getState().someOtherParam)),\n };\n}\n\nexport default connectAsync({\n loadDataAsProps,\n stateChangeComparator: deepEqual,\n})(MyContainer);\n```\n\n#### Limiting\n\nAs some functions called within `loadDataAsProps` can be expensive when ran on every Redux state change, you are able to declare a limiter function when calling `connectAsync`. Calls to `loadDataAsProps` are not limited by default.\n\n```javascript\nfunction loadDataAsProps({ store, ownProps }) {\n const { dispatch, getState } = store;\n return {\n myData: () => dispatch(expensiveQueryToData(ownProps.someParam)),\n myOtherData: () => dispatch(queryMyOtherData(getState().someOtherParam)),\n };\n}\n\nexport default connectAsync({\n loadDataAsProps,\n stateChangeLimiter: (onStateChange) => debounce(onStateChange, 100),\n})(MyContainer);\n```\n\n#### Updating and Refreshing Data\n\nIn the case that we need to update a remote resource and refresh stale data:\n\n```javascript\n/* MyUpdatingComponent.jsx */\nimport React, { Component, Fragment } from 'react';\nimport { compose } from 'redux';\nimport { connect } from 'react-redux';\nimport { connectAsync } from 'iguazu';\n\nimport { getMyDataAction, updateMyDataAction } from './iguazuActionCreators';\n\nclass MyUpdatingComponent extends Component {\n constructor(props) {\n super(props);\n this.state = { message: '' };\n }\n\n handleClick = () => {\n const { updateMyData, getMyData } = this.props;\n // Send updateMyData request\n const { promise: updateMyDataPromise } = updateMyData('someParam');\n return updateMyDataPromise\n .then(() => {\n // Refresh getMyData to get new results\n const { promise: myDataPromise } = getMyData();\n return myDataPromise;\n })\n .then(() => {\n this.setState({ message: 'Success!' });\n });\n };\n\n render() {\n const { isLoading, loadedWithErrors, myData } = this.props;\n const { message } = this.state;\n\n if (isLoading()) {\n return Loading...
;\n }\n\n if (loadedWithErrors()) {\n return Oh no! Something went wrong
;\n }\n\n return (\n