pluck_map 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3316ae636b712a8656e2efce061b2055b6e75f19b59e0265f1139e312e88d7ec
-  data.tar.gz: bb75083e099c90e38f4b2a92840c197eb93a4c268b8c65917f4172c21e1b9f51
+  metadata.gz: b299dd06b71f709f45a8b9df4e52b20c70785976a3502f5b2402f0f340da8160
+  data.tar.gz: d4d4e2f78031b5fe3fa8c6492885bc2bfa17b73f30825c60fede8f10fec2e13c
 SHA512:
-  metadata.gz: c2801ad881bdc370044fe2c997f7f3d1c137ae757af7aabc4bcc0d3c71e5a412ea136f95a769968aa4972e6d8385ccd6f961c265d8e6946363595bbc3139aae2
-  data.tar.gz: 1ef71fbbd7f3fcdb4494087fc537db3962fb2529373272edb3c96a0a71481c0b18f69f43201cde511640aa5970f0b7a545dfd96e3dabab32f2e89d07a07c2b87
+  metadata.gz: b6da4c576698798f98ac790f81a8dd4ff4f4b07b27212ef3c43f4d54966d04d139ff082f79b86a163abcaf3d3d64a27119c5cd84705baa32c7c39a7b3c369979
+  data.tar.gz: 9862dd28a87a7e82385f14eeb3a055672aac462cf0f2496ec8a189fa476d51c74a24711780ab1c84640c568f92053cb872d75c88834f094a6dd7399ca948e836

data/CHANGELOG.md

@@ -1,7 +1,11 @@
+## v0.6.0 (2019 May 5)
+
+* REFACTOR: Deprecated `Presenter#no_map?` and introduced `Attributes#will_map?` to replace it (@boblail)
+* REFACTOR: Deprecated passing strings to `:select` (Known-safe values can be wrapped in `Arel.sql`) (@boblail)
+
 ## v0.5.0 (2019 May 1)
 
-* REFACTOR: Introduced a new syntax for defining PluckMap Presenters and deprecated
-  calling `PluckMap::Presenter.new` with a block
+* REFACTOR: Introduced a new syntax for defining PluckMap Presenters and deprecated calling `PluckMap::Presenter.new` with a block (@boblail)
 * FEATURE: Add `to_json` presenter method (@boblail)
 * FEATURE: Add `to_csv` presenter method (@boblail)
 

data/README.md

@@ -5,6 +5,8 @@
 
 This library provides a DSL for presenting ActiveRecord::Relations without instantiating ActiveRecord models. It is useful when a Rails controller action does little more than fetch several records from the database and present them in some other data format (like JSON or CSV).
 
+### Why?
+
 Suppose you have an action like this:
 
 ```ruby
@@ -18,9 +20,9 @@ Suppose you have an action like this:
   end
 ```
 
-This instantiates a `Message` for every result, gets the attributes out of it, and then immediately discards it.
+:point_up: This instantiates a `Message` for every result, gets the attributes out of it, and then immediately discards it.
 
-We can skip that unnecessary instantiation by using `pluck`:
+We can skip that unnecessary instantiation by using [`pluck`](https://api.rubyonrails.org/classes/ActiveRecord/Calculations.html#method-i-pluck):
 
 ```ruby
   def index
@@ -86,6 +88,114 @@ This DSL also makes it easy to make fields optional:
   end
 ```
 
+### How is this different from [Jbuilder](https://github.com/rails/jbuilder)?
+
+Jbuilder gives you a similar DSL for defining JSON to be presented but it operators on instances of ActiveRecord objects rather than producing a query to pluck just the values we need from the database.
+
+
+
+## Usage
+
+### Attributes
+
+#### Syntax
+
+Define attributes using either of these syntaxes:
+
+ 1. Without the block variable
+
+    ```ruby
+    presenter = PluckMap[Book].define do
+      title
+    end
+    ```
+
+ 2. With the block variable
+
+    ```ruby
+    presenter = PluckMap[Book].define do |q|
+      q.title
+    end
+    ```
+
+Apart from the repetition of the block variable, the difference between the two styles is the value of `self` within the block. In the first case, `self` will be `PluckMap::AttributesBuilder`. In the second, `self` will be the containing object. The former is less repetitious but the latter can be useful if you want to refer to local methods or instance variables in the context.
+
+#### `:as` and `:select`
+
+:point_down: This will construct a query to select `books.title` from the database and present the value of each title with the key (or column name) `"title"`:
+
+```ruby
+presenter = PluckMap[Book].define do
+  title
+end
+```
+
+There are two ways to change the name of the key that is presented. Both of the following examples will select `authors.first_name` from the database and present it as `"firstName"`:
+
+
+ 1. Using `:as`
+
+    ```ruby
+    presenter = PluckMap[Author].define do
+      first_name as: "firstName"
+    end
+    ```
+
+ 2. Using `:select`
+
+    ```ruby
+    presenter = PluckMap[Author].define do
+      firstName select: :first_name
+    end
+    ```
+
+You can also pass raw SQL expressions to `:select`:
+
+```ruby
+presenter = PluckMap[Person].define do
+  name select: Arel.sql("CONCAT(first_name, ' ', last_name)")
+end
+```
+
+#### `:map`
+
+In the example above, we constructed `name` from `first_name` and `last_name` with a SQL expression. There are many reasons why we might want to process values before presenting them. When possible, it's usually more efficient to do this work in the query itself, but there are times when it's necessary or expedient to do it in Ruby. Use `:map` to process values returned from the query before they are presented.
+
+Here are a couple of examples:
+
+- Constructing `"name"` with `:map`:
+    ```ruby
+    presenter = PluckMap[Person].define do
+      name select: %i[ first_name last_name ], map: ->(first, last) { "#{first} #{last}" }
+    end
+    ```
+
+- Formatting phone numbers with `:map`:
+    ```ruby
+    presenter = PluckMap[Person].define do
+      phoneNumber select: %i[ phone_number ], map: ->(number) { PhoneNumberFormatter.format(number) }
+    end
+    ```
+
+#### `:value`
+
+You can also hard-code a value to be used and it won't be queried from the database. There are two ways of expressing this:
+
+```ruby
+presenter = PluckMap[Person].define do
+  id
+  type "Person"
+end
+```
+
+```ruby
+presenter = PluckMap[Person].define do
+  id
+  type value: "Person"
+end
+```
+
+
 
 ## Installation
 
@@ -104,6 +214,20 @@ Or install it yourself as:
     $ gem install pluck_map
 
 
+### Requirements
+
+The gem's only runtime requirement is:
+
+ - [activerecord](https://rubygems.org/gems/activerecord) 4.2+
+
+It supports these databases out of the box:
+
+ - PostgreSQL
+ - MySQL
+ - SQLite
+
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -111,6 +235,7 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/boblail/pluck_map.

data/lib/pluck_map/attribute.rb

@@ -17,6 +17,15 @@ module PluckMap
         raise ArgumentError, "You must select at least one column" if selects.empty?
         raise ArgumentError, "You must define a block if you are going to select " <<
           "more than one expression from the database" if selects.length > 1 && !block
+
+        @selects = @selects.map do |select|
+          if select.is_a?(String) && !select.is_a?(Arel::Nodes::SqlLiteral)
+            puts "DEPRECATION WARNING: Passing raw SQL as a String to :select is deprecated. Known-safe values can be passed by wrapping them in Arel.sql()."
+            Arel.sql(select)
+          else
+            select
+          end
+        end
       end
     end
 
@@ -24,8 +33,8 @@ module PluckMap
       block.call(*object)
     end
 
-    def no_map?
-      block.nil?
+    def will_map?
+      !block.nil?
     end
 
     # When the PluckMapPresenter performs the query, it will

data/lib/pluck_map/attributes.rb

@@ -42,6 +42,12 @@ module PluckMap
 
 
 
+    def will_map?
+      _attributes.any?(&:will_map?)
+    end
+
+
+
     def ==(other)
       return false if self.class != other.class
       _attributes == other.send(:_attributes)

data/lib/pluck_map/presenter.rb

@@ -25,7 +25,8 @@ module PluckMap
     end
 
     def no_map?
-      attributes.all?(&:no_map?)
+      puts "DEPRECATION WARNING: `PluckMap::Presenter#no_map?` is deprecated. You can replace it with `!attributes.will_map?`"
+      !attributes.will_map?
     end
 
   protected

data/lib/pluck_map/version.rb

@@ -1,3 +1,3 @@
 module PluckMapPresenter
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/pluck_map.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord"
+  spec.add_dependency "activerecord", ">= 4.2"
 
   spec.add_development_dependency "appraisal"
   spec.add_development_dependency "bundler"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pluck_map
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Bob Lail
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-05-02 00:00:00.000000000 Z
+date: 2019-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.2'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement