web_pipe 0.15.1 → 0.16.0

data/docs/extensions/rails.md

@@ -1,8 +1,8 @@
 # Rails
 
-The first two things to keep in mind in order to integrate with Rails is
+The first two things to keep in mind to integrate with Rails are
 that `WebPipe` instances are Rack applications and that rails router can
-perfectly [dispatch to a rack application](https://guides.rubyonrails.org/routing.html#routing-to-rack-applications). For example:
+perfectly [dispatch to a rack application](https://guides.rubyonrails.org/routing.html#routing-to-rack-applications).
 
 ```ruby
 # config/routes.rb
@@ -22,30 +22,29 @@ class MyRoute
 end
 ```
 
-In order to do something like the previous example you don't need to enable
-this extension. Notice that rails took care of dispatching the request to our
-`WebPipe` rack application, which was then responsible for generating the
-response. In this case, it used a simple call to `#set_response_body`.
+To do something like the previous example, you don't need to enable this
+extension. Notice that rails dispatched the request to our `WebPipe` rack
+application, which was then responsible for generating the response. In this
+case, it used a simple call to `#set_response_body`.
 
 It's quite possible that you don't need more than that in terms of rails
-integration. Of course, surely you want something more elaborate to generate
+integration. Of course, you want something more elaborate to generate
 responses. For that, you can use the view or template system you like. One
-option that will play specially well here is
+option that will play especially well here is
 [`hanami-view`](https://github.com/hanami/view). Furthermore, we have a
 tailored `hanami_view`
 [extension](https://waiting-for-dev.github.io/web_pipe/docs/extensions/hanami_view.html).
 
-You need to use `:rails` extension if:
+You need to use the `:rails` extension if:
 
-- You want to use `action_view` as rendering system.
-- You want to use rails url helpers from your `WebPipe` application.
+- You want to use `action_view` as a rendering system.
+- You want to use rails URL helpers from your `WebPipe` application.
 - You want to use controller helpers from your `WebPipe` application.
 
-Rails responsibilities for controlling the request/response cycle and the
-rendering process are a little bit tangled. For this reason, even if you
-want to use `WebPipe` applications instead of Rails controller actions you
-still have to use the typical top `ApplicationController` in order to define
-some behaviour for the view layer:
+Rails' responsibilities for controlling the request/response cycle are coupled
+to the rendering process. For this reason, even if you want to use `WebPipe`
+applications instead of Rails controller actions you still have to use the
+typical top `ApplicationController` to define some behavior for the view layer:
 
 - Which layout is applied to the template.
 - Which helpers will become available to the templates.
@@ -55,11 +54,11 @@ no layout is applied and only built-in helpers (for example,
 `number_as_currency`) are available. You can change it via the
 `:rails_controller` configuration option.
 
-The main method that this extension adds to `WebPipe::Conn` is `#render`,
-which just delegates to the [Rails
-implementation](https://api.rubyonrails.org/v6.0.1/classes/ActionController/Renderer.html)
-as you'd do in a typical rails controller. Remember that you can provide
-template instance variables through the keyword `:assigns`.
+The main method that this extension adds to `WebPipe::Conn` is `#render`, which
+delegates to the [Rails implementation]
+(https://api.rubyonrails.org/v6.0.1/classes/ActionController/Renderer.html) as
+you'd do in a typical rails controller. Remember that you can provide template
+instance variables through the keyword `:assigns`.
 
 ```ruby
 # config/routes.rb
@@ -92,10 +91,10 @@ end
 ```
 
 Notice that we used the keyword `template:` instead of taking advantage of
-automatic template lookup. We did that way so that we don't have to create also
-an `ArticlesController`, but it's up to you. In the case of having an
-`ArticlesController` we could just do `conn.render(:index, assigns: {
-articles: Article.all })`.
+automatic template lookup. We did that way so that we don't have to create an
+`ArticlesController`, but it's up to you. In the case of having an
+`ArticlesController`, we could do `conn.render(:index, assigns: { articles:
+Article.all })`.
 
 Besides, this extension provides with two other methods:
 
@@ -104,12 +103,7 @@ Besides, this extension provides with two other methods:
 - `helpers` returns the associated [controller
   helpers](https://api.rubyonrails.org/classes/ActionController/Helpers.html).
 
-In all the examples we have supposed that we are putting `WebPipe` applications
-within `app/controllers/` directory. However, remember you can put them
-wherever you like as long as you respect rails [`autoload_paths`](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#autoload-paths).
-
-Here you have a link to a very simple and contrived example of a rails
-application integrating `web_pipe`:
-
-https://github.com/waiting-for-dev/rails-web_pipe
-
+We have placed `WebPipe` applications within `app/controllers/` directory in
+all the examples. However, remember you can put them wherever you like as long
+as you respect rails
+[`autoload_paths`](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#autoload-paths).

data/docs/extensions/redirect.md

@@ -1,14 +1,15 @@
 # Redirect
 
-This extension helps with creating a redirect response.
+This extension helps create a redirect response.
 
 Redirect responses consist of two pieces:
 
-- `Location` response header with the URL to which browsers should redirect.
+- The `Location` response header with the URL to which browsers should
+  redirect.
 - A 3xx status code.
 
-A `#redirect(location, code)` method is added to `WebPipe::Conn` which takes
-care of both steps. `code` argument is optional, defaulting to `302`.
+A `#redirect(location, code)` method is added to `WebPipe::Conn`, which takes
+care of both steps. The `code` argument is optional, defaulting to `302`.
 
 ```ruby
 require 'web_pipe'

data/docs/extensions/router_params.md

@@ -1,12 +1,12 @@
 # Router params
 
-This extension can be used in order to merge placeholder parameters
+This extension can be used to merge placeholder parameters
 that usually routers support (like `get /users/:id`) to the parameters hash
-added through [`:params` extension](params.md) (which is
-automatically loaded).
+added through the [`:params` extension](params.md) (which is
+automatically loaded if using `:router_params`).
 
-What this extension does is adding a transformation function to the registry
-with name `:router_params`. Internally, it merges what is present in rack env's
+This extension adds a transformation function named `:router_params`to the
+registry. Internally, it merges what is present in rack env's
 `router.params` key.
 
 It automatically integrates with

data/docs/extensions/session.md

@@ -1,11 +1,11 @@
 # Session
 
-Wrapper around `Rack::Session` middleware to help working with
-sessions in your plugged operations.
+Wrapper around `Rack::Session` middleware to help work with sessions in your
+plugged operations.
 
-It depends on `Rack::Session` middleware, which is shipped by rack.
+It depends on the `Rack::Session` middleware, which is shipped by rack.
 
-It adds following methods to `WebPipe::Conn`:
+It adds the following methods to `WebPipe::Conn`:
 
 - `#fetch_session(key)`, `#fetch_session(key, default)` or
   `#fetch_session(key) { default }`. Returns what is stored under

data/docs/extensions/url.md

@@ -1,11 +1,11 @@
 # URL
 
-`:url` extension just adds a few methods which cook raw request information
-about the URL into something more digestible.
+The `:url` extension adds a few methods that process the raw URL information
+into something more digestable.
 
 Specifically, it adds:
 
-- `#base_url`: Which is schema + host + port (unless it is the default for the scheme). I.e. `'https://example.org'` or `'http://example.org:8000'`.
-- `#path`: Which is script name (if any) + path information. I.e. `'index.rb/users/1'` or `'users/1'`.
-- `#full_path`: Which is path + query string (if any). I.e. `'users/1?view=table'`.
-- `#url`: Which is base url + full path. I.e. `'http://example.org:8000/users/1?view=table'`.
+- `#base_url`: That's schema + host + port (unless it is the default for the scheme). E.g. `'https://example.org'` or `'http://example.org:8000'`.
+- `#path`: That's script name (if any) + path information. E.g. `'index.rb/users/1'` or `'users/1'`.
+- `#full_path`: That's path + query string (if any). E.g. `'users/1?view=table'`.
+- `#url`: That's base url + full path. E.g. `'http://example.org:8000/users/1?view=table'`.

data/docs/extensions.md

@@ -1,12 +1,11 @@
 # Extensions
 
-`WebPipe::Conn` features are by default raw: the very minimal you
-need to be able to build a web application. However, there are
-several extensions to progressively add just the ingredients you
-want to use.
+`WebPipe::Conn` features are bare-bones by default: the very minimal you need
+to be able to build a web application. However, there are several extensions to
+add just the ingredients you want to use progressively.
 
-In order to load the extensions, you have to call
-`#load_extensions` method in `WebPipe`:
+To load the extensions, you have to call `#load_extensions` method in
+`WebPipe`:
 
 ```ruby
 WebPipe.load_extensions(:params, :cookies)

data/docs/introduction.md

@@ -6,10 +6,10 @@ It means that with it and a rack router (like
 [`hanami-router`](https://github.com/hanami/router),
 [`http_router`](https://github.com/joshbuddy/http_router) or plain
 [rack](https://github.com/rack/rack) routing methods you can build a complete
-web application.  However, the idea behind `web_pipe` is being a decoupled
-component within a web framework.  For this reason, it plays extremely well
-with [dry-rb](https://dry-rb.org/) ecosystem. If it helps, you can think of it
-as a decoupled web controller (as the C in MVC).
+web application.  However, the idea behind `web_pipe` is for it to be a
+decoupled component within a web framework.  For this reason, it plays
+extremely well with [dry-rb](https://dry-rb.org/) ecosystem. If it helps, you
+can think of it as a decoupled web controller (as the C in MVC).
 
 `web_pipe` applications are built as a [pipe of
 operations](design_model.md) on an [immutable
@@ -28,9 +28,9 @@ Following there is a simple example. It is a web application that will check
 the value of a `user` parameter. When it is `Alice` or `Joe`, it will kindly
 say hello. Otherwise, it will unauthorize:
 
-> In order to try this example you can paste it to a file with name `config.ru`
-and launch the rack command `rackup` within the same directory. The application
-will be available in `http://localhost:9292`.
+> To try this example, you can paste it to a file with the name `config.ru` and
+launch the rack command `rackup` within the same directory. The application
+will be available at `http://localhost:9292`.
 
 ```ruby
 require 'web_pipe'

data/docs/plugging_operations/composing_operations.md

@@ -5,9 +5,9 @@ and returning a connection struct. As a result, a composition of operations is
 an operation in itself (as it also takes a connection struct and returns a
 connection struct).
 
-This can be leveraged to plug a whole `web_pipe` application as an operation
-to another application. Doing so, you are plugging an operation which is the
-composition of all operations for given application.
+We can leverage that to plug a whole `web_pipe` application as an operation to
+another application. By doing so, you are plugging an operation which is the
+composition of all operations for a given application.
 
 ```ruby
 class HtmlApp

data/docs/plugging_operations/injecting_operations.md

@@ -1,12 +1,12 @@
 # Injecting operations
 
-Operations can be injected at the moment an application is initialized,
-which allows you to override what the definition declares.
+You can inject operations at the moment an application is initialized. It
+allows you to override what the definition declares.
 
 To this effect, you must use `plugs:` keyword argument. It must be a hash where
-operations are matched by the name you gave them in its definition.
+the operations are matched by the name you gave them in its definition.
 
-This is mainly useful for testing purposes, where you can switch a heavy
+That is mainly useful for testing purposes, where you can switch a heavy
 operation and use another lighter one.
 
 In the following example, the response body of the application will be

data/docs/plugging_operations/inspecting_operations.md

@@ -1,11 +1,10 @@
 # Inspecting operations
 
-Once a `WebPipe` class is initialized all its operations get resolved. It
+Once a `WebPipe` class is initialized, all its operations get resolved. It
 happens because they are whether [resolved](resolving_operations.md) or
 [injected](injecting_operations.md). The final result can be accessed through
 the `#operations` method:
 
-
 ```ruby
 require 'web_pipe'
 require 'web_pipe/conn_support/builder'

data/docs/plugging_operations/resolving_operations.md

@@ -1,6 +1,6 @@
 # Resolving operations
 
-There are several ways you can specify how an operation is resolved.
+There are several ways you can specify how to resolve an operation.
 
 ## Instance method
 
@@ -53,8 +53,8 @@ end
 Operations can be resolved from a dependency injection container.
 
 A container is anything that responds to `#[]` (accepting `Symbol` or `String`
-as argument) in order to resolve a dependency. It can be configured at the
-moment `WebPipe` module is included:
+as argument) to resolve a dependency. It can be configured at the
+moment you include the `WebPipe` module:
 
 ```ruby
 MyContainer = Hash[

data/docs/plugging_operations.md

@@ -1,10 +1,10 @@
 # Plugging operations
 
-You can plug operations to your application with the DSL method `plug`. The
+You can plug operations into your application with the DSL method `plug`. The
 first argument it always takes is a symbol with the name you want
 to give to the operation (which is needed to allow
-[injection](plugging_operations/injecting_operations.md) on
-initialization).
+[injection](plugging_operations/injecting_operations.md) at
+initialization time).
 
 ```ruby
 class MyApp

data/docs/plugs/config.md

@@ -1,6 +1,6 @@
 # Config
 
-`Config` plug helps in the addition of configuration settings (`#config` hash
+The `Config` plug helps in adding configuration settings (`#config` hash
 attribute) to an instance of `WebPipe::Conn`.
 
 ```ruby

data/docs/plugs/content_type.md

@@ -1,6 +1,7 @@
 # ContentType
 
-`ContentType` plug is just a helper to set `Content-Type` response header.
+The `ContentType` plug is just a helper to set the `Content-Type` response
+header.
 
 Example:
 

data/docs/plugs.md

@@ -1,13 +1,12 @@
 # Plugs
 
-Some group of operations can be generalized as following same pattern. For
+Some groups of operations can be generalized as following the same pattern. For
 example, an operation setting `Content-Type` header to `text/html` is very
-similar to another one setting same header to `application/json`. We name plugs
-to this level of abstraction on top of operations: plugs are operation
-builders. In other words, they are higher order functions which return
-functions.
+similar to setting the same header to `application/json`. We name plugs to this
+level of abstraction on top of operations: plugs are operation builders. In
+other words, they are higher-order functions that return functions.
 
-Being just functions, we take as convention that plugs respond to `#call` in
-order to create an operation.
+Being just functions, we take as a convention that plugs respond to `#call` to
+create an operation.
 
 This library ships with some useful plugs.

data/docs/recipes/hanami_2_and_dry_rb_integration.md

@@ -0,0 +1,12 @@
+# Hanami 2 and dry-rb integration
+
+`web_pipe` has been designed to integrate smoothly with
+the [hanami](https://hanamirb.org/) & [dry-rb](https://dry-rb.org/) ecosystems. It shares the same design
+principles, and it ships with some extensions that even make this
+integration painless (like [`:dry-schema`](../extensions/dry_schema.md)
+extension or [`:hanami_view`](../extensions/hanami_view.md)).
+
+If you want to use `web_pipe` within a hanami 2 application, you can take
+inspiration from this sample todo app:
+
+https://github.com/waiting-for-dev/hanami_2_web_pipe_todo_app

data/docs/recipes/hanami_router_integration.md

@@ -22,4 +22,6 @@ end
 run router
 ```
 
-In order to perform [string matching with variables](https://github.com/hanami/router#string-matching-with-variables) you just need to load [`:router_params` extension](../extensions/router_params.md).
+To perform [string matching with
+variables](https://github.com/hanami/router#string-matching-with-variables) you
+just need to load [`:router_params` extension](../extensions/router_params.md).

data/docs/recipes/using_all_restful_methods.md

@@ -1,6 +1,6 @@
 # Using all RESTful methods
 
-As you probably know, a lot of browsers don't support some RESTful
+As you probably know, most browsers don't support some RESTful
 methods like `PATCH` or `PUT`. [Rack's `MethodOverride`
 middleware](https://github.com/rack/rack/blob/master/lib/rack/method_override.rb)
 provides a workaround for this limitation, allowing to override
@@ -9,12 +9,13 @@ request method in rack's env if a magical `_method` parameter or
 
 You have to be aware that if you use this middleware within a
 `web_pipe` application (through [`use` DSL
-method](../using_rack_middlewares.md)) it will have no effect.
-When your `web_pipe` application takes control of the request it
-has already gone through the router, which is the one who should
+method](../using_rack_middlewares.md)), it will have no effect.
+When your `web_pipe` application takes control of the request, it
+has already gone through the router, which is the one that should
 read the request method set by rack.
 
-The solution for this is very simple. Just use `MethodOverride` middleware before your router does its work. For example, in `config.ru`:
+The solution for this is straightforward. Just use `MethodOverride` middleware
+before your router does its work. For example, in `config.ru`:
 
 ```ruby
 # config.ru

data/docs/using_rack_middlewares/composing_middlewares.md

@@ -3,9 +3,8 @@
 In a similar way that you compose plugged operations, you can also compose rack
 middlewares from another application.
 
-For that, you just need to `use` another application. When you do so, all the
-middlewares for that application will be added to the stack in the same order
-they had there.
+For that, you just need to `use` another application. All the middlewares for
+that application will be added to the stack in the same order.
 
 ```ruby
 class HtmlApp

data/docs/using_rack_middlewares/injecting_middlewares.md

@@ -1,19 +1,19 @@
 # Injecting middlewares
 
-Middlewares can be injected at the moment an application is initialized,
+You can inject middlewares at the moment an application is initialized,
 allowing you to override what you have defined in the DSL.
 
-For that purpose, you have to use `middlewares:` keyword argument. It must be a
+For that purpose, you have to use the `middlewares:` keyword argument. It must be a
 hash where middlewares are matched by the name you gave them in its definition.
 
-A middleware must be specified as an `Array`. First item must be a rack
-middleware class. The rest of arguments (if any) should be any option it may
+A middleware must be specified as an `Array`. The first item must be a rack
+middleware class. The rest of the arguments (if any) should be any options it may
 need.
 
-This is mainly useful for testing purposes, where you can switch a heavy
+That is mainly useful for testing purposes, where you can switch a heavy
 middleware and use a mocked one instead.
 
-In the following example, rack session mechanism is being mocked:
+In the following example, we mock the rack session mechanism:
 
 ```ruby
 # config.ru

data/docs/using_rack_middlewares/inspecting_middlewares.md

@@ -1,15 +1,16 @@
 # Inspecting middlewares
 
-Once a `WebPipe` class is initialized all its middlewares get resolved. They
-can be accessed through the `#middlewares` method.
+Once a `WebPipe` class is initialized, all its middlewares get resolved. You
+can access them through the `#middlewares` method.
 
 Each middleware is represented by a
 `WebPipe::RackSupport::MiddlewareSpecification` instance, which contains two
-accessors: `middleware` returns the middleware class, while `options` returns
-an array with the arguments that are provided to the middleware on initialization.
+accessors: `middleware` returns the middleware class. In contrast, `options`
+returns an array with the arguments provided to the middleware on
+initialization.
 
-Kepp in mind that every middleware is resolved as an array. This is because it
-can in fact be composed by an chain of middlewares built through
+Keep in mind that every middleware is resolved as an array. That is because it
+can be composed by a chain of middlewares built through
 [composition](composing_middlewares.md).
 
 

data/docs/using_rack_middlewares.md

@@ -1,16 +1,16 @@
 # Using rack middlewares
 
 A one-way pipe like the one `web_pipe` implements can deal with any required
-feature in a web application. However, usually it is convenient to be able to
-use some well-known rack middleware so you don't have to reinvent the wheel.
-Even if you can add them at the router layer, `web_pipe` allows you to
-encapsulate them in your application definition.
+feature in a web application. However, usually, it is convenient to use some
+well-known rack middleware, so you don't have to reinvent the wheel.  Even if
+you can add them to the router layer, `web_pipe` allows you to encapsulate them
+in your application definition.
 
-In order to add rack middlewares to the stack, you have to use the DSL method
+To add rack middlewares to the stack, you have to use the DSL method
 `use`. The first argument it takes is a `Symbol` with the name you want to
 assign to it (which is needed to allow
 [injection](using_rack_middlewares/injecting_middlewares.md) on
-initialization). Then, it must follow the middleware class and any option it
+initialization). Then, it must follow the middleware class and any options it
 may need:
 
 ```ruby

data/lib/web_pipe/app.rb

@@ -1,54 +1,51 @@
 # frozen_string_literal: true
 
-require 'web_pipe/types'
 require 'web_pipe/conn'
 require 'web_pipe/conn_support/builder'
 require 'web_pipe/conn_support/composition'
 
 module WebPipe
-  # Rack application built around applying a pipe of {Operation} to
-  # a {Conn}.
+  # Rack app built from a chain of functions that take and return a
+  # {WebPipe::Conn}.
   #
-  # A rack application is something callable accepting rack's `env`
-  # as argument and returning a rack response. So, the workflow
-  # followed to build it is:
+  # This is the abstraction encompassing a rack application built only with the
+  # functions on {WebPipe::Conn}. {WebPipe::RackSupport::AppWithMiddlewares}
+  # takes middlewares also into account.
   #
-  # - Take rack's `env` and create a {Conn} from here.
-  # - Starting from it, apply the pipe of operations (anything
-  # callable accepting a {Conn} and returning a {Conn}).
-  # - Convert last {Conn} back to a rack response and
-  # return it.
+  # A rack application is something callable that takes the rack environment as
+  # an argument, and returns a rack response. So, this class needs to:
   #
-  # {Conn} can itself be of two different types (subclasses of it}:
-  # {Conn::Ongoing} and {Conn::Halted}. The pipe is stopped
-  # whenever the stack is emptied or a {Conn::Halted} is
-  # returned in any of the steps.
+  # - Take rack's environment and create a {WebPipe::Conn} struct from there.
+  # - Starting from the initial struct, apply the pipe of functions.
+  # - Convert the last {WebPipe::Conn} back to a rack response.
+  #
+  # {WebPipe::Conn} can itself be of two different types (subclasses of it}:
+  # {Conn::Ongoing} and {Conn::Halted}. The pipe is stopped on two scenarios:
+  #
+  # - The end of the pipe is reached.
+  # - One function returns a {Conn::Halted}.
   class App
-    # Type for a rack environment.
-    RackEnv = Types::Strict::Hash
-
     include Dry::Monads::Result::Mixin
 
     # @!attribute [r] operations
-    #   @return [Array<Operation[]>]
+    #   @return [Array<Proc>]
     attr_reader :operations
 
+    # @param operations [Array<Proc>]
     def initialize(operations)
-      @operations = Types.Array(
-        ConnSupport::Composition::Operation
-      )[operations]
+      @operations = operations
     end
 
-    # @param env [Hash] Rack env
+    # @param env [Hash] Rack environment
     #
     # @return env [Array] Rack response
     # @raise ConnSupport::Composition::InvalidOperationResult when an
-    # operation does not return a {Conn}
+    # operation doesn't return a {WebPipe::Conn}
     def call(env)
       extract_rack_response(
         apply_operations(
           conn_from_env(
-            RackEnv[env]
+            env
           )
         )
       )

data/lib/web_pipe/conn.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'dry/struct'
-require 'web_pipe/types'
 require 'web_pipe/conn_support/types'
 require 'web_pipe/conn_support/errors'
 require 'web_pipe/conn_support/headers'

data/lib/web_pipe/conn_support/builder.rb

@@ -6,15 +6,8 @@ require 'web_pipe/conn_support/headers'
 
 module WebPipe
   module ConnSupport
-    # Helper module to build a {Conn} from a rack's env.
-    #
-    # It always return a {Conn::Ongoing} subclass.
-    #
     # @api private
     module Builder
-      # @param env [Types::Env] Rack's env
-      #
-      # @return [Conn::Ongoing]
       # rubocop:disable Metrics/MethodLength
       def self.call(env)
         rr = Rack::Request.new(env)