Update documentation

Author: manomintis

CHANGELOG.md

@@ -1,7 +1,16 @@
 
 # Change Log
 All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2024-06-19
 
+### Added
+- pick() for picking certain values only
+- omit() for excluding certain values from results
+- redefine() for composing results according to manually defined map
+- paginate() and refinePaginate() for offset-based paginating of the results
+- Method chaining support
+
 ## [1.1.0] - 2024-04-03
 
 ### Added

README.md

@@ -14,67 +14,57 @@ Install the package:
 npm install adonis-api-resources
 ```
 
-
 Configure the package:
 
 ```sh
 node ace configure adonis-api-resources
 ```
 
-
-## Usage
-
-
-Generate a new resource:
+Generate a new resource (i.e. for a user):
 
 ```sh
 node ace make:resource user
 ```
 
-
-Edit newly generated app/resources/users_resource.ts to create output you need. This example shows how you may output user's full name even if your implementation of user model has separate fields for the first and last names:
-
-```typescript
-...
- return {
- full_name: data.firstName + ' ' + data.lastName,
- }
-...
-```
-
-
 Import your generated resource before using it, i.e. in a controller:
 
 ```typescript
 import UserResource from '#resources/user_resource'
 ```
 
-
 Remove old endpoint return declaration:
 
 ```typescript
 return user
 ```
 
-
-Use the your generated resource instead:
+Use the your generated resource instead (either of them):
 
 ```typescript
 return new UserResource(user).refine()
 ```
 
+## redefine() and refine() - manually defined map
 
-You may also use arrays of models, with resources:
+redefine() modifies a model or array of models according to your custom map defined in resource file. Used along with get() method, which indicates that data processing is done and provides the result. You can also use refine(), which is an alias of redefine().get(), see example below.
+
+Edit newly generated app/resources/user_resource.ts to create output you need. This example shows how you may output user's full name even if your implementation of user model has separate fields for the first and last names:
 
 ```typescript
-return new UserResource(users).refine()
+...
+ return {
+ full_name: data.firstName + ' ' + data.lastName,
+ }
+...
 ```
 
-That's it. Enjoy yourself!
-
+You may also use arrays of models, with resources:
 
-## Expected output examples
+```typescript
+return new UserResource(users).refine()
+```
 
+### Output examples
 
 Model:
 
@@ -84,7 +74,6 @@ Model:
 }
 ```
 
-
 Array of models:
 
 ```json
@@ -98,17 +87,46 @@ Array of models:
 ]
 ```
 
+## paginate() and refinePaginate()
+
+In case you are dealing with not paginateable array you can still create pagination using this extension. refinePaginate() is an alias of redefine().paginate(), see examples below:
+
+```typescript
+return new UserResource(users).refinePaginate(page, limit)
+return new UserResource(users).redefine().paginate(page, limit)
+```
 
-## Pagination support
+Arguments:
 
+page - optional (default value is 1)
 
-Offset-based pagination is supported. Example usage:
+limit - optional (default value is 10)
+
+## pick()
+
+No map definition is needed, once you only want to pick a few values of the object and leave other values behind. Examples:
 
 ```typescript
-const users = await User.query().paginate(1, 10)
-return new UserResource(users).refine()
+return new UserResource(users).pick('firstName').get()
+return new UserResource(users).pick('firstName', 'lastName', 'email').paginate(1, 20)
 ```
 
+## omit()
+
+No map definition is needed, once you only want to exclude a few values from the object. Examples:
+
+```typescript
+return new UserResource(users).omit('id').paginate()
+return new UserResource(users).omit('createdAt', 'updatedAt').get()
+```
+
+## get()
+
+get() finalizes data processing. While pick(), omit() and redefine() modify data, trailing get() or paginate() is needed to complete the response. This requirement is not applied to refine() and refinePaginate()
+
+## Lucid pagination support
+
+Lucid offset-based pagination is supported.
 
 [gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/manomintis/adonis-api-resources/test.yml?style=for-the-badge
 [gh-workflow-url]: https://github.com/manomintis/adonis-api-resources/actions/workflows/test.yml "Github action"