@rest-vir/define-service 1.6.0 → 1.7.0

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

@@ -160,6 +160,67 @@ export declare function fetchEndpoint<const EndpointToFetch extends Readonly<Sel
         serviceName: true;
     };
 }>, ...params: CollapsedFetchEndpointParams<EndpointToFetch>): Promise<FetchEndpointOutput<EndpointToFetch>>;
+/**
+ * Type safe output from sending a stream request to an endpoint definition. Used by
+ * {@link fetchStreamEndpoint}.
+ *
+ * @category Internal
+ * @category Package : @rest-vir/define-service
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export type FetchStreamEndpointOutput = Readonly<{
+    ok: true;
+    stream: ReadableStream<Uint8Array>;
+    response: Readonly<Response>;
+}> | Readonly<{
+    ok: false;
+    data: string | undefined;
+    response: Readonly<Response>;
+}>;
+/**
+ * Send a request to an endpoint definition and return a `ReadableStream` instead of parsing the
+ * response body. This is useful for consuming SSE (Server-Sent Events) endpoints from frontend
+ * clients.
+ *
+ * Uses the same request-building and validation flow as {@link fetchEndpoint}, but skips response
+ * body and JSON validation.
+ *
+ * @category Client (Frontend) Connection
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {fetchStreamEndpoint} from '@rest-vir/define-service';
+ *
+ * const result = await fetchStreamEndpoint(myService.endpoints['/my-sse-endpoint']);
+ *
+ * if (result.ok) {
+ *     const reader = result.stream.getReader();
+ * }
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export declare function fetchStreamEndpoint<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;
+    searchParamsShape: true;
+    methods: true;
+    service: {
+        serviceOrigin: true;
+        serviceName: true;
+    };
+}>, ...params: CollapsedFetchEndpointParams<EndpointToFetch>): Promise<FetchStreamEndpointOutput>;
 /**
  * Build request init and URL for fetching an endpoint. Used in {@link fetchEndpoint}.
  *

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

@@ -97,6 +97,64 @@ export async function fetchEndpoint(endpoint, ...params) {
         };
     }
 }
+/**
+ * Send a request to an endpoint definition and return a `ReadableStream` instead of parsing the
+ * response body. This is useful for consuming SSE (Server-Sent Events) endpoints from frontend
+ * clients.
+ *
+ * Uses the same request-building and validation flow as {@link fetchEndpoint}, but skips response
+ * body and JSON validation.
+ *
+ * @category Client (Frontend) Connection
+ * @category Package : @rest-vir/define-service
+ * @example
+ *
+ * ```ts
+ * import {fetchStreamEndpoint} from '@rest-vir/define-service';
+ *
+ * const result = await fetchStreamEndpoint(myService.endpoints['/my-sse-endpoint']);
+ *
+ * if (result.ok) {
+ *     const reader = result.stream.getReader();
+ * }
+ * ```
+ *
+ * @package [`@rest-vir/define-service`](https://www.npmjs.com/package/@rest-vir/define-service)
+ */
+export async function fetchStreamEndpoint(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);
+    if (response.ok) {
+        if (!response.body) {
+            throw new Error(`Endpoint '${endpoint.path}' returned an ok response with no body to stream.`);
+        }
+        return {
+            ok: true,
+            stream: response.body,
+            response,
+        };
+    }
+    else {
+        const responseText = await response.clone().text();
+        return {
+            ok: false,
+            data: responseText || undefined,
+            response,
+        };
+    }
+}
 /**
  * Build request init and URL for fetching an endpoint. Used in {@link fetchEndpoint}.
  *

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

@@ -5,7 +5,7 @@ import { type CommonWebSocket } from '../web-socket/common-web-socket.js';
 import { type ClientWebSocket, type GenericConnectWebSocketParams } from '../web-socket/overwrite-web-socket-methods.js';
 import { type GenericWebSocketDefinition } from '../web-socket/web-socket-definition.js';
 import { type CollapsedConnectWebSocketParams } from './connect-web-socket.js';
-import { buildEndpointUrl, type CollapsedFetchEndpointParams, type FetchEndpointOutput, type GenericFetchEndpointParams } from './fetch-endpoint.js';
+import { buildEndpointUrl, type CollapsedFetchEndpointParams, type FetchEndpointOutput, type FetchStreamEndpointOutput, type GenericFetchEndpointParams } from './fetch-endpoint.js';
 /**
  * An API generated by {@link generateApi}. This can be easily mocked by wrapping this API in
  * {@link makeMockApi}.
@@ -23,6 +23,12 @@ export declare class RestVirApi<SpecificService extends ServiceDefinition> {
         [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]>>;
+            /**
+             * Send a fetch request to this endpoint and return a `ReadableStream` instead of
+             * parsing the response body. Useful for consuming SSE (Server-Sent Events)
+             * endpoints.
+             */
+            fetchStream(...params: CollapsedFetchEndpointParams<SpecificService['endpoints'][EndpointPath]>): Promise<FetchStreamEndpointOutput>;
             buildUrl(params: Parameters<typeof buildEndpointUrl<SpecificService['endpoints'][EndpointPath]>>[1]): string;
         } : never;
     };

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

@@ -1,6 +1,6 @@
 import { mapObjectValues, } from '@augment-vir/common';
 import { connectWebSocket } from './connect-web-socket.js';
-import { buildEndpointUrl, fetchEndpoint, } from './fetch-endpoint.js';
+import { buildEndpointUrl, fetchEndpoint, fetchStreamEndpoint, } from './fetch-endpoint.js';
 /**
  * An API generated by {@link generateApi}. This can be easily mocked by wrapping this API in
  * {@link makeMockApi}.
@@ -32,16 +32,23 @@ export class RestVirApi {
     constructor(service, { endpointFetch, webSocketConnect, serviceOrigin } = {}) {
         this.serviceOrigin = serviceOrigin || service.serviceOrigin;
         this.endpoints = mapObjectValues(service.endpoints, (endpointPath, endpointDefinition) => {
+            const endpointWithOrigin = () => ({
+                ...endpointDefinition,
+                service: {
+                    ...endpointDefinition.service,
+                    serviceOrigin: this.serviceOrigin,
+                },
+            });
             return {
                 ...endpointDefinition,
                 fetch: (...params) => {
-                    return fetchEndpoint({
-                        ...endpointDefinition,
-                        service: {
-                            ...endpointDefinition.service,
-                            serviceOrigin: this.serviceOrigin,
-                        },
-                    }, {
+                    return fetchEndpoint(endpointWithOrigin(), {
+                        ...endpointFetch,
+                        ...params[0],
+                    });
+                },
+                fetchStream: (...params) => {
+                    return fetchStreamEndpoint(endpointWithOrigin(), {
                         ...endpointFetch,
                         ...params[0],
                     });
@@ -119,6 +126,12 @@ export function makeMockApi(api, mocks) {
                         ...params[0],
                     });
                 },
+                fetchStream: (...params) => {
+                    return fetchStreamEndpoint(endpointDefinition, {
+                        fetch: mocks.fetch,
+                        ...params[0],
+                    });
+                },
             };
         }),
         webSockets: mapObjectValues(api.webSockets, (webSocketPath, webSocketDefinition) => {

package/package.json

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