Eden (@elysia/eden)

To use Eden for fully type-safe Elysia client communication, install both elysia and @elysia/eden using bun:

bun add elysia @elysia/eden

EdenTreaty automatically maps Elysia route parameters (prefixed with :) to function arguments.

• Required Parameters: If a route is defined as /:id, the client will require an object containing id as a string or number.
• Optional Parameters: If a route is defined as /:id?, the parameter is treated as optional.

When calling these routes, the path parameters are passed as the first argument to the generated function, followed by the body (if applicable) and options (for headers/fetch config).

// If Elysia route is: app.get('/user/:id', ...)
// EdenTreaty usage:
const { data } = await client.api.user[':id']({ id: '123' });

// If Elysia route is: app.get('/user/:id?', ...)
// EdenTreaty usage:
const { data } = await client.api.user[':id']({ id: '123' });
const { data } = await client.api.user[':id']({}); // id is optional

EdenTreaty automatically detects if your request body contains File or FileList objects (or is a plain object containing them). If it does, it automatically converts the request into a FormData object.

This works in both browser and server environments (using Blob on the server). It supports:

• Single File objects.
• FileList objects.
• Arrays containing File objects.

When FormData is used, the Content-Type header is managed automatically to ensure the boundary is correctly set.

// If the server expects multipart/form-data
const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement
const file = fileInput.files?.[0]

if (file) {
    await client.upload.post({
        file, // Automatically converted to FormData
        description: 'My profile picture'
    })
}

The edenFetch client automatically manages Content-Type headers and body serialization:

• JSON: If the body is a plain object and no content-type is set, it automatically calls JSON.stringify(body) and sets the header to application/json.
• FormData/URLSearchParams: If the body is an instance of FormData or URLSearchParams, it is sent as-is without manual stringification.
• Query Parameters: The query object is automatically converted into a URL search string (e.g., ?key=value). Null or undefined values in the query object are filtered out before transmission.

Eden Treaty supports WebSocket connections through the .subscribe() method. When .subscribe() is called on a path, it returns an EdenWS instance instead of a standard fetch promise. The protocol (WS vs WSS) is automatically determined based on the base domain's protocol.

// If your Elysia app has a websocket route at /ws
const ws = client.ws.subscribe()

ws.send('hello')
ws.addEventListener('message', (event) => {
  console.log(event.data)
})

Every request made via the edenFetch client returns a promise that resolves to a response object. This object follows a consistent shape regardless of whether the request succeeded or failed.

Response Shape:

• data: The parsed response body (e.g., JSON, ArrayBuffer, or FormData). Returns null if an error occurred.
• error: An EdenFetchError instance if the request failed, otherwise null.
• status: The HTTP status code returned by the server.
• headers: The Headers object from the response.
• retry: A function that, when called, re-executes the exact same request. This is useful for implementing retry logic.

const { data, error, status, retry } = await client.endpoint.get()

if (error) {
  console.error(`Request failed with status ${status}`)
  // You can attempt to retry the request
  const retryData = await retry()
}

When initializing an EdenTreaty client, you can provide a Config object to customize how requests are handled. This allows you to set default fetch options, provide a custom fetch implementation, or define global response transformations.

Key configuration options:

• $fetch: Default options to pass to the standard fetch API (RequestInit).
• fetcher: A custom function to replace the default fetch implementation.
• transform: A Transform function (or array of functions) applied to responses globally.

const config: EdenTreaty.Config = {
    $fetch: {
        mode: 'cors'
    },
    fetcher: customFetcher,
    transform: (response) => {
        // transform logic
        return response;
    }
};

When initializing edenFetch, you can provide a configuration object to customize behavior globally for all requests made by that client instance.

Supported configuration options:

• fetcher: A custom fetch implementation (defaults to globalThis.fetch).
• throwHttpError: A global setting to determine if HTTP error statuses should throw an EdenFetchError or return an error object.

const client = edenFetch<App>('http://localhost:3000', {
  fetcher: myCustomFetcher,
  throwHttpError: true
})