HTTP

HttpClient is an Effect service that wraps Convex’s ConvexHttpClient. It provides query, mutation, and action methods that accept refs and automatically encode args and decode return values through the schemas defined in your function specs. It works in any JavaScript runtime that supports fetch.

Setup

Create the HttpClient layer by passing your Convex deployment URL.

import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

const HttpClientLive = HttpClient.layer("https://example-123.convex.cloud");

The layer can then be provided to any Effect that uses the HttpClient service.

Calling functions

Use the HttpClient service inside Effect.gen to call your functions with refs, the same way you would with @confect/react hooks or @confect/test.

import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);

  const noteId = yield* client.mutation(refs.public.notes.insert, {
    text: "Hello from the server",
  });

  const result = yield* client.action(refs.public.random.getNumber);
});

Each method returns an Effect that can fail with HttpClientError (wrapping transport-level errors) or ParseResult.ParseError (if schema encoding or decoding fails).

Typed errors

When a ref’s spec declares an error schema, the decoded error is added to the returned Effect’s error channel alongside HttpClientError and ParseError. See Error Handling for how to declare error schemas.

import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const lookup = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  return yield* client.query(refs.public.notes.getOrFail, { noteId });
});
// Effect.Effect<Note, NoteNotFound | HttpClientError | ParseError, HttpClient.HttpClient>

Recover from a typed failure with Effect.catchTag (or any other Effect error combinator).

lookup.pipe(
  Effect.catchTag("NoteNotFound", (error) =>
    Effect.succeed(`Note ${error.noteId} not found.`),
  ),
);

Authentication

Set or clear the auth token before making authenticated requests.

Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  yield* client.setAuth(token);

  const identity = yield* client.query(refs.public.auth.getIdentity);

  yield* client.clearAuth;
});

Running programs

Provide the HttpClient layer when running your program.

import { HttpClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";

const HttpClientLive = HttpClient.layer("https://example-123.convex.cloud");

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);
  yield* Console.log(notes);
});

Effect.runPromise(program.pipe(Effect.provide(HttpClientLive)));

Differences from `ConvexHttpClient`

`ConvexHttpClient`	`HttpClient`
Functions referenced via `api.module.fn`	Functions referenced via `refs`
Args passed directly to Convex as-is	Args are schema-encoded from `Type` to `Encoded` before sending
Return values received directly as-is	Return values are schema-decoded from `Encoded` to `Type`
Methods return `Promise`	Methods return `Effect` with typed errors

Getting Started

Concepts

Server

Clients

Guides

Setup

Calling functions

Typed errors

Authentication

Running programs

Differences from `ConvexHttpClient`

​Setup

​Calling functions

​Typed errors

​Authentication

​Running programs

​Differences from ConvexHttpClient

Setup

Calling functions

Typed errors

Authentication

Running programs

Differences from `ConvexHttpClient`