import { 
coreFetch, 
fetch, 
type Fetch, 
FetchApi, 
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, 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

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();
}