import { 
fetch, 
type FetchInit, 
type FetchOperation, 
type FetchResponse, 
HttpError
} from "@effectionx/fetch"

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, the request is aborted. 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

API Reference

// Fluent API - single yield*
let data = yield* fetch("/api/users").json();

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

// Traditional API - get response first
let response = yield* fetch("/api/users");
let data = yield* response.json();

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

// POST request with body
let result = yield* fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice" }),
}).expect().json();

// Stream response body
for (let chunk of yield* each(fetch("/large-file").body())) {
  console.log(chunk.length);
  yield* each.next();
}