@aicgen/aicgen 1.0.0-beta.2 → 1.0.1

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

package/data/language/dart/error-handling.md

@@ -0,0 +1,355 @@
+# Error Handling in Dart
+
+## Custom Exceptions
+
+```dart
+// ✅ Create structured exception hierarchy
+class AppException implements Exception {
+  final String message;
+  final int? code;
+  final dynamic details;
+
+  AppException(this.message, {this.code, this.details});
+
+  @override
+  String toString() => 'AppException: $message (code: $code)';
+}
+
+class NotFoundException extends AppException {
+  NotFoundException(String resource, String id)
+      : super('$resource with id $id not found', code: 404);
+}
+
+class ValidationException extends AppException {
+  ValidationException(String message, {Map<String, String>? errors})
+      : super(message, code: 400, details: errors);
+}
+
+// Usage
+throw NotFoundException('User', userId);
+throw ValidationException('Invalid input', errors: {'email': 'Invalid format'});
+```
+
+## Try-Catch-Finally
+
+```dart
+// ✅ Catch specific exceptions first
+Future<User> fetchUser(String id) async {
+  try {
+    final response = await http.get('/api/users/$id');
+    return User.fromJson(response.data);
+  } on NetworkException catch (e) {
+    print('Network error: ${e.message}');
+    throw AppException('Network request failed', details: e);
+  } on FormatException catch (e) {
+    print('Invalid JSON: $e');
+    throw AppException('Invalid response format');
+  } catch (e, stackTrace) {
+    print('Unexpected error: $e');
+    print('Stack trace: $stackTrace');
+    rethrow;
+  } finally {
+    print('Request completed');
+  }
+}
+
+// ✅ Use finally for cleanup
+Future<void> processFile(String path) async {
+  File? file;
+  try {
+    file = File(path);
+    final content = await file.readAsString();
+    await processContent(content);
+  } catch (e) {
+    print('Error processing file: $e');
+    rethrow;
+  } finally {
+    // Always runs, even if exception thrown
+    await file?.close();
+  }
+}
+```
+
+## Result Type Pattern
+
+```dart
+// ✅ Explicit success/failure without exceptions
+class Result<T> {
+  final T? data;
+  final AppException? error;
+
+  const Result.success(T data) : data = data, error = null;
+  const Result.failure(AppException error) : data = null, error = error;
+
+  bool get isSuccess => error == null;
+  bool get isFailure => error != null;
+}
+
+// Usage
+Future<Result<User>> fetchUserSafe(String id) async {
+  try {
+    final user = await fetchUser(id);
+    return Result.success(user);
+  } on AppException catch (e) {
+    return Result.failure(e);
+  } catch (e) {
+    return Result.failure(AppException('Unknown error: $e'));
+  }
+}
+
+// Consumer handles explicitly
+final result = await fetchUserSafe('123');
+if (result.isSuccess) {
+  print('User: ${result.data!.name}');
+} else {
+  print('Error: ${result.error!.message}');
+}
+```
+
+## Either Type Pattern
+
+```dart
+// ✅ Functional error handling
+sealed class Either<L, R> {
+  const Either();
+}
+
+class Left<L, R> extends Either<L, R> {
+  final L value;
+  const Left(this.value);
+}
+
+class Right<L, R> extends Either<L, R> {
+  final R value;
+  const Right(this.value);
+}
+
+// Usage
+Future<Either<AppException, User>> fetchUser(String id) async {
+  try {
+    final user = await _fetchUser(id);
+    return Right(user);
+  } on AppException catch (e) {
+    return Left(e);
+  }
+}
+
+// Pattern matching (Dart 3.0+)
+final result = await fetchUser('123');
+switch (result) {
+  case Left(value: final error):
+    print('Error: ${error.message}');
+  case Right(value: final user):
+    print('User: ${user.name}');
+}
+```
+
+## Validation
+
+```dart
+// ✅ Validate early, throw specific errors
+class UserValidator {
+  static void validate(String email, String password) {
+    if (email.isEmpty) {
+      throw ValidationException('Email is required');
+    }
+
+    if (!email.contains('@')) {
+      throw ValidationException('Invalid email format');
+    }
+
+    if (password.length < 8) {
+      throw ValidationException('Password must be at least 8 characters');
+    }
+  }
+}
+
+// Usage
+try {
+  UserValidator.validate(email, password);
+  await createUser(email, password);
+} on ValidationException catch (e) {
+  showError(e.message);
+}
+```
+
+## Assert for Development
+
+```dart
+// ✅ Use assert for development-time checks
+void transfer(Account from, Account to, double amount) {
+  assert(amount > 0, 'Amount must be positive');
+  assert(from.balance >= amount, 'Insufficient funds');
+
+  from.withdraw(amount);
+  to.deposit(amount);
+}
+
+// Assertions only run in debug mode
+// In production, they're removed
+```
+
+## Error Boundaries (Flutter)
+
+```dart
+// ✅ Catch errors at widget level
+class ErrorBoundary extends StatefulWidget {
+  final Widget child;
+
+  const ErrorBoundary({required this.child});
+
+  @override
+  State<ErrorBoundary> createState() => _ErrorBoundaryState();
+}
+
+class _ErrorBoundaryState extends State<ErrorBoundary> {
+  Object? error;
+
+  @override
+  Widget build(BuildContext context) {
+    if (error != null) {
+      return ErrorWidget(error: error!);
+    }
+
+    return ErrorWrapper(
+      onError: (error, stackTrace) {
+        setState(() => this.error = error);
+      },
+      child: widget.child,
+    );
+  }
+}
+```
+
+## Global Error Handling
+
+```dart
+// ✅ Catch uncaught errors
+void main() {
+  // Synchronous errors
+  FlutterError.onError = (details) {
+    print('Flutter error: ${details.exception}');
+    print('Stack trace: ${details.stack}');
+    reportError(details.exception, details.stack);
+  };
+
+  // Asynchronous errors
+  PlatformDispatcher.instance.onError = (error, stack) {
+    print('Async error: $error');
+    reportError(error, stack);
+    return true;
+  };
+
+  runApp(MyApp());
+}
+
+void reportError(Object error, StackTrace? stackTrace) {
+  // Send to error tracking service
+}
+```
+
+## Retry Pattern
+
+```dart
+// ✅ Retry with exponential backoff
+Future<T> retryWithBackoff<T>(
+  Future<T> Function() operation, {
+  int maxAttempts = 3,
+  Duration initialDelay = const Duration(seconds: 1),
+}) async {
+  int attempt = 0;
+  while (true) {
+    try {
+      return await operation();
+    } catch (e) {
+      attempt++;
+      if (attempt >= maxAttempts) rethrow;
+
+      final delay = initialDelay * (1 << attempt); // Exponential backoff
+      print('Retry attempt $attempt after $delay');
+      await Future.delayed(delay);
+    }
+  }
+}
+
+// Usage
+final user = await retryWithBackoff(
+  () => fetchUser('123'),
+  maxAttempts: 5,
+);
+```
+
+## Circuit Breaker Pattern
+
+```dart
+// ✅ Prevent cascading failures
+class CircuitBreaker {
+  final int failureThreshold;
+  final Duration timeout;
+
+  int _failureCount = 0;
+  DateTime? _openedAt;
+
+  CircuitBreaker({
+    this.failureThreshold = 5,
+    this.timeout = const Duration(minutes: 1),
+  });
+
+  Future<T> execute<T>(Future<T> Function() operation) async {
+    if (_isOpen()) {
+      if (_shouldReset()) {
+        _reset();
+      } else {
+        throw AppException('Circuit breaker is open');
+      }
+    }
+
+    try {
+      final result = await operation();
+      _onSuccess();
+      return result;
+    } catch (e) {
+      _onFailure();
+      rethrow;
+    }
+  }
+
+  bool _isOpen() => _openedAt != null;
+
+  bool _shouldReset() {
+    return _openedAt != null &&
+        DateTime.now().difference(_openedAt!) > timeout;
+  }
+
+  void _onSuccess() {
+    _failureCount = 0;
+  }
+
+  void _onFailure() {
+    _failureCount++;
+    if (_failureCount >= failureThreshold) {
+      _openedAt = DateTime.now();
+    }
+  }
+
+  void _reset() {
+    _failureCount = 0;
+    _openedAt = null;
+  }
+}
+```
+
+## Best Practices
+
+- Create custom exception classes for different error types
+- Catch specific exceptions before general ones
+- Use `rethrow` to preserve stack traces
+- Always clean up resources in `finally` blocks
+- Validate input early and throw meaningful errors
+- Use Result/Either types for expected failures
+- Implement global error handlers for uncaught errors
+- Use retry with exponential backoff for transient failures
+- Implement circuit breakers for external service calls
+- Don't catch exceptions you can't handle
+- Include context in error messages
+- Log errors with stack traces

package/data/language/dart/index.md

@@ -0,0 +1,10 @@
+# Dart Language Guidelines
+
+Comprehensive guidelines for writing idiomatic Dart code.
+
+## Topics
+
+- [Fundamentals](basics.md) - Types, null safety, syntax
+- [Async Programming](async.md) - Futures, async/await, Streams
+- [Error Handling](error-handling.md) - Exceptions and error patterns
+- [Testing](testing.md) - Unit and widget testing