diffx-js 0.5.4 → 0.5.8

package/README.md

@@ -24,62 +24,73 @@ The appropriate binary is automatically selected at runtime based on your system
 ## Usage
 
 ```javascript
-const { diff, diffString } = require('diffx-js');
-
-async function main() {
-  // Compare two files
-  const result = await diff('file1.json', 'file2.json');
-  
-  if (result.length === 0) {
-    console.log("No differences found.");
-  } else {
-    console.log("Differences found:");
-    for (const change of result) {
-      console.log(`${change.type}: ${change.path} = ${change.new_value}`);
+const { diff } = require('diffx-js');
+
+// Compare two JavaScript objects
+const old = { name: "Alice", age: 30, city: "Tokyo" };
+const newObj = { name: "Alice", age: 31, country: "Japan" };
+
+const result = diff(old, newObj);
+
+if (result.length === 0) {
+  console.log("No differences found.");
+} else {
+  console.log("Differences found:");
+  for (const change of result) {
+    console.log(`${change.diffType}: ${change.path}`);
+    if (change.oldValue !== undefined) {
+      console.log(`  Old: ${change.oldValue}`);
+    }
+    if (change.newValue !== undefined) {
+      console.log(`  New: ${change.newValue}`);
     }
   }
-
-  // Compare with options
-  const jsonResult = await diff('config1.yaml', 'config2.yaml', {
-    output: 'json',
-    ignoreKeysRegex: 'timestamp'
-  });
-
-  // Compare directory structures
-  const dirResult = await diff('dir1/', 'dir2/', {
-    recursive: true,
-    output: 'json'
-  });
-
-  // Compare strings directly
-  const stringResult = await diffString(
-    '{"a": 1}', 
-    '{"a": 2}', 
-    'json',
-    { output: 'json' }
-  );
 }
 
-main();
+// Compare with options
+const data1 = { 
+  values: [1.0001, 2.0002, 3.0003],
+  metadata: { timestamp: "2024-01-01" }
+};
+const data2 = { 
+  values: [1.0002, 2.0003, 3.0004],
+  metadata: { timestamp: "2024-01-02" }
+};
+
+const preciseResult = diff(data1, data2, {
+  epsilon: 0.001,
+  ignoreKeysRegex: "timestamp"
+});
+
+console.log(`Found ${preciseResult.length} significant differences`);
 ```
 
 
 ### API Reference
 
-#### `diff(input1, input2, options?)`
-- **input1, input2**: File paths or directory paths to compare
+#### `diff(old, new, options?)`
+- **old**: The old JavaScript object, array, or primitive value
+- **new**: The new JavaScript object, array, or primitive value  
 - **options**: Optional configuration object
-  - `format`: Input format ('json', 'yaml', 'toml', 'xml', 'ini', 'csv')
-  - `output`: Output format ('cli', 'json', 'yaml', 'unified')  
-  - `recursive`: Compare directories recursively
-  - `ignoreKeysRegex`: Ignore keys matching regex pattern
-  - `epsilon`: Tolerance for floating-point comparisons
-  - `context`: Number of context lines in unified output
-
-#### `diffString(content1, content2, format, options?)`
-- **content1, content2**: String content to compare
-- **format**: Data format ('json', 'yaml', 'toml', etc.)
-- **options**: Same as `diff()` options
+  - `epsilon`: Tolerance for floating-point comparisons (default: 0.0)
+  - `arrayIdKey`: Key to use for array element identification
+  - `ignoreKeysRegex`: Regex pattern for keys to ignore
+  - `pathFilter`: Only show differences in paths containing this string
+  - `outputFormat`: Output format ("diffx", "json", "yaml")
+  - `showUnchanged`: Show unchanged values as well
+  - `showTypes`: Show type information in output
+  - `ignoreWhitespace`: Ignore whitespace differences
+  - `ignoreCase`: Ignore case differences
+  - `briefMode`: Report only whether objects differ
+  - `quietMode`: Suppress normal output; return only results
+
+#### Return Value
+Returns an array of `JsDiffResult` objects, each containing:
+- `diffType`: Type of difference ('Added', 'Removed', 'Modified', 'TypeChanged')  
+- `path`: Path to the changed element
+- `oldValue`: Old value (for Modified/TypeChanged/Removed)
+- `newValue`: New value (for Modified/TypeChanged/Added)
+- `value`: Value (for Removed differences)
 
 ## Development
 

package/examples.ts

@@ -0,0 +1,320 @@
+#!/usr/bin/env tsx
+
+/**
+ * diffx-js TypeScript Examples - UNIFIED API DESIGN
+ * 
+ * Demonstrates native NAPI-RS API usage for semantic diffing
+ * Users parse files themselves and call the unified diff() function
+ */
+
+import { diff, DiffOptions, DiffResult } from './index';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// Colors for console output
+const colors = {
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    magenta: '\x1b[35m',
+    reset: '\x1b[0m'
+} as const;
+
+function log(message: string, color: keyof typeof colors = 'reset'): void {
+    console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function header(message: string): void {
+    log(`\n${message}`, 'cyan');
+    log('='.repeat(message.length), 'cyan');
+}
+
+function example(title: string, description: string): void {
+    log(`\n${title}`, 'yellow');
+    log(`   ${description}`, 'blue');
+}
+
+async function runExamples(): Promise<void> {
+    header('diffx-js Native API Examples');
+    
+    // Create temporary directory
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'diffx-examples-'));
+    const oldCwd = process.cwd();
+    process.chdir(tempDir);
+
+    try {
+        // Example 1: Basic JSON Configuration Comparison
+        header('1. Basic JSON Configuration Comparison');
+        
+        const config1 = {
+            app: {
+                name: "my-app",
+                version: "1.0.0",
+                database: {
+                    host: "localhost",
+                    port: 5432,
+                    ssl: false
+                }
+            },
+            features: ["auth", "logging"]
+        };
+
+        const config2 = {
+            app: {
+                name: "my-app", 
+                version: "1.1.0",
+                database: {
+                    host: "prod-db.example.com",
+                    port: 5432,
+                    ssl: true
+                }
+            },
+            features: ["auth", "logging", "metrics"]
+        };
+
+        example(
+            'Application Configuration Migration',
+            'Compare two versions of app configuration using native API'
+        );
+        
+        const results1 = diff(config1, config2);
+        log('API Results:', 'green');
+        console.log(JSON.stringify(results1, null, 2));
+
+        // Example 2: YAML Configuration with Options
+        header('2. Advanced Options Usage');
+
+        const oldYaml = `
+name: CI
+on:
+  push:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm test
+`;
+
+        const newYaml = `
+name: CI
+on:
+  push:
+    branches: [main, develop]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [16, 18, 20]
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm test
+`;
+
+        // Parse YAML using js-yaml (users would do this)
+        const yaml = await import('js-yaml');
+        const oldData = yaml.load(oldYaml) as any;
+        const newData = yaml.load(newYaml) as any;
+
+        const options: DiffOptions = {
+            outputFormat: 'json',
+            showTypes: true,
+            ignoreKeysRegex: '^(timestamp|updated_at)',
+            diffxOptions: {
+                ignoreWhitespace: true,
+                contextLines: 2
+            }
+        };
+
+        example(
+            'YAML Comparison with Advanced Options',
+            'Parse YAML yourself and use diffx options for customized output'
+        );
+
+        const results2 = diff(oldData, newData, options);
+        log('Filtered Results:', 'green');
+        console.log(JSON.stringify(results2, null, 2));
+
+        // Example 3: Array Comparison with ID Key
+        header('3. Smart Array Comparison');
+
+        const oldUsers = {
+            users: [
+                { id: 1, name: "Alice", role: "admin" },
+                { id: 2, name: "Bob", role: "user" },
+                { id: 3, name: "Charlie", role: "user" }
+            ]
+        };
+
+        const newUsers = {
+            users: [
+                { id: 1, name: "Alice", role: "admin" },
+                { id: 2, name: "Bob", role: "moderator" },
+                { id: 4, name: "David", role: "user" }
+            ]
+        };
+
+        const arrayOptions: DiffOptions = {
+            arrayIdKey: 'id',
+            showUnchanged: false
+        };
+
+        example(
+            'User Management Changes with Array ID Matching',
+            'Track user changes by ID rather than array position'
+        );
+
+        const results3 = diff(oldUsers, newUsers, arrayOptions);
+        log('User Changes:', 'green');
+        results3.forEach((result: DiffResult) => {
+            console.log(`${result.type}: ${result.path}`);
+            if (result.oldValue) console.log(`  Old: ${JSON.stringify(result.oldValue)}`);
+            if (result.newValue) console.log(`  New: ${JSON.stringify(result.newValue)}`);
+        });
+
+        // Example 4: Error Handling
+        header('4. Error Handling');
+
+        example(
+            'Handling Invalid Data Gracefully',
+            'Demonstrate proper error handling for malformed data'
+        );
+
+        try {
+            // Simulate circular reference (not serializable)
+            const circularObj: any = { name: "test" };
+            circularObj.self = circularObj;
+            
+            diff({ valid: "data" }, circularObj);
+        } catch (error) {
+            log(`Caught expected error: ${error}`, 'red');
+        }
+
+        // Example 5: Performance with Large Data
+        header('5. Large Data Performance');
+
+        const largeData1 = {
+            items: Array.from({ length: 1000 }, (_, i) => ({
+                id: i,
+                value: Math.random(),
+                category: `cat_${i % 10}`
+            }))
+        };
+
+        const largeData2 = {
+            items: Array.from({ length: 1000 }, (_, i) => ({
+                id: i,
+                value: Math.random(),
+                category: `cat_${i % 10}`,
+                newField: i % 100 === 0 ? "special" : undefined
+            })).filter(item => item.newField !== undefined || Math.random() > 0.1)
+        };
+
+        const perfOptions: DiffOptions = {
+            useMemoryOptimization: true,
+            batchSize: 100,
+            arrayIdKey: 'id'
+        };
+
+        example(
+            'Large Dataset Comparison with Memory Optimization',
+            'Handle large datasets efficiently with batching'
+        );
+
+        const startTime = Date.now();
+        const results5 = diff(largeData1, largeData2, perfOptions);
+        const endTime = Date.now();
+
+        log(`Processed ${results5.length} differences in ${endTime - startTime}ms`, 'green');
+
+        // Example 6: TypeScript Integration Patterns
+        header('6. TypeScript Integration Patterns');
+
+        interface ConfigSchema {
+            database: {
+                host: string;
+                port: number;
+                ssl: boolean;
+            };
+            features: string[];
+        }
+
+        const typedConfig1: ConfigSchema = {
+            database: { host: "localhost", port: 5432, ssl: false },
+            features: ["auth"]
+        };
+
+        const typedConfig2: ConfigSchema = {
+            database: { host: "remote", port: 5433, ssl: true },
+            features: ["auth", "logging"]
+        };
+
+        example(
+            'Type-Safe Configuration Comparison',
+            'Use TypeScript interfaces for better development experience'
+        );
+
+        const results6 = diff(typedConfig1, typedConfig2);
+        
+        // Type-safe result processing
+        results6.forEach((result: DiffResult) => {
+            switch (result.type) {
+                case 'added':
+                    log(`➕ Added: ${result.path} = ${JSON.stringify(result.newValue)}`, 'green');
+                    break;
+                case 'removed':
+                    log(`➖ Removed: ${result.path} = ${JSON.stringify(result.oldValue)}`, 'red');
+                    break;
+                case 'modified':
+                    log(`🔄 Modified: ${result.path}`, 'yellow');
+                    log(`   Old: ${JSON.stringify(result.oldValue)}`, 'red');
+                    log(`   New: ${JSON.stringify(result.newValue)}`, 'green');
+                    break;
+                case 'typeChanged':
+                    log(`🔀 Type Changed: ${result.path} (${result.oldType} → ${result.newType})`, 'magenta');
+                    break;
+            }
+        });
+
+        // Summary
+        header('Summary');
+        log('✅ All examples completed successfully!', 'green');
+        log('\nKey Benefits of Native API:', 'cyan');
+        log('  • No external CLI dependency', 'blue');
+        log('  • Better error handling', 'blue');
+        log('  • Type safety with TypeScript', 'blue');
+        log('  • Memory efficient for large data', 'blue');
+        log('  • Customizable output formats', 'blue');
+        log('  • Integration-friendly', 'blue');
+
+        log('\nNext Steps:', 'cyan');
+        log('  • See TypeScript definitions for full API', 'blue');
+        log('  • Check documentation for advanced options', 'blue');
+        log('  • Integrate into your CI/CD pipeline', 'blue');
+
+    } catch (error) {
+        log(`\nError running examples: ${error}`, 'red');
+        console.error(error);
+    } finally {
+        // Cleanup
+        process.chdir(oldCwd);
+        try {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        } catch (cleanupErr) {
+            log(`Cleanup warning: ${cleanupErr}`, 'yellow');
+        }
+    }
+}
+
+// Run examples if called directly
+if (require.main === module) {
+    runExamples().catch(console.error);
+}
+
+export { runExamples };

package/index.d.ts

@@ -0,0 +1,157 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface JsDiffOptions {
+  /** Numerical comparison tolerance */
+  epsilon?: number
+  /** Key to use for array element identification */
+  arrayIdKey?: string
+  /** Regex pattern for keys to ignore */
+  ignoreKeysRegex?: string
+  /** Only show differences in paths containing this string */
+  pathFilter?: string
+  /** Output format */
+  outputFormat?: string
+  /** Show unchanged values as well */
+  showUnchanged?: boolean
+  /** Show type information in output */
+  showTypes?: boolean
+  /** Enable memory optimization for large files */
+  useMemoryOptimization?: boolean
+  /** Batch size for memory optimization */
+  batchSize?: number
+  /** Ignore whitespace differences */
+  ignoreWhitespace?: boolean
+  /** Ignore case differences */
+  ignoreCase?: boolean
+  /** Report only whether files differ */
+  briefMode?: boolean
+  /** Suppress normal output; return only exit status */
+  quietMode?: boolean
+}
+export interface JsDiffResult {
+  /** Type of difference ('Added', 'Removed', 'Modified', 'TypeChanged') */
+  diffType: string
+  /** Path to the changed element */
+  path: string
+  /** Old value (for Modified/TypeChanged) */
+  oldValue?: any
+  /** New value (for Modified/TypeChanged/Added) */
+  newValue?: any
+  /** Value (for Removed) */
+  value?: any
+}
+/**
+ * Unified diff function for JavaScript/Node.js
+ *
+ * Compare two JavaScript objects or values and return differences.
+ *
+ * # Arguments
+ *
+ * * `old` - The old value (JavaScript object, array, or primitive)
+ * * `new` - The new value (JavaScript object, array, or primitive)
+ * * `options` - Optional configuration object
+ *
+ * # Returns
+ *
+ * Array of difference objects
+ *
+ * # Example
+ *
+ * ```javascript
+ * const { diff } = require('diffx-js');
+ *
+ * const old = { a: 1, b: 2 };
+ * const new = { a: 1, b: 3 };
+ * const result = diff(old, new);
+ * console.log(result); // [{ type: 'Modified', path: 'b', oldValue: 2, newValue: 3 }]
+ * ```
+ */
+export declare function diff(old: any, new: any, options?: JsDiffOptions | undefined | null): Array<JsDiffResult>
+/**
+ * Parse JSON string to JavaScript object
+ *
+ * # Arguments
+ *
+ * * `content` - JSON string to parse
+ *
+ * # Returns
+ *
+ * Parsed JavaScript object
+ */
+export declare function parseJson(content: string): any
+/**
+ * Parse CSV string to JavaScript array of objects
+ *
+ * # Arguments
+ *
+ * * `content` - CSV string to parse
+ *
+ * # Returns
+ *
+ * Array of JavaScript objects representing CSV rows
+ */
+export declare function parseCsv(content: string): any
+/**
+ * Parse YAML string to JavaScript object
+ *
+ * # Arguments
+ *
+ * * `content` - YAML string to parse
+ *
+ * # Returns
+ *
+ * Parsed JavaScript object
+ */
+export declare function parseYaml(content: string): any
+/**
+ * Parse TOML string to JavaScript object
+ *
+ * # Arguments
+ *
+ * * `content` - TOML string to parse
+ *
+ * # Returns
+ *
+ * Parsed JavaScript object
+ */
+export declare function parseToml(content: string): any
+/**
+ * Parse INI string to JavaScript object
+ *
+ * # Arguments
+ *
+ * * `content` - INI string to parse
+ *
+ * # Returns
+ *
+ * Parsed JavaScript object
+ */
+export declare function parseIni(content: string): any
+/**
+ * Parse XML string to JavaScript object
+ *
+ * # Arguments
+ *
+ * * `content` - XML string to parse
+ *
+ * # Returns
+ *
+ * Parsed JavaScript object
+ */
+export declare function parseXml(content: string): any
+/**
+ * Format diff results as string
+ *
+ * # Arguments
+ *
+ * * `results` - Array of diff results
+ * * `format` - Output format ("diffx", "json", "yaml")
+ *
+ * # Returns
+ *
+ * Formatted string output
+ */
+export declare function formatOutput(results: Array<JsDiffResult>, format: string): string