# @getforma/core/http

Reactive fetch, server-sent events and WebSocket clients with their option and result types.

These browser helpers use the platform's network APIs. Type parameters describe expected values; they do not replace application input validation or server authorization.

Published declaration: [@getforma/core@3.0.0](https://unpkg.com/@getforma/core@3.0.0/dist/http.d.ts).

## Values and functions

### createFetch

Function export

```ts
declare function createFetch<T>(url: string | (() => string), options?: FetchOptions<T>): FetchResult<T>;
```

Create a reactive fetch that exposes data/error/loading as signals.

If `url` is a signal getter (function), an effect auto-refetches when it
changes.

```ts
const { data, loading, error, refetch, abort } = createFetch<User[]>('/api/users');
```

Related declarations: [`FetchOptions`](/docs/3.0/api-http/#symbol-FetchOptions), [`FetchResult`](/docs/3.0/api-http/#symbol-FetchResult)

### createSSE

Function export

```ts
declare function createSSE<T = unknown>(url: string, options?: SSEOptions<T>): SSEConnection<T>;
```

Create a reactive Server-Sent Events connection.

```ts
const sse = createSSE<{ message: string }>('/api/events');
createEffect(() => {
  const msg = sse.data();
  if (msg) console.log(msg.message);
});
```

Related declarations: [`SSEConnection`](/docs/3.0/api-http/#symbol-SSEConnection), [`SSEOptions`](/docs/3.0/api-http/#symbol-SSEOptions)

### createWebSocket

Function export

```ts
declare function createWebSocket<TSend = unknown, TReceive = unknown>(url: string, options?: WSOptions<TReceive>): WSConnection<TSend, TReceive>;
```

Create a reactive WebSocket connection with auto-reconnect.

A closed connection is retried up to `maxReconnects` times. The n-th retry
waits a delay drawn uniformly between 0 and `reconnectInterval * 2^(n-1)`
(full jitter), so the clients of a server that restarts do not all reconnect
in the same instant. A successful open restarts the count.

Verified by: src/http/__tests__/ws-reconnect.test.ts > "with a seeded random source, the n-th reconnect delay lies between 0 and 2^(n-1) s and differs across simulated clients"
Verified by: src/http/__tests__/ws-reconnect.test.ts > "a successful connection restarts the cap at reconnectInterval"

```ts
const ws = createWebSocket<string, ChatMessage>('wss://chat.example.com');
ws.send('hello');
createEffect(() => {
  const msg = ws.data();
  if (msg) console.log(msg);
});
```

Related declarations: [`WSConnection`](/docs/3.0/api-http/#symbol-WSConnection), [`WSOptions`](/docs/3.0/api-http/#symbol-WSOptions)

### fetchJSON

Function export

```ts
declare function fetchJSON<T>(url: string, options?: RequestInit): Promise<T>;
```

One-shot fetch that returns parsed JSON.

```ts
const users = await fetchJSON<User[]>('/api/users');
```

## Exported types

### FetchOptions

Interface export

```ts
interface FetchOptions<T> extends Omit<RequestInit, 'signal'> {
    base?: string;
    params?: Record<string, string>;
    timeout?: number;
    transform?: (data: unknown) => T;
}
```

Forma HTTP - Fetch

Typed fetch wrapper with reactive signal integration.
Zero dependencies — native browser APIs only.

### FetchResult

Interface export

```ts
interface FetchResult<T> {
    data: () => T | null;
    error: () => Error | null;
    loading: () => boolean;
    refetch: () => Promise<void>;
    abort: () => void;
}
```



### SSEConnection

Interface export

```ts
interface SSEConnection<T = unknown> {
    data: () => T | null;
    error: () => Event | null;
    connected: () => boolean;
    close: () => void;
    on(event: string, handler: (data: unknown) => void): () => void;
}
```



### SSEOptions

Interface export

```ts
interface SSEOptions<T = unknown> {
    withCredentials?: boolean;
    headers?: Record<string, string>;
    parse?: (data: string) => T;
}
```

Forma HTTP - Server-Sent Events

Reactive SSE wrapper with signal integration.
Zero dependencies — native browser APIs only.

**`parse`**

Custom parser for incoming messages. Defaults to JSON.parse with raw data fallback.

### WSConnection

Interface export

```ts
interface WSConnection<TSend = unknown, TReceive = unknown> {
    data: () => TReceive | null;
    status: () => WSStatus;
    send(data: TSend): void;
    close(): void;
    on(handler: (data: TReceive) => void): () => void;
}
```



Related declarations: [`WSStatus`](/docs/3.0/api-http/#symbol-WSStatus)

### WSOptions

Interface export

```ts
interface WSOptions<TReceive = unknown> {
    protocols?: string | string[];
    reconnect?: boolean;
    reconnectInterval?: number;
    maxReconnects?: number;
    random?: () => number;
    parse?: (data: string) => TReceive;
}
```



**`reconnectInterval`**

The cap of the first reconnect delay, in ms (default 1000); it doubles each attempt.

**`random`**

The uniform source in [0, 1) the reconnect delay is drawn from. Defaults
to `Math.random`; a test passes a seeded one to replay a run. A value that
is not a function, or a draw outside [0, 1), falls back to `Math.random`.

**`parse`**

Custom parser for incoming messages. Defaults to JSON.parse with raw data fallback.

### WSStatus

Type alias export

```ts
type WSStatus = 'connecting' | 'open' | 'closed' | 'error';
```

Forma HTTP - WebSocket

Reactive WebSocket wrapper with auto-reconnect and signal integration.
Zero dependencies — native browser APIs only.

## Other entry points

[@getforma/core](/docs/3.0/api-core/) · [@getforma/core/runtime](/docs/3.0/api-runtime/) · [@getforma/core/runtime-hardened](/docs/3.0/api-runtime-hardened/) · [@getforma/core/runtime-csp](/docs/3.0/api-runtime-csp/) · [@getforma/core/tc39](/docs/3.0/api-tc39/) · [@getforma/core/storage](/docs/3.0/api-storage/) · [JSX namespace](/docs/3.0/api-jsx/)