Migration Guide¶

This guide helps you migrate from LDK v1.x to v2.0.0.

Overview¶

LDK v2.0.0 introduces powerful new features while maintaining full backward compatibility with v1.x applications. This means:

✅ No breaking changes - Your existing code will continue to work
✅ Gradual adoption - Enable new features when you're ready
✅ Same API - Familiar methods and patterns

What's New in v2.0.0¶

New Features¶

Real-time Updates - WebSocket-based live data synchronization
Intelligent Caching - Multi-strategy caching with automatic invalidation
Offline Support - Full offline-first capabilities with sync
Enhanced Security - Biometric auth, token refresh, security monitoring
Advanced Querying - GraphQL support, aggregations, full-text search
Optimistic Updates - Instant UI updates with automatic rollback
Transaction Support - Multi-operation atomic transactions

Enhanced APIs¶

Enhanced Collections - Automatic upgrade when V2 features are enabled
Enhanced Authentication - Advanced security features
Unified Initialization - Single LDK.initialize() method for all features

Migration Steps¶

Step 1: Update Dependencies¶

Update your pubspec.yaml:

dependencies:
  ldk: ^2.0.0  # Updated from lazy_development_kit

Step 2: Update Imports¶

Change your import statements:

// Old (v1.x)
import 'package:lazy_development_kit/lazy_development_kit.dart';

// New (v2.0.0)
import 'package:ldk/ldk.dart';

Step 3: No Code Changes Required!¶

Your existing v1.x code will work without any changes:

// This v1.x code works unchanged in v2.0.0
void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await LDK.initialize(
    baseUrl: 'https://your-strapi-server.com',
  );

  runApp(MyApp());
}

// Your existing collections work the same way
final posts = LDK.collection('posts');
final response = await posts.get();

Step 4: Enable V2 Features (Optional)¶

When you're ready, enable new features:

await LDK.initialize(
  baseUrl: 'https://your-strapi-server.com',

  // V2 features (all optional)
  enableGraphQL: true,
  enableRealtime: true,
  enableOfflineStorage: true,
  enableIntelligentCache: true,
  enableEnhancedAuth: true,
);

Feature Migration¶

Collections → Enhanced Collections¶

Your collections automatically become enhanced when V2 features are enabled:

// Same code, enhanced features
final posts = LDK.collection('posts');

// Now supports real-time updates
posts.subscribeToUpdates().listen((event) {
  print('Post updated: ${event.data}');
});

// Now supports optimistic updates
await posts.create(data, optimistic: true);

// Now supports advanced search
final results = await posts.search('flutter development');

Authentication → Enhanced Authentication¶

Access enhanced auth features when enabled:

// Basic auth (same as v1.x)
await LDK.instance.auth.signIn(email: email, password: password);

// Enhanced auth features (v2.0.0)
if (LDK.instance.enhancedAuth != null) {
  // Enable biometric authentication
  await LDK.instance.enhancedAuth.enableBiometric();

  // Sign in with biometric
  await LDK.instance.enhancedAuth.signInWithBiometric();

  // Monitor security events
  LDK.instance.enhancedAuth.securityEventsStream.listen((event) {
    // Handle security events
  });
}

Common Migration Patterns¶

Pattern 1: Gradual Feature Adoption¶

class AppService {
  static Future<void> initialize() async {
    await LDK.initialize(
      baseUrl: 'https://your-server.com',

      // Start with basic features
      enableGraphQL: false,
      enableRealtime: false,

      // Enable caching for better performance
      enableIntelligentCache: true,
      enableOfflineStorage: true,
    );
  }

  // Later, enable more features
  static Future<void> enableRealtimeFeatures() async {
    // Reinitialize with real-time features
    await LDK.dispose();
    await LDK.initialize(
      baseUrl: 'https://your-server.com',
      enableRealtime: true,
      enableGraphQL: true,
    );
  }
}

Pattern 2: Feature Detection¶

class FeatureService {
  static bool get hasRealtime {
    try {
      LDK.instance.realtime;
      return true;
    } catch (e) {
      return false;
    }
  }

  static bool get hasEnhancedAuth {
    try {
      LDK.instance.enhancedAuth;
      return true;
    } catch (e) {
      return false;
    }
  }
}

// Use features conditionally
Widget buildPostList() {
  if (FeatureService.hasRealtime) {
    // Use real-time updates
    return StreamBuilder(
      stream: LDK.collection('posts').subscribeToUpdates(),
      builder: (context, snapshot) => ...,
    );
  } else {
    // Use traditional approach
    return FutureBuilder(
      future: LDK.collection('posts').get(),
      builder: (context, snapshot) => ...,
    );
  }
}

Pattern 3: Progressive Enhancement¶

class PostService {
  static Future<List<Post>> getPosts() async {
    final collection = LDK.collection('posts');

    // Try enhanced features first
    if (collection is LDKEnhancedCollection) {
      // Use caching and optimizations
      final response = await collection.get(useCache: true);
      return response.data.map((json) => Post.fromJson(json)).toList();
    } else {
      // Fallback to basic functionality
      final response = await collection.get();
      return response.data.map((json) => Post.fromJson(json)).toList();
    }
  }
}

Breaking Changes¶

None! LDK v2.0.0 has no breaking changes. All v1.x code continues to work.

Deprecated Features¶

None! All v1.x features are still supported and maintained.

Performance Improvements¶

V2.0.0 includes several performance improvements that benefit all users:

Faster HTTP requests with connection pooling
Reduced memory usage with better resource management
Improved error handling with more specific exceptions
Better caching even without enabling intelligent cache

Testing Your Migration¶

1. Update Dependencies¶

flutter pub get

2. Run Your Tests¶

flutter test

3. Test Core Functionality¶

void main() async {
  // Test basic initialization
  await LDK.initialize(baseUrl: 'https://your-server.com');

  // Test basic operations
  final posts = LDK.collection('posts');
  final response = await posts.get();

  print('Migration successful! Loaded ${response.data.length} posts');
}

4. Gradually Enable Features¶

// Enable one feature at a time and test
await LDK.initialize(
  baseUrl: 'https://your-server.com',
  enableIntelligentCache: true, // Start with caching
);

Rollback Plan¶

If you encounter any issues, you can easily rollback:

Option 1: Disable V2 Features¶

await LDK.initialize(
  baseUrl: 'https://your-server.com',
  // Disable all V2 features
  enableGraphQL: false,
  enableRealtime: false,
  enableOfflineStorage: false,
  enableIntelligentCache: false,
  enableEnhancedAuth: false,
);

Option 2: Revert Package Version¶

dependencies:
  ldk: ^1.5.0  # Revert to last v1.x version

Getting Help¶

If you encounter issues during migration:

Check the Troubleshooting Guide
Review API Reference
Ask in GitHub Discussions
Report bugs in GitHub Issues

Next Steps¶

After migration:

Summary¶

LDK v2.0.0 migration is designed to be:

✅ Zero-effort - No code changes required
✅ Risk-free - Full backward compatibility
✅ Gradual - Enable features when ready
✅ Reversible - Easy rollback if needed

Your existing LDK v1.x application will work immediately with v2.0.0, and you can adopt new features at your own pace!

Ready to migrate? Follow the steps above and enjoy the new features in LDK v2.0.0! 🚀