Add doc about z.dehydrateFile #360
Conversation
| @@ -18,7 +18,7 @@ | |||
| "node": ">=8.10.0" | |||
| }, | |||
| "scripts": { | |||
| "docs": "npm run build && node lib/bin/docs.js", | |||
| "docs": "npm run build && ZAPIER_BASE_ENDPOINT='' node lib/bin/docs.js", | |||
There was a problem hiding this comment.
When generating docs, we should always use the production endpoint.
README-source.md
Outdated
| * `request` (optional) - request options. This is where you can specify HTTP headers, parameters, etc. | ||
| * `meta` (optional) - file meta information, which can include `filename`, `contentType`, and `knownLength`. | ||
|
|
||
| > **What's the difference between `z.dehydrateFile` and `z.dehydrate`?** The difference is in the Zap editor. The Zap editor behaves differently to dehydration based on how the pointer was made. If it's made by `z.dehydrate(func, inputData)`, the Zap editor will load the data immediately in the trigger step when users pull the sample. This allows users to map those fields in the subsequent steps. If the pointer is made by `z.dehydrateFile`, the Zap editor won't do that because it's unnecessary. There's nothing in binary file data for users to map in the subsequent steps. |
There was a problem hiding this comment.
I think it's good to call this out, as devs will likely have questions. It might make sense to lead off with something more generic though. Combined with what you wrote, maybe this (made tweaks to try to make it clearer for partners):
The difference has to do with efficiency and when Zapier chooses to hydrate data. Knowing which pointers give us back files helps us delay downloading files until its absolutely necessary.
A good example is users creating Zaps in the Zap Editor. If a pointer is made by `z.dehydrate`, the Zap Editor will hydrate the data immediately after pulling in samples. This allows users to map fields from the hydrated data into the subsequent steps of the Zap. If, however, the pointer is made by `z.dehydrateFile`, the Zap Editor will wait to hydrate the file. There's nothing in binary file data for users to map in the subsequent steps.
I removed "trigger" because a Search like "Find File" can also do dehydration. I also avoided saying "won't load" because, if the user is testing an action and clicks "Create File" we will load the file in the Zap Editor.
There was a problem hiding this comment.
Thanks for the suggestions! Fixed in 447e503.
README-source.md
Outdated
|
|
||
| > **What's the difference between `z.dehydrateFile` and `z.dehydrate`?** The difference is in the Zap editor. The Zap editor behaves differently to dehydration based on how the pointer was made. If it's made by `z.dehydrate(func, inputData)`, the Zap editor will load the data immediately in the trigger step when users pull the sample. This allows users to map those fields in the subsequent steps. If the pointer is made by `z.dehydrateFile`, the Zap editor won't do that because it's unnecessary. There's nothing in binary file data for users to map in the subsequent steps. | ||
|
|
||
| > `z.dehydrateFile` is new in v7.3.0. We used to recommend to use `z.dehydrate(func, inputData)` for files, too. But it's not the case anymore. Please change it to `z.dehydrateFile` for better user expereience in the Zap editor. |
There was a problem hiding this comment.
Please change it to
z.dehydrateFilefor a better user experience.
Couple grammar/spelling tweaks in my line above. Also, I think we can just say better experience in general. Yes, Zap Editor is major improvement at this point, but with some other tweaks we are making server side, it will be better on the server side as well.
There was a problem hiding this comment.
Fixed in 447e503. Thanks!
|
zapier/zapier#19954 and zapier/zapier-platform-core#112 have been merged. Will merge this one when we release CLI 7.3.0. |
Adds doc about
z.dehydrateFile, implemented in: