@rest-vir/define-service 0.0.2

package/dist/frontend-connect/fetch-endpoint.js

@@ -0,0 +1,135 @@
+import { check } from '@augment-vir/assert';
+import { addPrefix, filterMap, getObjectTypedEntries, HttpMethod, } from '@augment-vir/common';
+import { assertValidShape } from 'object-shape-tester';
+import { buildUrl } from 'url-vir';
+function defaultFetch(...[url, requestInit,]) {
+    return fetch(url, requestInit);
+}
+/**
+ * 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 function getAllowedEndpointMethods(endpoint) {
+    return filterMap(getObjectTypedEntries(endpoint.methods), ([methodName,]) => methodName, (methodName, [, allowed,]) => allowed);
+}
+function filterToValidMethod(endpoint, chosenMethod) {
+    if (chosenMethod && (chosenMethod === HttpMethod.Options || endpoint.methods[chosenMethod])) {
+        return chosenMethod;
+    }
+    else if (chosenMethod) {
+        throw new Error(`Given HTTP method '${chosenMethod}' is not allowed for endpoint '${endpoint.path}' in service '${endpoint.service.serviceName}'`);
+    }
+    const allowedMethods = getAllowedEndpointMethods(endpoint);
+    if (check.isLengthExactly(allowedMethods, 1)) {
+        return allowedMethods[0];
+    }
+    else if (allowedMethods.length) {
+        throw new Error(`Endpoint '${endpoint.path}' in service '${endpoint.service.serviceName}' allows multiple HTTP methods, one must be chosen.`);
+    }
+    else {
+        throw new Error(`Endpoint '${endpoint.path}' in service '${endpoint.service.serviceName}' has no allowed HTTP methods. Requests cannot be sent.`);
+    }
+}
+/**
+ * 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 async function fetchEndpoint(endpoint, ...params) {
+    const { requestData, fetch } = params[0] || {};
+    if (requestData) {
+        if (endpoint.requestDataShape) {
+            assertValidShape(requestData, endpoint.requestDataShape, { allowExtraKeys: true });
+        }
+        else {
+            throw new Error(`Request data was given but endpoint '${endpoint.path}' is not expecting any request data.`);
+        }
+    }
+    const { requestInit, url } = buildEndpointRequestInit(endpoint, ...params);
+    /* node:coverage ignore next: all tests mock fetch so we're never going to have a fallback here. */
+    const response = await (fetch || defaultFetch)(url, requestInit, endpoint);
+    const responseData = endpoint.responseDataShape ? await response.json() : undefined;
+    if (endpoint.responseDataShape) {
+        assertValidShape(responseData, endpoint.responseDataShape, { allowExtraKeys: true });
+    }
+    return {
+        data: responseData,
+        response,
+    };
+}
+/**
+ * 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 function buildEndpointRequestInit(endpoint, ...[{ method, options = {}, pathParams, requestData } = {},]) {
+    const headers = options.headers instanceof Headers
+        ? Object.fromEntries(options.headers.entries())
+        : check.isArray(options.headers)
+            ? Object.fromEntries(options.headers)
+            : options.headers || {};
+    const hasContentTypeHeader = Object.keys(headers).some((headerKey) => headerKey.toLowerCase() === 'content-type');
+    if (!hasContentTypeHeader && check.isObject(requestData)) {
+        headers['content-type'] = 'application/json';
+    }
+    const url = buildEndpointUrl(endpoint, { pathParams });
+    const requestInit = {
+        ...options,
+        headers,
+        method: filterToValidMethod(endpoint, method),
+        ...(requestData
+            ? {
+                body: JSON.stringify(requestData),
+            }
+            : {}),
+    };
+    return {
+        url,
+        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 function buildEndpointUrl(endpoint, { pathParams, }) {
+    let pathParamsCount = 0;
+    const builtUrl = buildUrl(endpoint.service.serviceOrigin, {
+        pathname: endpoint.path.replaceAll(/\/:([^/]+)/g, (wholeMatch, paramName) => {
+            pathParamsCount++;
+            if (pathParams && check.hasKey(pathParams, paramName) && pathParams[paramName]) {
+                return addPrefix({
+                    value: pathParams[paramName],
+                    prefix: '/',
+                });
+            }
+            else {
+                throw new Error(`Missing value for path param '${paramName}'.`);
+            }
+        }),
+    }).href;
+    if (!pathParamsCount && pathParams) {
+        throw new Error(`Endpoint '${endpoint.path}' in service '${endpoint.service.serviceName}' does not allow any path params but some where set.`);
+    }
+    return builtUrl;
+}

package/dist/frontend-connect/generate-api.d.ts

@@ -0,0 +1,102 @@
+import { MaybePromise, Overwrite, PartialWithUndefined, type Values } from '@augment-vir/common';
+import type { GenericEndpointDefinition } from '../endpoint/endpoint.js';
+import type { ServiceDefinition } from '../service/service-definition.js';
+import type { CommonWebSocket } from '../web-socket/common-web-socket.js';
+import { ClientWebSocket, GenericConnectWebSocketParams } from '../web-socket/overwrite-web-socket-methods.js';
+import type { WebSocketDefinition } from '../web-socket/web-socket-definition.js';
+import { CollapsedConnectWebSocketParams } from './connect-web-socket.js';
+import { CollapsedFetchEndpointParams, FetchEndpointOutput } from './fetch-endpoint.js';
+/**
+ * An API generated by {@link generateApi}. This can be easily mocked by wrapping this API in
+ * {@link makeMockApi}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type RestVirApi<SpecificService extends ServiceDefinition> = {
+    endpoints: {
+        [EndpointPath in keyof SpecificService['endpoints']]: SpecificService['endpoints'][EndpointPath] extends GenericEndpointDefinition ? SpecificService['endpoints'][EndpointPath] & {
+            /** Send a fetch request to this endpoint. */
+            fetch(...params: CollapsedFetchEndpointParams<SpecificService['endpoints'][EndpointPath]>): Promise<FetchEndpointOutput<SpecificService['endpoints'][EndpointPath]>>;
+        } : never;
+    };
+    webSockets: {
+        [WebSocketPath in keyof SpecificService['webSockets']]: SpecificService['webSockets'][WebSocketPath] extends WebSocketDefinition ? SpecificService['webSockets'][WebSocketPath] & {
+            /** Connect to this WebSocket. */
+            connect(...params: CollapsedConnectWebSocketParams<SpecificService['webSockets'][WebSocketPath], false, globalThis.WebSocket>): Promise<ClientWebSocket<SpecificService['webSockets'][WebSocketPath], globalThis.WebSocket>>;
+        } : never;
+    };
+};
+/**
+ * Creates an API from the given service definition, with automatically generated endpoint fetch and
+ * WebSocket connect methods.
+ *
+ * Use this to ship auto-generated API objects to internal or external teams so they have type safe
+ * access to your REST and WebSocket server.
+ *
+ * The generated API can easily mocked by wrapping it in {@link makeMockApi}.
+ *
+ * @category Create API
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {generateApi} from '@rest-vir/define-service';
+ *
+ * export const myApi = generateApi(myServiceDefinition);
+ *
+ * myApi.endpoints['/my-endpoint'].fetch();
+ * myApi.webSockets['/my-web-socket'].connect();
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function generateApi<const SpecificService extends ServiceDefinition>(service: SpecificService): RestVirApi<SpecificService>;
+/**
+ * Mock inputs for {@link makeMockApi}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type RestVirApiMocks<Api extends RestVirApi<any>, WebSocketClass extends CommonWebSocket> = PartialWithUndefined<{
+    /**
+     * A custom fetch mock that will override the default, if provided. This can safely be omitted
+     * to use the default JavaScript built-in global `fetch` function.
+     *
+     * See {@link createMockEndpointFetch} or {@link createMockEndpointResponse} for assistance
+     * mocking this.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: (url: string, requestInit: RequestInit, endpoint?: Values<Api['endpoints']> | undefined) => MaybePromise<Response>;
+    webSocketConstructor?: GenericConnectWebSocketParams<WebSocketClass>['webSocketConstructor'];
+}>;
+/**
+ * Overwrites types for an existing {@link RestVirApi} instance with mocks. This is created by
+ * {@link makeMockApi}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type MockExistingApi<Api extends RestVirApi<any>, WebSocketClass extends CommonWebSocket> = Overwrite<Api, {
+    webSockets: {
+        [WebSocketPath in keyof Api['webSockets']]: Api['webSockets'][WebSocketPath] extends WebSocketDefinition ? Overwrite<Api['webSockets'][WebSocketPath], {
+            /** Connect to this WebSocket. */
+            connect(...params: CollapsedConnectWebSocketParams<Api['webSockets'][WebSocketPath], false, WebSocketClass>): Promise<ClientWebSocket<Api['webSockets'][WebSocketPath], WebSocketClass>>;
+        }> : never;
+    };
+}>;
+/**
+ * Overwrites a generated API's fetch and WebSocket connect methods with a mocked fetch function and
+ * a mocked WebSocket constructor so you can have full control over them for unit-testing purposes.
+ *
+ * With this, you can unit test your clients without spinning up a mock API server.
+ *
+ * @category Testing : Client (Frontend)
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function makeMockApi<const Api extends RestVirApi<any>, const WebSocketClass extends CommonWebSocket>(api: Readonly<Api>, mocks: RestVirApiMocks<Api, WebSocketClass>): MockExistingApi<Api, WebSocketClass>;

package/dist/frontend-connect/generate-api.js

@@ -0,0 +1,83 @@
+import { mapObjectValues, } from '@augment-vir/common';
+import { connectWebSocket } from './connect-web-socket.js';
+import { fetchEndpoint, } from './fetch-endpoint.js';
+/**
+ * Creates an API from the given service definition, with automatically generated endpoint fetch and
+ * WebSocket connect methods.
+ *
+ * Use this to ship auto-generated API objects to internal or external teams so they have type safe
+ * access to your REST and WebSocket server.
+ *
+ * The generated API can easily mocked by wrapping it in {@link makeMockApi}.
+ *
+ * @category Create API
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {generateApi} from '@rest-vir/define-service';
+ *
+ * export const myApi = generateApi(myServiceDefinition);
+ *
+ * myApi.endpoints['/my-endpoint'].fetch();
+ * myApi.webSockets['/my-web-socket'].connect();
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function generateApi(service) {
+    return {
+        endpoints: mapObjectValues(service.endpoints, (endpointPath, endpointDefinition) => {
+            return {
+                ...endpointDefinition,
+                fetch: (...params) => {
+                    return fetchEndpoint(endpointDefinition, ...params);
+                },
+            };
+        }),
+        webSockets: mapObjectValues(service.webSockets, (webSocketPath, webSocketDefinition) => {
+            return {
+                ...webSocketDefinition,
+                connect: (...params) => {
+                    return connectWebSocket(webSocketDefinition, ...params);
+                },
+            };
+        }),
+    };
+}
+/**
+ * Overwrites a generated API's fetch and WebSocket connect methods with a mocked fetch function and
+ * a mocked WebSocket constructor so you can have full control over them for unit-testing purposes.
+ *
+ * With this, you can unit test your clients without spinning up a mock API server.
+ *
+ * @category Testing : Client (Frontend)
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export function makeMockApi(api, mocks) {
+    return {
+        endpoints: mapObjectValues(api.endpoints, (endpointPath, endpointDefinition) => {
+            return {
+                ...endpointDefinition,
+                fetch: (...params) => {
+                    return fetchEndpoint(endpointDefinition, {
+                        fetch: mocks.fetch,
+                        ...params[0],
+                    });
+                },
+            };
+        }),
+        webSockets: mapObjectValues(api.webSockets, (webSocketPath, webSocketDefinition) => {
+            return {
+                ...webSocketDefinition,
+                connect: (...params) => {
+                    return connectWebSocket(webSocketDefinition, {
+                        webSocketConstructor: mocks.webSocketConstructor,
+                        ...params[0],
+                    });
+                },
+            };
+        }),
+    };
+}

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

@@ -0,0 +1,187 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { CommonWebSocket, CommonWebSocketEventMap, CommonWebSocketState } from '../web-socket/common-web-socket.js';
+import { GenericConnectWebSocketParams, WebSocketLocation, type ClientWebSocket } from '../web-socket/overwrite-web-socket-methods.js';
+import { WebSocketDefinition } from '../web-socket/web-socket-definition.js';
+/**
+ * Parameters for {@link MockClientWebSocketClientSendCallback}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type MockClientWebSocketClientSendCallbackParams<WebSocketToConnect extends WebSocketDefinition> = {
+    webSocket: ClientWebSocket<WebSocketToConnect, MockClientWebSocket<WebSocketToConnect>>;
+    messageData: WebSocketToConnect['MessageFromClientType'];
+    messageSource: WebSocketLocation;
+};
+/**
+ * Type for {@link MockClientWebSocket.sendCallback}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type MockClientWebSocketClientSendCallback<WebSocketToConnect extends WebSocketDefinition> = (params: MockClientWebSocketClientSendCallbackParams<WebSocketToConnect>) => MaybePromise<void>;
+/**
+ * Options for {@link MockClientWebSocket} and {@link createMockClientWebSocketConstructor}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type MockClientWebSocketOptions<WebSocketToConnect extends WebSocketDefinition> = PartialWithUndefined<{
+    /**
+     * Set this to `true` if you want to prevent this mock WebSocket from immediately opening
+     * itself. You can then use `.open()` at any time to manually open it.
+     */
+    preventImmediateOpen: boolean;
+    sendCallback: MockClientWebSocketClientSendCallback<WebSocketToConnect>;
+}>;
+/**
+ * Use this to create a mock WebSocket constructor for unit testing Web Socket connection.
+ *
+ * This creates a {@link MockClientWebSocket} constructor for connections from the client side with
+ * types for the given {@link WebSocketDefinition} and utilizing the given
+ * {@link MockClientWebSocketOptions} instance. This can be passed to `connectWebSocket` as the
+ * `webSocketConstructor` to allow unit testing on a client without spinning up an entire host to
+ * serve the WebSocket connection.
+ *
+ * @category Testing : Client (Frontend)
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {
+ *     connectWebSocket,
+ *     createMockClientWebSocketConstructor,
+ * } from '@rest-vir/define-service';
+ *
+ * const webSocket = await connectWebSocket(myService.webSockets['/my-path'], {
+ *     webSocketConstructor: createMockClientWebSocketConstructor(
+ *         myService.webSockets['/my-path'],
+ *         {preventImmediateOpen: true},
+ *     ),
+ * });
+ *
+ * // mock server responses without an actual server
+ * webSocket.sendFromHost(myMessage);
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function createMockClientWebSocketConstructor<const WebSocketToConnect extends WebSocketDefinition>(webSocketToConnect: Readonly<WebSocketToConnect>, options?: Readonly<MockClientWebSocketOptions<WebSocketToConnect>>): typeof MockClientWebSocket<WebSocketToConnect>;
+/**
+ * Type for {@link MockClientWebSocket.listeners}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type MockClientWebSocketListeners = Partial<{
+    [EventName in keyof CommonWebSocketEventMap]: Set<(event: CommonWebSocketEventMap[EventName]) => void>;
+}>;
+/**
+ * A mock WebSocket constructor for connections from the client side. This can be passed to
+ * `connectWebSocket` as the `webSocketConstructor` to allow unit testing on a client without
+ * spinning up an entire host to serve the WebSocket connection.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {connectWebSocket, MockClientWebSocket} from '@rest-vir/define-service';
+ *
+ * const webSocket = await connectWebSocket(myService.webSockets['/my-path'], {
+ *     webSocketConstructor: MockClientWebSocket<(typeof myService.webSockets)['/my-path']>,
+ * });
+ *
+ * // mock server responses without an actual server
+ * webSocket.sendFromHost(myMessage);
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare class MockClientWebSocket<const WebSocketToConnect extends WebSocketDefinition = any> implements CommonWebSocket {
+    /**
+     * Mocked WebSocket event listeners. While this is public, you should attach a listener using
+     * {@link MockClientWebSocket.addEventListener} method and remove them with
+     * {@link MockClientWebSocket.removeEventListener}, as you would with a normal WebSocket
+     * instance.
+     */
+    listeners: MockClientWebSocketListeners;
+    /**
+     * Implements and mocks the standard `WebSocket.readyState` property.
+     *
+     * @see https://developer.mozilla.org/docs/Web/API/WebSocket/readyState
+     */
+    readyState: CommonWebSocketState;
+    /**
+     * This callback will be called whenever a message is sent to or from the WebSocket. This is set
+     * via the constructor option `sendCallback`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {MockClientWebSocket, connectWebSocket} from '@rest-vir/define-service';
+     *
+     * const webSocket = await connectWebSocket(myService.webSockets['/my-socket'], {
+     *     webSocketConstructor: createMockClientWebSocketConstructor(
+     *         myService.webSockets['/my-socket'],
+     *         {
+     *             sendCallback: (message) => {
+     *                 // handle the sent message here
+     *                 console.log('handled message:', message);
+     *             },
+     *         },
+     *     ),
+     * });
+     * ```
+     */
+    sendCallback: MockClientWebSocketClientSendCallback<WebSocketToConnect> | undefined;
+    constructor(...[, , , options,]: [
+        ...ConstructorParameters<NonNullable<GenericConnectWebSocketParams<any>['webSocketConstructor']>>,
+        options?: Readonly<MockClientWebSocketOptions<WebSocketToConnect>>
+    ]);
+    /**
+     * Manually set the WebSocket connection as opened. This is only necessary to use if you've set
+     * the constructor options to
+     */
+    open(): void;
+    /** Manually close and cleanup the WebSocket. */
+    close(): void;
+    /**
+     * Dispatch a WebSocket event. This is primarily used within the MockClientWebSocket class
+     * itself but may also be used externally to test various WebSocket scenarios.
+     *
+     * Note that dispatching `'open'` and `'close'` events will not actually close or open the
+     * WebSocket. Use the {@link MockClientWebSocket.open} and {@link MockClientWebSocket.close}
+     * methods instead (which appropriately dispatch their events).
+     */
+    dispatchEvent<const EventName extends keyof CommonWebSocketEventMap>(eventName: EventName, event: Omit<CommonWebSocketEventMap[EventName], 'type' | 'target'>): void;
+    /**
+     * Implements and mocks the standard `WebSocket.addEventListener` property but with message type
+     * safety.
+     *
+     * @see https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener
+     */
+    addEventListener<const EventName extends keyof CommonWebSocketEventMap>(eventName: EventName, listener: (event: CommonWebSocketEventMap[EventName]) => void): void;
+    /**
+     * Implements and mocks the standard `WebSocket.removeEventListener` property but with message
+     * type safety.
+     *
+     * @see https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener
+     */
+    removeEventListener<const EventName extends keyof CommonWebSocketEventMap>(eventName: EventName, listener: (event: CommonWebSocketEventMap[EventName]) => void): void;
+    /**
+     * Implements and mocks the standard `WebSocket.send` property but with message type safety.
+     *
+     * @see https://developer.mozilla.org/docs/Web/API/WebSocket/send
+     */
+    send(data: any): void;
+    /**
+     * Sends a message as if it came from the WebSocket host. Use this to unit test client-side
+     * WebSockets without needing a running host.
+     */
+    sendFromHost(data: WebSocketToConnect['MessageFromHostType']): void;
+}