Implement Request Batches with callBatch

scripts/build-types.ts

@@ -164,6 +164,10 @@ export interface IncomingMessageTypes {
  * obs-websocket is responding to a request coming from a client
  */
 [WebSocketOpCode.RequestResponse]: ResponseMessage;
+/**
+ * obs-websocket is responding to a batch request coming from a client
+ */
+[WebSocketOpCode.RequestBatchResponse]: ResponseBatchMessage;
 }
 
 export interface OutgoingMessageTypes {
@@ -197,6 +201,10 @@ export interface OutgoingMessageTypes {
  * Client is making a request to obs-websocket. Eg get current scene, create source.
  */
 [WebSocketOpCode.Request]: RequestMessage;
+/**
+ * Client is making a batch request to obs-websocket.
+ */
+[WebSocketOpCode.RequestBatch]: RequestBatchMessage;
 }
 
 type EventMessage<T = keyof OBSEventTypes> = T extends keyof OBSEventTypes ? {
@@ -214,13 +222,34 @@ export type RequestMessage<T = keyof OBSRequestTypes> = T extends keyof OBSReque
 requestData: OBSRequestTypes[T];
 } : never;
 
+export type RequestBatchRequest<T = keyof OBSRequestTypes> = T extends keyof OBSRequestTypes ? OBSRequestTypes[T] extends never ? {
+requestType: T;
+requestId?: string;
+} : {
+requestType: T;
+requestId?: string;
+requestData: OBSRequestTypes[T];
+} : never;
+
+export type RequestBatchMessage = {
+requestId: string;
+haltOnFailure?: boolean;
+executionType?: RequestBatchExecutionType
+requests: RequestBatchRequest[];
+};
+
 export type ResponseMessage<T = keyof OBSResponseTypes> = T extends keyof OBSResponseTypes ? {
 requestType: T;
 requestId: string;
 requestStatus: {result: true; code: number} | {result: false; code: number; comment: string};
 responseData: OBSResponseTypes[T];
 } : never;
 
+export type ResponseBatchMessage = {
+requestId: string;
+results: ResponseMessage[];
+}
+
 // Events
 export interface OBSEventTypes {
 ${generateObsEventTypes(protocol.events)}

src/base.ts

@@ -4,7 +4,7 @@ import EventEmitter from 'eventemitter3';
 import WebSocketIpml from 'isomorphic-ws';
 import {Except, Merge, SetOptional} from 'type-fest';
 
-import {OutgoingMessageTypes, WebSocketOpCode, OutgoingMessage, OBSEventTypes, IncomingMessage, IncomingMessageTypes, OBSRequestTypes, OBSResponseTypes, RequestMessage, ResponseMessage} from './types.js';
+import {OutgoingMessageTypes, WebSocketOpCode, OutgoingMessage, OBSEventTypes, IncomingMessage, IncomingMessageTypes, OBSRequestTypes, OBSResponseTypes, RequestMessage, RequestBatchExecutionType, RequestBatchRequest, RequestBatchMessage, ResponseMessage, ResponseBatchMessage} from './types.js';
 import authenticationHashing from './utils/authenticationHashing.js';
 
 export const debug = createDebug('obs-websocket-js');
@@ -147,6 +147,30 @@ export abstract class BaseOBSWebSocket extends EventEmitter<MapValueToArgsArray<
 return responseData as OBSResponseTypes[Type];
 }
 
+/**
+ * Send a batch request to obs-websocket
+ *
+ * @param requests Array of Request objects (type and data)
+ * @param options A set of options for how the batch will be executed
+ * @param options.executionType The mode of execution obs-websocket will run the batch in
+ * @param options.haltOnFailure Whether obs-websocket should stop executing the batch if one request fails
+ * @returns RequestBatch response
+ */
+async callBatch(requests: RequestBatchRequest[], options: {haltOnFailure?: boolean; executionType?: RequestBatchExecutionType} = {}): Promise<ResponseMessage[]> {
+const requestId = BaseOBSWebSocket.generateMessageId();
+const responsePromise = this.internalEventPromise<ResponseBatchMessage>(`res:${requestId}`);
+
+await this.message(WebSocketOpCode.RequestBatch, {
+requestId,
+requests,
+haltOnFailure: options.haltOnFailure,
+executionType: options.executionType,
+});
+
+const {results} = await responsePromise;
+return results;
+}
+
 /**
  * Cleanup from socket disconnection
  */
@@ -310,7 +334,8 @@ export abstract class BaseOBSWebSocket extends EventEmitter<MapValueToArgsArray<
 return;
 }
 
-case WebSocketOpCode.RequestResponse: {
+case WebSocketOpCode.RequestResponse:
+case WebSocketOpCode.RequestBatchResponse: {
 const {requestId} = d;
 this.internalListeners.emit(`res:${requestId}`, d);
 return;

src/types.ts

@@ -252,6 +252,10 @@ export interface IncomingMessageTypes {
  * obs-websocket is responding to a request coming from a client
  */
 [WebSocketOpCode.RequestResponse]: ResponseMessage;
+/**
+ * obs-websocket is responding to a batch request coming from a client
+ */
+[WebSocketOpCode.RequestBatchResponse]: ResponseBatchMessage;
 }
 
 export interface OutgoingMessageTypes {
@@ -285,6 +289,10 @@ export interface OutgoingMessageTypes {
  * Client is making a request to obs-websocket. Eg get current scene, create source.
  */
 [WebSocketOpCode.Request]: RequestMessage;
+/**
+ * Client is making a batch request to obs-websocket.
+ */
+[WebSocketOpCode.RequestBatch]: RequestBatchMessage;
 }
 
 type EventMessage<T = keyof OBSEventTypes> = T extends keyof OBSEventTypes ? {
@@ -302,13 +310,34 @@ export type RequestMessage<T = keyof OBSRequestTypes> = T extends keyof OBSReque
 requestData: OBSRequestTypes[T];
 } : never;
 
+export type RequestBatchRequest<T = keyof OBSRequestTypes> = T extends keyof OBSRequestTypes ? OBSRequestTypes[T] extends never ? {
+requestType: T;
+requestId?: string;
+} : {
+requestType: T;
+requestId?: string;
+requestData: OBSRequestTypes[T];
+} : never;
+
+export type RequestBatchMessage = {
+requestId: string;
+haltOnFailure?: boolean;
+executionType?: RequestBatchExecutionType;
+requests: RequestBatchRequest[];
+};
+
 export type ResponseMessage<T = keyof OBSResponseTypes> = T extends keyof OBSResponseTypes ? {
 requestType: T;
 requestId: string;
 requestStatus: {result: true; code: number} | {result: false; code: number; comment: string};
 responseData: OBSResponseTypes[T];
 } : never;
 
+export type ResponseBatchMessage = {
+requestId: string;
+results: ResponseMessage[];
+};
+
 // Events
 export interface OBSEventTypes {
 CurrentSceneCollectionChanging: {

tests/helpers/dev-server.ts

@@ -3,7 +3,7 @@ import sha256 from 'crypto-js/sha256.js';
 import Base64 from 'crypto-js/enc-base64.js';
 import {JsonObject} from 'type-fest';
 import {AddressInfo, WebSocketServer} from 'ws';
-import {IncomingMessage, WebSocketOpCode, OutgoingMessage} from '../../src/types.js';
+import {IncomingMessage, WebSocketOpCode, OutgoingMessage, ResponseBatchMessage, OBSRequestTypes, ResponseMessage} from '../../src/types.js';
 
 export interface MockServer {
 server: WebSocketServer;
@@ -54,6 +54,44 @@ const REQUEST_HANDLERS: Record<string, (req?: JsonObject | void) => FailureRespo
 /* eslint-enable @typescript-eslint/naming-convention */
 };
 
+function handleRequestData<T extends keyof OBSRequestTypes>(requestId: string | undefined, requestType: T, requestData: OBSRequestTypes[T]) {
+if (!(requestType in REQUEST_HANDLERS)) {
+return {
+requestType,
+requestId,
+requestStatus: {
+result: false,
+code: 204,
+comment: 'unknown type',
+},
+};
+}
+
+const responseData = REQUEST_HANDLERS[requestType](requestData);
+
+if (responseData instanceof FailureResponse) {
+return {
+requestType,
+requestId,
+requestStatus: {
+result: false,
+code: responseData.code,
+comment: responseData.message,
+},
+};
+}
+
+return {
+requestType,
+requestId,
+requestStatus: {
+result: true,
+code: 100,
+},
+responseData,
+};
+}
+
 export async function makeServer(
 authenticate?: boolean,
 ): Promise<MockServer> {
@@ -134,55 +172,33 @@ export async function makeServer(
 break;
 case WebSocketOpCode.Request: {
 const {requestData, requestId, requestType} = message.d;
-if (!(requestType in REQUEST_HANDLERS)) {
-send({
-op: WebSocketOpCode.RequestResponse,
-d: {
-// @ts-expect-error don't care
-requestType,
-requestId,
-requestStatus: {
-result: false,
-code: 204,
-comment: 'unknown type',
-},
-},
-});
-break;
-}
+const responseData = handleRequestData(requestId, requestType, requestData);
+send({
+op: WebSocketOpCode.RequestResponse,
+// @ts-expect-error RequestTypes and ResponseTypes are non-overlapping according to ts
+d: responseData,
+});
+break;
+}
+
+case WebSocketOpCode.RequestBatch: {
+const {requests, requestId, haltOnFailure: shouldHalt} = message.d;
+
+const response: ResponseBatchMessage = {requestId, results: []};
 
-const responseData = REQUEST_HANDLERS[requestType](requestData);
-
-if (responseData instanceof FailureResponse) {
-send({
-op: WebSocketOpCode.RequestResponse,
-d: {
-// @ts-expect-error don't care
-requestType,
-requestId,
-requestStatus: {
-result: false,
-code: responseData.code,
-comment: responseData.message,
-},
-},
-});
-break;
+for (const request of requests) {
+// @ts-expect-error requestData only exists on _some_ request types, not all
+const result = handleRequestData(request.requestId, request.requestType, request.requestData);
+response.results.push(result as ResponseMessage);
+
+if (!result.requestStatus.result && shouldHalt) {
+break;
+}
 }
 
 send({
-op: WebSocketOpCode.RequestResponse,
-d: {
-// @ts-expect-error don't care
-requestType,
-requestId,
-requestStatus: {
-result: true,
-code: 100,
-},
-// @ts-expect-error don't care
-responseData,
-},
+op: WebSocketOpCode.RequestBatchResponse,
+d: response,
 });
 
 break;

tests/request-batch.test.ts

@@ -0,0 +1,54 @@
+import anyTest, {TestFn} from 'ava';
+
+import {makeServer, MockServer} from './helpers/dev-server.js';
+import OBSWebSocket, {OBSRequestTypes, OBSResponseTypes, OBSWebSocketError} from '../src/json.js';
+
+const test = anyTest as TestFn<{
+server: MockServer;
+client: OBSWebSocket;
+}>;
+
+test.beforeEach(async t => {
+const server = await makeServer();
+const client = new OBSWebSocket();
+await client.connect(server.url);
+
+t.context = {
+server,
+client,
+};
+});
+
+test.afterEach(async t => {
+await t.context.client.disconnect();
+await t.context.server.teardown();
+});
+
+test('disconencted throws', async t => {
+const {client} = t.context;
+await client.disconnect();
+await t.throwsAsync(client.callBatch([{requestType: 'GetVersion'}]), {
+instanceOf: Error,
+message: 'Not connected',
+});
+});
+
+test('single request without parameters', async t => {
+const {client} = t.context;
+const [res] = await client.callBatch([{requestType: 'GetVersion'}]);
+
+t.is((res.responseData as OBSResponseTypes['GetVersion']).obsVersion, '5.0.0-mock.0');
+});
+
+test('multiple requests with mixed parameters', async t => {
+const {client} = t.context;
+const [res1, res2, res3] = await client.callBatch([
+{requestType: 'GetVersion'},
+{requestType: 'BroadcastCustomEvent', requestData: {eventData: {}}},
+{requestType: 'GetVersion'},
+]);
+
+t.is((res1.responseData as OBSResponseTypes['GetVersion']).obsVersion, '5.0.0-mock.0');
+t.is((res2.responseData as OBSResponseTypes['BroadcastCustomEvent']), undefined);
+t.is((res3.responseData as OBSResponseTypes['GetVersion']).obsVersion, '5.0.0-mock.0');
+});