@rest-vir/define-service 0.0.2

package/dist/web-socket/overwrite-web-socket-methods.d.ts

@@ -0,0 +1,276 @@
+import { MaybePromise, Overwrite, SelectFrom } from '@augment-vir/common';
+import { type AnyDuration } from 'date-vir';
+import type { HasRequiredKeys } from 'type-fest';
+import { NoParam } from '../util/no-param.js';
+import { CommonWebSocket, CommonWebSocketEventMap } from './common-web-socket.js';
+import { type WebSocketDefinition } from './web-socket-definition.js';
+/**
+ * Location of the WebSocket in question: on a client connecting to a WebSocket host or on the host
+ * that's accepting WebSocket connections.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare enum WebSocketLocation {
+    OnHost = "on-host",
+    OnClient = "on-client"
+}
+/**
+ * Returns the inverse WebSocket location compared to the given WebSocket location. For example,
+ * passing in `WebSocketLocation.OnHost` here will give you `WebSocketLocation.OnClient`.
+ *
+ * @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 getOppositeWebSocketLocation(originalWebSocketLocation: WebSocketLocation): WebSocketLocation;
+/**
+ * Returns the inverse WebSocket location compared to the given WebSocket location. For example,
+ * passing in `WebSocketLocation.OnHost` here will give you `WebSocketLocation.OnClient`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type FlipWebSocketLocation<Location extends WebSocketLocation> = Location extends WebSocketLocation.OnHost ? WebSocketLocation.OnClient : WebSocketLocation.OnHost;
+/**
+ * Determines a message's type based on the WebSocketLocation of where that message came from.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type GetWebSocketMessageTypeFromLocation<SpecificWebSocket extends Readonly<Pick<WebSocketDefinition, 'MessageFromClientType' | 'MessageFromHostType'>>, MessageFromSource extends WebSocketLocation> = MessageFromSource extends WebSocketLocation.OnClient ? SpecificWebSocket['MessageFromClientType'] : SpecificWebSocket['MessageFromHostType'];
+/**
+ * Parameters for the `sendAndWaitForReply` method that gets attached to WebSockets.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type SendAndWaitForReplyParams<Location extends WebSocketLocation, WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+}>> | NoParam = NoParam> = (WebSocketToConnect extends NoParam ? {
+    /** Generic message to send. */
+    message?: any;
+} : GetWebSocketMessageTypeFromLocation<Exclude<WebSocketToConnect, NoParam>, Location> extends undefined ? {
+    /** The message data to send to the other side of the WebSocket connection. */
+    message?: GetWebSocketMessageTypeFromLocation<Exclude<WebSocketToConnect, NoParam>, Location>;
+} : {
+    /** The message data to send to the other side of the WebSocket connection. */
+    message: GetWebSocketMessageTypeFromLocation<Exclude<WebSocketToConnect, NoParam>, Location>;
+}) & {
+    /**
+     * The duration to wait for a reply message. If this duration is exceeded and a response still
+     * hasn't been received, an error is thrown.
+     *
+     * @default {seconds: 10}
+     */
+    timeout?: Readonly<AnyDuration> | undefined;
+};
+/**
+ * Collapsed version of {@link SendAndWaitForReplyParams} for the `sendAndWaitForReply` method 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 CollapsedSendAndWaitForReplyParams<Location extends WebSocketLocation, WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+}>> | NoParam = NoParam> = HasRequiredKeys<SendAndWaitForReplyParams<Location, WebSocketToConnect>> extends true ? [SendAndWaitForReplyParams<Location, WebSocketToConnect>] : [SendAndWaitForReplyParams<Location, WebSocketToConnect>?];
+/**
+ * Takes any WebSocket class and overwrites it with some new rest vir methods and makes some
+ * existing WebSocket methods type safe.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type OverwriteWebSocketMethods<WebSocketClass extends CommonWebSocket, Location extends WebSocketLocation, OriginalWebSocketDefinition extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    SearchParamsType: true;
+}>> | NoParam = NoParam> = Overwrite<WebSocketClass, {
+    /**
+     * Adds an event listener that's wrapped in assertions to verify that message events have
+     * the expected contents.
+     */
+    addEventListener<const EventName extends keyof CommonWebSocketEventMap>(eventName: EventName, listener: WebSocketListener<EventName, OriginalWebSocketDefinition, FlipWebSocketLocation<Location>, WebSocketClass>): void;
+    /**
+     * Sends a message to the other side of the WebSocket connection and waits that other side
+     * to send a message in response.
+     *
+     * This will catch messages that might not have been intended as a response for the original
+     * message as it will catch _any_ message sent from the other side.
+     */
+    sendAndWaitForReply(...params: CollapsedSendAndWaitForReplyParams<Location, OriginalWebSocketDefinition>): Promise<OriginalWebSocketDefinition extends NoParam ? any : GetWebSocketMessageTypeFromLocation<Exclude<OriginalWebSocketDefinition, NoParam>, FlipWebSocketLocation<Location>>>;
+    /**
+     * Sends data through the WebSocket to the other side of the connection. This rest-vir
+     * wrapper ensures that all sent messages match expected types from the WebSocket
+     * definition.
+     *
+     * See [MDN](https://developer.mozilla.org/docs/Web/API/WebSocket/send) for the original
+     * `WebSocket.send()` docs.
+     */
+    send(...args: OriginalWebSocketDefinition extends NoParam ? [message?: any] : GetWebSocketMessageTypeFromLocation<Exclude<OriginalWebSocketDefinition, NoParam>, Location> extends undefined ? [
+        message?: GetWebSocketMessageTypeFromLocation<Exclude<OriginalWebSocketDefinition, NoParam>, Location>
+    ] : [
+        message: GetWebSocketMessageTypeFromLocation<Exclude<OriginalWebSocketDefinition, NoParam>, Location>
+    ]): void;
+}>;
+/**
+ * A WebSocket instance used only in clients to connect to a host.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type ClientWebSocket<WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    SearchParamsType: true;
+}>> | NoParam = NoParam, WebSocketClass extends CommonWebSocket = CommonWebSocket> = OverwriteWebSocketMethods<WebSocketClass, WebSocketLocation.OnClient, WebSocketToConnect>;
+/**
+ * Parameters for a type-safe WebSocket listener callback. Used in {@link WebSocketListener}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type WebSocketListenerParams<EventName extends keyof CommonWebSocketEventMap, WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    SearchParamsType: true;
+}>> | NoParam, MessageSource extends WebSocketLocation, WebSocketClass extends CommonWebSocket> = {
+    webSocketDefinition: WebSocketToConnect extends NoParam ? Readonly<Overwrite<WebSocketDefinition, 
+    /**
+     * This `Overwrite` is needed so that
+     * `CollapsedConnectWebSocketParams<ACTUAL_SOCKET>` can be assigned to
+     * `CollapsedConnectWebSocketParams<NoParam>`. Idk why.
+     */
+    {
+        path: any;
+        customProps: any;
+    }>> : Readonly<WebSocketToConnect>;
+    webSocket: ClientWebSocket<WebSocketToConnect, WebSocketClass>;
+} & (EventName extends 'message' ? {
+    event: Overwrite<CommonWebSocketEventMap[EventName], {
+        data: WebSocketToConnect extends NoParam ? any : GetWebSocketMessageTypeFromLocation<Exclude<WebSocketToConnect, NoParam>, MessageSource>;
+    }>;
+    searchParams: WebSocketToConnect extends NoParam ? any : Exclude<WebSocketToConnect, NoParam>['SearchParamsType'];
+    message: WebSocketToConnect extends NoParam ? any : GetWebSocketMessageTypeFromLocation<Exclude<WebSocketToConnect, NoParam>, MessageSource>;
+} : {
+    event: CommonWebSocketEventMap[EventName];
+});
+/**
+ * An object defining declaratively created listeners that will be attached to a rest-vir
+ * client-side WebSocket.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type ConnectWebSocketListeners<WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    SearchParamsType: true;
+}>> | NoParam, WebSocketClass extends CommonWebSocket> = Partial<{
+    [EventName in keyof CommonWebSocketEventMap]: WebSocketListener<EventName, WebSocketToConnect, WebSocketLocation.OnHost, WebSocketClass>;
+}>;
+/**
+ * A type-safe WebSocket listener callback.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type WebSocketListener<EventName extends keyof CommonWebSocketEventMap, WebSocketToConnect extends Readonly<SelectFrom<WebSocketDefinition, {
+    MessageFromClientType: true;
+    MessageFromHostType: true;
+    SearchParamsType: true;
+}>> | NoParam, MessageSource extends WebSocketLocation, WebSocketClass extends CommonWebSocket> = (params: WebSocketListenerParams<EventName, WebSocketToConnect, MessageSource, WebSocketClass>) => MaybePromise<void>;
+/**
+ * Generic connection parameters for `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 GenericConnectWebSocketParams<WebSocketClass extends CommonWebSocket> = {
+    /** Parameters for WebSocket paths that need them, like `'/my-path/:param1/:param2'`. */
+    pathParams?: Record<string, string> | undefined;
+    /**
+     * A list of WebSocket protocols. This is the standard built-in argument for the `WebSocket`
+     * constructor.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#protocols
+     */
+    protocols?: string[];
+    /**
+     * Optional listeners that can be immediately attached to the WebSocket instance instead of
+     * requiring externally adding them.
+     */
+    listeners?: ConnectWebSocketListeners<NoParam, WebSocketClass>;
+    /**
+     * A custom `WebSocket` constructor. Useful for debugging or unit testing. This can safely be
+     * omitted to use the default JavaScript built-in global `WebSocket` class.
+     *
+     * @default globalThis.WebSocket
+     */
+    webSocketConstructor?: (new (url: string, protocols: string[] | undefined, webSocketDefinition: WebSocketDefinition) => WebSocketClass) | undefined;
+    searchParams?: unknown;
+};
+/**
+ * Overwrites WebSocket methods with their rest-vir, type-safe replacements.
+ *
+ * WARNING: this mutates the input WebSocket.
+ *
+ * @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 overwriteWebSocketMethods<const WebSocketToConnect extends WebSocketDefinition | NoParam, const WebSocketClass extends CommonWebSocket, const Location extends WebSocketLocation>(webSocketDefinition: WebSocketToConnect extends NoParam ? WebSocketDefinition : WebSocketToConnect, rawWebSocket: Readonly<WebSocketClass>, webSocketLocation: Location): OverwriteWebSocketMethods<WebSocketClass, Location, WebSocketToConnect>;
+/**
+ * Waits for a WebSocket to reach to the open state.
+ *
+ * @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 waitForOpenWebSocket(webSocket: Readonly<Pick<CommonWebSocket, 'readyState' | 'addEventListener' | 'removeEventListener'>>): Promise<void>;
+/**
+ * Overwrites WebSocket methods with the typed rest-vir replacements, attaches WebSocket listeners,
+ * and waits for the WebSocket to be opened.
+ *
+ * @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 finalizeWebSocket<const WebSocketToConnect extends Readonly<WebSocketDefinition> | NoParam, const WebSocketClass extends CommonWebSocket, const Location extends WebSocketLocation>(webSocketDefinition: WebSocketToConnect extends NoParam ? WebSocketDefinition : WebSocketToConnect, 
+/** An already-constructed WebSocket instance. */
+webSocketInput: WebSocketClass, listeners: ConnectWebSocketListeners<NoParam, WebSocketClass> | undefined, location: Location): Promise<OverwriteWebSocketMethods<WebSocketClass, Location, WebSocketToConnect>>;
+/**
+ * Verifies that the given WebSocket message matches the defined expectations for the given message
+ * source.
+ *
+ * @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 verifyWebSocketMessage<const SpecificWebSocket extends SelectFrom<WebSocketDefinition, {
+    MessageFromHostType: true;
+    messageFromHostShape: true;
+    messageFromClientShape: true;
+    path: true;
+    service: {
+        serviceName: true;
+    };
+}>, Location extends WebSocketLocation>(webSocketDefinition: Readonly<SpecificWebSocket>, 
+/** The raw message data. */
+message: any, 
+/** The location from which the message was sent. */
+messageSentFrom: Location): SpecificWebSocket['MessageFromHostType'];

package/dist/web-socket/overwrite-web-socket-methods.js

@@ -0,0 +1,210 @@
+import { waitUntil } from '@augment-vir/assert';
+import { DeferredPromise, ensureErrorAndPrependMessage, getOrSet, stringify, } from '@augment-vir/common';
+import { convertDuration } from 'date-vir';
+import { assertValidShape } from 'object-shape-tester';
+import { parseJsonWithUndefined } from '../augments/json.js';
+import { CommonWebSocketState, } from './common-web-socket.js';
+/**
+ * Location of the WebSocket in question: on a client connecting to a WebSocket host or on the host
+ * that's accepting WebSocket connections.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export var WebSocketLocation;
+(function (WebSocketLocation) {
+    WebSocketLocation["OnHost"] = "on-host";
+    WebSocketLocation["OnClient"] = "on-client";
+})(WebSocketLocation || (WebSocketLocation = {}));
+/**
+ * Returns the inverse WebSocket location compared to the given WebSocket location. For example,
+ * passing in `WebSocketLocation.OnHost` here will give you `WebSocketLocation.OnClient`.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function getOppositeWebSocketLocation(originalWebSocketLocation) {
+    if (originalWebSocketLocation === WebSocketLocation.OnClient) {
+        return WebSocketLocation.OnHost;
+    }
+    else {
+        return WebSocketLocation.OnClient;
+    }
+}
+/**
+ * Overwrites WebSocket methods with their rest-vir, type-safe replacements.
+ *
+ * WARNING: this mutates the input WebSocket.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function overwriteWebSocketMethods(webSocketDefinition, rawWebSocket, webSocketLocation) {
+    const originalSend = rawWebSocket.send;
+    const originalAddEventListener = rawWebSocket.addEventListener;
+    const originalRemoveEventListener = rawWebSocket.removeEventListener;
+    const webSocket = rawWebSocket;
+    const originalListenerMap = {};
+    Object.assign(webSocket, {
+        originalListenerMap,
+        addEventListener(eventName, listener) {
+            function newListener(event) {
+                const baseParams = {
+                    event,
+                    webSocket,
+                    webSocketDefinition,
+                };
+                if (eventName === 'message') {
+                    const message = verifyWebSocketMessage(webSocketDefinition, parseJsonWithUndefined(String(event.data)), 
+                    /**
+                     * Flip the WebSocket location because messages on the client WebSocket will
+                     * come from the host and messages on the host WebSocket will come from the
+                     * client.
+                     */
+                    getOppositeWebSocketLocation(webSocketLocation));
+                    return listener({
+                        ...baseParams,
+                        message,
+                    });
+                }
+                else {
+                    return listener(baseParams);
+                }
+            }
+            getOrSet(originalListenerMap, eventName, () => new WeakMap()).set(listener, newListener);
+            return originalAddEventListener.call(webSocket, eventName, newListener);
+        },
+        removeEventListener(eventName, listener) {
+            const existing = originalListenerMap[eventName]?.get(listener);
+            if (existing) {
+                originalListenerMap[eventName]?.delete(listener);
+                originalRemoveEventListener.call(webSocket, eventName, existing);
+            }
+        },
+        async sendAndWaitForReply({ message, timeout = { seconds: 10 }, } = {}) {
+            const deferredReply = new DeferredPromise();
+            function listener({ message, }) {
+                if (!deferredReply.isSettled) {
+                    deferredReply.resolve(message);
+                }
+            }
+            setTimeout(() => {
+                if (!deferredReply.isSettled) {
+                    deferredReply.reject('Timeout: got no reply from the host.');
+                }
+            }, convertDuration(timeout, { milliseconds: true }).milliseconds);
+            webSocket.addEventListener('message', listener);
+            webSocket.send(message);
+            try {
+                const reply = await deferredReply.promise;
+                return reply;
+            }
+            finally {
+                webSocket.removeEventListener('message', listener);
+            }
+        },
+        send(message) {
+            originalSend.call(webSocket, 
+            /** The extra `String()` wrapper is to convert `undefined` into `'undefined'`. */
+            String(JSON.stringify(verifyWebSocketMessage(webSocketDefinition, message, webSocketLocation))));
+        },
+    });
+    return webSocket;
+}
+/**
+ * Waits for a WebSocket to reach to the open state.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export async function waitForOpenWebSocket(webSocket) {
+    const webSocketOpenedPromise = new DeferredPromise();
+    function errorListener(error) {
+        if (!webSocketOpenedPromise.isSettled) {
+            webSocketOpenedPromise.reject(ensureErrorAndPrependMessage(error, 'WebSocket connection failed.'));
+        }
+    }
+    webSocket.addEventListener('error', errorListener);
+    void waitUntil
+        .isTruthy(() => {
+        if (webSocketOpenedPromise.isSettled) {
+            return true;
+        }
+        if (webSocket.readyState === CommonWebSocketState.Closed) {
+            webSocketOpenedPromise.reject('WebSocket closed while waiting for it to open.');
+            return true;
+        }
+        else if (webSocket.readyState === CommonWebSocketState.Open) {
+            webSocketOpenedPromise.resolve();
+            return true;
+        }
+        else {
+            return false;
+        }
+    }, undefined, 'WebSocket never opened')
+        .catch((error) => {
+        if (!webSocketOpenedPromise.isSettled) {
+            webSocketOpenedPromise.reject(error);
+        }
+    });
+    await webSocketOpenedPromise.promise.finally(() => {
+        webSocket.removeEventListener('error', errorListener);
+    });
+}
+/**
+ * Overwrites WebSocket methods with the typed rest-vir replacements, attaches WebSocket listeners,
+ * and waits for the WebSocket to be opened.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export async function finalizeWebSocket(webSocketDefinition, 
+/** An already-constructed WebSocket instance. */
+webSocketInput, listeners, location) {
+    const webSocket = overwriteWebSocketMethods(webSocketDefinition, webSocketInput, location);
+    if (listeners?.open) {
+        webSocket.addEventListener('open', listeners.open);
+    }
+    if (listeners?.error) {
+        webSocket.addEventListener('error', listeners.error);
+    }
+    if (listeners?.message) {
+        webSocket.addEventListener('message', listeners.message);
+    }
+    if (listeners?.close) {
+        webSocket.addEventListener('close', listeners.close);
+    }
+    await waitForOpenWebSocket(webSocketInput);
+    return webSocket;
+}
+/**
+ * Verifies that the given WebSocket message matches the defined expectations for the given message
+ * source.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function verifyWebSocketMessage(webSocketDefinition, 
+/** The raw message data. */
+message, 
+/** The location from which the message was sent. */
+messageSentFrom) {
+    const shape = messageSentFrom === WebSocketLocation.OnClient
+        ? webSocketDefinition.messageFromClientShape
+        : webSocketDefinition.messageFromHostShape;
+    if (shape) {
+        assertValidShape(message, shape, {
+            allowExtraKeys: true,
+        });
+    }
+    else if (message) {
+        throw new TypeError(`WebSocket '${webSocketDefinition.path}' in service '${webSocketDefinition.service.serviceName}' does not expect any message data from the ${messageSentFrom === WebSocketLocation.OnClient ? 'client' : 'host'} but received it: ${stringify(message)}.`);
+    }
+    return message;
+}

package/dist/web-socket/web-socket-definition.d.ts

@@ -0,0 +1,170 @@
+import { AnyObject, Overwrite, type SelectFrom } from '@augment-vir/common';
+import { ShapeDefinition, ShapeToRuntimeType } from 'object-shape-tester';
+import type { IsEqual } from 'type-fest';
+import { EndpointPathBase } from '../endpoint/endpoint-path.js';
+import { MinimalService } from '../service/minimal-service.js';
+import { NoParam } from '../util/no-param.js';
+import { OriginRequirement } from '../util/origin.js';
+import type { BaseSearchParams } from '../util/search-params.js';
+/**
+ * Initialization for a WebSocket within a service 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 WebSocketInit<MessageFromClientShape = unknown, MessageFromServerShape = unknown> = {
+    messageFromClientShape: MessageFromClientShape;
+    messageFromHostShape: MessageFromServerShape;
+    /**
+     * 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 (that is parsed by the
+     * [`object-shape-tester`](https://www.npmjs.com/package/object-shape-tester) package) that all
+     * protocols for this WebSocket are collectively tested against. Omit this or set it to
+     * `undefined` to allow a string array of any length.
+     *
+     * This shape will be tested against all protocols together in a single array, so this should be
+     * an array shape. Only string-compatible values inside the array will work. It is recommended
+     * to use `tupleShape` from the `object-shape-tester` package.
+     *
+     * @example
+     *
+     * ```ts
+     * import {tupleShape, exact} from 'object-shape-tester';
+     *
+     * const partialWebSocketInit = {
+     *     protocolsShape: tupleShape('', exact('hi')),
+     * };
+     * ```
+     */
+    protocolsShape?: unknown;
+    /**
+     * 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, tupleShape} from 'object-shape-tester';
+     *
+     * const partialWebSocketInit = {
+     *     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;
+    /** Attach any other properties that you want inside of here. */
+    customProps?: Record<PropertyKey, unknown> | undefined;
+};
+/**
+ * Adds final props to a {@link WebSocketInit}, converting it into a {@link WebSocketDefinition}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type WithFinalWebSocketProps<Init, WebSocketPath extends EndpointPathBase> = (Init extends AnyObject ? Overwrite<Init, {
+    messageFromClientShape: IsEqual<Init['messageFromClientShape'], NoParam> extends true ? any : Init['messageFromClientShape'] extends NoParam ? ShapeDefinition<any, true> | undefined : undefined extends Init['messageFromClientShape'] ? undefined : ShapeDefinition<Init['messageFromClientShape'], true>;
+    messageFromHostShape: IsEqual<Init['messageFromHostShape'], NoParam> extends true ? any : Init['messageFromHostShape'] extends NoParam ? ShapeDefinition<any, true> | undefined : undefined extends Init['messageFromHostShape'] ? undefined : ShapeDefinition<Init['messageFromHostShape'], true>;
+    MessageFromClientType: Init['messageFromClientShape'] extends NoParam ? any : undefined extends Init['messageFromClientShape'] ? undefined : ShapeToRuntimeType<ShapeDefinition<Init['messageFromClientShape'], true>, false, true>;
+    MessageFromHostType: Init['messageFromHostShape'] extends NoParam ? any : undefined extends Init['messageFromHostShape'] ? undefined : ShapeToRuntimeType<ShapeDefinition<Init['messageFromHostShape'], true>, false, true>;
+    protocolsShape: 'protocolsShape' extends keyof Init ? undefined extends Init['protocolsShape'] ? undefined : ShapeDefinition<Init['protocolsShape'], true> | undefined : undefined;
+    ProtocolsType: undefined extends Init['protocolsShape'] ? string[] : ShapeToRuntimeType<ShapeDefinition<Init['protocolsShape'], true>, false, true>;
+    searchParamsShape: 'searchParamsShape' extends keyof Init ? undefined extends Init['searchParamsShape'] ? undefined : ShapeDefinition<Init['searchParamsShape'], true> | undefined : undefined;
+    SearchParamsType: IsEqual<Init['searchParamsShape'], undefined> extends true ? BaseSearchParams : ShapeToRuntimeType<ShapeDefinition<Init['searchParamsShape'], true>, false, true>;
+    customProps: 'customProps' extends keyof Init ? Init['customProps'] : undefined;
+}> : never) & {
+    path: WebSocketPath;
+    isWebSocket: true;
+    isEndpoint: false;
+    service: MinimalService;
+};
+/**
+ * A finished REST server WebSocket definition. 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 WebSocketDefinition<MessageFromClientShape = NoParam, MessageFromServerShape = NoParam, WebSocketPath extends EndpointPathBase = EndpointPathBase> = WithFinalWebSocketProps<WebSocketInit<MessageFromClientShape, MessageFromServerShape>, WebSocketPath>;
+/**
+ * A generic version of {@link WebSocketDefinition} that any WebSocketDefinition 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 GenericWebSocketDefinition = Overwrite<WebSocketDefinition, {
+    protocolsShape: any;
+    ProtocolsType: any;
+    searchParamsShape: any;
+    SearchParamsType: any;
+}>;
+/**
+ * Shape definition for {@link WebSocketInit}.
+ *
+ * @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 webSocketInitShape: ShapeDefinition<{
+    messageFromClientShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+    messageFromHostShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+    searchParamsShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+    /**
+     * Set a required client origin for this WebSocket.
+     *
+     * - 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]>[]]>;
+    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;
+    }]>]>>;
+    protocolsShape: import("object-shape-tester").ShapeUnknown<[unknown]>;
+}, false>;
+/**
+ * Attaches message type-only getters to a WebSocket 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 attachWebSocketShapeTypeGetters<const T extends AnyObject>(webSocketDefinition: T): asserts webSocketDefinition is T & Pick<WebSocketDefinition, 'MessageFromClientType' | 'MessageFromHostType'>;
+/**
+ * Asserts the the WebSocket definition 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 assertValidWebSocketDefinition(webSocketDefinition: Readonly<SelectFrom<WebSocketDefinition, {
+    isEndpoint: true;
+    isWebSocket: true;
+    path: true;
+    service: {
+        serviceName: true;
+    };
+}>>): void;