Skip to content

EspoCRM – Open Source CRM Application

TS migration, relation interfaces

Yuriia34466419d7f
diff --git a/client/src/contracts/relation.ts b/client/src/contracts/relation.ts
new file mode 100644
index 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.ts
index ecc4cd2512..0081c28a07 100644
--- a/client/src/global.d.ts
+++ b/client/src/global.d.ts
@@ -18,7 +18,7 @@ declare global {
// noinspection ES6ConvertVarToLetConst
var loader: {
require: (id: string, callback: RequireCallback, errorCallback?: RequireErrorCallback) => void;
- requirePromise: (id: string) => Promise<unknown>;
+ requirePromise: <T = unknown>(id: string) => Promise<T>;
}
// noinspection ES6ConvertVarToLetConst
diff --git a/client/src/handlers/create-related.js b/client/src/handlers/create-related.ts
similarity index 67%
rename from client/src/handlers/create-related.js
rename to client/src/handlers/create-related.ts
index 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.ts
new file mode 100644
index 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.ts
similarity index 63%
rename from client/src/handlers/select-related.js
rename to client/src/handlers/select-related.ts
index 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.js
index 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.js
index 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.ts
index 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.ts
index 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.json
index 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",