@cratis/arc 21.4.0 → 21.6.0

package/package.json

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

package/queries/QueryFor.ts

@@ -14,6 +14,7 @@ import { ParameterDescriptor } from '../reflection/ParameterDescriptor';
 import { ParametersHelper } from '../reflection/ParametersHelper';
 import { QueryHttpMethod } from './QueryHttpMethod';
 import { executeQueryHttpRequest } from './QueryHttpRequest';
+import { isAbortError } from './isAbortError';
 
 /**
  * Represents an implementation of {@link IQueryFor}.
@@ -117,17 +118,56 @@ export abstract class QueryFor<TDataType, TParameters = object> implements IQuer
             headers[Globals.microserviceHttpHeader] = this._microservice;
         }
 
-        const response = await executeQueryHttpRequest(this._httpMethod, {
-            route: this.route,
-            apiBasePath: this._apiBasePath,
-            origin: this._origin,
-            args: (args as object) ?? {},
-            parameterValues,
-            paging: this.paging,
-            sorting: this.sorting,
-            headers,
-            signal: this.abortController.signal
-        });
+        let response: Response;
+
+        try {
+            response = await executeQueryHttpRequest(this._httpMethod, {
+                route: this.route,
+                apiBasePath: this._apiBasePath,
+                origin: this._origin,
+                args: (args as object) ?? {},
+                parameterValues,
+                paging: this.paging,
+                sorting: this.sorting,
+                headers,
+                signal: this.abortController.signal
+            });
+        } catch (error) {
+            // An abort is not a failure - it is this query superseding its own in-flight request above.
+            // Rethrowing lets the caller discard the superseded request so it cannot settle over the
+            // newer one that now owns the result.
+            if (isAbortError(error)) {
+                throw error;
+            }
+
+            // A dead network, a CORS rejection or a DNS failure never reaches the server, so it is
+            // neither an authorization nor a validation outcome - it is reported as an exception, with
+            // the default value as data, exactly as every other unsuccessful result from here does.
+            // Destructuring a nullish rejection value throws, which would make the `String(error)`
+            // fallback written for exactly that case unreachable - so it is coerced to an object first.
+            const { message } = (error ?? {}) as { message?: string };
+            const failure = {
+                ...QueryResult.noSuccess,
+                data: this.defaultValue,
+                isSuccess: false,
+                isAuthorized: true,
+                isValid: true,
+                hasExceptions: true,
+                exceptionMessages: [message ?? String(error)],
+                // Left empty on purpose. Every result the server returns has its stack trace blanked
+                // unless exception detail is explicitly exposed, and consumers are told to forward
+                // this field to a logger - so filling it in here would make a failure that never
+                // reached the server the one case that escapes that policy. The message is what
+                // diagnoses a transport failure; the browser's own frames add nothing.
+                exceptionStackTrace: ''
+            };
+
+            // `hasData` is a prototype getter, and a spread copies own properties only - so the literal
+            // above would hand every consumer of this public `IQueryResult` member `undefined` instead
+            // of a boolean. Restoring the prototype makes it a real {@link QueryResult} again while
+            // leaving every field value exactly as it is.
+            return Object.setPrototypeOf(failure, QueryResult.prototype) as QueryResult<TDataType>;
+        }
 
         try {
             const result = await response.json();

package/queries/for_QueryFor/when_performing/with_a_nullish_transport_rejection.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+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 a nullish transport rejection', given(a_query_for, context => {
+    let outcome: { resolved: boolean; result?: QueryResult<string> };
+    let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
+
+    beforeEach(async () => {
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
+
+        // Nothing guarantees a rejection value is an object - `Promise.reject()` and a thrown `undefined`
+        // both reach here, and an interceptor or a polyfilled fetch can produce either.
+        fetchStub.callsFake(() => Promise.reject(undefined));
+
+        context.query.setOrigin('https://api.example.com');
+
+        outcome = await context.query.perform({ id: 'test-id' }).then(
+            result => ({ resolved: true, result }),
+            () => ({ resolved: false }));
+    });
+
+    afterEach(() => {
+        fetchHelper.restore();
+    });
+
+    it('should resolve rather than reject', () => outcome.resolved.should.be.true);
+
+    it('should report that it has exceptions', () => outcome.result!.hasExceptions.should.be.true);
+
+    it('should describe the rejection it could not read a message from', () => outcome.result!.exceptionMessages.should.deep.equal(['undefined']));
+}));

package/queries/for_QueryFor/when_performing/with_an_aborted_request.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 { a_query_for } from '../given/a_query_for';
+import { given } from '../../../given';
+
+import * as sinon from 'sinon';
+import { createFetchHelper } from '../../../helpers/fetchHelper';
+
+describe('with an aborted request', given(a_query_for, context => {
+    let rejection: unknown;
+    let fetchStub: sinon.SinonStub;
+    let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
+
+    beforeEach(async () => {
+        fetchHelper = createFetchHelper();
+        fetchStub = fetchHelper.stubFetch();
+        fetchStub.rejects(Object.assign(new Error('The operation was aborted'), { name: 'AbortError' }));
+
+        context.query.setOrigin('https://api.example.com');
+
+        // An abort only ever happens because a newer request superseded this one, so the outcome is
+        // recorded rather than swallowed - the assertions below are on what actually came back.
+        rejection = await context.query.perform({ id: 'test-id' }).then(() => undefined, error => error);
+    });
+
+    afterEach(() => {
+        fetchHelper.restore();
+    });
+
+    it('should reject so the superseded request cannot settle a result', () => (rejection !== undefined).should.be.true);
+
+    it('should reject with the abort error', () => (rejection as Error).name.should.equal('AbortError'));
+}));

package/queries/for_QueryFor/when_performing/with_fetch_error.ts

@@ -14,37 +14,30 @@ describe('with fetch error', given(a_query_for, context => {
     let fetchHelper: { stubFetch: () => sinon.SinonStub; restore: () => void };
 
     beforeEach(async () => {
-        // Setup fetch mock to reject
         fetchHelper = createFetchHelper();
         fetchStub = fetchHelper.stubFetch();
         fetchStub.rejects(new Error('Network error'));
 
         context.query.setOrigin('https://api.example.com');
 
-        try {
-            // Call perform with valid arguments - should handle the error and return no success
-            result = await context.query.perform({ id: 'test-id' });
-        } catch {
-            // If QueryFor doesn't handle the error, we'll create a default response
-            const noSuccess = { ...QueryResult.noSuccess, data: context.query.defaultValue } as QueryResult<string>;
-            result = noSuccess;
-        }
+        result = await context.query.perform({ id: 'test-id' });
     });
 
     afterEach(() => {
         fetchHelper.restore();
     });
 
-    it('should return no success result', () => {
-        result.isSuccess.should.be.false;
-    });
+    it('should resolve rather than reject', () => (result !== undefined).should.be.true);
 
-    it('should return default value', () => {
-        result.data.should.equal('');
-    });
+    it('should return an unsuccessful result', () => result.isSuccess.should.be.false);
 
-    it('should return result without data', () => {
-        result.data.should.equal('');
-        result.isSuccess.should.be.false;
-    });
-}));
+    it('should report that it has exceptions', () => result.hasExceptions.should.be.true);
+
+    it('should carry the transport error message', () => result.exceptionMessages.should.deep.equal(['Network error']));
+
+    it('should return the default value as data', () => result.data.should.equal(''));
+
+    // `hasData` is part of the public `IQueryResult` contract, and a consumer awaiting `perform()`
+    // directly reads it off this object rather than off the `QueryResultWithState` the hooks build.
+    it('should expose hasData as a boolean', () => (typeof result.hasData).should.equal('boolean'));
+}));

package/queries/isAbortError.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.
+
+/**
+ * Determines whether an error is the rejection produced by aborting a request through an
+ * {@link AbortSignal} - as opposed to a genuine transport failure.
+ *
+ * Deliberately kept out of the `queries` barrel: it is an internal detail shared by the query
+ * transport and {@link QueryFor}, not public surface for consumers to depend on.
+ * @param error The error to inspect.
+ * @returns True if the error represents an aborted request, false otherwise.
+ */
+export function isAbortError(error: unknown): boolean {
+    return (error as { name?: string })?.name === 'AbortError';
+}