docs: improve quick_start

Author: francescovallone

.website/.vitepress/config.mts

@@ -150,6 +150,7 @@ export default defineConfig({
             text: 'Overview',
             base: '/',
             items: [
+              { text: 'Quick Start', link: 'quick_start' },
               { text: 'Modules', link: 'modules' },
               { text: 'Controllers', link: 'controllers' },
               { text: 'Routes', link: 'routes' },

.website/package.json

@@ -14,7 +14,7 @@
   "license": "ISC",
   "devDependencies": {
     "baseline-browser-mapping": "^2.8.30",
-    "vitepress": "2.0.0-alpha.15"
+    "vitepress": "2.0.0-alpha.16"
   },
   "dependencies": {
     "@avesbox/canary": "^0.1.0",

.website/quick_start.md

@@ -68,3 +68,175 @@ serinus run --dev
 ```
 
 This will start the server on `http://localhost:3000` in development mode allowing you to leverage on an hot-restarter to automatically restart the server when a file is changed.
+
+## Let's complete it
+
+So now we have the application running but we should start adding some features to see how things really work.
+
+## Update the Todo model
+
+The `Todo` class is already augmented with the `JsonObject` mixin, meaning that this object can be converted to its json representation by the framework. But we also need to create it directly from the body although not the `Todo` class itself so let's create a `TodoDto` class.
+
+```dart
+class Todo with JsonObject{
+  final String title;
+  bool isDone;
+
+  Todo({
+    required this.title,
+    this.isDone = false,
+  });
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'title': title,
+      'isDone': isDone,
+    };
+  }
+}
+
+class TodoDto {
+
+  final String title;
+
+  const TodoDto({ 
+    required this.title, 
+  });
+
+  factory TodoDto.fromJson(Map<String, dynamic> json) { 
+    return TodoDto( 
+      title: json['title'], 
+    );
+  } 
+}
+
+```
+
+## Generate the models
+
+As you can see the `TodoDto` class has a `fromJson` factory constructor that will be used by the cli to generate the [ModelProvider](/techniques/model_provider.html). So let's do exactly that.
+
+Let's execute this command:
+
+```bash
+serinus generate models
+```
+
+And now we have a new file `model_provider` in the root of the `lib` folder.
+
+```dart
+import 'package:serinus/serinus.dart';
+
+import 'todo.dart';
+
+/// The [MyProjectModelProvider] is used to provide models for the Serinus application.
+/// It contains mappings for serializing and deserializing models to and from JSON.
+class MyProjectModelProvider extends ModelProvider {
+  @override
+  Map<String, Function> get toJsonModels {
+    return {"Todo": (model) => (model as Todo).toJson()};
+  }
+
+  @override
+  Map<String, Function> get fromJsonModels {
+    return {"TodoDto": (json) => TodoDto.fromJson(json)};
+  }
+}
+```
+
+Let's add it to the application.
+
+```dart
+import 'package:serinus/serinus.dart';
+
+import 'app_module.dart';
+import 'model_provider.dart';
+
+/// The bootstrap function is the entry point of the application.
+/// It will be called by the `entrypoint` file in the bin directory.
+/// 
+/// This function creates a Serinus application using the [AppModule]
+/// as the root module, and starts the server on host '0.0.0.0' and port 3000.
+Future<void> bootstrap() async {
+  final app = await serinus.createApplication(
+    entrypoint: AppModule(),
+    host: '0.0.0.0',
+    port: 3000,
+    modelProvider: MyProjectModelProvider()
+  );
+  await app.serve();
+}
+```
+
+## Use the model as the body in the TodoController
+
+First of all let's create a Pipe to validate the body.
+
+```dart
+import 'package:serinus/serinus.dart';
+
+import 'todo.dart';
+
+class TodoPipe extends Pipe {
+  @override
+  Future<void> transform(ExecutionContext context) async {
+    if (context.argumentsHost is! HttpArgumentsHost) {
+      return;
+    }
+    final reqContext = context.switchToHttp();
+    final body = reqContext.body;
+    if (body is TodoDto) {
+      if (body.title.isEmpty) {
+        throw BadRequestException('Title cannot be empty');
+      }
+      return;
+    }
+    throw BadRequestException('The body is not correct!');
+  }
+}
+```
+
+Then let's bind the pipe to the controller and specify the DTO to the route that will create the `Todo`.
+
+```dart
+import 'package:serinus/serinus.dart';
+
+import 'app_provider.dart';
+import 'todo.dart';
+import 'todo_pipe.dart';
+
+class AppController extends Controller {
+
+  AppController(): super('/'){
+    /// ...
+    on<Todo, TodoDto>(
+      Route.post(
+        '/',
+        pipes: {
+          TodoPipe()
+        }
+      ), 
+      _createTodo
+    );
+    /// ...
+  }
+
+///...
+
+  Future<Todo> _createTodo(RequestContext<TodoDto> context) async {
+    context.use<AppProvider>().addTodo(context.body.title);
+    return context.use<AppProvider>().todos.last;
+  }
+
+///...
+
+
+}
+```
+
+Now when you do a `POST` request to `/` everything will be safe and sound.
+
+## Conclusion
+
+We've created a REST Api that automatically convert and validates the body of a request without code generation and **magic** stuff like that.

packages/serinus/lib/src/contexts/request_context.dart

@@ -387,23 +387,27 @@ class _BodyConverter {
       }
     }
     if (modelProvider != null) {
-      if (value is FormData) {
-        final map = {...value.fields, ...value.files};
-        return modelProvider!.from(
-          '$targetType',
-          Map<String, dynamic>.from(map),
-        );
-      }
-      if (value is Map) {
-        final mapped = value.map((key, val) => MapEntry('$key', val));
-        final result = modelProvider!.from(
-          '$targetType',
-          Map<String, dynamic>.from(mapped),
-        );
-        if (allowsNull && result == null) {
-          return null;
+      try {
+        if (value is FormData) {
+          final map = {...value.fields, ...value.files};
+          return modelProvider!.from(
+            '$targetType',
+            Map<String, dynamic>.from(map),
+          );
+        }
+        if (value is Map) {
+          final mapped = value.map((key, val) => MapEntry('$key', val));
+          final result = modelProvider!.from(
+            '$targetType',
+            Map<String, dynamic>.from(mapped),
+          );
+          if (allowsNull && result == null) {
+            return null;
+          }
+          return result;
         }
-        return result;
+      } catch (e) {
+        throw BadRequestException('An error occured when parsing the object');
       }
       if (value is List) {
         throw BadRequestException('The element is not of the expected type');

packages/serinus/lib/src/core/middlewares/middleware_registry.dart

@@ -394,25 +394,34 @@ class MiddlewareRegistry extends Provider with OnApplicationBootstrap {
     }
 
     // Check if resolver path is parametric and can match target
-    final parametricRegex = RegExp(r'<[^>]+>');
-
-    if (resolverPath.contains('<')) {
+    if (_hasDynamicSegments(resolverPath)) {
       // Convert parametric path to regex pattern
-      final pattern = resolverPath.replaceAll(parametricRegex, r'([^/]+)');
+      final pattern = _toParametricPattern(resolverPath);
       final regex = RegExp('^$pattern\$');
       return regex.hasMatch(targetPath);
     }
 
     // Check if target path is parametric and can match resolver
-    if (targetPath.contains('<')) {
-      final pattern = targetPath.replaceAll(parametricRegex, r'([^/]+)');
+    if (_hasDynamicSegments(targetPath)) {
+      final pattern = _toParametricPattern(targetPath);
       final regex = RegExp('^$pattern\$');
       return regex.hasMatch(resolverPath);
     }
 
     return false;
   }
 
+  bool _hasDynamicSegments(String path) {
+    return path.contains('<') || path.contains(RegExp(r':[A-Za-z_]\w*\??'));
+  }
+
+  String _toParametricPattern(String path) {
+    var pattern = path;
+    pattern = pattern.replaceAll(RegExp(r'<[^>]+>\??'), r'([^/]+)');
+    pattern = pattern.replaceAll(RegExp(r':[A-Za-z_]\w*\??'), r'([^/]+)');
+    return pattern;
+  }
+
   /// Checks if versions are compatible
   bool _versionsMatch(
     List<VersioningOptions>? targetVersions,

packages/serinus/lib/src/routes/routes_explorer.dart

@@ -35,9 +35,6 @@ final class RoutesExplorer {
         ),
     };
     for (var controller in controllers.entries) {
-      if (controller.value.path.contains(RegExp(r'([\/]{2,})*([\:][\w+]+)'))) {
-        throw Exception('Invalid controller path: ${controller.value.path}');
-      }
       logger.info('${controller.key.runtimeType} {${controller.value.path}}');
       final versioningOptions = _container.config.versioningOptions;
       final globalVersioningEnabled =

packages/serinus/lib/src/routes/routes_resolver.dart

@@ -55,9 +55,6 @@ class RoutesResolver {
         entry.controller: ControllerSpec(entry.controller.path, entry.module),
     };
     for (var controller in mappedControllers.entries) {
-      if (controller.value.path.contains(RegExp(r'([\/]{2,})*([\:][\w+]+)'))) {
-        throw Exception('Invalid controller path: ${controller.value.path}');
-      }
       _logger.info('${controller.key.runtimeType} {${controller.value.path}}');
       _explorer.explore(
         controller,

packages/serinus/test/core/middlewares_test.dart

@@ -94,6 +94,9 @@ class TestModule extends Module {
         .apply([TestModuleMiddleware(), shelfMiddleware, shelfAltMiddleware])
         .forControllers([TestController])
         .exclude([RouteInfo('/request-event')]);
+    consumer.apply([DynamicParamMiddleware()]).forControllers([
+      DynamicController,
+    ]);
     consumer.apply([r]).forRoutes([RouteInfo('/request-event')]);
   }
 }
@@ -109,11 +112,33 @@ class TestModuleMiddleware extends Middleware {
   }
 }
 
+class DynamicParamMiddleware extends Middleware {
+  @override
+  Future<void> use(ExecutionContext context, NextFunction next) async {
+    final argumentsHost = context.argumentsHost;
+    if (argumentsHost is HttpArgumentsHost) {
+      final postId = argumentsHost.params['postId'];
+      if (postId != null) {
+        context.response.headers['x-post-id'] = postId.toString();
+      }
+    }
+    return next();
+  }
+}
+
+class DynamicController extends Controller {
+  DynamicController() : super('/posts/:postId') {
+    on(Route.get('/comments'), (context) async => 'dynamic-route-ok');
+  }
+}
+
 void main() {
   group('$Middleware', () {
     SerinusApplication? app;
 
-    final module = TestModule(controllers: [TestController()]);
+    final module = TestModule(
+      controllers: [TestController(), DynamicController()],
+    );
     setUpAll(() async {
       app = await serinus.createApplication(
         entrypoint: module,
@@ -196,5 +221,19 @@ void main() {
         expect(r.hasException, false);
       },
     );
+
+    test(
+      '''when a controller has a dynamic base path, middleware should resolve params for matched requests''',
+      () async {
+        final request = await HttpClient().getUrl(
+          Uri.parse('http://localhost:8888/posts/77/comments'),
+        );
+        final response = await request.close();
+        final body = await response.transform(utf8.decoder).join();
+        expect(response.statusCode, 200);
+        expect(body, contains('dynamic-route-ok'));
+        expect(response.headers.value('x-post-id'), '77');
+      },
+    );
   });
 }

packages/serinus/test/injector/explorer_test.dart

@@ -46,7 +46,7 @@ void main() {
     );
 
     test(
-      'when the application startup, and a controller has not a static path, then the explorer will throw an error',
+      'when the application startup, and a controller has a dynamic path, then the explorer should register matching routes',
       () async {
         final router = Router();
         final config = ApplicationConfig(
@@ -59,9 +59,12 @@ void main() {
         final container = SerinusContainer(config, _MockAdapter());
         final explorer = RoutesExplorer(container, router);
         await container.modulesContainer.registerModules(
-          SimpleMockModule(controllers: [MockControllerWithWrongPath()]),
+          SimpleMockModule(controllers: [MockControllerWithDynamicPath()]),
         );
-        expect(() => explorer.resolveRoutes(), throwsException);
+        explorer.resolveRoutes();
+        final result = router.lookup('/42', HttpMethod.get);
+        expect(result, isA<FoundRoute<RouterEntry>>());
+        expect(result.params['id'], '42');
       },
     );
 

packages/serinus/test/mocks/controller_mock.dart

@@ -7,9 +7,9 @@ class MockController extends Controller {
   }
 }
 
-class MockControllerWithWrongPath extends Controller {
+class MockControllerWithDynamicPath extends Controller {
   @override
-  MockControllerWithWrongPath([super.path = '/:id']) {
+  MockControllerWithDynamicPath([super.path = '/:id']) {
     on(Route.get('/'), (context) => Future.value('Hello world'));
   }
 }