plucker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52616a6406a6a077c0ac1f273ca2d4c09ed4c00d3990f2cae204ad82ac838e52
+  data.tar.gz: f3949aeef20eec3384743cb2170f07d03a6670734cbc8a1f40893a2dac552770
+SHA512:
+  metadata.gz: 14579f65d8d1ba9b7c37813ca743a2b2b80d8a1ac065cb7bf410f8fd4fac2d0d439aaa7b67ced685d4c30d77769cf2409eb86983244b2df8be8d8700e5ce6a1b
+  data.tar.gz: 804ba6ea55a925e26d3208dd589f59091bd22f0f4ae72058949bce0effa509c1e88a92aea07581803a3aaafec60d22dd32ad2936cfc9ee65010a52afe83c9d5a

data/.rubocop.yml

@@ -0,0 +1,168 @@
+require:
+  - rubocop-factory_bot
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 2.6.0
+  NewCops: enable
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+
+# Layout/IndentationConsistency:
+#   EnforcedStyle: indented_internal_methods
+
+Layout/LineLength:
+  Enabled: false
+  Max: 120
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Lint/NestedMethodDefinition:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Max: 100
+  Exclude:
+    - test/**/*.rb
+
+Metrics/BlockNesting:
+  Max: 3
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 25
+
+Metrics/MethodLength:
+  Max: 100
+  Exclude:
+    - test/**/*.rb
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+  Exclude:
+    - test/**/*.rb
+
+Metrics/PerceivedComplexity:
+  Max: 25
+
+Minitest/AssertInDelta:
+  Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false
+
+Performance/Casecmp:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+# Style/BlockDelimiters:
+#   Enabled: false
+
+Style/ClassVars:
+  Enabled: false
+
+# Style/CombinableLoops:
+#   Enabled: false
+
+# Style/ConditionalAssignment:
+#   Enabled: false
+
+Style/Documentation:
+  Enabled: true
+
+Style/DocumentationMethod:
+  Enabled: true
+  Exclude:
+    - test/**/*
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/FormatStringToken:
+  EnforcedStyle: template
+
+# Style/GuardClause:
+#   Enabled: false
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: either
+
+# Style/IfUnlessModifier:
+#   Enabled: false
+
+Style/Lambda:
+  EnforcedStyle: literal
+
+# Style/MethodDefParentheses:
+#   Enabled: false
+
+# Style/NegatedIf:
+#   Enabled: false
+
+# Style/Next:
+#   Enabled: false
+
+# Style/NumericPredicate:
+#   Enabled: false
+
+# Style/OpenStructUse:
+#   Enabled: false
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: false
+
+Style/RegexpLiteral:
+  AllowInnerSlashes: true
+
+# Style/RescueModifier:
+#   Enabled: false
+
+# Style/SafeNavigation:
+#   Enabled: true
+
+Style/SingleLineMethods:
+  Enabled: false
+
+Style/StringConcatenation:
+  Mode: conservative
+
+# Style/SymbolArray:
+#   Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 pioz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+![build](https://github.com/pioz/plucker/workflows/Ruby/badge.svg)
+[![codecov](https://codecov.io/gh/pioz/plucker/graph/badge.svg?token=95G6SJXB47)](https://codecov.io/gh/pioz/plucker)
+
+# Plucker
+
+Plucker allows projecting records extracted from a query into an array of
+specifically defined [Ruby structs](https://ruby-doc.org/current/Struct.html) for the occasion. It is an
+enchanted [`pluck`](https://www.rubydoc.info/docs/rails/ActiveRecord%2FCalculations:pluck). It
+takes a list of values you want to extract and throws them into a custom
+array of Ruby struct.
+
+This can make your application more efficient because it avoids loading
+ActiveRecord objects and utilizes structs, which are more efficient.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add plucker
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install plucker
+
+## Usage
+
+```ruby
+posts = Post.joins(:author, :comments).group(:id).plucker(:title, 'authors.name', { comments_count: 'COUNT(comments.id)' })
+post = posts.first
+post.title # 'How to make pizza'
+post.authors_name # 'Henry'
+post.comments_count # 2
+post.id # NoMethodError: undefined method `id' for #<struct title="How to make pizza", authors_name="Henry", comments_count=2>
+```
+
+## Purpose
+
+Let's assume we have these classes:
+
+```ruby
+class Author < ApplicationRecord
+  has_many :post
+
+  validates :name, presence: true
+end
+
+class Post < ApplicationRecord
+  belongs_to :author
+
+  validates :title, body, presence: true
+
+  def slug
+    self.title.parameterize
+  end
+end
+```
+
+and we execute this query:
+
+```ruby
+posts = Post.joins(:author).select('id, authors.name AS author_name')
+```
+
+The objects in the posts array are ActiveRecord objects of type `Post`. As I
+read the code, it feels natural for me to be able to do:
+
+```ruby
+post = posts.first
+post.id
+post.title
+post.body
+post.slug
+```
+
+Now, out of these instructions, only `post.id` works, while all the others
+will result in an error because the fields were not selected. This is very
+strange to me, and in a complex codebase, it can lead to confusion and
+frustration.
+
+Furthermore, I can see in the code `post.author_name` and wonder where that
+method or column is defined. Obviously, I won't find the definition of that
+method because it is dynamically generated by ActiveRecord. I don't like this
+very much; it makes it unclear what data is present in the object.
+
+Therefore, I have decided to write Plucker to have well-defined objects with
+clear fields right from the start. I aim for lightweight and efficient
+objects without creating ActiveRecord fat objects with methods that I can't
+even use.
+
+Keep in mind that you can always continue to perform queries in the standard
+ActiveRecord way. With Plucker, you have a new, more efficient, and clearer
+option.
+
+## Doc
+
+The arguments of Plucker can be specified in in 3 different ways depending on
+the requirements: as a `Symbol`, as a `String`, or as a `Hash`.
+
+When using a symbol, the column with the corresponding name to the symbol is
+selected, and the struct field will have that name:
+
+```ruby
+post = Post.plucker(:title).last
+#<struct title="How to make pizza">
+
+post = Post.joins(:author).plucker(:title, :name).last
+#<struct title="How to make pizza", name="Henry">
+```
+
+When using the symbol `:all` or `:*`, it is interpreted as `SELECT *`
+statement, selecting all columns from the specified table:
+
+```ruby
+post = Post.plucker(:all).last
+#<struct id=1, title="How to make pizza", author_id=1, created_at=Sat, 21 Oct 2023 14:24:08 UTC +00:00, updated_at=Sat, 21 Oct 2023 14:24:08 UTC +00:00>
+```
+
+When using a string value, the name of the struct field will be generated
+using the [`parameterize`](https://www.rubydoc.info/gems/activesupport/String#parameterize-instance_method)
+function with an underscore as the separator:
+
+```ruby
+post = Post.joins(:comments).plucker('posts.title', 'COUNT(comments.id)').last
+#<struct posts_title="How to make pizza", count_comments_id=2>
+```
+
+When using the string `table_name.*`, it is interpreted as `SELECT
+table_name.*` statement, selecting all columns from the specified table:
+
+```ruby
+post = Post.joins(:author).plucker(:*, 'authors.*').last
+#<struct id=1, title="How to make pizza", author_id=1, created_at=Sat, 21 Oct 2023 14:24:08 UTC +00:00, updated_at=Sat, 21 Oct 2023 14:24:08 UTC +00:00, authors_id: 1, authors_name: 'Henry', authors_created_at=Sat, 21 Oct 2023 14:24:08 UTC +00:00, authors_updated_at=Sat, 21 Oct 2023 14:24:08 UTC +00:00>
+```
+
+When using a Hash, it operates similarly to the String case, except that the
+name of the struct field will be the same as the key of the Hash:
+
+```ruby
+post = Post.joins(:comments).plucker(:title, comments_count: 'COUNT(comments.id)').last
+#<struct title="How to make pizza", comments_count=2>
+```
+
+Plucker also takes an optional block, which is passed to the struct
+definition:
+
+```ruby
+posts = Post.plucker(:title) do
+  def slug
+    self.title.parameterize
+  end
+
+  def as_json
+    super.tap do |json|
+      json['slug'] = self.slug
+    end
+  end
+end.last
+#<struct title="How to make pizza">
+
+post.title
+# 'How to make pizza'
+post.slug
+# 'how-to-make-pizza'
+post.as_json
+# {"title"=>"How to make pizza", "slug"=>"how-to-make-pizza"}
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pioz/plucker.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+task default: :test

data/lib/plucker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Plucker
+  VERSION = '0.1.0'
+end

data/lib/plucker.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'plucker/version'
+require 'active_record'
+
+# :nodoc:
+module Plucker
+  # :nodoc:
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # :nodoc:
+  module ClassMethods
+    # Plucker allows projecting records extracted from a query into an array
+    # of specifically defined Ruby structs for the occasion. It is an
+    # enchanted `pluck`. It takes a list of values you want to extract and
+    # throws them into a custom array of Ruby struct.
+    def plucker(*args, &block)
+      scope = current_scope || self.all
+      scope_table_name = scope.table.name
+      columns = []
+      alias_names = []
+      args.each do |value|
+        case value
+        when Symbol
+          if value.in?(%i[all *])
+            scope_table_name.classify.constantize.columns.map do |column|
+              columns << column.name
+              alias_names << column.name.to_sym
+            end
+          else
+            columns << value.to_s
+            alias_names << value
+          end
+        when String
+          table_name, column_name = value.split('.')
+          if column_name == '*'
+            table_name.classify.constantize.columns.map do |column|
+              columns << column.name
+              alias_names << "#{table_name}_#{column.name}".parameterize(separator: '_').to_sym
+            end
+          else
+            columns << Arel.sql(value)
+            alias_names << value.parameterize(separator: '_').to_sym
+          end
+        when Hash
+          value.map do |k, v|
+            columns << Arel.sql(v.to_s)
+            alias_names << k.to_sym
+          end
+        else
+          raise "Invalid plucker argument: '#{value.inspect}'"
+        end
+      end
+
+      struct = Struct.new(*alias_names) do
+        class_eval(&block) if block
+      end
+      scope.pluck(*columns).map do |record|
+        struct.new(*record)
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.include(Plucker)

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: plucker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- pioz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Plucker allows projecting a query into a specifically defined struct
+  for the query.
+email:
+- epilotto@gmx.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/plucker.rb
+- lib/plucker/version.rb
+homepage: https://github.com/pioz/plucker
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pioz/plucker
+  source_code_uri: https://github.com/pioz/plucker
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key:
+specification_version: 4
+summary: Pluck database records in structs.
+test_files: []