@microsoft/sp-component-base 1.23.1 → 1.24.0-beta.2

package/lib-esm/DynamicDataSourceManager.js

@@ -0,0 +1,358 @@
+import { _EngagementLogger, _LogEntry, _LogType, _TraceLogger, _LogSource, _QosMonitor } from '@microsoft/sp-diagnostics';
+import { Text, Validate } from '@microsoft/sp-core-library';
+import { _DynamicDataUtilities } from '@microsoft/sp-dynamic-data';
+import * as lodash from '@microsoft/sp-lodash-subset';
+import { cloneDeep, findIndex, merge } from '@microsoft/sp-lodash-subset';
+import DynamicDataProvider from './DynamicDataProvider';
+import strings from './loc/Strings.resx';
+import { isExemptWebPartWithDynamicDataFromLazyLoadKSActivated } from './common/KillSwitches';
+class DynamicDataSourceManager {
+    /**
+   * Initializes the Dynamic Data source manager for a specific component.
+   *
+   * @param component - Component on which the source is being constructed.
+   *
+   * @internal
+   */ _initialize(component, serviceScope) {
+        Validate.isNotNullOrUndefined(component, 'component');
+        Validate.isNotNullOrUndefined(serviceScope, 'serviceScope');
+        this._component = component;
+        this._dynamicDataManager = serviceScope.consume(_DynamicDataUtilities.IDynamicDataManagerServiceKey);
+        this._isInitialized = true;
+    }
+    /**
+   * Disposes the resources held by the Dynamic Data source.
+   */ dispose() {
+        if (!this._isDisposed) {
+            if (this._src) {
+                this._dynamicDataManager.removeSource(this._src.id);
+                delete this._src;
+            }
+            delete this._dynamicDataManager;
+            delete this._component;
+            this._isInitialized = false;
+            this._isDisposed = true;
+        }
+    }
+    /**
+   * Returns true if the DynamicDataSourceManager is disposed.
+   */ get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+   * Returns the source of DynamicDataSourceManager.
+   * @internal
+   */ get _source() {
+        return this._src;
+    }
+    /**
+   * Initializes the Dynamic Data Source for the component.
+   *
+   * @param callableFunctions - Set of methods that are exposed through the Dynamic Data Source
+   */ initializeSource(callableFunctions) {
+        this._assertNotDisposed();
+        this._assertInitialized();
+        if (this._src) {
+            throw new Error(strings.SourceAlreadyInitialized);
+        }
+        this._callableFunctions = callableFunctions;
+        this._src = this._buildSource(this._component);
+        this._dynamicDataManager.addSource(this._src);
+        if (!isExemptWebPartWithDynamicDataFromLazyLoadKSActivated()) {
+            this._component._containsDynamicDataSource = true;
+        }
+        this._logFeatureEntry('DynamicDataSourceInitialized', {
+            sourceId: this._src.id
+        });
+    }
+    /**
+   * Notifies that this source has updated its properties.
+   *
+   * When invoked, it enables to broadcast the notification to all the consumers who have
+   * registered to this notification from this source.
+   */ notifySourceChanged() {
+        this._assertNotDisposed();
+        this._assertInitialized();
+        this._assertSourceExists();
+        this._dynamicDataManager.notifySourceChanged(this._src.id);
+    }
+    /**
+   * Notifies that this source has updated a specific property.
+   *
+   * When invoked, it enables to broadcast the notification to all the consumers who have
+   * registered to this notification from this source.
+   *
+   * @param propertyId - Id of the updated property in the source.
+   */ notifyPropertyChanged(propertyId) {
+        Validate.isNonemptyString(propertyId, 'propertyId');
+        this._assertNotDisposed();
+        this._assertInitialized();
+        this._assertSourceExists();
+        this._dynamicDataManager.notifyPropertyChanged(this._src.id, propertyId);
+    }
+    /**
+   * Updates the metadata of the Dynamic Data Source.
+   * It allows to update fields like title or description.
+   * Auto-generated fields like alias, componentId or instanceId cannot be updated.
+   *
+   * @param metadata - Partial of the metadata.
+   */ updateMetadata(metadata) {
+        this._assertNotDisposed();
+        this._assertInitialized();
+        this._assertSourceExists();
+        Validate.isNotNullOrUndefined(metadata, 'metadata');
+        // Ensure that auto-generated properties are not updated.
+        metadata.alias = undefined;
+        metadata.componentId = undefined;
+        metadata.instanceId = undefined;
+        merge(this._src.metadata, metadata);
+    }
+    /**
+   * Returns the Id of the current DataSource.
+   * If the component did not initialize as a dynamic data source, then it returns an empty string.
+   */ get sourceId() {
+        return this._src ? this._src.id : '';
+    }
+    _buildSource(component) {
+        // If the source is returning non-empty allowed events then, it has to define
+        // 'sendEvent' event handler as well.
+        if (this._callableFunctions.allowedEvents && this._callableFunctions.allowedEvents.length > 0) {
+            if (!this._callableFunctions.sendEvent) {
+                throw new Error(strings.NoSendEventWhenAllowedEventsIsNonEmpty);
+            }
+        }
+        return {
+            id: this._component._dynamicDataSourceId,
+            metadata: this._buildMetadata(component),
+            // Return a clone to ensure that the consumer doesn't modify values in the source
+            getPropertyDefinitions: this._getPropertyDefinitions.bind(this),
+            getPropertyValue: this._getPropertyValue.bind(this),
+            getAnnotatedPropertyValue: this._getAnnotatedPropertyValue.bind(this),
+            // async callbacks
+            getPropertyDefinitionsAsync: this._getPropertyDefinitionsAsync.bind(this),
+            getPropertyValueAsync: this._getPropertyValueAsync.bind(this),
+            getAnnotatedPropertyValueAsync: this._getAnnotatedPropertyValueAsync.bind(this),
+            allowedEventsAsync: this._allowedEventsAsync.bind(this),
+            sendEvent: this._sendEvent.bind(this)
+        };
+    }
+    /**
+   * This is the allowedEvents() that the DynamicDataSource actually exposes.
+   * It does a copy of the data to ensure the consumer doesn't modify the source.
+   */ _allowedEvents() {
+        return this._callableFunctions.allowedEvents ? cloneDeep(this._callableFunctions.allowedEvents()) : undefined;
+    }
+    /**
+   * This is the sendEvent() that the consumer invokes to send an event to the source, with data.
+   * @param eventName - Name of the event
+   * @param data - Associated data
+   */ _sendEvent(eventName, data) {
+        this._assertValidEvent(eventName);
+        this._callableFunctions.sendEvent(eventName, data);
+    }
+    /**
+   * This is the getPropertyDefinitions() that the DynamicDataSource actually exposes.
+   * It does a copy of the data to ensure the consumer doesn't modify the source.
+   * This assumes that the component has dynamic data and has a controller.
+   */ _getPropertyDefinitions() {
+        return cloneDeep(this._callableFunctions.getPropertyDefinitions());
+    }
+    /**
+   * This is the getPropertyValue() that the DynamicDataSource actually exposes.
+   * It does a copy of the data to ensure the consumer doesn't modify the source.
+   * This assumes that the component has the source initialized.
+   * If there is no value returned, it checks whether the propertyId is incorrect or the value is actually undefined.
+   *
+   * @remarks
+   * If the property value associated with the property id, is an array then the
+   * propertyId will have [*] notation appended at the end to support valid JSON Path notation.
+   * Hence when reading the property id, we account for that and extract the name accordingly.
+   */ _getPropertyValue(propertyId) {
+        Validate.isNotNullOrUndefined(propertyId, 'propertyId');
+        const qosMonitor = new _QosMonitor('DynamicDataSourceManager._getPropertyValue');
+        const paths = propertyId.split(DynamicDataProvider._jsonPathArrayRegex);
+        try {
+            let propertyValue = this._callableFunctions.getPropertyValue(paths.shift());
+            if (paths.length > 0) {
+                if (!isNaN(parseInt(paths[0], 10)) && Array.isArray(propertyValue)) {
+                    propertyValue = propertyValue[paths[0]];
+                }
+            }
+            if (propertyValue === undefined) {
+                if (// This code can be slow if there is a many property definitions (O(n) for number of properties).
+                // It's done this way to prioritize memory consumption instead of CPU cycles as this is an optional feature,
+                // so if it's not used there is no memory footprint
+                this._callableFunctions.getPropertyDefinitions().filter((def)=>def.id === propertyId).length === 0 && this._src // Check that the source exists to get its title
+                ) {
+                    throw new Error(`Property "${propertyId}" doesn't exist in source "${this._src.metadata.title}"`);
+                }
+            }
+            // DO NOT log propertyValue it can contain PII.
+            qosMonitor.writeSuccess({
+                ...this._src && this._src.metadata || {},
+                sourceId: this._src && this._src.id,
+                propertyId
+            });
+            return cloneDeep(propertyValue);
+        } catch (error) {
+            qosMonitor.writeUnexpectedFailure('NoPropertyId', error, {
+                propertyId
+            });
+            _TraceLogger.logErrorData({
+                source: this._logSource,
+                error: error
+            });
+            return undefined;
+        }
+    }
+    /**
+   * Returns the real time value of the property.
+   */ _getPropertyDefinitionsAsync() {
+        return Promise.resolve(this._getPropertyDefinitions());
+    }
+    /**
+   * Returns the real time value of the property.
+   * @param propertyId - property id for which the value is requested.
+   */ _getPropertyValueAsync(propertyId) {
+        return Promise.resolve(this._getPropertyValue(propertyId));
+    }
+    /**
+   * This is the allowedEvents() that the DynamicDataSource actually exposes.
+   * It does a copy of the data to ensure the consumer doesn't modify the source.
+   */ _allowedEventsAsync() {
+        return Promise.resolve(this._allowedEvents());
+    }
+    /**
+   * This is the getPropertyValueSchema() that the DynamicDataSource actually exposes.
+   * It does a copy of the data to ensure the consumer doesn't modify the source.
+   * If the source doesn't provide the annotated value, then it falls back to whatever
+   * 'getPropertyValue' returns as the sample value and metadata would be undefined.
+   *
+   * @remarks
+   * If the property value associated with the property id, is an array then the
+   * propertyId will have [*] notation appended at the end to support valid JSON Path notation.
+   * Hence when reading the property id, we account for that and extract the name accordingly.
+   *
+   * @param propertyId - property id for which the schema is requested.
+   */ _getAnnotatedPropertyValue(propertyId) {
+        Validate.isNotNullOrUndefined(propertyId, 'propertyId');
+        const qosMonitor = new _QosMonitor('DynamicDataSourceManager._getAnnotatedPropertyValue');
+        let annotatedPropertyValue;
+        const { getAnnotatedPropertyValue } = this._callableFunctions;
+        if (getAnnotatedPropertyValue) {
+            const paths = propertyId.split(DynamicDataProvider._jsonPathArrayRegex);
+            try {
+                annotatedPropertyValue = this._callableFunctions.getAnnotatedPropertyValue(paths.shift());
+                if (paths.length > 0) {
+                    if (!isNaN(parseInt(paths[0], 10)) && Array.isArray(annotatedPropertyValue)) {
+                        annotatedPropertyValue = annotatedPropertyValue[paths[0]];
+                    }
+                }
+                qosMonitor.writeSuccess({
+                    ...this._src && this._src.metadata || {},
+                    sourceId: this._src && this._src.id,
+                    annotatedPropertyValue,
+                    propertyId
+                });
+            } catch (error) {
+                qosMonitor.writeExpectedFailure('NoAnnotatedPropertyValue', error, {
+                    annotatedPropertyValue
+                });
+                _TraceLogger.logErrorData({
+                    source: this._logSource,
+                    error: error
+                });
+                annotatedPropertyValue = undefined;
+            }
+        }
+        if (!annotatedPropertyValue) {
+            annotatedPropertyValue = {
+                sampleValue: this._getPropertyValue(propertyId),
+                metadata: undefined
+            };
+        }
+        return annotatedPropertyValue;
+    }
+    /**
+   * Returns the annotated value of the property.
+   * @param propertyId - property id for which the value is requested.
+   */ _getAnnotatedPropertyValueAsync(propertyId) {
+        return Promise.resolve(this._getAnnotatedPropertyValue(propertyId));
+    }
+    _buildMetadata(component) {
+        const metadata = {
+            title: component.manifest.alias,
+            alias: component.manifest.alias,
+            componentId: component.componentId,
+            instanceId: component.instanceId
+        };
+        // Web parts have properties "title" and "description" that should go to the source by default.
+        const componentWithMetadata = component;
+        if (componentWithMetadata.title) {
+            metadata.title = componentWithMetadata.title;
+        }
+        if (componentWithMetadata.description) {
+            metadata.description = componentWithMetadata.description;
+        }
+        return metadata;
+    }
+    /**
+   * Asserts if the event is a valid event on the source.
+   *
+   * Its an invalid event in two cases:
+   *  1. When '_allowedEvent()' api returns undefined
+   *  2. When the event name is not one of the allowed events on the source.
+   *
+   * @param eventName - Name of the event.
+   */ _assertValidEvent(eventName) {
+        if (!this._allowedEvents() || findIndex(this._allowedEvents(), {
+            name: eventName
+        }) === -1) {
+            throw new Error(Text.format(strings.InvalidEvent, eventName, this._src.metadata.title));
+        }
+    }
+    _assertNotDisposed() {
+        if (this.isDisposed) {
+            throw new Error(strings.DynamicDataSourceManagerIsDisposed);
+        }
+    }
+    _assertInitialized() {
+        if (!this._isInitialized) {
+            throw new Error(strings.DynamicDataSourceManagerIsNotInitialized);
+        }
+    }
+    _assertSourceExists() {
+        if (!this._src) {
+            throw new Error(strings.DynamicDataSourceIsNotInitialized);
+        }
+    }
+    /**
+   * Logs a feature event.
+   * @param logFeature - Name of the feature to log.
+   * @param contextualProps - Contextual log properties of the feature event.
+   */ _logFeatureEntry(logFeature, contextualProps) {
+        const isInternal = this._component.manifest.isInternal || false;
+        const logProperties = {
+            alias: this._component.manifest.alias,
+            isInternal: isInternal.toString()
+        };
+        const logEntry = new _LogEntry('DynamicDataSourceManager', logFeature, _LogType.Event, lodash.merge(logProperties, contextualProps));
+        _EngagementLogger.logEventWithLogEntry(logEntry);
+    }
+    constructor(){
+        this._src = undefined;
+        this._isDisposed = false;
+        this._isInitialized = false;
+        this._logSource = _LogSource.create('DynamicDataSourceManager');
+    }
+}
+/**
+ * The Dynamic Data Source Manager is responsible for:
+ *  - Constructing the dynamic data source
+ *  - Allowing initialization of the dynamic data source by a component
+ *  - Allowing data source to update its metadata and notify when data has been updated.
+ *
+ * @public
+ */ export { DynamicDataSourceManager as default };
+
+//# sourceMappingURL=./DynamicDataSourceManager.js.map