@cratis/arc 19.12.0 → 20.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/arc",
-    "version": "19.12.0",
+    "version": "20.1.0",
     "description": "",
     "author": "Cratis",
     "license": "MIT",

package/queries/HubConnectionKeepAlive.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Manages keep-alive behavior for hub connections (both WebSocket and Server-Sent Events).
+ *
+ * Records connection activity (any message received or sent). An interval fires every
+ * {@link intervalMs} milliseconds; if no activity has been recorded since the last tick the
+ * provided {@link onIdle} callback is invoked — the caller decides whether to send a ping,
+ * trigger a reconnect, or take some other action.
+ *
+ * Both {@link WebSocketHubConnection} and {@link ServerSentEventHubConnection} own one instance
+ * of this class so the keep-alive logic is written once and behaves identically for both
+ * transports.
+ */
+export class HubConnectionKeepAlive {
+    private _lastActivityTime = Date.now();
+    private _timer?: ReturnType<typeof setInterval>;
+
+    /**
+     * Initializes a new instance of {@link HubConnectionKeepAlive}.
+     * @param {number} intervalMs How often (in milliseconds) to check for idle connections.
+     * @param {() => void} onIdle Callback invoked when the interval fires and no activity has
+     *   been recorded in the last {@link intervalMs} milliseconds.
+     */
+    constructor(
+        private readonly _intervalMs: number,
+        private readonly _onIdle: () => void,
+    ) {}
+
+    /**
+     * Start the keep-alive timer. Safe to call multiple times — a running timer is stopped first.
+     */
+    start(): void {
+        this.stop();
+        this._lastActivityTime = Date.now();
+        this._timer = setInterval(() => {
+            if (Date.now() - this._lastActivityTime >= this._intervalMs) {
+                this._onIdle();
+            }
+        }, this._intervalMs);
+    }
+
+    /**
+     * Stop the keep-alive timer.
+     */
+    stop(): void {
+        if (this._timer !== undefined) {
+            clearInterval(this._timer);
+            this._timer = undefined;
+        }
+    }
+
+    /**
+     * Record that the connection has been active (message sent or received).
+     * Resets the idle timer so that a keep-alive is not sent while data is already flowing.
+     */
+    recordActivity(): void {
+        this._lastActivityTime = Date.now();
+    }
+}

package/queries/IObservableQueryHubConnection.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DataReceived } from './ObservableQueryConnection';
+import { SubscriptionRequest } from './WebSocketHubConnection';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Defines a multiplexed hub connection that carries multiple observable query subscriptions
+ * over a single transport (WebSocket or SSE + POST).
+ *
+ * Both {@link WebSocketHubConnection} and {@link ServerSentEventHubConnection} implement this
+ * interface, allowing the pool to work with either transport interchangeably.
+ */
+export interface IObservableQueryHubConnection {
+    /**
+     * Gets the number of active query subscriptions on this connection.
+     */
+    readonly queryCount: number;
+
+    /**
+     * Gets the latency of the last ping/pong sequence in milliseconds.
+     */
+    readonly lastPingLatency: number;
+
+    /**
+     * Gets the rolling average latency in milliseconds.
+     */
+    readonly averageLatency: number;
+
+    /**
+     * Subscribe to a query on this hub connection.
+     * @param {string} queryId Client-generated unique identifier for this subscription.
+     * @param {SubscriptionRequest} request The subscription request payload.
+     * @param {DataReceived<any>} callback Callback invoked whenever the server pushes a result for this query.
+     */
+    subscribe(queryId: string, request: SubscriptionRequest, callback: DataReceived<any>): void;
+
+    /**
+     * Unsubscribe from a query on this hub connection.
+     * @param {string} queryId The identifier of the subscription to cancel.
+     */
+    unsubscribe(queryId: string): void;
+
+    /**
+     * Permanently close this hub connection and clean up all subscriptions.
+     */
+    dispose(): void;
+}

package/queries/IReconnectPolicy.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Callback invoked by {@link IReconnectPolicy} when it is time to attempt a reconnect.
+ */
+export type ReconnectCallback = () => void;
+
+/**
+ * Defines the contract for a reconnect policy that controls back-off and retry behavior
+ * for observable query connections.
+ */
+export interface IReconnectPolicy {
+    /**
+     * The current number of reconnect attempts made since the last {@link reset}.
+     */
+    readonly attempt: number;
+
+    /**
+     * Schedule the next reconnect attempt.
+     * @param {ReconnectCallback} onReconnect Callback to invoke when the delay elapses.
+     * @param {string} label Human-readable label used in log output (e.g. the connection URL).
+     * @returns {boolean} {@code true} if the attempt was scheduled; {@code false} if the maximum
+     *                    number of attempts has been reached and the policy has given up.
+     */
+    schedule(onReconnect: ReconnectCallback, label: string): boolean;
+
+    /**
+     * Reset the attempt counter and cancel any pending timer.
+     * Call this when a connection is successfully established.
+     */
+    reset(): void;
+
+    /**
+     * Cancel any pending reconnect timer without resetting the attempt counter.
+     * Call this when the connection is permanently disposed.
+     */
+    cancel(): void;
+}

package/queries/ObservableQueryConnection.ts

@@ -3,6 +3,8 @@
 
 import { Globals } from '../Globals';
 import { IObservableQueryConnection } from './IObservableQueryConnection';
+import { IReconnectPolicy } from './IReconnectPolicy';
+import { ReconnectPolicy } from './ReconnectPolicy';
 import { QueryResult } from './QueryResult';
 import { WebSocketMessage, WebSocketMessageType } from './WebSocketMessage';
 
@@ -28,8 +30,9 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
      * @param {Url} url The fully qualified Url.
      * @param {string} _microservice The microservice name.
      * @param {number} pingIntervalMs The ping interval in milliseconds (default: 10000).
+     * @param {IReconnectPolicy} reconnectPolicy The reconnect policy to use (default: {@link ReconnectPolicy}).
      */
-    constructor(url: URL, private readonly _microservice: string, pingIntervalMs: number = 10000) {
+    constructor(url: URL, private readonly _microservice: string, pingIntervalMs: number = 10000, private readonly _reconnectPolicy: IReconnectPolicy = new ReconnectPolicy()) {
         this._pingIntervalMs = pingIntervalMs;
         const secure = url.protocol?.indexOf('https') === 0 || false;
 
@@ -82,32 +85,12 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
             url = `${url}${query}`;
         }
 
-        let timeToWait = 500;
-        const timeExponent = 500;
-        const retries = 100;
-        let currentAttempt = 0;
-        const maxTime = 10_000;
-
         const connectSocket = () => {
-            const retry = () => {
-                currentAttempt++;
-                if (currentAttempt > retries) {
-                    console.log(`Attempted ${retries} retries for route '${url}'. Abandoning.`);
-                    return;
-                }
-                console.log(`Attempting to reconnect for '${url}' (#${currentAttempt})`);
-
-                setTimeout(connectSocket, timeToWait);
-                timeToWait += (timeExponent * currentAttempt);
-                timeToWait = timeToWait > maxTime ? maxTime : timeToWait; 
-            };
-
             this._socket = new WebSocket(url);
             this._socket.onopen = () => {
                 if (this._disconnected) return;
                 console.log(`Connection for '${url}' established`);
-                timeToWait = 500;
-                currentAttempt = 0;
+                this._reconnectPolicy.reset();
                 this._connectionStartTime = Date.now();
                 this.startPinging();
             };
@@ -115,13 +98,13 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
                 if (this._disconnected) return;
                 console.log(`Unexpected connection closed for route '${url}'`);
                 this.stopPinging();
-                retry();
+                this._reconnectPolicy.schedule(connectSocket, url);
             };
             this._socket.onerror = (error) => {
                 if (this._disconnected) return;
                 console.log(`Error with connection for '${url}' - ${error}`);
                 this.stopPinging();
-                retry();
+                this._reconnectPolicy.schedule(connectSocket, url);
             };
             this._socket.onmessage = (ev) => {
                 if (this._disconnected) {
@@ -143,6 +126,7 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
         }
         console.log(`Disconnecting '${this._url}'`);
         this._disconnected = true;
+        this._reconnectPolicy.cancel();
         this.stopPinging();
         this._socket?.close();
         console.log(`Connection for '${this._url}' closed`);

package/queries/ObservableQueryConnectionFactory.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Globals } from '../Globals';
+import { joinPaths } from '../joinPaths';
+import { UrlHelpers } from '../UrlHelpers';
+import { IObservableQueryConnection } from './IObservableQueryConnection';
+import { ObservableQueryConnection } from './ObservableQueryConnection';
+import { QueryTransportMethod } from './QueryTransportMethod';
+import { ServerSentEventQueryConnection, SSE_HUB_ROUTE } from './ServerSentEventQueryConnection';
+import { ServerSentEventHubConnection } from './ServerSentEventHubConnection';
+import { WebSocketHubConnection } from './WebSocketHubConnection';
+import { MultiplexedObservableQueryConnection, WS_HUB_ROUTE, getOrCreateMultiplexer } from './ObservableQueryMultiplexer';
+
+/**
+ * The SSE subscribe POST endpoint route.
+ */
+export const SSE_SUBSCRIBE_ROUTE = '/.cratis/queries/sse/subscribe';
+
+/**
+ * The SSE unsubscribe POST endpoint route.
+ */
+export const SSE_UNSUBSCRIBE_ROUTE = '/.cratis/queries/sse/unsubscribe';
+
+/**
+ * Describes what the factory needs to know about a query in order to create
+ * the right connection. Transport details are intentionally absent — the
+ * factory reads those from {@link Globals}.
+ */
+export interface QueryConnectionDescriptor {
+    /** The route template (e.g. `/api/accounts/debit/all-accounts`). */
+    route: string;
+    /** Fully-qualified backend query name used by hub transports. */
+    queryName: string;
+    /** Origin base URL (e.g. `http://localhost:5000`). */
+    origin: string;
+    /** API base path prefix. */
+    apiBasePath: string;
+    /** Microservice identifier. */
+    microservice: string;
+    /** Route/query arguments for the current subscription. */
+    args?: object;
+}
+
+/**
+ * Single entry-point for creating observable query connections.
+ *
+ * The transport is chosen as a 2x2 matrix of (direct | hub) x (WebSocket | SSE):
+ *
+ * |                | Direct (per-query URL)         | Hub (centralized endpoint)    |
+ * |----------------|-------------------------------|-------------------------------|
+ * | **WebSocket**  | ObservableQueryConnection                | MultiplexedObservableQueryConnection |
+ * | **SSE**        | ServerSentEventQueryConnection           | MultiplexedObservableQueryConnection |
+ *
+ * In multiplexed mode, both transports share the same multiplexer — it creates either
+ * WebSocket or SSE connections depending on the transport setting.
+ *
+ * {@link ObservableQueryFor} never needs to know which transport is in use.
+ */
+export function createObservableQueryConnection<TDataType>(descriptor: QueryConnectionDescriptor): IObservableQueryConnection<TDataType> {
+    const isSSE = Globals.queryTransportMethod === QueryTransportMethod.ServerSentEvents;
+
+    if (Globals.queryDirectMode) {
+        return isSSE
+            ? createDirectSSEConnection<TDataType>(descriptor)
+            : createDirectWebSocketConnection<TDataType>(descriptor);
+    }
+
+    return createMultiplexedConnection<TDataType>(descriptor, isSSE);
+}
+
+// ---- Direct mode: one connection per query, hitting the query's own URL ----
+
+function buildDirectUrl(descriptor: QueryConnectionDescriptor): URL {
+    const { route } = UrlHelpers.replaceRouteParameters(descriptor.route, descriptor.args as object);
+    const actualRoute = joinPaths(descriptor.apiBasePath, route);
+    return UrlHelpers.createUrlFrom(descriptor.origin, descriptor.apiBasePath, actualRoute);
+}
+
+function createDirectWebSocketConnection<TDataType>(descriptor: QueryConnectionDescriptor): IObservableQueryConnection<TDataType> {
+    return new ObservableQueryConnection<TDataType>(buildDirectUrl(descriptor), descriptor.microservice);
+}
+
+function createDirectSSEConnection<TDataType>(descriptor: QueryConnectionDescriptor): IObservableQueryConnection<TDataType> {
+    return new ServerSentEventQueryConnection<TDataType>(buildDirectUrl(descriptor));
+}
+
+// ---- Multiplexed mode: centralized endpoint, multiple queries share connections ----
+
+function createMultiplexedConnection<TDataType>(descriptor: QueryConnectionDescriptor, isSSE: boolean): IObservableQueryConnection<TDataType> {
+    const transport = isSSE ? 'sse' : 'ws';
+    const cacheKey = `${Globals.queryConnectionCount}|${transport}|${descriptor.origin}|${descriptor.apiBasePath}|${descriptor.microservice}`;
+
+    const multiplexer = getOrCreateMultiplexer(() => {
+        if (isSSE) {
+            const sseRoute = joinPaths(descriptor.apiBasePath, SSE_HUB_ROUTE);
+            const sseUrl = UrlHelpers.createUrlFrom(descriptor.origin, descriptor.apiBasePath, sseRoute);
+            const subscribeRoute = joinPaths(descriptor.apiBasePath, SSE_SUBSCRIBE_ROUTE);
+            const subscribeUrl = UrlHelpers.createUrlFrom(descriptor.origin, descriptor.apiBasePath, subscribeRoute);
+            const unsubscribeRoute = joinPaths(descriptor.apiBasePath, SSE_UNSUBSCRIBE_ROUTE);
+            const unsubscribeUrl = UrlHelpers.createUrlFrom(descriptor.origin, descriptor.apiBasePath, unsubscribeRoute);
+            return new ServerSentEventHubConnection(
+                sseUrl.toString(),
+                subscribeUrl.toString(),
+                unsubscribeUrl.toString(),
+                descriptor.microservice,
+            );
+        } else {
+            const hubRoute = joinPaths(descriptor.apiBasePath, WS_HUB_ROUTE);
+            const hubUrl = UrlHelpers.createUrlFrom(descriptor.origin, descriptor.apiBasePath, hubRoute);
+            const secure = hubUrl.protocol?.indexOf('https') === 0;
+            const wsUrl = `${secure ? 'wss' : 'ws'}://${hubUrl.host}${hubUrl.pathname}${hubUrl.search}`;
+            return new WebSocketHubConnection(wsUrl, descriptor.microservice);
+        }
+    }, cacheKey);
+
+    return new MultiplexedObservableQueryConnection<TDataType>(multiplexer, descriptor.queryName);
+}

package/queries/ObservableQueryConnectionPool.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IObservableQueryConnection } from './IObservableQueryConnection';
+import { DataReceived } from './ObservableQueryConnection';
+
+/**
+ * Tracks the number of active subscribers assigned to each pool slot.
+ */
+interface PoolSlot {
+    queryCount: number;
+}
+
+/**
+ * Represents a pool of observable query connection factories distributed round-robin across N slots.
+ *
+ * Each call to {@link acquire} picks the slot with the fewest active queries (falling back to
+ * round-robin when counts are equal) and creates a fresh connection for that subscriber via the
+ * provided factory. The connection is a dedicated instance per subscriber; the pool only tracks
+ * slot utilization so future multiplexed transports (e.g. WebSocket) can share connections
+ * across a fixed number of physical hub connections.
+ *
+ * When {@link size} is 1 (the default), all queries are counted against a single slot — the
+ * natural behavior for a single multiplexed connection.
+ *
+ * @template TDataType The type of data received from the connections.
+ */
+export class ObservableQueryConnectionPool<TDataType> {
+    private readonly _slots: PoolSlot[];
+
+    /**
+     * Initializes a new {@link ObservableQueryConnectionPool}.
+     * @param {number} size Number of logical slots (hub connections) in the pool.
+     * @param {() => IObservableQueryConnection<TDataType>} factory Factory that produces a new connection instance per subscriber.
+     */
+    constructor(
+        size: number,
+        private readonly _factory: () => IObservableQueryConnection<TDataType>
+    ) {
+        this._slots = Array.from({ length: Math.max(1, size) }, () => ({ queryCount: 0 }));
+    }
+
+    /**
+     * Picks the least-loaded pool slot, creates a fresh connection via the factory, and starts
+     * delivering data to the provided callback.
+     * @param {DataReceived<TDataType>} dataReceived Callback invoked for each message.
+     * @param {object} queryArguments Arguments forwarded to the connection.
+     * @returns A cleanup function that decrements the slot counter and disconnects the connection.
+     */
+    acquire(dataReceived: DataReceived<TDataType>, queryArguments?: object): () => void {
+        // Pick the slot with the fewest active queries.
+        const slot = this._slots.reduce((min, current) => current.queryCount < min.queryCount ? current : min, this._slots[0]);
+        slot.queryCount++;
+
+        // Each subscriber gets its own dedicated connection instance.
+        const connection = this._factory();
+        connection.connect(dataReceived, queryArguments);
+
+        return () => {
+            connection.disconnect();
+            slot.queryCount = Math.max(0, slot.queryCount - 1);
+        };
+    }
+}

package/queries/ObservableQueryFor.ts

@@ -2,11 +2,11 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { IObservableQueryFor, OnNextResult } from './IObservableQueryFor';
-import { ObservableQueryConnection } from './ObservableQueryConnection';
 import { ObservableQuerySubscription } from './ObservableQuerySubscription';
 import { ValidateRequestArguments } from './ValidateRequestArguments';
 import { IObservableQueryConnection } from './IObservableQueryConnection';
 import { NullObservableQueryConnection } from './NullObservableQueryConnection';
+import { createObservableQueryConnection } from './ObservableQueryConnectionFactory';
 import { Constructor } from '@cratis/fundamentals';
 import { JsonSerializer } from '@cratis/fundamentals';
 import { QueryResult } from './QueryResult';
@@ -36,6 +36,8 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
     abstract readonly route: string;
     abstract readonly defaultValue: TDataType;
     readonly roles: string[] = [];
+    /** Backend fully-qualified query name used when subscribing via the SSE hub. Overridden in generated proxies. */
+    readonly queryName?: string;
     abstract readonly parameterDescriptors: ParameterDescriptor[];
     abstract get requiredRequestParameters(): string[];
     sorting: Sorting;
@@ -91,10 +93,14 @@ export abstract class ObservableQueryFor<TDataType, TParameters = object> implem
         if (!this.validateArguments(args)) {
             this._connection = new NullObservableQueryConnection(this.defaultValue);
         } else {
-            const { route } = UrlHelpers.replaceRouteParameters(this.route, args as object);
-            const actualRoute = joinPaths(this._apiBasePath, route);
-            const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);
-            this._connection = new ObservableQueryConnection<TDataType>(url, this._microservice);
+            this._connection = createObservableQueryConnection({
+                route: this.route,
+                queryName: this.queryName ?? this.constructor.name,
+                origin: this._origin,
+                apiBasePath: this._apiBasePath,
+                microservice: this._microservice,
+                args: args as object,
+            });
         }
 
         // Build query arguments including unused args parameters, parameter descriptor values, and paging/sorting

package/queries/ObservableQueryMultiplexer.ts

@@ -0,0 +1,214 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IObservableQueryConnection } from './IObservableQueryConnection';
+import { IObservableQueryHubConnection } from './IObservableQueryHubConnection';
+import { DataReceived } from './ObservableQueryConnection';
+import { SubscriptionRequest } from './WebSocketHubConnection';
+import { Globals } from '../Globals';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * The WebSocket demultiplexer route used when connecting through the multiplexed observable query endpoint.
+ */
+export const WS_HUB_ROUTE = '/.cratis/queries/ws';
+
+/**
+ * Multiplexes multiple observable query subscriptions across a bounded pool of physical
+ * connections (WebSocket or SSE) to the backend demultiplexer.
+ *
+ * Each pool slot is a single multiplexed connection. When a new subscription is requested,
+ * the slot with the fewest active queries is chosen. This balances load across N physical
+ * connections while keeping the total connection count bounded.
+ */
+export class ObservableQueryMultiplexer {
+    private readonly _connections: IObservableQueryHubConnection[];
+    private readonly _size: number;
+
+    /**
+     * Initializes a new {@link ObservableQueryMultiplexer}.
+     * @param {number} size Number of physical connections (pool slots).
+     * @param {() => IObservableQueryHubConnection} connectionFactory Factory function to create each connection.
+     */
+    constructor(size: number, connectionFactory: () => IObservableQueryHubConnection) {
+        this._size = Math.max(1, size);
+        this._connections = Array.from({ length: this._size }, () => connectionFactory());
+    }
+
+    /**
+     * Gets the pool size.
+     */
+    get size(): number {
+        return this._size;
+    }
+
+    /**
+     * Gets the best available ping latency across all connections.
+     */
+    get lastPingLatency(): number {
+        return this._connections.reduce((min, c) =>
+            c.lastPingLatency > 0 && c.lastPingLatency < min ? c.lastPingLatency : min,
+            Number.MAX_SAFE_INTEGER
+        );
+    }
+
+    /**
+     * Gets the average latency across all connections.
+     */
+    get averageLatency(): number {
+        const active = this._connections.filter(c => c.averageLatency > 0);
+        if (active.length === 0) return 0;
+        return active.reduce((sum, c) => sum + c.averageLatency, 0) / active.length;
+    }
+
+    /**
+     * Subscribe to a query through the multiplexer. Picks the least-loaded connection
+     * and sends a Subscribe message on it.
+     * @param {string} queryName Fully qualified backend query name.
+     * @param {object} queryArguments Flat query arguments (incl. page, pageSize, sortBy, sortDirection).
+     * @param {DataReceived<any>} callback Callback invoked for each result.
+     * @returns A cleanup function that unsubscribes from the query.
+     */
+    subscribe(queryName: string, queryArguments: object | undefined, callback: DataReceived<any>): () => void {
+        const request = this.buildSubscriptionRequest(queryName, queryArguments);
+        const conn = this.leastLoaded();
+        const queryId = this.generateQueryId();
+
+        conn.subscribe(queryId, request, callback);
+
+        return () => {
+            conn.unsubscribe(queryId);
+        };
+    }
+
+    /**
+     * Dispose all connections in the multiplexer.
+     */
+    dispose(): void {
+        for (const conn of this._connections) {
+            conn.dispose();
+        }
+    }
+
+    private leastLoaded(): IObservableQueryHubConnection {
+        return this._connections.reduce((min, c) =>
+            c.queryCount < min.queryCount ? c : min, this._connections[0]);
+    }
+
+    private generateQueryId(): string {
+        // Use crypto.randomUUID when available, fall back to timestamp + random
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+
+    private buildSubscriptionRequest(queryName: string, args?: object): SubscriptionRequest {
+        const request: SubscriptionRequest = { queryName };
+
+        if (!args) return request;
+
+        const a = args as Record<string, any>;
+        const pagingAndSortingKeys = new Set(['page', 'pageSize', 'sortBy', 'sortDirection']);
+
+        if (a.page !== undefined && a.page !== null) request.page = Number(a.page);
+        if (a.pageSize !== undefined && a.pageSize !== null) request.pageSize = Number(a.pageSize);
+        if (a.sortBy !== undefined && a.sortBy !== null) request.sortBy = String(a.sortBy);
+        if (a.sortDirection !== undefined && a.sortDirection !== null) request.sortDirection = String(a.sortDirection);
+
+        // Everything else goes into arguments as string key-value pairs
+        const remaining: Record<string, string | null> = {};
+        let hasRemaining = false;
+
+        for (const [key, value] of Object.entries(a)) {
+            if (pagingAndSortingKeys.has(key)) continue;
+            remaining[key] = value !== undefined && value !== null ? String(value) : null;
+            hasRemaining = true;
+        }
+
+        if (hasRemaining) {
+            request.arguments = remaining;
+        }
+
+        return request;
+    }
+}
+
+/**
+ * Wraps an {@link ObservableQueryMultiplexer} subscription as an {@link IObservableQueryConnection},
+ * allowing the multiplexed transport to plug into the existing query subscription pipeline
+ * without changes to callers.
+ */
+export class MultiplexedObservableQueryConnection<TDataType> implements IObservableQueryConnection<TDataType> {
+    private _cleanup?: () => void;
+
+    /**
+     * Initializes a new {@link MultiplexedObservableQueryConnection}.
+     * @param {ObservableQueryMultiplexer} multiplexer The shared multiplexer.
+     * @param {string} queryName The fully qualified backend query name.
+     */
+    constructor(
+        private readonly _pool: ObservableQueryMultiplexer,
+        private readonly _queryName: string,
+    ) {
+    }
+
+    /** @inheritdoc */
+    get lastPingLatency(): number {
+        return this._pool.lastPingLatency;
+    }
+
+    /** @inheritdoc */
+    get averageLatency(): number {
+        return this._pool.averageLatency;
+    }
+
+    /** @inheritdoc */
+    connect(dataReceived: DataReceived<TDataType>, queryArguments?: object): void {
+        this._cleanup = this._pool.subscribe(
+            this._queryName,
+            queryArguments,
+            dataReceived as DataReceived<any>,
+        );
+    }
+
+    /** @inheritdoc */
+    disconnect(): void {
+        this._cleanup?.();
+        this._cleanup = undefined;
+    }
+}
+
+// ----- Shared pool singleton management -----
+
+let _sharedMultiplexer: ObservableQueryMultiplexer | undefined;
+let _sharedMultiplexerKey = '';
+
+/**
+ * Returns the shared {@link ObservableQueryMultiplexer}, creating or re-creating it when the
+ * configuration (connection count, origin, base path, microservice, transport) changes.
+ * @param {() => IObservableQueryHubConnection} connectionFactory Factory to create individual connections.
+ * @param {string} cacheKey A string that identifies the current configuration for invalidation.
+ * @returns The shared multiplexer instance.
+ */
+export function getOrCreateMultiplexer(connectionFactory: () => IObservableQueryHubConnection, cacheKey: string): ObservableQueryMultiplexer {
+    if (_sharedMultiplexer && _sharedMultiplexerKey === cacheKey) {
+        return _sharedMultiplexer;
+    }
+
+    _sharedMultiplexer?.dispose();
+    _sharedMultiplexer = new ObservableQueryMultiplexer(Globals.queryConnectionCount, connectionFactory);
+    _sharedMultiplexerKey = cacheKey;
+    return _sharedMultiplexer;
+}
+
+/**
+ * Disposes and clears the shared multiplexer singleton.
+ * Intended for use in test teardown to prevent state leakage across tests.
+ */
+export function resetSharedMultiplexer(): void {
+    _sharedMultiplexer?.dispose();
+    _sharedMultiplexer = undefined;
+    _sharedMultiplexerKey = '';
+}