@cratis/arc 22.142.0 → 22.144.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "type": "module",
     "name": "@cratis/arc",
-    "version": "22.142.0",
+    "version": "22.144.0",
     "description": "TypeScript command, query, validation, identity, and messaging runtime for Cratis Arc — the CQRS application framework for ASP.NET Core — used by generated proxies.",
     "keywords": [
         "cratis",
@@ -118,10 +118,10 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/fundamentals": "^7.25.1",
+        "@cratis/fundamentals": "^7.27.0",
         "rxjs": "^7.8.2"
     },
     "devDependencies": {
-        "@cratis/fundamentals": "7.25.1"
+        "@cratis/fundamentals": "7.27.0"
     }
 }

package/queries/ObservableQueryFor.ts

@@ -19,6 +19,7 @@ import { UrlHelpers } from '../UrlHelpers.js';
 import type { GetHttpHeaders } from '../GetHttpHeaders.js';
 import type { ParameterDescriptor } from '../reflection/ParameterDescriptor.js';
 import { ParametersHelper } from '../reflection/ParametersHelper.js';
+import { SliceLocation } from '../reflection/SliceLocation.js';
 import type { QueryHttpMethod } from './QueryHttpMethod.js';
 import { executeQueryHttpRequest } from './QueryHttpRequest.js';
 
@@ -32,6 +33,11 @@ export abstract class ObservableQueryFor<
     TDataType,
     TParameters = object,
 > implements IObservableQueryFor<TDataType, TParameters> {
+    /**
+     * Gets the {@link SliceLocation} of the query. Generated proxies override it with the location resolved from the backend namespace.
+     */
+    static readonly sliceLocation: SliceLocation = SliceLocation.empty;
+
     private _microservice: string;
     private _apiBasePath: string;
     private _origin: string;

package/queries/QueryFor.ts

@@ -12,6 +12,7 @@ import { Sorting } from './Sorting.js';
 import { GetHttpHeaders } from '../GetHttpHeaders.js';
 import { ParameterDescriptor } from '../reflection/ParameterDescriptor.js';
 import { ParametersHelper } from '../reflection/ParametersHelper.js';
+import { SliceLocation } from '../reflection/SliceLocation.js';
 import { QueryHttpMethod } from './QueryHttpMethod.js';
 import { executeQueryHttpRequest } from './QueryHttpRequest.js';
 import { isAbortError } from './isAbortError.js';
@@ -21,6 +22,11 @@ import { isAbortError } from './isAbortError.js';
  * @template TDataType Type of data returned by the query.
  */
 export abstract class QueryFor<TDataType, TParameters = object> implements IQueryFor<TDataType, TParameters> {
+    /**
+     * Gets the {@link SliceLocation} of the query. Generated proxies override it with the location resolved from the backend namespace.
+     */
+    static readonly sliceLocation: SliceLocation = SliceLocation.empty;
+
     private _microservice: string;
     private _apiBasePath: string;
     private _origin: string;

package/queries/for_ObservableQueryFor/when_getting_the_slice_location.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ObservableQueryFor } from '../ObservableQueryFor.js';
+import { IQuery } from '../IQuery.js';
+import { TestObservableQuery } from './given/TestQueries.js';
+import { ParameterDescriptor } from '../../reflection/ParameterDescriptor.js';
+import { SliceLocation } from '../../reflection/SliceLocation.js';
+
+class ObserveInvoices extends ObservableQueryFor<string[]> {
+    static readonly sliceLocation: SliceLocation = new SliceLocation('Billing', 'Invoices', 'Listing');
+    readonly route = '/api/billing/invoices/observe';
+    readonly defaultValue: string[] = [];
+    readonly parameterDescriptors: ParameterDescriptor[] = [];
+
+    get requiredRequestParameters(): string[] {
+        return [];
+    }
+
+    constructor() {
+        super(String, true);
+    }
+}
+
+describe('when getting the slice location', () => {
+    let declared: SliceLocation | undefined;
+    let undeclared: SliceLocation | undefined;
+
+    beforeEach(() => {
+        const query: IQuery = new ObserveInvoices();
+        declared = SliceLocation.of(query);
+        undeclared = SliceLocation.of(new TestObservableQuery());
+    });
+
+    it('should return the static slice location of the proxy class', () => declared!.should.equal(ObserveInvoices.sliceLocation));
+    it('should return the empty slice location when the class declares none', () => undeclared!.should.equal(SliceLocation.empty));
+});

package/queries/for_QueryFor/when_getting_the_slice_location.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryFor } from '../QueryFor.js';
+import { IQuery } from '../IQuery.js';
+import { TestQueryFor } from './given/TestQueries.js';
+import { ParameterDescriptor } from '../../reflection/ParameterDescriptor.js';
+import { SliceLocation } from '../../reflection/SliceLocation.js';
+
+class AllInvoices extends QueryFor<string[]> {
+    static readonly sliceLocation: SliceLocation = new SliceLocation('Billing', 'Invoices', 'Listing');
+    readonly route = '/api/billing/invoices';
+    readonly defaultValue: string[] = [];
+    readonly parameterDescriptors: ParameterDescriptor[] = [];
+
+    get requiredRequestParameters(): string[] {
+        return [];
+    }
+
+    constructor() {
+        super(String, true);
+    }
+}
+
+describe('when getting the slice location', () => {
+    let declared: SliceLocation | undefined;
+    let undeclared: SliceLocation | undefined;
+
+    beforeEach(() => {
+        const query: IQuery = new AllInvoices();
+        declared = SliceLocation.of(query);
+        undeclared = SliceLocation.of(new TestQueryFor());
+    });
+
+    it('should return the static slice location of the proxy class', () => declared!.should.equal(AllInvoices.sliceLocation));
+    it('should return the empty slice location when the class declares none', () => undeclared!.should.equal(SliceLocation.empty));
+});

package/reflection/SliceLocation.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a class, abstract or concrete, that may declare a static `sliceLocation` member.
+ */
+export type SliceLocationDeclaringType = abstract new (...args: never[]) => unknown;
+
+function isSliceLocationShaped(value: unknown): value is { module: string, feature: string, slice: string } {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value as Record<string, unknown>;
+    return typeof candidate.module === 'string' && typeof candidate.feature === 'string' && typeof candidate.slice === 'string';
+}
+
+/**
+ * Represents where a command or query lives: the module, feature and slice resolved from its backend namespace.
+ * @remarks
+ * Generated proxies carry it as the static `sliceLocation` member, resolved from the same namespace mapping as the
+ * folder the proxy is generated to. When the namespace is too shallow for all three parts, the deepest parts are
+ * filled and the rest are empty strings, never null.
+ *
+ * The location is static metadata on the proxy class only. Instances carry no `sliceLocation` member, because a
+ * command or query may itself have a property named `SliceLocation`, which the generated accessor would clash with.
+ * Read it with {@link SliceLocation.of} for an instance or {@link SliceLocation.ofType} for a class.
+ */
+export class SliceLocation {
+    /**
+     * Gets a slice location where every part is empty.
+     */
+    static readonly empty: SliceLocation = new SliceLocation('', '', '');
+
+    /**
+     * Initializes a new instance of the {@link SliceLocation} class.
+     * @param module The module the slice belongs to.
+     * @param feature The feature the slice belongs to.
+     * @param slice The slice itself.
+     */
+    constructor(readonly module: string, readonly feature: string, readonly slice: string) {
+    }
+
+    /**
+     * Gets the slice location declared on the class of an instance, such as a generated command or query proxy.
+     * @param instance The instance to get for.
+     * @returns The declared {@link SliceLocation}, or {@link SliceLocation.empty} when the class declares none.
+     */
+    static of(instance: object): SliceLocation {
+        return SliceLocation.ofType(instance.constructor as SliceLocationDeclaringType);
+    }
+
+    /**
+     * Gets the slice location declared as the static `sliceLocation` member of a type, such as a generated command or query proxy class.
+     * @param type The type to get for.
+     * @returns The declared {@link SliceLocation}, or {@link SliceLocation.empty} when the type declares none.
+     */
+    static ofType(type: SliceLocationDeclaringType): SliceLocation {
+        const declared = (type as { sliceLocation?: unknown }).sliceLocation;
+        if (declared instanceof SliceLocation) {
+            return declared;
+        }
+
+        // A proxy compiled against another copy of @cratis/arc carries an instance of that copy's class.
+        if (isSliceLocationShaped(declared)) {
+            return new SliceLocation(declared.module, declared.feature, declared.slice);
+        }
+
+        return SliceLocation.empty;
+    }
+
+    /**
+     * Gets the parts that are set, joined with a forward slash.
+     * @returns The slice location as a path, for example `Billing/Invoices/Pay`.
+     */
+    toString(): string {
+        return [this.module, this.feature, this.slice].filter(part => part.length > 0).join('/');
+    }
+}

package/reflection/for_SliceLocation/when_converting_to_string.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SliceLocation } from '../SliceLocation.js';
+
+describe('when converting to string', () => {
+    it('should join all parts with a forward slash', () => new SliceLocation('Billing', 'Invoices', 'Pay').toString().should.equal('Billing/Invoices/Pay'));
+    it('should leave out empty parts', () => new SliceLocation('', 'Invoices', 'Pay').toString().should.equal('Invoices/Pay'));
+});

package/reflection/for_SliceLocation/when_getting_it_of_a_type.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SliceLocation } from '../SliceLocation.js';
+
+abstract class Declaring {
+    static readonly sliceLocation: SliceLocation = new SliceLocation('Billing', 'Invoices', 'Pay');
+}
+
+class NotDeclaring {
+}
+
+class DeclaringOneFromAnotherCopy {
+    static readonly sliceLocation = { module: 'Billing', feature: 'Invoices', slice: 'Refund' };
+}
+
+class DeclaringSomethingElse {
+    static readonly sliceLocation = 'Billing/Invoices/Pay';
+}
+
+describe('when getting it of a type', () => {
+    let declared: SliceLocation;
+    let undeclared: SliceLocation;
+    let notASliceLocation: SliceLocation;
+    let fromAnotherCopy: SliceLocation;
+
+    beforeEach(() => {
+        declared = SliceLocation.ofType(Declaring);
+        undeclared = SliceLocation.ofType(NotDeclaring);
+        notASliceLocation = SliceLocation.ofType(DeclaringSomethingElse);
+        fromAnotherCopy = SliceLocation.ofType(DeclaringOneFromAnotherCopy);
+    });
+
+    it('should return the declared slice location', () => declared.should.equal(Declaring.sliceLocation));
+    it('should return the empty slice location when the type declares none', () => undeclared.should.equal(SliceLocation.empty));
+    it('should return a slice location with the parts declared by another copy of the class', () => fromAnotherCopy.should.deep.equal(new SliceLocation('Billing', 'Invoices', 'Refund')));
+    it('should return the empty slice location when the static member is not a slice location', () => notASliceLocation.should.equal(SliceLocation.empty));
+});

package/reflection/for_SliceLocation/when_getting_it_of_an_instance_whose_class_declares_none.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SliceLocation } from '../SliceLocation.js';
+
+class NotDeclaring {
+}
+
+describe('when getting it of an instance whose class declares none', () => {
+    let result: SliceLocation;
+
+    beforeEach(() => {
+        result = SliceLocation.of(new NotDeclaring());
+    });
+
+    it('should return the empty slice location', () => result.should.equal(SliceLocation.empty));
+    it('should have an empty module', () => result.module.should.equal(''));
+    it('should have an empty feature', () => result.feature.should.equal(''));
+    it('should have an empty slice', () => result.slice.should.equal(''));
+});

package/reflection/for_SliceLocation/when_getting_it_of_an_instance_whose_class_declares_one.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SliceLocation } from '../SliceLocation.js';
+
+class Declaring {
+    static readonly sliceLocation: SliceLocation = new SliceLocation('Billing', 'Invoices', 'Pay');
+}
+
+describe('when getting it of an instance whose class declares one', () => {
+    let result: SliceLocation;
+
+    beforeEach(() => {
+        result = SliceLocation.of(new Declaring());
+    });
+
+    it('should return the declared slice location', () => result.should.equal(Declaring.sliceLocation));
+});

package/reflection/index.ts

@@ -5,3 +5,4 @@ export * from './IHaveParameters.js';
 export * from './ParameterDescriptor.js';
 export * from './ParametersHelper.js';
 export * from './PropertyDescriptor.js';
+export * from './SliceLocation.js';