@cratis/arc 18.0.0

package/commands/CommandResults.ts

@@ -0,0 +1,105 @@
+// 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 { ValidationResult } from '../validation/ValidationResult';
+import { Command } from './Command';
+import { CommandResult } from './CommandResult';
+import { ICommandResult } from './ICommandResult';
+
+type GetSpecificState = (commandResult: CommandResult) => boolean;
+
+
+export class CommandResults implements ICommandResult {
+    constructor(private readonly _commandResultsPerCommand: Map<Command, CommandResult>) {
+    }
+
+    /** @inheritdoc */
+    readonly correlationId: Guid = Guid.empty;
+
+    /** @inheritdoc */
+    get isSuccess(): boolean {
+        return this.isAnyFalse(_ => _.isSuccess);
+    }
+
+    /** @inheritdoc */
+    get isAuthorized(): boolean {
+        return this.isAnyFalse(_ => _.isAuthorized);
+    }
+
+    /** @inheritdoc */
+    get isValid(): boolean {
+        return this.isAnyFalse(_ => _.isValid);
+    }
+
+    /** @inheritdoc */
+    get hasExceptions(): boolean {
+        return this.isAnyTrue(_ => _.hasExceptions);
+    }
+
+    /** @inheritdoc */
+    get validationResults(): ValidationResult[] {
+        const errors: ValidationResult[] = [];
+
+        for (const result of this._commandResultsPerCommand.values()) {
+            result.validationResults.forEach(_ => errors.push(_));
+        }
+
+        return errors;
+    }
+
+    /** @inheritdoc */
+    get exceptionMessages(): string[] {
+        const messages: string[] = [];
+
+        for (const result of this._commandResultsPerCommand.values()) {
+            result.exceptionMessages.forEach(_ => messages.push(_));
+        }
+
+        return messages;
+    }
+
+    /** @inheritdoc */
+    get authorizationFailureReason(): string {
+        const reasons: string[] = [];
+
+        for (const result of this._commandResultsPerCommand.values()) {
+            if (result.authorizationFailureReason) {
+                reasons.push(result.authorizationFailureReason);
+            }
+        }
+
+        return reasons.join('; ');
+    }
+
+    /** @inheritdoc */
+    get exceptionStackTrace(): string {
+        let stackTraces = '';
+
+        for (const result of this._commandResultsPerCommand.values()) {
+            stackTraces = stackTraces + '\n' + result.exceptionStackTrace;
+        }
+
+        return stackTraces;
+
+    }
+
+
+    isAnyFalse(callback: GetSpecificState) {
+        for (const result of this._commandResultsPerCommand.values()) {
+            if (!callback(result)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    isAnyTrue(callback: GetSpecificState) {
+        for (const result of this._commandResultsPerCommand.values()) {
+            if (callback(result)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/commands/CommandValidator.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Validator } from '../validation/Validator';
+
+export type CommandPropertyValidators = { [key: string]: Validator; };
+
+/**
+ * Represents the command validator
+ */
+export abstract class CommandValidator {
+    abstract readonly properties: CommandPropertyValidators;
+
+    get isValid() {
+        return true;
+    }
+}

package/commands/ICommand.ts

@@ -0,0 +1,82 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ICanBeConfigured } from '../ICanBeConfigured';
+import { CommandResult } from './CommandResult';
+import { PropertyDescriptor } from '../reflection/PropertyDescriptor';
+
+/**
+ * Callback for when a property changes.
+ */
+export type PropertyChanged = (property: string) => void;
+
+/**
+ * Defines the base of a command.
+ */
+export interface ICommand<TCommandContent = object, TCommandResponse = object> extends ICanBeConfigured {
+    /**
+     * Gets the route information for the command.
+     */
+    readonly route: string;
+
+    /**
+     * Gets the property descriptors for the command.
+     */
+    readonly propertyDescriptors: PropertyDescriptor[];
+
+    /**
+     * Execute the {@link ICommand}.
+     * @param [args] Optional arguments for the command route - depends on whether or not the command needs arguments.
+     * @returns {CommandResult} for the execution.
+     */
+    execute(): Promise<CommandResult<TCommandResponse>>;
+
+    /**
+     * Validate the {@link ICommand} without executing it.
+     * @returns {CommandResult} for the validation containing authorization and validation status.
+     * @remarks
+     * This method performs authorization and validation checks on the server without executing the command handler.
+     * Use this for pre-flight validation to provide early feedback to users.
+     */
+    validate(): Promise<CommandResult<TCommandResponse>>;
+
+    /**
+     * Clear the command properties and reset them to their default values. This will also clear the initial values.
+     * This is used when the command is not needed anymore and should be cleared.
+     */
+    clear(): void;
+
+    /**
+     * Set the initial values for the command. This is used for tracking if there are changes to a command or not.
+     * @param {*} values Values to set.
+     */
+    setInitialValues(values: TCommandContent): void;
+
+    /**
+     * Set the initial values for the command to be the current value of the properties.
+     */
+    setInitialValuesFromCurrentValues(): void;
+
+    /**
+     * Revert any changes on the command.
+     */
+    revertChanges(): void;
+
+    /**
+     * Gets whether or not there are changes to any properties.
+     */
+    readonly hasChanges: boolean;
+
+    /**
+     * Notify about a property that has had its value changed.
+     * @param {string} property Name of property that changes.
+     */
+    propertyChanged(property: string): void;
+
+    /**
+     * Register callback that gets called when a property changes.
+     * @param {PropertyChanged} callback Callback to register.
+     * @param {*} thisArg The this arg to use when calling.
+     */
+    onPropertyChanged(callback: PropertyChanged, thisArg: object): void;
+}

package/commands/ICommandResult.ts

@@ -0,0 +1,60 @@
+// 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 { ValidationResult } from '../validation/ValidationResult';
+
+/**
+ * Defines the result from executing commands.
+ */
+ export interface ICommandResult<TResponse = object> {
+    /**
+     * Gets the correlation identifier associated with the executed command.
+     */
+     readonly correlationId: Guid;
+
+     /**
+      * Gets whether or not the command executed successfully.
+      */
+     readonly isSuccess: boolean;
+
+     /**
+      * Gets whether or not the command was authorized to execute.
+      */
+     readonly isAuthorized: boolean;
+
+     /**
+      * Gets whether or not the command is valid.
+      */
+     readonly isValid: boolean;
+
+     /**
+      * Gets whether or not there are any exceptions that occurred.
+      */
+     readonly hasExceptions: boolean;
+
+     /**
+      * Gets any validation errors. If this collection is empty, there are errors.
+      */
+     readonly validationResults: ValidationResult[];
+
+     /**
+      * Gets any exception messages that might have occurred.
+      */
+     readonly exceptionMessages: string[];
+
+     /**
+      * Gets the reason for authorization failure, if any.
+      */
+     readonly authorizationFailureReason: string;
+
+     /**
+      * Gets the stack trace if there was an exception.
+      */
+     readonly exceptionStackTrace: string;
+
+    /**
+     * Gets the response from the command, if any.
+     */
+     readonly response?: TResponse;
+}

package/commands/for_Command/CommandWithRouteParams.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 { Command } from '../Command';
+import { CommandValidator } from '../CommandValidator';
+import { PropertyDescriptor } from '../../reflection/PropertyDescriptor';
+
+export interface ICommandWithRouteParams {
+    id: string;
+    name: string;
+}
+
+export class CommandWithRouteParams extends Command<ICommandWithRouteParams> implements ICommandWithRouteParams {
+    validation!: CommandValidator;
+    route = '/api/items/{id}';
+    propertyDescriptors: PropertyDescriptor[] = [
+        new PropertyDescriptor('id', String),
+        new PropertyDescriptor('name', String)
+    ];
+
+    constructor() {
+        super(Object, false);
+    }
+
+    get requestParameters(): string[] {
+        return ['id'];
+    }
+    get properties(): string[] {
+        return ['id', 'name'];
+    }
+
+    id!: string;
+    name!: string;
+}

package/commands/for_Command/SomeCommand.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 { Command } from '../Command';
+import { CommandValidator } from '../CommandValidator';
+import { PropertyDescriptor } from '../../reflection/PropertyDescriptor';
+
+export interface ISomeCommand {
+    someProperty: string;
+}
+
+export class SomeCommand extends Command<ISomeCommand> implements ISomeCommand {
+    validation!: CommandValidator;
+    route = '';
+    propertyDescriptors: PropertyDescriptor[] = [
+        new PropertyDescriptor('someProperty', String)
+    ];
+
+    constructor() {
+        super(Object, false);
+    }
+
+    get requestParameters(): string[] {
+        return [];
+    }
+    get properties(): string[] {
+        return [
+            'someProperty'
+        ];
+    }
+
+    someProperty!: string;
+}
+

package/commands/for_Command/given/a_command.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 sinon from 'sinon';
+import { SomeCommand } from '../SomeCommand';
+
+export class a_command {
+    command: SomeCommand;
+    fetchStub: sinon.SinonStub;
+
+    constructor() {
+        this.command = new SomeCommand();
+        this.command.route = '/test-route';
+        this.command.setOrigin('http://localhost');
+        this.command.setApiBasePath('/api');
+        this.fetchStub = sinon.stub(globalThis, 'fetch');
+    }
+}

package/commands/for_Command/when_clearing_the_command.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SomeCommand } from './SomeCommand';
+
+describe('when clearing the command', () => {
+    const command = new SomeCommand();
+    command.setInitialValues({
+        someProperty: ''
+    });
+    command.someProperty = '42';
+    command.propertyChanged('someProperty');
+    command.clear();
+
+    it('should not have any changes', () => command.hasChanges.should.be.false);
+    it('should clear the property', () => (command.someProperty === undefined).should.be.true);
+});

package/commands/for_Command/when_executing/and_command_route_not_found.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 { a_command } from '../given/a_command';
+import { given } from '../../../given';
+import { CommandResult } from '../../CommandResult';
+
+describe("when executing and command route not found", given(a_command, context => {
+    let result: CommandResult<object>;
+
+    beforeEach(async () => {
+        context.fetchStub.resolves({
+            status: 404,
+            json: async () => ({})
+        });
+
+        result = await context.command.execute();
+    });
+
+    afterEach(() => {
+        context.fetchStub.restore();
+    });
+
+    it("should_return_failed_result", () => result.isSuccess.should.be.false);
+    it("should_have_exception_messages", () => (result.exceptionMessages.length > 0).should.be.true);
+}));

package/commands/for_Command/when_executing/and_fetch_throws_exception.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 { a_command } from '../given/a_command';
+import { given } from '../../../given';
+import { CommandResult } from '../../CommandResult';
+
+describe("when executing and fetch throws exception", given(a_command, context => {
+    let result: CommandResult<object>;
+
+    beforeEach(async () => {
+        context.fetchStub.rejects(new Error('Network error'));
+
+        result = await context.command.execute();
+    });
+
+    afterEach(() => {
+        context.fetchStub.restore();
+    });
+
+    it("should_return_failed_result", () => result.isSuccess.should.be.false);
+    it("should_include_error_message", () => result.exceptionMessages[0].should.contain('Error during server call'));
+    it("should_have_exception_messages", () => (result.exceptionMessages.length > 0).should.be.true);
+}));

package/commands/for_Command/when_executing/with_command_properties.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_command } from '../given/a_command';
+import { given } from '../../../given';
+
+describe("when executing with command properties", given(a_command, context => {
+    const responseData = {
+        correlationId: '12345678-1234-1234-1234-123456789012',
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        response: {}
+    };
+
+    beforeEach(async () => {
+        context.command.someProperty = 'test value';
+
+        context.fetchStub.resolves({
+            status: 200,
+            json: async () => responseData
+        });
+
+        await context.command.execute();
+    });
+
+    afterEach(() => {
+        context.fetchStub.restore();
+    });
+
+    it("should_include_command_properties_in_body", () => {
+        const call = context.fetchStub.getCall(0);
+        const body = JSON.parse(call.args[1].body);
+        body.someProperty.should.equal('test value');
+    });
+}));

package/commands/for_Command/when_executing/with_custom_http_headers.ts

@@ -0,0 +1,60 @@
+// 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 { SomeCommand } from '../SomeCommand';
+import { given } from '../../../given';
+
+describe("when executing with custom http headers", given(class {
+    command: SomeCommand;
+    fetchStub: sinon.SinonStub;
+
+    constructor() {
+        this.command = new SomeCommand();
+        this.command.route = '/test-route';
+        this.command.setOrigin('http://localhost');
+        this.command.setApiBasePath('/api');
+        this.command.setHttpHeadersCallback(() => ({
+            'X-Custom-Header': 'custom-value',
+            'Authorization': 'Bearer token123'
+        }));
+        this.fetchStub = sinon.stub(globalThis, 'fetch');
+    }
+}, context => {
+    const responseData = {
+        correlationId: '12345678-1234-1234-1234-123456789012',
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        response: {}
+    };
+
+    beforeEach(async () => {
+        context.fetchStub.resolves({
+            status: 200,
+            json: async () => responseData
+        });
+
+        await context.command.execute();
+    });
+
+    afterEach(() => {
+        context.fetchStub.restore();
+    });
+
+    it("should_include_custom_headers", () => {
+        const call = context.fetchStub.getCall(0);
+        call.args[1].headers['X-Custom-Header'].should.equal('custom-value');
+        call.args[1].headers['Authorization'].should.equal('Bearer token123');
+    });
+
+    it("should_include_default_headers", () => {
+        const call = context.fetchStub.getCall(0);
+        call.args[1].headers['Content-Type'].should.equal('application/json');
+        call.args[1].headers['Accept'].should.equal('application/json');
+    });
+}));

package/commands/for_Command/when_executing/with_microservice_header.ts

@@ -0,0 +1,55 @@
+// 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 { SomeCommand } from '../SomeCommand';
+import { given } from '../../../given';
+import { Globals } from '../../../Globals';
+
+describe("when executing with microservice header", given(class {
+    command: SomeCommand;
+    fetchStub: sinon.SinonStub;
+    originalMicroserviceHeader: string;
+
+    constructor() {
+        this.command = new SomeCommand();
+        this.command.route = '/test-route';
+        this.command.setOrigin('http://localhost');
+        this.command.setApiBasePath('/api');
+        this.command.setMicroservice('my-microservice');
+        this.fetchStub = sinon.stub(globalThis, 'fetch');
+        this.originalMicroserviceHeader = Globals.microserviceHttpHeader;
+        Globals.microserviceHttpHeader = 'X-Microservice-Id';
+    }
+}, context => {
+    const responseData = {
+        correlationId: '12345678-1234-1234-1234-123456789012',
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        response: {}
+    };
+
+    beforeEach(async () => {
+        context.fetchStub.resolves({
+            status: 200,
+            json: async () => responseData
+        });
+
+        await context.command.execute();
+    });
+
+    afterEach(() => {
+        context.fetchStub.restore();
+        Globals.microserviceHttpHeader = context.originalMicroserviceHeader;
+    });
+
+    it("should_include_microservice_header", () => {
+        const call = context.fetchStub.getCall(0);
+        call.args[1].headers['X-Microservice-Id'].should.equal('my-microservice');
+    });
+}));

package/commands/for_Command/when_executing/with_origin_and_api_base_path.ts

@@ -0,0 +1,51 @@
+// 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 { SomeCommand } from '../SomeCommand';
+import { given } from '../../../given';
+
+describe("when executing with origin and api base path", given(class {
+    command: SomeCommand;
+    fetchStub: sinon.SinonStub;
+
+    constructor() {
+        this.command = new SomeCommand();
+        this.command.route = '/items';
+        this.command.setOrigin('https://api.example.com');
+        this.command.setApiBasePath('/api/v1');
+        this.fetchStub = sinon.stub(globalThis, 'fetch');
+    }
+}, context => {
+    const responseData = {
+        correlationId: '12345678-1234-1234-1234-123456789012',
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        response: {}
+    };
+
+    beforeEach(async () => {
+        context.fetchStub.resolves({
+            status: 200,
+            json: async () => responseData
+        });
+
+        await context.command.execute();
+    });
+
+    afterEach(() => {
+        context.fetchStub.restore();
+    });
+
+    it("should_construct_url_with_origin_and_base_path", () => {
+        const call = context.fetchStub.getCall(0);
+        const url = call.args[0];
+        url.toString().should.contain('https://api.example.com');
+        url.toString().should.contain('/api/v1/items');
+    });
+}));