bruce-models 7.1.74 → 7.1.76

package/dist/bruce-models.umd.js

@@ -90,6 +90,9 @@
             ECacheKey["EntityHistoricData"] = "entityhistoricdata";
             ECacheKey["EntityHistoricDataRec"] = "entityhistoricdatarec";
             ECacheKey["EntityHistoricDataStats"] = "entityhistoricdatastats";
+            ECacheKey["EntityHistoricDataSeries"] = "entityhistoricdataseries";
+            ECacheKey["EntityHistoricDataAnalysis"] = "entityhistoricdataanalysis";
+            ECacheKey["EntityHistoricDataPage"] = "entityhistoricdatapage";
             ECacheKey["AccountLimits"] = "accountlimits";
         })(ECacheKey = Api.ECacheKey || (Api.ECacheKey = {}));
         // 1 minute.
@@ -4776,9 +4779,16 @@
     })(exports.PathUtils || (exports.PathUtils = {}));
 
     (function (EntityHistoricData) {
+        // How long a v3 historic read stays good when the caller says the data is not changing under it.
+        // Historic records for a past range are immutable until something writes, and a write invalidates
+        // through ClearCacheByEntityIds, so holding them is safe rather than merely convenient.
+        EntityHistoricData.STATIC_CACHE_DURATION = 15 * 60 * 1000;
+        // The live case genuinely gains records as it runs, so it keeps a short window.
+        EntityHistoricData.LIVE_CACHE_DURATION = 30 * 1000;
         /**
          * Returns historic data for an array of Entity IDs.
          * A maximum number of records will be returned per Entity ID, this information is returned in the response.
+         * @deprecated Don't use.
          * @param params
          * @returns
          */
@@ -4874,6 +4884,7 @@
         EntityHistoricData.GetList = GetList;
         /**
          * Returns historic data statistics for an array of Entity IDs.
+         * @deprecated Don't use.
          * @param params
          * @returns
          */
@@ -4913,6 +4924,7 @@
         /**
          * Creates or updates historic data records.
          * Please note that the expected input/output does not include internal fields found inside the "Bruce" attribute.
+         * @deprecated Don't use.
          * @param params
          * @returns
          */
@@ -4950,6 +4962,7 @@
         /**
          * Deletes historic data records for an array of Entity IDs.
          * This deletes all records within a provided key + range.
+         * @deprecated Don't use.
          * @param params
          * @returns
          */
@@ -4983,6 +4996,388 @@
             });
         }
         EntityHistoricData.Delete = Delete;
+        /*
+         * Returns how long a read may be held, based on whether the caller is tracking live data.
+         */
+        function CacheDurationFor(live) {
+            return live === false ? EntityHistoricData.STATIC_CACHE_DURATION : EntityHistoricData.LIVE_CACHE_DURATION;
+        }
+        /*
+         * Shared body for the v3 historic reads, which all post to the same route.
+         */
+        function BuildV3Filter(params) {
+            const { entityIds, entityTypeId, attrKey, dateTimeFrom, dateTimeTo, scenario } = params;
+            const body = {};
+            if (entityIds === null || entityIds === void 0 ? void 0 : entityIds.length) {
+                body["Entity.ID"] = entityIds;
+            }
+            if (entityTypeId) {
+                body["EntityType.ID"] = entityTypeId;
+            }
+            if (attrKey) {
+                body["AttrKey"] = typeof attrKey == "string" ? attrKey : exports.PathUtils.Wrap(attrKey);
+            }
+            if (dateTimeFrom) {
+                body["DateTimeFrom"] = dateTimeFrom;
+            }
+            if (dateTimeTo) {
+                body["DateTimeTo"] = dateTimeTo;
+            }
+            if (scenario) {
+                body["Scenario"] = scenario;
+            }
+            return body;
+        }
+        /**
+         * Returns a histogram of where historic records sit in time, without returning the records.
+         * Answers "when does this data exist" for a timeline in one request, at a cost that does not grow with the number of records.
+         * @param params
+         * @returns
+         */
+        function GetAnalysis(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let { entityIds, entityTypeId, buckets, api, req } = params;
+                if (!(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length) && !entityTypeId) {
+                    return { analysis: [] };
+                }
+                if (!api) {
+                    api = exports.ENVIRONMENT.Api().GetBruceApi();
+                }
+                req = exports.Api.PrepReqParams(req);
+                const body = BuildV3Filter(params);
+                body["Analysis"] = true;
+                if (buckets > 0) {
+                    body["Buckets"] = buckets;
+                }
+                const cacheKey = exports.Api.ECacheKey.EntityHistoricDataAnalysis + exports.Api.ECacheKey.Id + JSON.stringify(body);
+                const cached = api.GetCacheItem(cacheKey, req);
+                if (cached === null || cached === void 0 ? void 0 : cached.found) {
+                    return cached.data;
+                }
+                const prom = api.POST("v3/entities/getHistoric", body, req).then((res) => {
+                    return { analysis: ((res === null || res === void 0 ? void 0 : res.Items) || []) };
+                });
+                api.SetCacheItem({
+                    key: cacheKey,
+                    value: prom,
+                    req: req,
+                    duration: CacheDurationFor(params.live)
+                });
+                return prom;
+            });
+        }
+        EntityHistoricData.GetAnalysis = GetAnalysis;
+        /**
+         * Returns the date range and record count per attribute key, in the shape GetStats returns.
+         * Prefer GetAnalysis directly, which also carries the distribution.
+         * @param params
+         * @returns
+         */
+        function GetRanges(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // One bucket, since the distribution costs work to build and no caller of this reads it.
+                const { analysis } = yield GetAnalysis(Object.assign(Object.assign({}, params), { buckets: 1 }));
+                return {
+                    stats: (analysis || []).map(a => ({
+                        attrKey: a.AttrKey,
+                        dateTimeMin: a.DateTimeMin,
+                        dateTimeMax: a.DateTimeMax,
+                        count: a.Count
+                    }))
+                };
+            });
+        }
+        EntityHistoricData.GetRanges = GetRanges;
+        /**
+         * Returns a numeric attribute aggregated into time buckets, computed in the database.
+         * This is what a chart wants: the reduction happens server-side, so the response is the size of
+         * the plotted series rather than the size of the underlying records.
+         * @param params
+         * @returns
+         */
+        function GetSeries(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let { entityIds, entityTypeId, valueAttrKey, aggregate, interval, api, req } = params;
+                const empty = {
+                    AttrKey: null,
+                    Aggregate: aggregate || "avg",
+                    Interval: interval || "day",
+                    DateTimeMin: null,
+                    DateTimeMax: null,
+                    PointCount: 0,
+                    Points: []
+                };
+                if ((!(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length) && !entityTypeId) || !valueAttrKey) {
+                    return { series: empty };
+                }
+                if (!api) {
+                    api = exports.ENVIRONMENT.Api().GetBruceApi();
+                }
+                req = exports.Api.PrepReqParams(req);
+                const body = BuildV3Filter(params);
+                body["Select"] = { Type: "CALC" };
+                body["selectAttrKey"] = typeof valueAttrKey == "string" ? valueAttrKey : exports.PathUtils.Wrap(valueAttrKey);
+                if (aggregate) {
+                    body["aggregate"] = aggregate;
+                }
+                if (interval) {
+                    body["interval"] = interval;
+                }
+                const cacheKey = exports.Api.ECacheKey.EntityHistoricDataSeries + exports.Api.ECacheKey.Id + JSON.stringify(body);
+                const cached = api.GetCacheItem(cacheKey, req);
+                if (cached === null || cached === void 0 ? void 0 : cached.found) {
+                    return cached.data;
+                }
+                const prom = api.POST("v3/entities/getHistoric", body, req).then((res) => {
+                    var _a;
+                    return { series: (((_a = res === null || res === void 0 ? void 0 : res.Items) === null || _a === void 0 ? void 0 : _a[0]) || empty) };
+                });
+                api.SetCacheItem({
+                    key: cacheKey,
+                    value: prom,
+                    req: req,
+                    duration: CacheDurationFor(params.live)
+                });
+                return prom;
+            });
+        }
+        EntityHistoricData.GetSeries = GetSeries;
+        /**
+         * Returns one aggregated series per Entity, computed in the database in a single request.
+         * @param params
+         * @returns
+         */
+        function GetSeriesByEntity(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let { entityIds, entityTypeId, valueAttrKey, aggregate, interval, api, req } = params;
+                if ((!(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length) && !entityTypeId) || !valueAttrKey) {
+                    return { seriesByIds: {} };
+                }
+                if (!api) {
+                    api = exports.ENVIRONMENT.Api().GetBruceApi();
+                }
+                req = exports.Api.PrepReqParams(req);
+                const body = BuildV3Filter(params);
+                body["Select"] = { Type: "CALC" };
+                body["selectAttrKey"] = typeof valueAttrKey == "string" ? valueAttrKey : exports.PathUtils.Wrap(valueAttrKey);
+                body["GroupBy"] = "Entity";
+                if (aggregate) {
+                    body["aggregate"] = aggregate;
+                }
+                if (interval) {
+                    body["interval"] = interval;
+                }
+                const cacheKey = exports.Api.ECacheKey.EntityHistoricDataSeries + exports.Api.ECacheKey.Id + JSON.stringify(body);
+                const cached = api.GetCacheItem(cacheKey, req);
+                if (cached === null || cached === void 0 ? void 0 : cached.found) {
+                    return cached.data;
+                }
+                const prom = api.POST("v3/entities/getHistoric", body, req).then((res) => {
+                    const seriesByIds = {};
+                    for (const series of ((res === null || res === void 0 ? void 0 : res.Items) || [])) {
+                        const entityId = series === null || series === void 0 ? void 0 : series["Entity.ID"];
+                        if (entityId) {
+                            seriesByIds[entityId] = series;
+                        }
+                    }
+                    return { seriesByIds };
+                });
+                api.SetCacheItem({
+                    key: cacheKey,
+                    value: prom,
+                    req: req,
+                    duration: CacheDurationFor(params.live)
+                });
+                return prom;
+            });
+        }
+        EntityHistoricData.GetSeriesByEntity = GetSeriesByEntity;
+        /**
+         * Returns one page of historic records, newest first by default.
+         * @param params
+         * @returns
+         */
+        function GetPage(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let { entityIds, entityTypeId, pageIndex, pageSize, orderBy, orderDir, api, req } = params;
+                if (!(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length) && !entityTypeId) {
+                    return { items: [], pageIndex: 0, pageSize: 0, sample: 0 };
+                }
+                if (!api) {
+                    api = exports.ENVIRONMENT.Api().GetBruceApi();
+                }
+                req = exports.Api.PrepReqParams(req);
+                const body = BuildV3Filter(params);
+                if (params.sample > 0) {
+                    body["Sample"] = params.sample;
+                }
+                else {
+                    body["PageIndex"] = pageIndex > 0 ? pageIndex : 0;
+                    if (pageSize > 0) {
+                        body["PageSize"] = pageSize;
+                    }
+                }
+                if (orderBy) {
+                    body["OrderBy"] = orderBy;
+                }
+                if (orderDir) {
+                    body["OrderDir"] = orderDir;
+                }
+                const cacheKey = exports.Api.ECacheKey.EntityHistoricDataPage + exports.Api.ECacheKey.Id + JSON.stringify(body);
+                const cached = api.GetCacheItem(cacheKey, req);
+                if (cached === null || cached === void 0 ? void 0 : cached.found) {
+                    return cached.data;
+                }
+                const prom = api.POST("v3/entities/getHistoric", body, req).then((res) => {
+                    var _a, _b, _c;
+                    return {
+                        items: (res === null || res === void 0 ? void 0 : res.Items) || [],
+                        pageIndex: (_a = res === null || res === void 0 ? void 0 : res.PageIndex) !== null && _a !== void 0 ? _a : 0,
+                        pageSize: (_b = res === null || res === void 0 ? void 0 : res.PageSize) !== null && _b !== void 0 ? _b : 0,
+                        sample: (_c = res === null || res === void 0 ? void 0 : res.Sample) !== null && _c !== void 0 ? _c : 0
+                    };
+                });
+                api.SetCacheItem({
+                    key: cacheKey,
+                    value: prom,
+                    req: req,
+                    duration: CacheDurationFor(params.live)
+                });
+                return prom;
+            });
+        }
+        EntityHistoricData.GetPage = GetPage;
+        /*
+         * Converts a v3 record into the flatter shape the render engines consume.
+         */
+        function ToDataRecord(record) {
+            const entity = (record === null || record === void 0 ? void 0 : record.Entity) || {};
+            const bruce = entity.Bruce || {};
+            const data = Object.assign({}, entity);
+            delete data.Bruce;
+            return {
+                attrKey: record === null || record === void 0 ? void 0 : record.AttrKey,
+                dateTime: record === null || record === void 0 ? void 0 : record.DateTime,
+                entityId: record === null || record === void 0 ? void 0 : record["Entity.ID"],
+                data: data,
+                location: bruce.Location,
+                transform: bruce.Transform,
+                boundaries: bruce.Boundaries,
+                geometry: bruce.VectorGeometry
+            };
+        }
+        EntityHistoricData.ToDataRecord = ToDataRecord;
+        /**
+         * Returns records grouped per Entity.
+         * @param params
+         * @returns
+         */
+        function GetRecordsByEntity(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { entityIds, entityTypeId } = params;
+                if (!(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length) && !entityTypeId) {
+                    return { recordsByIds: {}, sample: 0 };
+                }
+                const page = yield GetPage(Object.assign(Object.assign({}, params), { pageSize: params.sample > 0 ? undefined : (params.pageSize || 1000) }));
+                const recordsByIds = {};
+                for (const item of page.items) {
+                    const record = ToDataRecord(item);
+                    if (!record.entityId) {
+                        continue;
+                    }
+                    if (!recordsByIds[record.entityId]) {
+                        recordsByIds[record.entityId] = [];
+                    }
+                    recordsByIds[record.entityId].push(record);
+                }
+                for (const entityId of Object.keys(recordsByIds)) {
+                    recordsByIds[entityId].sort((a, b) => new Date(a.dateTime).getTime() - new Date(b.dateTime).getTime());
+                }
+                return { recordsByIds, sample: page.sample };
+            });
+        }
+        EntityHistoricData.GetRecordsByEntity = GetRecordsByEntity;
+        /*
+         * Assembles a v3 record, nesting the platform managed values where a read reports them.
+         */
+        function BuildRecord(params) {
+            const { entityId, attrKey, dateTime, values, internal, scenario } = params;
+            const entity = Object.assign({}, (values || {}));
+            if (internal) {
+                entity.Bruce = Object.assign(Object.assign({}, (entity.Bruce || {})), internal);
+            }
+            const record = {
+                "Entity.ID": entityId,
+                AttrKey: typeof attrKey == "string" ? attrKey : exports.PathUtils.Wrap(attrKey),
+                DateTime: dateTime,
+                Entity: entity
+            };
+            if (scenario) {
+                record.Scenario = scenario;
+            }
+            return record;
+        }
+        EntityHistoricData.BuildRecord = BuildRecord;
+        /**
+         * Creates or updates historic records.
+         * @param params
+         * @returns
+         */
+        function Save(params) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let { records, scenario, api, req } = params;
+                if (!(records === null || records === void 0 ? void 0 : records.length)) {
+                    return { records: [], warnings: [] };
+                }
+                if (!api) {
+                    api = exports.ENVIRONMENT.Api().GetBruceApi();
+                }
+                const body = { Items: records };
+                if (scenario) {
+                    body["Scenario"] = scenario;
+                }
+                const res = yield api.POST("v3/entities/historic", body, exports.Api.PrepReqParams(req));
+                const entityIds = records.map(r => r["Entity.ID"]).filter((v, i, a) => v && a.indexOf(v) === i);
+                ClearCacheByEntityIds(api, entityIds);
+                for (const attrKey of records.map(r => r.AttrKey).filter((v, i, a) => v && a.indexOf(v) === i)) {
+                    api.Cache.RemoveByContains(exports.Entity.GetHistoricContainsKey(attrKey));
+                }
+                return {
+                    records: ((res === null || res === void 0 ? void 0 : res.Items) || []),
+                    warnings: ((res === null || res === void 0 ? void 0 : res.Warning) || [])
+                };
+            });
+        }
+        EntityHistoricData.Save = Save;
+        /**
+         * Deletes every historic record matching the filter, and reports how many were removed.
+         * The filter is the one the reads accept, so a caller can delete exactly what it just listed.
+         * @param params
+         * @returns
+         */
+        function DeleteRange(params) {
+            var _a;
+            return __awaiter(this, void 0, void 0, function* () {
+                let { entityIds, attrKey, dateTimeFrom, dateTimeTo, scenario, api, req } = params;
+                if (!(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length)) {
+                    return { deleted: 0 };
+                }
+                if (!api) {
+                    api = exports.ENVIRONMENT.Api().GetBruceApi();
+                }
+                if (!scenario && (!attrKey || !dateTimeFrom || !dateTimeTo)) {
+                    throw new Error("Deleting outside a Scenario requires attrKey, dateTimeFrom and dateTimeTo.");
+                }
+                const body = BuildV3Filter(params);
+                const res = yield api.POST("v3/entities/deleteHistoric", body, exports.Api.PrepReqParams(req));
+                if (attrKey) {
+                    api.Cache.RemoveByContains(exports.Entity.GetHistoricContainsKey(typeof attrKey == "string" ? attrKey : exports.PathUtils.Wrap(attrKey)));
+                }
+                ClearCacheByEntityIds(api, entityIds);
+                return { deleted: (_a = res === null || res === void 0 ? void 0 : res.Deleted) !== null && _a !== void 0 ? _a : 0 };
+            });
+        }
+        EntityHistoricData.DeleteRange = DeleteRange;
         function GetListCacheKey(entityIds, attrKey, dateTimeFrom, dateTimeTo) {
             return exports.Api.ECacheKey.EntityHistoricDataRec + exports.Api.ECacheKey.Id + entityIds.join(",") + exports.Api.ECacheKey.Id + attrKey + exports.Api.ECacheKey.Id + dateTimeFrom + exports.Api.ECacheKey.Id + dateTimeTo;
         }
@@ -5001,15 +5396,21 @@
             if (!api || !(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length)) {
                 return;
             }
-            const REC_KEY_PREFIX = exports.Api.ECacheKey.EntityHistoricDataRec + exports.Api.ECacheKey.Id;
-            const STATS_KEY_PREFIX = exports.Api.ECacheKey.EntityHistoricDataStats + exports.Api.ECacheKey.Id;
+            const PREFIXES = [
+                exports.Api.ECacheKey.EntityHistoricDataRec + exports.Api.ECacheKey.Id,
+                exports.Api.ECacheKey.EntityHistoricDataStats + exports.Api.ECacheKey.Id,
+                exports.Api.ECacheKey.EntityHistoricDataSeries + exports.Api.ECacheKey.Id,
+                exports.Api.ECacheKey.EntityHistoricDataAnalysis + exports.Api.ECacheKey.Id,
+                exports.Api.ECacheKey.EntityHistoricDataPage + exports.Api.ECacheKey.Id
+            ];
             api.Cache.RemoveByCallback((key) => {
                 let keyStr = String(key);
-                if (!keyStr.startsWith(STATS_KEY_PREFIX) && !keyStr.startsWith(REC_KEY_PREFIX)) {
+                const prefix = PREFIXES.find(p => keyStr.startsWith(p));
+                if (!prefix) {
                     return false;
                 }
                 // Shorten to speed up the next step.
-                keyStr = keyStr.replace(STATS_KEY_PREFIX, "").replace(REC_KEY_PREFIX, "");
+                keyStr = keyStr.replace(prefix, "");
                 // Look for any matching Entity IDs.
                 for (let i = 0; i < entityIds.length; i++) {
                     const entityId = entityIds[i];
@@ -5996,6 +6397,7 @@
         (function (EOutlineKind) {
             EOutlineKind["Entity"] = "ENTITY";
             EOutlineKind["Attribute"] = "ATTRIBUTE";
+            EOutlineKind["Reference"] = "REFERENCE";
         })(EOutlineKind = Entity.EOutlineKind || (Entity.EOutlineKind = {}));
         /**
          * Returns an entity record for the given entity id.
@@ -19608,7 +20010,7 @@
     })(exports.UrlUtils || (exports.UrlUtils = {}));
 
     // This is updated with the package.json version on build.
-    const VERSION = "7.1.74";
+    const VERSION = "7.1.76";
 
     exports.VERSION = VERSION;
     exports.AbstractApi = AbstractApi;