Merge pull request #105 from inaka/dev

Release 4.0

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. `Jayme` a
 
 ---
 
+### 4.x Releases
+
+- `4.0.x` releases - [4.0.0](#400)
+
 ### 3.x Releases
 
 - `3.0.x` releases - [3.0.0](#300)
@@ -18,6 +22,19 @@ All notable changes to this project will be documented in this file. `Jayme` a
 
 ---
 
+## 4.0.0
+
+- `CRUDRepository` protocol no longer exists. Its functionalities have now been divided into four separate protocols: `Creatable`, `Readable`, `Updatable` and `Deletable`. (Issue [#84](https://github.com/inaka/Jayme/issues/84))
+- `PagedRepository` protocol no longer exists. Its `findByPage(pageNumber:)` method has been moved to the `Readable` protocol and has a new signature: `read(pageNumber:pageSize:)`.  (Issue [#95](https://github.com/inaka/Jayme/issues/95))
+- `findAll()` has been renamed to `readAll()` in the `Readable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+- `find(byId:)` has been renamed to `read(id:)` in the `Readable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+- `update(_)` has been renamed to `update(_, id:)` in the `Updatable` protocol; a new `update(_)` function has been added (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+- `delete(_)` has been renamed to `delete(id:)` in the `Deletable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+- Added `create([entity1, entity2, …])` function in the `Creatable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+- Added `read()` function in the `Readable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87])) 
+- Added `update([entity1, entity2, …])` function in the `Updatable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+- Added `delete()` function in the `Deletable` protocol (Issue [#87](https://github.com/inaka/Jayme/issues/87]))
+
 ## 3.0.0
 
 - All of the changes involved in this release are due to [Swift 3 breaking changes](https://apple.github.io/swift-evolution/) and its [new APIs design](https://swift.org/documentation/api-design-guidelines/).

Documentation/Jayme 3.0 Migration Guide.md

@@ -12,7 +12,7 @@ This guide is provided in order to ease the transition of existing applications
 
 ### Automatically Suggested Changes
 
-There are some compiler migration mechanisms that have been implemented in Jayme 2.0 by leveraging the `@unavailable` attribute in a `Compatibility.swift` file.
+There are some compiler migration mechanisms that have been implemented in Jayme 3.0 by leveraging the `@unavailable` attribute in a `Compatibility.swift` file.
 
 ***For these changes you only have to follow the compiler suggestions and they should be applied automatically.***
 

Documentation/Jayme 4.0 Migration Guide.md

@@ -0,0 +1,69 @@
+# Jayme 4.0 Migration Guide
+
+**Jayme 4.0** is the latest major release of Jayme. As a major release, following Semantic Versioning conventions, 4.0 introduces several API-breaking changes that one should be aware of.
+
+This guide is provided in order to ease the transition of existing applications using Jayme 3.x to the latest APIs, as well as explain the design and structure of new and changed functionality.
+
+---
+
+Based in our experiences by using Jayme in production projects, **we've decided to focus Jayme 4.0 on an enhanced CRUD API design**, that is better organized as of this version, and provides more functionality.
+
+
+
+#### Better organized CRUD API
+
+The main change that you need to be aware of is that **your repositories will no longer conform to a `CRUDRepository` protocol**. Instead, they can conform to `Creatable`, `Readable`, `Updatable` and `Deletable` protocols, depending on what each repository needs.
+
+By organizing the CRUD API this way, your code will follow the [YAGNI principle](https://en.wikipedia.org/wiki/You_aren't_gonna_need_it) better than before. For instance: If you have a repository whose entities only need to be _read_, but not _created_, _updated_ or _deleted_, then you shouldn't need to write a `dictionaryValue` method for that entity type at all. You were forced to do so when conforming to `CRUDRepository`, but now, by only conforming to the `Readable` protocol, you don't have to.
+
+> This new organization has been discussed in the issue [#84](https://github.com/inaka/Jayme/issues/84). Check it out for further reference.
+
+
+
+#### More CRUD functionality
+
+The other breakthrough is that now repositories can be aimed to perform operations in two ways: **single-entity** or **multiple-entity**.
+
+Typical examples of *single-entity* endpoints are `/me`, `/profile` or `/device`, whereas typical examples of *multiple-entity* endpoints are `/users`, `/posts`, `/feed_items` or `/comments`.
+
+Sometimes your repository needs to perform operations that always apply to a single entity. Under this scenario, your repository would not, for instance, delete an entity by `id`, instead, you would prefer to use a generic `delete()` method to delete _the only entity_ that lives in the repository, and not the `delete(id:)` method.
+
+Below is a table exposing all the methods that are available in the `Creatable`, `Readable`, `Updatable` and `Deletable` protocols, categorizing them by interest: *single* vs. *multiple* entity repository.
+
+<table>
+<th></th><th>Single-Entity Repository<br>(e.g. /profile)</th><th>Multiple-Entity Repository<br>(e.g. /users)</th>
+<tr><td><i>Creatable</i></td><td><b>.create(e)</b><br>POST /profile → ⚪ </td><td><b>.create(e)</b><br>POST /users → ⚪<br><br><b>.create([e1, e2, ...])</b><br>POST /users → [⚪ ,⚪ , ...]</td></tr>
+<tr><td><i>Readable</i></td><td><b>.read()</b><br>GET /profile → ⚪ </td><td><b>.read(id: x)</b><br>GET /users/x →⚪ <br><br><b>.readAll()</b><br>GET /users → [⚪ ,⚪ , ...]</td></tr></tr>
+<tr><td><i>Updatable</i></td><td><b>.update(e)</b><br>PUT /profile → ⚪</td><td><b>.update(e, id: x)</b><br>PUT /users/x → ⚪<br><br><b>.update([e1, e2, ...])</b><br>PATCH /users → [⚪ ,⚪ , ...]</td></tr>
+<tr><td><i>Deletable</i></td><td><b>.delete()</b><br>DELETE /profile</td><td><b>.delete(id: x)</b><br>DELETE /users/x</td></tr>
+
+</table>
+
+> This new organization has been discussed in the issue [#87](https://github.com/inaka/Jayme/issues/87). Check it out for further reference.
+
+---
+
+### Automatically Suggested Changes
+
+There are some compiler migration mechanisms that have been implemented in Jayme 4.0 via a `Compatibility.swift` file.
+
+***For these changes you only have to follow the compiler suggestions and they should be applied automatically.***
+
+For instance, `findAll()` has been renamed to `readAll()`: The compiler will automatically suggest the replacement of `findAll()` to `readAll()`.
+
+---
+
+### Manual Changes
+
+However, there are some other changes that would have required overwhelming (if ever possible) mechanisms to be implemented in order to keep automatic suggestions from the compiler. In consequence, we decided not to implement them.
+
+⚠️ ***Therefore, it's up to you to perform these changes manually.***
+
+- **CRUDRepository** no longer exists. The compiler will suggest you to use the `Creatable`, `Readable`, `Updatable` and `Deletable` protocols instead, but it's up to you to write which ones each of your repository needs to conform to.
+- **Watch out the `update(_)` method**. In Jayme 3.x, this method appends the entity's `id` to the URL path. In Jayme 4.x, this method does not append the `id`, there is the `update(_, id:)` method for doing so. Therefore, anywhere you were calling `update(entity)`, you have to change it by `update(entity, id: entity.id)`. You have to do it manually, because `update(entity)` still compiles, but has a different behavior as of Jayme 4.0.
+- **PagedRepository** no longer exists. The compiler will suggest you to use the `Readable` protocol instead. However, you have to manually change any call to the `findByPage(pageNumber:)` method, which now is `read(pageNumber:pageSize:)`.
+- **Dictionaries** are now represented as `[AnyHashable: Any]` instead of `[String: Any]`. You have to manually change these appearances in your `DictionaryInitializable` and `DictionaryRepresentable` methods of your entities.
+
+---
+
+For further documentation regarding changes, check out the **[Change Log](../Changelog.md)**.