EspoCRM – Open Source CRM Application
PHP calendarcontactscrmcrm-platformcrm-systemcustomer-portalcustomer-supportcustomizabledocumentsemail-marketingkanbanleadsopen-sourcephpplatformsales-automationsingle-page-applicationsupport
TS migration, relation interfaces
Yuriia34466419d7f
diff --git a/client/src/contracts/relation.ts b/client/src/contracts/relation.tsnew file mode 100644index 0000000000..c2175e8a55--- /dev/null+++ b/client/src/contracts/relation.ts@@ -0,0 +1,107 @@+/************************************************************************+ * This file is part of EspoCRM.+ *+ * EspoCRM – Open Source CRM application.+ * Copyright (C) 2014-2026 EspoCRM, Inc.+ * Website: https://www.espocrm.com+ *+ * This program is free software: you can redistribute it and/or modify+ * it under the terms of the GNU Affero General Public License as published by+ * the Free Software Foundation, either version 3 of the License, or+ * (at your option) any later version.+ *+ * This program is distributed in the hope that it will be useful,+ * but WITHOUT ANY WARRANTY; without even the implied warranty of+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ * GNU Affero General Public License for more details.+ *+ * You should have received a copy of the GNU Affero General Public License+ * along with this program. If not, see <https://www.gnu.org/licenses/>.+ *+ * The interactive user interfaces in modified source and object code versions+ * of this program must display Appropriate Legal Notices, as required under+ * Section 5 of the GNU Affero General Public License version 3.+ *+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.+ ************************************************************************/++import type Model from 'model';+import type {AdvancedFilter} from 'search-manager';++export interface SelectRelatedFilters {+ /**+ * Advanced filters. A field name as a key.+ */+ advanced?: Record<string, AdvancedFilter>;+ /**+ * Bool filters.+ */+ bool?: string[];+ /**+ * A primary filter.+ */+ primary?: string;+ /**+ * A field to order by.+ */+ orderBy?: string;+ /**+ * An order direction.+ */+ order?: 'asc' | 'desc';+}++/**+ * Select related records. Prepares filters for selecting records to relate.+ */+export interface SelectRelatedHandler<M extends Model = Model> {++ /**+ * Filters.+ *+ * @param model A parent model.+ * @return {Promise<SelectRelatedFilters>} Filters.+ */+ getFilters(model: M): Promise<SelectRelatedFilters>;+}++/**+ * Prepares attributes for a related record that is being created.+ *+ * @param model A parent model.+ */+export interface CreateRelatedHandler<M extends Model = Model> {++ /**+ * Get attributes for a new record.+ *+ * @param model A model.+ * @param link A link name.+ */+ getAttributes(model: M, link: string): Promise<Record<string, unknown>>;+}++/**+ * Prepares attributes to set to the model when selecting and clearing a related record.+ *.+ * @template M A related model type.+ * @template P A parent model type.+ */+export interface SelectFieldHandler<M extends Model = Model> {++ /**+ * Get attributes to set to the model after selecting the related model.+ *+ * @param model A related model.+ * @return {Promise<Record<string, unknown>>} Attributes.+ */+ getAttributes: (model: M) => Promise<Record<string, unknown>>;++ /**+ * Get attributes to set to the model after clearing a related model. Usually, it's null values.+ *+ * @return {Promise<Record<string, unknown>>} Attributes.+ */+ getClearAttributes: () => Promise<Record<string, unknown>>;+}diff --git a/client/src/global.d.ts b/client/src/global.d.tsindex ecc4cd2512..0081c28a07 100644--- a/client/src/global.d.ts+++ b/client/src/global.d.ts@@ -18,7 +18,7 @@ declare global {// noinspection ES6ConvertVarToLetConstvar loader: {require: (id: string, callback: RequireCallback, errorCallback?: RequireErrorCallback) => void;- requirePromise: (id: string) => Promise<unknown>;+ requirePromise: <T = unknown>(id: string) => Promise<T>;}// noinspection ES6ConvertVarToLetConstdiff --git a/client/src/handlers/create-related.js b/client/src/handlers/create-related.tssimilarity index 67%rename from client/src/handlers/create-related.jsrename to client/src/handlers/create-related.tsindex c0f285b4e1..f6a5aba9e1 100644--- a/client/src/handlers/create-related.js+++ b/client/src/handlers/create-related.ts@@ -26,31 +26,41 @@* these Appropriate Legal Notices must retain the display of the "EspoCRM" word.************************************************************************/+import type {CreateRelatedHandler as CreateRelatedHandlerInterface} from 'contracts/relation';+import type ViewHelper from 'view-helper';+import type Model from 'model';+/*** Prepares attributes for a related record that is being created.- *- * @abstract*/-class CreateRelatedHandler {+abstract class CreateRelatedHandler<M extends Model = Model> implements CreateRelatedHandlerInterface<M> {++ /**+ * @internal+ */+ protected readonly viewHelper: ViewHelper/**- * @param {module:view-helper} viewHelper+ * @internal*/- constructor(viewHelper) {- // noinspection JSUnusedGlobalSymbols+ constructor(viewHelper: ViewHelper) {this.viewHelper = viewHelper;}/*** Get attributes for a new record.*- * @abstract- * @param {module:model} model A model.- * @param {string} link A link name. As of v9.2.0.- * @return {Promise<Object.<string, *>>} Attributes.+ * @param model A model.+ * @param link A link name. As of v9.2.0.+ * @return {Promise<Object.<string, unknown>>} Attributes.*/- getAttributes(model, link) {- return Promise.resolve({});+ async getAttributes(model: M, link: string): Promise<Record<string, unknown>> {+ // noinspection BadExpressionStatementJS+ model;+ // noinspection BadExpressionStatementJS+ link;++ return {};}}diff --git a/client/src/handlers/select-field-relation.ts b/client/src/handlers/select-field-relation.tsnew file mode 100644index 0000000000..046a069c00--- /dev/null+++ b/client/src/handlers/select-field-relation.ts@@ -0,0 +1,68 @@+/************************************************************************+ * This file is part of EspoCRM.+ *+ * EspoCRM – Open Source CRM application.+ * Copyright (C) 2014-2026 EspoCRM, Inc.+ * Website: https://www.espocrm.com+ *+ * This program is free software: you can redistribute it and/or modify+ * it under the terms of the GNU Affero General Public License as published by+ * the Free Software Foundation, either version 3 of the License, or+ * (at your option) any later version.+ *+ * This program is distributed in the hope that it will be useful,+ * but WITHOUT ANY WARRANTY; without even the implied warranty of+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ * GNU Affero General Public License for more details.+ *+ * You should have received a copy of the GNU Affero General Public License+ * along with this program. If not, see <https://www.gnu.org/licenses/>.+ *+ * The interactive user interfaces in modified source and object code versions+ * of this program must display Appropriate Legal Notices, as required under+ * Section 5 of the GNU Affero General Public License version 3.+ *+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.+ ************************************************************************/++import type {SelectFieldHandler} from 'contracts/relation';+import type ViewHelper from 'view-helper';+import type Model from 'model';++/**+ * @since 10.0.0+ */+abstract class SelectFieldRelationHandler<M extends Model = Model> implements SelectFieldHandler<M> {++ /**+ * @internal+ */+ protected viewHelper: ViewHelper++ /**+ * A parent model.+ *+ */+ protected readonly model: Model;++ /**+ * @internal+ */+ constructor(viewHelper: ViewHelper, model: Model) {+ this.viewHelper = viewHelper;+ this.model = model;+ }++ /**+ * @inheritDoc+ */+ abstract getAttributes(model: M): Promise<Record<string, unknown>>++ /**+ * @inheritDoc+ */+ abstract getClearAttributes(): Promise<Record<string, unknown>>+}++export default SelectFieldRelationHandler;diff --git a/client/src/handlers/select-related.js b/client/src/handlers/select-related.tssimilarity index 63%rename from client/src/handlers/select-related.jsrename to client/src/handlers/select-related.tsindex 5fd6aa9e0d..5d0c06e652 100644--- a/client/src/handlers/select-related.js+++ b/client/src/handlers/select-related.ts@@ -26,47 +26,39 @@* these Appropriate Legal Notices must retain the display of the "EspoCRM" word.************************************************************************/-/** @module handlers/select-related */--/**- * @typedef {Object} module:handlers/select-related~filters- * @property {Object.<string, import('search-manager').AdvancedFilter>} [advanced]- * Advanced filters map. A field name as a key.- * @property {string[]} [bool] Bool filters.- * @property {string} [primary] A primary filter.- * @property {string} [orderBy] A field to order by.- * @property {'asc'|'desc'} [order] An order direction.- */+import type {SelectRelatedFilters, SelectRelatedHandler as SelectRelatedHandlerInterface} from 'contracts/relation';+import type ViewHelper from 'view-helper';+import type Model from 'model';/*** Prepares filters for selecting records to relate.- *- * @abstract+ * Use the interface directly rather than extending this class.*/-class SelectRelatedHandler {+abstract class SelectRelatedHandler<M extends Model = Model> implements SelectRelatedHandlerInterface<M> {/**- * @protected- * @type {import('view-helper').default}+ * @internal*/- viewHelper+ protected readonly viewHelper: ViewHelper/**- * @param {import('view-helper').default} viewHelper+ * @internal*/- constructor(viewHelper) {+ constructor(viewHelper: ViewHelper) {this.viewHelper = viewHelper;}/**- * Get filters for selecting records to relate.+ * @inheritDoc*- * @abstract- * @param {module:model} model A model.- * @return {Promise<module:handlers/select-related~filters>} Filters.+ * @param model A model.+ * @return {Promise<SelectRelatedFilters>} Filters.*/- getFilters(model) {- return Promise.resolve({});+ async getFilters(model: M): Promise<SelectRelatedFilters> {+ // noinspection BadExpressionStatementJS+ model;++ return {};}}diff --git a/client/src/helpers/record/create-related.js b/client/src/helpers/record/create-related.jsindex cdaeec9636..a0db2f87e7 100644--- a/client/src/helpers/record/create-related.js+++ b/client/src/helpers/record/create-related.js@@ -75,8 +75,8 @@ class CreateRelatedHelper {if (handler) {const Handler = await Espo.loader.requirePromise(handler);- /** @type {import('handlers/create-related').default} */- const handlerObj = new Handler(this.view.getHelper());+ /** @type {import('contracts/relation').CreateRelatedHandler} */+ const handlerObj = new Handler(this.view.getHelper(), {link: link});const additionalAttributes = await handlerObj.getAttributes(model, link);diff --git a/client/src/helpers/record/select-related.js b/client/src/helpers/record/select-related.jsindex 6238c2c67e..0c08b28e60 100644--- a/client/src/helpers/record/select-related.js+++ b/client/src/helpers/record/select-related.js@@ -140,7 +140,7 @@ class SelectRelatedHelper {Espo.loader.requirePromise(handler).then(Handler => new Handler(this.view.getHelper()))- .then(/** module:handlers/select-related */handler => {+ .then(/** import('contracts/relation').SelectRelatedHandler */handler => {handler.getFilters(model).then(filters => resolve(filters));});diff --git a/client/src/views/fields/link-multiple.ts b/client/src/views/fields/link-multiple.tsindex 995fb89c5c..da026f92d7 100644--- a/client/src/views/fields/link-multiple.ts+++ b/client/src/views/fields/link-multiple.ts@@ -35,6 +35,8 @@ import Model from 'model';import {AjaxPromise} from 'util/ajax';import Ajax from 'ajax';import Ui from 'ui';+import {SelectRelatedHandler} from 'contracts/relation';+import CreateRelatedHandler from 'handlers/create-related';interface LinkMultipleParams extends BaseParams{@@ -1042,17 +1044,18 @@ class LinkMultipleFieldView<return Promise.resolve(attributes);}- return new Promise(resolve => {- Espo.loader.requirePromise(this.panelDefs.createHandler)- .then((Handler: any) => new Handler(this.getHelper()))- .then(async /** import('handlers/create-related').default */handler => {- const additionalAttributes = await handler.getAttributes(this.model, this.name);+ return new Promise(async resolve => {+ const handler = this.panelDefs.createHandler;- resolve({- ...attributes,- ...additionalAttributes,- });- });+ const Handler = await Espo.loader.requirePromise<new (...args: any[]) => CreateRelatedHandler>(handler);+ const handlerInstance = new Handler(this.getHelper());++ const additionalAttributes = await handlerInstance.getAttributes(this.model, this.name);++ resolve({+ ...attributes,+ ...additionalAttributes,+ });});};}@@ -1068,7 +1071,7 @@ class LinkMultipleFieldView<});}- private _getSelectFilters(): Promise<SelectFilters> {+ private _getSelectFilters(): Promise<SelectFilters> {const handler = this.panelDefs.selectHandler;const localBoolFilterList = this.getSelectBoolFilterList();@@ -1094,36 +1097,32 @@ class LinkMultipleFieldView<}return new Promise(async resolve => {- Espo.loader.requirePromise(handler)- .then((Handler: any) => new Handler(this.getHelper()))- .then(/** module:handlers/select-related */handler => {- return handler.getFilters(this.model);- })- .then(filters => {- const advanced = {- ...(this.getSelectFilters() || {}),- ...(filters.advanced || {}),- ...this._getCascadingFilters(),- };-- const primaryFilter = this.getSelectPrimaryFilterName() ||- filters.primary || this.panelDefs.selectPrimaryFilterName;-- const boolFilterList =- (localBoolFilterList || filters.bool || this.panelDefs.selectBoolFilterList) ?- [- ...(localBoolFilterList ?? []),- ...(filters.bool ?? []),- ...(this.panelDefs.selectBoolFilterList ?? []),- ] :- undefined;-- resolve({- bool: boolFilterList,- primary: primaryFilter,- advanced: advanced,- });- });+ const Handler = await Espo.loader.requirePromise<new (...args: any[]) => SelectRelatedHandler>(handler);+ const filters = await new Handler(this.getHelper()).getFilters(this.model);++ const advanced = {+ ...(this.getSelectFilters() || {}),+ ...(filters.advanced || {}),+ ...this._getCascadingFilters(),+ };++ const primaryFilter = this.getSelectPrimaryFilterName() || filters.primary ||+ this.panelDefs.selectPrimaryFilterName;++ const boolFilterList =+ (localBoolFilterList || filters.bool || this.panelDefs.selectBoolFilterList) ?+ [+ ...(localBoolFilterList ?? []),+ ...(filters.bool ?? []),+ ...(this.panelDefs.selectBoolFilterList ?? []),+ ] :+ undefined;++ resolve({+ bool: boolFilterList,+ primary: primaryFilter,+ advanced: advanced,+ });});}diff --git a/client/src/views/fields/link.ts b/client/src/views/fields/link.tsindex 13e9cbdc27..df9f76c767 100644--- a/client/src/views/fields/link.ts+++ b/client/src/views/fields/link.ts@@ -35,6 +35,8 @@ import Ui from 'ui';import {AdvancedFilter} from 'search-manager';import Model from 'model';import {AjaxPromise} from 'util/ajax';+import {SelectRelatedHandler, SelectFieldHandler} from 'contracts/relation';+import CreateRelatedHandler from 'handlers/create-related';/*** Parameters.@@ -88,11 +90,6 @@ interface CascadingLogic {}[]}-interface SelectFieldHandler {- getAttributes: (model: Model) => Promise<Record<string, unknown>>;- getClearAttributes: () => Promise<Record<string, unknown>>;-}-interface SelectFilters {bool?: string[];advanced?: Object;@@ -468,19 +465,20 @@ class LinkFieldView<private getSelectFieldHandler(): Promise<SelectFieldHandler> {if (!this.panelDefs.selectFieldHandler) {return Promise.resolve({+ getAttributes: (_: Model) => Promise.resolve({}),getClearAttributes: () => Promise.resolve({}),- getAttributes: () => Promise.resolve({}),});}- return new Promise(resolve => {- Espo.loader.requirePromise(this.panelDefs.selectFieldHandler)- .then((Handler: any) => {- // Model is passed as of v8.2.- const handler = new Handler(this.getHelper(), this.model);+ return new Promise(async resolve => {+ const handler = this.panelDefs.selectFieldHandler;- resolve(handler);- });+ const Handler = await Espo.loader.requirePromise<new (...args: any[]) => SelectFieldHandler>(handler);++ // Model is passed as of v8.2.+ const handlerImplementation = new Handler(this.getHelper(), this.model);++ resolve(handlerImplementation);});}@@ -1065,17 +1063,18 @@ class LinkFieldView<return Promise.resolve(attributes);}- return new Promise(resolve => {- Espo.loader.requirePromise(this.panelDefs.createHandler)- .then((Handler: any) => new Handler(this.getHelper()))- .then(async /** import('handlers/create-related').default */handler => {- const additionalAttributes = await handler.getAttributes(this.model, this.name);+ return new Promise(async resolve => {+ const handler = this.panelDefs.createHandler;- resolve({- ...attributes,- ...additionalAttributes,- });- });+ const Handler = await Espo.loader.requirePromise<new (...args: any[]) => CreateRelatedHandler>(handler);+ const handlerInstance = new Handler(this.getHelper());++ const additionalAttributes = await handlerInstance.getAttributes(this.model, this.name);++ resolve({+ ...attributes,+ ...additionalAttributes,+ });});};}@@ -1188,43 +1187,40 @@ class LinkFieldView<});}- return new Promise(resolve => {- Espo.loader.requirePromise(handler)- .then((Handler: any) => new Handler(this.getHelper()))- .then(/** module:handlers/select-related */handler => {- return handler.getFilters(this.model);- })- .then(filters => {- const advanced = {- ...(this.getSelectFilters() ?? {}),- ...(filters.advanced ?? {}),- ...this._getCascadingFilters(),- };-- const primaryFilter = this.getSelectPrimaryFilterName() ||- filters.primary || this.panelDefs.selectPrimaryFilterName;-- const boolFilterList = (localBoolFilterList || filters.bool || this.panelDefs.selectBoolFilterList) ?- [- ...(localBoolFilterList || []),- ...(filters.bool || []),- ...(this.panelDefs.selectBoolFilterList || []),- ] :- undefined;-- this._applyAdditionalFilter(advanced);-- const orderBy = filters.orderBy;- const order = orderBy ? filters.order : undefined;-- resolve({- bool: boolFilterList,- primary: primaryFilter,- advanced: advanced,- orderBy: orderBy,- order: order,- });- });+ return new Promise(async resolve => {+ const Handler = await Espo.loader.requirePromise<new (...args: any[]) => SelectRelatedHandler>(handler);++ const filters = await new Handler(this.getHelper()).getFilters(this.model);++ const advanced = {+ ...(this.getSelectFilters() ?? {}),+ ...(filters.advanced ?? {}),+ ...this._getCascadingFilters(),+ };++ const primaryFilter = this.getSelectPrimaryFilterName() || filters.primary ||+ this.panelDefs.selectPrimaryFilterName;++ const boolFilterList = (localBoolFilterList || filters.bool || this.panelDefs.selectBoolFilterList) ?+ [+ ...(localBoolFilterList || []),+ ...(filters.bool || []),+ ...(this.panelDefs.selectBoolFilterList || []),+ ] :+ undefined;++ this._applyAdditionalFilter(advanced);++ const orderBy = filters.orderBy;+ const order = orderBy ? filters.order : undefined;++ resolve({+ bool: boolFilterList,+ primary: primaryFilter,+ advanced: advanced,+ orderBy: orderBy,+ order: order,+ });});}diff --git a/schema/metadata/clientDefs.json b/schema/metadata/clientDefs.jsonindex fa6f38a3b6..2dafa237c6 100644--- a/schema/metadata/clientDefs.json+++ b/schema/metadata/clientDefs.json@@ -482,15 +482,15 @@},"selectHandler": {"type": "string",- "description": "A select handler for providing filters when selecting related records. Should have a method *getFilters* returning a promise. Optionally, extend from `handlers/select-related`. \n\nPromise value:\n```{bool?: string[], primary?: string, orderBy?: string, order?: 'asc'|'desc', advanced: Record}```"+ "description": "A select handler for providing filters when selecting related records. Should implement `contracts/relation.SelectRelatedHandler` Optionally, extend from `handlers/select-related`."},"createHandler": {"type": "string",- "description": "A create handler. Provides attributes when creating a new related record. Should have a method *getAttributes* returning a promise. Optionally, extend from `handlers/create-related`."+ "description": "A create handler. Provides attributes when creating a new related record. Should implement `contracts/relation.CreateRelatedHandler`. Optionally, extend from `handlers/create-related`."},"selectFieldHandler": {"type": "string",- "description": "A handler called when change a link field. Only for belongs-to and has-one relations. Should have *getAttributes* and *getClearAttributes* methods."+ "description": "A handler called when change a link field. Only for belongs-to and has-one relations. Should implement `contracts/relation.SelectFieldHandler`."},"layout": {"type": "string",