@cratis/arc.react 18.0.0

package/index.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 * as commands from './commands';
+import * as dialogs from './dialogs';
+import * as identity from './identity';
+import * as queries from './queries';
+
+export * from './Arc';
+export * from './ArcContext';
+export * from './WellKnownBindings';
+
+export {
+    commands,
+    dialogs,
+    identity,
+    queries
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+    "name": "@cratis/arc.react",
+    "version": "18.0.0",
+    "description": "",
+    "author": "Cratis",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/cratis/arc.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "**/*.ts",
+        "**/*.tsx"
+    ],
+    "type": "module",
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/esm/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/esm/index.d.ts",
+            "require": "./dist/cjs/index.js",
+            "import": "./dist/esm/index.js"
+        },
+        "./commands": {
+            "types": "./dist/esm/commands/index.d.ts",
+            "require": "./dist/cjs/commands/index.js",
+            "import": "./dist/esm/commands/index.js"
+        },
+        "./queries": {
+            "types": "./dist/esm/queries/index.d.ts",
+            "require": "./dist/cjs/queries/index.js",
+            "import": "./dist/esm/queries/index.js"
+        },
+        "./dialogs": {
+            "types": "./dist/esm/dialogs/index.js",
+            "require": "./dist/cjs/dialogs/index.js",
+            "import": "./dist/esm/dialogs/index.js"
+        },
+        "./identity": {
+            "types": "./dist/esm/identity/index.d.ts",
+            "require": "./dist/cjs/identity/index.js",
+            "import": "./dist/esm/identity/index.js"
+        }
+    },
+    "scripts": {
+        "prepare": "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"
+    },
+    "dependencies": {
+        "@cratis/arc": "18.0.0",
+        "@cratis/fundamentals": "^7.2.3",
+        "tsyringe": "^4.10.0"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+    }
+}

package/queries/SetPage.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.
+
+/**
+ * Delegate type for setting the page in the context of the {@link useQueryWithPaging} or {@link useObservableQueryWithPaging} hooks.
+ */
+export type SetPage = (page: number) => Promise<void>;

package/queries/SetPageSize.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.
+
+/**
+ * Delegate type for setting the page size in the context of the {@link useQueryWithPaging} or {@link useObservableQueryWithPaging} hooks.
+ */
+export type SetPageSize = (pageSize: number) => Promise<void>;

package/queries/SetSorting.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 { Sorting } from '@cratis/arc/queries';
+
+/**
+ * Delegate type for setting the sorting in the context of the {@link useQuery}, {@link useQueryWithPaging}, {@link useObservableQuery} or {@link useObservableQueryWithPaging} hooks.
+ */
+export type SetSorting = (sorting: Sorting) => Promise<void>;

package/queries/for_useQuery/FakeQuery.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 { QueryFor } from '@cratis/applications/queries';
+import { ParameterDescriptor } from '@cratis/applications/reflection';
+
+export interface FakeQueryResult {
+    id: string;
+    name: string;
+}
+
+export class FakeQuery extends QueryFor<FakeQueryResult[]> {
+    readonly route = '/api/fake-query';
+    readonly parameterDescriptors: ParameterDescriptor[] = [];
+
+    get requiredRequestParameters(): string[] {
+        return [];
+    }
+
+    defaultValue: FakeQueryResult[] = [];
+
+    constructor() {
+        super(Object, true);
+    }
+}

package/queries/for_useQuery/when_creating_instance.ts

@@ -0,0 +1,63 @@
+// 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 sinon from 'sinon';
+import { useQuery } from '../useQuery';
+import { FakeQuery } from './FakeQuery';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+describe('when creating instance', () => {
+    let fetchStub: sinon.SinonStub;
+    let queryInstance: FakeQuery | null = null;
+
+    const captureInstance = (instance: FakeQuery) => {
+        queryInstance = instance;
+    };
+
+    beforeEach(() => {
+        fetchStub = sinon.stub(global, 'fetch').resolves({
+            json: async () => ({ data: [], isSuccess: true, isAuthorized: true, isValid: true, hasExceptions: false, validationResults: [], exceptionMessages: [], exceptionStackTrace: '' })
+        } as Response);
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice',
+        apiBasePath: '/api',
+        origin: 'https://example.com',
+        httpHeadersCallback: () => ({ 'X-Custom-Header': 'custom-value' })
+    };
+
+    class SpyQuery extends FakeQuery {
+        constructor() {
+            super();
+            captureInstance(this);
+        }
+    }
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(() => {
+                useQuery(SpyQuery);
+                return React.createElement('div', null, 'Test');
+            })
+        )
+    );
+
+    it('should set microservice from context', () => ((queryInstance as any)._microservice).should.equal('test-microservice'));
+    it('should set api base path from context', () => ((queryInstance as any)._apiBasePath).should.equal('/api'));
+    it('should set origin from context', () => ((queryInstance as any)._origin).should.equal('https://example.com'));
+    it('should set http headers callback from context', () => {
+        const headers = (queryInstance as any)._httpHeadersCallback();
+        headers.should.deep.equal({ 'X-Custom-Header': 'custom-value' });
+    });
+});

package/queries/for_useQuery/when_creating_instance_with_sorting.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 React from 'react';
+import { render } from '@testing-library/react';
+import sinon from 'sinon';
+import { useQuery } from '../useQuery';
+import { FakeQuery } from './FakeQuery';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+import { Sorting } from '@cratis/applications/queries';
+
+describe('when creating instance with sorting', () => {
+    let fetchStub: sinon.SinonStub;
+    let queryInstance: FakeQuery | null = null;
+
+    const captureInstance = (instance: FakeQuery) => {
+        queryInstance = instance;
+    };
+
+    beforeEach(() => {
+        fetchStub = sinon.stub(global, 'fetch').resolves({
+            json: async () => ({ data: [], isSuccess: true, isAuthorized: true, isValid: true, hasExceptions: false, validationResults: [], exceptionMessages: [], exceptionStackTrace: '' })
+        } as Response);
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice'
+    };
+
+    const sorting = new Sorting('name', 1);
+    
+    class SpyQuery extends FakeQuery {
+        constructor() {
+            super();
+            captureInstance(this);
+        }
+    }
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(() => {
+                useQuery(SpyQuery, undefined, sorting);
+                return React.createElement('div', null, 'Test');
+            })
+        )
+    );
+
+    it('should set sorting on the query', () => queryInstance!.sorting.should.equal(sorting));
+});

package/queries/for_useQuery/when_creating_instance_without_optional_context_values.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 React from 'react';
+import { render } from '@testing-library/react';
+import sinon from 'sinon';
+import { useQuery } from '../useQuery';
+import { FakeQuery } from './FakeQuery';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+describe('when creating instance without optional context values', () => {
+    let fetchStub: sinon.SinonStub;
+    let queryInstance: FakeQuery | null = null;
+
+    const captureInstance = (instance: FakeQuery) => {
+        queryInstance = instance;
+    };
+
+    beforeEach(() => {
+        fetchStub = sinon.stub(global, 'fetch').resolves({
+            json: async () => ({ data: [], isSuccess: true, isAuthorized: true, isValid: true, hasExceptions: false, validationResults: [], exceptionMessages: [], exceptionStackTrace: '' })
+        } as Response);
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice'
+    };
+
+    class SpyQuery extends FakeQuery {
+        constructor() {
+            super();
+            captureInstance(this);
+        }
+    }
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(() => {
+                useQuery(SpyQuery);
+                return React.createElement('div', null, 'Test');
+            })
+        )
+    );
+
+    it('should set api base path to empty string', () => ((queryInstance as any)._apiBasePath).should.equal(''));
+    it('should set origin to empty string', () => ((queryInstance as any)._origin).should.equal(''));
+    it('should set http headers callback to return empty object', () => {
+        const headers = (queryInstance as any)._httpHeadersCallback();
+        headers.should.deep.equal({});
+    });
+});

package/queries/for_useQueryWithPaging/when_creating_instance_with_paging.ts

@@ -0,0 +1,67 @@
+// 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 sinon from 'sinon';
+import { useQueryWithPaging } from '../useQuery';
+import { FakeQuery } from '../for_useQuery/FakeQuery';
+import { ArcContext, ArcConfiguration } from '../../ArcContext';
+import { Paging } from '@cratis/applications/queries';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+describe('when creating instance with paging', () => {
+    let fetchStub: sinon.SinonStub;
+    let queryInstance: FakeQuery | null = null;
+
+    const captureInstance = (instance: FakeQuery) => {
+        queryInstance = instance;
+    };
+
+    beforeEach(() => {
+        fetchStub = sinon.stub(global, 'fetch').resolves({
+            json: async () => ({ data: [], isSuccess: true, isAuthorized: true, isValid: true, hasExceptions: false, validationResults: [], exceptionMessages: [], exceptionStackTrace: '' })
+        } as Response);
+    });
+
+    afterEach(() => {
+        fetchStub.restore();
+    });
+
+    const config: ArcConfiguration = {
+        microservice: 'test-microservice',
+        apiBasePath: '/api',
+        origin: 'https://example.com',
+        httpHeadersCallback: () => ({ 'X-Custom-Header': 'custom-value' })
+    };
+
+    const paging = new Paging(1, 10);
+    
+    class SpyQuery extends FakeQuery {
+        constructor() {
+            super();
+            captureInstance(this);
+        }
+    }
+
+    render(
+        React.createElement(
+            ArcContext.Provider,
+            { value: config },
+            React.createElement(() => {
+                useQueryWithPaging(SpyQuery, paging);
+                return React.createElement('div', null, 'Test');
+            })
+        )
+    );
+
+    it('should set paging on the query', () => queryInstance!.paging.should.equal(paging));
+    it('should set microservice from context', () => ((queryInstance as any)._microservice).should.equal('test-microservice'));
+    it('should set api base path from context', () => ((queryInstance as any)._apiBasePath).should.equal('/api'));
+    it('should set origin from context', () => ((queryInstance as any)._origin).should.equal('https://example.com'));
+    it('should set http headers callback from context', () => {
+        const headers = (queryInstance as any)._httpHeadersCallback();
+        headers.should.deep.equal({ 'X-Custom-Header': 'custom-value' });
+    });
+});

package/queries/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './SetPage';
+export * from './SetPageSize';
+export * from './SetSorting';
+export * from './useObservableQuery';
+export * from './useQuery';

package/queries/useObservableQuery.ts

@@ -0,0 +1,83 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryResultWithState, IObservableQueryFor, Sorting, Paging } from '@cratis/arc/queries';
+import { Constructor } from '@cratis/fundamentals';
+import { useState, useEffect, useContext, useRef, useMemo } from 'react';
+import { SetSorting } from './SetSorting';
+import { SetPage } from './SetPage';
+import { SetPageSize } from './SetPageSize';
+import { ArcContext } from '../ArcContext';
+
+function useObservableQueryInternal<TDataType, TQuery extends IObservableQueryFor<TDataType>, TArguments = object>(query: Constructor<TQuery>, sorting?: Sorting, paging?: Paging, args?: TArguments):
+    [QueryResultWithState<TDataType>, SetSorting, SetPage, SetPageSize] {
+    const [currentPaging, setCurrentPaging] = useState<Paging>(paging ?? Paging.noPaging);
+    const [currentSorting, setCurrentSorting] = useState<Sorting>(sorting ?? Sorting.none);
+    const arc = useContext(ArcContext);
+    const queryInstance = useRef<TQuery | null>(null);
+
+    queryInstance.current = useMemo(() => {
+        const instance = new query() as TQuery;
+        instance.paging = currentPaging;
+        instance.sorting = currentSorting;
+        instance.setMicroservice(arc.microservice);
+        instance.setApiBasePath(arc.apiBasePath ?? '');
+        instance.setOrigin(arc.origin ?? '');
+        return instance;
+    }, [currentPaging, currentSorting]);
+
+    const [result, setResult] = useState<QueryResultWithState<TDataType>>(QueryResultWithState.empty(queryInstance.current.defaultValue));
+    const argumentsDependency = queryInstance.current.requiredRequestParameters.map(_ => args?.[_]);
+
+    useEffect(() => {
+        const subscription = queryInstance.current!.subscribe(response => {
+            setResult(QueryResultWithState.fromQueryResult(response, false));
+        }, args as object);
+
+        return () => {
+            subscription.unsubscribe();
+        };
+    }, [...argumentsDependency, ...[currentPaging, currentSorting]]);
+
+    return [
+        result,
+        async (sorting: Sorting) => {
+            setCurrentSorting(sorting);
+        },
+        async (page: number) => {
+            setCurrentPaging(new Paging(page, currentPaging.pageSize));
+        },
+        async (pageSize: number) => {
+            setCurrentPaging(new Paging(currentPaging.page, pageSize));
+        }];
+}
+
+/**
+ * React hook for working with {@link IObservableQueryFor} within the state management of React.
+ * @template TDataType Type of model the query is for.
+ * @template TQuery Type of observable query to use.
+ * @template TArguments Optional: Arguments for the query, if any
+ * @param query Query type constructor.
+ * @param args Optional: Arguments for the query, if any
+ * @returns Tuple of {@link QueryResultWithState} and a {@link PerformQuery} delegate.
+ */
+export function useObservableQuery<TDataType, TQuery extends IObservableQueryFor<TDataType>, TArguments = object>(query: Constructor<TQuery>, args?: TArguments, sorting?: Sorting):
+    [QueryResultWithState<TDataType>, SetSorting] {
+    const [result, setSorting] = useObservableQueryInternal<TDataType, TQuery, TArguments>(query, sorting, Paging.noPaging, args);
+    return [result, setSorting];
+}
+
+/**
+ * React hook for working with {@link IObservableQueryFor} within the state management of React for queries with paging.
+ * @template TDataType Type of model the query is for.
+ * @template TQuery Type of observable query to use.
+ * @template TArguments Optional: Arguments for the query, if any
+ * @param query Query type constructor.
+ * @param args Optional: Arguments for the query, if any
+ * @param paging Paging information.
+ * @returns Tuple of {@link QueryResultWithState} and a {@link PerformQuery} delegate.
+ */
+export function useObservableQueryWithPaging<TDataType, TQuery extends IObservableQueryFor<TDataType>, TArguments = object>(query: Constructor<TQuery>, paging: Paging, args?: TArguments, sorting?: Sorting):
+    [QueryResultWithState<TDataType>, SetSorting, SetPage, SetPageSize] {
+    return useObservableQueryInternal<TDataType, TQuery, TArguments>(query, sorting, paging, args);
+}

package/queries/useQuery.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IQueryFor, QueryResultWithState, QueryResult, Paging, Sorting } from '@cratis/arc/queries';
+import { Constructor } from '@cratis/fundamentals';
+import { useState, useEffect, useContext, useRef, useMemo } from 'react';
+import { SetSorting } from './SetSorting';
+import { SetPage } from './SetPage';
+import { SetPageSize } from './SetPageSize';
+import { ArcContext } from '../ArcContext';
+
+/**
+ * Delegate type for performing a {@link IQueryFor} in the context of the {@link useQuery} hook.
+ */
+export type PerformQuery<TArguments = object> = (args?: TArguments) => Promise<void>;
+
+type QueryPerformer<TQuery extends IQueryFor<TDataType>, TDataType, TArguments = object> = (performer: TQuery, args?: TArguments) => Promise<QueryResult<TDataType>>;
+
+function useQueryInternal<TDataType, TQuery extends IQueryFor<TDataType>, TArguments = object>(query: Constructor<TQuery>, performer: QueryPerformer<TQuery, TDataType, TArguments>, sorting?: Sorting, paging?: Paging, args?: TArguments):
+    [QueryResultWithState<TDataType>, PerformQuery<TArguments>, SetSorting, SetPage, SetPageSize] {
+    paging ??= Paging.noPaging;
+    sorting ??= Sorting.none;
+    const arc = useContext(ArcContext);
+    const queryInstance = useRef<TQuery | null>(null);
+    const [renderCounter, setRenderCounter] = useState(0);
+
+    queryInstance.current = useMemo(() => {
+        const instance = new query() as TQuery;
+        instance.paging = paging;
+        instance.sorting = sorting;
+        instance.setMicroservice(arc.microservice);
+        instance.setApiBasePath(arc.apiBasePath ?? '');
+        instance.setOrigin(arc.origin ?? '');
+        instance.setHttpHeadersCallback(arc.httpHeadersCallback ?? (() => ({})));
+        return instance;
+    }, []);
+
+    const [result, setResult] = useState<QueryResultWithState<TDataType>>(QueryResultWithState.initial(queryInstance.current!.defaultValue));
+
+    const queryExecutor = (async (args?: TArguments) => {
+        if (queryInstance) {
+            try {
+                const queryResult = await performer(queryInstance.current!, args);
+                setResult(QueryResultWithState.fromQueryResult(queryResult, false));
+            } catch {
+                // Ignore
+            }
+        }
+    });
+
+    useEffect(() => {
+        queryExecutor(args);
+    }, []);
+
+    const invalidate = () => {
+        setRenderCounter(renderCounter + 1);
+    };
+
+    return [
+        result!,
+        async (args?: TArguments) => {
+            setResult(QueryResultWithState.fromQueryResult(result!, true));
+            await queryExecutor(args);
+        },
+        async (sorting: Sorting) => {
+            setResult(QueryResultWithState.fromQueryResult(result!, true));
+            queryInstance.current!.sorting = sorting;
+            invalidate();
+            await queryExecutor(args);
+        },
+        async (page: number) => {
+            setResult(QueryResultWithState.fromQueryResult(result!, true));
+            queryInstance.current!.paging = new Paging(page, queryInstance.current!.paging?.pageSize ?? 0);
+            invalidate();
+            await queryExecutor(args);
+        },
+        async (pageSize: number) => {
+            setResult(QueryResultWithState.fromQueryResult(result!, true));
+            queryInstance.current!.paging = new Paging(queryInstance.current!.paging?.page ?? 0, pageSize);
+            invalidate();
+            await queryExecutor(args);
+        }];
+}
+
+/**
+ * React hook for working with {@link IQueryFor} within the state management of React.
+ * @template TDataType Type of model the query is for.
+ * @template TQuery Type of query to use.
+ * @template TArguments Optional: Arguments for the query, if any
+ * @param query Query type constructor.
+ * @param args Optional: Arguments for the query, if any
+ * @returns Tuple of {@link QueryResult} and a {@link PerformQuery} delegate.
+ */
+export function useQuery<TDataType, TQuery extends IQueryFor<TDataType>, TArguments = object>(query: Constructor<TQuery>, args?: TArguments, sorting?: Sorting):
+    [QueryResultWithState<TDataType>, PerformQuery<TArguments>, SetSorting] {
+    const [result, perform, setSorting] = useQueryInternal(query, async (queryInstance: TQuery, actualArgs?: TArguments) => await queryInstance.perform(actualArgs!), sorting, undefined, args);
+    return [result, perform, setSorting];
+}
+
+/**
+ * React hook for working with {@link IQueryFor} within the state management of React for queries with paging.
+ * @template TDataType Type of model the query is for.
+ * @template TQuery Type of query to use.
+ * @template TArguments Optional: Arguments for the query, if any
+ * @param query Query type constructor.
+ * @param paging Paging information.
+ * @param args Optional: Arguments for the query, if any
+ * @returns Tuple of {@link QueryResult} and a {@link PerformQuery} delegate.
+ */
+export function useQueryWithPaging<TDataType, TQuery extends IQueryFor<TDataType>, TArguments = object>(query: Constructor<TQuery>, paging: Paging, args?: TArguments, sorting?: Sorting):
+    [QueryResultWithState<TDataType>, PerformQuery<TArguments>, SetSorting, SetPage, SetPageSize] {
+    return useQueryInternal(query, async (queryInstance: TQuery, actualArgs?: TArguments) => await queryInstance.perform(actualArgs!), sorting, paging, args);
+}