@cratis/arc 18.0.0

package/GetHttpHeaders.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a function that retrieves HTTP headers.
+ */
+export type GetHttpHeaders = () => HeadersInit;

package/Globals.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export interface IGlobals {
+    microservice: string;
+    microserviceHttpHeader: string;
+    microserviceWSQueryArgument: string;
+}
+
+export const Globals: IGlobals = {
+    microservice: '',
+    microserviceHttpHeader: 'x-cratis-microservice',
+    microserviceWSQueryArgument: 'x-cratis-microservice'
+};

package/ICanBeConfigured.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { GetHttpHeaders } from 'GetHttpHeaders';
+
+/**
+ * Represents the concept of something that can be configured.
+ */
+export interface ICanBeConfigured {
+    /**
+     * Set the microservice to be used for the query. This is passed along to the server to identify the microservice.
+     * @param microservice Name of microservice
+     */
+    setMicroservice(microservice: string);
+
+    /**
+     * Set the base path for the API to use for the query. This is used to prepend to the path to any fetch operation.
+     * @param apiBasePath Base path for the API
+     */
+    setApiBasePath(apiBasePath: string): void;
+
+    /**
+     * Set the origin to be used for the query. This is used to set the origin (scheme + host + port) for API calls.
+     * @param origin The origin to use.
+     */
+    setOrigin(origin: string): void;
+
+    /**
+     * Set the callback to call for getting additional Http headers for Web requests.
+     * @param callback Callback that gets called.
+     */
+    setHttpHeadersCallback(callback: GetHttpHeaders): void;
+}

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/UrlHelpers.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export class UrlHelpers {
+    /**
+     * Creates a URL from the given origin, API base path, and route.
+     * @param origin The origin of the request. If not provided, it defaults to the current document's origin.
+     * @param apiBasePath The base path for the API.
+     * @param route The specific route for the request.
+     * @returns The constructed URL.
+    */
+    static createUrlFrom(origin: string, apiBasePath: string, route: string): URL {
+        if ((!origin || origin.length === 0) && typeof document !== 'undefined') {
+            origin = document.location?.origin ?? '';
+        }
+
+        return new URL(route, `${origin}${apiBasePath}`);
+    }
+
+    /**
+     * Replaces route parameters in the route template with values from the parameters object.
+     * Returns both the updated route and the parameters that were not used in the route.
+     * @param route The route template with placeholders like {paramName}.
+     * @param parameters The parameters to replace in the route.
+     * @returns An object containing the updated route and unused parameters.
+     */
+    static replaceRouteParameters<T extends object>(route: string, parameters?: T): { route: string; unusedParameters: Partial<T> } {
+        if (!parameters) {
+            return { route, unusedParameters: {} };
+        }
+
+        let result = route;
+        const unusedParameters: Partial<T> = { ...parameters };
+
+        for (const [key, value] of Object.entries(parameters)) {
+            const pattern = new RegExp(`\\{${key}\\}`, 'gi');
+            const newRoute = result.replace(pattern, encodeURIComponent(String(value)));
+            
+            if (newRoute !== result) {
+                delete unusedParameters[key as keyof T];
+                result = newRoute;
+            }
+        }
+
+        return { route: result, unusedParameters };
+    }
+
+    /**
+     * Builds URLSearchParams from the given parameters and additional query parameters.
+     * @param unusedParameters Parameters that were not used in route replacement.
+     * @param additionalParams Additional query parameters to include.
+     * @returns URLSearchParams containing all parameters.
+     */
+    static buildQueryParams(unusedParameters: object, additionalParams?: Record<string, string | number>): URLSearchParams {
+        const queryParams = new URLSearchParams();
+
+        for (const [key, value] of Object.entries(unusedParameters)) {
+            if (value !== undefined && value !== null) {
+                queryParams.set(key, String(value));
+            }
+        }
+
+        if (additionalParams) {
+            for (const [key, value] of Object.entries(additionalParams)) {
+                queryParams.set(key, String(value));
+            }
+        }
+
+        return queryParams;
+    }
+}

package/commands/Command.ts

@@ -0,0 +1,209 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ICommand, PropertyChanged } from './ICommand';
+import { CommandResult } from "./CommandResult";
+import { CommandValidator } from './CommandValidator';
+import { Constructor, JsonSerializer } from '@cratis/fundamentals';
+import { Globals } from '../Globals';
+import { joinPaths } from '../joinPaths';
+import { UrlHelpers } from '../UrlHelpers';
+import { GetHttpHeaders } from '../GetHttpHeaders';
+import { PropertyDescriptor } from '../reflection/PropertyDescriptor';
+
+type Callback = {
+    callback: WeakRef<PropertyChanged>;
+    thisArg: WeakRef<object>;
+}
+
+/**
+ * Represents an implementation of {@link ICommand} that works with HTTP fetch.
+ */
+export abstract class Command<TCommandContent = object, TCommandResponse = object> implements ICommand<TCommandContent, TCommandResponse> {
+    private _microservice: string;
+    private _apiBasePath: string;
+    private _origin: string;
+    private _httpHeadersCallback: GetHttpHeaders;
+    abstract readonly route: string;
+    abstract readonly validation: CommandValidator;
+    abstract readonly propertyDescriptors: PropertyDescriptor[];
+    abstract get requestParameters(): string[];
+    abstract get properties(): string[];
+
+    private _initialValues: object = {};
+    private _hasChanges = false;
+    private _callbacks: Callback[] = [];
+
+    /**
+     * Initializes a new instance of the {@link Command<,>} class.
+     * @param _responseType Type of response.
+     * @param _isResponseTypeEnumerable Whether or not the response type is enumerable.
+     */
+    constructor(readonly _responseType: Constructor = Object, readonly _isResponseTypeEnumerable: boolean) {
+        this._microservice = Globals.microservice ?? '';
+        this._apiBasePath = '';
+        this._origin = '';
+        this._httpHeadersCallback = () => ({});
+    }
+
+    /** @inheritdoc */
+    setMicroservice(microservice: string) {
+        this._microservice = microservice;
+    }
+
+    /** @inheritdoc */
+    setApiBasePath(apiBasePath: string): void {
+        this._apiBasePath = apiBasePath;
+    }
+
+    /** @inheritdoc */
+    setOrigin(origin: string): void {
+        this._origin = origin;
+    }
+
+    /** @inheritdoc */
+    setHttpHeadersCallback(callback: GetHttpHeaders): void {
+        this._httpHeadersCallback = callback;
+    }
+
+    /** @inheritdoc */
+    async execute(): Promise<CommandResult<TCommandResponse>> {
+        let actualRoute = this.route;
+
+        if (this.requestParameters && this.requestParameters.length > 0) {
+            const payload = this.buildPayload();
+            const { route } = UrlHelpers.replaceRouteParameters(this.route, payload);
+            actualRoute = route;
+        }
+
+        const result = await this.performRequest(actualRoute, 'Command not found at route', 'Error during server call');
+        this.setInitialValuesFromCurrentValues();
+        return result;
+    }
+
+    /** @inheritdoc */
+    async validate(): Promise<CommandResult<TCommandResponse>> {
+        const actualRoute = `${this.route}/validate`;
+        return this.performRequest(actualRoute, 'Command validation endpoint not found at route', 'Error during validation call');
+    }
+
+    private buildPayload(): object {
+        const payload = {};
+        this.properties.forEach(property => {
+            payload[property] = this[property];
+        });
+        return payload;
+    }
+
+    private buildHeaders(): HeadersInit {
+        const customHeaders = this._httpHeadersCallback?.() ?? {};
+        const headers = {
+            ...customHeaders,
+            'Accept': 'application/json',
+            'Content-Type': 'application/json'
+        };
+
+        if (this._microservice?.length > 0) {
+            headers[Globals.microserviceHttpHeader] = this._microservice;
+        }
+
+        return headers;
+    }
+
+    private async performRequest(
+        route: string,
+        notFoundMessage: string,
+        errorMessage: string
+    ): Promise<CommandResult<TCommandResponse>> {
+        const payload = this.buildPayload();
+        const headers = this.buildHeaders();
+        const actualRoute = joinPaths(this._apiBasePath, route);
+        const url = UrlHelpers.createUrlFrom(this._origin, this._apiBasePath, actualRoute);
+
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JsonSerializer.serialize(payload)
+            });
+
+            if (response.status === 404) {
+                return CommandResult.failed([`${notFoundMessage} '${actualRoute}'`]) as CommandResult<TCommandResponse>;
+            }
+
+            const result = await response.json();
+            return new CommandResult(result, this._responseType, this._isResponseTypeEnumerable);
+        } catch (ex) {
+            return CommandResult.failed([`${errorMessage}: ${ex}`]) as CommandResult<TCommandResponse>;
+        }
+    }
+
+    /** @inheritdoc */
+    clear(): void {
+        this.properties.forEach(property => {
+            this[property] = undefined;
+        });
+        this._initialValues = {};
+        this._hasChanges = false;
+    }
+
+    /** @inheritdoc */
+    setInitialValues(values: TCommandContent) {
+        this.properties.forEach(property => {
+            if (Object.prototype.hasOwnProperty.call(values, property)) {
+                this._initialValues[property] = values[property];
+                this[property] = values[property];
+            }
+        });
+        this.updateHasChanges();
+    }
+
+    /** @inheritdoc */
+    setInitialValuesFromCurrentValues() {
+        this.properties.forEach(property => {
+            if (this[property]) {
+                this._initialValues[property] = this[property];
+            }
+        });
+        this.updateHasChanges();
+    }
+
+    /** @inheritdoc */
+    revertChanges(): void {
+        this.properties.forEach(property => {
+            this[property] = this._initialValues[property];
+        });
+    }
+
+    /** @inheritdoc */
+    get hasChanges() {
+        return this._hasChanges;
+    }
+
+    /** @inheritdoc */
+    propertyChanged(property: string) {
+        this.updateHasChanges();
+
+        this._callbacks.forEach(callbackContainer => {
+            const callback = callbackContainer.callback.deref();
+            const thisArg = callbackContainer.thisArg.deref();
+            if (callback && thisArg) {
+                callback.call(thisArg, property);
+            } else {
+                this._callbacks = this._callbacks.filter(_ => _.callback !== callbackContainer.callback);
+            }
+        });
+    }
+
+    /** @inheritdoc */
+    onPropertyChanged(callback: PropertyChanged, thisArg: object) {
+        this._callbacks.push({
+            callback: new WeakRef(callback),
+            thisArg: new WeakRef(thisArg)
+        });
+    }
+
+    private updateHasChanges() {
+        this._hasChanges = this.properties.some(property => this[property] !== this._initialValues[property]);
+    }
+}

package/commands/CommandResult.ts

@@ -0,0 +1,203 @@
+// 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 { ICommandResult } from './ICommandResult';
+import { ValidationResult } from '../validation/ValidationResult';
+import { Constructor, JsonSerializer } from '@cratis/fundamentals';
+
+/**
+ * Delegate type for the onSuccess callback.
+ */
+type OnSuccess = (<TResponse>(response: TResponse) => void) | (() => void);
+
+/**
+ * Delegate type for the onFailed callback.
+ */
+type OnFailed<TResponse> = ((commandResult: CommandResult<TResponse>) => void) | (() => void);
+
+/**
+ * Delegate type for the onException callback.
+ */
+type OnException = (messages: string[], stackTrace: string) => void;
+
+/**
+ * Delegate type for the onUnauthorized callback.
+ */
+type OnUnauthorized = () => void;
+
+/**
+ * Delegate type for the onValidationFailure callback.
+ */
+type OnValidationFailure = (validationResults: ValidationResult[]) => void;
+
+type ServerCommandResult = {
+    correlationId: string;
+    isSuccess: boolean;
+    isAuthorized: boolean;
+    isValid: boolean;
+    hasExceptions: boolean;
+    validationResults: {
+        severity: number;
+        message: string;
+        members: string[];
+        state: object;
+    }[];
+    exceptionMessages: string[];
+    exceptionStackTrace: string;
+    authorizationFailureReason: string;
+
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    response: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+}
+
+/**
+ * Represents the result from executing a {@link ICommand}.
+ */
+export class CommandResult<TResponse = object> implements ICommandResult<TResponse> {
+
+    static empty: CommandResult = new CommandResult({
+        correlationId: Guid.empty.toString(),
+        isSuccess: true,
+        isAuthorized: true,
+        isValid: true,
+        hasExceptions: false,
+        validationResults: [],
+        exceptionMessages: [],
+        exceptionStackTrace: '',
+        authorizationFailureReason: '',
+        response: null
+    }, Object, false);
+
+    static failed = (exceptionMessages: string[]): CommandResult => {
+        return new CommandResult({
+            correlationId: Guid.empty.toString(),
+            isSuccess: false,
+            isAuthorized: true,
+            isValid: true,
+            hasExceptions: true,
+            validationResults: [],
+            exceptionMessages: exceptionMessages,
+            exceptionStackTrace: '',
+            authorizationFailureReason: '',
+            response: null
+        }, Object, false);
+    };
+
+    /** @inheritdoc */
+    readonly correlationId: Guid;
+
+    /** @inheritdoc */
+    readonly isSuccess: boolean;
+
+    /** @inheritdoc */
+    readonly isAuthorized: boolean;
+
+    /** @inheritdoc */
+    readonly isValid: boolean;
+
+    /** @inheritdoc */
+    readonly hasExceptions: boolean;
+
+    /** @inheritdoc */
+    readonly validationResults: ValidationResult[];
+
+    /** @inheritdoc */
+    readonly exceptionMessages: string[];
+
+    /** @inheritdoc */
+    readonly exceptionStackTrace: string;
+
+    /** @inheritdoc */
+    readonly authorizationFailureReason: string;
+
+    /** @inheritdoc */
+    readonly response?: TResponse;
+
+    /**
+     * Creates an instance of command result.
+     * @param {*} result The JSON/any representation of the command result;
+     * @param {Constructor} responseInstanceType The {@see Constructor} that represents the type of response, if any. Defaults to {@see Object}.
+     * @param {boolean} isResponseTypeEnumerable Whether or not the response type is an enumerable or not.
+     */
+    constructor(result: ServerCommandResult, responseInstanceType: Constructor = Object, isResponseTypeEnumerable: boolean) {
+        this.correlationId = Guid.parse(result.correlationId);
+        this.isSuccess = result.isSuccess;
+        this.isAuthorized = result.isAuthorized;
+        this.isValid = result.isValid;
+        this.hasExceptions = result.hasExceptions;
+        this.validationResults = result.validationResults.map(_ => new ValidationResult(_.severity, _.message, _.members, _.state));
+        this.exceptionMessages = result.exceptionMessages;
+        this.exceptionStackTrace = result.exceptionStackTrace;
+        this.authorizationFailureReason = result.authorizationFailureReason;
+
+        if (result.response) {
+            if (isResponseTypeEnumerable) {
+                this.response = JsonSerializer.deserializeArrayFromInstance(responseInstanceType, result.response) as TResponse;
+            } else {
+                this.response = JsonSerializer.deserializeFromInstance(responseInstanceType, result.response) as TResponse;
+            }
+        }
+    }
+
+    /**
+     * Set up a callback for when the command was successful.
+     * @param {OnSuccess} callback The callback to call when the command was successful.
+     * @returns {CommandResult} The instance of the command result.
+     */
+    onSuccess(callback: OnSuccess): CommandResult<TResponse> {
+        if (this.isSuccess) {
+            callback(this.response as TResponse);
+        }
+        return this;
+    }
+
+    /**
+     * Set up a callback for when the command failed.
+     * @param {OnFailed} callback The callback to call when the command failed.
+     * @returns {CommandResult} The instance of the command result.
+     */
+    onFailed(callback: OnFailed<TResponse>): CommandResult<TResponse> {
+        if (!this.isSuccess) {
+            callback(this);
+        }
+        return this;
+    }
+
+    /**
+     * Set up a callback for when the command failed with an exception.
+     * @param {OnException} callback The callback to call when the command had an exception.
+     * @returns {CommandResult} The instance of the command result.
+     */
+    onException(callback: OnException): CommandResult<TResponse> {
+        if (this.hasExceptions) {
+            callback(this.exceptionMessages, this.exceptionStackTrace);
+        }
+        return this;
+    }
+
+    /**
+     * Set up a callback for when the command was unauthorized.
+     * @param {OnUnauthorized} callback The callback to call when the command was unauthorized.
+     * @returns {CommandResult} The instance of the command result.
+     */
+    onUnauthorized(callback: OnUnauthorized): CommandResult<TResponse> {
+        if (!this.isAuthorized) {
+            callback();
+        }
+        return this;
+    }
+
+    /**
+     * Set up a callback for when the command had validation errors.
+     * @param {OnSuccess} callback The callback to call when the command was invalid.
+     * @returns {CommandResult} The instance of the command result.
+     */
+    onValidationFailure(callback: OnValidationFailure): CommandResult<TResponse> {
+        if (!this.isValid) {
+            callback(this.validationResults);
+        }
+        return this;
+    }
+}