rack-component 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98202bd82c61277b38d1300b503c561372f617ef49ff5f61a7ec6582830d1d25
-  data.tar.gz: ddb88dacbe4bd2c60a3ba337b08ded9d6b9151e01300c2226ef428bd5ab83aa1
+  metadata.gz: 7fb150ff5c8b988370259759086c1775d851c5d7b302c223bbd1a1ecf03eaf62
+  data.tar.gz: 2d298170408b3ff3893353ba62becbfa88212168cd7f3e212aad4011d2c39e2c
 SHA512:
-  metadata.gz: 2185f7fad25bfaed06bcfc199d4986b71739c97ec3ce54d7336299c5eff49b6d5f8b050a6096ca7a761505c4c4d2a25bb5aeb04d9e320cc7df36fc8d974aad32
-  data.tar.gz: 892055b99db3a063ab79128fe4ef5e89de7d93055d8f006d5ad5197fde8c6aad48fff87db65078b93bc4a113e6aa9357683fda92dcae9a2776607859fc9998ee
+  metadata.gz: debdc05c3a309c2ed25334124f3bcfc726c4d92e15fe517d7946f48944ecd78239fb32bb4305f64ee7632bbc7235d6b065f08aefb88bd2b050a01bd9998cc03f
+  data.tar.gz: f365e4454d2189123524f86cf3f845f06f974beb6d0f4993aaf921523464469b2a1041d10d0db6889fcd493c0a3740a1d9755361d996d886eb79c39f9b85e05b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rack-component (0.4.0)
+    rack-component (0.4.1)
 
 GEM
   remote: https://rubygems.org/
@@ -25,7 +25,6 @@ GEM
     jaro_winkler (1.5.1)
     kwalify (0.7.2)
     method_source (0.9.0)
-    mustermann (1.0.3)
     parallel (1.12.1)
     parser (2.5.1.2)
       ast (~> 2.4.0)
@@ -34,8 +33,6 @@ GEM
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     rack (2.0.6)
-    rack-protection (2.0.4)
-      rack
     rack-test (0.8.3)
       rack (>= 1.0, < 3)
     rainbow (3.0.0)
@@ -67,11 +64,6 @@ GEM
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
     ruby-progressbar (1.10.0)
-    sinatra (2.0.4)
-      mustermann (~> 1.0)
-      rack (~> 2.0)
-      rack-protection (= 2.0.4)
-      tilt (~> 2.0)
     thread_safe (0.3.6)
     tilt (2.0.8)
     unicode-display_width (1.4.0)
@@ -96,7 +88,6 @@ DEPENDENCIES
   reek (~> 5)
   rspec (~> 3.0)
   rubocop (~> 0.59)
-  sinatra (~> 2)
   tilt (~> 2)
   yard (~> 0.9)
 

data/README.md

@@ -3,13 +3,42 @@
 Like a React.js component, a `Rack::Component` implements a `render` method that
 takes input data and returns what to display.
 
-```ruby
-bundle add 'rack-component'
-```
+## Install
 
-## Get Started
+Add `rack-component` to your Gemfile and run `bundle install`:
+
+```
+gem 'rack-component'
+```
 
-The simplest component is just a function:
+## Table of Contents
+
+* [Getting Started](#getting-started)
+  * [Components as plain functions](#components-as-plain-functions)
+  * [Components as Rack::Components](#components-as-rackcomponents)
+  * [Components that re-render instantly](#components-that-re-render-instantly)
+* [Recipes](#recipes)
+  * [Render one component inside another](#render-one-component-inside-another)
+  * [Memoize an expensive component for one minute](#memoize-an-expensive-component-for-one-minute)
+  * [Memoize an expensive component until its content changes](#memoize-an-expensive-component-until-its-content-changes)
+  * [Render an HTML list from an array](#render-an-html-list-from-an-array)
+  * [Render a Rack::Component from a Rails controller](#render-a-rackcomponent-from-a-rails-controller)
+  * [Mount a Rack::Component as a Rack app](#mount-a-rackcomponent-as-a-rack-app)
+  * [Build an entire App out of Rack::Components](#build-an-entire-app-out-of-rackcomponents)
+* [API Reference](#api-reference)
+* [Performance](#performance)
+* [Compatibility](#compatibility)
+* [Anybody using this in production?](#anybody-using-this-in-production)
+* [Ruby reference](#ruby-reference)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Getting Started
+
+### Components as plain functions
+
+The simplest component is just a lambda that takes an `env` parameter:
 
 ```ruby
 Greeter = lambda do |env|
@@ -19,11 +48,13 @@ end
 Greeter.call(name: 'Mina') #=> '<h1>Hi, Mina.</h1>'
 ```
 
-Convert your function to a `Rack::Component` when it needs instance methods or state:
+### Components as Rack::Components
+
+Convert your lambda to a `Rack::Component` when it needs instance methods or
+state:
 
 ```ruby
 require 'rack/component'
-
 class FormalGreeter < Rack::Component
   render do |env|
     "<h1>Hi, #{title} #{env[:name]}.</h1>"
@@ -39,7 +70,9 @@ FormalGreeter.call(name: 'Macron') #=> "<h1>Hi, President Macron.</h1>"
 FormalGreeter.call(name: 'Merkel', title: 'Chancellor') #=> "<h1>Hi, Chancellor Merkel.</h1>"
 ```
 
-Replace `#call` with `#memoized` to make re-renders instant:
+### Components that re-render instantly
+
+Replace `#call` with `#memoized` to make re-renders with the same `env` instant:
 
 ```ruby
 require 'rack/component'
@@ -73,7 +106,8 @@ NetworkGreeter.memoized(name: 'Macron') #=> instant! "Hi, President Macron."
 ## Recipes
 
 ### Render one component inside another
-You can nest Rack::Components as if they were [React Children][JSX Children] by
+
+You can nest Rack::Components as if they were [React Children][jsx children] by
 calling them with a block.
 
 ```ruby
@@ -94,9 +128,16 @@ end
 class PostPage < Rack::Component
   render do |env|
     post = Post.find(id: env[:id])
-    # Nest a PostContent instance inside a Layout instance
+    # Nest a PostContent instance inside a Layout instance, with some arbitrary HTML too
     Layout.call(title: post.title) do
-      PostContent.call(title: post.title, body: post.body)
+      <<~HTML
+        <main>
+          #{PostContent.call(title: post.title, body: post.body)}
+          <footer>
+            I am a footer.
+          </footer>
+        </main>
+      HTML
     end
   end
 end
@@ -130,9 +171,55 @@ class Layout < Rack::Component
 end
 ```
 
+### Memoize an expensive component for one minute
+
+You can use `memoized` as a time-based cache by passing a timestamp to `env`:
+
+```ruby
+require 'rack/component'
+
+# Render one million posts as JSON
+class MillionPosts < Rack::Component
+  render { |env| Post.limit(1_000_000).to_json }
+end
+
+MillionPosts.memoized(Time.now.to_i / 60) #=> first call is slow
+MillionPosts.memoized(Time.now.to_i / 60) #=> next calls in same minute are quick
+```
+
+### Memoize an expensive component until its content changes
+
+This recipe will speed things up when your database calls are fast but your
+render method is slow:
+
+```ruby
+require 'rack/component'
+class PostAnalysis < Rack::Component
+  render do |env|
+    <<~HTML
+      <h1>#{env[:post].title}</h1>
+      <article>#{env[:post].content}</article>
+      <aside>#{expensive_natural_language_analysis}</aside>
+    HTML
+  end
+
+  def expensive_natural_language_analysis
+    FancyNaturalLanguageLibrary.analyze(env[:post].content)
+  end
+end
+
+PostAnalysis.memoized(post: Post.find(1)) #=> slow, because it runs an expensive natural language analysis
+PostAnalysis.memoized(post: Post.find(1)) #=> instant, because the content of :post has not changed
+```
+
+This recipe works with any Ruby object that implements a `#hash` method based
+on the object's content, including instances of `ActiveRecord::Base` and
+`Sequel::Model`.
+
 ### Render an HTML list from an array
-[JSX Lists][JSX Lists] use JavaScript's `map` function. Rack::Component does
-likewise.
+
+[JSX Lists][jsx lists] use JavaScript's `map` function. Rack::Component does
+likewise, only you need to call `join` on the array:
 
 ```ruby
 require 'rack/component'
@@ -150,12 +237,12 @@ class PostsList < Rack::Component
     env[:posts].map { |post|
       <<~HTML
         <li class="item">
-          <a href="#{post[:url]}>
+          <a href="#{post[:url]}">
             #{post[:name]}
           </a>
         </li>
       HTML
-    }.join #unlike, with JSX, you need to call `join` on your array
+    }.join #unlike JSX, you need to call `join` on your array
   end
 end
 
@@ -163,32 +250,66 @@ posts = [{ name: 'First Post', id: 1 }, { name: 'Second', id: 2 }]
 PostsList.call(posts: posts) #=> <h1>This is a list of posts</h1> <ul>...etc
 ```
 
-### Mount a Rack::Component tree inside a Rails app
-For when just a few parts of your app are built with components:
+### Render a Rack::Component from a Rails controller
 
 ```ruby
-# config/routes.rb
-mount MyComponent, at: '/a_path_of_your_choosing'
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  def index
+    render json: PostsList.call(params)
+  end
+end
+
+# app/components/posts_list.rb
+class PostsList < Rack::Component
+  render { |env| posts.to_json }
+
+  def posts
+    Post.magically_filter_via_params(env)
+  end
+end
+```
+
+### Mount a Rack::Component as a Rack app
 
-# config/initializers/my_component.rb
+Because Rack::Components follow the same API as a Rack app, you can mount them
+anywhere you can mount a Rack app. It's up to you to return a valid rack
+tuple, though.
+
+```ruby
+# config.ru
 require 'rack/component'
-class MyComponent < Rack::Component
+
+class Posts < Rack::Component
   render do |env|
-    <<~HTML
-      <h1>Hello from inside a Rails app!</h1>
-    HTML
+    [status, headers, [body]]
+  end
+
+  def status
+    200
+  end
+
+  def headers
+    { 'Content-Type' => 'application/json' }
+  end
+
+  def body
+    Post.all.to_json
   end
 end
+
+run Posts
 ```
 
-### Build an entire Rack app out of Rack::Components
+### Build an entire App out of Rack::Components
+
 In real life, maybe don't do this. Use [Roda] or [Sinatra] for routing, and use
 Rack::Component instead of Controllers, Views, and templates. But to see an
 entire app built only out of Rack::Components, see
 [the example spec](https://github.com/chrisfrank/rack-component/blob/master/spec/raw_rack_example_spec.rb).
 
-
 ## API Reference
+
 The full API reference is available here:
 
 https://www.rubydoc.info/gems/rack-component
@@ -197,6 +318,7 @@ For info on how to clear or change the size of the memoziation cache, please see
 [the spec][spec].
 
 ## Performance
+
 On my machine, Rendering a Rack::Component is almost 10x faster than rendering a
 comparable Tilt template, and almost 100x faster than ERB from the Ruby standard
 library. Run `ruby spec/benchmarks.rb` to see what to expect in your env.
@@ -217,7 +339,7 @@ Calculating -------------------------------------
 Component [memoized]      1.276M (± 0.9%) i/s -      6.432M in   5.041348s
 ```
 
-Notice that using `Component#memoized` is *slower* than using `Component#call`
+Notice that using `Component#memoized` is _slower_ than using `Component#call`
 in this benchmark. Because these components do almost nothing, it's more work to
 check the memoziation cache than to just render. For components that don't
 access a database, don't do network I/O, and aren't very CPU-intensive, it's
@@ -225,8 +347,9 @@ probably fastest not to memoize. For components that do I/O, using `#memoize`
 can speed things up by several orders of magnitude.
 
 ## Compatibility
+
 Rack::Component has zero dependencies, and will work in any Rack app. It should
-even work *outside* a Rack app, because it's not actually dependent on Rack. I
+even work _outside_ a Rack app, because it's not actually dependent on Rack. I
 packaged it under the Rack namespace because it follows the Rack `call`
 specification, and because that's where I use and test it.
 
@@ -237,14 +360,14 @@ Aye:
 - [future.com](https://www.future.com/)
 - [Seattle & King County Homelessness Response System](https://hrs.kc.future.com/)
 
-## Ruby reference:
+## Ruby reference
 
 Where React uses [JSX] to make components more ergonomic, Rack::Component leans
 heavily on some features built into the Ruby language, specifically:
 
 - [Heredocs]
 - [String Interpolation]
-- [Calling methods with a block][Ruby Blocks]
+- [Calling methods with a block][ruby blocks]
 
 ## Development
 
@@ -268,11 +391,11 @@ https://github.com/chrisfrank/rack-component.
 MIT
 
 [spec]: https://github.com/chrisfrank/rack-component/blob/master/spec/rack/component_spec.rb
-[JSX]: https://reactjs.org/docs/introducing-jsx.html
-[JSX Children]: https://reactjs.org/docs/composition-vs-inheritance.html
-[JSX Lists]: https://reactjs.org/docs/lists-and-keys.html
-[Heredocs]: https://ruby-doc.org/core-2.5.0/doc/syntax/literals_rdoc.html#label-Here+Documents
-[String Interpolation]: http://ruby-for-beginners.rubymonstas.org/bonus/string_interpolation.html
-[Ruby Blocks]: https://mixandgo.com/learn/mastering-ruby-blocks-in-less-than-5-minutes
-[Roda]: http://roda.jeremyevans.net
-[Sinatra]: http://sinatrarb.com
+[jsx]: https://reactjs.org/docs/introducing-jsx.html
+[jsx children]: https://reactjs.org/docs/composition-vs-inheritance.html
+[jsx lists]: https://reactjs.org/docs/lists-and-keys.html
+[heredocs]: https://ruby-doc.org/core-2.5.0/doc/syntax/literals_rdoc.html#label-Here+Documents
+[string interpolation]: http://ruby-for-beginners.rubymonstas.org/bonus/string_interpolation.html
+[ruby blocks]: https://mixandgo.com/learn/mastering-ruby-blocks-in-less-than-5-minutes
+[roda]: http://roda.jeremyevans.net
+[sinatra]: http://sinatrarb.com

data/lib/rack/component/version.rb

@@ -1,5 +1,5 @@
 module Rack
   class Component
-    VERSION = '0.4.0'.freeze
+    VERSION = '0.4.1'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-component
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Chris Frank
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-28 00:00:00.000000000 Z
+date: 2019-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips