@rest-vir/define-service 0.15.1 → 0.17.0

package/dist/endpoint/endpoint.d.ts

@@ -4,7 +4,6 @@ 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 { type BaseSearchParams } from '../util/search-params.js';
 import { type EndpointPathBase } from './endpoint-path.js';
 /**
  * The type for setting up an individual endpoint, used in `defineService`.
@@ -122,7 +121,7 @@ export type WithFinalEndpointProps<Init, EndpointPath extends EndpointPathBase>
     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 ? ShapeDefinition<Init['searchParamsShape'], true> | undefined : undefined;
-    SearchParamsType: 'searchParamsShape' extends keyof Init ? ShapeToRuntimeType<ShapeDefinition<Init['searchParamsShape'], true>, false, true> : BaseSearchParams;
+    SearchParamsType: 'searchParamsShape' extends keyof Init ? ShapeToRuntimeType<ShapeDefinition<Init['searchParamsShape'], true>, false, true> : undefined;
     customProps: 'customProps' extends keyof Init ? Init['customProps'] : undefined;
 }> : never) & {
     path: EndpointPath;

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

@@ -4,7 +4,7 @@ import { type 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';
+import { type GenericWebSocketDefinition, 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
@@ -28,7 +28,8 @@ export declare function buildWebSocketUrl(webSocketDefinition: Readonly<SelectFr
         serviceName: true;
         serviceOrigin: true;
     };
-}>>, ...[{ pathParams },]: CollapsedConnectWebSocketParams): string;
+    searchParamsShape: true;
+}>>, ...[{ pathParams, searchParams },]: CollapsedConnectWebSocketParams): string;
 /**
  * Params for {@link connectWebSocket}.
  *
@@ -64,7 +65,7 @@ export type ConnectWebSocketParams<WebSocketToConnect extends Readonly<SelectFro
 } : {
     protocols: WebSocketToConnect['ProtocolsType'];
 }) & (WebSocketToConnect['searchParamsShape'] extends undefined ? {
-    searchParams?: string[];
+    searchParams?: never;
 } : {
     searchParams: WebSocketToConnect['SearchParamsType'];
 });
@@ -92,4 +93,4 @@ export type CollapsedConnectWebSocketParams<WebSocketToConnect extends Readonly<
  * @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>>;
+export declare function connectWebSocket<const WebSocketToConnect extends Readonly<GenericWebSocketDefinition> | NoParam, WebSocketClass extends CommonWebSocket>(webSocketDefinition: WebSocketToConnect extends GenericWebSocketDefinition ? WebSocketToConnect : Readonly<WebSocketDefinition>, ...params: CollapsedConnectWebSocketParams<WebSocketToConnect, true, WebSocketClass>): Promise<ClientWebSocket<WebSocketToConnect, WebSocketClass>>;

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

@@ -31,7 +31,7 @@ export function assertValidWebSocketProtocols(protocols) {
  * @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 } = {},]) {
+export function buildWebSocketUrl(webSocketDefinition, ...[{ pathParams, searchParams } = {},]) {
     const httpUrl = buildEndpointUrl({
         methods: {
             [HttpMethod.Get]: true,
@@ -40,7 +40,8 @@ export function buildWebSocketUrl(webSocketDefinition, ...[{ pathParams } = {},]
         requestDataShape: undefined,
         responseDataShape: undefined,
         service: webSocketDefinition.service,
-    }, { pathParams });
+        searchParamsShape: webSocketDefinition.searchParamsShape,
+    }, { pathParams, searchParams });
     return buildUrl(httpUrl, {
         protocol: httpUrl.startsWith('https') ? 'wss' : 'ws',
     }).href;

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

@@ -3,6 +3,7 @@ import { type IsEqual, type IsNever } from 'type-fest';
 import { type PathParams } from '../endpoint/endpoint-path.js';
 import { type EndpointDefinition, type EndpointExecutorData, type GenericEndpointDefinition } from '../endpoint/endpoint.js';
 import { type NoParam } from '../util/no-param.js';
+import { type BaseSearchParams } from '../util/search-params.js';
 /**
  * A general version of {@link FetchEndpointParams} to be used when accepting _any_ endpoint (like in
  * tests).
@@ -14,6 +15,7 @@ import { type NoParam } from '../util/no-param.js';
 export type GenericFetchEndpointParams = {
     pathParams?: Record<string, string> | undefined;
     requestData?: any;
+    searchParams?: BaseSearchParams | undefined;
     method?: HttpMethod | undefined;
     options?: Omit<RequestInit, 'body' | 'method'> | undefined;
     /**
@@ -50,6 +52,10 @@ export type FetchEndpointParams<EndpointToFetch extends SelectFrom<EndpointDefin
 } : {
     /** This endpoint has no path parameters to configure. */
     pathParams?: undefined;
+}) & (EndpointToFetch['SearchParamsType'] extends undefined ? {
+    searchParams?: never;
+} : {
+    searchParams: EndpointToFetch['SearchParamsType'];
 }) & (EndpointExecutorData<EndpointToFetch>['request'] extends undefined ? {
     /**
      * This endpoint does not accept any request data, so there is none to be
@@ -141,6 +147,7 @@ export declare function fetchEndpoint<const EndpointToFetch extends Readonly<Sel
     requestDataShape: true;
     path: true;
     responseDataShape: true;
+    searchParamsShape: true;
     methods: true;
     service: {
         serviceOrigin: true;
@@ -167,12 +174,13 @@ export declare function buildEndpointRequestInit<const EndpointToFetch extends R
     requestDataShape: true;
     path: true;
     responseDataShape: true;
+    searchParamsShape: true;
     methods: true;
     service: {
         serviceOrigin: true;
         serviceName: true;
     };
-}>, ...[{ method, options, pathParams, requestData },]: CollapsedFetchEndpointParams<EndpointToFetch, false>): {
+}>, ...[{ method, options, pathParams, requestData, searchParams },]: CollapsedFetchEndpointParams<EndpointToFetch, false>): {
     url: string;
     requestInit: RequestInit;
 };
@@ -192,6 +200,7 @@ export declare function buildEndpointUrl<const EndpointToFetch extends Readonly<
     methods: true;
     requestDataShape: true;
     responseDataShape: true;
+    searchParamsShape: true;
 }>> | NoParam = NoParam>(endpoint: EndpointToFetch extends EndpointDefinition ? EndpointToFetch : SelectFrom<EndpointDefinition, {
     path: true;
     service: {
@@ -199,6 +208,7 @@ export declare function buildEndpointUrl<const EndpointToFetch extends Readonly<
         serviceName: true;
     };
     requestDataShape: true;
+    searchParamsShape: true;
     responseDataShape: true;
     methods: true;
-}>, { pathParams, }: Pick<EndpointToFetch extends NoParam ? Readonly<GenericFetchEndpointParams> : Readonly<FetchEndpointParams<Exclude<EndpointToFetch, NoParam>>>, 'pathParams'>): string;
+}>, { pathParams, searchParams, }: Pick<EndpointToFetch extends NoParam ? Readonly<GenericFetchEndpointParams> : Readonly<FetchEndpointParams<Exclude<EndpointToFetch, NoParam>>>, 'pathParams' | 'searchParams'>): string;

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

@@ -93,7 +93,7 @@ export async function fetchEndpoint(endpoint, ...params) {
  * @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 } = {},]) {
+export function buildEndpointRequestInit(endpoint, ...[{ method, options = {}, pathParams, requestData, searchParams } = {},]) {
     const headers = options.headers instanceof Headers
         ? Object.fromEntries(options.headers.entries())
         : check.isArray(options.headers)
@@ -112,7 +112,10 @@ export function buildEndpointRequestInit(endpoint, ...[{ method, options = {}, p
             headers['content-type'] = 'application/json';
         }
     }
-    const url = buildEndpointUrl(endpoint, { pathParams });
+    const url = buildEndpointUrl(endpoint, {
+        pathParams,
+        searchParams,
+    });
     const requestInit = {
         ...options,
         headers,
@@ -139,9 +142,16 @@ export function buildEndpointRequestInit(endpoint, ...[{ method, options = {}, p
  * @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, }) {
+export function buildEndpointUrl(endpoint, { pathParams, searchParams, }) {
     let pathParamsCount = 0;
+    if (endpoint.searchParamsShape) {
+        assertValidShape(searchParams, endpoint.searchParamsShape, {
+            /** Allow extra keys for forwards compatibility. */
+            allowExtraKeys: true,
+        }, `Invalid search params given to '${endpoint.path}' in service '${endpoint.service.serviceName}'`);
+    }
     const builtUrl = buildUrl(endpoint.service.serviceOrigin, {
+        search: searchParams,
         pathname: endpoint.path.replaceAll(/\/:([^/]+)/g, (wholeMatch, paramName) => {
             pathParamsCount++;
             if (pathParams && check.hasKey(pathParams, paramName) && pathParams[paramName]) {
@@ -156,7 +166,7 @@ export function buildEndpointUrl(endpoint, { pathParams, }) {
         }),
     }).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.`);
+        throw new Error(`'${endpoint.path}' in service '${endpoint.service.serviceName}' does not allow any path params but some where set.`);
     }
     return builtUrl;
 }

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

@@ -1,7 +1,7 @@
 import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
 import { CommonWebSocketState, type CommonWebSocket, type CommonWebSocketEventMap } from '../web-socket/common-web-socket.js';
 import { WebSocketLocation, type ClientWebSocket, type GenericConnectWebSocketParams } from '../web-socket/overwrite-web-socket-methods.js';
-import { type WebSocketDefinition } from '../web-socket/web-socket-definition.js';
+import { type GenericWebSocketDefinition, type WebSocketDefinition } from '../web-socket/web-socket-definition.js';
 /**
  * Parameters for {@link MockClientWebSocketClientSendCallback}.
  *
@@ -102,7 +102,7 @@ export type MockClientWebSocketListeners = Partial<{
  *
  * @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 {
+export declare class MockClientWebSocket<const WebSocketToConnect extends GenericWebSocketDefinition = 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

package/dist/util/origin.d.ts

@@ -56,3 +56,27 @@ export declare const originRequirementShape: import("object-shape-tester").Shape
 }]>, import("object-shape-tester").ShapeClass<[RegExpConstructor]>, () => void, import("object-shape-tester").ShapeOr<[string, import("object-shape-tester").ShapeExact<readonly [{
     anyOrigin: boolean;
 }]>, import("object-shape-tester").ShapeClass<[RegExpConstructor]>, () => void]>[]]>, false>;
+/**
+ * - `boolean`: the origin was explicitly checked and passed (`true`) or failed (`false`)
+ * - `undefined`: no origin checking occurred
+ * - `AnyOrigin`: requirements explicitly allow any origin.
+ */
+export type OriginRequirementResult = boolean | undefined | AnyOrigin;
+/**
+ * Checks the given origin against the given origin requirement and determine if the origin matches.
+ * See {@link OriginRequirementResult} for details on what each possible return value means.
+ *
+ * @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 checkOriginRequirement(origin: string | undefined, originRequirement: OriginRequirement): Promise<OriginRequirementResult>;
+/**
+ * Narrower version of {@link checkOriginRequirement} that simply returns `true` if the origin
+ * matched or `false` otherwise.
+ *
+ * @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 matchesOriginRequirement(origin: string | undefined, originRequirement: NonNullable<OriginRequirement>): Promise<boolean>;

package/dist/util/origin.js

@@ -31,3 +31,53 @@ export function isAnyOrigin(input) {
 export const originRequirementShape = defineShape(or(undefined, '', exact(AnyOrigin), classShape(RegExp), () => { }, [
     or('', exact(AnyOrigin), classShape(RegExp), () => { }),
 ]));
+/**
+ * Checks the given origin against the given origin requirement and determine if the origin matches.
+ * See {@link OriginRequirementResult} for details on what each possible return value means.
+ *
+ * @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 checkOriginRequirement(origin, originRequirement) {
+    if (isAnyOrigin(originRequirement)) {
+        /** Any origin has been explicitly allowed. */
+        return AnyOrigin;
+    }
+    else if (originRequirement === undefined) {
+        /** No checking occurred. */
+        return undefined;
+    }
+    else if (!origin) {
+        /** If there is an origin requirement but no origin then the origin automatically fails. */
+        return false;
+    }
+    else if (check.isString(originRequirement)) {
+        return origin === originRequirement;
+    }
+    else if (check.instanceOf(originRequirement, RegExp)) {
+        return !!originRequirement.exec(origin);
+    }
+    else if (check.isArray(originRequirement)) {
+        for (const requirement of originRequirement) {
+            if (await checkOriginRequirement(origin, requirement)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    else {
+        return await originRequirement(origin);
+    }
+}
+/**
+ * Narrower version of {@link checkOriginRequirement} that simply returns `true` if the origin
+ * matched or `false` otherwise.
+ *
+ * @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 matchesOriginRequirement(origin, originRequirement) {
+    return !!(await checkOriginRequirement(origin, originRequirement));
+}

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

@@ -2,6 +2,7 @@ import { type MaybePromise, type Overwrite, type SelectFrom } from '@augment-vir
 import { type AnyDuration } from 'date-vir';
 import { type HasRequiredKeys } from 'type-fest';
 import { type NoParam } from '../util/no-param.js';
+import { type BaseSearchParams } from '../util/search-params.js';
 import { type CommonWebSocket, type CommonWebSocketEventMap } from './common-web-socket.js';
 import { type WebSocketDefinition } from './web-socket-definition.js';
 /**
@@ -251,7 +252,7 @@ export type GenericConnectWebSocketParams<WebSocketClass extends CommonWebSocket
      * @default globalThis.WebSocket
      */
     webSocketConstructor?: (new (url: string, protocols: string[] | undefined, webSocketDefinition: WebSocketDefinition) => WebSocketClass) | undefined;
-    searchParams?: unknown;
+    searchParams?: BaseSearchParams | undefined;
 };
 /**
  * Overwrites WebSocket methods with their rest-vir, type-safe replacements.

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

@@ -1,4 +1,4 @@
-import { waitUntil } from '@augment-vir/assert';
+import { check, waitUntil } from '@augment-vir/assert';
 import { callAsynchronously, DeferredPromise, ensureErrorAndPrependMessage, getOrSet, stringify, wrapInTry, } from '@augment-vir/common';
 import { convertDuration } from 'date-vir';
 import { assertValidShape } from 'object-shape-tester';
@@ -138,6 +138,21 @@ export function overwriteWebSocketMethods(webSocketDefinition, rawWebSocket, web
     });
     return webSocket;
 }
+function cleanUpWebSocketError(error) {
+    if (check.isObject(error)) {
+        delete error.webSocket;
+        if (check.hasKey(error, 'webSocketDefinition') &&
+            check.hasKey(error.webSocketDefinition, 'path')) {
+            error.path = error.webSocketDefinition.path;
+        }
+        delete error.webSocketDefinition;
+        return error;
+        /* node:coverage ignore next 3: edge case */
+    }
+    else {
+        return error;
+    }
+}
 /**
  * Waits for a WebSocket to reach to the open state.
  *
@@ -149,7 +164,7 @@ export async function waitForOpenWebSocket(webSocket) {
     const webSocketOpenedPromise = new DeferredPromise();
     function errorListener(error) {
         if (!webSocketOpenedPromise.isSettled) {
-            webSocketOpenedPromise.reject(ensureErrorAndPrependMessage(error, 'WebSocket connection failed.'));
+            webSocketOpenedPromise.reject(ensureErrorAndPrependMessage(cleanUpWebSocketError(error), 'WebSocket connection failed.'));
         }
     }
     webSocket.addEventListener('error', errorListener);
@@ -172,7 +187,7 @@ export async function waitForOpenWebSocket(webSocket) {
     }, undefined, 'WebSocket never opened')
         .catch((error) => {
         if (!webSocketOpenedPromise.isSettled) {
-            webSocketOpenedPromise.reject(error);
+            webSocketOpenedPromise.reject(cleanUpWebSocketError(error));
         }
     });
     await webSocketOpenedPromise.promise.finally(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rest-vir/define-service",
-    "version": "0.15.1",
+    "version": "0.17.0",
     "description": "Define an connect to a declarative and type safe REST and WebSocket service.",
     "keywords": [
         "rest",