v5

.github/workflows/dart.yml

@@ -15,12 +15,14 @@ jobs:
       image:  google/dart:latest
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Install dependencies
-      run: pub get
-    - name: Formatting
-      run: dartfmt -n --set-exit-if-changed .
-    - name: Analyzer
-      run: dartanalyzer --fatal-infos --fatal-warnings lib test example
-    - name: Run tests
-      run: pub run test
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: dart pub get
+      - name: Format
+        run: dartfmt --dry-run --set-exit-if-changed lib test
+      - name: Analyzer
+        run: dart analyze --fatal-infos --fatal-warnings
+      - name: Tests
+        run: dart test --coverage=.coverage -j1
+      - name: Coverage
+        run: dart run coverage:format_coverage -l -c -i .coverage --report-on=lib --packages=.packages | dart run check_coverage:check_coverage

.gitignore

@@ -13,7 +13,5 @@ pubspec.lock
 # If you don't generate documentation locally you can remove this line.
 doc/api/
 
-# Generated by test_coverage
-test/.test_coverage.dart
-coverage
-coverage_badge.svg
+# Generated by coverage
+/.coverage/

CHANGELOG.md

@@ -5,6 +5,13 @@ 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
+- Sound null-safety support.
+
+### Changed
+- Everything. Again. This is another major **BC-breaking** rework. Please refer to 
+  the API documentation, examples and tests.
+
 ## [4.3.0] - 2020-07-30
 ### Added
 - `meta` parameter for createResourceAt()
@@ -26,24 +33,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Filtering support for collections ([pr](https://github.com/f3ath/json-api-dart/pull/97))
 
 ### Changed
-- The client will not attempt to decode the body of the HTTP response with error status if the correct Content-Type 
-is missing. Before in such cases a `FormatException` would be thrown ([pr](https://github.com/f3ath/json-api-dart/pull/98))
+- The client will not attempt to decode the body of the HTTP response with error status if the correct Content-Type
+  is missing. Before in such cases a `FormatException` would be thrown ([pr](https://github.com/f3ath/json-api-dart/pull/98))
 
 ## [4.1.0] - 2020-05-28
 ### Changed
 - `DartHttp` now defaults to utf8 if no encoding is specified in the response.
 
-## [4.0.0] - 2020-05-26
+## [4.0.0] - 2020-02-29
 ### Changed
-- This is a major **BC-breaking** rework which affected pretty much all areas.
+- Everything. This is a major **BC-breaking** rework which affected pretty much all areas. Please refer to the documentation.
+
+## [3.2.3] - 2020-08-06
+### Fixed
+- Call toJson() on resourceObject when serializing ([#84](https://github.com/f3ath/json-api-dart/pull/84))
+
 
 ## [3.2.2] - 2020-01-07
 ### Fixed
--  Can not decode related resource which is null ([issue](https://github.com/f3ath/json-api-dart/issues/77))
+-  Can not decode related resource which is null ([#77](https://github.com/f3ath/json-api-dart/issues/77))
 
 ## [3.2.1] - 2020-01-01
 ### Fixed
--  Incorrect URL in the example in the Client documentation ([issue](https://github.com/f3ath/json-api-dart/issues/74))
+-  Incorrect URL in the example in the Client documentation ([#74](https://github.com/f3ath/json-api-dart/issues/74))
 
 ## [3.2.0] - 2019-12-30
 ### Added
@@ -69,12 +81,13 @@ is missing. Before in such cases a `FormatException` would be thrown ([pr](https
 
 ## [3.0.0] - 2019-12-17
 ### Added
-- Support for custom non-standard links ([issue](https://github.com/f3ath/json-api-dart/issues/61))
+- Support for custom non-standard links ([#61](https://github.com/f3ath/json-api-dart/issues/61))
 - Client supports `jsonapi` key in outgoing requests.
 - `Document.contentType` constant.
 - `IdentifierObject.fromIdentifier` factory method
 
 ### Changed
+Most of the changes are **BC-BREAKING**.
 - `URLBuilder` was renamed to `UrlFactory`.
 - `DocumentBuilder` was split into `ServerDocumentFactory` and `ClientDocumentFactory`. Some methods were renamed.
 - Static `decodeJson` methods were renamed to `fromJson`.
@@ -84,7 +97,7 @@ is missing. Before in such cases a `FormatException` would be thrown ([pr](https
 - The signature of `Controller`.
 - `Server` was renamed to `JsonApiServer`.
 - `Pagination` was renamed to `PaginationStrategy`.
-
+ 
 ### Removed
 - (Server) `ResourceTarget`, `CollectionTarget`, `RelationshipTarget`  classes.
 - `QueryParameters` interface.
@@ -93,35 +106,37 @@ is missing. Before in such cases a `FormatException` would be thrown ([pr](https
 
 ## [2.1.0] - 2019-12-04
 ### Added
-- `onHttpCall` hook to enable raw http request/response logging ([issue](https://github.com/f3ath/json-api-dart/issues/60)).
+- `onHttpCall` hook to enable raw http request/response logging ([#60](https://github.com/f3ath/json-api-dart/issues/60)).
 
 ## [2.0.3] - 2019-09-29
 ### Fixed
 - Documentation links got broken due to pub.dev update.
 
 ## [2.0.2] - 2019-08-01
 ### Fixed
-- Meta members have incorrect type ([issue](https://github.com/f3ath/json-api-dart/issues/54)).
+- Meta members have incorrect type ([#54](https://github.com/f3ath/json-api-dart/issues/54)).
 
 ## [2.0.1] - 2019-07-12
 ### Fixed
 - Readme example was outdated.
 
 ## [2.0.0] - 2019-07-12
+
 ### Changed
 - This package now consolidates the Client, the Server and the Document in one single library. 
-It does not depend on `json_api_document` and `json_api_server` anymore, please remove these packages 
-from your `pubspec.yaml`.
+    It does not depend on `json_api_document` and `json_api_server` anymore, please remove these packages 
+    from your `pubspec.yaml`.
 - The min Dart SDK version bumped to `2.3.0`
 - The Client requires an instance of HttpClient to be passed to the constructor explicitly.
 - Both the Document and the Server have been refactored with lots of **BREAKING CHANGES**. 
-See the examples and the functional tests for details.
+    See the examples and the functional tests for details.
 - Meta properties are not defensively copied, but set directly. Meta property behavior is unified across 
-the Document model.
+    the Document model.
 
 ### Removed
 - `JsonApiParser` is removed. Use the static `decodeJson` methods in the corresponding classes instead.
 
+
 ## [1.0.1] - 2019-04-05
 ### Fixed
 - Bumped the dependencies versions due to a bug in `json_api_document`.
@@ -136,54 +151,55 @@ the Document model.
 - Renamed `client.removeToOne(...)` to `client.deleteToOne(...)`
 
 ## [0.5.0] - 2019-03-21
-### Added
-- Related collection pagination
-- Async operations support
-
 ### Changed
 - More BC-breaking changes in the Server
 
 ### Fixed
-- Location headers generated incorrectly
+- Location headers were incorrectly generated by Server
 
-## [0.4.0] - 2019-03-17
 ### Added
-- Compound documents support in Client (Server-side support is still very limited)
+- Related collection pagination
+- Async operations support
 
+## [0.4.0] - 2019-03-17
 ### Changed
 - Parsing logic moved out
 - Some other BC-breaking changes in the Document
 - Huge changes in the Server
 
+### Added
+- Compound documents support in Client (Server-side support is still very limited)
+
 ### Fixed
 - Server was not setting links for resources and relationships
 
 ## [0.3.0] - 2019-03-16
+### Changed
+- Huge BC-breaking refactoring in the Document model which propagated everywhere
+
 ### Added
 - Resource attributes update
 - Resource relationships update
 
-### Changed
-- Huge BC-breaking refactoring in the Document model which propagated everywhere
-
 ## [0.2.0] - 2019-03-01
 ### Added
 - Improved ResourceController error handling
 - Resource creation
 - Resource deletion
 
-## 0.1.0 - 2019-02-27
+## [0.1.0] - 2019-02-27
 ### Added
 - Client: fetch resources, collections, related resources and relationships
 
-[Unreleased]: https://github.com/f3ath/json-api-dart/compare/4.3.0...HEAD
+[Unreleased]: https://github.com/f3ath/json-api-dart/compare/4.3.0..HEAD
 [4.3.0]: https://github.com/f3ath/json-api-dart/compare/4.2.2...4.3.0
 [4.2.2]: https://github.com/f3ath/json-api-dart/compare/4.2.1...4.2.2
 [4.2.1]: https://github.com/f3ath/json-api-dart/compare/4.2.0...4.2.1
 [4.2.0]: https://github.com/f3ath/json-api-dart/compare/4.1.0...4.2.0
 [4.1.0]: https://github.com/f3ath/json-api-dart/compare/4.0.0...4.1.0
 [4.0.0]: https://github.com/f3ath/json-api-dart/compare/3.2.2...4.0.0
-[3.2.2]: https://github.com/f3ath/json-api-dart/compare/3.2.1...3.2.2
+[3.2.3]: https://github.com/f3ath/json-api-dart/compare/3.2.2..3.2.3
+[3.2.2]: https://github.com/f3ath/json-api-dart/compare/3.2.1..3.2.2
 [3.2.1]: https://github.com/f3ath/json-api-dart/compare/3.2.0...3.2.1
 [3.2.0]: https://github.com/f3ath/json-api-dart/compare/3.1.0...3.2.0
 [3.1.0]: https://github.com/f3ath/json-api-dart/compare/3.0.0...3.1.0
@@ -199,4 +215,5 @@ the Document model.
 [0.5.0]: https://github.com/f3ath/json-api-dart/compare/0.4.0...0.5.0
 [0.4.0]: https://github.com/f3ath/json-api-dart/compare/0.3.0...0.4.0
 [0.3.0]: https://github.com/f3ath/json-api-dart/compare/0.2.0...0.3.0
-[0.2.0]: https://github.com/f3ath/json-api-dart/compare/0.1.0...0.2.0
+[0.2.0]: https://github.com/f3ath/json-api-dart/compare/0.1.0...0.2.0
+[0.1.0]: https://github.com/f3ath/json-api-dart/releases/tag/0.1.0

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Alexey Karapetov
+Copyright (c) 2019-2021 Alexey Karapetov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,142 +1,6 @@
-# JSON:API for Dart/Flutter
+# JSON:API Client and Server for Dart/Flutter. Version 5.
 
-[JSON:API] is a specification for building APIs in JSON.
+[JSON:API] is a specification for building JSON APIs. The documentation is a work-in-progress.
 
-This package consists of several libraries:
-- The [Document library] is the core of this package. It describes the JSON:API document structure
-- The [Client library] is a JSON:API Client for Flutter, Web and Server-side
-- The [Server library] is a framework-agnostic JSON:API server implementation
-- The [HTTP library] is a thin abstraction of HTTP requests and responses
-- The [Query library] builds and parses the query parameters (page, sorting, filtering, etc)
-- The [Routing library] builds and matches URIs for resources, collections, and relationships
-
-## Document model
-The main concept of JSON:API model is the [Resource]. 
-Resources are passed between the client and the server in the form of a JSON-encodable [Document]. 
-
-## Client
-[JsonApiClient] is an implementation of the JSON:API client supporting all features of the JSON:API standard:
-- fetching resources and collections (both primary and related) 
-- creating resources
-- deleting resources
-- updating resource attributes and relationships
-- direct modification of relationships (both to-one and to-many)
-- [async processing](https://jsonapi.org/recommendations/#asynchronous-processing)
-
-The client returns back a [Response] which contains the HTTP status code, headers and the JSON:API [Document].
-
-Sometimes the request URIs can be inferred from the context. 
-For such cases you may use the [RoutingClient] which is a wrapper over the [JsonApiClient] capable of inferring the URIs.
-The [RoutingClient] requires an instance of [RouteFactory] to be provided.
-
-[JsonApiClient] itself does not make actual HTTP calls. 
-Instead, it calls the underlying [HttpHandler] which acts as an HTTP client (must be passed to the constructor).
-The library comes with an implementation of [HttpHandler] called [DartHttp] which uses the Dart's native http client.
-
-## Server
-This is a framework-agnostic library for implementing a JSON:API server.
-It may be used on its own (a fully functional server implementation is included) or as a set of independent components.
-
-### Request lifecycle
-#### HTTP request
-The server receives an incoming [HttpRequest] containing the HTTP headers and the body represented as a String.
-When this request is received, your server may decide to check for authentication or other non-JSON:API concerns
-to prepare for the request processing, or it may decide to fail out with an error response.
-
-#### JSON:API request
-The [RequestConverter] is then used to convert the HTTP request to a [JsonApiRequest].
-[JsonApiRequest] abstracts the JSON:API specific details,
-such as the request target (a collection, a resource or a relationship) and the decoded body (e.g. [Resource] or [Identifier]).
-At this point it is possible to determine whether the request is a valid JSON:API request and to read the decoded payload.
-You may perform some application-specific logic, e.g. check for authentication.
-Each implementation of [JsonApiRequest] has the `handleWith()` method to dispatch a call to the right method of the [Controller].
-
-#### Controller
-The [Controller] consolidates all methods to process JSON:API requests. 
-Every controller method must return an instance of [JsonApiResponse] (or another type, the controller is generic). 
-This library comes with a particular implementation of the [Controller] called [RepositoryController].
-The [RepositoryController] takes care of all JSON:API specific logic (e.g. validation, filtering, resource 
-inclusion) and translates the JSON:API requests to calls to a resource [Repository].
-
-#### Repository (optional)
-The [Repository] is an interface separating the data storage concerns from the specifics of the API.
-
-#### JSON:API response
-When an instance of [JsonApiResponse] is returned from the controller, the [ResponseConverter] 
-converts it to an [HttpResponse]. 
-The converter takes care of JSON:API transport-layer concerns.
-In particular, it:
-- generates a proper [Document], including the HATEOAS links or meta-data
-- encodes the document to JSON string
-- sets the response headers
-
-#### HTTP response
-The generated [HttpResponse] is sent to the underlying HTTP system.
-This is the final step. 
-
-## HTTP
-This library is used by both the Client and the Server to abstract out the HTTP protocol specifics.
-The [HttpHandler] interface turns an [HttpRequest] to an [HttpResponse].
-The Client consumes an implementation of [HttpHandler] as a low-level HTTP client.
-The Server is itself an implementation of [HttpHandler].
-
-## Query
-This is a set of classes for building avd parsing some URL query parameters defined in the standard.
-- [Fields] for [Sparse fieldsets]
-- [Include] for [Inclusion of Related Resources]
-- [Page] for [Collection Pagination]
-- [Sort] for [Collection Sorting]
-
-## Routing
-Defines the logic for constructing and matching URLs for resources, collections and relationships.
-The URL construction is used by both the Client (See [RoutingClient] for instance) and the Server libraries.
-The [StandardRouting] implements the [Recommended URL design].
 
 [JSON:API]: https://jsonapi.org
-[Sparse fieldsets]: https://jsonapi.org/format/#fetching-sparse-fieldsets
-[Inclusion of Related Resources]: https://jsonapi.org/format/#fetching-includes
-[Collection Pagination]: https://jsonapi.org/format/#fetching-pagination
-[Collection Sorting]: https://jsonapi.org/format/#fetching-sorting
-[Recommended URL design]: https://jsonapi.org/recommendations/#urls
-
-[Client library]: https://pub.dev/documentation/json_api/latest/client/client-library.html
-[Server library]: https://pub.dev/documentation/json_api/latest/server/server-library.html
-[Document library]: https://pub.dev/documentation/json_api/latest/document/document-library.html
-[Query library]: https://pub.dev/documentation/json_api/latest/query/query-library.html
-[Routing library]: https://pub.dev/documentation/json_api/latest/uri_design/uri_design-library.html
-[HTTP library]: https://pub.dev/documentation/json_api/latest/http/http-library.html
-
-
-[Resource]: https://pub.dev/documentation/json_api/latest/document/Resource-class.html
-[Identifier]: https://pub.dev/documentation/json_api/latest/document/Identifier-class.html
-[Document]: https://pub.dev/documentation/json_api/latest/document/Document-class.html
-[JsonApiClient]: https://pub.dev/documentation/json_api/latest/client/JsonApiClient-class.html
-
-
-[Response]: https://pub.dev/documentation/json_api/latest/client/Response-class.html
-[RoutingClient]: https://pub.dev/documentation/json_api/latest/client/RoutingClient-class.html
-[DartHttp]: https://pub.dev/documentation/json_api/latest/client/DartHttp-class.html
-
-
-[RequestConverter]: https://pub.dev/documentation/json_api/latest/server/RequestConverter-class.html
-[JsonApiResponse]: https://pub.dev/documentation/json_api/latest/server/JsonApiResponse-class.html
-[ResponseConverter]: https://pub.dev/documentation/json_api/latest/server/ResponseConverter-class.html
-[JsonApiRequest]: https://pub.dev/documentation/json_api/latest/server/JsonApiRequest-class.html
-[Controller]: https://pub.dev/documentation/json_api/latest/server/Controller-class.html
-[Repository]: https://pub.dev/documentation/json_api/latest/server/Repository-class.html
-[RepositoryController]: https://pub.dev/documentation/json_api/latest/server/RepositoryController-class.html
-
-
-[HttpHandler]: https://pub.dev/documentation/json_api/latest/http/HttpHandler-class.html
-[HttpRequest]: https://pub.dev/documentation/json_api/latest/http/HttpRequest-class.html
-[HttpResponse]: https://pub.dev/documentation/json_api/latest/http/HttpResponse-class.html
-
-
-[Fields]: https://pub.dev/documentation/json_api/latest/query/Fields-class.html
-[Include]: https://pub.dev/documentation/json_api/latest/query/Include-class.html
-[Page]: https://pub.dev/documentation/json_api/latest/query/Page-class.html
-[Sort]: https://pub.dev/documentation/json_api/latest/query/Sort-class.html
-
-
-[RouteFactory]: https://pub.dev/documentation/json_api/latest/routing/RouteFactory-class.html
-[StandardRouting]: https://pub.dev/documentation/json_api/latest/routing/StandardRouting-class.html