https://github.com/cxres/prep-fetch
https://github.com/cxres/prep-fetch
Last synced: about 16 hours ago
JSON representation
- Host: GitHub
- URL: https://github.com/cxres/prep-fetch
- Owner: CxRes
- License: mpl-2.0
- Created: 2024-07-08T21:31:03.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-20T01:24:07.000Z (almost 2 years ago)
- Last Synced: 2025-10-02T18:13:26.150Z (9 months ago)
- Language: JavaScript
- Size: 74.2 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PREP Fetch
Prep your [`Fetch`](https://fetch.spec.whatwg.org/) [`Response`](https://fetch.spec.whatwg.org/#responses) to receive [Per Resource Events](https://cxres.github.io/prep/draft-gupta-httpbis-per-resource-events.html) notifications.
PREP Fetch is thin wrapper around [Multipart Fetch](https://npmjs.com/package/multipart-fetch) that pre-processes the response to a PREP request giving you separate representation and notification streams.
## Installation
### Browser
You can use PREP Fetch directly in the browser as shown below:
```html
import prepFetch from "https://path/to/prep-fetch/dist/browser.js";
```
#### CDN
Replace the dummy import path with a link to the bundle provided by your favourite CDN. Find the links/link formats at:
- [jsdelivr](https://www.jsdelivr.com/package/npm/prep-fetch)
- [unpkg](https://www.unpkg.com/)
#### Local
Alternatively you can download the package from npm and use it locally. If you have npm installed, an easy way to do this is:
```sh
npm pack prep-fetch
```
Unpack the downloaded `.tgz` file and point the import path to `dist/browser.min.js`.
### JavaScript Runtimes
Install PREP Fetch using your favorite package manager:
```sh
add prep-fetch
```
You can now `import` PREP Fetch in your project, as usual:
```js
import prepFetch from "prep-fetch";
```
On Deno, you can link to the bundle directly from source, just like in the browser, or export it from `deps.ts`.
## Usage
1. Request PREP notifications using `Fetch` and invoke PREP Fetch on the response:
```js
let response;
try {
response = await fetch("https://example.org/source/of/events", {
headers: {
"accept-events": '"prep"',
},
});
} catch (error) {
// Handle any network errors
}
const prepResponse = prepFetch(response);
```
2. Read representation, say, as text:
```js
const representation = await prepResponse.getRepresentation();
console.log(await representation.text());
```
**IMPORTANT**: Read the representation completely before reading notifications as these are being delivered serially on the underlying HTTP response stream.
3. Now get the notifications and iterate over it:
```js
const notifications = await prepResponse.getNotifications();
for await (const notification of notifications) {
// .message parses the Response body as a internet format message
// mime-type: `message/rfc822`
const message = await notification.message();
// output the notification
console.log(message.headers);
// output any body
console.log(await message.body());
}
```
or, if you are using the asyncIterator protocol:
```js
const notifications = await prepResponse.getNotifications();
const notificationsIterator = notifications.notifications();
let { value, done } = await notificationsIterator.next();
while (!done) {
const message = await notification.message();
console.log(await message.body());
({ value, done } = await notificationsIterator.next());
}
```
**IMPORTANT**: Always read each message completely before proceeding to the next notification.
For a more detailed example, see the "should serve notifications" block in `tests/integration/prep-fetch.test.js`.
## Copyright and License
Copyright © 2024, [Rahul Gupta](https://cxres.pages.dev/profile#i) and PREP Fetch contributors.
The source code in this repository is released under the [Mozilla Public License v2.0](./LICENSE).