@rest-vir/define-service 0.0.2

package/dist/endpoint/endpoint.d.ts

@@ -0,0 +1,198 @@
+import { AnyObject, HttpMethod, JsonCompatibleValue, Overwrite, type SelectFrom } from '@augment-vir/common';
+import { type ShapeDefinition, type ShapeToRuntimeType } from 'object-shape-tester';
+import { type RequireAtLeastOne } from 'type-fest';
+import { type MinimalService } from '../service/minimal-service.js';
+import { type NoParam } from '../util/no-param.js';
+import { type OriginRequirement } from '../util/origin.js';
+import { BaseSearchParams } from '../util/search-params.js';
+import { type EndpointPathBase } from './endpoint-path.js';
+/**
+ * Base Endpoint request/response shape type.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type EndpointDataShapeBase = JsonCompatibleValue;
+/**
+ * The type for setting up an individual endpoint, used in `defineService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type EndpointInit<AllowedMethods extends RequireAtLeastOne<Record<HttpMethod, boolean>> = RequireAtLeastOne<Record<HttpMethod, boolean>>, RequestDataShape extends EndpointDataShapeBase | NoParam = EndpointDataShapeBase | NoParam, ResponseDataShape = unknown> = {
+    /**
+     * Shape definition for request data. Set to `undefined` for no request data.
+     *
+     * See the [`object-shape-tester`](https://www.npmjs.com/package/object-shape-tester) package
+     * for extra details on defining a shape.
+     */
+    requestDataShape: RequestDataShape;
+    /**
+     * Shape definition for response data. Set to `undefined` for no response data.
+     *
+     * See the [`object-shape-tester`](https://www.npmjs.com/package/object-shape-tester) package
+     * for extra details on defining a shape.
+     */
+    responseDataShape: ResponseDataShape;
+    /**
+     * All allowed (or not allowed) HTTP methods for this endpoint. Set `true` for each allowed
+     * method and omit or set `false` for each blocked method.
+     */
+    methods: AllowedMethods;
+    /**
+     * Set a required client origin for this endpoint.
+     *
+     * - If this is omitted, the service's origin requirement is used instead.
+     * - If this is explicitly set to `undefined`, this endpoint allows any origins (regardless of the
+     *   service's origin requirement).
+     * - Any other set value overrides the service's origin requirement (if it has any).
+     */
+    requiredClientOrigin?: OriginRequirement;
+    /**
+     * A shape used to verify search params. This should match the entire search params object.
+     *
+     * Note the following:
+     *
+     * - Search param values will _always_ be in an array
+     * - Elements in search param value arrays will _always_ be strings
+     *
+     * @example
+     *
+     * ```ts
+     * import {exact, enumShape} from 'object-shape-tester';
+     *
+     * const partialEndpointInit = {
+     *     searchParamsShape: {
+     *         // use `tupleShape` to ensure there's exactly one entry for this search param
+     *         userId: tupleShape(enumShape(MyEnum)),
+     *         date: tupleShape(exact('2')),
+     *         // don't use `tupleShape` here so that there can be any number of entries
+     *         colors: [''],
+     *     },
+     * };
+     * ```
+     */
+    searchParamsShape?: unknown;
+    /**
+     * Any additional data that you wish to attach to this endpoint. This won't be used by the
+     * service at all, it's merely a place for you to place extra data which will be passed along to
+     * your endpoint implementations.
+     */
+    customProps?: Record<PropertyKey, unknown> | undefined;
+};
+/**
+ * Used to validate {@link EndpointInit} inside of `defineService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare const endpointInitShape: ShapeDefinition<{
+    requestDataShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+    responseDataShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+    searchParamsShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+    /**
+     * Set a required client origin for this endpoint.
+     *
+     * - If this is omitted, the service's origin requirement is used instead.
+     * - If this is explicitly set to `undefined`, this endpoint allows any origins (regardless of the
+     *   service's origin requirement).
+     * - Any other set value overrides the service's origin requirement (if it has any).
+     */
+    requiredClientOrigin: import("object-shape-tester").ShapeOr<[undefined, string, import("object-shape-tester").ShapeClass<[RegExpConstructor]>, () => void, import("object-shape-tester").ShapeOr<[string, import("object-shape-tester").ShapeClass<[RegExpConstructor]>, () => void]>[]]>;
+    methods: import("object-shape-tester").ShapeIndexedKeys<[{
+        keys: import("object-shape-tester").ShapeEnum<readonly [typeof HttpMethod]>;
+        values: boolean;
+        required: false;
+    }]>;
+    customProps: import("object-shape-tester").ShapeOptional<import("object-shape-tester").ShapeOr<[undefined, import("object-shape-tester").ShapeIndexedKeys<[{
+        keys: import("object-shape-tester").ShapeUnknown<[unknown]>;
+        values: import("object-shape-tester").ShapeUnknown<[unknown]>;
+        required: false;
+    }]>]>>;
+}, false>;
+/**
+ * Adds final properties to {@link EndpointInit} so it becomes {@link EndpointDefinition}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type WithFinalEndpointProps<Init, EndpointPath extends EndpointPathBase> = (Init extends AnyObject ? Overwrite<Init, {
+    requestDataShape: Init['requestDataShape'] extends NoParam ? ShapeDefinition<any, true> | undefined : undefined extends Init['requestDataShape'] ? undefined : ShapeDefinition<Init['requestDataShape'], true>;
+    responseDataShape: Init['responseDataShape'] extends NoParam ? ShapeDefinition<any, true> | undefined : undefined extends Init['responseDataShape'] ? undefined : ShapeDefinition<Init['responseDataShape'], true>;
+    RequestType: Init['requestDataShape'] extends NoParam ? any : undefined extends Init['requestDataShape'] ? undefined : ShapeToRuntimeType<ShapeDefinition<Init['requestDataShape'], true>, false, true>;
+    ResponseType: Init['responseDataShape'] extends NoParam ? any : undefined extends Init['responseDataShape'] ? undefined : ShapeToRuntimeType<ShapeDefinition<Init['responseDataShape'], true>, false, true>;
+    searchParamsShape: 'searchParamsShape' extends keyof Init ? undefined extends Init['searchParamsShape'] ? undefined : ShapeDefinition<Init['searchParamsShape'], true> | undefined : undefined;
+    SearchParamsType: undefined extends Init['searchParamsShape'] ? BaseSearchParams : ShapeToRuntimeType<ShapeDefinition<Init['searchParamsShape'], true>, false, true>;
+    customProps: 'customProps' extends keyof Init ? Init['customProps'] : undefined;
+}> : never) & {
+    path: EndpointPath;
+    isWebSocket: false;
+    isEndpoint: true;
+    service: MinimalService;
+};
+/**
+ * A fully defined endpoint instance. This is generated from `defineService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type EndpointDefinition<AllowedMethods extends RequireAtLeastOne<Record<HttpMethod, boolean>> = RequireAtLeastOne<Record<HttpMethod, boolean>>, RequestDataShape extends EndpointDataShapeBase | NoParam = NoParam, ResponseDataShape extends EndpointDataShapeBase | NoParam = NoParam, EndpointPath extends EndpointPathBase = EndpointPathBase> = WithFinalEndpointProps<EndpointInit<AllowedMethods, RequestDataShape, ResponseDataShape>, EndpointPath>;
+/**
+ * A generic version of {@link EndpointDefinition} that any endpoint can be assigned to.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type GenericEndpointDefinition = Overwrite<EndpointDefinition, {
+    searchParamsShape: any;
+    SearchParamsType: any;
+}>;
+/**
+ * Extracts response and request data from an endpoint definition.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type BaseEndpointForExecutorData = Pick<EndpointDefinition, 'requestDataShape' | 'responseDataShape'>;
+/**
+ * Extracts response and request data from an endpoint definition into different properties.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type EndpointExecutorData<SpecificEndpoint extends BaseEndpointForExecutorData> = {
+    request: ShapeToRuntimeType<SpecificEndpoint['requestDataShape'], false, true>;
+    response: ShapeToRuntimeType<SpecificEndpoint['responseDataShape'], false, true>;
+};
+/**
+ * Attaches request and response type-only getters to an endpoint definition.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function attachEndpointShapeTypeGetters<const T extends AnyObject>(endpoint: T): asserts endpoint is T & Pick<EndpointDefinition, 'RequestType' | 'ResponseType'>;
+/**
+ * Asserts that the given finalized {@link EndpointDefinition} instance is valid.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function assertValidEndpoint(endpoint: Readonly<SelectFrom<EndpointDefinition, {
+    path: true;
+    methods: true;
+    isWebSocket: true;
+    isEndpoint: true;
+    service: {
+        serviceName: true;
+    };
+}>>): void;

package/dist/endpoint/endpoint.js

@@ -0,0 +1,80 @@
+import { HttpMethod, } from '@augment-vir/common';
+import { defineShape, enumShape, indexedKeys, optional, or, unknownShape, } from 'object-shape-tester';
+import { ensureServiceDefinitionError } from '../service/service-definition.error.js';
+import { originRequirementShape } from '../util/origin.js';
+import { assertValidEndpointPath } from './endpoint-path.js';
+/**
+ * Used to validate {@link EndpointInit} inside of `defineService`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export const endpointInitShape = defineShape({
+    requestDataShape: unknownShape(),
+    responseDataShape: unknownShape(),
+    searchParamsShape: unknownShape(),
+    /**
+     * Set a required client origin for this endpoint.
+     *
+     * - If this is omitted, the service's origin requirement is used instead.
+     * - If this is explicitly set to `undefined`, this endpoint allows any origins (regardless of the
+     *   service's origin requirement).
+     * - Any other set value overrides the service's origin requirement (if it has any).
+     */
+    requiredClientOrigin: originRequirementShape,
+    methods: indexedKeys({
+        keys: enumShape(HttpMethod),
+        values: false,
+        required: false,
+    }),
+    customProps: optional(or(undefined, indexedKeys({
+        keys: unknownShape(),
+        values: unknownShape(),
+        required: false,
+    }))),
+});
+/**
+ * Attaches request and response type-only getters to an endpoint definition.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function attachEndpointShapeTypeGetters(endpoint) {
+    Object.defineProperties(endpoint, {
+        RequestType: {
+            enumerable: false,
+            get() {
+                throw new Error('.RequestType should not be used as a value.');
+            },
+        },
+        ResponseType: {
+            enumerable: false,
+            get() {
+                throw new Error('.ResponseType should not be used as a value.');
+            },
+        },
+    });
+}
+/**
+ * Asserts that the given finalized {@link EndpointDefinition} instance is valid.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function assertValidEndpoint(endpoint) {
+    try {
+        assertValidEndpointPath(endpoint.path);
+        if (!Object.values(endpoint.methods).some((value) => value)) {
+            throw new Error('Endpoint has no allowed HTTP methods.');
+        }
+    }
+    catch (error) {
+        throw ensureServiceDefinitionError(error, {
+            serviceName: endpoint.service.serviceName,
+            ...endpoint,
+        });
+    }
+}

package/dist/frontend-connect/connect-web-socket.d.ts

@@ -0,0 +1,95 @@
+import { RequiredKeysOf, SelectFrom } from '@augment-vir/common';
+import { IsNever } from 'type-fest';
+import { PathParams } from '../endpoint/endpoint-path.js';
+import { type NoParam } from '../util/no-param.js';
+import type { CommonWebSocket } from '../web-socket/common-web-socket.js';
+import { type ClientWebSocket, type ConnectWebSocketListeners, type GenericConnectWebSocketParams } from '../web-socket/overwrite-web-socket-methods.js';
+import { type WebSocketDefinition } from '../web-socket/web-socket-definition.js';
+/**
+ * Verifies that no WebSocket protocols in the given list are invalid. This doesn't have anything to
+ * do with a `WebsocketDefinition` instance, it's just checking if the given protocols can even be
+ * sent.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function assertValidWebSocketProtocols(protocols: ReadonlyArray<unknown> | undefined): void;
+/**
+ * Builds a WebSocket URL.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function buildWebSocketUrl(webSocketDefinition: Readonly<SelectFrom<WebSocketDefinition, {
+    path: true;
+    service: {
+        serviceName: true;
+        serviceOrigin: true;
+    };
+}>>, ...[{ pathParams },]: CollapsedConnectWebSocketParams): string;
+/**
+ * Params for {@link connectWebSocket}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type ConnectWebSocketParams<WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    path: true;
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    protocolsShape: true;
+    ProtocolsType: true;
+    searchParamsShape: true;
+    SearchParamsType: true;
+}>>, AllowWebSocketMock extends boolean = true, WebSocketClass extends CommonWebSocket = CommonWebSocket> = {
+    /**
+     * Optional listeners that can be immediately attached to the WebSocket instance instead of
+     * requiring externally adding them.
+     */
+    listeners?: ConnectWebSocketListeners<WebSocketToConnect, WebSocketClass>;
+} & (IsNever<PathParams<WebSocketToConnect['path']>> extends true ? {
+    /** This WebSocket has no path parameters to configure. */
+    pathParams?: undefined;
+} : PathParams<WebSocketToConnect['path']> extends string ? {
+    /** Required path params for this WebSocket's path. */
+    pathParams: Readonly<Record<PathParams<WebSocketToConnect['path']>, string>>;
+} : {
+    /** This WebSocket has no path parameters to configure. */
+    pathParams?: undefined;
+}) & (AllowWebSocketMock extends true ? Pick<GenericConnectWebSocketParams<WebSocketClass>, 'webSocketConstructor'> : unknown) & (WebSocketToConnect['protocolsShape'] extends undefined ? {
+    protocols?: string[];
+} : {
+    protocols: WebSocketToConnect['ProtocolsType'];
+}) & (WebSocketToConnect['searchParamsShape'] extends undefined ? {
+    searchParams?: string[];
+} : {
+    searchParams: WebSocketToConnect['SearchParamsType'];
+});
+/**
+ * Collapsed version of {@link ConnectWebSocketParams} for {@link connectWebSocket} that only
+ * _requires_ an object parameter if the parameters object has any required keys.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type CollapsedConnectWebSocketParams<WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    path: true;
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    protocolsShape: true;
+    ProtocolsType: true;
+    searchParamsShape: true;
+    SearchParamsType: true;
+}>> | NoParam = NoParam, AllowWebSocketMock extends boolean = true, WebSocketClass extends CommonWebSocket = CommonWebSocket> = WebSocketToConnect extends NoParam ? [Readonly<GenericConnectWebSocketParams<WebSocketClass>>?] : Readonly<ConnectWebSocketParams<Exclude<WebSocketToConnect, NoParam>, AllowWebSocketMock, WebSocketClass>> extends infer RealParams ? RequiredKeysOf<RealParams> extends never ? [RealParams?] : [RealParams] : [];
+/**
+ * Creates and connects a new client WebSocket instance with type safety.
+ *
+ * @category Client (Frontend) Connection
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function connectWebSocket<const WebSocketToConnect extends Readonly<WebSocketDefinition> | NoParam, WebSocketClass extends CommonWebSocket>(webSocketDefinition: WebSocketToConnect extends WebSocketDefinition ? WebSocketToConnect : Readonly<WebSocketDefinition>, ...params: CollapsedConnectWebSocketParams<WebSocketToConnect, true, WebSocketClass>): Promise<ClientWebSocket<WebSocketToConnect, WebSocketClass>>;

package/dist/frontend-connect/connect-web-socket.js

@@ -0,0 +1,64 @@
+import { ensureErrorAndPrependMessage, HttpMethod, } from '@augment-vir/common';
+import { buildUrl } from 'url-vir';
+import { finalizeWebSocket, WebSocketLocation, } from '../web-socket/overwrite-web-socket-methods.js';
+import { buildEndpointUrl } from './fetch-endpoint.js';
+import { parseSecWebSocketProtocolHeader } from './web-socket-protocol-parse.js';
+/**
+ * Verifies that no WebSocket protocols in the given list are invalid. This doesn't have anything to
+ * do with a `WebsocketDefinition` instance, it's just checking if the given protocols can even be
+ * sent.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function assertValidWebSocketProtocols(protocols) {
+    if (!protocols || !protocols.length) {
+        return;
+    }
+    const joinedProtocols = protocols.join(', ');
+    try {
+        parseSecWebSocketProtocolHeader(joinedProtocols);
+    }
+    catch (error) {
+        throw ensureErrorAndPrependMessage(error, `Invalid protocols given ('${joinedProtocols}')`);
+    }
+}
+/**
+ * Builds a WebSocket URL.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function buildWebSocketUrl(webSocketDefinition, ...[{ pathParams } = {},]) {
+    const httpUrl = buildEndpointUrl({
+        methods: {
+            [HttpMethod.Get]: true,
+        },
+        path: webSocketDefinition.path,
+        requestDataShape: undefined,
+        responseDataShape: undefined,
+        service: webSocketDefinition.service,
+    }, { pathParams });
+    return buildUrl(httpUrl, {
+        protocol: httpUrl.startsWith('https') ? 'wss' : 'ws',
+    }).href;
+}
+const defaultWebSocket = function (...[url, protocols,]) {
+    return new globalThis.WebSocket(url, protocols);
+};
+/**
+ * Creates and connects a new client WebSocket instance with type safety.
+ *
+ * @category Client (Frontend) Connection
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export async function connectWebSocket(webSocketDefinition, ...params) {
+    const [{ webSocketConstructor = defaultWebSocket, protocols, listeners } = {},] = params;
+    assertValidWebSocketProtocols(protocols);
+    const url = buildWebSocketUrl(webSocketDefinition, ...params);
+    const clientWebSocket = await finalizeWebSocket(webSocketDefinition, new webSocketConstructor(url, protocols, webSocketDefinition), listeners, WebSocketLocation.OnClient);
+    return clientWebSocket;
+}

package/dist/frontend-connect/fetch-endpoint.d.ts

@@ -0,0 +1,199 @@
+import { HttpMethod, KeyCount, type ExtractKeysWithMatchingValues, type MaybePromise, type RequiredKeysOf, type SelectFrom } from '@augment-vir/common';
+import { type IsEqual, type IsNever } from 'type-fest';
+import { type PathParams } from '../endpoint/endpoint-path.js';
+import { EndpointExecutorData, type EndpointDefinition, type GenericEndpointDefinition } from '../endpoint/endpoint.js';
+import { type NoParam } from '../util/no-param.js';
+/**
+ * A general version of {@link FetchEndpointParams} to be used when accepting _any_ endpoint (like in
+ * tests).
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type GenericFetchEndpointParams = {
+    pathParams?: Record<string, string> | undefined;
+    requestData?: any;
+    method?: HttpMethod | undefined;
+    options?: Omit<RequestInit, 'body' | 'method'> | undefined;
+    /**
+     * A custom fetch implementation. Useful for debugging or unit testing. This can safely be
+     * omitted to use the default JavaScript built-in global `fetch` function.
+     */
+    fetch?: ((url: string, requestInit: RequestInit, endpoint?: GenericEndpointDefinition | undefined) => MaybePromise<Response>) | undefined;
+};
+/**
+ * Type that determines which HTTP request methods can be used for the given endpoint definition.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type FetchMethod<EndpointToFetch extends Pick<EndpointDefinition, 'methods'>> = IsEqual<KeyCount<Record<ExtractKeysWithMatchingValues<EndpointToFetch['methods'], true>, boolean>>, 1> extends true ? never : Extract<HttpMethod, ExtractKeysWithMatchingValues<EndpointToFetch['methods'], true>> | `${Extract<HttpMethod, ExtractKeysWithMatchingValues<EndpointToFetch['methods'], true>>}`;
+/**
+ * All type safe parameters for sending a request to an endpoint using {@link fetchEndpoint}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type FetchEndpointParams<EndpointToFetch extends SelectFrom<EndpointDefinition, {
+    path: true;
+    requestDataShape: true;
+    responseDataShape: true;
+    methods: true;
+}>, AllowFetchMock extends boolean = true> = EndpointToFetch extends EndpointDefinition ? Readonly<(IsNever<PathParams<EndpointToFetch['path']>> extends true ? {
+    /** This endpoint has no path parameters to configure. */
+    pathParams?: undefined;
+} : PathParams<EndpointToFetch['path']> extends string ? {
+    pathParams: Readonly<Record<PathParams<EndpointToFetch['path']>, string>>;
+} : {
+    /** This endpoint has no path parameters to configure. */
+    pathParams?: undefined;
+}) & (EndpointExecutorData<EndpointToFetch>['request'] extends undefined ? {
+    /**
+     * This endpoint does not accept any request data, so there is none to be
+     * set.
+     */
+    requestData?: never;
+} : {
+    requestData: EndpointExecutorData<EndpointToFetch>['request'];
+}) & (IsNever<FetchMethod<EndpointToFetch>> extends true ? {
+    /**
+     * This endpoint only allows one method so it does not need to be
+     * configured.
+     */
+    method?: never;
+} : {
+    method: FetchMethod<EndpointToFetch>;
+}) & (AllowFetchMock extends true ? Pick<GenericFetchEndpointParams, 'options' | 'fetch'> : Pick<GenericFetchEndpointParams, 'options'>)> : GenericFetchEndpointParams;
+/**
+ * Type safe output from sending a request to an endpoint definition. Used by {@link fetchEndpoint}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type FetchEndpointOutput<EndpointToFetch extends Readonly<SelectFrom<EndpointDefinition, {
+    requestDataShape: true;
+    responseDataShape: true;
+}>> | NoParam> = Readonly<{
+    data: EndpointToFetch extends SelectFrom<EndpointDefinition, {
+        requestDataShape: true;
+        responseDataShape: true;
+    }> ? EndpointExecutorData<EndpointToFetch>['response'] : any;
+    response: Readonly<Response>;
+}>;
+/**
+ * Extracts an array of all allowed methods for the given endpoint definition.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function getAllowedEndpointMethods(endpoint: Readonly<Pick<EndpointDefinition, 'methods'>>): HttpMethod[];
+/**
+ * A wrapper for {@link FetchEndpointParams} that requires parameters based on the endpoint being
+ * fetched.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type CollapsedFetchEndpointParams<EndpointToFetch extends Readonly<SelectFrom<EndpointDefinition, {
+    path: true;
+    requestDataShape: true;
+    responseDataShape: true;
+    methods: true;
+}>> | NoParam, AllowFetchMock extends boolean = true> = EndpointToFetch extends NoParam ? [Readonly<GenericFetchEndpointParams>?] : Readonly<FetchEndpointParams<Exclude<EndpointToFetch, NoParam>, AllowFetchMock>> extends infer RealParams ? RequiredKeysOf<RealParams> extends never ? [RealParams?] : [RealParams] : [];
+/**
+ * Send a request to an endpoint definition with type safe parameters.
+ *
+ * This can safely be used in frontend _or_ backend code.
+ *
+ * @category Client (Frontend) Connection
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {fetchEndpoint} from '@rest-vir/define-service';
+ *
+ * const {data, response} = await fetchEndpoint(myService.endpoints['/my-endpoint']);
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function fetchEndpoint<const EndpointToFetch extends Readonly<SelectFrom<EndpointDefinition, {
+    requestDataShape: true;
+    path: true;
+    responseDataShape: true;
+    methods: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+}>> | NoParam>(endpoint: EndpointToFetch extends EndpointDefinition ? EndpointToFetch : SelectFrom<EndpointDefinition, {
+    requestDataShape: true;
+    path: true;
+    responseDataShape: true;
+    methods: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+}>, ...params: CollapsedFetchEndpointParams<EndpointToFetch>): Promise<FetchEndpointOutput<EndpointToFetch>>;
+/**
+ * Build request init and URL for fetching an endpoint. Used in {@link fetchEndpoint}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function buildEndpointRequestInit<const EndpointToFetch extends Readonly<SelectFrom<EndpointDefinition, {
+    requestDataShape: true;
+    path: true;
+    responseDataShape: true;
+    methods: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+}>> | NoParam>(endpoint: EndpointToFetch extends EndpointDefinition ? EndpointToFetch : SelectFrom<EndpointDefinition, {
+    requestDataShape: true;
+    path: true;
+    responseDataShape: true;
+    methods: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+}>, ...[{ method, options, pathParams, requestData },]: CollapsedFetchEndpointParams<EndpointToFetch, false>): {
+    url: string;
+    requestInit: RequestInit;
+};
+/**
+ * Creates and finalizes a URL for sending fetches to the given endpoint.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function buildEndpointUrl<const EndpointToFetch extends Readonly<SelectFrom<EndpointDefinition, {
+    path: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+    methods: true;
+    requestDataShape: true;
+    responseDataShape: true;
+}>> | NoParam = NoParam>(endpoint: EndpointToFetch extends EndpointDefinition ? EndpointToFetch : SelectFrom<EndpointDefinition, {
+    path: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+    requestDataShape: true;
+    responseDataShape: true;
+    methods: true;
+}>, { pathParams, }: Pick<EndpointToFetch extends NoParam ? Readonly<GenericFetchEndpointParams> : Readonly<FetchEndpointParams<Exclude<EndpointToFetch, NoParam>>>, 'pathParams'>): string;