@memberjunction/global 2.111.1 → 2.112.0

package/dist/generic/baseEngine.d.ts

@@ -0,0 +1,260 @@
+import { BehaviorSubject } from 'rxjs';
+import { UserInfo } from './securityInfo';
+import { DatasetItemFilterType, IMetadataProvider, IRunViewProvider, RunViewResult } from './interfaces';
+import { BaseInfo } from './baseInfo';
+import { BaseEntityEvent } from './baseEntity';
+import { MJEvent } from '../interface';
+import { BaseSingleton } from '../BaseSingleton';
+/**
+ * Property configuration for the BaseEngine class to automatically load/set properties on the class.
+ */
+export declare class BaseEnginePropertyConfig extends BaseInfo {
+    /**
+     * The type of item to load, either 'entity' or 'dataset', defaults to 'entity'
+     */
+    Type: 'entity' | 'dataset';
+    /**
+     * The name of the property in the class instance
+     */
+    PropertyName: string;
+    /**
+     * The entity name to load from the database, required if Type is 'entity'
+     */
+    EntityName?: string;
+    /**
+     * The dataset name to load from the database, required if Type is 'dataset'
+     */
+    DatasetName?: string;
+    /**
+     * Optional, filters to apply to the data load, applies only when type is 'entity'. Use DatasetItemFilters for dataset filters.
+     */
+    Filter?: string;
+    /**
+     * Optional, filters to apply to each item in a dataset, only applies when type is 'dataset' and is optional in those cases.
+     */
+    DatasetItemFilters?: DatasetItemFilterType[];
+    /**
+     * Optional, only used if Type is 'dataset', specifies how to handle the results of the dataset load. Defaults to 'single_property' if not specified. When set to 'single_property', the entire dataset is set to the property specified by PropertyName.
+     * When set to 'individual_properties', each item in the dataset is set to a property on the object with the name of the item's key plus the item's Code name.
+     * For example, if the item's key is 'Demo' and the item's Code name is 'FirstItem', the property set on the object would be 'Demo_FirstItem'.
+     */
+    DatasetResultHandling?: 'single_property' | 'individual_properties';
+    /**
+     * Optional, order by clause to apply to the data load, only applies when type is 'entity'
+     */
+    OrderBy?: string;
+    /**
+     * Optional, expiration time in milliseconds
+     */
+    Expiration?: number;
+    /**
+     * Optional, whether to add the result to the object, defaults to true if not specified
+     */
+    AddToObject?: boolean;
+    /**
+     * Optional, defaults to true. If set to false, AutoRefresh for this item will be disabled. By default, whenever a BaseEntity event is emitted for a save/delete, if the entity name
+     * for this config matches the BaseEntity's entity name, the config will be refreshed. If this is set to false, that will not happen. NOTE: This is not a network notification mechanism,
+     * it only works within the local tier, so for example within a browser application, that brower's engine sub-classes will be updated when changes are made to entities in that application
+     * environment, and the same is true for MJAPI/Server based environments. If you need network based notification, additional infrastructure will be needed to implement that.
+     */
+    AutoRefresh?: boolean;
+    constructor(init?: Partial<BaseEnginePropertyConfig>);
+}
+/**
+ * Abstract base class for any engine-style class which executes work on behalf of a caller typically using a provider-style architecture with plug-ins. This base class
+ * provides a mechanism for loading metadata from the database and caching it for use by the engine. Subclasses must implement the Config abstract method and within that
+ * generally it is recommended to call the Load method to load the metadata. Subclasses can also override the AdditionalLoading method to perform additional loading tasks.
+ */
+export declare abstract class BaseEngine<T> extends BaseSingleton<T> {
+    private _loaded;
+    private _loadingSubject;
+    private _contextUser;
+    private _metadataConfigs;
+    private _dynamicConfigs;
+    private _dataMap;
+    private _expirationTimers;
+    private _entityEventSubjects;
+    private _provider;
+    /**
+     * While the BaseEngine class is a singleton, normally, it is possible to have multiple instances of the class in an application if the class is used in multiple contexts that have different providers.
+     */
+    constructor();
+    /**
+     * Returns the metadata provider to use for the engine. If a provider is set via the Config method, that provider will be used, otherwise the default provider will be used.
+     */
+    get ProviderToUse(): IMetadataProvider;
+    /**
+     * Returns the RunView provider to use for the engine. This is the same underlying object as the @property ProviderTouse, but cast to IRunViewProvider.
+     * If a provider is set via the Config method, that provider will be used, otherwise the default provider will be used.
+     */
+    get RunViewProviderToUse(): IRunViewProvider;
+    /**
+     * Returns a COPY of the metadata configs array for the engine. This is a copy so you can't modify the original configs by modifying this array.
+     */
+    get Configs(): BaseEnginePropertyConfig[];
+    /**
+     * Configures the engine by loading metadata from the database.
+     */
+    abstract Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): any;
+    /**
+     * This method should be called by sub-classes to load up their specific metadata requirements. For more complex metadata
+     * loading or for post-processing of metadata loading done here, overide the AdditionalLoading method to add your logic.
+     * @param configs
+     * @param contextUser
+     * @returns
+     */
+    protected Load(configs: Partial<BaseEnginePropertyConfig>[], provider: IMetadataProvider, forceRefresh?: boolean, contextUser?: UserInfo): Promise<void>;
+    /**********************************************************************
+     * This section is for handling caching of multiple instances when needed
+     * We use the primary singleton as the instance to store a cache of instances
+     * that are tied to specific providers. This is useful when we have multiple
+     * providers in a given app going to different connections.
+     *********************************************************************/
+    private static _providerInstances;
+    private static get ProviderInstances();
+    /**
+     * This method will check for the existence of an instance of this engine class that is tied to a specific provider. If one exists, it will return it, otherwise it will create a new instance
+     */
+    static GetProviderInstance<T>(provider: IMetadataProvider, subclassConstructor: new () => BaseEngine<T>): BaseEngine<T>;
+    /**
+     * Internal method to set the provider when an engine is loaded
+     * @param provider
+     */
+    protected SetProvider(provider: IMetadataProvider): void;
+    protected CheckAddToProviderInstances(provider: IMetadataProvider): void;
+    private _eventListener;
+    /**
+     * This method is responsible for registering for MJGlobal events and listening for BaseEntity events where those
+     * BaseEntity are related to the engine's configuration metadata. The idea is to auto-refresh the releated configs
+     * when the BaseEntity is updated.
+     */
+    protected SetupGlobalEventListener(): Promise<boolean>;
+    /**
+     * Subclasses of BaseEngine can override this method to handle individual MJGlobal events. This is typically done to optimize
+     * the way refreshes are done when a BaseEntity is updated. If you are interested in only BaseEntity events, override
+     * the HandleIndividualBaseEntityEvent method instead as this method primarily serves to filter all the events we get from MJGlobal
+     * and only pass on BaseEntity events to HandleIndividualBaseEntityEvent.
+     * @param event
+     */
+    protected HandleIndividualEvent(event: MJEvent): Promise<boolean>;
+    /**
+     * This method handles the individual base entity event and just checks to see if it is a delete or save event and if so, debounces it.
+     * Override this method if you want to have a different handling for the filtering of events that are debounced or if you don't want to debounce
+     * at all you can do that in an override of this method.
+     * @param event
+     */
+    protected HandleIndividualBaseEntityEvent(event: BaseEntityEvent): Promise<boolean>;
+    /**
+     * This method handles the debouncing process, by default using the EntityEventDebounceTime property to set the debounce time. Debouncing is
+     * done on a per-entity basis, meaning that if the debounce time passes for a specific entity name, the event will be processed. This is done to
+     * prevent multiple events from being processed in quick succession for a single entity which would cause a lot of wasted processing.
+     *
+     * Override this method if you want to change how debouncing time such as having variable debounce times per-entity, etc.
+     * @param event
+     * @returns
+     */
+    protected DebounceIndividualBaseEntityEvent(event: BaseEntityEvent): Promise<boolean>;
+    private _entityEventDebounceTime;
+    /**
+     * Overridable property to set the debounce time for entity events. Default is 5000 milliseconds (5 seconds).
+     */
+    protected get EntityEventDebounceTime(): number;
+    /**
+     * This method does the actual work of processing the entity event. It is not directly called from the event handler because we want to first debounce the events
+     * which also introduces a delay which is usually desirable so that our processing is typically outside of the scope of any transaction processing that would have
+     * originated the event.
+     *
+     * This is the best method to override if you want to change the actual processing of an entity event but do NOT want to modify the debouncing behavior.
+     */
+    protected ProcessEntityEvent(event: BaseEntityEvent): Promise<void>;
+    /**
+     * Utility method to upgrade an object to a BaseEnginePropertyConfig object.
+     * @param obj
+     * @returns
+     */
+    protected UpgradeObjectToConfig(obj: any): BaseEnginePropertyConfig;
+    /**
+     * Loads the specified metadata configurations.
+     * @param configs - The metadata configurations to load
+     * @param contextUser - The context user information
+     */
+    protected LoadConfigs(configs: Partial<BaseEnginePropertyConfig>[], contextUser: UserInfo): Promise<void>;
+    /**
+     * Loads a single metadata configuration.
+     * @param config - The metadata configuration to load
+     * @param contextUser - The context user information
+     */
+    protected LoadSingleConfig(config: BaseEnginePropertyConfig, contextUser: UserInfo): Promise<void>;
+    /**
+     * Handles the process of loading a single config of type 'entity'.
+     * @param config
+     * @param contextUser
+     */
+    protected LoadSingleEntityConfig(config: BaseEnginePropertyConfig, contextUser: UserInfo): Promise<void>;
+    /**
+     * Handles the result of a single view load.
+     * @param config
+     * @param result
+     */
+    protected HandleSingleViewResult(config: BaseEnginePropertyConfig, result: RunViewResult): void;
+    /**
+     * Handles the process of loading multiple entity configs in a single network call via RunViews()
+     * @param configs
+     * @param contextUser
+     */
+    protected LoadMultipleEntityConfigs(configs: BaseEnginePropertyConfig[], contextUser: UserInfo): Promise<void>;
+    /**
+     * Handles the process of loading a single config of type 'dataset'.
+     * @param config
+     * @param contextUser
+     */
+    protected LoadSingleDatasetConfig(config: BaseEnginePropertyConfig, contextUser: UserInfo): Promise<void>;
+    /**
+     * Sets an expiration timer for a metadata property.
+     * @param propertyName - The name of the property
+     * @param expiration - The expiration time in milliseconds
+     */
+    private SetExpirationTimer;
+    /**
+     * Adds a dynamic metadata configuration at runtime.
+     * @param config - The metadata configuration to add
+     * @param contextUser - The context user information
+     */
+    AddDynamicConfig(config: BaseEnginePropertyConfig, contextUser?: UserInfo): Promise<void>;
+    /**
+     * Removes a dynamic metadata configuration at runtime.
+     * @param propertyName - The name of the property to remove
+     */
+    RemoveDynamicConfig(propertyName: string): void;
+    /**
+     * Refreshes a specific item.
+     * @param propertyName - The name of the property to refresh
+     */
+    RefreshItem(propertyName: string): Promise<void>;
+    /**
+     * Refreshes all items
+     */
+    RefreshAllItems(): Promise<void>;
+    /**
+     * Subclasses can override this method to perform additional loading tasks
+     * @param contextUser
+     */
+    protected AdditionalLoading(contextUser?: UserInfo): Promise<void>;
+    /**
+     * Returns true if the data has been loaded, false otherwise.
+     */
+    get Loaded(): boolean;
+    /**
+     * Returns the loading subject. You can call await Config() and after Config() comes back as true that means you're loaded. However you can also directly subscribe to this subject to get updates on the loading status.
+     */
+    get LoadingSubject(): BehaviorSubject<boolean>;
+    /**
+     * Returns the context user set for the object, this is set via the Config() method.
+     */
+    get ContextUser(): UserInfo;
+    /**
+     * Helper method for sub-classes to have a single line of code that will make sure the data is loaded before proceeding and will throw an error if not loaded.
+     */
+    protected TryThrowIfNotLoaded(): void;
+}
+//# sourceMappingURL=baseEngine.d.ts.map

package/dist/generic/baseEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseEngine.d.ts","sourceRoot":"","sources":["../../src/generic/baseEngine.ts"],"names":[],"mappings":"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"}