Skip to content
Closed
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
56 commits
Select commit Hold shift + click to select a range
91bbd7f
Fix view/controller observer cleanup and return use case subscriptions
arrrrny Jan 17, 2026
2db37d6
feat: v7 API redesign - Result-based UseCases, AppFailure hierarchy, …
arrrrny Jan 17, 2026
fb5ff6d
Merge pull request #1 from arrrrny/v7
arrrrny Jan 17, 2026
563dbda
changed authors
arrrrny Jan 17, 2026
c9d2b97
Merge pull request #2 from arrrrny/v7
arrrrny Jan 17, 2026
371384b
feat: Add fca CLI for code generation
arrrrny Jan 17, 2026
f3d7c17
feat(fca): Add --data flag for data layer generation
arrrrny Jan 17, 2026
8fd9bf3
docs: Add comprehensive CLI guide, AGENTS.md, and update changelog
arrrrny Jan 17, 2026
7c9f523
Merge pull request #3 from arrrrny/v7-cli
arrrrny Jan 17, 2026
1d52301
Merge pull request #4 from arrrrny/v7
arrrrny Jan 17, 2026
8c7ddc5
Add MCP Server for fca CLI
arrrrny Jan 17, 2026
903e05a
Add resources and notifications to MCP server
arrrrny Jan 17, 2026
c63de84
Update dependencies to latest compatible versions
arrrrny Jan 17, 2026
ad71f27
Make resources/list scan and return actual files
arrrrny Jan 17, 2026
7109207
Merge pull request #5 from arrrrny/v7-cli
arrrrny Jan 17, 2026
08e1c41
Merge pull request #6 from arrrrny/v7
arrrrny Jan 17, 2026
d7ab8e8
Optimize resources/list to prevent timeouts
arrrrny Jan 17, 2026
31c6a20
updated packages
arrrrny Jan 17, 2026
282b96c
Merge pull request #7 from arrrrny/v7-cli
arrrrny Jan 17, 2026
02699bd
Merge pull request #8 from arrrrny/v7-cli
arrrrny Jan 17, 2026
08d2cc8
Further optimize resource listing to eliminate timeouts
arrrrny Jan 17, 2026
9580064
Temporarily disable resources to test timeout
arrrrny Jan 17, 2026
fcfe4f2
Revert "Temporarily disable resources to test timeout"
arrrrny Jan 17, 2026
cf816ac
Add precompiled executable recommendation to docs
arrrrny Jan 17, 2026
2f52647
Update documentation with optimal precompiled config
arrrrny Jan 17, 2026
fe4ac55
Merge pull request #9 from arrrrny/v7-cli
arrrrny Jan 17, 2026
39b9a75
Merge pull request #10 from arrrrny/v7
arrrrny Jan 17, 2026
e5e7359
Fix: Add cancelToken check to stream use cases (watch, watchList)
arrrrny Jan 17, 2026
be3f026
Merge pull request #11 from arrrrny/v7-cli
arrrrny Jan 17, 2026
f0a89a9
Merge pull request #12 from arrrrny/v7-cli
arrrrny Jan 17, 2026
2c61db3
Fix: Place presentation layer files in pages subdirectory
arrrrny Jan 17, 2026
cd10df1
Add rebuild script for MCP server and CLI
arrrrny Jan 17, 2026
fa36955
Fix: Stream cancelToken, presentation pages structure, and rebuild sc…
arrrrny Jan 17, 2026
c82d45a
Fix: Stream cancelToken, presentation pages structure, and rebuild sc…
arrrrny Jan 17, 2026
e23615c
Fix: Improve MCP server stability and rebuild script
arrrrny Jan 17, 2026
ed3235a
Merge v7-cli: Improve MCP server stability and rebuild script
arrrrny Jan 17, 2026
f1a1693
Merge v7-cli: Improve MCP server stability and rebuild script
arrrrny Jan 17, 2026
6f97e15
added ZED config
arrrrny Jan 17, 2026
9ec207c
Fix: Resolve all Flutter analyze issues
arrrrny Jan 17, 2026
c5a108f
Fix: Improve State generation with granular loading states and consis…
arrrrny Jan 19, 2026
e3622ed
Fix: Improve State generation with granular loading states and consis…
arrrrny Jan 19, 2026
ecf5ff3
removed unused variable
arrrrny Jan 19, 2026
a952e53
removed warnings
arrrrny Jan 19, 2026
5471434
added state into controller
arrrrny Jan 19, 2026
2c82d7c
state generators updated
arrrrny Jan 19, 2026
9d32982
Fix: Generate controller methods with and without state management
arrrrny Jan 19, 2026
b4741c7
Docs: Update controller generation documentation
arrrrny Jan 19, 2026
e530040
Docs: Update MCP server descriptions for state management
arrrrny Jan 19, 2026
850c12d
Fix: Remove unnecessary braces in string interpolation
arrrrny Jan 19, 2026
24b663d
Merge branch 'master' into v7
arrrrny Jan 19, 2026
82cc8ff
Fix: Lower flutter_lints version for CI compatibility
arrrrny Jan 19, 2026
6f22201
Fix: Resolve meta dependency conflict for CI
arrrrny Jan 19, 2026
e90fb69
Fix: Disable avoid_renaming_method_parameters lint in example
arrrrny Jan 19, 2026
1e9ec72
Fix: Update tests to handle async operations properly
arrrrny Jan 19, 2026
0b1d69d
Fix: Add blank lines between generated methods in controller
arrrrny Jan 19, 2026
95e3fb2
Refactor: Improve failure handling with factory constructors
arrrrny Jan 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,175 changes: 650 additions & 525 deletions README.md

Large diffs are not rendered by default.

209 changes: 199 additions & 10 deletions example/README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,205 @@
# example
# Flutter Clean Architecture v7 Example

A new Flutter project.
This example demonstrates the new v7 API of the Flutter Clean Architecture package.

## Getting Started
## Features Demonstrated

This project is a starting point for a Flutter application.
### 1. UseCase (Single-shot Operations)

A few resources to get you started if this is your first Flutter project:
The default `UseCase` class is for single-shot operations that return `Result<T, AppFailure>`:

- [Lab: Write your first Flutter app](https://flutter.io/docs/get-started/codelab)
- [Cookbook: Useful Flutter samples](https://flutter.io/docs/cookbook)
```dart
class GetTodoUseCase extends UseCase<Todo, int> {
final TodoRepository _repository;

For help getting started with Flutter, view our
[online documentation](https://flutter.io/docs), which offers tutorials,
samples, guidance on mobile development, and a full API reference.
GetTodoUseCase(this._repository);

@override
Future<Todo> execute(int id, CancelToken? cancelToken) async {
cancelToken?.throwIfCancelled();
return _repository.getTodo(id);
}
}

// Usage
final result = await getTodoUseCase(1);
result.fold(
(todo) => print('Got: ${todo.title}'),
(failure) => print('Error: ${failure.message}'),
);
```

### 2. StreamUseCase (Real-time Updates)

Use `StreamUseCase` for reactive operations that emit multiple values:

```dart
class WatchTodosUseCase extends StreamUseCase<List<Todo>, NoParams> {
final TodoRepository _repository;

WatchTodosUseCase(this._repository);

@override
Stream<List<Todo>> execute(NoParams params, CancelToken? cancelToken) {
return _repository.watchTodos();
}
}

// Usage
watchTodosUseCase(const NoParams()).listen((result) {
result.fold(
(todos) => updateList(todos),
(failure) => showError(failure),
);
});
```

### 3. BackgroundUseCase (CPU-intensive Operations)

Use `BackgroundUseCase` for operations that should run on a separate isolate:

```dart
class CalculatePrimesUseCase extends BackgroundUseCase<PrimeResult, PrimeParams> {
@override
BackgroundTask<PrimeParams> buildTask() => _calculatePrime;

// MUST be static or top-level function!
static void _calculatePrime(BackgroundTaskContext<PrimeParams> context) {
final n = context.params.n;
final prime = calculateNthPrime(n);
context.sendData(PrimeResult(n, prime));
context.sendDone();
}
}
```

### 4. Controller and CleanView

The presentation layer uses `Controller` for state management and `CleanView` for the UI:

```dart
class TodoController extends Controller {
TodoState _state = const TodoState();
TodoState get state => _state;

Future<void> createTodo(String title) async {
_setState(_state.copyWith(isCreating: true));

final result = await execute(_createTodo, title);

result.fold(
(todo) => _setState(_state.copyWith(isCreating: false)),
(failure) => _setState(_state.copyWith(error: failure)),
);
}

void _setState(TodoState newState) {
_state = newState;
refreshUI();
}
}
```

### 5. ControlledWidgetBuilder (Fine-grained Rebuilds)

Use `ControlledWidgetBuilder` for widgets that need to rebuild when the controller changes:

```dart
ControlledWidgetBuilder<TodoController>(
builder: (context, controller) {
if (controller.state.isLoading) {
return const CircularProgressIndicator();
}
return Text(controller.state.todos.length.toString());
},
)
```

### 6. Result and AppFailure (Type-safe Error Handling)

All operations return `Result<T, AppFailure>` for type-safe error handling:

```dart
result.fold(
(success) => handleSuccess(success),
(failure) => handleFailure(failure),
);

// Pattern matching on failure types
switch (failure) {
case ValidationFailure(:final message):
showValidationError(message);
case NetworkFailure():
showOfflineMessage();
case NotFoundFailure():
showNotFound();
default:
showGenericError();
}
```

### 7. CancelToken (Cooperative Cancellation)

Use `CancelToken` to cancel long-running operations:

```dart
final cancelToken = createCancelToken();
final result = await execute(useCase, params, cancelToken: cancelToken);

// Later, to cancel:
cancelToken.cancel('User navigated away');
```

## Project Structure

```
lib/
├── main.dart # App entry point
└── src/
├── data/
│ └── repositories/
│ └── in_memory_todo_repository.dart # Repository implementation
├── domain/
│ ├── entities/
│ │ ├── todo.dart # Todo entity
│ │ └── prime_result.dart # Prime calculation result
│ ├── repositories/
│ │ └── todo_repository.dart # Repository interface
│ ├── usecases/
│ │ ├── get_todo_usecase.dart # Single-shot UseCase
│ │ ├── create_todo_usecase.dart # UseCase with validation
│ │ ├── toggle_todo_usecase.dart # UseCase for updates
│ │ ├── delete_todo_usecase.dart # CompletableUseCase (void return)
│ │ ├── watch_todos_usecase.dart # StreamUseCase
│ │ └── calculate_primes_usecase.dart # BackgroundUseCase
│ └── domain.dart # Barrel export
└── presentation/
└── pages/
├── todo_state.dart # Immutable state class
├── todo_controller.dart # Controller with all use cases
└── todo_page.dart # CleanView with UI
```

## Running the Example

```bash
cd example
flutter pub get
flutter run
```

## Running Tests

```bash
cd example
flutter test
```

## Key Concepts

1. **Single-shot by default**: `UseCase` returns `Future<Result<T, AppFailure>>` instead of streams
2. **Opt-in streaming**: Use `StreamUseCase` when you need reactive updates
3. **Type-safe errors**: `AppFailure` is a sealed class for exhaustive pattern matching
4. **Automatic cleanup**: `Controller` automatically cancels operations on dispose
5. **Fine-grained rebuilds**: Use `ControlledWidgetBuilder` to rebuild only what's needed
6. **Immutable state**: Use immutable state classes with `copyWith` for predictable updates
2 changes: 1 addition & 1 deletion example/ios/Flutter/AppFrameworkInfo.plist
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,6 @@
<key>CFBundleVersion</key>
<string>1.0</string>
<key>MinimumOSVersion</key>
<string>8.0</string>
<string>13.0</string>
</dict>
</plist>
32 changes: 32 additions & 0 deletions example/ios/Flutter/ephemeral/flutter_lldb_helper.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
#
# Generated file, do not edit.
#

import lldb

def handle_new_rx_page(frame: lldb.SBFrame, bp_loc, extra_args, intern_dict):
"""Intercept NOTIFY_DEBUGGER_ABOUT_RX_PAGES and touch the pages."""
base = frame.register["x0"].GetValueAsAddress()
page_len = frame.register["x1"].GetValueAsUnsigned()

# Note: NOTIFY_DEBUGGER_ABOUT_RX_PAGES will check contents of the
# first page to see if handled it correctly. This makes diagnosing
# misconfiguration (e.g. missing breakpoint) easier.
data = bytearray(page_len)
data[0:8] = b'IHELPED!'

error = lldb.SBError()
frame.GetThread().GetProcess().WriteMemory(base, data, error)
if not error.Success():
print(f'Failed to write into {base}[+{page_len}]', error)
return

def __lldb_init_module(debugger: lldb.SBDebugger, _):
target = debugger.GetDummyTarget()
# Caveat: must use BreakpointCreateByRegEx here and not
# BreakpointCreateByName. For some reasons callback function does not
# get carried over from dummy target for the later.
bp = target.BreakpointCreateByRegex("^NOTIFY_DEBUGGER_ABOUT_RX_PAGES$")
bp.SetScriptCallbackFunction('{}.handle_new_rx_page'.format(__name__))
bp.SetAutoContinue(True)
print("-- LLDB integration loaded --")
5 changes: 5 additions & 0 deletions example/ios/Flutter/ephemeral/flutter_lldbinit
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#
# Generated file, do not edit.
#

command script import --relative-to-command-file flutter_lldb_helper.py
7 changes: 4 additions & 3 deletions example/ios/Flutter/flutter_export_environment.sh
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
#!/bin/sh
# This is a generated file; do not edit or check into version control.
export "FLUTTER_ROOT=/Users/arrrrny/fvm/versions/3.22.2"
export "FLUTTER_ROOT=/usr/local/share/flutter"
export "FLUTTER_APPLICATION_PATH=/Users/arrrrny/Developer/flutter_clean_architecture/example"
export "COCOAPODS_PARALLEL_CODE_SIGN=true"
export "FLUTTER_TARGET=lib/main.dart"
export "FLUTTER_TARGET=/Users/arrrrny/Developer/flutter_clean_architecture/example/lib/main.dart"
export "FLUTTER_BUILD_DIR=build"
export "FLUTTER_BUILD_NAME=1.0.0"
export "FLUTTER_BUILD_NUMBER=1"
export "DART_DEFINES=RkxVVFRFUl9WRVJTSU9OPTMuMzguNg==,RkxVVFRFUl9DSEFOTkVMPXN0YWJsZQ==,RkxVVFRFUl9HSVRfVVJMPWh0dHBzOi8vZ2l0aHViLmNvbS9mbHV0dGVyL2ZsdXR0ZXIuZ2l0,RkxVVFRFUl9GUkFNRVdPUktfUkVWSVNJT049OGI4NzI4Njg0OQ==,RkxVVFRFUl9FTkdJTkVfUkVWSVNJT049NzhmYzMwMTJlNA==,RkxVVFRFUl9EQVJUX1ZFUlNJT049My4xMC43"
export "DART_OBFUSCATION=false"
export "TRACK_WIDGET_CREATION=true"
export "TREE_SHAKE_ICONS=false"
export "PACKAGE_CONFIG=.dart_tool/package_config.json"
export "PACKAGE_CONFIG=/Users/arrrrny/Developer/flutter_clean_architecture/example/.dart_tool/package_config.json"
Loading
Loading