PREP Fetch

Prep your Fetch Response to receive Per Resource Events notifications.

PREP Fetch is thin wrapper around 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:

<script type="module">
  import prepFetch from "https://path/to/prep-fetch/dist/browser.js";
</script>

CDN

Replace the dummy import path with a link to the bundle provided by your favourite CDN. Find the links/link formats at:

• jsdelivr
• unpkg

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:

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:

<npm|pnpm|yarn|bun> add prep-fetch

You can now import PREP Fetch in your project, as usual:

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:

   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:

   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:

   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:

   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 and PREP Fetch contributors.

The source code in this repository is released under the Mozilla Public License v2.0.