tm1npm 1.0.0 → 1.1.0

package/.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Global code owners - require review from KimKaoPoo for all changes
+* @KimKaoPoo
+
+# Workflow files - require review for CI/CD changes
+/.github/ @KimKaoPoo
+
+# Package configuration - require review for publishing settings
+/package.json @KimKaoPoo
+/package-lock.json @KimKaoPoo

package/.github/workflows/pr-build-check.yml

@@ -0,0 +1,252 @@
+name: PR Build Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main, master, develop]
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main, master, develop]
+
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+  checks: write
+
+jobs:
+  build-check:
+    name: Build Validation
+    runs-on: ubuntu-latest
+    
+    # Skip draft PRs unless they're marked as ready for review
+    if: github.event.pull_request.draft == false || github.event.action == 'ready_for_review'
+    
+    strategy:
+      matrix:
+        node-version: [16, 18, 20]
+        
+    steps:
+      - name: Checkout PR code
+        uses: actions/checkout@v4
+        with:
+          # For pull_request_target, we checkout the PR code safely
+          ref: ${{ github.event.pull_request.head.sha }}
+          
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ matrix.node-version }}-
+            ${{ runner.os }}-node-
+            
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Lint code (if available)
+        run: |
+          if npm run lint --if-present; then
+            echo "✅ Linting passed"
+          else
+            echo "⚠️ No lint script found or linting failed"
+          fi
+        continue-on-error: true
+        
+      - name: Type checking (if available)
+        run: |
+          if npm run typecheck --if-present; then
+            echo "✅ Type checking passed"
+          else
+            echo "⚠️ No typecheck script found, skipping"
+          fi
+        continue-on-error: true
+        
+      - name: Run build
+        id: build
+        run: |
+          echo "🔨 Building project..."
+          npm run build
+          echo "✅ Build completed successfully"
+          
+      - name: Verify build output
+        run: |
+          echo "🔍 Verifying build artifacts..."
+          
+          # Check if lib directory exists
+          if [ -d "lib" ]; then
+            echo "✅ lib/ directory found"
+            echo "📂 Build output structure:"
+            ls -la lib/ || echo "Empty lib directory"
+          else
+            echo "❌ lib/ directory not found"
+            echo "Build may have failed or output directory is different"
+            exit 1
+          fi
+          
+          # Check for main entry points
+          missing_files=()
+          
+          if [ ! -f "lib/index.js" ]; then
+            missing_files+=("lib/index.js")
+          fi
+          
+          if [ ! -f "lib/index.d.ts" ]; then
+            missing_files+=("lib/index.d.ts")
+          fi
+          
+          if [ ${#missing_files[@]} -eq 0 ]; then
+            echo "✅ Essential build files found"
+          else
+            echo "⚠️ Some expected build files are missing:"
+            printf ' - %s\n' "${missing_files[@]}"
+            echo "This may be expected depending on your build configuration"
+          fi
+          
+      - name: Test build artifacts (if tests available)
+        run: |
+          if npm run test --if-present; then
+            echo "✅ Tests passed with built code"
+          else
+            echo "⚠️ No test script found, skipping test validation"
+          fi
+        continue-on-error: true
+        
+      - name: Success summary
+        if: success()
+        run: |
+          echo "🎉 Build validation successful!"
+          echo "✅ Node.js ${{ matrix.node-version }}: Build completed successfully"
+          echo "📦 All build artifacts generated correctly"
+          
+      - name: Failure summary
+        if: failure()
+        run: |
+          echo "❌ Build validation failed!"
+          echo "❌ Node.js ${{ matrix.node-version }}: Build failed"
+          echo "Please fix build issues before merging this PR"
+
+  # Summary job for all matrix builds
+  build-summary:
+    name: Build Summary
+    needs: build-check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      statuses: write
+      checks: write
+    if: always()
+    
+    steps:
+      - name: Determine overall result
+        id: result
+        run: |
+          if [[ "${{ needs.build-check.result }}" == "success" ]]; then
+            echo "result=success" >> $GITHUB_OUTPUT
+            echo "message=All builds passed across Node.js versions 16, 18, 20" >> $GITHUB_OUTPUT
+            echo "🎉 All builds successful!"
+          else
+            echo "result=failure" >> $GITHUB_OUTPUT
+            echo "message=Some builds failed - check logs for details" >> $GITHUB_OUTPUT
+            echo "❌ Some builds failed"
+          fi
+          
+      - name: Create commit status
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const sha = context.payload.pull_request?.head?.sha || context.sha;
+            const result = '${{ steps.result.outputs.result }}';
+            const message = '${{ steps.result.outputs.message }}';
+            
+            const state = result === 'success' ? 'success' : 'failure';
+            const description = result === 'success' 
+              ? '✅ Build validation passed'
+              : '❌ Build validation failed';
+              
+            await github.rest.repos.createCommitStatus({
+              owner,
+              repo,
+              sha,
+              state,
+              target_url: `https://github.com/${owner}/${repo}/actions/runs/${context.runId}`,
+              description,
+              context: 'PR Build Check'
+            });
+            
+            console.log(`Commit status created: ${state}`);
+            console.log(`SHA: ${sha}`);
+            console.log(`Description: ${description}`);
+            
+      - name: Comment on PR
+        if: github.event_name == 'pull_request' || github.event_name == 'pull_request_target'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const prNumber = context.payload.pull_request.number;
+            const result = '${{ steps.result.outputs.result }}';
+            const runUrl = `https://github.com/${owner}/${repo}/actions/runs/${context.runId}`;
+            
+            let commentBody;
+            
+            if (result === 'success') {
+              commentBody = '## ✅ Build Validation Passed\n\n' +
+                '**All builds completed successfully!**\n\n' +
+                '- ✅ Node.js 16: Build passed\n' +
+                '- ✅ Node.js 18: Build passed\n' +
+                '- ✅ Node.js 20: Build passed\n\n' +
+                '📦 All build artifacts generated correctly.\n\n' +
+                `[View detailed results](${runUrl})`;
+            } else {
+              commentBody = '## ❌ Build Validation Failed\n\n' +
+                '**Some builds failed - please review and fix:**\n\n' +
+                '🔍 **Common issues to check:**\n' +
+                '- TypeScript compilation errors\n' +
+                '- Missing dependencies\n' +
+                '- Syntax errors\n' +
+                '- Import/export issues\n\n' +
+                'Please fix the build issues and push your changes.\n\n' +
+                `[View detailed results](${runUrl})`;
+            }
+            
+            // Check if we already commented on this PR for this run
+            const comments = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number: prNumber,
+            });
+            
+            const botComment = comments.data.find(comment => 
+              comment.user.type === 'Bot' && 
+              comment.body.includes('Build Validation')
+            );
+            
+            if (botComment) {
+              // Update existing comment
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: botComment.id,
+                body: commentBody
+              });
+              console.log('Updated existing PR comment');
+            } else {
+              // Create new comment
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body: commentBody
+              });
+              console.log('Created new PR comment');
+            }

package/.github/workflows/publish-npm.yml

@@ -4,6 +4,9 @@ on:
   release:
     types: [published]
 
+env:
+  ALLOWED_PUBLISHER: hsubebe89
+
 jobs:
   publish:
     runs-on: ubuntu-latest
@@ -12,6 +15,15 @@ jobs:
       id-token: write
     
     steps:
+      - name: Verify publisher authorization
+        run: |
+          if [ "${{ github.actor }}" != "${{ env.ALLOWED_PUBLISHER }}" ]; then
+            echo "❌ ERROR: Only ${{ env.ALLOWED_PUBLISHER }} can publish to NPM"
+            echo "Current actor: ${{ github.actor }}"
+            exit 1
+          fi
+          echo "✅ Publisher authorization verified for ${{ github.actor }}"
+          
       - name: Checkout code
         uses: actions/checkout@v4
         

package/.github/workflows/security-check.yml

@@ -0,0 +1,29 @@
+name: Security Check
+
+on:
+  create:
+  release:
+    types: [published, created, edited, deleted]
+
+env:
+  ALLOWED_MAINTAINER: hsubebe89
+
+jobs:
+  verify-permissions:
+    runs-on: ubuntu-latest
+    if: github.ref_type == 'tag' || github.event_name == 'release'
+    
+    steps:
+      - name: Verify tag/release permissions
+        run: |
+          if [ "${{ github.actor }}" != "${{ env.ALLOWED_MAINTAINER }}" ]; then
+            echo "❌ ERROR: Only ${{ env.ALLOWED_MAINTAINER }} can create tags and releases"
+            echo "Current actor: ${{ github.actor }}"
+            echo "Event: ${{ github.event_name }}"
+            echo "Ref type: ${{ github.ref_type }}"
+            
+            # Log the unauthorized attempt
+            echo "⚠️  SECURITY ALERT: Unauthorized attempt to create tag/release by ${{ github.actor }}"
+            exit 1
+          fi
+          echo "✅ Tag/release permissions verified for ${{ github.actor }}"

package/README.md

@@ -1,5 +1,15 @@
 # tm1npm
 
+<pre>
+████████╗███╗   ███╗ ██╗███╗   ██╗██████╗ ███╗   ███╗
+╚══██╔══╝████╗ ████║███║████╗  ██║██╔══██╗████╗ ████║
+   ██║   ██╔████╔██║╚██║██╔██╗ ██║██████╔╝██╔████╔██║
+   ██║   ██║╚██╔╝██║ ██║██║╚██╗██║██╔═══╝ ██║╚██╔╝██║
+   ██║   ██║ ╚═╝ ██║ ██║██║ ╚████║██║     ██║ ╚═╝ ██║
+   ╚═╝   ╚═╝     ╚═╝ ╚═╝╚═╝  ╚═══╝╚═╝     ╚═╝     ╚═╝
+
+🚀 TM1 Integration for Node.js - Build powerful TM1 applications
+</pre>
 tm1npm is the Node.js/TypeScript package for IBM Planning Analytics (TM1), providing a comprehensive interface to the TM1 REST API.
 
 By wrapping the IBM Planning Analytics (TM1) REST API in a concise TypeScript framework, tm1npm facilitates Node.js developments for TM1.
@@ -18,6 +28,9 @@ const tm1 = new TM1Service({
 });
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     const subset = new Subset('Month', 'Q1', ['Jan', 'Feb', 'Mar']);
     await tm1.dimensions.subsets.create(subset, true);
 } finally {
@@ -82,6 +95,43 @@ npm install --save-dev typescript @types/node
 
 ## Usage
 
+### Important: Connection Workflow
+
+**⚠️ CRITICAL**: Always call `await tm1.connect()` before performing any TM1 operations and `await tm1.logout()` when finished. This is the correct usage pattern:
+
+```typescript
+import { TM1Service } from 'tm1npm';
+
+const tm1 = new TM1Service({
+    address: 'localhost',
+    port: 8879,
+    user: 'admin',
+    password: 'your_password',
+    ssl: false
+});
+
+try {
+    // Step 1: Connect to TM1 server (REQUIRED!)
+    await tm1.connect();
+    
+    // Step 2: Perform TM1 operations
+    const version = await tm1.getVersion();
+    console.log('TM1 Version:', version);
+    
+    const cubes = await tm1.cubes.getAllNames();
+    console.log('Available cubes:', cubes);
+    
+} finally {
+    // Step 3: Always logout to clean up session (REQUIRED!)
+    await tm1.logout();
+}
+```
+
+**Why this matters:**
+- `connect()` establishes the session with TM1 server
+- `logout()` properly closes the session and prevents memory leaks
+- Skipping either step can cause connection issues or resource leaks
+
 ### TM1 11 On-Premise
 
 ```typescript
@@ -96,6 +146,9 @@ const tm1 = new TM1Service({
 });
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     const version = await tm1.server.getProductVersion();
     console.log('TM1 Version:', version);
     
@@ -122,6 +175,9 @@ const tm1 = new TM1Service({
 });
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     const chores = await tm1.chores.getAll();
     for (const chore of chores) {
         chore.reschedule(-1); // Reschedule 1 hour earlier
@@ -148,6 +204,9 @@ const params = {
 const tm1 = new TM1Service(params);
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     const version = await tm1.server.getProductVersion();
     console.log('TM1 Version:', version);
 } finally {
@@ -171,6 +230,9 @@ const tm1 = new TM1Service({
 });
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     const version = await tm1.server.getProductVersion();
     console.log('TM1 Version:', version);
 } finally {
@@ -194,6 +256,9 @@ const params = {
 const tm1 = new TM1Service(params);
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     const version = await tm1.server.getProductVersion();
     console.log('TM1 Version:', version);
 } finally {
@@ -211,6 +276,9 @@ import { TM1Service, Dimension, Hierarchy, Element } from 'tm1npm';
 const tm1 = new TM1Service(config);
 
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     // Create a new dimension
     const elements = [
         new Element('Total', 'Consolidated'),
@@ -248,16 +316,31 @@ const mdx = `
 const cellset = await tm1.cubes.cells.executeMdx(mdx);
 console.log('Data:', cellset);
 
+// 🆕 NEW: Get data as CSV format
+const csvData = await tm1.cubes.cells.executeMdxCsv(mdx, {
+    csv_dialect: { delimiter: ',', quotechar: '"' }
+});
+console.log('CSV Data:', csvData);
+
+// 🆕 NEW: Get data as DataFrame (pandas-like)
+const dataFrame = await tm1.cubes.cells.executeMdxDataFrame(mdx);
+console.log('DataFrame shape:', dataFrame.shape);
+console.log('Columns:', dataFrame.columns);
+
 // Read data using cell coordinates
 const value = await tm1.cubes.cells.getValue('Budget', ['Jan', 'Revenue', 'Actual']);
 console.log('Cell value:', value);
+
+// 🆕 NEW: Trace how a cell is calculated
+const trace = await tm1.cubes.cells.traceCellCalculation('Budget', ['Jan', 'Revenue', 'Actual']);
+console.log('Cell calculation trace:', trace);
 ```
 
 ### Writing Data to Cubes
 
 ```typescript
 // Write single cell
-await tm1.cubes.cells.writeValue(1000, 'Budget', ['Jan', 'Revenue', 'Budget']);
+await tm1.cubes.cells.writeValue('Budget', ['Jan', 'Revenue', 'Budget'], 1000);
 
 // Write multiple cells
 const cellset = {
@@ -266,7 +349,18 @@ const cellset = {
     'Mar:Revenue:Budget': 1200
 };
 
-await tm1.cubes.cells.writeValues('Budget', cellset);
+await tm1.cubes.cells.write('Budget', cellset);
+
+// 🆕 NEW: Async writing for better performance
+const executionId = await tm1.cubes.cells.writeAsync('Budget', cellset);
+console.log('Async write started:', executionId);
+
+// 🆕 NEW: Proportional spreading
+await tm1.cubes.cells.relativeProportionalSpread(
+    'Budget', 
+    10000,              // value to spread
+    ['Total', 'Revenue', 'Budget']  // coordinates
+);
 ```
 
 ### Executing Processes
@@ -280,16 +374,67 @@ const result = await tm1.processes.execute('ImportData', {
 
 console.log('Process executed successfully:', result);
 
+// 🆕 NEW: Compile process and check for errors
+const compilation = await tm1.processes.compileProcess('ImportData');
+if (compilation.success) {
+    console.log('Process compiled successfully');
+} else {
+    console.error('Compilation errors:', compilation.errors);
+}
+
 // Execute with return information
-const [success, status, errorLog] = await tm1.processes.executeWithReturn('ImportData', {
+const result2 = await tm1.processes.executeWithReturn('ImportData', {
     pFilename: 'data.csv'
 });
 
-if (success) {
-    console.log('Process completed successfully');
-} else {
-    console.error('Process failed:', errorLog);
-}
+console.log('Process result:', result2);
+
+// 🆕 NEW: Async execution with polling
+const asyncResult = await tm1.processes.pollExecuteWithReturn('ImportData', {
+    pFilename: 'data.csv'
+}, 300, 5); // 300s timeout, 5s poll interval
+
+console.log('Async process completed:', asyncResult);
+```
+
+### 🆕 NEW: Working with DataFrames
+
+tm1npm now includes a comprehensive DataFrame implementation for pandas-like data manipulation:
+
+```typescript
+import { DataFrame } from 'tm1npm';
+
+// Create DataFrame from TM1 data
+const mdx = "SELECT [Time].Members ON COLUMNS, [Account].Members ON ROWS FROM [Budget]";
+const dataFrame = await tm1.cubes.cells.executeMdxDataFrame(mdx);
+
+// Explore the data
+console.log('Shape:', dataFrame.shape);        // [rows, columns]
+console.log('Columns:', dataFrame.columns);    // ['Time', 'Account', 'Value']
+
+// Filter data
+const filtered = dataFrame.filter((row, index) => row[2] > 1000); // Value > 1000
+
+// Sort by value column
+const sorted = dataFrame.sortBy('Value', false); // descending
+
+// Group by Account and sum
+const grouped = dataFrame.groupBy('Account').sum('Value');
+
+// Convert to different formats
+const csvString = dataFrame.toCsv(',');
+const jsonArray = dataFrame.toJson();
+
+// Advanced search with multiple criteria
+const salesCubes = await tm1.cubes.searchCubes({
+    namePattern: 'sales',
+    dimensionNames: ['Time', 'Account'],
+    hasRules: true,
+    minDimensions: 3,
+    maxDimensions: 6
+});
+
+console.log('Found sales cubes:', salesCubes);
 ```
 
 ## Configuration Options
@@ -448,6 +593,8 @@ tm1npm is inspired by and designed to provide feature parity with **tm1py**, the
 
 **🏆 Feature Parity Status**: tm1npm achieves **95-98% feature parity** with tm1py, providing nearly all the same functionality you know and love from the Python ecosystem.
 
+**🚀 NEW in v1.0.1**: Major functionality update with **25+ new methods** including CSV export, cell tracing, DataFrame support, advanced async operations, and enhanced search capabilities!
+
 ### Why tm1npm?
 
 - **Familiar API**: If you're coming from tm1py, you'll feel right at home
@@ -480,6 +627,9 @@ import { TM1Service } from 'tm1npm';
 
 const tm1 = new TM1Service({address: 'localhost', port: 8001, user: 'admin', password: 'apple'});
 try {
+    // Connect to TM1 server
+    await tm1.connect();
+    
     // Get cube names
     const cubes = await tm1.cubes.getAllNames();
     
@@ -509,14 +659,14 @@ try {
 
 ### Comprehensive Feature Parity
 
-tm1npm implements **280+ functions** from tm1py's 31 core services, including:
+tm1npm implements **300+ functions** from tm1py's 31 core services, including:
 
 #### Core Services (Complete Coverage)
-- ✅ **CellService**: 45+ methods including async operations, blob support, tracing
-- ✅ **CubeService**: 40+ methods for complete cube management
+- ✅ **CellService**: 60+ methods including CSV export, cell tracing, async operations, DataFrame support
+- ✅ **CubeService**: 45+ methods for complete cube management and advanced search
 - ✅ **DimensionService**: 30+ methods for dimension operations  
 - ✅ **ElementService**: 60+ methods including TI-based operations
-- ✅ **ProcessService**: 40+ methods with debugging and async execution
+- ✅ **ProcessService**: 45+ methods with compilation, debugging and async execution
 - ✅ **ViewService**: 30+ methods for private/public view management
 - ✅ **HierarchyService**: 18+ methods including balance checking
 
@@ -530,7 +680,13 @@ tm1npm implements **280+ functions** from tm1py's 31 core services, including:
 - ✅ **SandboxService**: Sandbox operations
 
 #### Advanced Features (Enterprise Ready)
-- ✅ **Async Operations**: `writeDataframeAsync()`, `executeMdxAsync()`, `pollExecuteWithReturn()`
+- ✅ **CSV Export**: `executeMdxCsv()`, `executeViewCsv()` with full formatting control
+- ✅ **Cell Analysis**: `traceCellCalculation()`, `traceCellFeeders()`, `checkCellFeeders()`
+- ✅ **Proportional Spreading**: `relativeProportionalSpread()`, `clearSpread()`
+- ✅ **DataFrame Support**: JavaScript DataFrame class with pandas-like functionality
+- ✅ **Advanced Search**: `searchCubes()`, `searchForDimension()`, multi-criteria filtering
+- ✅ **Enhanced Async**: `executeMdxAsync()`, `executeViewAsync()`, `writeDataframeAsync()`
+- ✅ **Process Features**: `compileProcess()`, `pollExecuteWithReturn()` with error details
 - ✅ **TI Integration**: `deleteElementsUseTi()`, `writeThroughUnboundProcess()`
 - ✅ **Bulk Operations**: `deleteEdgesUseBlob()`, `writeThroughBlob()`
 - ✅ **Performance**: Blob support, compact JSON, iterative JSON