@willwade/aac-processors 0.0.3

package/examples/typescript-demo.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env ts-node
+
+/**
+ * TypeScript Demo - AACProcessors 2.0
+ * 
+ * This example demonstrates the new TypeScript API and features
+ * including translation workflows and cross-format conversion.
+ */
+
+import { 
+  getProcessor, 
+  DotProcessor, 
+  ObfProcessor,
+  AACTree, 
+  AACPage, 
+  AACButton 
+} from '../src/index';
+import fs from 'fs';
+import path from 'path';
+
+async function main() {
+  console.log('🚀 AACProcessors 2.0 TypeScript Demo\n');
+
+  // Example 1: Auto-detect processor by file extension
+  console.log('📁 Example 1: Auto-detection');
+  try {
+    const dotFile = path.join(__dirname, 'example.dot');
+    if (fs.existsSync(dotFile)) {
+      const processor = getProcessor(dotFile);
+      console.log(`✅ Detected processor: ${processor.constructor.name}`);
+      
+      const tree = processor.loadIntoTree(dotFile);
+      console.log(`📊 Loaded ${Object.keys(tree.pages).length} pages`);
+      
+      const texts = processor.extractTexts(dotFile);
+      console.log(`📝 Found ${texts.length} text elements`);
+    } else {
+      console.log('⚠️  example.dot not found, skipping auto-detection demo');
+    }
+  } catch (error) {
+    console.error('❌ Auto-detection error:', error);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 2: Create a communication board programmatically
+  console.log('🏗️  Example 2: Programmatic Board Creation');
+  
+  const tree = new AACTree();
+  
+  // Create home page
+  const homePage = new AACPage({
+    id: 'home',
+    name: 'Home Page',
+    buttons: []
+  });
+  
+  // Add buttons
+  const greetingButton = new AACButton({
+    id: 'btn_hello',
+    label: 'Hello',
+    message: 'Hello, how are you today?',
+    type: 'SPEAK'
+  });
+  
+  const foodButton = new AACButton({
+    id: 'btn_food',
+    label: 'Food',
+    message: 'I want something to eat',
+    type: 'NAVIGATE',
+    targetPageId: 'food_page'
+  });
+  
+  const drinkButton = new AACButton({
+    id: 'btn_drink',
+    label: 'Drink',
+    message: 'I want something to drink',
+    type: 'SPEAK'
+  });
+  
+  homePage.addButton(greetingButton);
+  homePage.addButton(foodButton);
+  homePage.addButton(drinkButton);
+  tree.addPage(homePage);
+  
+  // Create food page
+  const foodPage = new AACPage({
+    id: 'food_page',
+    name: 'Food Options',
+    buttons: []
+  });
+  
+  const appleButton = new AACButton({
+    id: 'btn_apple',
+    label: 'Apple',
+    message: 'I want an apple',
+    type: 'SPEAK'
+  });
+  
+  const backButton = new AACButton({
+    id: 'btn_back',
+    label: 'Back',
+    message: 'Go back to home',
+    type: 'NAVIGATE',
+    targetPageId: 'home'
+  });
+  
+  foodPage.addButton(appleButton);
+  foodPage.addButton(backButton);
+  tree.addPage(foodPage);
+  
+  tree.rootId = 'home';
+  
+  console.log(`✅ Created communication board with ${Object.keys(tree.pages).length} pages`);
+  
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 3: Save to multiple formats
+  console.log('💾 Example 3: Cross-Format Conversion');
+  
+  const tempDir = path.join(__dirname, 'temp');
+  if (!fs.existsSync(tempDir)) {
+    fs.mkdirSync(tempDir);
+  }
+  
+  try {
+    // Save as DOT
+    const dotProcessor = new DotProcessor();
+    const dotPath = path.join(tempDir, 'demo-board.dot');
+    dotProcessor.saveFromTree(tree, dotPath);
+    console.log(`✅ Saved as DOT: ${dotPath}`);
+    
+    // Save as OBF
+    const obfProcessor = new ObfProcessor();
+    const obfPath = path.join(tempDir, 'demo-board.obf');
+    obfProcessor.saveFromTree(tree, obfPath);
+    console.log(`✅ Saved as OBF: ${obfPath}`);
+    
+    // Verify round-trip integrity
+    const reloadedDotTree = dotProcessor.loadIntoTree(dotPath);
+    const reloadedObfTree = obfProcessor.loadIntoTree(obfPath);
+    
+    console.log(`🔄 DOT round-trip: ${Object.keys(reloadedDotTree.pages).length} pages`);
+    console.log(`🔄 OBF round-trip: ${Object.keys(reloadedObfTree.pages).length} pages`);
+    
+  } catch (error) {
+    console.error('❌ Conversion error:', error);
+  }
+  
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 4: Translation workflow
+  console.log('🌍 Example 4: Translation Workflow');
+  
+  try {
+    const dotPath = path.join(tempDir, 'demo-board.dot');
+    if (fs.existsSync(dotPath)) {
+      const processor = new DotProcessor();
+      
+      // Extract all text
+      const originalTexts = processor.extractTexts(dotPath);
+      console.log(`📝 Found ${originalTexts.length} translatable texts:`, originalTexts);
+      
+      // Create Spanish translations
+      const translations = new Map([
+        ['Hello', 'Hola'],
+        ['Food', 'Comida'],
+        ['Drink', 'Bebida'],
+        ['Apple', 'Manzana'],
+        ['Back', 'Atrás'],
+        ['Home Page', 'Página Principal'],
+        ['Food Options', 'Opciones de Comida'],
+        ['Hello, how are you today?', 'Hola, ¿cómo estás hoy?'],
+        ['I want something to eat', 'Quiero algo de comer'],
+        ['I want something to drink', 'Quiero algo de beber'],
+        ['I want an apple', 'Quiero una manzana'],
+        ['Go back to home', 'Volver a casa']
+      ]);
+      
+      // Apply translations
+      const spanishPath = path.join(tempDir, 'demo-board-spanish.dot');
+      const translatedBuffer = processor.processTexts(dotPath, translations, spanishPath);
+      
+      console.log(`✅ Applied ${translations.size} translations`);
+      console.log(`💾 Saved Spanish version: ${spanishPath}`);
+      
+      // Verify translations
+      const spanishTexts = processor.extractTexts(spanishPath);
+      console.log(`🔍 Spanish texts:`, spanishTexts.slice(0, 5), '...');
+      
+    } else {
+      console.log('⚠️  DOT file not found for translation demo');
+    }
+  } catch (error) {
+    console.error('❌ Translation error:', error);
+  }
+  
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 5: Error handling
+  console.log('🛡️  Example 5: Error Handling');
+  
+  try {
+    const processor = new DotProcessor();
+    
+    // Try to load a non-existent file
+    try {
+      processor.loadIntoTree('non-existent-file.dot');
+    } catch (error) {
+      console.log(`✅ Caught expected error: ${error instanceof Error ? error.message : error}`);
+    }
+    
+    // Try to load invalid content
+    try {
+      const invalidContent = Buffer.from('This is not a valid DOT file');
+      const tree = processor.loadIntoTree(invalidContent);
+      console.log(`✅ Gracefully handled invalid content: ${Object.keys(tree.pages).length} pages`);
+    } catch (error) {
+      console.log(`✅ Handled invalid content error: ${error instanceof Error ? error.message : error}`);
+    }
+    
+  } catch (error) {
+    console.error('❌ Error handling demo failed:', error);
+  }
+  
+  console.log('\n🎉 Demo completed successfully!');
+  console.log('\n📚 For more examples, see:');
+  console.log('   - README.md for API documentation');
+  console.log('   - test/ directory for comprehensive usage examples');
+  console.log('   - examples/ directory for more demos');
+  
+  // Cleanup
+  try {
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+      console.log('\n🧹 Cleaned up temporary files');
+    }
+  } catch (error) {
+    console.warn('⚠️  Failed to clean up temporary files:', error);
+  }
+}
+
+// Run the demo
+if (require.main === module) {
+  main().catch(error => {
+    console.error('❌ Demo failed:', error);
+    process.exit(1);
+  });
+}
+
+export { main as runDemo };

package/examples/unified-interface-demo.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env ts-node
+
+/**
+ * Demonstration of the unified alias interface for aac-tools-platform integration
+ * Shows how all processors now support consistent method signatures
+ */
+
+import {
+  TouchChatProcessor,
+  ObfProcessor,
+  SnapProcessor,
+  DotProcessor,
+  GridsetProcessor,
+  ApplePanelsProcessor,
+  AstericsGridProcessor,
+  ExcelProcessor,
+  OpmlProcessor,
+  StringCasing,
+  detectCasing,
+  ExtractStringsResult,
+  TranslatedString,
+  SourceString
+} from "../src/index";
+
+async function demonstrateUnifiedInterface() {
+  console.log("🚀 AAC Processors - Unified Interface Demo");
+  console.log("==========================================\n");
+
+  // Create instances of different processors
+  const processors = [
+    { name: "TouchChat", processor: new TouchChatProcessor(), extension: ".ce" },
+    { name: "OBF", processor: new ObfProcessor(), extension: ".obf" },
+    { name: "Snap", processor: new SnapProcessor(), extension: ".spb" },
+    { name: "Grid3", processor: new GridsetProcessor(), extension: ".gridset" },
+    { name: "Apple Panels", processor: new ApplePanelsProcessor(), extension: ".ascconfig" },
+    { name: "Asterics Grid", processor: new AstericsGridProcessor(), extension: ".grd" },
+    { name: "Excel", processor: new ExcelProcessor(), extension: ".xlsx" },
+    { name: "OPML", processor: new OpmlProcessor(), extension: ".opml" },
+    { name: "DOT", processor: new DotProcessor(), extension: ".dot" }
+  ];
+
+  console.log("1. 📋 Checking Unified Interface Availability");
+  console.log("----------------------------------------------");
+  
+  processors.forEach(({ name, processor }) => {
+    const hasExtractMethod = typeof processor.extractStringsWithMetadata === 'function';
+    const hasGenerateMethod = typeof processor.generateTranslatedDownload === 'function';
+    
+    console.log(`${name} Processor:`);
+    console.log(`  ✅ extractStringsWithMetadata: ${hasExtractMethod ? 'Available' : 'Not Available'}`);
+    console.log(`  ✅ generateTranslatedDownload: ${hasGenerateMethod ? 'Available' : 'Not Available'}`);
+    console.log(`  ✅ Backward compatibility: ${typeof processor.extractTexts === 'function' ? 'Maintained' : 'Broken'}`);
+    console.log();
+  });
+
+  console.log("2. 🔤 String Casing Detection Demo");
+  console.log("----------------------------------");
+  
+  const testStrings = [
+    "Hello World",
+    "hello world", 
+    "HELLO WORLD",
+    "helloWorld",
+    "HelloWorld",
+    "hello_world",
+    "HELLO_WORLD",
+    "hello-world",
+    "Hello-World"
+  ];
+
+  testStrings.forEach(str => {
+    const casing = detectCasing(str);
+    console.log(`"${str}" → ${casing}`);
+  });
+  console.log();
+
+  console.log("3. 🔄 Mock Translation Workflow");
+  console.log("-------------------------------");
+  
+  // Mock data for demonstration
+  const mockExtractedResult: ExtractStringsResult = {
+    errors: [],
+    extractedStrings: [
+      {
+        string: "Hello",
+        vocabPlacementMeta: {
+          vocabLocations: [{
+            table: "buttons",
+            id: 1,
+            column: "LABEL",
+            casing: StringCasing.CAPITAL
+          }]
+        }
+      },
+      {
+        string: "goodbye",
+        vocabPlacementMeta: {
+          vocabLocations: [{
+            table: "buttons", 
+            id: 2,
+            column: "MESSAGE",
+            casing: StringCasing.LOWER
+          }]
+        }
+      }
+    ]
+  };
+
+  const mockTranslatedStrings: TranslatedString[] = [
+    {
+      sourcestringid: 1,
+      overridestring: "",
+      translatedstring: "Hola"
+    },
+    {
+      sourcestringid: 2,
+      overridestring: "Adiós",
+      translatedstring: "goodbye_translated"
+    }
+  ];
+
+  const mockSourceStrings: SourceString[] = [
+    {
+      id: 1,
+      sourcestring: "Hello",
+      vocabplacementmetadata: mockExtractedResult.extractedStrings[0].vocabPlacementMeta
+    },
+    {
+      id: 2,
+      sourcestring: "goodbye", 
+      vocabplacementmetadata: mockExtractedResult.extractedStrings[1].vocabPlacementMeta
+    }
+  ];
+
+  console.log("📤 Mock Extracted Strings:");
+  mockExtractedResult.extractedStrings.forEach((extracted, index) => {
+    console.log(`  ${index + 1}. "${extracted.string}" (${extracted.vocabPlacementMeta.vocabLocations[0].casing})`);
+    console.log(`     Location: ${extracted.vocabPlacementMeta.vocabLocations[0].table}.${extracted.vocabPlacementMeta.vocabLocations[0].column}[${extracted.vocabPlacementMeta.vocabLocations[0].id}]`);
+  });
+  console.log();
+
+  console.log("🔄 Mock Translation Mapping:");
+  mockTranslatedStrings.forEach((translation) => {
+    const sourceString = mockSourceStrings.find(s => s.id === translation.sourcestringid);
+    const finalTranslation = translation.overridestring || translation.translatedstring;
+    console.log(`  "${sourceString?.sourcestring}" → "${finalTranslation}"`);
+  });
+  console.log();
+
+  console.log("4. 🎯 Processor-Specific Features");
+  console.log("---------------------------------");
+  
+  console.log("TouchChat Processor:");
+  console.log("  • Extracts from SQLite database within .ce files");
+  console.log("  • Handles button labels, messages, and pronunciations");
+  console.log("  • Preserves TouchChat-specific metadata");
+  console.log();
+  
+  console.log("Generic Processors (OBF, Snap, DOT):");
+  console.log("  • Use unified extraction logic from BaseProcessor");
+  console.log("  • Extract page names and button content");
+  console.log("  • Consistent metadata format across all formats");
+  console.log();
+
+  console.log("5. ✅ Integration Benefits");
+  console.log("-------------------------");
+  console.log("✅ Unified API: All processors support the same method signatures");
+  console.log("✅ Backward Compatible: Existing methods continue to work unchanged");
+  console.log("✅ Extensible: Easy to add new AAC formats with consistent interface");
+  console.log("✅ Type Safe: Full TypeScript support with proper type definitions");
+  console.log("✅ Error Handling: Consistent error format across all processors");
+  console.log("✅ Metadata Rich: Detailed location and casing information for translations");
+  console.log();
+
+  console.log("🎉 Demo Complete! The unified interface is ready for aac-tools-platform integration.");
+}
+
+// Run the demo
+if (require.main === module) {
+  demonstrateUnifiedInterface().catch(console.error);
+}
+
+export { demonstrateUnifiedInterface };

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@willwade/aac-processors",
+  "version": "0.0.3",
+  "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "docs/**/*",
+    "examples/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "test"
+  },
+  "scripts": {
+    "build": "rimraf dist && mkdir dist && ./node_modules/typescript/bin/tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist coverage",
+    "lint": "eslint 'src/**/*.{js,ts}' 'test/**/*.{js,ts}'",
+    "lint:fix": "eslint 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' --fix",
+    "format": "prettier --write 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' '*.{js,ts,json,md}'",
+    "format:check": "prettier --check 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' '*.{js,ts,json,md}'",
+    "test": "npm run build && jest",
+    "test:watch": "npm run build && jest --watch",
+    "test:coverage": "npm run build && jest --coverage",
+    "test:ci": "npm run build && jest --coverage --ci --watchAll=false --testTimeout=30000",
+    "coverage:report": "node scripts/coverage-analysis.js",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "aac",
+    "augmentative-communication",
+    "alternative-communication",
+    "assistive-technology",
+    "accessibility",
+    "communication-boards",
+    "snap",
+    "grid3",
+    "touchchat",
+    "obf",
+    "opml",
+    "dot",
+    "typescript",
+    "translation",
+    "i18n"
+  ],
+  "author": {
+    "name": "Will Wade",
+    "email": "wwade@acecentre.org.uk",
+    "url": "https://github.com/willwade"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/willwade/AACProcessors-nodejs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/willwade/AACProcessors-nodejs/issues"
+  },
+  "homepage": "https://github.com/willwade/AACProcessors-nodejs#readme",
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/exceljs": "^0.5.3",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.24",
+    "@types/plist": "^3.0.5",
+    "@typescript-eslint/eslint-plugin": "^7.1.0",
+    "@typescript-eslint/parser": "^7.1.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "fast-check": "^4.2.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "~5.5.0"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "axios": "^1.11.0",
+    "better-sqlite3": "^11.9.1",
+    "commander": "^13.1.0",
+    "exceljs": "^4.4.0",
+    "fast-xml-parser": "^5.2.0",
+    "plist": "^3.1.0",
+    "yauzl": "^3.2.0"
+  },
+  "bin": {
+    "aac-processors": "./dist/cli/index.js"
+  }
+}