AtomHttpApi

Connects typed HttpApi clients to atoms.

The service created here exposes the generated HTTP API client plus atom-based query and mutation helpers. Query atoms call endpoints and track their asynchronous result, while mutations run endpoint calls that can invalidate reactivity keys after a successful request. Query atoms can also be cached, serialized for hydration, and kept alive with a time-to-live.

2 exports Added in v4.0.0 Source

Constructors

Service

Added in v4.0.0 Source

Creates a Context.Service class for an HTTP API client backed by an atom runtime.

Details

The options provide the API definition, HTTP client layer, optional client and response transforms, base URL, and runtime factory used by the query and mutation helpers.

Signature

declare function Service<Self>(): <Id extends string, ApiId extends string, Groups extends Constraint>(id: Id, options: {
  readonly api: HttpApi<ApiId, Groups>;
  readonly baseUrl?: string | URL;
  readonly httpClient: Layer<HttpClient | ClientServices<Groups>, never, never> | (get: AtomContext) => Layer<HttpClient | ClientServices<Groups>>;
  readonly runtime?: RuntimeFactory;
  readonly transformClient?: (client: HttpClient) => HttpClient;
  readonly transformResponse?: (effect: Effect<unknown, unknown, unknown>) => Effect<unknown, unknown, unknown>;
}) => AtomHttpApiClient<Self, Id, Groups>

Services

AtomHttpApiClient interface

Added in v4.0.0 Source

A Context.Service for an HTTP API client integrated with atom reactivity.

Details

It exposes the generated HTTP API client, an atom runtime, mutation helpers that return AtomResultFns, and query helpers that return atoms of endpoint results.

Signature

interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpApiGroup.Constraint> extends Service<Self, HttpApiClient.Client<Groups, never, never>> {
  constructor(_: never);
  readonly mutation: <GroupIdentifier extends string, EndpointIdentifier extends string, Group extends Constraint = Extract<Groups, {
    readonly identifier: GroupIdentifier;
  }>, Endpoint extends Constraint = Extract<Endpoints<Group>, {
    readonly identifier: EndpointIdentifier;
  }>, ResponseMode extends ClientResponseMode = ClientResponseMode>(group: GroupIdentifier, endpoint: EndpointIdentifier, options?: {
    readonly responseMode?: ResponseMode;
  }) => [Endpoint] extends [HttpApiEndpoint<_Identifier, _Method, _Path, _Params, _Query, _Payload, _Headers, _Success, _Error, _Middleware, _RE>] ? AtomResultFn<Simplify<ClientRequest<_Params, _Query, _Payload, _Headers, "decoded-only"> & {
    readonly reactivityKeys?: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>;
  }>, ResponseByMode<Extract<_Success, Top>["Type"], ResponseMode>, ErrorByMode<_Error, _Middleware, ResponseMode>> : never;
  readonly query: <GroupIdentifier extends string, EndpointIdentifier extends string, Group extends Constraint = Extract<Groups, {
    readonly identifier: GroupIdentifier;
  }>, Endpoint extends Constraint = Extract<Endpoints<Group>, {
    readonly identifier: EndpointIdentifier;
  }>, ResponseMode extends ClientResponseMode = "decoded-only">(group: GroupIdentifier, endpoint: EndpointIdentifier, request: [Endpoint] extends [HttpApiEndpoint<_Identifier, _Method, _Path, _Params, _Query, _Payload, _Headers, _Success, _Error, _R, _RE>] ? Simplify<ClientRequest<_Params, _Query, _Payload, _Headers, ResponseMode> & {
    readonly reactivityKeys?: readonly Array<unknown> | ReadonlyRecord<string, readonly Array<unknown>>;
    readonly serializationKey?: string;
    readonly timeToLive?: Input;
  }> : never) => [Endpoint] extends [HttpApiEndpoint<_Identifier, _Method, _Path, _Params, _Query, _Payload, _Headers, _Success, _Error, _Middleware, _RE>] ? Atom<AsyncResult<ResponseByMode<Extract<_Success, Top>["Type"], ResponseMode>, ErrorByMode<_Error, _Middleware, ResponseMode>>> : never;
  readonly runtime: AtomRuntime<Self>;
}