Schwi

Motivation

While building JS/TS librairies for LiterateInk and Papillon, I had a lot of issues concerning compatibility across runtimes.

Let's see an example about Set-Cookie headers.

// Browsers, Bun, Deno, Node.js
new Headers([
  ["Set-Cookie", "hello=1"],
  ["Set-Cookie", "world=2"],
]).getSetCookie();
// This simply works, we get the following.
// > ["hello=1", "world=2"]

// React Native
new Headers([
  ["Set-Cookie", "hello=1"],
  ["Set-Cookie", "world=2"],
]).getSetCookie();
// This does NOT work because they're using
// https://www.npmjs.com/package/whatwg-fetch
// and `getSetCookie` is not implemented there.
// You can fix this by using the following code instead:
new Headers([
  ["Set-Cookie", "hello=1"],
  ["Set-Cookie", "world=2"],
]).get("Set-Cookie");
// > "hello=1, world=2"
// Now this works, but as you can see the output is not the same...
// We have to handle this properly !

So we have to use different code for React Native and the rest of the runtimes and also handle the fact that the output is not the same ! As you can see, this is very frustrating.

Now let's query an API that is not allowing CORS through Tauri.

// Tauri
const response = await fetch("https://api.example.com");
// > Error: CORS
// To fix this issue, you have to instead use the
// `fetch` API from official Tauri plugins.

// Node.js, Bun, Deno, React Native
const response = await fetch("https://api.example.com");
// > 200 OK
// Simply works !

Now you can see that the CORS policy is not the same across runtimes. It's completely normal and compliant behavior, but it can be frustrating when you want to build a cross-platform library that should work everywhere.

Note that you should really only use this library if you want to build a cross-platform library which needs to either interact with Set-Cookie headers (such as Set-Cookie), either manipulate request headers (such as User-Agent, Origin or Referer) or simply ignore CORS.

The goal of this library is to provide a consistent API across runtimes. This means that you can use the same HTTP API across all runtimes, and it will behave the same way.

Features

• Implements a working getSetCookie function on HeaderMap, even on React Native
• Tauri's native HTTP plugin is automatically used when available
• Uses undici on Bun to prevent strange headers issues
• Provides optional toXML() and toHTML() helpers in HttpResponse for easier access with other packages, see installation section to enable those
• Opt in using a native implementation of fetch on React Native

Installation

npm add schwi
pnpm add schwi
yarn add schwi
bun add schwi

Tauri

You're required to setup Tauri's HTTP plugin, see https://tauri.app/plugin/http-client/ for more details.

tauri add http

Do not forget to configure capabilities for the Tauri HTTP client.

React Native

You can optionally opt-in react-native-real-fetch to use features that are not supported with the default fetch implementation in React Native.

If you don't have the following packages installed, it'll use the global fetch.

Bare

npm add [email protected] react-native-nitro-modules@^0.29.3
cd ios && pod install

Expo

npx expo add [email protected] react-native-nitro-modules@^0.29.3
npx expo prebuild

Optional Features

# Enables `HttpResponse.toHTML()`, otherwise you'll get an error during runtime.
pnpm add cheerio

# Enables `HttpResponse.toXML()`, otherwise you'll get an error during runtime.
pnpm add fast-xml-parser

Usage

import { HttpRequest, send } from "schwi";

const request = new HttpRequest.Builder("https://postman-echo.com/cookies/set")
  .setUrlSearchParameter("foo1", "bar1")
  .setUrlSearchParameter("foo2", "bar2")
  .setRedirection(HttpRequest.Redirection.MANUAL)
  .build();

const response = await send(request);
console.log(response.headers.getSetCookie());

const body = await response.toString();
console.log(body);

You can browse the examples folder to see how to use the library in different runtimes.