Class RestVirClient<ClientApi>

Package

@rest-vir/api

Type Parameters

const ClientApi extends ApiDefinition

Index

Constructors

constructor

new RestVirClient<const ClientApi extends ApiDefinition>(
    api: Readonly<ClientApi>,
    baseUrl: string,
    fetchOverride?: ClientFetch,
    webSocketConstructor?: new (
        ...params: WebSocketConnectWebSocketConstructorParams,
    ) => CommonWebSocket,
): RestVirClient<ClientApi>
Type Parameters
- const ClientApi extends ApiDefinition
Parameters
- api: Readonly<ClientApi>
- baseUrl: string
  All route paths are joined to this URL.
- OptionalfetchOverride: ClientFetch
  Optional fetch override to wrap or reimplement the native fetch function.
- OptionalwebSocketConstructor: new (...params: WebSocketConnectWebSocketConstructorParams) => CommonWebSocket
  Optional WebSocket constructor used as the fallback when RestVirClient.connectWebSocket is called without an explicit webSocketConstructor param.
Returns RestVirClient<ClientApi>
- Defined in packages/api/src/client.ts:62

Properties

`Readonly`api

api: Readonly<ClientApi>

baseUrl

baseUrl: string

All route paths are joined to this URL.

`Optional`fetchOverride

fetchOverride?: ClientFetch

Optional fetch override to wrap or reimplement the native fetch function.

`Optional`webSocketConstructor

webSocketConstructor?: new (
...params: WebSocketConnectWebSocketConstructorParams,
) => CommonWebSocket

Optional WebSocket constructor used as the fallback when RestVirClient.connectWebSocket is called without an explicit webSocketConstructor param.

Methods

buildEndpointRequestInit

buildEndpointRequestInit<
    const Endpoint extends
        EndpointDefinition & { path: keyof ClientApi["endpoints"] },
    const Method extends "GET"
    | "PUT"
    | "POST"
    | "DELETE"
    | "PATCH"
    | "TRACE",
>(
    endpoint: Endpoint,
    method: Method,
    params:
        | SetNullishPropertiesAsOptional<
            {
                fetchOverride: ClientFetch
                | undefined;
                options: Omit<RequestInit, "body" | "method"> | undefined;
                pathParams: ExtractPathParams<
                    NoInfer<Endpoint> extends { path: string }
                        ? ({ path: string } & NoInfer<Endpoint>)["path"]
                        : typeof NoParam,
                >;
                requestData: EndpointRequestType<NoInfer<Endpoint>, NoInfer<Method>>;
                requiredHeaders: EndpointRequestHeadersType<
                    ExtractEndpointMethodDefinitionWithNoParam<
                        NoInfer<Endpoint>,
                        NoInfer<Method>,
                    >,
                >;
                searchParams: RouteSearchParamsType<
                    ExtractEndpointMethodDefinition<NoInfer<Endpoint>, NoInfer<Method>>,
                >;
                skipAutomaticContentTypeHeader: boolean | undefined;
            },
        >
        | undefined,
): { requestInit: RequestInit; url: string }
Type Parameters
- const Endpoint extends EndpointDefinition & { path: keyof ClientApi["endpoints"] }
- const Method extends "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "TRACE"
Parameters
- endpoint: Endpoint
- method: Method
- params:
      | SetNullishPropertiesAsOptional<
          {
              fetchOverride: ClientFetch
              | undefined;
              options: Omit<RequestInit, "body" | "method"> | undefined;
              pathParams: ExtractPathParams<
                  NoInfer<Endpoint> extends { path: string }
                      ? ({ path: string } & NoInfer<Endpoint>)["path"]
                      : typeof NoParam,
              >;
              requestData: EndpointRequestType<NoInfer<Endpoint>, NoInfer<Method>>;
              requiredHeaders: EndpointRequestHeadersType<
                  ExtractEndpointMethodDefinitionWithNoParam<
                      NoInfer<Endpoint>,
                      NoInfer<Method>,
                  >,
              >;
              searchParams: RouteSearchParamsType<
                  ExtractEndpointMethodDefinition<NoInfer<Endpoint>, NoInfer<Method>>,
              >;
              skipAutomaticContentTypeHeader: boolean | undefined;
          },
      >
      | undefined
Returns { requestInit: RequestInit; url: string }
Throws
Error if the given params are invalid for the given endpoint.
- Defined in packages/api/src/client.ts:237

buildEndpointUrl

buildEndpointUrl<
    const Endpoint extends
        EndpointDefinition & { path: keyof ClientApi["endpoints"] },
    const Method extends "GET"
    | "PUT"
    | "POST"
    | "DELETE"
    | "PATCH"
    | "TRACE",
>(
    endpoint: Endpoint,
    method: Method,
    params: Readonly<
        SetNullishPropertiesAsOptional<
            {
                pathParams: ExtractPathParams<NoInfer<Endpoint>["path"]>;
                searchParams: RouteSearchParamsType<
                    ExtractEndpointMethodDefinition<NoInfer<Endpoint>, NoInfer<Method>>,
                >;
            },
        >,
    >,
): string
Type Parameters
- const Endpoint extends EndpointDefinition & { path: keyof ClientApi["endpoints"] }
- const Method extends "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "TRACE"
Parameters
- endpoint: Endpoint
- method: Method
- params: Readonly<
      SetNullishPropertiesAsOptional<
          {
              pathParams: ExtractPathParams<NoInfer<Endpoint>["path"]>;
              searchParams: RouteSearchParamsType<
                  ExtractEndpointMethodDefinition<NoInfer<Endpoint>, NoInfer<Method>>,
              >;
          },
      >,
  >
Returns string
Throws
Error if given searchParams or pathParams are invalid for the given endpoint or path (respectively).
- Defined in packages/api/src/client.ts:187

buildWebSocketUrl

buildWebSocketUrl<
    const ThisWebSocket extends
        | typeof NoParam
        | BaseWebSocketDefinition & { customProps?: UnknownObject } & BaseCommonRouteDefinition & {
            path: keyof ClientApi["webSockets"];
        } = typeof NoParam,
    WebSocketClass extends typeof NoParam
    | CommonWebSocket = typeof NoParam,
>(
    webSocket: ThisWebSocket,
    webSocketParams:
        | SetNullishPropertiesAsOptional<
            {
                listeners: ConnectWebSocketListeners<
                    NoInfer<ThisWebSocket>,
                    WebSocketClass,
                >;
                pathParams: ExtractPathParams<
                    NoInfer<ThisWebSocket> extends { path: string }
                        ? ({ path: string } & NoInfer<ThisWebSocket>)["path"]
                        : typeof NoParam,
                >;
                protocols: WebSocketConnectProtocolType<NoInfer<ThisWebSocket>>;
                searchParams: RouteSearchParamsType<NoInfer<ThisWebSocket>>;
                webSocketConstructor?: WebSocketConnectWebSocketConstructor<
                    WebSocketClass,
                >;
            },
        >
        | undefined,
): string
Type Parameters
- const ThisWebSocket extends
      | typeof NoParam
      | BaseWebSocketDefinition & { customProps?: UnknownObject } & BaseCommonRouteDefinition & {
          path: keyof ClientApi["webSockets"];
      } = typeof NoParam
- WebSocketClass extends typeof NoParam | CommonWebSocket = typeof NoParam
Parameters
- webSocket: ThisWebSocket
- webSocketParams:
      | SetNullishPropertiesAsOptional<
          {
              listeners: ConnectWebSocketListeners<
                  NoInfer<ThisWebSocket>,
                  WebSocketClass,
              >;
              pathParams: ExtractPathParams<
                  NoInfer<ThisWebSocket> extends { path: string }
                      ? ({ path: string } & NoInfer<ThisWebSocket>)["path"]
                      : typeof NoParam,
              >;
              protocols: WebSocketConnectProtocolType<NoInfer<ThisWebSocket>>;
              searchParams: RouteSearchParamsType<NoInfer<ThisWebSocket>>;
              webSocketConstructor?: WebSocketConnectWebSocketConstructor<
                  WebSocketClass,
              >;
          },
      >
      | undefined
Returns string
- Defined in packages/api/src/client.ts:372

connectWebSocket

connectWebSocket<
    const ThisWebSocket extends
        BaseWebSocketDefinition & { customProps?: UnknownObject } & BaseCommonRouteDefinition & {
            path: keyof ClientApi["webSockets"];
        },
    WebSocketClass extends CommonWebSocket,
>(
    webSocket: ThisWebSocket,
    ...restParams: WebSocketConnectParams<
        NoInfer<ThisWebSocket>,
        WebSocketClass,
    >,
): Promise<
    OverwriteWebSocketMethods<WebSocketClass, OnClient, ThisWebSocket>,
>
Type Parameters
- const ThisWebSocket extends BaseWebSocketDefinition & { customProps?: UnknownObject } & BaseCommonRouteDefinition & {
  path: keyof ClientApi["webSockets"];
  }
- WebSocketClass extends CommonWebSocket
Parameters
- webSocket: ThisWebSocket
- ...restParams: WebSocketConnectParams<NoInfer<ThisWebSocket>, WebSocketClass>
Returns Promise<OverwriteWebSocketMethods<WebSocketClass, OnClient, ThisWebSocket>>
- Defined in packages/api/src/client.ts:337

fetch

fetch<
    const Endpoint extends
        EndpointDefinition & { path: keyof ClientApi["endpoints"] },
>(
    endpoint: Endpoint,
): {
    [Method in "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "TRACE"]: BivariantFunction<
        EndpointFetchParams<NoInfer<Endpoint>, Method>,
        Promise<
            If<
                IsAny<
                    DefinedEndpointFetchOutputs<Endpoint, Method, true> & {
                        unexpectedError: UnknownFetchOutput<true>;
                    },
                >,
                any,
                If<
                    IsNever<
                        DefinedEndpointFetchOutputs<Endpoint, Method, true> & {
                            unexpectedError: UnknownFetchOutput<true>;
                        },
                    >,
                    never,
                    If<
                        IsNever<
                            | "unexpectedError"
                            | keyof DefinedEndpointFetchOutputs<Endpoint, Method, true>,
                        >,
                        never,
                        _RequireExactlyOne<
                            DefinedEndpointFetchOutputs<Endpoint, Method, true> & {
                                unexpectedError: UnknownFetchOutput<true>;
                            },
                            If<
                                IsAny<"unexpectedError" | keyof (...)>,

                                    | "unexpectedError"
                                    | keyof DefinedEndpointFetchOutputs<(...), (...), (...)>,

                                    | "unexpectedError"
                                    | keyof DefinedEndpointFetchOutputs<(...), (...), (...)>,
                            >,
                        >,
                    >,
                >,
            >,
        >,
    >
}
Return a method-keyed object for the given endpoint. Each property is a function that runs the fetch for that specific HTTP method.
Type Parameters
- const Endpoint extends EndpointDefinition & { path: keyof ClientApi["endpoints"] }
Parameters
- endpoint: Endpoint
Returns {
    [Method in "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "TRACE"]: BivariantFunction<
        EndpointFetchParams<NoInfer<Endpoint>, Method>,
        Promise<
            If<
                IsAny<
                    DefinedEndpointFetchOutputs<Endpoint, Method, true> & {
                        unexpectedError: UnknownFetchOutput<true>;
                    },
                >,
                any,
                If<
                    IsNever<
                        DefinedEndpointFetchOutputs<Endpoint, Method, true> & {
                            unexpectedError: UnknownFetchOutput<true>;
                        },
                    >,
                    never,
                    If<
                        IsNever<
                            | "unexpectedError"
                            | keyof DefinedEndpointFetchOutputs<Endpoint, Method, true>,
                        >,
                        never,
                        _RequireExactlyOne<
                            DefinedEndpointFetchOutputs<Endpoint, Method, true> & {
                                unexpectedError: UnknownFetchOutput<true>;
                            },
                            If<
                                IsAny<"unexpectedError" | keyof (...)>,

                                    | "unexpectedError"
                                    | keyof DefinedEndpointFetchOutputs<(...), (...), (...)>,

                                    | "unexpectedError"
                                    | keyof DefinedEndpointFetchOutputs<(...), (...), (...)>,
                            >,
                        >,
                    >,
                >,
            >,
        >,
    >
}
Example
```
const response = await client.fetch(healthEndpoint).GET();
const created = await client.fetch(usersEndpoint).POST({requestData: ...});
```
- Defined in packages/api/src/client.ts:87

fetchStream

fetchStream<
    const Endpoint extends
        EndpointDefinition & { path: keyof ClientApi["endpoints"] },
    const Method extends "GET"
    | "PUT"
    | "POST"
    | "DELETE"
    | "PATCH"
    | "TRACE",
>(
    endpoint: Endpoint,
    method: Method,
    ...restParams: EndpointFetchParams<NoInfer<Endpoint>, NoInfer<Method>>,
): Promise<EndpointFetchStreamOutput<Endpoint, Method>>
Send a request to an endpoint definition and return a ReadableStream instead of parsing the response body. Useful for consuming SSE (Server-Sent Events) endpoints from the frontend.

Uses the same request-building flow as .fetch(), but skips response body and JSON validation.
Type Parameters
- const Endpoint extends EndpointDefinition & { path: keyof ClientApi["endpoints"] }
- const Method extends "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "TRACE"
Parameters
- endpoint: Endpoint
- method: Method
- ...restParams: EndpointFetchParams<NoInfer<Endpoint>, NoInfer<Method>>
Returns Promise<EndpointFetchStreamOutput<Endpoint, Method>>
- Defined in packages/api/src/client.ts:121

`Protected`runEndpointRequest

runEndpointRequest<
    const Endpoint extends
        EndpointDefinition & { path: keyof ClientApi["endpoints"] },
    const Method extends "GET"
    | "PUT"
    | "POST"
    | "DELETE"
    | "PATCH"
    | "TRACE",
>(
    endpoint: Endpoint,
    method: Method,
    params:
        | {
            fetchOverride?: ClientFetch;
            options?: Omit<RequestInit, "body" | "method">;
            pathParams?: GenericPathParams;
            requestData?: any;
            requiredHeaders?: Record<string, string>;
            searchParams?: Readonly<Record<string, AllowedSearchParamValue>>;
            skipAutomaticContentTypeHeader?: boolean;
        }
        | undefined,
    getResponseDataOverride?: HandleDeclaredResponseStatusOverride,
): Promise<Record<string, UnknownFetchOutput>>
Validate that the endpoint is registered, build its request init, send the request, and shape the response into the status-keyed output. The body of RestVirClient.fetch and RestVirClient.fetchStream; their only divergent step is how they read responseData out of the response.
Type Parameters
- const Endpoint extends EndpointDefinition & { path: keyof ClientApi["endpoints"] }
- const Method extends "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "TRACE"
Parameters
- endpoint: Endpoint
- method: Method
- params:
      | {
          fetchOverride?: ClientFetch;
          options?: Omit<RequestInit, "body" | "method">;
          pathParams?: GenericPathParams;
          requestData?: any;
          requiredHeaders?: Record<string, string>;
          searchParams?: Readonly<Record<string, AllowedSearchParamValue>>;
          skipAutomaticContentTypeHeader?: boolean;
      }
      | undefined
  - {
        fetchOverride?: ClientFetch;
        options?: Omit<RequestInit, "body" | "method">;
        pathParams?: GenericPathParams;
        requestData?: any;
        requiredHeaders?: Record<string, string>;
        searchParams?: Readonly<Record<string, AllowedSearchParamValue>>;
        skipAutomaticContentTypeHeader?: boolean;
    }
    OptionalfetchOverride?: ClientFetch
    Override the fetch function that is used when fetching the endpoint.
    
    Default
    fetch // the global fetch
    
    Optionaloptions?: Omit<RequestInit, "body" | "method">
    Set the standard request init options that fetch allows.
    
    OptionalpathParams?: GenericPathParams
    Set the required path params, if any. These are only allowed if the endpoint's path has param or wildcard strings.
    
    OptionalrequestData?: any
    Set the endpoint fetch's request data, if allowed by the endpoint.
    
    OptionalrequiredHeaders?: Record<string, string>
    Set headers that are required by this route's definition, if any. Note that additional headers can be supplied in the options property, but any headers provided in both will instead use the values from here here (in requiredHeaders).
    
    OptionalsearchParams?: Readonly<Record<string, AllowedSearchParamValue>>
    Set search params on the endpoint's URL.
    
    OptionalskipAutomaticContentTypeHeader?: boolean
    If true, automatic request data 'Content-Type' header assignment will be skipped.
  - undefined
- OptionalgetResponseDataOverride: HandleDeclaredResponseStatusOverride
Returns Promise<Record<string, UnknownFetchOutput>>
- Defined in packages/api/src/client.ts:146

Class RestVirClient<ClientApi>

Package

Type Parameters

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

Returns RestVirClient<ClientApi>

Properties

Readonlyapi

baseUrl

OptionalfetchOverride

OptionalwebSocketConstructor

Methods

buildEndpointRequestInit

Type Parameters

Parameters

Returns { requestInit: RequestInit; url: string }

Throws

buildEndpointUrl

Type Parameters

Parameters

Returns string

Throws

buildWebSocketUrl

Type Parameters

Parameters

Returns string

connectWebSocket

Type Parameters

Parameters

Returns Promise<OverwriteWebSocketMethods<WebSocketClass, OnClient, ThisWebSocket>>

fetch

Type Parameters

Parameters

Example

fetchStream

Type Parameters

Parameters

Returns Promise<EndpointFetchStreamOutput<Endpoint, Method>>

ProtectedrunEndpointRequest

Type Parameters

Parameters

OptionalfetchOverride?: ClientFetch

Default

Optionaloptions?: Omit<RequestInit, "body" | "method">

OptionalpathParams?: GenericPathParams

OptionalrequestData?: any

OptionalrequiredHeaders?: Record<string, string>

OptionalsearchParams?: Readonly<Record<string, AllowedSearchParamValue>>

OptionalskipAutomaticContentTypeHeader?: boolean

Returns Promise<Record<string, UnknownFetchOutput>>

Settings

On This Page

`Readonly`api

`Optional`fetchOverride

`Optional`webSocketConstructor

`Protected`runEndpointRequest

`Optional`fetchOverride?: ClientFetch

`Optional`options?: Omit<RequestInit, "body" | "method">

`Optional`pathParams?: GenericPathParams

`Optional`requestData?: any

`Optional`requiredHeaders?: Record<string, string>

`Optional`searchParams?: Readonly<Record<string, AllowedSearchParamValue>>

`Optional`skipAutomaticContentTypeHeader?: boolean