added: define fetch docs and quick reference examples #1

JulesPatry · 2019-08-04T17:48:57Z

Created Docs for

defineFetch API
defineFetch share API
CRUD examples
multiple request example

JulesPatry · 2019-08-04T18:02:03Z

docs/API/defineFetch.md

+| Prop      | Type                                                                        | Default    | Description                                                                                                                                                                                                                                                                                                                                   |
+| --------- | --------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`     | string[]                                                                    | required\* | These strings will be used to create a key for the data store.                                                                                                                                                                                                                                                                                |
+| `request` | func (...requestArgs)<br /> Returns -> <br /> func (...resiftServices) <br> | required\* | The `request` function is what will dispatch. The return data is what will be stored and returned in `useFetch`. <br /><br /> `requestArgs` are optional arguments needed for a request. <br /><br /> `resiftServices` are services such as `http` and `dispatch` supplied through Resift that give additional functionality to your request. |


@ricokahler, what are the standards on arguments like these?

Any arguments that are required to make a request but aren't required to identify the fetch should go in the request args, otherwise (if they identify the request) then they should go in the make args

ricokahler

These docs are great. I was a bit strict on the examples because they'll serve a model for others to understand but other than that, they're great

ricokahler · 2019-08-05T16:53:21Z

docs/API/defineFetch-share.md

+| Prop        | Type             | Default    | Description                                                                                                        |
+| ----------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `namespace` | string           | required\* | Another `defineFetch` function sharing the same name space will result them sharing the same key to the data store |
+| `merge`     | func(prev, next) | required\* | `merge` adds customizing functionality before the data is applied to the data store.                               |


merge isn't required (or at least isn't supposed to be). if merge isn't provided, the default behavior is that the next will replace the previous e.g. merge: (_prev, next) => next

Good to know!

I'll update this.

ricokahler · 2019-08-05T16:56:01Z

docs/API/defineFetch-share.md

+  share: {
+    namespace: 'person',
+    // Keep data flow as is
+    merge: (previous, next) => ({ ...previous, ...next }),


in context of the comment above, you could omit this logic. I think a good example of merge would be to update a single person in the list after a PUT, otherwise, I think it makes sense to prefer replacement instead of merging (i.e. (prev, next) => next vs (prev, next) => ({...prev, ...next}))

ricokahler · 2019-08-05T16:56:22Z

docs/API/defineFetch-share.md

+    // Keep data flow as is
+    merge: (previous, next) => ({ ...previous, ...next }),
+  },
+  make: (personName: string) => ({


You have personName here by personId down there.

ricokahler · 2019-08-05T16:58:03Z

docs/API/defineFetch-share.md

+```
+
+```tsx
+// Example container using `definefetch` above


For the open source, docs, I don't think we should suggest the container pattern. it's not something I see in the community and is probably unique to us

@ricokahler, what do you recommend?

I think it makes sense to just call this component <Person /> or <Profile />. Instead of putting this logic in a container component, let's just make the example put it in the component itself.

Unless they've used redux before, I just don't think people will know what a container component is. And from the mouth of the prophet himself:

Update from 2019: I wrote this article a long time ago and my views have since evolved. In particular, I don’t suggest splitting your components [into container and presentational components] anymore. If you find it natural in your codebase, this pattern can be handy. But I’ve seen it enforced without any necessity and with almost dogmatic fervor far too many times. The main reason I found it useful was because it let me separate complex stateful logic from other aspects of the component. Hooks let me do the same thing without an arbitrary division. This text is left intact for historical reasons but don’t take it too seriously.

link

ricokahler · 2019-08-05T17:16:06Z

docs/API/defineFetch-share.md

+    dispatch(getPerson());
+  }, []);
+
+  const handleEditPerson = useCallback(


I don't think we suggest using useCallback

agreed since it complicates things.

ricokahler · 2019-08-05T19:19:24Z

docs/examples/defineFetch-HTTP-services.md

+  share: {
+    namespace: 'person',
+    // Keep data flow as is
+    merge: (previous, next) => ({ ...previous, ...next }),


In this case, I think it would be better to omit merge to prefer the default merge behavior (replacement)

ricokahler · 2019-08-05T19:19:58Z

docs/examples/defineFetch-HTTP-services.md

+    // Keep data flow as is
+    merge: (previous, next) => ({ ...previous, ...next }),
+  },
+  make: (personName: string) => ({


I think you meant personId?

ricokahler · 2019-08-05T19:20:46Z

docs/examples/defineFetch-HTTP-services.md

+    namespace: 'person',
+    merge: (previous, next) => {
+      // Customize and add data
+      return { ...previous, ...next, lastEdited: new Date() }


I don't think this is a valid use case of merge. In this case, it would be better to add lastEdited as part of the request

Ah I see. You are spot on.

ricokahler · 2019-08-05T20:32:08Z

docs/examples/defineFetch-HTTP-services.md

+      return { ...previous, ...next, lastEdited: new Date() }
+    },
+  },
+  make: (personName: string) => ({


same comment as above, i think you meant personId?

ricokahler · 2019-08-05T20:51:10Z

docs/examples/multiple-request-defineFetch.md

+      const getPeople = makeGetPeople();
+      dispatch(getPeople());
+
+      return errors.length ? errors : null;


I don't think it's a good idea to return a list of errors here. In real usage, it might be better to throw if there are any errors.

Since this is an example, I think the easiest way to teach the concept is to just sequentially delete all the people using async, await, and a normal for of loop.

If there is any error, it will cause the whole fetch to stop and error status to show up

Change it to how you would like. I have updated it to now log the error instead of returning all errors.

…t/Resift into feature/defineFetch-docs

ricokahler · 2019-08-28T04:42:06Z

@JulesPatry I merged the API docs generator into #2 . Pull the latest from that branch and then you can update defineFetch.d.ts with your API docs in there.

Run this command locally to get the API docs to generate. Unfortunately there is no hot reloading for the .d.ts files yet.

cd website
node ./generate-api-docs && npm start

ricokahler · 2019-10-14T19:49:44Z

I'm closing this because we changed how API documentation works since this PR was opened, however, I'll come back to this PR and copy and paste your docs to where they should be in the typings. I'll give you co-author too

JulesPatry added 3 commits August 4, 2019 13:47

added: define fetch docs and quick reference examples

cf171f8

Update defineFetch-share.md

ac8a5fa

Update multiple-request-defineFetch.md

4ac589d

JulesPatry commented Aug 4, 2019

View reviewed changes

ricokahler suggested changes Aug 5, 2019

View reviewed changes

JulesPatry added 4 commits August 6, 2019 14:18

doc update

178193a

Merge branch 'feature/defineFetch-docs' of https://github.com/JustSif…

787ffb2

…t/Resift into feature/defineFetch-docs

responded to pr comments part 1

109f321

responded to more comments in the PR

03a37a8

This was referenced Aug 22, 2019

API documentation #8

Closed

Initial documentation #7

Closed

ricokahler added this to the v0.1.0 milestone Aug 23, 2019

ricokahler closed this Oct 14, 2019

ricokahler deleted the feature/defineFetch-docs branch October 14, 2019 19:51

ricokahler restored the feature/defineFetch-docs branch October 14, 2019 19:51

ricokahler deleted the feature/defineFetch-docs branch November 16, 2019 05:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

added: define fetch docs and quick reference examples #1

added: define fetch docs and quick reference examples #1

JulesPatry commented Aug 4, 2019

JulesPatry Aug 4, 2019

ricokahler Aug 12, 2019

ricokahler left a comment

ricokahler Aug 5, 2019

JulesPatry Aug 6, 2019

JulesPatry Aug 6, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 6, 2019

JulesPatry Aug 6, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 6, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 6, 2019

ricokahler Aug 12, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 6, 2019

ricokahler Aug 5, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 8, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 8, 2019

ricokahler Aug 5, 2019

ricokahler Aug 5, 2019

JulesPatry Aug 8, 2019

ricokahler commented Aug 28, 2019

ricokahler commented Oct 14, 2019

added: define fetch docs and quick reference examples #1

added: define fetch docs and quick reference examples #1

Conversation

JulesPatry commented Aug 4, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ricokahler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ricokahler commented Aug 28, 2019

ricokahler commented Oct 14, 2019