network-orbit/docs/docs/guides/migration-guide.md

Migration Guide

This guide helps you migrate between versions of DebrosFramework and understand breaking changes, new features, and upgrade procedures.

Version History

Current Version: 0.5.1-beta

Status: Active Development Release Date: Current Stability: Beta - API may change

Migration Strategies

Understanding DebrosFramework Versions

DebrosFramework follows semantic versioning:

• Major versions (1.0.0) - Breaking changes, major new features
• Minor versions (0.1.0) - New features, backwards compatible
• Patch versions (0.0.1) - Bug fixes, no API changes

Current Development Status

Since DebrosFramework is currently in beta (0.5.x), some features are:

✅ Stable and Production-Ready:

• Core model system with decorators
• Basic CRUD operations
• Field validation and transformation
• Lifecycle hooks
• Database management
• Sharding system

🚧 In Active Development:

• Advanced query builder features
• Complex relationship loading
• Query optimization
• Full migration system

❌ Planned for Future Releases:

• Real-time synchronization
• Advanced caching strategies
• Performance monitoring tools
• Distributed consensus features

Upgrade Procedures

From 0.4.x to 0.5.x

Breaking Changes

1. Model Field Definition Changes

   // OLD (0.4.x)
   @Field({ type: String, required: true })
   username: string;
   
   // NEW (0.5.x)
   @Field({ type: 'string', required: true })
   username: string;
   

2. Framework Configuration Structure

   // OLD (0.4.x)
   const framework = new DebrosFramework({
     cacheEnabled: true,
     logLevel: 'debug'
   });
   
   // NEW (0.5.x)
   const framework = new DebrosFramework({
     features: {
       queryCache: true,
     },
     monitoring: {
       logLevel: 'debug'
     }
   });
   

3. Query Builder API Changes

   // OLD (0.4.x) - Static methods
   const users = await User.where('isActive', true).find();
   
   // NEW (0.5.x) - Query builder pattern
   const users = await User.query().where('isActive', true).find();
   

Migration Steps

1. Update Package

   npm install @debros/network@^0.5.0
   

2. Update Field Definitions

   // Update all field type definitions from constructors to strings
   @Field({ type: 'string' }) // instead of String
   @Field({ type: 'number' }) // instead of Number
   @Field({ type: 'boolean' }) // instead of Boolean
   @Field({ type: 'array' }) // instead of Array
   @Field({ type: 'object' }) // instead of Object
   

3. Update Framework Configuration

   // Migrate old config structure to new nested structure
   const framework = new DebrosFramework({
     features: {
       queryCache: true,
       automaticPinning: true,
       pubsub: true,
       relationshipCache: true,
     },
     performance: {
       queryTimeout: 30000,
       batchSize: 100,
     },
     monitoring: {
       enableMetrics: true,
       logLevel: 'info',
     },
   });
   

4. Update Query Patterns

   // Replace static query methods with query builder
   
   // OLD
   const users = await User.where('isActive', true).find();
   const posts = await Post.orderBy('createdAt', 'desc').limit(10).find();
   
   // NEW
   const users = await User.query().where('isActive', true).find();
   const posts = await Post.query().orderBy('createdAt', 'desc').limit(10).find();
   

5. Update Error Handling

   // NEW error types
   try {
     const user = await User.create(data);
   } catch (error) {
     if (error instanceof ValidationError) {
       console.log('Field validation failed:', error.field);
     } else if (error instanceof DatabaseError) {
       console.log('Database operation failed:', error.message);
     }
   }
   

Automated Migration Script

// migration-script.ts
import * as fs from 'fs';
import * as path from 'path';

interface MigrationRule {
  pattern: RegExp;
  replacement: string;
  description: string;
}

const migrationRules: MigrationRule[] = [
  {
    pattern: /@Field\(\s*{\s*type:\s*(String|Number|Boolean|Array|Object)/g,
    replacement: '@Field({ type: \'$1\'.toLowerCase()',
    description: 'Convert field types from constructors to strings'
  },
  {
    pattern: /(\w+)\.where\(/g,
    replacement: '$1.query().where(',
    description: 'Convert static where calls to query builder'
  },
  {
    pattern: /(\w+)\.orderBy\(/g,
    replacement: '$1.query().orderBy(',
    description: 'Convert static orderBy calls to query builder'
  },
  {
    pattern: /(\w+)\.limit\(/g,
    replacement: '$1.query().limit(',
    description: 'Convert static limit calls to query builder'
  },
];

function migrateFile(filePath: string): void {
  let content = fs.readFileSync(filePath, 'utf8');
  let hasChanges = false;

  migrationRules.forEach(rule => {
    if (rule.pattern.test(content)) {
      content = content.replace(rule.pattern, rule.replacement);
      hasChanges = true;
      console.log(`✅ Applied: ${rule.description} in ${filePath}`);
    }
  });

  if (hasChanges) {
    fs.writeFileSync(filePath, content);
    console.log(`📝 Updated: ${filePath}`);
  }
}

function migrateDirectory(dirPath: string): void {
  const files = fs.readdirSync(dirPath);
  
  files.forEach(file => {
    const fullPath = path.join(dirPath, file);
    const stat = fs.statSync(fullPath);
    
    if (stat.isDirectory()) {
      migrateDirectory(fullPath);
    } else if (file.endsWith('.ts') || file.endsWith('.js')) {
      migrateFile(fullPath);
    }
  });
}

// Run migration
console.log('🚀 Starting DebrosFramework 0.5.x migration...');
migrateDirectory('./src');
console.log('✅ Migration completed!');

Feature Development Roadmap

Upcoming Features (0.6.x)

1. Enhanced Query Builder

   • Full WHERE clause support
   • JOIN operations
   • Subqueries
   • Query optimization

2. Advanced Relationships

   • Polymorphic relationships
   • Through relationships
   • Eager loading optimization

3. Performance Improvements

   • Query result caching
   • Connection pooling
   • Batch operations

Future Features (0.7.x+)

1. Real-time Features

   • Live queries
   • Real-time synchronization
   • Conflict resolution

2. Advanced Migration System

   • Schema versioning
   • Data transformation
   • Rollback capabilities

3. Monitoring and Analytics

   • Performance metrics
   • Query analysis
   • Health monitoring

Best Practices for Migration

1. Test in Development First

// Create a test migration environment
const testFramework = new DebrosFramework({
  environment: 'test',
  features: {
    queryCache: false, // Disable caching for testing
  },
  monitoring: {
    logLevel: 'debug', // Verbose logging
  },
});

// Test all your models and operations
async function testMigration() {
  try {
    await testFramework.initialize(orbitDBService, ipfsService);
    
    // Test each model
    await testUserOperations();
    await testPostOperations();
    await testQueryOperations();
    
    console.log('✅ Migration test passed');
  } catch (error) {
    console.error('❌ Migration test failed:', error);
  }
}

2. Gradual Migration Strategy

// Step 1: Update dependencies
// Step 2: Migrate models one at a time
// Step 3: Update query patterns
// Step 4: Test thoroughly
// Step 5: Deploy to staging
// Step 6: Deploy to production

class GradualMigration {
  private migratedModels = new Set<string>();
  
  async migrateModel(modelName: string, modelClass: any) {
    try {
      // Validate model configuration
      await this.validateModelConfig(modelClass);
      
      // Test basic operations
      await this.testModelOperations(modelClass);
      
      this.migratedModels.add(modelName);
      console.log(`✅ Migrated model: ${modelName}`);
    } catch (error) {
      console.error(`❌ Failed to migrate model ${modelName}:`, error);
      throw error;
    }
  }
  
  private async validateModelConfig(modelClass: any) {
    // Validate field definitions
    // Check relationship configurations
    // Verify decorator usage
  }
  
  private async testModelOperations(modelClass: any) {
    // Test create, read, update, delete
    // Test query operations
    // Test relationships
  }
}

3. Backup and Recovery

// Create backup before migration
async function createBackup() {
  const framework = getCurrentFramework();
  const databaseManager = framework.getDatabaseManager();
  
  // Export all data
  const backup = {
    timestamp: Date.now(),
    version: '0.4.x',
    databases: {},
  };
  
  // Backup each database
  const databases = await databaseManager.getAllDatabases();
  for (const [name, db] of databases) {
    backup.databases[name] = await exportDatabase(db);
  }
  
  // Save backup
  await saveBackup(backup);
  console.log('✅ Backup created successfully');
}

async function restoreFromBackup(backupPath: string) {
  const backup = await loadBackup(backupPath);
  
  // Restore each database
  for (const [name, data] of Object.entries(backup.databases)) {
    await restoreDatabase(name, data);
  }
  
  console.log('✅ Restored from backup');
}

Troubleshooting Migration Issues

Common Issues and Solutions

1. Field Type Errors

Problem: TypeError: Field type must be a string

Solution:

// Wrong
@Field({ type: String })

// Correct
@Field({ type: 'string' })

2. Query Builder Not Found

Problem: TypeError: User.where is not a function

Solution:

// Wrong
const users = await User.where('isActive', true).find();

// Correct
const users = await User.query().where('isActive', true).find();

3. Configuration Structure Errors

Problem: Unknown configuration option: cacheEnabled

Solution:

// Wrong
const framework = new DebrosFramework({
  cacheEnabled: true
});

// Correct
const framework = new DebrosFramework({
  features: {
    queryCache: true
  }
});

4. Relationship Loading Issues

Problem: Cannot read property 'posts' of undefined

Solution:

// Ensure relationships are loaded
const user = await User.findById(userId, {
  with: ['posts']
});

// Or use the relationship manager
const relationshipManager = framework.getRelationshipManager();
await relationshipManager.loadRelationship(user, 'posts');

Migration Validation

// Validation script to run after migration
async function validateMigration() {
  const checks = [
    validateModels,
    validateQueries,
    validateRelationships,
    validatePerformance,
  ];
  
  for (const check of checks) {
    try {
      await check();
      console.log(`✅ ${check.name} passed`);
    } catch (error) {
      console.error(`❌ ${check.name} failed:`, error);
      throw error;
    }
  }
  
  console.log('🎉 Migration validation completed successfully');
}

async function validateModels() {
  // Test model creation, updates, deletion
  const user = await User.create({
    username: 'test_migration',
    email: 'test@migration.com'
  });
  
  await user.delete();
}

async function validateQueries() {
  // Test basic queries work
  const users = await User.query().find();
  if (!Array.isArray(users)) {
    throw new Error('Query did not return array');
  }
}

async function validateRelationships() {
  // Test relationship loading
  // Implementation depends on your models
}

async function validatePerformance() {
  // Basic performance checks
  const start = Date.now();
  await User.query().find();
  const duration = Date.now() - start;
  
  if (duration > 5000) {
    console.warn('⚠️ Query performance degraded');
  }
}

Getting Help

Migration Support

• GitHub Issues: Report migration problems
• Discord Community: Get real-time help
• Migration Assistance: Contact the development team for complex migrations

Useful Commands

# Check current version
npm list @debros/network

# Update to latest beta
npm install @debros/network@beta

# Check for breaking changes
npm audit

# Run migration tests
npm run test:migration

This migration guide will be updated as DebrosFramework evolves. Always check the latest documentation before starting a migration.