@cratis/arc.react 18.0.0

package/Arc.tsx

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandScope } from './commands';
+import { IdentityProvider } from './identity';
+import { Bindings } from './Bindings';
+import { ArcConfiguration, ArcContext } from './ArcContext';
+import { GetHttpHeaders } from '@cratis/arc';
+
+export interface ArcProps {
+    children?: JSX.Element | JSX.Element[];
+    microservice?: string;
+    development?: boolean;
+    origin?: string;
+    basePath?: string;
+    apiBasePath?: string;
+    httpHeadersCallback?: GetHttpHeaders;
+}
+
+export const Arc = (props: ArcProps) => {
+    const configuration: ArcConfiguration = {
+        microservice: props.microservice ?? '',
+        development: props.development ?? false,
+        origin: props.origin ?? '',
+        basePath: props.basePath ?? '',
+        apiBasePath: props.apiBasePath ?? '',
+        httpHeadersCallback: props.httpHeadersCallback
+    };
+
+    Bindings.initialize(
+        configuration.microservice,
+        configuration.apiBasePath,
+        configuration.origin,
+        configuration.httpHeadersCallback);
+
+    return (
+        <ArcContext.Provider value={configuration}>
+            <IdentityProvider httpHeadersCallback={props.httpHeadersCallback}>
+                <CommandScope>
+                    {props.children}
+                </CommandScope>
+            </IdentityProvider>
+        </ArcContext.Provider>);
+};

package/ArcContext.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { GetHttpHeaders, Globals } from '@cratis/arc';
+import React from 'react';
+
+export interface ArcConfiguration {
+    microservice: string;
+    development?: boolean
+    origin?: string;
+    basePath?: string;
+    apiBasePath?: string;
+    httpHeadersCallback?: GetHttpHeaders;
+}
+
+export const ArcContext = React.createContext<ArcConfiguration>({
+    microservice: Globals.microservice,
+    development: false,
+    origin: '',
+    basePath: '',
+    apiBasePath: '',
+    httpHeadersCallback: () => ({})
+});

package/Bindings.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.
+
+import { container } from 'tsyringe';
+import { IQueryProvider, QueryProvider } from '@cratis/arc/queries';
+import { Constructor } from '@cratis/fundamentals';
+import { WellKnownBindings } from './WellKnownBindings';
+import { GetHttpHeaders } from '@cratis/arc';
+
+export class Bindings {
+    static initialize(microservice: string, apiBasePath?: string, origin?: string, httpHeadersCallback?: GetHttpHeaders): void {
+        container.registerSingleton(WellKnownBindings.microservice, microservice);
+        container.register(IQueryProvider as Constructor<IQueryProvider>, { useValue: new QueryProvider(microservice, apiBasePath ?? '', origin ?? '', httpHeadersCallback ?? (() => ({}))) });
+    }
+}

package/README.md

@@ -0,0 +1,65 @@
+# Cratis Application Model
+
+## Packages / Deployables
+
+[![Nuget](https://img.shields.io/nuget/v/Cratis.Arc?logo=nuget)](http://nuget.org/packages/Cratis.Arc)
+[![NPM](https://img.shields.io/npm/v/@cratis/arc?label=@cratis/arc&logo=npm)](https://www.npmjs.com/package/@cratis/arc)
+
+## Builds
+
+[![.NET Build](https://github.com/cratis/arc/actions/workflows/dotnet-build.yml/badge.svg)](https://github.com/cratis/arc/actions/workflows/dotnet-build.yml)
+[![JavaScript Build](https://github.com/cratis/arc/actions/workflows/javascript-build.yml/badge.svg)](https://github.com/cratis/arc/actions/workflows/javascript-build.yml)
+[![Documentation site](https://github.com/Cratis/Documentation/actions/workflows/pages.yml/badge.svg)](https://github.com/Cratis/Documentation/actions/workflows/pages.yml)
+
+## Description
+
+The Cratis Application model represents an opinionated approach to building consistent applications based on the concepts behind CQRS.
+It offers extensions for different frameworks and is built on top of ASP.NET Core. One of the traits of Arc has is the
+bridging between the backend and the frontend. Arc provides a tool, called **ProxyGenerator** that generates TypeScript
+code for recognized artifacts matching the criteria of what is considered a **commmand** or a **query**.
+
+## Contributing
+
+If you want to jump into building this repository and possibly contributing, please refer to [contributing](./Documentation/contributing/index.md).
+
+### Prerequisites
+
+The following are prerequisites to work with this repository.
+
+* [.NET 8+](https://dotnet.microsoft.com/en-us/).
+* [Node 16+](https://nodejs.org/en)
+* [Yarn](https://yarnpkg.com)
+
+### Central Package Management
+
+This repository leverages [Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/Central-Package-Management), which
+means that all package versions are managed from a file at the root level called [Directory.Packages.props](./Directory.Packages.props).
+
+In addition there are also [Directory.Build.props](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory?view=vs-2022#directorybuildprops-and-directorybuildtargets) files for
+setting up common settings that are applied cross cuttingly.
+
+### Root package.json
+
+The `package.json` found at the root level defines all the workspaces. It is assumed
+
+All developer dependencies are defined in the top level `package.json`. The reason for this is to be able to provide global scripts
+for every package to use for easier maintenance.
+
+The `package.json` found at the top level contains scripts that can then be used in a child project for this to work properly.
+
+In a package, all you need to do is to define the scripts to use the global scripts in the `package.json´ of that project:
+
+```json
+{
+    "scripts": {
+        "prepublish": "yarn g:build",
+        "clean": "yarn g:clean",
+        "build": "yarn g:build",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci",
+        "test": "yarn g:test",
+        "ci": "yarn g:ci",
+        "up": "yarn g:up"
+    }
+}
+```

package/WellKnownBindings.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.
+
+/**
+ * Well-known IoC binding constants.
+ */
+export const WellKnownBindings = {
+    microservice: 'Microservice'
+};

package/commands/CommandScope.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import React, { useEffect, useState } from 'react';
+import { Command, CommandResult, CommandResults } from '@cratis/arc/commands';
+import { CommandScopeImplementation } from './CommandScopeImplementation';
+import { ICommandScope } from './ICommandScope';
+
+/* eslint-disable @typescript-eslint/no-empty-function */
+const defaultCommandScopeContext: ICommandScope = {
+    addCommand: () => { },
+    execute: async () => {
+        return new CommandResults(new Map());
+    },
+    hasChanges: false,
+    revertChanges: () => { }
+};
+/* eslint-enable @typescript-eslint/no-empty-function */
+
+export const CommandScopeContext = React.createContext<ICommandScope>(defaultCommandScopeContext);
+
+export type CommandScopeChanged = (hasChanges: boolean) => void;
+export type CommandScopeExecute = () => Promise<Map<Command, CommandResult>>;
+
+export type AddCommand = (command: Command) => void;
+
+export interface ICommandScopeProps {
+    children?: JSX.Element | JSX.Element[];
+    setHasChanges?: CommandScopeChanged;
+}
+
+export const CommandScope = (props: ICommandScopeProps) => {
+    const [hasChanges, setHasChanges] = useState(false);
+    const [commandScope, setCommandScope] = useState<ICommandScope>(defaultCommandScopeContext);
+
+    useEffect(() => {
+        const commandScopeImplementation = new CommandScopeImplementation((value) => {
+            setHasChanges(value);
+        });
+        setCommandScope(commandScopeImplementation);
+    }, []);
+
+    if (commandScope) {
+        commandScope.hasChanges = hasChanges;
+    }
+
+    return (
+        <CommandScopeContext.Provider value={{
+            addCommand: (command) => commandScope!.addCommand(command),
+            execute: () => commandScope.execute(),
+            revertChanges: () => commandScope.revertChanges(),
+            hasChanges
+        }}>
+            {props.children}
+        </CommandScopeContext.Provider>
+    );
+};

package/commands/CommandScopeImplementation.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import React from 'react';
+import { ICommand, CommandResults } from '@cratis/arc/commands';
+import { ICommandScope } from './ICommandScope';
+
+
+/**
+ * Represents an implementation of {@link ICommandScope}.
+ */
+export class CommandScopeImplementation implements ICommandScope {
+    private _commands: ICommand[] = [];
+    private _hasChanges = false;
+
+    constructor(private readonly _setHasChanges: React.Dispatch<React.SetStateAction<boolean>>) {
+    }
+
+    /** @inheritdoc */
+    get hasChanges(): boolean {
+        return this._hasChanges;
+    }
+
+    set hasChanges(value: boolean) {
+        this._hasChanges = value;
+    }
+
+    /** @inheritdoc */
+    addCommand(command: ICommand): void {
+        if (this._commands.some(_ => _ == command)) {
+            return;
+        }
+
+        this._commands.push(command);
+        this.evaluateHasChanges();
+        command.onPropertyChanged(this.evaluateHasChanges, this);
+    }
+
+    /** @inheritdoc */
+    async execute(): Promise<CommandResults> {
+        const commandsToCommandResult = new Map();
+
+        for (const command of this._commands.filter(_ => _.hasChanges === true)) {
+            const commandResult = await command.execute();
+            commandsToCommandResult.set(command, commandResult);
+        }
+        this.evaluateHasChanges();
+        return new CommandResults(commandsToCommandResult);
+    }
+
+    /** @inheritdoc */
+    revertChanges() {
+        this._commands.forEach(command => command.revertChanges());
+        this.evaluateHasChanges();
+    }
+
+    private evaluateHasChanges() {
+        let hasCommandChanges = false;
+        this._commands.forEach(command => {
+            if (command.hasChanges) {
+                hasCommandChanges = true;
+            }
+        });
+
+        this._hasChanges = hasCommandChanges;
+        this._setHasChanges(hasCommandChanges);
+    }
+}

package/commands/ICommandScope.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 { ICommand, CommandResults } from '@cratis/arc/commands';
+
+/**
+ * Defines the system for tracking commands in a scope.
+ */
+export interface ICommandScope {
+    /**
+     * Gets or sets whether or not there are any changes in the context.
+     */
+    hasChanges: boolean;
+
+    /**
+     * Add a command for tracking in the scope.
+     * @param {ICommand} command Command to add.
+     */
+    addCommand(command: ICommand): void;
+
+    /**
+     * Execute all commands with changes.
+     * @returns {Promise<CommandResults>} Command results per command that was executed.
+     */
+    execute(): Promise<CommandResults>;
+
+    /**
+     * Revert any changes for commands in scope.
+     */
+    revertChanges(): void;
+}

package/commands/for_CommandScopeImplementation/FakeCommand.ts

@@ -0,0 +1,59 @@
+// 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 { CommandResult, ICommand, PropertyChanged } from '@cratis/arc/commands';
+import { PropertyDescriptor } from '@cratis/arc/reflection';
+
+/* eslint-disable */
+
+export class FakeCommand implements ICommand {
+    route = '';
+    propertyDescriptors: PropertyDescriptor[] = [];
+    private _hasChanges: boolean;
+
+    constructor(hasChanges: boolean) {
+        this._hasChanges = hasChanges;
+        this.execute = sinon.fake(() => {
+            this._hasChanges = false;
+            return new Promise<CommandResult>(resolve => {
+                resolve(CommandResult.empty);
+            });
+        });
+        this.setInitialValues = sinon.stub();
+        this.setInitialValues = sinon.stub();
+        this.propertyChanged = sinon.stub();
+        this.onPropertyChanged = sinon.stub();
+        this.revertChanges = sinon.fake(() => {
+            this._hasChanges = false;
+        });
+    }
+
+    get hasChanges() {
+        return this._hasChanges;
+    }
+
+    revertChanges(): void {
+        throw new Error('Method not implemented.');
+    }
+
+    execute(): Promise<CommandResult> {
+        throw new Error('Method not implemented.');
+    }
+    setInitialValues(values: {}): void {
+        throw new Error('Method not implemented.');
+    }
+    setInitialValuesFromCurrentValues(): void {
+        throw new Error('Method not implemented.');
+    }
+    propertyChanged(property: string): void {
+        throw new Error('Method not implemented.');
+    }
+    onPropertyChanged(callback: PropertyChanged, thisArg: any): void {
+        throw new Error('Method not implemented.');
+    }
+
+    setMicroservice(microservice: string) {
+        throw new Error('Method not implemented.');
+    }
+}

package/commands/for_CommandScopeImplementation/when_executing_with_three_commands_were_two_having_changes.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 { SinonStub } from 'sinon';
+import { CommandScopeImplementation } from '../CommandScopeImplementation';
+import { FakeCommand } from './FakeCommand';
+
+describe('when executing with three commands were two having changes', async () => {
+    const scope = new CommandScopeImplementation(() => {});
+
+    const firstCommand = new FakeCommand(true);
+    const secondCommand = new FakeCommand(false);
+    const thirdCommand = new FakeCommand(true);
+
+    scope.addCommand(firstCommand);
+    scope.addCommand(secondCommand);
+    scope.addCommand(thirdCommand);
+
+    await scope.execute();
+
+    it('should call execute on first command', () => (firstCommand.execute as SinonStub).called.should.be.true);
+    it('should not call execute on second command', () => (secondCommand.execute as SinonStub).called.should.be.false);
+    it('should call execute on third command', () => (thirdCommand.execute as SinonStub).called.should.be.true);
+    it('should not have any changes', () => scope.hasChanges.should.be.false);
+});

package/commands/for_CommandScopeImplementation/when_none_of_the_added_commands_has_changes.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandScopeImplementation } from '../CommandScopeImplementation';
+import { FakeCommand } from './FakeCommand';
+
+describe('when none of the added commands has changes', () => {
+    const scope = new CommandScopeImplementation(() => {});
+
+    const firstCommand = new FakeCommand(false);
+    const secondCommand = new FakeCommand(false);
+    const thirdCommand = new FakeCommand(false);
+
+    scope.addCommand(firstCommand);
+    scope.addCommand(secondCommand);
+    scope.addCommand(thirdCommand);
+
+    it('should not have changes', () => scope.hasChanges.should.be.false);
+});

package/commands/for_CommandScopeImplementation/when_one_of_the_added_commands_has_changes.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandScopeImplementation } from '../CommandScopeImplementation';
+import { FakeCommand } from './FakeCommand';
+
+describe('when one of the added commands has changes', () => {
+    const scope = new CommandScopeImplementation(() => {});
+
+    const firstCommand = new FakeCommand(false);
+    const secondCommand = new FakeCommand(true);
+    const thirdCommand = new FakeCommand(false);
+
+    scope.addCommand(firstCommand);
+    scope.addCommand(secondCommand);
+    scope.addCommand(thirdCommand);
+
+    it('should have changes', () => scope.hasChanges.should.be.true);
+});

package/commands/for_CommandScopeImplementation/when_property_changes_on_added_command.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 sinon from 'sinon';
+import { CommandScopeImplementation } from '../CommandScopeImplementation';
+import { PropertyChanged } from '@cratis/arc/commands';
+import { FakeCommand } from './FakeCommand';
+
+describe('when property changes on added command', () => {
+    const setHasChanges = sinon.stub();
+    const scope = new CommandScopeImplementation(setHasChanges);
+    let callbackToCall: PropertyChanged;
+    let thisArgForCallback: object = {};
+
+    const command = new FakeCommand(true);
+    command.onPropertyChanged = (callback: PropertyChanged, thisArg: object): void => {
+        callbackToCall = callback;
+        thisArgForCallback = thisArg;
+    };
+
+    scope.addCommand(command);
+
+    callbackToCall!.call(thisArgForCallback, '');
+
+    it('should call set has changes', () => setHasChanges.called.should.be.true);
+});

package/commands/for_CommandScopeImplementation/when_reverting_with_three_commands_were_two_having_changes.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 { SinonStub } from 'sinon';
+import { CommandScopeImplementation } from '../CommandScopeImplementation';
+import { FakeCommand } from './FakeCommand';
+
+describe('when reverting with three commands were two having changes', () => {
+    const scope = new CommandScopeImplementation(() => {});
+
+    const firstCommand = new FakeCommand(true);
+    const secondCommand = new FakeCommand(false);
+    const thirdCommand = new FakeCommand(true);
+
+    scope.addCommand(firstCommand);
+    scope.addCommand(secondCommand);
+    scope.addCommand(thirdCommand);
+
+    scope.revertChanges();
+
+    it('should call revert on first command', () => (firstCommand.revertChanges as SinonStub).called.should.be.true);
+    it('should call revert on second command', () => (secondCommand.revertChanges as SinonStub).called.should.be.true);
+    it('should call revert on third command', () => (thirdCommand.revertChanges as SinonStub).called.should.be.true);
+    it('should not have any changes', () => scope.hasChanges.should.be.false);
+});

package/commands/for_CommandScopeImplementation/when_there_are_no_commands.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandScopeImplementation } from '../CommandScopeImplementation';
+
+describe('when there are no commands', () => {
+    const scope = new CommandScopeImplementation(() => {});
+
+    it('should have no changes', () => scope.hasChanges.should.be.false);
+});

package/commands/for_useCommand/FakeCommand.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 { Command, CommandValidator } from '@cratis/applications/commands';
+import { PropertyDescriptor } from '@cratis/applications/reflection';
+
+export interface FakeCommandContent {
+    someProperty?: string;
+    anotherProperty?: number;
+}
+
+export class FakeCommand extends Command<FakeCommandContent> {
+    readonly route = '/api/fake-command';
+    readonly validation = {} as CommandValidator;
+    readonly propertyDescriptors: PropertyDescriptor[] = [];
+
+    someProperty?: string;
+    anotherProperty?: number;
+
+    get requestParameters(): string[] {
+        return [];
+    }
+
+    get properties(): string[] {
+        return ['someProperty', 'anotherProperty'];
+    }
+
+    constructor() {
+        super(Object, false);
+    }
+}

package/commands/for_useCommand/when_creating_instance.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import React from 'react';
+import { render } from '@testing-library/react';
+import { useCommand } from '../useCommand';
+import { FakeCommand } from './FakeCommand';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+
+describe('when creating instance', () => {
+    let capturedCommand: FakeCommand | null = null;
+
+    const TestComponent = () => {
+        const [command] = useCommand(FakeCommand);
+        capturedCommand = command;
+        return React.createElement('div', null, 'Test');
+    };
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice',
+        apiBasePath: '/api',
+        origin: 'https://example.com',
+        httpHeadersCallback: () => ({ 'X-Custom-Header': 'custom-value' })
+    };
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(TestComponent)
+        )
+    );
+
+    it('should set microservice from context', () => capturedCommand!['_microservice'].should.equal('test-microservice'));
+    it('should set api base path from context', () => capturedCommand!['_apiBasePath'].should.equal('/api'));
+    it('should set origin from context', () => capturedCommand!['_origin'].should.equal('https://example.com'));
+    it('should set http headers callback from context', () => {
+        const headers = capturedCommand!['_httpHeadersCallback']();
+        headers.should.deep.equal({ 'X-Custom-Header': 'custom-value' });
+    });
+});

package/commands/for_useCommand/when_creating_instance_with_initial_values.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 React from 'react';
+import { render } from '@testing-library/react';
+import { useCommand } from '../useCommand';
+import { FakeCommand, FakeCommandContent } from './FakeCommand';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+
+describe('when creating instance with initial values', () => {
+    let capturedCommand: FakeCommand | null = null;
+
+    const initialValues: FakeCommandContent = {
+        someProperty: 'initial-value',
+        anotherProperty: 42
+    };
+
+    const TestComponent = () => {
+        const [command] = useCommand(FakeCommand, initialValues);
+        capturedCommand = command;
+        return React.createElement('div', null, 'Test');
+    };
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice'
+    };
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(TestComponent)
+        )
+    );
+
+    it('should set someProperty from initial values', () => capturedCommand!.someProperty!.should.equal('initial-value'));
+    it('should set anotherProperty from initial values', () => capturedCommand!.anotherProperty!.should.equal(42));
+});

package/commands/for_useCommand/when_creating_instance_without_optional_context_values.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 React from 'react';
+import { render } from '@testing-library/react';
+import { useCommand } from '../useCommand';
+import { FakeCommand } from './FakeCommand';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+
+describe('when creating instance without optional context values', () => {
+    let capturedCommand: FakeCommand | null = null;
+
+    const TestComponent = () => {
+        const [command] = useCommand(FakeCommand);
+        capturedCommand = command;
+        return React.createElement('div', null, 'Test');
+    };
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice'
+    };
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(TestComponent)
+        )
+    );
+
+    it('should set api base path to empty string', () => capturedCommand!['_apiBasePath'].should.equal(''));
+    it('should set origin to empty string', () => capturedCommand!['_origin'].should.equal(''));
+    it('should set http headers callback to return empty object', () => {
+        const headers = capturedCommand!['_httpHeadersCallback']();
+        headers.should.deep.equal({});
+    });
+});