@cratis/arc 22.0.1 → 22.1.0

package/queries/for_ObservableQueryFor/when_subscribing/with_direct_mode_and_sse_transport.ts

@@ -9,61 +9,95 @@ import { ObservableQuerySubscription } from '../../ObservableQuerySubscription';
 
 import * as sinon from 'sinon';
 
-describe('when subscribing with direct mode and SSE transport', given(an_observable_query_for, context => {
-    let callback: sinon.SinonStub;
-    let subscription: ObservableQuerySubscription<string>;
-    let capturedUrl: string;
-    let originalQueryDirectMode: boolean;
-    let originalTransportMethod: QueryTransportMethod;
-
-    beforeEach(() => {
-        originalQueryDirectMode = Globals.queryDirectMode;
-        originalTransportMethod = Globals.queryTransportMethod;
-
-        Globals.queryDirectMode = true;
-        Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
-
-        context.query.setOrigin('https://example.com');
-        callback = sinon.stub();
-
-        const FakeEventSourceConstructor = function (this: EventSource, url: string) {
-            capturedUrl = url;
-            Object.assign(this, {
-                onopen: null,
-                onerror: null,
-                onmessage: null,
-                close: sinon.stub(),
-                addEventListener: sinon.stub(),
-                removeEventListener: sinon.stub(),
-            });
+describe(
+    'when subscribing with direct mode and SSE transport',
+    given(an_observable_query_for, (context) => {
+        let callback: sinon.SinonStub;
+        let subscription: ObservableQuerySubscription<string>;
+        let capturedUrl: string;
+        let eventSourceInstance: EventSource & {
+            onmessage: ((event: { data: string }) => void) | null;
         };
-        (globalThis as Record<string, unknown>)['EventSource'] = FakeEventSourceConstructor;
-
-        subscription = context.query.subscribe(callback, { id: 'test-id' });
-    });
-
-    afterEach(() => {
-        Globals.queryDirectMode = originalQueryDirectMode;
-        Globals.queryTransportMethod = originalTransportMethod;
-        if (subscription) {
-            subscription.unsubscribe();
-        }
-        delete (globalThis as Record<string, unknown>)['EventSource'];
-    });
-
-    it('should connect to the per-query SSE URL', () => {
-        capturedUrl.should.include('/api/test/test-id');
-    });
-
-    it('should not connect to the hub SSE endpoint', () => {
-        capturedUrl.should.not.include('/.cratis/queries/sse');
-    });
-
-    it('should not include a query name parameter', () => {
-        capturedUrl.should.not.include('query=');
-    });
-
-    it('should return a subscription', () => {
-        subscription.should.not.be.undefined;
-    });
-}));
+        let originalQueryDirectMode: boolean;
+        let originalTransportMethod: QueryTransportMethod;
+
+        beforeEach(() => {
+            originalQueryDirectMode = Globals.queryDirectMode;
+            originalTransportMethod = Globals.queryTransportMethod;
+
+            Globals.queryDirectMode = true;
+            Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
+
+            context.query.setOrigin('https://example.com');
+            callback = sinon.stub();
+
+            const FakeEventSourceConstructor = function (this: EventSource, url: string) {
+                capturedUrl = url;
+                eventSourceInstance = this as EventSource & {
+                    onmessage: ((event: { data: string }) => void) | null;
+                };
+                Object.assign(this, {
+                    onopen: null,
+                    onerror: null,
+                    onmessage: null,
+                    close: sinon.stub(),
+                    addEventListener: sinon.stub(),
+                    removeEventListener: sinon.stub(),
+                });
+            };
+            (globalThis as Record<string, unknown>)['EventSource'] =
+                FakeEventSourceConstructor;
+
+            subscription = context.query.subscribe(callback, { id: 'test-id' });
+
+            const result = {
+                data: 'ready result',
+                isSuccess: true,
+                isAuthorized: true,
+                isValid: true,
+                hasExceptions: false,
+                validationResults: [],
+                exceptionMessages: [],
+                exceptionStackTrace: '',
+                paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+            };
+            eventSourceInstance.onmessage?.({ data: JSON.stringify(result) });
+            eventSourceInstance.onmessage?.({
+                data: JSON.stringify({ ...result, isSuccess: false, isReady: false }),
+            });
+        });
+
+        afterEach(() => {
+            Globals.queryDirectMode = originalQueryDirectMode;
+            Globals.queryTransportMethod = originalTransportMethod;
+            if (subscription) {
+                subscription.unsubscribe();
+            }
+            delete (globalThis as Record<string, unknown>)['EventSource'];
+        });
+
+        it('should connect to the per-query SSE URL', () => {
+            capturedUrl.should.include('/api/test/test-id');
+        });
+
+        it('should not connect to the hub SSE endpoint', () => {
+            capturedUrl.should.not.include('/.cratis/queries/sse');
+        });
+
+        it('should not include a query name parameter', () => {
+            capturedUrl.should.not.include('query=');
+        });
+
+        it('should return a subscription', () => {
+            subscription.should.not.be.undefined;
+        });
+
+        it('should normalize omitted readiness to true', () => {
+            callback.firstCall.args[0].isReady.should.be.true;
+        });
+
+        it('should preserve false readiness', () => {
+            callback.secondCall.args[0].isReady.should.be.false;
+        });
+    }),
+);

package/queries/for_ObservableQueryFor/when_subscribing/with_direct_mode_disabled_and_sse_transport.ts

@@ -8,63 +8,135 @@ import { QueryTransportMethod } from '../../QueryTransportMethod';
 import { ObservableQuerySubscription } from '../../ObservableQuerySubscription';
 import { SSE_HUB_ROUTE } from '../../ServerSentEventQueryConnection';
 import { resetSharedMultiplexer } from '../../ObservableQueryMultiplexer';
+import { HubMessageType } from '../../WebSocketHubConnection';
 
 import * as sinon from 'sinon';
 
-describe('when subscribing with direct mode disabled and SSE transport', given(an_observable_query_for, context => {
-    let callback: sinon.SinonStub;
-    let subscription: ObservableQuerySubscription<string>;
-    let capturedUrl: string;
-    let originalQueryDirectMode: boolean;
-    let originalTransportMethod: QueryTransportMethod;
-
-    beforeEach(() => {
-        originalQueryDirectMode = Globals.queryDirectMode;
-        originalTransportMethod = Globals.queryTransportMethod;
-        resetSharedMultiplexer();
-
-        Globals.queryDirectMode = false;
-        Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
-
-        context.query.setOrigin('https://example.com');
-        callback = sinon.stub();
-
-        // EventSource doesn't exist in Node.js — inject a fake via globalThis
-        const FakeEventSourceConstructor = function (this: EventSource, url: string) {
-            capturedUrl = url;
-            Object.assign(this, {
-                onopen: null,
-                onerror: null,
-                onmessage: null,
-                close: sinon.stub(),
-                addEventListener: sinon.stub(),
-                removeEventListener: sinon.stub(),
-            });
+describe(
+    'when subscribing with direct mode disabled and SSE transport',
+    given(an_observable_query_for, (context) => {
+        let callback: sinon.SinonStub;
+        let subscription: ObservableQuerySubscription<string>;
+        let capturedUrl: string;
+        let fetchStub: sinon.SinonStub;
+        let eventSourceInstance: EventSource & {
+            onopen: (() => void) | null;
+            onmessage: ((event: { data: string }) => void) | null;
         };
-        (globalThis as Record<string, unknown>)['EventSource'] = FakeEventSourceConstructor;
+        let originalQueryDirectMode: boolean;
+        let originalTransportMethod: QueryTransportMethod;
+
+        beforeEach(() => {
+            originalQueryDirectMode = Globals.queryDirectMode;
+            originalTransportMethod = Globals.queryTransportMethod;
+            resetSharedMultiplexer();
+
+            Globals.queryDirectMode = false;
+            Globals.queryTransportMethod = QueryTransportMethod.ServerSentEvents;
+
+            context.query.setOrigin('https://example.com');
+            callback = sinon.stub();
+
+            // EventSource doesn't exist in Node.js — inject a fake via globalThis
+            const FakeEventSourceConstructor = function (this: EventSource, url: string) {
+                capturedUrl = url;
+                eventSourceInstance = this as EventSource & {
+                    onopen: (() => void) | null;
+                    onmessage: ((event: { data: string }) => void) | null;
+                };
+                Object.assign(this, {
+                    onopen: null,
+                    onerror: null,
+                    onmessage: null,
+                    close: sinon.stub(),
+                    addEventListener: sinon.stub(),
+                    removeEventListener: sinon.stub(),
+                });
+            };
+            (globalThis as Record<string, unknown>)['EventSource'] =
+                FakeEventSourceConstructor;
+            fetchStub = sinon.stub().resolves({ ok: true } as Response);
+            (globalThis as Record<string, unknown>)['fetch'] = fetchStub;
+
+            subscription = context.query.subscribe(callback, { id: 'test-id' });
+            eventSourceInstance.onopen?.();
+            // An older Arc server omits subscription capabilities from Connected, so this fixture
+            // intentionally exercises legacy missing-revision result frames.
+            eventSourceInstance.onmessage?.({
+                data: JSON.stringify({
+                    type: HubMessageType.Connected,
+                    payload: 'connection-1',
+                }),
+            });
 
-        subscription = context.query.subscribe(callback, { id: 'test-id' });
-    });
+            let subscribeRequest: { queryId: string; revision?: number };
+            try {
+                subscribeRequest = JSON.parse(fetchStub.firstCall.args[1].body as string);
+            } catch (error) {
+                throw new Error('The SSE hub subscribe request was not valid JSON', {
+                    cause: error,
+                });
+            }
+            eventSourceInstance.onmessage?.({
+                data: JSON.stringify({
+                    type: HubMessageType.QueryResult,
+                    queryId: subscribeRequest.queryId,
+                    payload: {
+                        data: 'ready result',
+                        isSuccess: true,
+                        isAuthorized: true,
+                        isValid: true,
+                        hasExceptions: false,
+                        validationResults: [],
+                        exceptionMessages: [],
+                        exceptionStackTrace: '',
+                        paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+                    },
+                }),
+            });
+        });
+
+        afterEach(() => {
+            Globals.queryDirectMode = originalQueryDirectMode;
+            Globals.queryTransportMethod = originalTransportMethod;
+            if (subscription) {
+                subscription.unsubscribe();
+            }
+            delete (globalThis as Record<string, unknown>)['EventSource'];
+            delete (globalThis as Record<string, unknown>)['fetch'];
+            resetSharedMultiplexer();
+        });
+
+        it('should connect to the centralized SSE hub endpoint', () => {
+            capturedUrl.should.include(SSE_HUB_ROUTE);
+        });
+
+        it('should not include query name in URL since subscriptions are done via POST', () => {
+            capturedUrl.should.not.include('query=');
+        });
 
-    afterEach(() => {
-        Globals.queryDirectMode = originalQueryDirectMode;
-        Globals.queryTransportMethod = originalTransportMethod;
-        if (subscription) {
-            subscription.unsubscribe();
+        it('should return a subscription', () => {
+            (subscription === undefined).should.equal(false);
+        });
+
+        it('should omit revisions when the server does not advertise support', () => {
+            (getSubscribeBody().revision === undefined).should.equal(true);
+        });
+
+        function getSubscribeBody(): { revision?: number } {
+            try {
+                return JSON.parse(fetchStub.firstCall.args[1].body as string) as {
+                    revision?: number;
+                };
+            } catch (error) {
+                throw new Error('Expected a valid subscribe request body', {
+                    cause: error,
+                });
+            }
         }
-        delete (globalThis as Record<string, unknown>)['EventSource'];
-        resetSharedMultiplexer();
-    });
-
-    it('should connect to the centralized SSE hub endpoint', () => {
-        capturedUrl.should.include(SSE_HUB_ROUTE);
-    });
-
-    it('should not include query name in URL since subscriptions are done via POST', () => {
-        capturedUrl.should.not.include('query=');
-    });
-
-    it('should return a subscription', () => {
-        subscription.should.not.be.undefined;
-    });
-}));
+
+        it('should normalize omitted readiness to true', () => {
+            callback.firstCall.args[0].isReady.should.equal(true);
+        });
+    }),
+);

package/queries/for_ObservableQueryFor/when_subscribing/with_web_socket_hub_payload_without_readiness.ts

@@ -0,0 +1,107 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { given } from '../../../given';
+import { Globals } from '../../../Globals';
+import { HubMessageType } from '../../WebSocketHubConnection';
+import type { ObservableQuerySubscription } from '../../ObservableQuerySubscription';
+import { resetSharedMultiplexer } from '../../ObservableQueryMultiplexer';
+import { QueryTransportMethod } from '../../QueryTransportMethod';
+import { an_observable_query_for } from '../given/an_observable_query_for';
+
+describe(
+    'when subscribing with web socket hub payload without readiness',
+    given(an_observable_query_for, (context) => {
+        let callback: sinon.SinonStub;
+        let subscription: ObservableQuerySubscription<string>;
+        let originalQueryDirectMode: boolean;
+        let originalTransportMethod: QueryTransportMethod;
+        let originalWebSocket: typeof WebSocket;
+        let socket: {
+            readyState: number;
+            onopen: (() => void) | null;
+            onclose: (() => void) | null;
+            onerror: ((event: Event) => void) | null;
+            onmessage: ((event: { data: string }) => void) | null;
+            send: sinon.SinonStub;
+            close: sinon.SinonStub;
+        };
+
+        beforeEach(() => {
+            originalQueryDirectMode = Globals.queryDirectMode;
+            originalTransportMethod = Globals.queryTransportMethod;
+            originalWebSocket = globalThis.WebSocket;
+            resetSharedMultiplexer();
+
+            Globals.queryDirectMode = false;
+            Globals.queryTransportMethod = QueryTransportMethod.WebSocket;
+            context.query.setOrigin('https://example.com');
+            callback = sinon.stub();
+
+            socket = {
+                readyState: 0,
+                onopen: null,
+                onclose: null,
+                onerror: null,
+                onmessage: null,
+                send: sinon.stub(),
+                close: sinon.stub(),
+            };
+
+            const WebSocketStub = sinon.stub().returns(socket);
+            Object.assign(WebSocketStub, {
+                CONNECTING: 0,
+                OPEN: 1,
+                CLOSING: 2,
+                CLOSED: 3,
+            });
+            (globalThis as Record<string, unknown>)['WebSocket'] = WebSocketStub;
+
+            subscription = context.query.subscribe(callback, { id: 'test-id' });
+            socket.readyState = 1;
+            socket.onopen?.();
+
+            // An older Arc server sends no Connected capability message, so this fixture intentionally
+            // remains in legacy mode and accepts only result frames without a revision.
+            let subscribeMessage: { queryId: string };
+            try {
+                subscribeMessage = JSON.parse(socket.send.firstCall.args[0]);
+            } catch (error) {
+                throw new Error('The WebSocket subscribe message was not valid JSON', {
+                    cause: error,
+                });
+            }
+            socket.onmessage?.({
+                data: JSON.stringify({
+                    type: HubMessageType.QueryResult,
+                    queryId: subscribeMessage.queryId,
+                    payload: {
+                        data: 'ready result',
+                        isSuccess: true,
+                        isAuthorized: true,
+                        isValid: true,
+                        hasExceptions: false,
+                        validationResults: [],
+                        exceptionMessages: [],
+                        exceptionStackTrace: '',
+                        paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+                    },
+                }),
+            });
+        });
+
+        afterEach(() => {
+            subscription?.unsubscribe();
+            Globals.queryDirectMode = originalQueryDirectMode;
+            Globals.queryTransportMethod = originalTransportMethod;
+            globalThis.WebSocket = originalWebSocket;
+            resetSharedMultiplexer();
+            sinon.restore();
+        });
+
+        it('should normalize omitted readiness to true', () => {
+            callback.firstCall.args[0].isReady.should.equal(true);
+        });
+    }),
+);

package/queries/for_QueryInstanceCache/when_setting_last_result/with_only_readiness_changed.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import sinon from 'sinon';
+import { PagingInfo } from '../../PagingInfo';
+import { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when setting the last result with only readiness changed', () => {
+    const key = 'MyQuery::';
+    const data = ['a', 'b'];
+    let listener: sinon.SinonStub;
+
+    beforeEach(() => {
+        const cache = new QueryInstanceCache();
+        cache.getOrCreate(key, () => ({}));
+        listener = sinon.stub();
+        cache.addListener<string[]>(key, listener);
+
+        cache.setLastResult(
+            key,
+            new QueryResultWithState(
+                data,
+                PagingInfo.noPaging,
+                false,
+                true,
+                true,
+                [],
+                false,
+                [],
+                '',
+                false,
+                undefined,
+                false,
+            ),
+        );
+        listener.resetHistory();
+
+        cache.setLastResult(
+            key,
+            new QueryResultWithState(
+                data,
+                PagingInfo.noPaging,
+                false,
+                true,
+                true,
+                [],
+                false,
+                [],
+                '',
+                false,
+                undefined,
+                true,
+            ),
+        );
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should notify the listener', () => listener.calledOnce.should.be.true);
+    it('should provide the changed readiness', () =>
+        listener.firstCall.args[0].isReady.should.be.true);
+});

package/queries/for_QueryResult/when_constructing_from_a_server_result/with_readiness_false.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResult } from '../../QueryResult';
+
+describe('when constructing from a server result with readiness false', () => {
+    const result = new QueryResult(
+        {
+            data: null,
+            isSuccess: false,
+            isReady: false,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+        },
+        Object,
+        false,
+    );
+
+    it('should not be ready', () => result.isReady.should.be.false);
+});

package/queries/for_QueryResult/when_constructing_from_a_server_result/without_readiness.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResult } from '../../QueryResult';
+
+describe('when constructing from a server result without readiness', () => {
+    const result = new QueryResult(
+        {
+            data: {},
+            isSuccess: true,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+        },
+        Object,
+        false,
+    );
+
+    it('should be ready', () => result.isReady.should.be.true);
+});

package/queries/for_QueryResultWithState/when_creating_from_query_result/with_readiness_false.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResult } from '../../QueryResult';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when creating from query result with readiness false', () => {
+    const queryResult = new QueryResult(
+        {
+            data: null,
+            isSuccess: false,
+            isReady: false,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: false,
+            validationResults: [],
+            exceptionMessages: [],
+            exceptionStackTrace: '',
+            paging: { page: 0, size: 0, totalItems: 0, totalPages: 0 },
+        },
+        Object,
+        false,
+    );
+
+    const result = QueryResultWithState.fromQueryResult(queryResult, false);
+
+    it('should not be ready', () => result.isReady.should.be.false);
+});

package/queries/for_QueryResultWithState/when_creating_from_query_result/without_readiness.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { IQueryResult } from '../../IQueryResult';
+import { PagingInfo } from '../../PagingInfo';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+describe('when creating from query result without readiness', () => {
+    const queryResult: IQueryResult<string> = {
+        data: 'ready result',
+        paging: PagingInfo.noPaging,
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        validationResults: [],
+        hasExceptions: false,
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        hasData: true,
+    };
+
+    const result = QueryResultWithState.fromQueryResult(queryResult, false);
+
+    it('should be ready', () => result.isReady.should.be.true);
+});

package/queries/for_ServerSentEventHubConnection/given/a_deferred_promise.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.
+
+export class a_deferred_promise<T> {
+    readonly promise: Promise<T>;
+    resolve!: (value: T) => void;
+    reject!: (reason?: unknown) => void;
+
+    constructor() {
+        this.promise = new Promise<T>((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+}