cuprum-rails 0.1.0 → 0.2.0

data/README.md

@@ -8,6 +8,7 @@ Cuprum::Rails defines the following objects:
     - [Commands](#commands): Each collection is comprised of `Cuprum` commands, which implement common collection operations such as inserting or querying data.
 - [Controllers](#controllers): Decouples controller responsibilities for precise control, reusability, and reduction of boilerplate code.
     - [Actions](#actions): Implement a controller's actions as a `Cuprum` command.
+    - [Middleware](#middleware): Wraps a controller's actions with additional functionality.
     - [Requests](#requests): Encapsulates a controller request.
     - [Resources](#resources) and [Routes](#routes): Configuration for a resourceful controller.
     - [Responders](#responders) and [Responses](#responses): Generate controller responses from action results.
@@ -31,7 +32,7 @@ The second benefit is *reusability*. Breaking down a controller into its constit
 
 ### Compatibility
 
-Cuprum::Collections is tested against Ruby (MRI) 2.6 through 3.0.
+Cuprum::Rails is tested against Ruby (MRI) 3.0 through 3.2, and Rails 6.1 through 7.1.
 
 ### Documentation
 
@@ -39,7 +40,7 @@ Documentation is generated using [YARD](https://yardoc.org/), and can be generat
 
 ### License
 
-Copyright (c) 2021 Rob Smith
+Copyright (c) 2021-2022 Rob Smith
 
 Stannum is released under the [MIT License](https://opensource.org/licenses/MIT).
 
@@ -59,7 +60,7 @@ Please note that the `Cuprum::Collections` project is released with a [Contribut
 
 ## Reference
 
-<a id="collections"></a>
+<span id="collections"></span>
 
 ### Collections
 
@@ -110,6 +111,7 @@ Initializing a collection requires the `:record_class` keyword, which should be
 - The `:member_name` parameter is used to create an envelope for singular query commands such as the `FindOne` command. If not given, the member name will be generated automatically as a singular form of the collection name.
 - The `:primary_key_name` parameter specifies the attribute that serves as the primary key for the collection entities. The default value is `:id`.
 - The `:primary_key_type` parameter specifies the type of the primary key attribute. The default value is `Integer`.
+- The `:qualified_name` parameter acts as a unique identifier for the collection. It is used as the unique key in repositories.
 
 <a id="commands"></a>
 
@@ -388,20 +390,39 @@ require 'cuprum/rails/repository'
 A `Cuprum::Rails::Repository` is a group of Rails collections. A single repository might represent all or a subset of the tables in your database.
 
 ```ruby
-repository = Cuprum::Collections::Repository.new
+repository = Cuprum::Rails::Repository.new
 repository.key?('books')
 #=> false
 
-repository.add(books_collection)
-
-repository.key?('books')
-#=> true
-repository.keys
-#=> ['books']
+collection = repository.find_or_create(entity_class: Book)
+#=> a Cuprum::Rails::Collection
+collection.collection_name
+#=> 'books'
+collection.qualified_name
+#=> 'books'
 repository['books']
 #=> the books collection
 ```
 
+If the model has a namespace, e.g. `Authentication::User`, the `#collection_name` will be based on the last name segment, while the `#qualified_name` will be based on the entire name.
+
+```ruby
+repository = Cuprum::Rails::Repository.new
+repository.key?('authentication/users')
+#=> false
+
+collection = repository.find_or_create(entity_class: Authentication::User)
+#=> a Cuprum::Rails::Collection
+collection.collection_name
+#=> 'users'
+collection.qualified_name
+#=> 'authentication/users'
+repository['authentication/users']
+#=> the users collection
+```
+
+You can also pass the `#collection_name` and `#qualified_name` as parameters.
+
 <a id="controllers"></a>
 
 ### Controllers
@@ -439,7 +460,7 @@ class BooksController
     )
   end
 
-  responder :html, Cuprum::Rails::Responders::Html::PluralResource
+  responder :html, Cuprum::Rails::Responders::Html::Resource
   responder :json, Cuprum::Rails::Responders::Json::Resource
 
   action :create,  Cuprum::Rails::Actions::Create
@@ -464,6 +485,14 @@ The [Responders](#responders) determine what request formats are accepted by the
 
 The [Serializers](#serializers) are used in API responses (such as a JSON response) to convert application data into a serialized format. `Cuprum::Rails` defines a base set of serializers for simple data; applications can either set a generic serializer for records (as in `BooksController`, above) or set specific serializers for each record class on a per-controller basis. Serializers are defined by overriding the `.serializers` class method - make sure to call `super()` and merge the results, unless you specifically want to override the default values.
 
+You can also define `.default_format`, which sets a default value for when the request does not specify a format. For example, a request to `/api/books.html` specifies the `:html` format, while there is no format specified for `/api/books`.
+
+```ruby
+class BooksController
+  default_format :html
+end
+```
+
 #### Defining Actions
 
 A non-abstract controller should define at least one [Action](#actions), corresponding to a page, process, or API endpoint for the application. Actions are defined using the `.action` class method, which takes two parameters: an `action_name`, which should be either a string or a symbol (e.g. `:publish`), and an `action_class`, which is a subclass of `Cuprum::Rails::Action`.
@@ -484,6 +513,47 @@ class BooksController
 end
 ```
 
+<a id="controllers-defining-middleware"></a>
+
+#### Defining Middleware
+
+You can use [middleware](#middleware) to insert functionality before, after, or around controller actions. Think of it as a supercharged alternative to the traditional Rails `before_action` and `after_action` hooks, but without the magic behavior. Use cases for middleware include:
+
+- Authentication
+- Logging
+- Profiling
+
+Middleware commands have a specific interface. See [Middleware](#middleware), below, for how to define your own middleware commands.
+
+```ruby
+class BooksController
+  middleware LoggingMiddleware
+  middleware AuthenticationMiddleware, except: %i[index show]
+  middleware ProfilingMiddleware,      only:   %i[create update]
+end
+```
+
+Adding middleware to a controller is straightforward. In our example above, the `LoggingMiddleware` will run for all actions, the `AuthenticationMiddleware` will run for all actions except for `:index` and `:show`, and the `ProfilingMiddleware` will run for the `:create` and `:update` actions.
+
+Each middleware command can have functionality that runs before, after, or around the action (and subsequent middleware). Code that runs before the action has access to the `request:`, and can modify the request passed to the next command or even skip the action and return its own result. Code that runs after the action has access to the `request:` and the action `result`, and can modify or replace the result.
+
+The middleware is executed in the order it is defined. For the `BooksController#create` action, the code would run as follows:
+
+1. `LoggingMiddleware`: Any code that executes before the action.
+1. `AuthenticationMiddleware`: Any code that executes before the action.
+1. `ProfilingMiddleware`: Any code that executes before the action.
+1. `Books::CreateAction`
+1. `ProfilingMiddleware`: Any code that executes after the action.
+1. `AuthenticationMiddleware`: Any code that executes after the action.
+1. `LoggingMiddleware`: Any code that executes after the action.
+
+Code that runs before or around the action can skip the action and return its own result. For example, the `AuthenticationMiddleware` will check for a valid session. If there is not a valid session, it will return a failing result rather than calling the action. In this case, the code would run as follows:
+
+1. `LoggingMiddleware`: Any code that executes before the action.
+1. `AuthenticationMiddleware`: The session is not found, so the action is not called.
+1. `AuthenticationMiddleware`: Any code that executes after the action.
+1. `LoggingMiddleware`: Any code that executes after the action.
+
 <a id="controllers-action-lifecycle"></a>
 
 #### The Action Lifecycle
@@ -492,10 +562,11 @@ Inside a controller action, `Cuprum::Rails` splits up the responsibilities of re
 
 1. The Action
     1. The `action_class` is initialized, passing the controller `resource` to the constructor and returning the `action`.
-    2. The controller `#request` is wrapped in a `Cuprum::Rails::Request`, which is passed to the `action`'s `#call` method, returning the `result`.
+    2. The `action` is wrapped with any `middleware` that is defined by the controller for that action.
+    3. The controller `#request` is wrapped in a `Cuprum::Rails::Request`, which is passed to the `action`'s `#call` method, returning the `result`.
 2. The Responder
     1. The `responder_class` is found for the request based on the request's `format` and the configured `responders`.
-    2. The `responder_class` is initialized with the `action_name`, `resource`, and `serializers`, returning the `responder`.
+    2. The `responder_class` is initialized with the `action_name`, `controller_name`, `resource`, and `serializers`, returning the `responder`.
     3. The `responder` is called with the action `result`, and finds a matching `response` based on the action name, the result's success or failure, and the result error (if any).
 3. The Response
     1. The `response` is then called with the controller, which allows it to reference native Rails controller methods for rendering or redirecting.
@@ -506,15 +577,15 @@ Let's walk through this step by step. We start by making a `POST` request to `/b
     1. We initialize our configured action class, which is `Cuprum::Rails::Actions::Index`.
     2. We wrap the request in a `Cuprum::Rails::Request`, and call our `action` with the wrapped `request`. The action performs the business logic (building, validating, and persisting a new `Book`) and returns an instance of `Cuprum::Result`. In our case, the book's attributes are valid, so the result has a `:status` of `:success` and a value of `{ 'book' => #<Book id: 0, title: 'Gideon the Ninth'> }`.
 2. The Responder
-    1. We're making an HTML request, so our controller will use the responder configured for the `:html` format. In our case, this is `Cuprum::Rails::Responders::Html::PluralResource`, which defines default behavior for responding to resourceful requests.
-    2. Our `Responders::Html::PluralResource` is initialized, giving us a `responder`.
+    1. We're making an HTML request, so our controller will use the responder configured for the `:html` format. In our case, this is `Cuprum::Rails::Responders::Html::Resource`, which defines default behavior for responding to resourceful requests.
+    2. Our `Responders::Html::Resource` is initialized, giving us a `responder`.
     3. The `responder` is called with our `result`. There is a match for a successful `:create` action, which returns an instance of `Cuprum::Rails::Responses::Html::RedirectResponse` with a `path` of `/books/0`.
 3. The Response
     1. Finally, our `response` object is called. The `RedirectResponse` directs the controller to redirect to `/books/0`, which is the `:show` page for our newly created `Book`.
 
 <a id="actions"></a>
 
-### Actions
+### Controller Actions
 
 ```ruby
 require 'cuprum/rails/action'
@@ -547,8 +618,11 @@ class PublishBook < Cuprum::Rails::Actions::ResourceAction
   private
 
   def process(request)
-    book_id = step { resource_id }
-    book    = step { collection.find_one.call(entity_id: book_id) }
+    super
+
+    step { require_resource_id }
+
+    book = step { collection.find_one.call(primary_key: resource_id) }
 
     book.published_at = DateTime.current
 
@@ -561,12 +635,57 @@ end
 
 `ResourceAction` delegates `#collection`, `#resource_name`, and `#singular_resource_name` to the `#resource`. In addition, it defines the following helper methods. Each method returns a `Cuprum::Result`, so you can use the `#step` control flow to handle command errors.
 
-- `#resource_id`: Wraps `params[:id]` in a result, or returns a failing result with a `Cuprum::Rails::Errors::MissingParameters` error.
-- `#resource_params`: Wraps `params[singular_resource_name]` and filters them using `resource.permitted_attributes`. Returns a failing result with a `Cuprum::Rails::Errors::MissingParameters` error if the resource params are missing, or with a `Cuprum::Rails::Errors::UndefinedPermittedAttributes` error if the resource does not define permitted attributes.
+- `#resource_id`: Returns `params[:id]`.
+- `#resource_params`: Filters `params[singular_resource_name]` and using `resource.permitted_attributes`.
+
+#### Transactions
+
+`Cuprum::Rails` integrates with `ActiveRecord` to support database transactions. The `#transaction` method integrates native transactions with the `Cuprum` control flow:
+
+```ruby
+class ReturnBook < Cuprum::Rails::Actions::ResourceAction
+  private
+
+  def books_collection
+    @books_collection ||= repository['books']
+  end
+
+  def process(request)
+    super
+
+    step { require_resource_id }
+
+    loan = step { collection.find_one.call(primary_key: resource_id) }
+
+    transaction do
+      step { return_book(loan.book_id) }
+
+      step { collection.destroy_one.call(entity: loan) }
+    end
+  end
+
+  def return_book(book_id)
+    step do
+      books_collection.assign_one.call(
+        attributes: { 'borrowed' => false },
+        entity: book
+      )
+    end
+
+    books_collection.update_one.call(entity: book)
+  end
+end
+```
+
+Here, we are defining a custom action for returning a borrowed library book. Inside our transaction, we are defining two steps. First, we are marking the book as no longer borrowed, so other patrons will be able to check it out or request it. Second, we destroy the join model between the user and the book. If either of these steps returns a failing result, the transaction will automatically roll back.
+
+If you do not want to roll back on a failed step, use the native `ActiveRecord.transaction` method instead.
+
+#### Actions
 
 `Cuprum::Rails` also provides some pre-defined actions to implement classic resourceful controllers. Each resource action calls one or more commands from the resource collection to query or persist the record or records.
 
-#### Create
+##### Create
 
 The `Create` action passes the resource params to `collection.build_one`, validates the record using `collection.validate_one`, and finally inserts the new record into the collection using the `collection.insert_one` command. The action returns a Hash containing the created record.
 
@@ -583,13 +702,11 @@ Book.where(title: 'Gideon the Ninth').exist?
 #=> true
 ```
 
-If the created record is not valid, the action returns a failing result with a `Cuprum::Collections::Errors::FailedValidation` error.
-
-If the params do not include attributes for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::MissingParameters` error.
+If the params do not include attributes for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::InvalidParameters` error.
 
-If the permitted attributes are not defined for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::UndefinedPermittedAttributes` error.
+If the created record is not valid, the action returns a failing result with a `Cuprum::Collections::Errors::FailedValidation` error.
 
-#### Destroy
+##### Destroy
 
 The `Destroy` action removes the record from the collection via `collection.destroy_one`. The action returns a Hash containing the deleted record.
 
@@ -606,9 +723,11 @@ Book.where(id: 0).exist?
 #=> false
 ```
 
+If the params do not include a primary key for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::InvalidParameters` error.
+
 If the record with the given primary key does not exist, the action returns a failing result with a `Cuprum::Collections::Errors::NotFound` error.
 
-#### Edit
+##### Edit
 
 The `Edit` action finds the record with the given primary key via `collection.find_one` and returns a Hash containing the found record.
 
@@ -622,9 +741,11 @@ result.value
 #=> { 'book' => #<Book id: 0> }
 ```
 
+If the params do not include a primary key for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::InvalidParameters` error.
+
 If the record with the given primary key does not exist, the action returns a failing result with a `Cuprum::Collections::Errors::NotFound` error.
 
-#### Index
+##### Index
 
 The `Index` action performs a query on the records using `collection.find_matching`, and returns a Hash containing the found records. You can pass `:limit`, `:offset`, `:order`, and `:where` parameters to filter the results.
 
@@ -642,7 +763,7 @@ result.value
 #=> { 'books' => [#<Book>, #<Book>, #<Book>] }
 ```
 
-#### New
+##### New
 
 The `New` action builds a new record with empty attributes using `collection.build_one`, and returns a Hash containing the new record.
 
@@ -655,7 +776,7 @@ result.value
 #=> { 'book' => #<Book> }
 ```
 
-#### Show
+##### Show
 
 The `Show` action finds the record with the given primary key via `collection.find_one` and returns a Hash containing the found record.
 
@@ -669,9 +790,11 @@ result.value
 #=> { 'book' => #<Book id: 0> }
 ```
 
+If the params do not include a primary key for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::InvalidParameters` error.
+
 If the record with the given primary key does not exist, the action returns a failing result with a `Cuprum::Collections::Errors::NotFound` error.
 
-#### Update
+##### Update
 
 The `Update` action finds the record with the given primary key via `collection.find_one`, assigns the given attributes using `collection.assign_one`, validates the record using `collection.validate_one`, and finally updates the record in the collection using the `collection.update_one` command. The action returns a Hash containing the created record.
 
@@ -688,13 +811,120 @@ Book.find(0).title
 #=> 'Gideon the Ninth'
 ```
 
+If the params do not include a primary key and attributes for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::InvalidParameters` error.
+
 If the record with the given primary key does not exist, the action returns a failing result with a `Cuprum::Collections::Errors::NotFound` error.
 
 If the updated record is not valid, the action returns a failing result with a `Cuprum::Collections::Errors::FailedValidation` error.
 
-If the params do not include attributes for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::MissingParameters` error.
+<a id="middleware"></a>
+
+### Middleware
+
+A middleware command takes two parameters. First, a `next_command` argument, which is the next item in the middleware chain (or the controller action if the middleware is the last one in the chain). Second, a `request:` keyword - this is the [request](#requests) passed down from the controller.
+
+See [Defining Middleware](#controllers-defining-middleware), above, for using middleware in a `Cuprum::Rails::Controller`, or see [Cuprum](github.com/sleepingkingstudios/cuprum) for more information on middleware.
 
-If the permitted attributes are not defined for the resource, the action returns a failing result with a `Cuprum::Rails::Errors::UndefinedPermittedAttributes` error.
+#### Creating Middleware
+
+Each middleware class should be a subclass of `Cuprum::Command` and include `Cuprum::Middleware`. The constructor can optionally take either `:repository` and `:resource` keywords; if these are defined, they are passed the relevant controller property when the middleware is initialized.
+
+```ruby
+class ExampleMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  def initialize(repository:, resource:)
+    super()
+
+    @repository = repository
+    @resource   = resource
+  end
+end
+```
+
+#### Before An Action
+
+Middleware commands can run before an action, similar to a native Rails `before_action` filter.
+
+```ruby
+class AuthenticationMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  private def process(next_command, request:)
+    step { Authentication::RequireUser.call(request: request) }
+
+    super
+  end
+end
+```
+
+Here, we are creating a basic middleware command. We call our authentication command in a `step`, meaning that if the authentication command returns a failing result, we will immediately return that result. This means that our action will not run if the session is invalid.
+
+If the authentication command returns a passing result, we call `super` to invoke the default behavior of `Cuprum::Middleware`. This calls `next_command.call(request: request)` to continue the middleware or invoke the action.
+
+#### After An Action
+
+Likewise, middleware commands can run after an action, similar to a native Rails `after_action` filter.
+
+```ruby
+class LoggingMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  private def process(next_command, request:)
+    result = next_command.call(request: request)
+
+    if result.success?
+      Rails.logger.info(
+        "Successful Request: controller: #{request.controller_name}, action:" \
+          " #{request.action_name}"
+      )
+    else
+      Rails.logger.error(
+        "Failed Request: controller: #{request.controller_name}, action:" \
+          " #{request.action_name}, error: #{result.error.as_json}"
+      )
+    end
+
+    result
+  end
+end
+```
+
+This middleware is a little more complicated. Instead of intercepting the request before the action, here we are taking the result of the action and implementing some custom behavior based on the success or failure of the action. Finally, make sure to return the result.
+
+Note that we are explicitly calling `next_command.call(request: request)` rather than relying on `super`. This is because `super` calls the next command inside a `step`, and will immediately return a failing result rather than continuing through `#process`. For our logging middleware, however, we actually want to handle both passing and failing results.
+
+#### Around An Action
+
+Finally, we can run middleware around an action, similiar to a native Rails `around_action` filter.
+
+```ruby
+class ProfilingMiddleware < Cuprum::Command
+  include Cuprum::Middleware
+
+  private
+
+  def process(next_command, request:)
+    start_time = Time.current
+
+    value = super(next_command, request: request)
+
+    return if value.nil?
+
+    end_time = Time.current
+
+    value.merge('time_elapsed' => time_elapsed(start_time, end_time))
+  end
+
+  def time_elapsed(start_time, end_time)
+    difference = ((end_time - start_time).round(3) * 1_000).to_i
+
+    "#{difference} milliseconds"
+  end
+end
+```
+
+We start by capturing the current time, before the action is run. We then call the action via `super`; this means that the middleware will return immediately on a failed result. Once the action has run, we calculate how long the action took to run and merge that into the result value. In a production environment, we would probably pass that data to a monitoring service.
 
 <a id="requests"></a>
 
@@ -715,8 +945,11 @@ Each request defines the following properties:
 - `#method`: The HTTP method used for the request as a `Symbol`, e.g. `:get` or `:post`.
 - `#parameters`: (also `#params`) The complete parameters for the request, including both params from the request body and from the query string. A `Hash` with `String` keys.
 - `#path`: The relative path of the request, including query params.
+- `#path_parameters`: (also `#path_params`) The path parameters for the request, minus the Rails-provided `action` and `controller` params. A `Hash` with `String` keys.
 - `#query_parameters`: (also `#query_params`) The query parameters for the request. A `Hash` with `String` keys.
 
+The request properties can also be accessed via the `#[]` method (using either String or Symbol keys), or updated via the `#[]=` method. The `#properties` method returns all of the request properties as a `Hash`.
+
 <a id="resources"></a>
 
 ### Resources
@@ -738,7 +971,8 @@ resource.resource_name
 
 A resource must be initialized with either a `resource_class` or a `resource_name`. It defines the following properties:
 
-- `#collection`: A `Cuprum::Collections` collection, used to perform queries and persistence operations on the resource data.
+- `#base_url`: The base url for the collection, used when generating routes.
+- `#collection`: A `Cuprum::Collections` collection, used to perform queries and persistence operations on the resource data. If not given and the collection has a `#resource_class`, then a `Cuprum::Rails::Collection` is automatically generated.
 - `#resource_class`: The `Class` of items in the resource.
 - `#resource_name`: The name of the resource as a `String`. If the resource is initialized with a `resource_class`, the `resource_name` is derived from the given class.
 - `#routes`: A [Cuprum::Rails::Routes](#routes) object for the resource. If not given, a default routes object is generated for the resource.
@@ -853,9 +1087,11 @@ Provides default responses for HTML requests.
 - For a successful result, renders the template for the action and assigns the result value as local variables.
 - For a failing result, redirects to the resource `:index` page (for a collection action) or the resource `:show` page (for a member action).
 
-**Cuprum::Rails::Responders::Html::PluralResource**
+**Cuprum::Rails::Responders::Html::Resource**
 
-Provides some additional response handling for plural resources.
+Provides some additional response handling for resources.
+
+If the resource is plural:
 
 - For a failed `#create` result, renders the `:new` template.
 - For a successful `#create` result, redirects to the `:show` page.
@@ -864,9 +1100,7 @@ Provides some additional response handling for plural resources.
 - For a failed `#update` result, renders the `:edit` template.
 - For a successful `#update` result, redirects to the `:show` page.
 
-**Cuprum::Rails::Responders::Html::SingularResource**
-
-Provides some additional response handling for singular resources.
+If the resource is singular:
 
 - For a failed `#create` result, renders the `:new` template.
 - For a successful `#create` result, redirects to the `:show` page.
@@ -879,14 +1113,14 @@ Provides some additional response handling for singular resources.
 Provides default responses for JSON requests.
 
 - For a successful result, serializes the result value and generates a JSON object of the form `{ ok: true, data: serialized_value }`.
-- For a failing result, creates and serializes a generic error and generates a JSON object of the form `{ ok: false, error: serialized_error }` and a status of `500 Internal Server Error`.
+- For a failing result, creates and serializes a generic error and generates a JSON object of the form `{ ok: false, error: serialized_error }` and a status of `500 Internal Server Error`. If the Rails environment is `:development`, it will instead serialize the error from the result.
 
 **Cuprum::Rails::Responders::Json::Resource**
 
 - For a successful `#create` result, serializes the result value with a status of `201 Created`.
 - For a failed result with an `AlreadyExists` error, serializes the error with a status of `422 Unprocessable Entity`.
 - For a failed result with a `FailedValidation` error, serializes the error with a status of `422 Unprocessable Entity`.
-- For a failed result with a `MissingParameters` error, serializes the error with a status of `400 Bad Request`.
+- For a failed result with an `InvalidParameters` error, serializes the error with a status of `400 Bad Request`.
 - For a failed result with a `NotFound` error, serializes the error with a status of `404 Not Found`.
 
 <a id="responses"></a>
@@ -932,23 +1166,26 @@ A response for a JSON request. Takes the serialized `:data` to return as well as
 
 Serializers convert entities and data structures into serialized data. Each serializer is specific to one format and one type of object - for example, the `Cuprum::Rails::Serializers::Json::ErrorSerializer` generates a JSON representation of a `Cuprum::Error`.
 
-Serializers are also recursive: the `#call` method must accept a `:serializers` keyword, which contains the serializer mappings for the current controller or context. This allows serialization to be context-specific - one controller may use one serializer for a particular record class, while another controller may use a limited set of attributes, such as an admin versus a user-facing controller.
+Serialization is context-specific - one controller may use one serializer for a particular record class, while another controller may use a limited set of attributes, such as an admin versus a user-facing controller. To handle this, the `#call` method must accept a `:context` keyword, which is an instance of `Cuprum::Rails::Serializers::Context`. Each context is initialized with a set of serializers that are used to serialize attributes, array items or hash values, associated models, or otherwise nested properties. All of this is handled automatically inside the controller action.
 
 ```ruby
 class StructSerializer < Cuprum::Rails::Serializers::JsonSerializer
-  def call(struct, serializers:)
+  def call(struct, context:)
     struct.each_pair.with_object do |(key, value), hsh|
-      hsh[key] = super(value, serializers: serializers)
+      hsh[key] = super(value, context: context)
     end
   end
 end
 
 serializer = StructSerializer.new
+context    = Cuprum::Rails::Serializers::Context.new(
+  serializers: Cuprum::Rails::Serializers::Json.default_serializers
+)
 struct     =
   Struct
   .new(:series, :author, :titles)
   .new('The Locked Tomb', 'Tamsyn Muir', ['Gideon the Ninth', 'Harrow the Ninth'])
-serializer.call(struct, serializers: Cuprum::Rails::Serializers::Json.default_serializers)
+serializer.call(struct, context: context)
 #=> {
 #     'series' => 'The Locked Tomb',
 #     'author' => 'Tamsyn Muir',
@@ -956,13 +1193,13 @@ serializer.call(struct, serializers: Cuprum::Rails::Serializers::Json.default_se
 #   }
 ```
 
-Above, we define a custom serializer for serializing `Struct` instances. We then use the serializer on our Book-like struct by passing it to the `#call` method, along with the default JSON serializers. The `#call` method takes each pair of keys and values and calls `super()`, which finds the configured serializer for each value. In our case, the default serializer for a `String` returns the string, while the default serializer for an `Array` returns a new array whose items are the serialized array items. Finally, a `Hash` with `String` keys is generated, which is our `Struct` serialized into a JSON-compatible object.
+Above, we define a custom serializer for serializing `Struct` instances. We then use the serializer on our Book-like struct by passing it to the `#call` method, along with a serialization context that contains the default JSON serializers. The `#call` method takes each pair of keys and values and calls `super()`, which finds the configured serializer for each value. In our case, the default serializer for a `String` returns the string, while the default serializer for an `Array` returns a new array whose items are the serialized array items. Finally, a `Hash` with `String` keys is generated, which is our `Struct` serialized into a JSON-compatible object.
 
 `Cuprum::Rails` defines the following serializers:
 
 **Cuprum::Rails::Serializers::Json::Serializer**
 
-The base class for JSON serializers. Takes a configured `serializers:` hash and finds the serializer for the given object, then calls that serializer with the object and the configured serializers.
+The base class for JSON serializers. Takes a configured `context:` and finds the serializer for the given object, then calls that serializer with the object and the given context.
 
 The serializer for an object is determined based on the object's class. Specifically, for each ancestor of the object's class, the configured serializers are checked for a key matching that ancestor. If that class or module is a key in the configured hash, then the corresponding serializer is used to serialize the object. If the configured serializers do not include a serializer for any of the object class's ancestors, raises an `UndefinedSerializerError`.
 
@@ -1002,44 +1239,100 @@ class RecordSerializer < Cuprum::Rails::Serializers::Json::AttributesSerializer
 end
 
 class BookSerializer < RecordSerializer
-  attribute :title
-  attribute :author
-  attribute :series
+  attributes \
+    :title,
+    :author,
+    :series
 end
 
 class DetailedBookSerializer < BookSerializer
-  attribute :category
-  attribute :published_at
+  attributes \
+    :category,
+    published_at: :iso8601
 end
 
-serializers = Cuprum::Rails::Serializers::Json.default_serializers
-book        = Book.new(
-  id:       0,
-  title:    'Nona The Ninth',
-  author:   'Tamsyn Muir',
-  series:   'The Locked Tomb',
-  category: 'Science Fiction and Fantasy',
+
+context = Cuprum::Rails::Serializers::Context.new(
+  serializers: Cuprum::Rails::Serializers::Json.default_serializers
+)
+book    = Book.new(
+  id:           0,
+  title:        'Nona The Ninth',
+  author:       'Tamsyn Muir',
+  series:       'The Locked Tomb',
+  category:     'Science Fiction and Fantasy',
+  published_at: Date.new(2022, 9, 13)
 )
 
-BookSerializer.new.call(book, serializers: serializers)
+BookSerializer.new.call(book, context: context)
 #=> {
 #     'id'     => 0,
 #     'title'  => 'Nona The Ninth',
 #     'author' => 'Tamsyn Muir',
-#     'series' => 'The Locked Tombs'
+#     'series' => 'The Locked Tomb'
 #   }
 
-DetailedBookSerializer.new.call(book, serializers: serializers)
+DetailedBookSerializer.new.call(book, context: context)
 #=> {
 #     'id'           => 0,
 #     'title'        => 'Nona The Ninth',
 #     'author'       => 'Tamsyn Muir',
 #     'series'       => 'The Locked Tombs',
 #     'category'     => 'Science Fiction and Fantasy',
-#     'published_at' => nil
+#     'published_at' => '2022-09-13'
 #   }
 ```
 
 Above, we define an abstract `RecordSerializer` and a `BookSerializer`, which inherits the `:id` attribute and defines the `:title`, `:author`, and `:series` attributes. When the book serializer is called, it serializes the values of each attribute using the configured serializers; any attributes that are not defined on the serializer are ignored.
 
 We also define a `DetailedBookSerializer` which inherits from `BookSerializer`. This allows us to reuse the attributes defined for our basic book serializer.
+
+Attribute serializers also inherit from `PropertiesSerializer` (see below), and can use the `.property` method. This allows the user to serialize compound properties, or to handle cases where the desired serialization key is different from the name of the attribute.
+
+#### Property Serializers
+
+Property serializers define a set of properties to be serialized. This is useful for serializing data structures such as database models.
+
+```ruby
+class EmployeeSerializer < Cuprum::Rails::Serializers::Json::PropertiesSerializer
+  property :first_name, scope: :first_name
+  property(:last_name, &:last_name)
+  property(:full_name) { |user| "#{user.first_name} #{user.last_name}" }
+  property(:hire_date, scope: :hire_date, &:iso8601)
+  property :salary, serializer: BigDecimalSerializer.new
+  property :department, scope: %i[department name]
+end
+
+context  = Cuprum::Rails::Serializers::Context.new(
+  serializers: Cuprum::Rails::Serializers::Json.default_serializers
+)
+employee = Employee.new(
+  first_name: 'Alan',
+  last_name:  'Bradley',
+  hire_date:  Date.new(1977, 5, 25)
+  salary:     BigDecimal.new('100000')
+  department: Department.new(name: 'Engineering')
+)
+
+EmployeeSerializer.new.call(employee, context: context)
+#=> {
+#     first_name: 'Alan',
+#     last_name:  'Bradley',
+#     full_name:  'Alan Bradley',
+#     hire_date:  '1977-05-25',
+#     salary:     '0.1e6',
+#     department: 'Engineering'
+#   }
+```
+
+Here, we're creating a serializer for our `Employee` model, which serializes each employee into a `Hash` with the configured `property` keys.
+
+- The property name determines the key used to serialize the value in the resulting Hash.
+- The `:scope` keyword determines the initial value to be serialized.
+  - If the scope is `nil`, the object as a whole will be passed to the mapping and then the serializer.
+  - If the scope is a String or a Symbol, then the value of the object property with that key will be mapped. Above, the `first_name` property is defined with `scope: :first_name`, so the initial value will be `employee.first_name`.
+  - If the scope is an Array, then the value of the nested property at those keys will be mapped. Above, the `department` property is defined with `scope: %i[department name]`, so the initial value will be `employee.department.name`.
+- The `:serializer` keyword specifies how the mapped value is to be serialized. It should either be an instance of `Cuprum::Rails::Serializers::BaseSerializer` or a `Proc` that accepts two parameters: an `object` argument, and a `:context` keyword that is the current `Cuprum::Rails::Serializers::Context`.
+- The block, if any, is used to map the scoped value before passing it to the serializer. Above, the `full_name` property is generated by combining the `employee.first_name` and `employee.last_name`.
+
+When the `property` does not specify a `scope`, a `serializer`, or provide a block, it will raise an `ArgumentError`. This would otherwise serialize the object itself using the default serializers. If, for some reason, this is the desired behavior, pass an identity block or `&:itself` as the mapping block.