@vaadin/hilla-frontend/Connect.d.ts

Hilla core frontend utils

import type { ReactiveControllerHost } from "@lit/reactive-element";
import { type ActionOnLostSubscription, FluxConnection, type FluxSubscriptionStateChangeEvent } from "./FluxConnection.js";
export declare const BODY_PART_NAME = "hilla_body_part";
export type MaybePromise<T> = Promise<T> | T;
/**
* Represents the connection to and endpoint returning a subscription rather than a value.
*/
export interface Subscription<T> {
	/** Cancels the subscription.  No values are made available after calling this. */
	cancel(): void;
	context(context: ReactiveControllerHost): Subscription<T>;
	/** Called when the subscription has completed. No values are made available after calling this. */
	onComplete(callback: () => void): Subscription<T>;
	/** Called when an exception occured in the subscription. */
	onError(callback: (message: string) => void): Subscription<T>;
	/** Called when a new value is available. */
	onNext(callback: (value: T) => void): Subscription<T>;
	/** Called when the subscription state changes. */
	onConnectionStateChange(callback: (event: FluxSubscriptionStateChangeEvent) => void): Subscription<T>;
	/**
	* Called when the connection is restored, but there's no longer a valid subscription. If the callback returns
	* `ActionOnLostSubscription.RESUBSCRIBE`, the subscription will be re-established by connecting to the same
	* server method again. If the callback returns `ActionOnLostSubscription.REMOVE`, the subscription will be
	* forgotten. This is also the default behavior if the callback is not set or if it returns `undefined`.
	*/
	onSubscriptionLost(callback: () => ActionOnLostSubscription | void): Subscription<T>;
}
/**
* The `ConnectClient` constructor options.
*/
export interface ConnectClientOptions {
	/**
	* The `middlewares` property value.
	*/
	middlewares?: Middleware[];
	/**
	* The `prefix` property value.
	*/
	prefix?: string;
	/**
	* The Atmosphere options for the FluxConnection.
	*/
	atmosphereOptions?: Partial<Atmosphere.Request>;
}
export interface EndpointCallMetaInfo {
	/**
	* The endpoint name.
	*/
	endpoint: string;
	/**
	* The method name to call on in the endpoint class.
	*/
	method: string;
	/**
	* Optional object with method call arguments.
	*/
	params?: Record<string, unknown>;
}
/**
* An object with the call arguments and the related Request instance.
* See also {@link ConnectClient.call | the call() method in ConnectClient}.
*/
export interface MiddlewareContext extends EndpointCallMetaInfo {
	/**
	* The Fetch API Request object reflecting the other properties.
	*/
	request: Request;
}
/**
* An async middleware callback that invokes the next middleware in the chain
* or makes the actual request.
* @param context - The information about the call and request
*/
export type MiddlewareNext = (context: MiddlewareContext) => MaybePromise<Response>;
/**
* An interface that allows defining a middleware as a class.
*/
export interface MiddlewareClass {
	/**
	* @param context - The information about the call and request
	* @param next - Invokes the next in the call chain
	*/
	invoke(context: MiddlewareContext, next: MiddlewareNext): MaybePromise<Response>;
}
/**
* An async callback function that can intercept the request and response
* of a call.
*/
export type MiddlewareFunction = (context: MiddlewareContext, next: MiddlewareNext) => MaybePromise<Response>;
/**
* An async callback that can intercept the request and response
* of a call, could be either a function or a class.
*/
export type Middleware = MiddlewareClass | MiddlewareFunction;
/**
* A list of parameters supported by {@link ConnectClient.call | the call() method in ConnectClient}.
*/
export interface EndpointRequestInit {
	/**
	* An AbortSignal to set request's signal.
	*/
	signal?: AbortSignal | null;
	/**
	* If set to true, the connection state will not be updated during the request.
	*/
	mute?: boolean;
}
/**
* A low-level network calling utility. It stores
* a prefix and facilitates remote calls to endpoint class methods
* on the Hilla backend.
*
* Example usage:
*
* ```js
* const client = new ConnectClient();
* const responseData = await client.call('MyEndpoint', 'myMethod');
* ```
*
* ### Prefix
*
* The client supports an `prefix` constructor option:
* ```js
* const client = new ConnectClient({prefix: '/my-connect-prefix'});
* ```
*
* The default prefix is '/connect'.
*
*/
export declare class ConnectClient {
	#private;
	/**
	* The array of middlewares that are invoked during a call.
	*/
	middlewares: Middleware[];
	/**
	* The Hilla endpoint prefix
	*/
	prefix: string;
	/**
	* The Atmosphere options for the FluxConnection.
	*/
	atmosphereOptions: Partial<Atmosphere.Request>;
	/**
	* @param options - Constructor options.
	*/
	constructor(options?: ConnectClientOptions);
	/**
	* Gets a representation of the underlying persistent network connection used for subscribing to Flux type endpoint
	* methods.
	*/
	get fluxConnection(): FluxConnection;
	/**
	* Calls the given endpoint method defined using the endpoint and method
	* parameters with the parameters given as params.
	* Asynchronously returns the parsed JSON response data.
	*
	* @param endpoint - Endpoint name.
	* @param method - Method name to call in the endpoint class.
	* @param params - Optional parameters to pass to the method.
	* @param init - Optional parameters for the request
	* @returns Decoded JSON response data.
	*/
	call(endpoint: string, method: string, params?: Record<string, unknown>, init?: EndpointRequestInit): Promise<any>;
	/**
	* Subscribes to the given method defined using the endpoint and method
	* parameters with the parameters given as params. The method must return a
	* compatible type such as a Flux.
	* Returns a subscription that is used to fetch values as they become available.
	*
	* @param endpoint - Endpoint name.
	* @param method - Method name to call in the endpoint class.
	* @param params - Optional parameters to pass to the method.
	* @returns A subscription used to handles values as they become available.
	*/
	subscribe(endpoint: string, method: string, params?: any): Subscription<any>;
}