fetch

Effection-native fetch with structured concurrency and streaming response support.

Installation

npm install @effectionx/fetch effection

Usage

import { main } from "effection";
import { fetch } from "@effectionx/fetch";

await main(function* () {
  let users = yield* fetch("https://api.example.com/users").json();
  console.log(users);
});

Fluent API

Chain methods directly on fetch() for concise one-liners:

// JSON
let data = yield* fetch("https://api.example.com/users").json();

// Text
let html = yield* fetch("https://example.com").text();

// With validation - throws HttpError on non-2xx
let data = yield* fetch("https://api.example.com/users").expect().json();

Traditional API

You can also get the response first, then consume the body:

let response = yield* fetch("https://api.example.com/users");
let data = yield* response.json();

Streaming response bodies

import { each } from "effection";
import { fetch } from "@effectionx/fetch";

function* example() {
  for (let chunk of yield* each(fetch("https://example.com/large-file.bin").body())) {
    console.log(chunk.length);
    yield* each.next();
  }
}

Concurrent requests

import { all } from "effection";
import { fetch } from "@effectionx/fetch";

function* fetchMultiple() {
  let [users, posts, comments] = yield* all([
    fetch("https://api.example.com/users").json(),
    fetch("https://api.example.com/posts").json(),
    fetch("https://api.example.com/comments").json(),
  ]);

  return { users, posts, comments };
}

Validate JSON while parsing

import { fetch } from "@effectionx/fetch";

interface User {
  id: string;
  name: string;
}

function parseUser(value: unknown): User {
  if (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value
  ) {
    return value as User;
  }

  throw new Error("invalid user payload");
}

function* getUser() {
  return yield* fetch("https://api.example.com/user").json(parseUser);
}

Handle non-2xx responses

import { HttpError, fetch } from "@effectionx/fetch";

function* getUser(id: string) {
  try {
    return yield* fetch(`https://api.example.com/users/${id}`).expect().json();
  } catch (error) {
    if (error instanceof HttpError) {
      console.error(error.status, error.statusText);
    }
    throw error;
  }
}

API

fetch(input, init?)

Returns a FetchOperation that supports both fluent chaining and traditional usage.

• input - URL string, URL object, or Request object
• init - Optional FetchInit options (same as RequestInit but without signal)

Cancellation is handled automatically via Effection's structured concurrency. When the scope exits, an in-flight request is aborted. A native fetch that has already settled is left intact. The signal option is intentionally omitted since Effection manages cancellation for you.

FetchOperation

Chainable fetch operation returned by fetch().

• json<T>(), json<T>(parse) - parse response as JSON
• text() - get response as text
• arrayBuffer() - get response as ArrayBuffer
• blob() - get response as Blob
• formData() - get response as FormData
• body() - stream response body as Stream<Uint8Array, void>
• expect() - returns a new FetchOperation that throws HttpError on non-2xx

Can also be yielded directly to get a FetchResponse:

let response = yield* fetch("https://api.example.com/users");

FetchResponse

Effection wrapper around native Response with operation-based body readers.

• json<T>(), json<T>(parse)
• text()
• arrayBuffer()
• blob()
• formData()
• body(): Stream<Uint8Array, void>
• expect() - throws HttpError for non-2xx responses
• raw - access the underlying native Response