tm1npm 1.5.3 → 2.0.0

package/src/services/AsyncOperationService.ts

@@ -52,6 +52,12 @@ export interface AsyncOperation {
     result?: any;
     parameters?: Record<string, any>;
     metadata?: Record<string, any>;
+    /**
+     * When true, the operation is tracked with a client-side UUID and the
+     * TM1 server has no record of it. `getAsyncOperationStatus` returns the
+     * cached status instead of polling `/_async('{id}')`.
+     */
+    trackedLocally?: boolean;
 }
 
 /**
@@ -113,30 +119,81 @@ export class AsyncOperationService {
             return operation.status;
         }
 
-        // Poll TM1 server for updated status
+        // Locally tracked operations hold a client-side UUID; the TM1 server
+        // would return 404 for them. Rely on the in-memory cache, which is
+        // populated by background .then()/.catch() callbacks in helpers like
+        // ProcessService.executeWithReturnAsync.
+        if (operation.trackedLocally) {
+            return operation.status;
+        }
+
+        // Poll TM1 server for updated status. /_async('{id}') returns 202 while
+        // the op is pending, and 200/201 with the final operation payload once done.
+        // TM1 v12 may encode embedded failures in the `asyncresult` response header.
         try {
-            const url = formatUrl("/AsyncOperations('{}')", operationId);
-            const response = await this.rest.get(url);
-            const serverStatus = this.mapServerStatus(response.data.Status);
+            const url = formatUrl("/_async('{}')", operationId);
+            const response = await this.rest.get(url, { asyncRequestsMode: false });
+            const serverStatus = this.deriveStatusFromResponse(response);
 
-            // Update operation status
             operation.status = serverStatus;
             if (this.isTerminalStatus(serverStatus)) {
                 operation.endTime = new Date();
-                if (serverStatus === OperationStatus.COMPLETED && response.data.Result) {
-                    operation.result = response.data.Result;
-                } else if (serverStatus === OperationStatus.FAILED && response.data.Error) {
-                    operation.error = response.data.Error;
+                if (serverStatus === OperationStatus.COMPLETED) {
+                    operation.result = response.data;
+                } else if (serverStatus === OperationStatus.FAILED) {
+                    operation.error = this.extractErrorFromResponse(response);
                 }
             }
 
             return serverStatus;
-        } catch (error) {
-            // If server doesn't support AsyncOperations endpoint, return cached status
+        } catch (error: any) {
+            // HTTP 4xx/5xx surfaces as a thrown TM1RestException — treat as a terminal FAILED
+            // so callers stop polling. Network errors (no status) leave cached status intact.
+            // Note: 404 is treated as FAILED here (operation never materialized). This differs
+            // from ProcessService.pollExecuteWithReturn which treats 404 as "not ready yet"
+            // because process async IDs can take a moment to register on the server.
+            const status = error?.status ?? error?.response?.status;
+            if (typeof status === 'number' && status >= 400) {
+                operation.status = OperationStatus.FAILED;
+                operation.endTime = new Date();
+                operation.error = error?.message ?? String(error);
+                return OperationStatus.FAILED;
+            }
             return operation.status;
         }
     }
 
+    private deriveStatusFromResponse(response: any): OperationStatus {
+        if (response.status === 202) {
+            return OperationStatus.RUNNING;
+        }
+        const asyncResult = response.headers?.['asyncresult'];
+        if (typeof asyncResult === 'string') {
+            const embedded = parseInt(asyncResult.trim().split(/\s+/)[0], 10);
+            if (!Number.isNaN(embedded) && (embedded < 200 || embedded >= 300)) {
+                return OperationStatus.FAILED;
+            }
+        }
+        if (response.status === 200 || response.status === 201) {
+            return OperationStatus.COMPLETED;
+        }
+        return OperationStatus.PENDING;
+    }
+
+    private extractErrorFromResponse(response: any): string {
+        const asyncResult = response.headers?.['asyncresult'];
+        if (typeof asyncResult === 'string') {
+            return asyncResult;
+        }
+        if (typeof response.data === 'string') {
+            return response.data;
+        }
+        if (response.data?.error?.message) {
+            return response.data.error.message;
+        }
+        return JSON.stringify(response.data);
+    }
+
     /**
      * List all active async operations
      *
@@ -178,11 +235,10 @@ export class AsyncOperationService {
         this.stopPolling(operationId);
 
         try {
-            // Try to cancel on server if supported
-            const url = formatUrl("/AsyncOperations('{}')/Cancel", operationId);
-            await this.rest.post(url, {});
+            const url = formatUrl("/_async('{}')", operationId);
+            await this.rest.delete(url, { asyncRequestsMode: false });
         } catch (error) {
-            // If server doesn't support cancellation, just mark as cancelled locally
+            console.warn(`Failed to cancel async operation ${operationId} on server:`, error);
         }
 
         // Update operation status
@@ -243,6 +299,9 @@ export class AsyncOperationService {
     public async createAsyncOperation(definition: AsyncOperationDefinition): Promise<string> {
         const operationId = this.generateOperationId();
 
+        // generateOperationId produces a client-side UUID; the server has no
+        // record of it, so polling /_async('{id}') would 404. Mark as locally
+        // tracked so getAsyncOperationStatus returns the cached status instead.
         const operation: AsyncOperation = {
             id: operationId,
             type: definition.type,
@@ -250,7 +309,8 @@ export class AsyncOperationService {
             status: OperationStatus.PENDING,
             startTime: new Date(),
             parameters: definition.parameters,
-            metadata: definition.metadata
+            metadata: definition.metadata,
+            trackedLocally: true
         };
 
         this.operations.set(operationId, operation);
@@ -442,19 +502,6 @@ export class AsyncOperationService {
                status === OperationStatus.TIMEOUT;
     }
 
-    private mapServerStatus(serverStatus: string): OperationStatus {
-        const statusMap: Record<string, OperationStatus> = {
-            'Pending': OperationStatus.PENDING,
-            'Running': OperationStatus.RUNNING,
-            'CompletedSuccessfully': OperationStatus.COMPLETED,
-            'CompletedWithErrors': OperationStatus.FAILED,
-            'Cancelled': OperationStatus.CANCELLED,
-            'Timeout': OperationStatus.TIMEOUT
-        };
-
-        return statusMap[serverStatus] || OperationStatus.PENDING;
-    }
-
     private stopPolling(operationId: string): void {
         const intervalId = this.pollingIntervals.get(operationId);
         if (intervalId) {

package/src/services/ElementService.ts

@@ -4,9 +4,15 @@ import { ObjectService } from './ObjectService';
 import { Element, ElementType } from '../objects/Element';
 import { ElementAttribute } from '../objects/ElementAttribute';
 import { Process } from '../objects/Process';
+import { ProcessService } from './ProcessService';
+import { HierarchyService } from './HierarchyService';
+import { CellService } from './CellService';
 import {
     formatUrl,
-    CaseAndSpaceInsensitiveDict
+    escapeODataValue,
+    requireDataAdmin,
+    CaseAndSpaceInsensitiveDict,
+    CaseAndSpaceInsensitiveSet
 } from '../utils/Utils';
 
 export interface ElementsDataFrameOptions {
@@ -408,6 +414,21 @@ export class ElementService extends ObjectService {
         return await this.rest.post(url, JSON.stringify(body));
     }
 
+    /**
+     * Add multiple element attributes in bulk
+     */
+    public async addElementAttributes(
+        dimensionName: string,
+        hierarchyName: string,
+        elementAttributes: ElementAttribute[]
+    ): Promise<AxiosResponse> {
+        const url = formatUrl(
+            "/Dimensions('{}')/Hierarchies('{}')/ElementAttributes",
+            dimensionName, hierarchyName);
+        const body = elementAttributes.map(ea => ea.bodyAsDict);
+        return await this.rest.post(url, JSON.stringify(body));
+    }
+
     /**
      * Delete multiple elements in bulk
      */
@@ -1204,4 +1225,304 @@ export class ElementService extends ObjectService {
         
         return elements.map(name => `[${dimensionName}].[${hierarchy}].[${name}]`);
     }
+
+    public async getNumberOfConsolidatedElements(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<number> {
+        return this._getElementCountWithFilter(dimensionName, hierarchyName, `Type eq ${ElementType.CONSOLIDATED}`);
+    }
+
+    public async getNumberOfLeafElements(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<number> {
+        return this._getElementCountWithFilter(dimensionName, hierarchyName, `Type ne ${ElementType.CONSOLIDATED}`);
+    }
+
+    public async getNumberOfNumericElements(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<number> {
+        return this._getElementCountWithFilter(dimensionName, hierarchyName, `Type eq ${ElementType.NUMERIC}`);
+    }
+
+    public async getNumberOfStringElements(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<number> {
+        return this._getElementCountWithFilter(dimensionName, hierarchyName, `Type eq ${ElementType.STRING}`);
+    }
+
+    /**
+     * Get element types from all hierarchies in a single API call
+     */
+    public async getElementTypesFromAllHierarchies(
+        dimensionName: string,
+        skipConsolidations: boolean = false
+    ): Promise<CaseAndSpaceInsensitiveDict<string>> {
+        let url = formatUrl(
+            "/Dimensions('{}')?$expand=Hierarchies($select=Elements;$expand=Elements($select=Name,Type",
+            dimensionName
+        );
+        url += skipConsolidations ? ";$filter=Type ne 3))" : "))";
+
+        const response = await this.rest.get(url);
+        const result = new CaseAndSpaceInsensitiveDict<string>();
+        for (const hierarchy of response.data.Hierarchies) {
+            for (const element of hierarchy.Elements) {
+                result.set(element.Name, element.Type);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Check if the element attributes cube exists for a dimension
+     */
+    public async attributeCubeExists(dimensionName: string): Promise<boolean> {
+        const url = formatUrl("/Cubes('{}')", Element.ELEMENT_ATTRIBUTES_PREFIX + dimensionName);
+        return this._exists(url);
+    }
+
+    /**
+     * Get parent mapping for all elements in a hierarchy
+     */
+    public async getParentsOfAllElements(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<{ [elementName: string]: string[] }> {
+        const url = formatUrl(
+            "/Dimensions('{}')/Hierarchies('{}')/Elements?$select=Name&$expand=Parents($select=Name)",
+            dimensionName, hierarchyName
+        );
+        const response = await this.rest.get(url);
+        const result: { [elementName: string]: string[] } = {};
+        for (const child of response.data.value) {
+            result[child.Name] = (child.Parents || []).map((p: any) => p.Name);
+        }
+        return result;
+    }
+
+    /**
+     * Get the canonical/principal name of an element (resolves aliases)
+     */
+    public async getElementPrincipalName(
+        dimensionName: string,
+        hierarchyName: string,
+        elementName: string
+    ): Promise<string> {
+        const element = await this.get(dimensionName, hierarchyName, elementName);
+        return element.name;
+    }
+
+    /**
+     * Check if one element is a direct parent of another
+     *
+     * Unlike the related function in TM1 (ELISPAR or ElementIsParent), this function will return false
+     * if an invalid element is passed. An invalid dimension or hierarchy will cause the underlying
+     * REST call to throw (the error propagates from the TM1 server).
+     */
+    public async elementIsParent(
+        dimensionName: string,
+        hierarchyName: string,
+        parentName: string,
+        elementName: string
+    ): Promise<boolean> {
+        const mdx = this._buildDrillIntersectionMdx(
+            dimensionName, hierarchyName,
+            parentName, elementName,
+            'TM1DrillDownMember', false
+        );
+        const cardinality = await this._getMdxSetCardinality(mdx);
+        return cardinality > 0;
+    }
+
+    /**
+     * Check if one element is an ancestor of another
+     *
+     * Unlike the related function in TM1 (ELISANC or ElementIsAncestor), this function will return false
+     * if an invalid element is passed; but will raise an exception if an invalid dimension or hierarchy is passed.
+     *
+     * For method you can pass three values:
+     * - 'TI' performs best, but requires admin permissions
+     * - 'TM1DrillDownMember' performs well when element is a leaf
+     * - 'Descendants' performs well when ancestorName and elementName are Consolidations
+     *
+     * If no method is passed, defaults to 'TI' for admin users, 'TM1DrillDownMember' otherwise.
+     * Note: isAdmin is determined from RestService state; if not set, defaults to 'TM1DrillDownMember'.
+     */
+    public async elementIsAncestor(
+        dimensionName: string,
+        hierarchyName: string,
+        ancestorName: string,
+        elementName: string,
+        method?: string
+    ): Promise<boolean> {
+        if (!method) {
+            method = this.isAdmin ? 'TI' : 'TM1DrillDownMember';
+        }
+
+        if (method.toUpperCase() === 'TI') {
+            if (await this._elementIsAncestorTi(dimensionName, hierarchyName, elementName, ancestorName)) {
+                return true;
+            }
+            if (await this.hierarchyExists(dimensionName, hierarchyName)) {
+                return false;
+            }
+            throw new Error(`Hierarchy: '${hierarchyName}' does not exist in dimension: '${dimensionName}'`);
+        }
+
+        if (method.toUpperCase() === 'DESCENDANTS' || method.toUpperCase() === 'TM1DRILLDOWNMEMBER') {
+            if (!await this.exists(dimensionName, hierarchyName, elementName)) {
+                if (!await this.hierarchyExists(dimensionName, hierarchyName)) {
+                    throw new Error(`Hierarchy '${hierarchyName}' does not exist in dimension '${dimensionName}'`);
+                }
+                return false;
+            }
+        }
+
+        const mdx = this._buildDrillIntersectionMdx(
+            dimensionName, hierarchyName,
+            ancestorName, elementName,
+            method, true
+        );
+        const cardinality = await this._getMdxSetCardinality(mdx);
+        return cardinality > 0;
+    }
+
+    /**
+     * Remove a single edge from a hierarchy
+     */
+    public async removeEdge(
+        dimensionName: string,
+        hierarchyName: string,
+        parentName: string,
+        componentName: string
+    ): Promise<AxiosResponse> {
+        const url = formatUrl(
+            "/Dimensions('{}')/Hierarchies('{}')/Elements('{}')/Edges(ParentName='{}',ComponentName='{}')",
+            dimensionName, hierarchyName, parentName, parentName, componentName
+        );
+        return this.rest.delete(url);
+    }
+
+    /**
+     * Check if a hierarchy exists in a dimension (convenience delegation to HierarchyService)
+     */
+    public async hierarchyExists(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<boolean> {
+        const hierarchyService = new HierarchyService(this.rest);
+        return hierarchyService.exists(dimensionName, hierarchyName);
+    }
+
+    /**
+     * Get all element names and alias values for leaf elements as a case-and-space-insensitive set
+     */
+    public async getAllLeafElementIdentifiers(
+        dimensionName: string,
+        hierarchyName: string
+    ): Promise<CaseAndSpaceInsensitiveSet> {
+        const mdxElements = `{ Tm1FilterByLevel ( { Tm1SubsetAll ([${dimensionName}].[${hierarchyName}]) } , 0 ) }`;
+
+        const aliasAttributes = await this.getAliasElementAttributes(dimensionName, hierarchyName);
+
+        if (aliasAttributes.length === 0) {
+            const result = await this.executeSetMdx(mdxElements, undefined, ['Name'], null, null);
+            const identifiers = new CaseAndSpaceInsensitiveSet();
+            for (const record of result) {
+                identifiers.add(record[0].Name);
+            }
+            return identifiers;
+        }
+
+        const attrMdx = aliasAttributes.map(a =>
+            `[}ElementAttributes_${dimensionName}].[}ElementAttributes_${dimensionName}].[${a}]`
+        ).join(',');
+        const mdx = `SELECT ${mdxElements} ON ROWS, {${attrMdx}} ON COLUMNS FROM [}ElementAttributes_${dimensionName}]`;
+
+        return this._retrieveMdxRowsAndCellValuesAsStringSet(mdx);
+    }
+
+    private async _getElementCountWithFilter(
+        dimensionName: string,
+        hierarchyName: string,
+        filter: string
+    ): Promise<number> {
+        const baseUrl = formatUrl(
+            "/Dimensions('{}')/Hierarchies('{}')/Elements/$count",
+            dimensionName, hierarchyName
+        );
+        const url = `${baseUrl}?$filter=${filter}`;
+        const response = await this.rest.get(url);
+        return parseInt(response.data) || 0;
+    }
+
+    private _buildDrillIntersectionMdx(
+        dimensionName: string,
+        hierarchyName: string,
+        firstElementName: string,
+        secondElementName: string,
+        mdxMethod: string,
+        recursive: boolean
+    ): string {
+        const first = `[${dimensionName}].[${hierarchyName}].[${firstElementName}]`;
+        const second = `[${dimensionName}].[${hierarchyName}].[${secondElementName}]`;
+
+        let drillSet: string;
+        if (mdxMethod.toUpperCase() === 'TM1DRILLDOWNMEMBER') {
+            drillSet = recursive
+                ? `{TM1DRILLDOWNMEMBER({${first}}, ALL, RECURSIVE)}`
+                : `{TM1DRILLDOWNMEMBER({${first}}, ALL)}`;
+        } else if (mdxMethod.toUpperCase() === 'DESCENDANTS') {
+            drillSet = `{DESCENDANTS(${first}, ${second}.Level, SELF)}`;
+        } else {
+            throw new Error("Invalid MDX Drill Method. Options: 'TM1DrillDownMember' or 'Descendants'");
+        }
+
+        return `INTERSECT(${drillSet}, {${second}})`;
+    }
+
+    private async _getMdxSetCardinality(mdx: string): Promise<number> {
+        const url = '/ExecuteMDXSetExpression?$select=Cardinality';
+        const payload = { MDX: mdx };
+        const response = await this.rest.post(url, JSON.stringify(payload));
+        return response.data.Cardinality || 0;
+    }
+
+    @requireDataAdmin
+    private async _elementIsAncestorTi(
+        dimensionName: string,
+        hierarchyName: string,
+        elementName: string,
+        ancestorName: string
+    ): Promise<boolean> {
+        const processService = new ProcessService(this.rest);
+        const code = `ElementIsAncestor('${escapeODataValue(dimensionName)}', '${escapeODataValue(hierarchyName)}', '${escapeODataValue(ancestorName)}', '${escapeODataValue(elementName)}')=1`;
+        return processService.evaluateBooleanTiExpression(code);
+    }
+
+    private async _retrieveMdxRowsAndCellValuesAsStringSet(mdx: string): Promise<CaseAndSpaceInsensitiveSet> {
+        const cellService = new CellService(this.rest);
+        const { rows, values } = await cellService.executeMdxRowsAndValues(mdx);
+        const result = new CaseAndSpaceInsensitiveSet();
+
+        for (const row of rows) {
+            for (const name of row) {
+                if (name) {
+                    result.add(name);
+                }
+            }
+        }
+
+        for (const value of values) {
+            if (value && typeof value === 'string' && value.trim() !== '') {
+                result.add(value);
+            }
+        }
+
+        return result;
+    }
 }

package/src/services/FileService.ts

@@ -1,6 +1,6 @@
 import path from 'path';
-import { AxiosRequestConfig, AxiosResponse } from 'axios';
-import { RestService } from './RestService';
+import { AxiosResponse } from 'axios';
+import { RequestOptions, RestService } from './RestService';
 import { ObjectService } from './ObjectService';
 import { verifyVersion } from '../utils/Utils';
 
@@ -227,7 +227,7 @@ export class FileService extends ObjectService {
     }
 
     private async uploadFileContentWithoutMpu(url: string, content: Buffer): Promise<AxiosResponse> {
-        const config: AxiosRequestConfig = {
+        const config: RequestOptions = {
             headers: this.binaryHttpHeader
         };
         return await this.rest.put(url, content, config);