Registry / api / fetch-multipart-graphql

fetch-multipart-graphql

library2.3.1jsnpmunverified

Cross-browser function to fetch and parse streaming multipart GraphQL responses, enabling support for the @defer directive in GraphQL clients like Apollo Server and Relay Modern. Current stable version is 2.3.1, released with moderate cadence. Key differentiators: supports both fetch and XMLHttpRequest, handles streaming multipart responses out-of-the-box, and works with Relay's Observable pattern. Requires polyfill for TextEncoder/TextDecoder in older browsers.

api

npm install fetch-multipart-graphql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-MULTIPART-GR

fetch-multipart-graphql

apijavascriptv2.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export

✓ import fetchMultipart from 'fetch-multipart-graphql';

✗ const fetchMultipart = require('fetch-multipart-graphql');

Default export is a function. The package is ESM-only; CommonJS require() will not work.

type for options (TypeScript)

✓ import type { FetchMultipartOptions } from 'fetch-multipart-graphql';

✗ import { FetchMultipartOptions } from 'fetch-multipart-graphql';

TypeScript users should use import type for the options type to avoid runtime inclusion.

Named exports (none)

✓ Only default export available.

✗ import { fetchMultipart } from 'fetch-multipart-graphql';

There is no named export; only the default function is exported.

Fetches a multipart GraphQL response with @defer and logs each chunk. Uses credentials: 'include' for cookies.

import fetchMultipart from 'fetch-multipart-graphql'; const query = ` query { viewer { name ...DeferredFields @defer } } fragment DeferredFields on User { email } `; fetchMultipart('/graphql', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ query }), credentials: 'include', onNext: (parts) => { console.log('Received parts:', parts); // parts is an array of GraphQL responses }, onError: (err) => { console.error('Error:', err); }, onComplete: () => { console.log('Stream complete'); } });

Debug

Known issues

gotchaThe package requires TextEncoder/TextDecoder to be available globally. In browsers like IE11 or older Edge, you must provide a polyfill, otherwise requests will fail silently.

fix

Install and import 'text-encoding-utf-8' before using fetchMultipart.

affects: all

breakingIf the server does not return a multipart response (e.g., single JSON response), fetchMultipart will hang because it expects a stream. This is a common pitfall when @defer is not properly configured.

fix

Ensure the server supports multipart responses (e.g., Apollo Server with @defer). Otherwise, use a regular fetch.

affects: all

deprecatedThe onNext callback receives an array of parts. In earlier versions, it received a single part object. If you are migrating, check your callback signature.

fix

Update onNext to expect an array: parts => /* handle array */

affects: >=2.0.0 <2.3.0

gotchaWhen using credentials: 'same-origin' or 'include', the XHR path may have different behavior than fetch in some browsers regarding CORS.

fix

Test your specific browser scenario; consider using fetch if possible.

affects: all

Errors

Common errors & fixes

TextEncoder is not defined

Missing TextEncoder/TextDecoder polyfill in browsers that don't support it natively.

fix

npm install text-encoding-utf-8 and import it before fetchMultipart.

fetchMultipart is not a function

Incorrect import: using named import instead of default import.

fix

Use: import fetchMultipart from 'fetch-multipart-graphql';

Cannot read property 'onNext' of undefined

Missing or incorrectly named options callback (e.g., onNext vs onData).

fix

Provide onNext, onError, and onComplete as options object properties.

Request aborted due to CORS preflight

The request uses credentials or non-simple headers triggering CORS preflight; server must respond with appropriate CORS headers.

fix

Configure server to allow the Origin, methods, and headers.

Upgrade

Version history

2.3.1latest on npm

Audit

Dependencies

text-encoding-utf-8optionalPolyfill required for TextEncoder/TextDecoder in browsers that lack native support (e.g., older Edge, IE11).

Agent activity

41 hits · last 30 days

node

Resources

githubssh://git@github.com/relay-tools/fetch-multipart-graphql ↗

packagefetch-multipart-graphql ↗

homepagehttps://github.com/relay-tools/fetch-multipart-graphql#readme ↗