[WIP] V9

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- Automatically encode DateTime objects as an ISO-8601 string
+- The "conflict" server response
+
+### Changed
+- URL Design matching now respects the base URL
+- Allow null to be returned by error interceptors
+
+### Fixed
+- StandardUriDesign working inconsistently, depending on the trailing slash in the path
+
 ## [8.1.0] - 2024-08-29
 ### Added
 - The rawResponse property to the responses of the RoutingClient
@@ -13,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [8.0.0] - 2024-07-01
 ### Added
-- CORS middware
+- CORS middleware
 
 ### Changed
 - Bump http\_interop to v2.0
@@ -264,6 +276,7 @@ the Document model.
 ### Added
 - Client: fetch resources, collections, related resources and relationships
 
+[Unreleased]: https://github.com/f3ath/json-api-dart/compare/8.1.0...HEAD
 [8.1.0]: https://github.com/f3ath/json-api-dart/compare/8.0.0...8.1.0
 [8.0.0]: https://github.com/f3ath/json-api-dart/compare/7.0.1...8.0.0
 [7.0.1]: https://github.com/f3ath/json-api-dart/compare/7.0.0...7.0.1

analysis_options.yaml

@@ -1,5 +1,11 @@
 include: package:lints/recommended.yaml
+formatter:
+  page_width: 100
+
 linter:
   rules:
-    - sort_constructors_first
-    - sort_unnamed_constructors_first
+  - use_declaring_parameters
+  - unnecessary_primary_constructor_body
+  - unnecessary_type_name_in_constructor
+
+  - prefer_if_null_operators

example/client.dart

@@ -17,7 +17,7 @@ void main() async {
   /// This is the interface which decouples this JSON:API implementation
   /// from the HTTP client.
   /// Learn more: https://pub.dev/packages/http_interop
-  final httpHandler = httpClient.handleInterop;
+  final httpHandler = httpClient.sendInterop;
 
   /// This is the basic JSON:API client. It is flexible but not very convenient
   /// to use, because you would need to remember a lot of JSON:API protocol details.
@@ -28,7 +28,7 @@ void main() async {
   /// It is called routing because it routes the calls to the correct
   /// URLs depending on the use case. Take a look at its methods, they cover
   /// all the standard scenarios specified by the JSON:API standard.
-  final client = RoutingClient(uriDesign, jsonApiClient);
+  final client = RoutingClient(uriDesign.uri, jsonApiClient);
 
   try {
     /// Fetch the collection.
@@ -38,12 +38,7 @@ void main() async {
     /// The fetched collection allows us to iterate over the resources
     /// and to look into their attributes
     for (final resource in response.collection) {
-      final {
-        'name': name,
-        'red': red,
-        'green': green,
-        'blue': blue,
-      } = resource.attributes;
+      final {'name': name, 'red': red, 'green': green, 'blue': blue} = resource.attributes;
       print('${resource.type}:${resource.id}');
       print('$name - $red:$green:$blue');
     }

example/server.dart

@@ -1,14 +1,13 @@
 import 'dart:io';
 
-import 'package:http_interop/http_interop.dart' as interop;
-import 'package:json_api/document.dart';
-import 'package:json_api/http.dart';
+import 'package:http_interop_middleware/http_interop_middleware.dart';
 import 'package:json_api/routing.dart';
 import 'package:json_api/server.dart';
 import 'package:uuid/uuid.dart';
 
 import 'server/in_memory_repo.dart';
 import 'server/json_api_server.dart';
+import 'server/logger_middleware.dart';
 import 'server/repository.dart';
 import 'server/repository_controller.dart';
 
@@ -18,21 +17,16 @@ Future<void> main() async {
   final repo = InMemoryRepo(['colors']);
   await initRepo(repo);
   final controller = RepositoryController(repo, Uuid().v4);
-  interop.Handler handler =
-      ControllerRouter(controller, StandardUriDesign.matchTarget).handle;
-
-  handler = tryCatchMiddleware(handler,
-      onError: ErrorConverter(onError: (e, stack) async {
-        stderr.writeln(e);
-        stderr.writeln(stack);
-        return response(500,
-            document: OutboundErrorDocument(
-                [ErrorObject(title: 'Internal Server Error')]));
-      }).call);
-
-  handler = loggingMiddleware(handler,
-      onRequest: (r) => print('${r.method} ${r.uri}'),
-      onResponse: (r) => print('${r.statusCode}'));
+
+  final handler = errorConverter()
+      .wrapIn(loggerMiddleware)
+      .call(
+        router(
+          getTarget: (rq) => StandardUriDesign.pathOnly.target(rq.uri),
+          getController: (_, _) => controller,
+        ),
+      );
+
   final server = JsonApiServer(handler, host: host, port: port);
 
   ProcessSignal.sigint.watch().listen((event) async {
@@ -46,16 +40,19 @@ Future<void> main() async {
 }
 
 Future initRepo(Repository repo) async {
-  final models = {
-    {'name': 'Salmon', 'r': 250, 'g': 128, 'b': 114},
-    {'name': 'Pink', 'r': 255, 'g': 192, 'b': 203},
-    {'name': 'Lime', 'r': 0, 'g': 255, 'b': 0},
-    {'name': 'Peru', 'r': 205, 'g': 133, 'b': 63},
-  }.map((color) => Model(Uuid().v4())
-    ..attributes['name'] = color['name']
-    ..attributes['red'] = color['r']
-    ..attributes['green'] = color['g']
-    ..attributes['blue'] = color['b']);
+  final models =
+      {
+        {'name': 'Salmon', 'r': 250, 'g': 128, 'b': 114},
+        {'name': 'Pink', 'r': 255, 'g': 192, 'b': 203},
+        {'name': 'Lime', 'r': 0, 'g': 255, 'b': 0},
+        {'name': 'Peru', 'r': 205, 'g': 133, 'b': 63},
+      }.map(
+        (color) => Model(Uuid().v4())
+          ..attributes['name'] = color['name']
+          ..attributes['red'] = color['r']
+          ..attributes['green'] = color['g']
+          ..attributes['blue'] = color['b'],
+      );
   for (final model in models) {
     await repo.persist('colors', model);
   }

example/server/in_memory_repo.dart

@@ -4,8 +4,8 @@ import 'package:json_api/src/nullable.dart';
 
 import 'repository.dart';
 
-class InMemoryRepo implements Repository {
-  InMemoryRepo(Iterable<String> types) {
+class InMemoryRepo(Iterable<String> types) implements Repository {
+  this {
     for (var type in types) {
       _storage[type] = {};
     }
@@ -29,8 +29,7 @@ class InMemoryRepo implements Repository {
   }
 
   @override
-  Stream<Identifier> addMany(
-      String type, String id, String rel, Iterable<Identifier> ids) {
+  Stream<Identifier> addMany(String type, String id, String rel, Iterable<Identifier> ids) {
     final many = _many(type, id, rel);
     many.addAll(ids.map(Reference.of));
     return Stream.fromIterable(many).map((e) => e.toIdentifier());
@@ -47,21 +46,17 @@ class InMemoryRepo implements Repository {
   }
 
   @override
-  Future<void> replaceOne(
-      String type, String id, String rel, Identifier? one) async {
+  Future<void> replaceOne(String type, String id, String rel, Identifier? one) async {
     _model(type, id).one[rel] = nullable(Reference.of)(one);
   }
 
   @override
-  Stream<Identifier> deleteMany(
-          String type, String id, String rel, Iterable<Identifier> many) =>
-      Stream.fromIterable(
-              _many(type, id, rel)..removeAll(many.map(Reference.of)))
+  Stream<Identifier> deleteMany(String type, String id, String rel, Iterable<Identifier> many) =>
+      Stream.fromIterable(_many(type, id, rel)..removeAll(many.map(Reference.of)))
           .map((it) => it.toIdentifier());
 
   @override
-  Stream<Identifier> replaceMany(
-      String type, String id, String rel, Iterable<Identifier> many) {
+  Stream<Identifier> replaceMany(String type, String id, String rel, Iterable<Identifier> many) {
     final set = _many(type, id, rel);
     set.clear();
     set.addAll(many.map(Reference.of));

example/server/json_api_server.dart

@@ -3,20 +3,15 @@ import 'dart:io';
 import 'package:http_interop/http_interop.dart';
 import 'package:http_interop_io/http_interop_io.dart';
 
-class JsonApiServer {
-  JsonApiServer(
-    this._handler, {
-    this.host = 'localhost',
-    this.port = 8080,
-  });
+class JsonApiServer(
+  final Handler _handler, {
 
   /// Server host name
-  final String host;
+  final String host = 'localhost',
 
   /// Server port
-  final int port;
-
-  final Handler _handler;
+  final int port = 8080,
+}) {
   HttpServer? _server;
 
   /// Server uri

example/server/logger_middleware.dart

@@ -0,0 +1,20 @@
+import 'dart:io';
+
+import 'package:http_interop_middleware/http_interop_middleware.dart';
+
+/// Middleware that logs all requests and responses to stderr.
+final Middleware loggerMiddleware = middleware(
+  onRequest: (r) async {
+    stderr.writeln(r);
+    return null;
+  },
+  onResponse: (r, _) async {
+    stderr.writeln(r);
+    return null;
+  },
+  onError: (e, t, _) async {
+    stderr.writeln(e);
+    stderr.writeln(t);
+    return null;
+  },
+);

example/server/relationship_node.dart

@@ -1,18 +1,14 @@
 /// Relationship tree node
-class RelationshipNode {
-  RelationshipNode(this.name);
-
+class RelationshipNode(
+  /// The name of the relationship
+  final String name,
+) {
   static Iterable<RelationshipNode> forest(Iterable<String> relationships) {
     final root = RelationshipNode('');
-    relationships
-        .map((rel) => rel.trim().split('.').map((e) => e.trim()))
-        .forEach(root.add);
+    relationships.map((rel) => rel.trim().split('.').map((e) => e.trim())).forEach(root.add);
     return root.children;
   }
 
-  /// The name of the relationship
-  final String name;
-
   Iterable<RelationshipNode> get children => _map.values;
 
   final _map = <String, RelationshipNode>{};

example/server/repository.dart

@@ -1,7 +1,7 @@
 import 'package:json_api/document.dart';
 import 'package:json_api/src/nullable.dart';
 
-abstract class Repository {
+abstract class Repository() {
   /// Fetches a collection.
   /// Throws [CollectionNotFound].
   Stream<Model> fetchCollection(String type);
@@ -16,8 +16,7 @@ abstract class Repository {
   /// Throws [CollectionNotFound].
   /// Throws [ResourceNotFound].
   /// Throws [RelationshipNotFound].
-  Stream<Identifier> addMany(
-      String type, String id, String rel, Iterable<Identifier> many);
+  Stream<Identifier> addMany(String type, String id, String rel, Iterable<Identifier> many);
 
   /// Delete the resource
   Future<void> delete(String type, String id);
@@ -29,33 +28,25 @@ abstract class Repository {
 
   /// Deletes refs from the to-many relationship.
   /// Returns the new actual refs.
-  Stream<Identifier> deleteMany(
-      String type, String id, String rel, Iterable<Identifier> many);
+  Stream<Identifier> deleteMany(String type, String id, String rel, Iterable<Identifier> many);
 
   /// Replaces refs in the to-many relationship.
   /// Returns the new actual refs.
-  Stream<Identifier> replaceMany(
-      String type, String id, String rel, Iterable<Identifier> many);
+  Stream<Identifier> replaceMany(String type, String id, String rel, Iterable<Identifier> many);
 }
 
-class Reference {
-  Reference(this.type, this.id);
-
+class Reference(final String type, final String id) {
   static Reference of(Identifier id) => Reference(id.type, id.id);
 
   Identifier toIdentifier() => Identifier(type, id);
-  final String type;
-  final String id;
-
   @override
   final hashCode = 0;
 
   @override
-  bool operator ==(Object other) =>
-      other is Reference && type == other.type && id == other.id;
+  bool operator ==(Object other) => other is Reference && type == other.type && id == other.id;
 }
 
-class ModelProps {
+class ModelProps() {
   static ModelProps fromResource(Resource res) {
     final props = ModelProps();
     res.attributes.forEach((key, value) {
@@ -92,19 +83,14 @@ class ModelProps {
 }
 
 /// A model of a resource. Essentially, this is the core of a resource object.
-class Model extends ModelProps {
-  Model(this.id);
-
-  final String id;
-
+class Model(final String id) extends ModelProps {
   Resource toResource(String type) {
     final res = Resource(type, id);
     attributes.forEach((key, value) {
       res.attributes[key] = value;
     });
     one.forEach((key, value) {
-      res.relationships[key] =
-          (value == null ? ToOne.empty() : ToOne(value.toIdentifier()));
+      res.relationships[key] = (value == null ? ToOne.empty() : ToOne(value.toIdentifier()));
     });
     many.forEach((key, value) {
       res.relationships[key] = ToMany(value.map((it) => it.toIdentifier()));