bruce-models 7.1.74 → 7.1.76

package/dist/bruce-models.es5.js

@@ -85,6 +85,9 @@ var Api;
         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.
@@ -4841,9 +4844,16 @@ var PathUtils;
 
 var EntityHistoricData;
 (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
      */
@@ -4939,6 +4949,7 @@ var EntityHistoricData;
     EntityHistoricData.GetList = GetList;
     /**
      * Returns historic data statistics for an array of Entity IDs.
+     * @deprecated Don't use.
      * @param params
      * @returns
      */
@@ -4978,6 +4989,7 @@ var EntityHistoricData;
     /**
      * 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
      */
@@ -5015,6 +5027,7 @@ var EntityHistoricData;
     /**
      * 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
      */
@@ -5048,6 +5061,388 @@ var EntityHistoricData;
         });
     }
     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 : 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 = ENVIRONMENT.Api().GetBruceApi();
+            }
+            req = Api.PrepReqParams(req);
+            const body = BuildV3Filter(params);
+            body["Analysis"] = true;
+            if (buckets > 0) {
+                body["Buckets"] = buckets;
+            }
+            const cacheKey = Api.ECacheKey.EntityHistoricDataAnalysis + 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 = ENVIRONMENT.Api().GetBruceApi();
+            }
+            req = Api.PrepReqParams(req);
+            const body = BuildV3Filter(params);
+            body["Select"] = { Type: "CALC" };
+            body["selectAttrKey"] = typeof valueAttrKey == "string" ? valueAttrKey : PathUtils.Wrap(valueAttrKey);
+            if (aggregate) {
+                body["aggregate"] = aggregate;
+            }
+            if (interval) {
+                body["interval"] = interval;
+            }
+            const cacheKey = Api.ECacheKey.EntityHistoricDataSeries + 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 = ENVIRONMENT.Api().GetBruceApi();
+            }
+            req = Api.PrepReqParams(req);
+            const body = BuildV3Filter(params);
+            body["Select"] = { Type: "CALC" };
+            body["selectAttrKey"] = typeof valueAttrKey == "string" ? valueAttrKey : PathUtils.Wrap(valueAttrKey);
+            body["GroupBy"] = "Entity";
+            if (aggregate) {
+                body["aggregate"] = aggregate;
+            }
+            if (interval) {
+                body["interval"] = interval;
+            }
+            const cacheKey = Api.ECacheKey.EntityHistoricDataSeries + 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 = ENVIRONMENT.Api().GetBruceApi();
+            }
+            req = 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 = Api.ECacheKey.EntityHistoricDataPage + 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 : 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 = ENVIRONMENT.Api().GetBruceApi();
+            }
+            const body = { Items: records };
+            if (scenario) {
+                body["Scenario"] = scenario;
+            }
+            const res = yield api.POST("v3/entities/historic", body, 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(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 = 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, Api.PrepReqParams(req));
+            if (attrKey) {
+                api.Cache.RemoveByContains(Entity.GetHistoricContainsKey(typeof attrKey == "string" ? attrKey : 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 Api.ECacheKey.EntityHistoricDataRec + Api.ECacheKey.Id + entityIds.join(",") + Api.ECacheKey.Id + attrKey + Api.ECacheKey.Id + dateTimeFrom + Api.ECacheKey.Id + dateTimeTo;
     }
@@ -5066,15 +5461,21 @@ var EntityHistoricData;
         if (!api || !(entityIds === null || entityIds === void 0 ? void 0 : entityIds.length)) {
             return;
         }
-        const REC_KEY_PREFIX = Api.ECacheKey.EntityHistoricDataRec + Api.ECacheKey.Id;
-        const STATS_KEY_PREFIX = Api.ECacheKey.EntityHistoricDataStats + Api.ECacheKey.Id;
+        const PREFIXES = [
+            Api.ECacheKey.EntityHistoricDataRec + Api.ECacheKey.Id,
+            Api.ECacheKey.EntityHistoricDataStats + Api.ECacheKey.Id,
+            Api.ECacheKey.EntityHistoricDataSeries + Api.ECacheKey.Id,
+            Api.ECacheKey.EntityHistoricDataAnalysis + Api.ECacheKey.Id,
+            Api.ECacheKey.EntityHistoricDataPage + 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];
@@ -6074,6 +6475,7 @@ var Entity;
     (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.
@@ -19961,7 +20363,7 @@ var UrlUtils;
 })(UrlUtils || (UrlUtils = {}));
 
 // This is updated with the package.json version on build.
-const VERSION = "7.1.74";
+const VERSION = "7.1.76";
 
 export { VERSION, Account, AccountAudit, AccountConcept, AccountFeatures, AccountInvite, AccountLimits, AccountTemplate, AccountType, AnnDocument, AbstractApi, Api, ApiGetters, BruceApi, GlobalApi, GuardianApi, Assembly, Calculator, ChangeSet, ClientFile, Bounds, BruceEvent, BruceVariable, CacheControl, Camera, Cartes, Carto, Color, DelayQueue, GeoJson, Geometry, LRUCache, UTC, CustomForm, DashboardView, DataFeed, DataLab, DataLabGroup, DataSource, DataTransform, Comment, Entity, EntityAttachment, EntityAttachmentType, EntityAttribute, EntityComment, EntityCoords, EntityHistoricData, EntityLink, EntityLod, EntityLodCategory, EntityRelation, EntityRelationType, EntitySource, EntityTableView, EntityTag, EntityType, EntityTypeTrigger, Ontology, OntologyDocument, ENVIRONMENT, ExportBrz, ExportUsd, ImportAssembly, ImportCad, ImportCsv, ImportGeoJson, ImportJson, ImportKml, ImportLcc, ImportedFile, Uploader, Markup, UIMarkup, NAVIGATOR_CHAT_EVENT_ENTITY_HIGHLIGHT_APPLIED, NAVIGATOR_CHAT_EVENT_SCENE_CONTEXT_PREFETCHED, NavigatorChatClient, NavigatorMcpWebSocketClient, Plugin, ProgramKey, MenuItem, ProjectView, ProjectViewBookmark, ProjectViewBookmarkGroup, ProjectViewLegacy, ProjectViewLegacyBookmark, ProjectViewLegacyTile, ProjectViewTile, ZoomControl, Scenario, HostingLocation, MessageBroker, PendingAction, RecordChangeFeed, Style, Tileset, Tracking, Permission, Session, User, UserGroup, UserMfaMethod, EncryptUtils, MathUtils, ObjectUtils, PathUtils, UrlUtils };
 //# sourceMappingURL=bruce-models.es5.js.map