@aicgen/aicgen 1.0.0-beta.1 → 1.0.0

package/data/language/dart/async.md

@@ -0,0 +1,289 @@
+# Async Programming in Dart
+
+## Futures and async/await
+
+```dart
+// ✅ Async function returns Future
+Future<User> fetchUser(String id) async {
+  final response = await http.get('/api/users/$id');
+  return User.fromJson(response.data);
+}
+
+// ✅ Handle errors with try-catch
+Future<User> fetchUserSafely(String id) async {
+  try {
+    final response = await http.get('/api/users/$id');
+    return User.fromJson(response.data);
+  } catch (e) {
+    print('Failed to fetch user: $e');
+    rethrow;
+  }
+}
+
+// ❌ Don't forget await
+Future<void> badExample() async {
+  final user = fetchUser('123');   // Missing await!
+  print(user);                     // Prints: Instance of 'Future<User>'
+}
+
+// ✅ Correct
+Future<void> goodExample() async {
+  final user = await fetchUser('123');
+  print(user.name);                // Prints: Alice
+}
+```
+
+## Parallel Execution
+
+```dart
+// ❌ Sequential - slow
+Future<void> sequential() async {
+  final user = await fetchUser('1');       // 100ms
+  final posts = await fetchPosts('1');     // 150ms
+  final comments = await fetchComments('1'); // 120ms
+  // Total: 370ms
+}
+
+// ✅ Parallel - fast
+Future<void> parallel() async {
+  final results = await Future.wait([
+    fetchUser('1'),
+    fetchPosts('1'),
+    fetchComments('1'),
+  ]);
+  // Total: 150ms (longest operation)
+
+  final user = results[0] as User;
+  final posts = results[1] as List<Post>;
+  final comments = results[2] as List<Comment>;
+}
+
+// ✅ With better typing using records (Dart 3.0+)
+Future<(User, List<Post>, List<Comment>)> fetchUserData(String id) async {
+  final (user, posts, comments) = await (
+    fetchUser(id),
+    fetchPosts(id),
+    fetchComments(id),
+  ).wait;
+
+  return (user, posts, comments);
+}
+```
+
+## Future Methods
+
+```dart
+// timeout - fail if takes too long
+Future<User> fetchWithTimeout(String id) async {
+  return fetchUser(id).timeout(
+    const Duration(seconds: 5),
+    onTimeout: () => throw TimeoutException('Request timed out'),
+  );
+}
+
+// catchError - handle errors without try-catch
+final user = await fetchUser('123').catchError((error) {
+  print('Error: $error');
+  return User.guest();             // Fallback value
+});
+
+// then - chain operations (prefer async/await)
+fetchUser('123')
+  .then((user) => user.name)
+  .then((name) => print(name));
+
+// whenComplete - always runs (like finally)
+await fetchUser('123').whenComplete(() {
+  print('Request completed');
+});
+```
+
+## Streams
+
+```dart
+// Create stream
+Stream<int> countStream(int max) async* {
+  for (int i = 1; i <= max; i++) {
+    await Future.delayed(const Duration(seconds: 1));
+    yield i;
+  }
+}
+
+// ✅ Listen to stream
+final subscription = countStream(5).listen(
+  (count) {
+    print('Count: $count');
+  },
+  onError: (error) {
+    print('Error: $error');
+  },
+  onDone: () {
+    print('Stream completed');
+  },
+);
+
+// Cancel subscription
+await subscription.cancel();
+
+// ✅ Async for loop
+Future<void> processStream() async {
+  await for (final count in countStream(5)) {
+    print('Count: $count');
+  }
+  print('Done');
+}
+```
+
+## Stream Transformations
+
+```dart
+// Transform stream data
+Stream<String> getUserNames() {
+  return fetchUsersStream()
+    .map((user) => user.name)
+    .where((name) => name.isNotEmpty);
+}
+
+// Async map
+Stream<User> enrichUsers(Stream<String> userIds) {
+  return userIds.asyncMap((id) async {
+    return await fetchUser(id);
+  });
+}
+
+// Combine streams
+final combined = StreamGroup.merge([stream1, stream2, stream3]);
+
+// Buffer events
+final buffered = stream.transform(
+  StreamTransformer.fromHandlers(
+    handleData: (data, sink) {
+      sink.add(data);
+    },
+  ),
+);
+```
+
+## StreamController
+
+```dart
+class ChatService {
+  final _messagesController = StreamController<Message>.broadcast();
+
+  Stream<Message> get messages => _messagesController.stream;
+
+  void sendMessage(Message message) {
+    _messagesController.add(message);
+  }
+
+  void dispose() {
+    _messagesController.close();
+  }
+}
+
+// Usage
+final chat = ChatService();
+
+final subscription = chat.messages.listen((message) {
+  print('New message: ${message.text}');
+});
+
+chat.sendMessage(Message(text: 'Hello'));
+
+// Clean up
+await subscription.cancel();
+chat.dispose();
+```
+
+## Isolates (Heavy Computation)
+
+```dart
+// Run expensive computation in isolate
+Future<int> calculateInIsolate(int n) async {
+  return await Isolate.run(() {
+    int result = 0;
+    for (int i = 0; i < n; i++) {
+      result += i;
+    }
+    return result;
+  });
+}
+
+// ✅ For CPU-intensive tasks
+Future<Image> processImage(File imageFile) async {
+  final bytes = await imageFile.readAsBytes();
+
+  // Run in isolate to avoid blocking UI
+  final processed = await Isolate.run(() {
+    return applyFilters(bytes);
+  });
+
+  return Image.memory(processed);
+}
+```
+
+## Completer
+
+```dart
+// Create Future manually
+class DatabaseConnection {
+  final Completer<void> _readyCompleter = Completer();
+
+  Future<void> get ready => _readyCompleter.future;
+
+  void connect() async {
+    try {
+      await _performConnection();
+      _readyCompleter.complete();
+    } catch (e) {
+      _readyCompleter.completeError(e);
+    }
+  }
+}
+
+// Usage
+final db = DatabaseConnection();
+db.connect();
+await db.ready;                  // Wait until connected
+```
+
+## Error Handling
+
+```dart
+// ✅ Use try-catch with async/await
+Future<void> safeOperation() async {
+  try {
+    await riskyOperation();
+  } on NetworkException catch (e) {
+    print('Network error: ${e.message}');
+  } on TimeoutException {
+    print('Operation timed out');
+  } catch (e, stackTrace) {
+    print('Unexpected error: $e');
+    print('Stack trace: $stackTrace');
+    rethrow;
+  }
+}
+
+// ✅ Handle stream errors
+stream.listen(
+  (data) => process(data),
+  onError: (error) {
+    if (error is NetworkException) {
+      reconnect();
+    }
+  },
+);
+```
+
+## Best Practices
+
+- Always use `async`/`await` for readability
+- Run independent operations in parallel with `Future.wait`
+- Set timeouts for network operations
+- Cancel subscriptions when done
+- Use isolates for CPU-intensive work
+- Handle errors explicitly
+- Close StreamControllers when finished
+- Use `async*` and `yield` for generating stream data
+- Prefer `await for` over `listen` for sequential processing

package/data/language/dart/basics.md

@@ -0,0 +1,280 @@
+# Dart Fundamentals
+
+## Null Safety
+
+Dart has sound null safety - non-nullable by default:
+
+```dart
+// Non-nullable types
+String name = 'Alice';           // Cannot be null
+int age = 30;                    // Cannot be null
+
+// Nullable types - add ?
+String? middleName;              // Can be null
+int? optionalAge;                // Can be null
+
+// ❌ Compile error
+String lastName = null;          // Error: Can't assign null to non-nullable
+
+// ✅ Correct
+String? lastName = null;         // OK: Explicitly nullable
+```
+
+## Type Annotations
+
+Always use explicit types for clarity:
+
+```dart
+// ✅ Explicit types
+String getUserName(int userId) {
+  final User user = fetchUser(userId);
+  return user.name;
+}
+
+// Variables
+final String message = 'Hello';
+const int maxRetries = 3;
+List<String> names = ['Alice', 'Bob'];
+
+// ❌ Avoid dynamic
+dynamic data = fetchData();      // No type safety
+
+// ✅ Use specific types
+Map<String, dynamic> data = fetchData();
+```
+
+## Null-Aware Operators
+
+```dart
+// ?. - Null-aware access
+String? name = user?.name;       // null if user is null
+
+// ?? - Null coalescing
+String displayName = user?.name ?? 'Guest';
+
+// ??= - Null-aware assignment
+name ??= 'Unknown';              // Assign only if null
+
+// ! - Null assertion (use sparingly)
+String name = user!.name;        // Assert user is not null
+```
+
+## Collections
+
+```dart
+// Lists
+final List<String> fruits = ['apple', 'banana'];
+fruits.add('orange');
+
+// Sets (unique values)
+final Set<int> uniqueIds = {1, 2, 3};
+
+// Maps
+final Map<String, int> scores = {
+  'Alice': 100,
+  'Bob': 95,
+};
+
+// ✅ Use collection if for conditional elements
+final List<String> items = [
+  'required',
+  if (showOptional) 'optional',
+  if (user != null) user.name,
+];
+
+// ✅ Use spread operator
+final List<int> combined = [...list1, ...list2];
+```
+
+## Functions
+
+```dart
+// Named parameters (recommended for multiple params)
+void createUser({
+  required String email,
+  required String name,
+  int? age,
+}) {
+  // email and name are required
+  // age is optional
+}
+
+createUser(email: 'test@example.com', name: 'Alice');
+
+// Positional parameters
+int add(int a, int b) => a + b;
+
+// Optional positional
+String greet(String name, [String? title]) {
+  return title != null ? '$title $name' : name;
+}
+
+// Arrow syntax for single expressions
+bool isAdult(int age) => age >= 18;
+```
+
+## Classes
+
+```dart
+// ✅ Use final for immutable fields
+class User {
+  final String id;
+  final String email;
+  String name;                   // Mutable
+
+  User({
+    required this.id,
+    required this.email,
+    required this.name,
+  });
+
+  // Named constructors
+  User.guest() : id = '', email = '', name = 'Guest';
+
+  // Factory constructors
+  factory User.fromJson(Map<String, dynamic> json) {
+    return User(
+      id: json['id'] as String,
+      email: json['email'] as String,
+      name: json['name'] as String,
+    );
+  }
+}
+
+// ✅ Immutable classes with const
+class Point {
+  final double x;
+  final double y;
+
+  const Point(this.x, this.y);
+}
+
+const origin = Point(0, 0);      // Compile-time constant
+```
+
+## Enums
+
+```dart
+// Simple enum
+enum Status {
+  pending,
+  processing,
+  completed,
+  failed,
+}
+
+// Enhanced enums (Dart 2.17+)
+enum UserRole {
+  admin('Administrator', level: 3),
+  editor('Editor', level: 2),
+  viewer('Viewer', level: 1);
+
+  const UserRole(this.displayName, {required this.level});
+
+  final String displayName;
+  final int level;
+
+  bool canEdit() => level >= 2;
+}
+
+// Usage
+final role = UserRole.admin;
+print(role.displayName);         // 'Administrator'
+print(role.canEdit());           // true
+```
+
+## Extension Methods
+
+```dart
+// Add methods to existing types
+extension StringExtensions on String {
+  bool get isEmail => contains('@');
+
+  String capitalize() {
+    if (isEmpty) return this;
+    return '${this[0].toUpperCase()}${substring(1)}';
+  }
+}
+
+// Usage
+print('test@example.com'.isEmail);    // true
+print('hello'.capitalize());          // 'Hello'
+```
+
+## Cascade Notation
+
+```dart
+// ✅ Use cascades for fluent method chaining
+final user = User(id: '1', email: 'test@example.com', name: 'Alice')
+  ..setRole(UserRole.admin)
+  ..setActive(true)
+  ..save();
+
+// ✅ Building objects
+final button = Button()
+  ..text = 'Submit'
+  ..onPressed = handleSubmit
+  ..enabled = true;
+```
+
+## Late Variables
+
+```dart
+// late - initialize later, but before use
+class UserService {
+  late final Database db;
+
+  Future<void> init() async {
+    db = await Database.connect();
+  }
+
+  Future<User> getUser(String id) async {
+    return db.query('SELECT * FROM users WHERE id = ?', [id]);
+  }
+}
+
+// ⚠️ Runtime error if accessed before initialization
+late String config;
+print(config);                   // Error!
+
+// ✅ Initialize before use
+config = loadConfig();
+print(config);                   // OK
+```
+
+## Naming Conventions
+
+```dart
+// ✓ Classes/Enums/Typedefs: PascalCase
+class UserAccount { }
+enum OrderStatus { }
+typedef IntCallback = void Function(int);
+
+// ✓ Variables/Functions/Parameters: camelCase
+String userName = 'Alice';
+void processOrder() { }
+
+// ✓ Constants: lowerCamelCase
+const maxRetries = 3;
+const apiBaseUrl = 'https://api.example.com';
+
+// ✓ Private members: prefix with _
+class User {
+  String _password;              // Private field
+  void _hashPassword() { }       // Private method
+}
+
+// ✓ Files: snake_case
+// user_service.dart
+// order_repository.dart
+```
+
+## Best Practices
+
+- Prefer `final` over `var` for immutability
+- Use `const` for compile-time constants
+- Leverage null safety - avoid `!` assertion
+- Use named parameters for functions with multiple parameters
+- Make classes immutable when possible
+- Use extension methods to add functionality to existing types
+- Follow the official Dart style guide