@sap-cloud-sdk/odata-common/dist/entity-base.d.ts

SAP Cloud SDK for JavaScript common functions of OData client generator and OpenAPI clint generator.

import { EntityBuilder } from './entity-builder';
import type { Field, Link } from './selectable';
import type { DeSerializers } from './de-serializers';
import type { EntityApi } from './entity-api';
/**
 * Helper type to extract the {@link @sap-cloud-sdk/util!ODataVersion} from a given entity so ODataVersionOf<MyVersion2Entity> is `v2`.
 */
export type ODataVersionOf<T extends EntityBase> = T['_oDataVersion'];
/**
 * Represents the static API of an entity.
 */
export interface Constructable<EntityT extends EntityBase> {
    /**
     * Name of the entity.
     */
    _entityName: string;
    /**
     * Base path as specified in the `options-per-service.json`, e.g., `/sap/opu/odata/sap/API_COMMON_SRV`.
     */
    _defaultBasePath: string;
    /**
     * Names of the key properties of the entity.
     */
    _keys: string[];
    new (...args: any[]): EntityT;
}
/**
 * Entity builder type with check for EntityT.
 */
export type EntityBuilderType<EntityT extends EntityBase, DeSerializersT extends DeSerializers> = {
    [property in keyof Required<Omit<EntityT, keyof EntityBase>>]: (value: EntityT[property]) => EntityBuilderType<EntityT, DeSerializersT>;
} & EntityBuilder<EntityT, DeSerializersT>;
/**
 * Super class for all representations of OData entity types.
 */
export declare abstract class EntityBase {
    readonly _entityApi: any;
    static _serviceName: string;
    static _entityName: string;
    static _defaultBasePath: string;
    /**
     * The remote state of the entity.
     * Remote state refers to the last known state of the entity on the remote system from which it has been retrieved or to which it has been posted.
     * It is stored as map, where the keys are stored in the format of the original OData properties.
     */
    protected remoteState: {
        [keys: string]: any;
    };
    /**
     * The current ETag version of the entity in the remote system.
     * The ETag identified the version of the in the remote system. It will be automatically set in the "if-match" header of update requests and can be set as a custom header for delete requests.
     * When no ETag is provided by the remote system the value of this variable defaults to "*".
     */
    protected _versionIdentifier: string;
    /**
     * A mapper representing custom fields in an entity.
     * Custom fields are represented by their field names and the corresponding values.
     * A custom field can be added or updated using {@link setCustomField} method.
     */
    protected _customFields: Record<string, any>;
    abstract readonly _oDataVersion: any;
    /**
     * @internal
     */
    constructor(_entityApi: any);
    /**
     * ETag version identifier accessor.
     * @returns The ETag version identifier of the retrieved entity, returns `undefined` if not retrieved.
     */
    get versionIdentifier(): string;
    /**
     * Returns a map that contains all entity custom fields.
     * @returns A map of all defined custom fields in the entity.
     */
    getCustomFields(): Record<string, any>;
    /**
     * Custom field value getter.
     * @param fieldName - The name of the custom field.
     * @returns The value of the corresponding custom field.
     */
    getCustomField(fieldName: string): any;
    /**
     * Sets a new custom field in the entity or updates it.
     * Throws an error, if the provided custom field name is already defined by an original field in entity.
     * @param fieldName - The name of the custom field to update.
     * @param value - The value of the field.
     * @returns The entity itself, to facilitate method chaining.
     */
    setCustomField(fieldName: string, value: any): this;
    /**
     * Validates whether a custom field exists in the entity.
     * @param fieldName - The name of the custom field to update.
     * @returns A boolean value, that indicates whether a custom field is defined in entity.
     */
    hasCustomField(fieldName: string): boolean;
    /**
     * Sets custom fields on an entity.
     * @param customFields - Custom fields to set on the entity.
     * @returns The entity itself, to facilitate method chaining.
     */
    setCustomFields(customFields: Record<string, any>): this;
    /**
     * Set the ETag version identifier of the retrieved entity.
     * @param etag - The returned ETag version of the entity.
     * @returns The entity itself, to facilitate method chaining.
     */
    setVersionIdentifier(etag: string | undefined): this;
    /**
     * Initializes or sets the remoteState of the entity.
     * This function is called on all read, create and update requests.
     * @param state - State to be set as remote state.
     * @returns The entity itself, to facilitate method chaining.
     */
    setOrInitializeRemoteState(state?: Record<string, any>): this;
    /**
     * Returns all updated custom field properties compared to the last known remote state.
     * @returns An object containing all updated custom properties, with their new values.
     */
    getUpdatedCustomFields(): Record<string, any>;
    /**
     * Returns all changed properties compared to the last known remote state.
     * The returned properties do not include custom fields.
     * Use {@link getUpdatedCustomFields}, if you need custom fields.
     * @returns EntityBase with all properties that changed.
     */
    getUpdatedProperties(): Record<string, any>;
    /**
     * Returns all changed property names compared to the last known remote state.
     * The returned properties names do not include custom fields.
     * Use {@link getUpdatedCustomFields}, if you need custom fields.
     * @returns EntityBase with all properties that changed.
     */
    getUpdatedPropertyNames(): string[];
    /**
     * Overwrites the default toJSON method so that all instance variables as well as all custom fields of the entity are returned.
     * @returns An object containing all instance variables + custom fields.
     */
    toJSON(): {
        [key: string]: any;
    };
    protected isVisitedEntity<EntityT extends EntityBase>(entity: EntityT, visitedEntities?: EntityBase[]): boolean;
    protected getCurrentStateForKey(key: string, visitedEntities?: EntityBase[]): any;
    /**
     * Validates whether a field name does not conflict with an original field name and thus can be defined as custom fields.
     * @param customFieldName - Field name to check.
     * @returns Boolean value that describes whether a field name can be defined as custom field.
     */
    protected isConflictingCustomField(customFieldName: string): boolean;
    /**
     * Creates an object containing all defined properties, navigation properties and custom fields in the entity.
     * @param visitedEntities - List of entities to check in case of circular dependencies.
     * @returns EntityBase as an object with all defined entity fields.
     */
    protected asObject(visitedEntities?: EntityBase[]): Record<string, any>;
}
/**
 * Represents an object that is related to an entity.
 * Objects that have the same structure would be represented by the same type in TypeScript.
 * This interface allows to identify equal structures as different structures if they are related to different entities.
 */
export interface EntityIdentifiable<T extends EntityBase, DeSerializersT extends DeSerializers> {
    /**
     * Dummy property whose type makes structurally identical entities distinguishable in TypeScript.
     */
    readonly _entity: T;
    /**
     * Dummy property to also include the deserializer type in the structure of the entity type.
     */
    readonly _deSerializers: DeSerializersT;
}
/**
 * @internal
 */
export declare function isSelectedProperty(json: any, field: Field<any> | Link<any, any, any>): boolean;
/**
 * @internal
 */
export declare function isExistentProperty(json: any, link: Link<any, any, any>): boolean;
/**
 * @internal
 */
export declare function isExpandedProperty(json: any, link: Link<any, any, any>): boolean;
/**
 * Create an entity builder for an entity API.
 * @param entityApi - The entity API to build entities for.
 * @returns An entity builder instance for the given entity API.
 */
export declare function entityBuilder<EntityT extends EntityBase, DeSerializersT extends DeSerializers>(entityApi: EntityApi<EntityT, DeSerializersT>): EntityBuilderType<EntityT, DeSerializersT>;