@cratis/arc 18.4.2 → 18.5.0

package/identity/for_IdentityProvider/when_refreshing/with_type_safe_details.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+import { IdentityProvider } from '../../IdentityProvider';
+import { an_identity_provider } from '../given/an_identity_provider';
+import { given } from '../../../given';
+
+class TestDetails {
+    userId: Guid = Guid.empty;
+    role: string = '';
+}
+
+describe('when refreshing with type safe details', given(an_identity_provider, context => {
+    let result: { id: string; name: string; details: TestDetails };
+
+    beforeEach(async () => {
+        const testGuid = Guid.create();
+        context.fetchStub.resolves({
+            ok: true,
+            json: async () => ({
+                id: 'test-user-id',
+                name: 'Test User',
+                details: { 
+                    userId: testGuid.toString(), 
+                    role: 'admin' 
+                }
+            })
+        } as Response);
+
+        const identity = await IdentityProvider.refresh(TestDetails);
+        result = {
+            id: identity.id,
+            name: identity.name,
+            details: identity.details
+        };
+    });
+
+    it('should deserialize details with proper types', () => {
+        result.details.userId.should.be.instanceOf(Guid);
+    });
+}));

package/package.json

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

package/queries/IObservableQueryConnection.ts

@@ -7,6 +7,16 @@ import { DataReceived } from './ObservableQueryConnection';
  * Defines a connection for observable queries.
  */
 export interface IObservableQueryConnection<TDataType> {
+    /**
+     * Gets the latency of the last ping/pong sequence in milliseconds.
+     */
+    readonly lastPingLatency: number;
+
+    /**
+     * Gets the average latency since the connection started in milliseconds.
+     */
+    readonly averageLatency: number;
+
     /**
      * Connect to a specific route.
      * @param {DataReceived<TDataType> dataReceived Callback that will receive the data.

package/queries/NullObservableQueryConnection.ts

@@ -17,6 +17,16 @@ export class NullObservableQueryConnection<TDataType> implements IObservableQuer
     constructor(readonly defaultValue: TDataType) {
     }
 
+    /** @inheritdoc */
+    get lastPingLatency(): number {
+        return 0;
+    }
+
+    /** @inheritdoc */
+    get averageLatency(): number {
+        return 0;
+    }
+
     /** @inheritdoc */
     connect(dataReceived: DataReceived<TDataType>) {
         dataReceived(QueryResult.empty(this.defaultValue));

package/queries/ObservableQueryConnection.ts

@@ -4,6 +4,7 @@
 import { Globals } from '../Globals';
 import { IObservableQueryConnection } from './IObservableQueryConnection';
 import { QueryResult } from './QueryResult';
+import { WebSocketMessage, WebSocketMessageType } from './WebSocketMessage';
 
 export type DataReceived<TDataType> = (data: QueryResult<TDataType>) => void;
 
@@ -15,12 +16,21 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
     private _socket!: WebSocket;
     private _disconnected = false;
     private _url: string;
+    private _pingInterval?: ReturnType<typeof setInterval>;
+    private _pingIntervalMs: number = 10000;
+    private _lastPingSentTime?: number;
+    private _lastPongLatency: number = 0;
+    private _latencySamples: number[] = [];
+    private _connectionStartTime?: number;
 
     /**
      * Initializes a new instance of the {@link ObservableQueryConnection<TDataType>} class.
      * @param {Url} url The fully qualified Url.
+     * @param {string} _microservice The microservice name.
+     * @param {number} pingIntervalMs The ping interval in milliseconds (default: 10000).
      */
-    constructor(url: URL, private readonly _microservice: string) {
+    constructor(url: URL, private readonly _microservice: string, pingIntervalMs: number = 10000) {
+        this._pingIntervalMs = pingIntervalMs;
         const secure = url.protocol?.indexOf('https') === 0 || false;
 
         this._url = `${secure ? 'wss' : 'ws'}://${url.host}${url.pathname}${url.search}`;
@@ -41,6 +51,24 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
         this.disconnect();
     }
 
+    /**
+     * Gets the latency of the last ping/pong sequence in milliseconds.
+     */
+    get lastPingLatency(): number {
+        return this._lastPongLatency;
+    }
+
+    /**
+     * Gets the average latency since the connection started in milliseconds.
+     */
+    get averageLatency(): number {
+        if (this._latencySamples.length === 0) {
+            return 0;
+        }
+        const sum = this._latencySamples.reduce((acc, val) => acc + val, 0);
+        return sum / this._latencySamples.length;
+    }
+
     /** @inheritdoc */
     connect(dataReceived: DataReceived<TDataType>, queryArguments?: object) {
         let url = this._url;
@@ -80,15 +108,19 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
                 console.log(`Connection for '${url}' established`);
                 timeToWait = 500;
                 currentAttempt = 0;
+                this._connectionStartTime = Date.now();
+                this.startPinging();
             };
             this._socket.onclose = () => {
                 if (this._disconnected) return;
                 console.log(`Unexpected connection closed for route '${url}'`);
+                this.stopPinging();
                 retry();
             };
             this._socket.onerror = (error) => {
                 if (this._disconnected) return;
                 console.log(`Error with connection for '${url}' - ${error}`);
+                this.stopPinging();
                 retry();
             };
             this._socket.onmessage = (ev) => {
@@ -96,7 +128,7 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
                     console.log('Received message after closing connection');
                     return;
                 }
-                dataReceived(JSON.parse(ev.data));
+                this.handleMessage(ev.data, dataReceived);
             };
         };
 
@@ -111,8 +143,67 @@ export class ObservableQueryConnection<TDataType> implements IObservableQueryCon
         }
         console.log(`Disconnecting '${this._url}'`);
         this._disconnected = true;
+        this.stopPinging();
         this._socket?.close();
         console.log(`Connection for '${this._url}' closed`);
         this._socket = undefined!;
     }
+
+    private startPinging() {
+        this.stopPinging();
+        this._pingInterval = setInterval(() => {
+            this.sendPing();
+        }, this._pingIntervalMs);
+    }
+
+    private stopPinging() {
+        if (this._pingInterval) {
+            clearInterval(this._pingInterval);
+            this._pingInterval = undefined;
+        }
+    }
+
+    private sendPing() {
+        if (this._disconnected || !this._socket || this._socket.readyState !== WebSocket.OPEN) {
+            return;
+        }
+
+        this._lastPingSentTime = Date.now();
+        const pingMessage: WebSocketMessage = {
+            type: WebSocketMessageType.Ping,
+            timestamp: this._lastPingSentTime
+        };
+
+        this._socket.send(JSON.stringify(pingMessage));
+    }
+
+    private handleMessage(rawData: string, dataReceived: DataReceived<TDataType>) {
+        try {
+            const message = JSON.parse(rawData) as WebSocketMessage;
+
+            // Handle messages based on type
+            if (message.type === WebSocketMessageType.Pong) {
+                this.handlePong(message);
+            } else if (message.type === WebSocketMessageType.Data || !message.type) {
+                // For backward compatibility, treat messages without a type as data messages
+                const data = message.data ?? message;
+                dataReceived(data as QueryResult<TDataType>);
+            }
+        } catch (error) {
+            console.error('Error parsing WebSocket message:', error);
+        }
+    }
+
+    private handlePong(message: WebSocketMessage) {
+        if (message.timestamp && this._lastPingSentTime) {
+            const latency = Date.now() - message.timestamp;
+            this._lastPongLatency = latency;
+            this._latencySamples.push(latency);
+
+            // Keep only the last 100 samples for average calculation
+            if (this._latencySamples.length > 100) {
+                this._latencySamples.shift();
+            }
+        }
+    }
 }

package/queries/WebSocketMessage.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the type of WebSocket message.
+ */
+export enum WebSocketMessageType {
+    /**
+     * A data message containing query results.
+     */
+    Data = 'Data',
+
+    /**
+     * A ping message sent from client to server.
+     */
+    Ping = 'Ping',
+
+    /**
+     * A pong message sent from server to client in response to a ping.
+     */
+    Pong = 'Pong'
+}
+
+/**
+ * Represents a WebSocket message envelope.
+ */
+export type WebSocketMessage = {
+    /**
+     * The type of message.
+     */
+    type: WebSocketMessageType;
+
+    /**
+     * The timestamp when the message was sent (for ping/pong latency tracking).
+     */
+    timestamp?: number;
+
+    /**
+     * The payload data (for data messages).
+     */
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    data?: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+};

package/queries/for_ObservableQueryConnection/given/an_observable_query_connection.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ObservableQueryConnection } from '../../ObservableQueryConnection';
+import * as sinon from 'sinon';
+
+export class an_observable_query_connection {
+    connection: ObservableQueryConnection<string>;
+    url: URL;
+    microservice: string;
+    mockWebSocket: sinon.SinonStubbedInstance<WebSocket>;
+
+    constructor() {
+        this.url = new URL('https://example.com/api/test');
+        this.microservice = 'test-microservice';
+        
+        // Stub the WebSocket constructor
+        this.mockWebSocket = sinon.createStubInstance(WebSocket);
+        Object.defineProperty(this.mockWebSocket, 'readyState', {
+            value: WebSocket.OPEN,
+            writable: false
+        });
+        
+        // Create connection with a short ping interval for testing (100ms)
+        this.connection = new ObservableQueryConnection<string>(this.url, this.microservice, 100);
+    }
+}

package/queries/for_ObservableQueryConnection/when_constructing.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { an_observable_query_connection } from './given/an_observable_query_connection';
+import { given } from '../../given';
+
+describe('when constructing', given(an_observable_query_connection, context => {
+    it('should have zero last ping latency', () => {
+        context.connection.lastPingLatency.should.equal(0);
+    });
+
+    it('should have zero average latency', () => {
+        context.connection.averageLatency.should.equal(0);
+    });
+}));

package/queries/for_ObservableQueryFor/when_performing/with_enumerable_query.ts

@@ -4,11 +4,13 @@
 import { an_observable_query_for } from '../given/an_observable_query_for';
 import { given } from '../../../given';
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 
 describe('when performing with enumerable query', given(an_observable_query_for, context => {
     let result: QueryResult<string[]>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: ['item1', 'item2', 'item3'],
         isSuccess: true,
@@ -27,7 +29,8 @@ describe('when performing with enumerable query', given(an_observable_query_for,
     };
 
     beforeEach(async () => {
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -41,7 +44,7 @@ describe('when performing with enumerable query', given(an_observable_query_for,
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return successful result', () => {

package/queries/for_ObservableQueryFor/when_performing/with_paging.ts

@@ -4,10 +4,12 @@
 import { an_observable_query_for } from '../given/an_observable_query_for';
 import { given } from '../../../given';
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { Paging } from '../../Paging';
 
 describe('when performing with paging', given(an_observable_query_for, context => {
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: 'test-result',
         isSuccess: true,
@@ -30,7 +32,8 @@ describe('when performing with paging', given(an_observable_query_for, context =
         if ((globalThis.fetch as sinon.SinonStub)?.restore) {
             (globalThis.fetch as sinon.SinonStub).restore();
         }
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -44,7 +47,7 @@ describe('when performing with paging', given(an_observable_query_for, context =
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should include page parameter in URL', () => {

package/queries/for_ObservableQueryFor/when_performing/with_parameter_descriptor_values.ts

@@ -4,11 +4,13 @@
 import { an_observable_query_for } from '../given/an_observable_query_for';
 import { given } from '../../../given';
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 
 describe('with parameter descriptor values', given(an_observable_query_for, context => {
     let result: QueryResult<string>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: 'test-result',
         isSuccess: true,
@@ -27,7 +29,8 @@ describe('with parameter descriptor values', given(an_observable_query_for, cont
     };
 
     beforeEach(async () => {
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -45,7 +48,7 @@ describe('with parameter descriptor values', given(an_observable_query_for, cont
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return successful result', () => {

package/queries/for_ObservableQueryFor/when_performing/with_partial_parameter_descriptor_values.ts

@@ -4,11 +4,13 @@
 import { an_observable_query_for } from '../given/an_observable_query_for';
 import { given } from '../../../given';
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 
 describe('with partial parameter descriptor values', given(an_observable_query_for, context => {
     let result: QueryResult<string>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: 'test-result',
         isSuccess: true,
@@ -27,7 +29,8 @@ describe('with partial parameter descriptor values', given(an_observable_query_f
     };
 
     beforeEach(async () => {
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -45,7 +48,7 @@ describe('with partial parameter descriptor values', given(an_observable_query_f
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return successful result', () => {

package/queries/for_ObservableQueryFor/when_performing/with_route_parameters_and_unused_parameters.ts

@@ -4,12 +4,14 @@
 import { an_observable_query_for } from '../given/an_observable_query_for';
 import { given } from '../../../given';
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 import { expect } from 'chai';
 
 describe('when performing with route parameters and unused parameters', given(an_observable_query_for, context => {
     let result: QueryResult<string>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: 'test-result',
         isSuccess: true,
@@ -28,7 +30,8 @@ describe('when performing with route parameters and unused parameters', given(an
     };
 
     beforeEach(async () => {
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -43,7 +46,7 @@ describe('when performing with route parameters and unused parameters', given(an
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return successful result', () => {

package/queries/for_ObservableQueryFor/when_performing/with_sorting.ts

@@ -4,11 +4,13 @@
 import { an_observable_query_for } from '../given/an_observable_query_for';
 import { given } from '../../../given';
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { Sorting } from '../../Sorting';
 import { SortDirection } from '../../SortDirection';
 
 describe('when performing with sorting', given(an_observable_query_for, context => {
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: 'test-result',
         isSuccess: true,
@@ -27,7 +29,8 @@ describe('when performing with sorting', given(an_observable_query_for, context
     };
 
     beforeEach(async () => {
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -41,7 +44,7 @@ describe('when performing with sorting', given(an_observable_query_for, context
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should include sortBy parameter in URL', () => {

package/queries/for_ObservableQueryFor/when_performing/with_valid_arguments.ts

@@ -6,9 +6,12 @@ import { given } from '../../../given';
 import * as sinon from 'sinon';
 import { QueryResult } from '../../QueryResult';
 
+import { createFetchHelper } from '../../../helpers/fetchHelper';
+
 describe('when performing with valid arguments', given(an_observable_query_for, context => {
     let result: QueryResult<string>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: 'test-result',
         isSuccess: true,
@@ -27,7 +30,9 @@ describe('when performing with valid arguments', given(an_observable_query_for,
     };
 
     beforeEach(async () => {
-        fetchStub = sinon.stub(global, 'fetch');
+        // Setup fetch mock using helper
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -42,7 +47,7 @@ describe('when performing with valid arguments', given(an_observable_query_for,
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return successful result', () => {

package/queries/for_QueryFor/when_performing/with_abort_controller.ts

@@ -5,12 +5,14 @@ import { a_query_for } from '../given/a_query_for';
 import { given } from '../../../given';
 
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 
 describe('with abort controller', given(a_query_for, context => {
     let result1: QueryResult<string>;
     let result2: QueryResult<string>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     let firstAbortController: AbortController;
     const mockResponse = {
         data: 'test-result',
@@ -31,7 +33,8 @@ describe('with abort controller', given(a_query_for, context => {
 
     beforeEach(async () => {
         // Setup fetch mock
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -49,7 +52,7 @@ describe('with abort controller', given(a_query_for, context => {
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should create new abort controller on second call', () => {

package/queries/for_QueryFor/when_performing/with_enumerable_query.ts

@@ -5,11 +5,13 @@ import { a_query_for } from '../given/a_query_for';
 import { given } from '../../../given';
 
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 
 describe('with enumerable query', given(a_query_for, context => {
     let result: QueryResult<string[]>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
     const mockResponse = {
         data: ['item1', 'item2'],
         isSuccess: true,
@@ -29,7 +31,8 @@ describe('with enumerable query', given(a_query_for, context => {
 
     beforeEach(async () => {
         // Setup fetch mock
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.resolves({
             json: sinon.stub().resolves(mockResponse),
             ok: true,
@@ -43,7 +46,7 @@ describe('with enumerable query', given(a_query_for, context => {
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return successful result', () => {

package/queries/for_QueryFor/when_performing/with_fetch_error.ts

@@ -5,15 +5,18 @@ import { a_query_for } from '../given/a_query_for';
 import { given } from '../../../given';
 
 import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
 import { QueryResult } from '../../QueryResult';
 
 describe('with fetch error', given(a_query_for, context => {
     let result: QueryResult<string>;
     let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
 
     beforeEach(async () => {
         // Setup fetch mock to reject
-        fetchStub = sinon.stub(global, 'fetch');
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
         fetchStub.rejects(new Error('Network error'));
 
         context.query.setOrigin('https://api.example.com');
@@ -29,7 +32,7 @@ describe('with fetch error', given(a_query_for, context => {
     });
 
     afterEach(() => {
-        fetchStub.restore();
+        fetchHelper.restore();
     });
 
     it('should return no success result', () => {