@cratis/arc 20.60.0 → 20.60.2

package/queries/for_QueryInstanceCache/when_setting_last_result/with_a_re_delivered_identical_result.ts

@@ -0,0 +1,34 @@
+// 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 { QueryInstanceCache } from '../../QueryInstanceCache';
+import { QueryResultWithState } from '../../QueryResultWithState';
+
+type Item = { id: string; name: string };
+
+describe('when the server re-delivers an identical snapshot after re-subscribing', () => {
+    const key = 'MyQuery::';
+    let cache: QueryInstanceCache;
+    let listener: sinon.SinonStub;
+
+    const first = QueryResultWithState.empty<Item[]>([{ id: 'a', name: 'First' }]);
+
+    // A fresh deserialization of the same payload — equal in value, all-new references.
+    const second = QueryResultWithState.empty<Item[]>([{ id: 'a', name: 'First' }]);
+
+    beforeEach(() => {
+        cache = new QueryInstanceCache();
+        cache.getOrCreate(key, () => ({}));
+        listener = sinon.stub();
+        cache.addListener(key, listener);
+
+        cache.setLastResult(key, first);
+        cache.setLastResult(key, second);
+    });
+
+    afterEach(() => sinon.restore());
+
+    it('should notify only for the first result', () => listener.calledOnce.should.be.true);
+    it('should keep holding the original data reference', () => cache.getLastResult<Item[]>(key)!.data.should.equal(first.data));
+});

package/queries/for_ServerSentEventHubConnection/when_keep_alive_is_idle/triggers_reconnect.ts

@@ -33,10 +33,10 @@ describe('when keep-alive interval elapses without any server message', given(a_
         // Deliver Connected so the connection is fully established.
         context.simulateMessage({ type: HubMessageType.Connected, payload: 'conn-123' });
 
-        // Advance past the idle threshold (1.5× keep-alive interval) without any further messages.
-        // The check interval fires every KEEP_ALIVE_MS; the idle threshold is KEEP_ALIVE_MS * 1.5.
-        // After the first interval tick (500ms) the elapsed idle time (500ms) is below the
-        // threshold (750ms). At the second tick (1000ms) the elapsed time exceeds the threshold.
+        // Advance past the idle threshold (IDLE_THRESHOLD_FACTOR × keep-alive interval) without any
+        // further messages. The check interval fires every KEEP_ALIVE_MS; the idle threshold is
+        // KEEP_ALIVE_MS * 2. After the first interval tick (500ms) the elapsed idle time (500ms) is
+        // below the threshold (1000ms). At the second tick (1000ms) the elapsed time reaches it.
         clock.tick(KEEP_ALIVE_MS * 2 + 1);
     });
 

package/queries/for_ServerSentEventHubConnection/when_server_advertises_a_longer_keep_alive_interval/does_not_reconnect_at_the_assumed_threshold.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 sinon from 'sinon';
+import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event_hub_connection';
+import { given } from '../../../given';
+import { HubMessageType } from '../../WebSocketHubConnection';
+
+const ASSUMED_KEEP_ALIVE_MS = 500;
+const SERVER_KEEP_ALIVE_MS = 2000;
+
+describe('when the server advertises a longer keep-alive interval than the client assumed', given(a_server_sent_event_hub_connection, context => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        context.setup();
+
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        const { ServerSentEventHubConnection } = require('../../ServerSentEventHubConnection');
+        context.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            ASSUMED_KEEP_ALIVE_MS,
+            15000,
+            context.policy
+        );
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+
+        context.simulateMessage({
+            type: HubMessageType.Connected,
+            payload: 'conn-123',
+            keepAliveIntervalMs: SERVER_KEEP_ALIVE_MS
+        });
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    describe('and the assumed threshold elapses', () => {
+        beforeEach(() => {
+            // Far past the assumed threshold (2 × 500ms), but the server only promised a message
+            // every 2000ms — tearing the connection down here is exactly the bug being fixed.
+            clock.tick(ASSUMED_KEEP_ALIVE_MS * 2 + 1);
+        });
+
+        it('should not schedule a reconnect', () => (context.policy.schedule as sinon.SinonStub).called.should.be.false);
+    });
+
+    describe('and the advertised threshold elapses', () => {
+        beforeEach(() => {
+            // Checks now run on the server's 2000ms cadence; the tick at 4000ms sees 4000ms of silence.
+            clock.tick(SERVER_KEEP_ALIVE_MS * 2 + 1);
+        });
+
+        it('should schedule a reconnect', () => (context.policy.schedule as sinon.SinonStub).calledOnce.should.be.true);
+    });
+}));

package/queries/for_ServerSentEventHubConnection/when_server_reports_keep_alive_disabled/never_reconnects_from_idle.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 sinon from 'sinon';
+import { a_server_sent_event_hub_connection } from '../given/a_server_sent_event_hub_connection';
+import { given } from '../../../given';
+import { HubMessageType } from '../../WebSocketHubConnection';
+
+const ASSUMED_KEEP_ALIVE_MS = 500;
+
+describe('when the server reports that keep-alive is disabled', given(a_server_sent_event_hub_connection, context => {
+    let clock: sinon.SinonFakeTimers;
+
+    beforeEach(() => {
+        clock = sinon.useFakeTimers();
+        context.setup();
+
+        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+        const { ServerSentEventHubConnection } = require('../../ServerSentEventHubConnection');
+        context.connection = new ServerSentEventHubConnection(
+            'http://localhost/.cratis/queries/sse',
+            'http://localhost/.cratis/queries/sse/subscribe',
+            'http://localhost/.cratis/queries/sse/unsubscribe',
+            '',
+            ASSUMED_KEEP_ALIVE_MS,
+            15000,
+            context.policy
+        );
+
+        context.connection.subscribe('q1', { queryName: 'MyQuery' }, sinon.stub());
+        context.simulateOpen();
+
+        context.simulateMessage({
+            type: HubMessageType.Connected,
+            payload: 'conn-123',
+            keepAliveIntervalMs: 0
+        });
+
+        // A server that never pings is silent by design — watching for silence would otherwise
+        // reconnect on a loop forever. Hard drops still surface through onerror.
+        clock.tick(ASSUMED_KEEP_ALIVE_MS * 20);
+    });
+
+    afterEach(() => {
+        clock.restore();
+        sinon.restore();
+    });
+
+    it('should never schedule a reconnect from inactivity', () => (context.policy.schedule as sinon.SinonStub).called.should.be.false);
+}));

package/queries/for_reconcileQueryData/when_items_are_added_or_removed/reuses_the_surviving_items.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a snapshot with an item added', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ];
+
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return a new collection', () => result.should.not.equal(previous));
+    it('should have the new length', () => result.length.should.equal(3));
+    it('should keep the references of the surviving items', () => {
+        result[0].should.equal(previous[0]);
+        result[1].should.equal(previous[1]);
+    });
+    it('should take the new reference for the added item', () => result[2].should.equal(next[2]));
+});
+
+describe('when reconciling a snapshot with an item removed', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should have the new length', () => result.length.should.equal(2));
+    it('should keep the reference of the item that stayed in place', () => result[0].should.equal(previous[0]));
+    it('should keep the reference of the item that shifted position', () => result[1].should.equal(previous[2]));
+});

package/queries/for_reconcileQueryData/when_one_item_changed/only_the_changed_item_gets_a_new_reference.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a snapshot in which a single item changed', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second changed' },
+        { id: 'c', name: 'Third' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return a new collection', () => result.should.not.equal(previous));
+    it('should keep the reference of the first unchanged item', () => result[0].should.equal(previous[0]));
+    it('should keep the reference of the last unchanged item', () => result[2].should.equal(previous[2]));
+    it('should take the new reference for the changed item', () => result[1].should.equal(next[1]));
+    it('should carry the changed value', () => result[1].name.should.equal('Second changed'));
+});

package/queries/for_reconcileQueryData/when_reconciling_an_unchanged_collection/preserves_all_references.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a re-delivered snapshot that did not change', () => {
+    const previous = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ];
+
+    // A fresh deserialization of the same payload — equal in value, all-new references.
+    const next = [
+        { id: 'a', name: 'First' },
+        { id: 'b', name: 'Second' }
+    ];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return the previous collection itself', () => result.should.equal(previous));
+    it('should not adopt any of the new references', () => result.forEach((item, index) => item.should.equal(previous[index])));
+});

package/queries/for_reconcileQueryData/when_reconciling_non_collection_payloads/compares_by_value.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { reconcileQueryData } from '../../reconcileQueryData';
+
+describe('when reconciling a single object that did not change', () => {
+    const previous = { id: 'a', name: 'First' };
+    const next = { id: 'a', name: 'First' };
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return the previous object', () => result.should.equal(previous));
+});
+
+describe('when reconciling a single object that changed', () => {
+    const previous = { id: 'a', name: 'First' };
+    const next = { id: 'a', name: 'Changed' };
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should return the new object', () => result.should.equal(next));
+});
+
+describe('when reconciling items that carry no identity', () => {
+    const previous = [{ name: 'First' }, { name: 'Second' }];
+    const next = [{ name: 'First' }, { name: 'Second' }];
+
+    const result = reconcileQueryData(previous, next);
+
+    it('should fall back to positional matching and preserve the collection', () => result.should.equal(previous));
+});

package/queries/index.ts

@@ -35,6 +35,7 @@ export * from './ObservableQuerySubscription';
 export * from './WebSocketMessage';
 export * from './QueryTransportMethod';
 export * from './QueryInstanceCache';
+export * from './reconcileQueryData';
 export * from './IQueryProvider';
 export * from './QueryProvider';
 export * from './QueryValidator';

package/queries/reconcileQueryData.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { deepEqual } from '../deepEqual';
+
+/**
+ * Resolves the conventional identity of an item so it can be matched against its previous version.
+ *
+ * Uses the `id` property, the same strategy the server-side change-set computation applies, and
+ * reduces concept-style identities (objects with a meaningful `toString()`) to a comparable value.
+ * @param {unknown} item The item to resolve identity for.
+ * @returns {unknown} The identity value, or `undefined` when the item carries no usable identity.
+ */
+function getIdentity(item: unknown): unknown {
+    const id = (item as Record<string, unknown>)?.id;
+
+    if (id === null || id === undefined) {
+        return undefined;
+    }
+
+    if (typeof id === 'object') {
+        const stringValue = id.toString();
+        return stringValue !== '[object Object]' ? stringValue : JSON.stringify(id);
+    }
+
+    return id;
+}
+
+/**
+ * Reconciles a full payload against the previous one, carrying over the previous object references
+ * for every item that did not actually change.
+ *
+ * Observable queries re-deliver a complete snapshot whenever a subscription is (re-)established.
+ * Deserializing that snapshot produces entirely new object references, so consumers that compare by
+ * reference — memoized components, effect dependencies — treat every item as changed even when the
+ * payload is identical to what they already display. Reconciling restores referential stability:
+ * unchanged items keep their previous reference, and when nothing changed at all the previous
+ * payload itself is returned so callers can detect "no change" with a single `===`.
+ *
+ * Items are matched by their `id` when present, falling back to position for identity-less items.
+ * @template T The payload type.
+ * @param {T} previous The payload currently held.
+ * @param {T} next The freshly received payload.
+ * @returns {T} `previous` when nothing changed; otherwise the new payload with unchanged items carried over by reference.
+ */
+export function reconcileQueryData<T>(previous: T, next: T): T {
+    if (previous === next) {
+        return previous;
+    }
+
+    if (Array.isArray(previous) && Array.isArray(next)) {
+        return reconcileArray(previous, next) as T;
+    }
+
+    return deepEqual(previous, next) ? previous : next;
+}
+
+/**
+ * Reconciles two arrays element by element, preserving previous references for unchanged items.
+ * @param {unknown[]} previous The array currently held.
+ * @param {unknown[]} next The freshly received array.
+ * @returns {unknown[]} `previous` when the arrays are equivalent; otherwise a new array reusing unchanged items.
+ */
+function reconcileArray(previous: unknown[], next: unknown[]): unknown[] {
+    const previousByIdentity = new Map<unknown, unknown>();
+
+    for (const item of previous) {
+        const identity = getIdentity(item);
+
+        // Keep the first occurrence — duplicate identities are not a shape we can reconcile
+        // meaningfully, and preferring the first keeps the result deterministic.
+        if (identity !== undefined && !previousByIdentity.has(identity)) {
+            previousByIdentity.set(identity, item);
+        }
+    }
+
+    let changed = previous.length !== next.length;
+
+    const reconciled = next.map((item, index) => {
+        const identity = getIdentity(item);
+        const candidate = identity !== undefined ? previousByIdentity.get(identity) : previous[index];
+
+        if (candidate !== undefined && deepEqual(candidate, item)) {
+            // An unchanged item that moved still leaves the collection changed as a whole, but the
+            // item itself keeps its reference so only the ordering re-renders, not its content.
+            if (candidate !== previous[index]) {
+                changed = true;
+            }
+
+            return candidate;
+        }
+
+        changed = true;
+        return item;
+    });
+
+    return changed ? reconciled : previous;
+}