tm1npm 1.5.3 → 2.0.0

package/src/services/ProcessService.ts

@@ -1,13 +1,38 @@
 import { AxiosResponse } from 'axios';
 import { v4 as uuidv4 } from 'uuid';
-import { RestService } from './RestService';
+import { RequestOptions, RestService } from './RestService';
 import { ObjectService } from './ObjectService';
 import { Process } from '../objects/Process';
-import { ProcessDebugBreakpoint } from '../objects/ProcessDebugBreakpoint';
+import { ProcessDebugBreakpoint, BreakPointType, HitMode } from '../objects/ProcessDebugBreakpoint';
 import { TM1RestException, TM1Exception } from '../exceptions/TM1Exception';
 import { formatUrl, lowerAndDropSpaces } from '../utils/Utils';
 import { OperationStatus, OperationType } from './AsyncOperationService';
 
+export interface CompileSyntaxError {
+    LineNumber: number;
+    Message: string;
+}
+
+interface ProcessExecuteBody {
+    Parameters?: Array<{ Name: string; Value: unknown }>;
+}
+
+interface ProcessExecuteSummary {
+    ProcessExecuteStatusCode: string;
+    ErrorLogFile?: { Filename?: string } | null;
+}
+
+interface ValidationError {
+    line: number;
+    message: string;
+    severity: string;
+}
+
+interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+}
+
 export class ProcessService extends ObjectService {
     /** Service to handle Object Updates for TI Processes
      * 
@@ -74,7 +99,7 @@ export class ProcessService extends ObjectService {
 
         const response = await this.rest.get(url);
         const responseAsDict = response.data;
-        return responseAsDict.value.map((p: any) => Process.fromDict(p));
+        return responseAsDict.value.map((p: Record<string, unknown>) => Process.fromDict(p));
     }
 
     public async getAllNames(skipControlProcesses: boolean = false): Promise<string[]> {
@@ -88,7 +113,7 @@ export class ProcessService extends ObjectService {
         const url = "/Processes?$select=Name" + (skipControlProcesses ? modelProcessFilter : "");
 
         const response = await this.rest.get(url);
-        const processes = response.data.value.map((process: any) => process.Name);
+        const processes = response.data.value.map((process: { Name: string }) => process.Name);
         return processes;
     }
 
@@ -169,8 +194,8 @@ export class ProcessService extends ObjectService {
          * :return: response
          */
         const url = formatUrl("/Processes('{}')/tm1.Execute", processName);
-        
-        const body: any = {};
+
+        const body: ProcessExecuteBody = {};
         if (parameters && Object.keys(parameters).length > 0) {
             body.Parameters = Object.entries(parameters).map(([name, value]) => ({
                 Name: name,
@@ -194,8 +219,8 @@ export class ProcessService extends ObjectService {
          * :return: response including execution details
          */
         const url = formatUrl("/Processes('{}')/tm1.ExecuteWithReturn?$expand=*", processName);
-        
-        const body: any = {};
+
+        const body: ProcessExecuteBody = {};
         if (parameters && Object.keys(parameters).length > 0) {
             body.Parameters = Object.entries(parameters).map(([name, value]) => ({
                 Name: name,
@@ -203,9 +228,9 @@ export class ProcessService extends ObjectService {
             }));
         }
 
-        const config: any = {};
+        const config: RequestOptions = {};
         if (timeout) {
-            config.timeout = timeout * 1000;
+            config.timeout = timeout;
         }
 
         return await this.rest.post(url, JSON.stringify(body), config);
@@ -221,105 +246,53 @@ export class ProcessService extends ObjectService {
         return await this.rest.post(url, '{}');
     }
 
-    public async compileProcess(processName: string): Promise<{success: boolean, errors: string[]}> {
-        /** Compile a process and return detailed compilation results
+    public async compileProcess(process: Process): Promise<CompileSyntaxError[]> {
+        /** Compile an unbound process and return syntax errors
          *
-         * :param process_name: name of the process
-         * :return: compilation result with success status and error details
+         * :param process: Instance of .Process class
+         * :return: list of syntax errors (empty if successful)
          */
-        try {
-            const response = await this.compile(processName);
-            
-            // Check if compilation was successful
-            if (response.status === 200) {
-                return {
-                    success: true,
-                    errors: []
-                };
-            } else {
-                return {
-                    success: false,
-                    errors: [response.statusText || 'Compilation failed']
-                };
-            }
-        } catch (error: any) {
-            const errorMessage = error.response?.data?.error?.message || error.message || 'Unknown compilation error';
-            return {
-                success: false,
-                errors: [errorMessage]
-            };
-        }
+        const url = '/CompileProcess';
+        const payload = { Process: process.bodyAsDict };
+        const response = await this.rest.post(url, JSON.stringify(payload));
+        return response.data.value;
     }
 
     /**
-     * Poll execution status for async process execution
+     * Poll for async execution result
+     *
+     * :param asyncId: async operation ID returned from executeWithReturn with returnAsyncId=true
+     * :return: tuple of [success, status, errorLogFile] or null if not ready
      */
-    public async pollExecuteWithReturn(
-        processName: string,
-        parameters?: Record<string, any>,
-        timeout: number = 300,
-        pollInterval: number = 5
-    ): Promise<any> {
-        /** Execute process asynchronously and poll for completion
-         *
-         * :param process_name: name of the process
-         * :param parameters: dictionary of process parameters
-         * :param timeout: maximum time to wait for completion (seconds)
-         * :param poll_interval: time between status checks (seconds)
-         * :return: execution result when completed
-         */
-        
-        // Start async execution
-        const executeUrl = formatUrl("/Processes('{}')/tm1.ExecuteAsync", processName);
-        const body: any = {};
-        
-        if (parameters && Object.keys(parameters).length > 0) {
-            body.Parameters = Object.entries(parameters).map(([name, value]) => ({
-                Name: name,
-                Value: value
-            }));
-        }
-
-        const executeResponse = await this.rest.post(executeUrl, JSON.stringify(body));
-        const executionId = executeResponse.data.ID || executeResponse.data.ExecutionId;
-        
-        if (!executionId) {
-            throw new TM1Exception('Failed to start async process execution');
-        }
-
-        // Poll for completion
-        const startTime = Date.now();
-        const maxTime = timeout * 1000;
-        
-        while (Date.now() - startTime < maxTime) {
-            try {
-                // Check execution status
-                const statusUrl = `/ExecutionStatus('${executionId}')`;
-                const statusResponse = await this.rest.get(statusUrl);
-                const status = statusResponse.data;
-                
-                if (status.Status === 'Completed') {
-                    // Get execution results
-                    const resultUrl = `/ExecutionResults('${executionId}')`;
-                    const resultResponse = await this.rest.get(resultUrl);
-                    return resultResponse.data;
-                } else if (status.Status === 'Failed') {
-                    throw new TM1Exception(`Process execution failed: ${status.ErrorMessage || 'Unknown error'}`);
-                }
-                
-                // Wait before next poll
-                await new Promise(resolve => setTimeout(resolve, pollInterval * 1000));
-                
-            } catch (error) {
-                if (error instanceof TM1Exception) {
-                    throw error;
-                }
-                // If status check fails, wait and retry
-                await new Promise(resolve => setTimeout(resolve, pollInterval * 1000));
+    public async pollExecuteWithReturn(asyncId: string): Promise<[boolean, string, string | null] | null> {
+        try {
+            const response = await this.rest.retrieve_async_response(asyncId);
+            // tm1py returns None while the async op is still in-flight (status 202).
+            if (response.status !== 200 && response.status !== 201) {
+                return null;
             }
+            // TODO: tm1py handles TM1 < v11 binary-wrapped responses via
+            // build_response_from_binary_response. Add support if needed.
+            return this._executeWithReturnParseResponse(response.data);
+        } catch (error) {
+            // 404 means the async resource hasn't materialized yet — return null
+            // so the caller can retry. 202 means still running. Both are
+            // retryable, unlike AsyncOperationService which treats 404 as
+            // terminal FAILED for locally-tracked operations.
+            const err = error as { status?: number; response?: { status?: number } };
+            const status = err?.status ?? err?.response?.status;
+            if (status === 202 || status === 404) {
+                return null;
+            }
+            throw error;
         }
-        
-        throw new TM1Exception(`Process execution timed out after ${timeout} seconds`);
+    }
+
+    private _executeWithReturnParseResponse(executionSummary: ProcessExecuteSummary): [boolean, string, string | null] {
+        const success = executionSummary.ProcessExecuteStatusCode === 'CompletedSuccessfully';
+        const status = executionSummary.ProcessExecuteStatusCode;
+        const errorLogFile = executionSummary.ErrorLogFile?.Filename ?? null;
+        return [success, status, errorLogFile];
     }
 
     public async executeProcessWithReturn(
@@ -347,7 +320,7 @@ export class ProcessService extends ObjectService {
         return '';
     }
 
-    public async getProcessDebugBreakpoints(debugId: string): Promise<ProcessDebugBreakpoint[]> {
+    public async debugGetBreakpoints(debugId: string): Promise<ProcessDebugBreakpoint[]> {
         /** Get debug breakpoints for a debug context
          *
          * :param debugId: debug session ID
@@ -355,28 +328,27 @@ export class ProcessService extends ObjectService {
          */
         const url = formatUrl("/ProcessDebugContexts('{}')/Breakpoints", debugId);
         const response = await this.rest.get(url);
-        return response.data.value.map((bp: any) => ProcessDebugBreakpoint.fromDict(bp));
+        return response.data.value.map((bp: Record<string, unknown>) => ProcessDebugBreakpoint.fromDict(bp));
     }
 
-    public async createProcessDebugBreakpoint(
+    public async debugAddBreakpoint(
         debugId: string,
         breakpoint: ProcessDebugBreakpoint
     ): Promise<AxiosResponse> {
-        /** Create a debug breakpoint in a debug context
+        /** Add a single breakpoint to a debug context (delegates to debugAddBreakpoints)
          *
          * :param debugId: debug session ID
          * :param breakpoint: ProcessDebugBreakpoint object
          * :return: response
          */
-        const url = formatUrl("/ProcessDebugContexts('{}')/Breakpoints", debugId);
-        return await this.rest.post(url, breakpoint.body);
+        return this.debugAddBreakpoints(debugId, [breakpoint]);
     }
 
-    public async deleteProcessDebugBreakpoint(
+    public async debugRemoveBreakpoint(
         debugId: string,
         breakpointId: number
     ): Promise<AxiosResponse> {
-        /** Delete a debug breakpoint from a debug context
+        /** Remove a breakpoint from a debug context
          *
          * :param debugId: debug session ID
          * :param breakpointId: ID of the breakpoint
@@ -588,7 +560,7 @@ export class ProcessService extends ObjectService {
         }
 
         const response = await this.rest.get(url);
-        return response.data.value.map((log: any) => log.Filename);
+        return response.data.value.map((log: { Filename: string }) => log.Filename);
     }
 
     public async getErrorLogFilenames(
@@ -675,7 +647,7 @@ export class ProcessService extends ObjectService {
         }
 
         const response = await this.rest.get(url);
-        return response.data.value.map((process: any) => process.Name);
+        return response.data.value.map((process: { Name: string }) => process.Name);
     }
 
     public async updateOrCreate(process: Process): Promise<AxiosResponse> {
@@ -729,7 +701,7 @@ export class ProcessService extends ObjectService {
             processName
         );
 
-        const body: any = {};
+        const body: ProcessExecuteBody = {};
         if (parameters && Object.keys(parameters).length > 0) {
             body.Parameters = Object.entries(parameters).map(([name, value]) => ({
                 Name: name,
@@ -737,12 +709,14 @@ export class ProcessService extends ObjectService {
             }));
         }
 
-        const config: any = {};
+        const config: RequestOptions = {};
         if (timeout) {
-            config.timeout = timeout * 1000;
+            config.timeout = timeout;
         }
 
-        const response = await this.rest.post(url, JSON.stringify(body), config);
+        // rest.post returns AxiosResponse | string (string only when caller
+        // opts into returnAsyncId). debugProcess never does, so narrow.
+        const response = (await this.rest.post(url, JSON.stringify(body), config)) as AxiosResponse;
         return response.data;
     }
 
@@ -859,6 +833,79 @@ export class ProcessService extends ObjectService {
         }
     }
 
+    /**
+     * Evaluate a TI expression and return the string result.
+     *
+     * Creates a temporary process with sFunc = {formula}, compiles it,
+     * starts a debug session, adds a data breakpoint on sFunc, continues
+     * execution to evaluate, reads the result, and cleans up.
+     */
+    public async evaluateTiExpression(formula: string): Promise<string> {
+        // tm1py uses formula[formula.find("=") + 1:] which greedily strips at the
+        // first "=" anywhere in the string. We use a regex to only strip a leading
+        // "=" prefix (e.g. "=NOW;" → "NOW;"), avoiding mangling formulas with
+        // embedded "=" (e.g. comparisons like "IF(1=1,...)").
+        formula = formula.replace(/^\s*=\s*/, '');
+
+        // Ensure semicolon at end
+        if (!formula.trim().endsWith(';')) {
+            formula += ';';
+        }
+
+        const prologList = [`sFunc = ${formula}`, "sDebug='Stop';"];
+        const processName = `}TM1py${uuidv4()}`;
+        const p = new Process(
+            processName,
+            false,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            Process.AUTO_GENERATED_STATEMENTS + prologList.join('\r\n'),
+            '',
+            '',
+            ''
+        );
+
+        const syntaxErrors = await this.compileProcess(p);
+        if (syntaxErrors && syntaxErrors.length > 0) {
+            throw new Error(syntaxErrors.map(e => `Line ${e.LineNumber}: ${e.Message}`).join('; '));
+        }
+
+        try {
+            await this.create(p);
+            const debugContext = await this.debugProcess(processName);
+            const debugId = debugContext.ID;
+
+            const breakpoint = new ProcessDebugBreakpoint(
+                1,
+                BreakPointType.PROCESS_DEBUG_CONTEXT_DATA_BREAK_POINT,
+                true,
+                HitMode.BREAK_ALWAYS,
+                0,
+                '',
+                'sFunc'
+            );
+
+            await this.debugAddBreakpoint(debugId, breakpoint);
+            await this.debugContinue(debugId);
+            const result = await this.debugGetVariableValues(debugId);
+            await this.debugContinue(debugId);
+
+            if (!result || !('sFunc' in result)) {
+                throw new Error('unknown error: no formula result found');
+            }
+            return result['sFunc'];
+
+        } finally {
+            try {
+                await this.delete(processName);
+            } catch (_) {
+                // Cleanup failure should not mask the original error
+            }
+        }
+    }
+
     /**
      * Analyze process dependencies (what cubes/dimensions/processes it uses)
      *
@@ -868,8 +915,8 @@ export class ProcessService extends ObjectService {
      * @example
      * ```typescript
      * const deps = await processService.analyzeProcessDependencies('ImportData');
-     * console.log('Cubes used:', deps.cubes);
-     * console.log('Dimensions used:', deps.dimensions);
+     * // deps.cubes      => array of cube names referenced in the process
+     * // deps.dimensions => array of dimension names referenced in the process
      * ```
      */
     public async analyzeProcessDependencies(processName: string): Promise<any> {
@@ -937,35 +984,32 @@ export class ProcessService extends ObjectService {
      * Validate process syntax without executing it
      *
      * @param processName - Name of the process
-     * @returns Promise<{isValid: boolean, errors: any[]}> - Validation result
+     * @returns Promise<ValidationResult> - Validation result
      *
      * @example
      * ```typescript
      * const result = await processService.validateProcessSyntax('MyProcess');
      * if (!result.isValid) {
-     *     console.error('Errors:', result.errors);
+     *     // result.errors contains ValidationError[] entries
      * }
      * ```
      */
-    public async validateProcessSyntax(processName: string): Promise<{isValid: boolean, errors: any[]}> {
+    public async validateProcessSyntax(processName: string): Promise<ValidationResult> {
         try {
-            const result = await this.compileProcess(processName);
+            const response = await this.compile(processName);
+            if (response.status === 200) {
+                return { isValid: true, errors: [] };
+            }
             return {
-                isValid: result.success,
-                errors: result.errors.map((error, index) => ({
-                    line: index + 1,
-                    message: error,
-                    severity: 'Error'
-                }))
+                isValid: false,
+                errors: [{ line: 0, message: response.statusText || 'Compilation failed', severity: 'Error' }]
             };
-        } catch (error: any) {
+        } catch (error) {
+            const err = error as { response?: { data?: { error?: { message?: string } } }; message?: string };
+            const errorMessage = err.response?.data?.error?.message || err.message || 'Validation failed';
             return {
                 isValid: false,
-                errors: [{
-                    line: 0,
-                    message: error.message || 'Validation failed',
-                    severity: 'Error'
-                }]
+                errors: [{ line: 0, message: errorMessage, severity: 'Error' }]
             };
         }
     }
@@ -979,7 +1023,7 @@ export class ProcessService extends ObjectService {
      * @example
      * ```typescript
      * const plan = await processService.getProcessExecutionPlan('ImportData');
-     * console.log('Estimated execution time:', plan.estimatedTime);
+     * // plan.estimatedTime => estimated execution time (ms)
      * ```
      */
     public async getProcessExecutionPlan(processName: string): Promise<any> {
@@ -1059,19 +1103,20 @@ export class ProcessService extends ObjectService {
 
         // Execute process asynchronously
         this.executeWithReturn(processName, parameters)
-            .then((result: any) => {
+            .then((result: unknown) => {
                 asyncOps.updateOperationStatus(
                     operationId,
                     OperationStatus.COMPLETED,
                     result
                 );
             })
-            .catch((error: any) => {
+            .catch((error: unknown) => {
+                const message = (error as { message?: string })?.message ?? String(error);
                 asyncOps.updateOperationStatus(
                     operationId,
                     OperationStatus.FAILED,
                     undefined,
-                    error.message || String(error)
+                    message
                 );
             });
 
@@ -1087,9 +1132,7 @@ export class ProcessService extends ObjectService {
      * @example
      * ```typescript
      * const status = await processService.pollProcessExecution(operationId);
-     * if (status === OperationStatus.COMPLETED) {
-     *     console.log('Process completed!');
-     * }
+     * // if (status === OperationStatus.COMPLETED) handle completion
      * ```
      */
     public async pollProcessExecution(operationId: string): Promise<OperationStatus> {
@@ -1110,7 +1153,7 @@ export class ProcessService extends ObjectService {
      * @example
      * ```typescript
      * await processService.cancelProcessExecution(operationId);
-     * console.log('Process execution cancelled');
+     * // cancellation is acknowledged once the promise resolves
      * ```
      */
     public async cancelProcessExecution(operationId: string): Promise<void> {
@@ -1121,4 +1164,4 @@ export class ProcessService extends ObjectService {
 
         await asyncOps.cancelAsyncOperation(operationId);
     }
-}
+}