sort_param 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbe25d60eee31370137b39d3edaa1b0e90270ce37e710fda5bd8d4d46bf09763
-  data.tar.gz: 174b0d2fc448a461b6eef190f80d73c20ad21f90e821647714716f35e22b05d0
+  metadata.gz: 78cff5e96b34b0697aa50227db7186cbbbaac54290cdaf88ff6201ae35afda6e
+  data.tar.gz: 025b26afa452522750032d2be80f83dca0c0343ff00416e2a6d2299e47680980
 SHA512:
-  metadata.gz: 283a35dd58cef523745ef97a097d0ba46548438b580947bc37d8754bdf326b99002f3ba145a270c7fa86978f8b0eca20ffc316b709f0c44b1cffc764dc01d888
-  data.tar.gz: 51b36c10d39d676274133664678c241c301050f64de7495764e1773124f5b17ecbbf8f334c1b62f6e8a943aed57e9cde8409926917e9ca7bbc0cf27bf3eb3364
+  metadata.gz: 8c191c86a31f9a9c300ab3064d3b44b9be8f273fc4578de139482f7434bb07b5c69d44ef12077b262a2832757450f7ded50ced460e501cf602328a29e6e2d2ad
+  data.tar.gz: 788302acfbcf086d426fe2adebb1c5ee59aa85ece7e5e78e956e6ea81987b04efef002ed052d7b0615736648b17552a46c7a5d85c44e94a2f0d6f416ebf4b94e

data/CHANGELOG.md

@@ -1,3 +1,8 @@
 ## [0.1.0]
-
 - Initial release
+
+## [0.2.0]
+- Support setting a different field name in the formatted output
+
+## [1.0.0]
+- Rename :formatted_name option to :rename

data/README.md

@@ -1,11 +1,31 @@
 # SortParam
 
-Sort records using a query parameter based on JSON API's sorting format.
+[![Gem Version](https://badge.fury.io/rb/sort_param.svg)](https://badge.fury.io/rb/sort_param) [![CI](https://github.com/jsonb-uy/sort_param/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/jsonb-uy/sort_param/actions/workflows/ruby.yml) [![codecov](https://codecov.io/gh/jsonb-uy/sort_param/branch/main/graph/badge.svg?token=09RE3PZW4G)](https://codecov.io/gh/jsonb-uy/sort_param) [![Maintainability](https://api.codeclimate.com/v1/badges/d1655f67377c21e9618a/maintainability)](https://codeclimate.com/github/jsonb-uy/sort_param/maintainability)
+
+Sort records using a query parameter based on JSON API's sort parameter format.
+
+In a nutshell, this gem converts comma-separated sort fields from this:
+<pre>
+?sort=<b>+users.first_name,-users.last_name:nulls_last,users.email</b>
+</pre>
+
+
+to this:
+```SQL
+users.first_name asc, users.last_name desc nulls last, users.email asc
+```
+
+or to this:
+```ruby
+{"users.first_name"=>{:direction=>:asc}, "users.last_name"=>{:direction=>:desc, :nulls=>:last}, "users.email"=>{:direction=>:asc}}
+```
 
 ## Features
 
+* Sort field whitelisting.
 * Supports `ORDER BY` expression generation for MySQL and PG.
-* Parse the sort string/expression into hash for any further processing.
+* Parsing of comma-separated sort fields into hash for any further processing.
+* Specifying `NULL` sort order.
 
 ## Installation
 
@@ -80,6 +100,21 @@ sort_param.load!("+first_name,-last_name")
 => {"first_name"=>{:nulls=>:first, :direction=>:asc}, "last_name"=>{:direction=>:desc}}
 ```
 
+Any other additional column option set in `SortParam::Definition` or `SortParam.define` will be included in the column's hash value.
+For example:
+
+```ruby
+sort_param = SortParam.define do
+               field :first_name, foo: :bar, nulls: :first
+             end
+
+sort_param.load!("+first_name")
+=> {"first_name"=>{:foo=>:bar, :nulls=>:first, :direction=>:asc}}
+
+sort_param.load!("-first_name:nulls_last")
+=> {"first_name"=>{:foo=>:bar, :nulls=>:last, :direction=>:desc}}
+```
+
 #### IV. Example with explicit nulls sort order
 
 ###### Example in PG mode:
@@ -91,16 +126,36 @@ sort_param.load!("+first_name:nulls_last,-last_name:nulls_first", mode: :pg)
 ```
 <br/>
 
+### Render a different field name in the output
+Set the `:rename` field option to output a different field name:
+
+```ruby
+  sort_param = SortParam.define do
+    field :first_name, rename: 'users.name'
+  end
+  
+  sort_param.load!("+first_name", mode: :pg)
+  => "users.name asc"
+  
+  sort_param.load!("+first_name", mode: :mysql)
+  => "users.name asc"
+  
+  sort_param.load!("+first_name")
+  => {"users.name"=>{:direction=>:asc}}
+```
+
+<br/>
+
 ### Rails example
 
 ```ruby
-def index
-  users = User.all.order(order_by)
+def index 
+  render json: User.all.order(sort_fields)
 end
 
 private
 
-def order_by
+def sort_fields
   SortParam.define do
     field :first_name
     field :last_name, nulls: :first
@@ -114,6 +169,40 @@ def sort_param
 end
 ```
 
+We can DRY this up a bit by creating a concern:
+
+#### controllers/concerns/has_sort_param.rb
+
+```ruby
+module HasSortParam
+  extend ActiveSupport::Concern
+
+  def sort_param(default: nil, &block)
+    raise ArgumentError.new('Missing block') unless block_given?
+
+    definition = SortParam.define(&block)
+    definition.load!(params[:sort].presence || default, mode: :pg)
+  end
+end
+```
+
+### controller
+
+```ruby
+def index 
+  render json: User.all.order(sort_fields)
+end
+
+private
+
+def sort_fields
+  sort_param default: '+first_name,-last_name' do
+    field :first_name
+    field :last_name, nulls: :first
+  end
+end
+```
+
 ### Error
 
 | Class | Description |

data/lib/sort_param/definition.rb

@@ -26,6 +26,7 @@ module SortParam
     # @param name [String, Symbol] column name
     # @param defaults [Hash] column default options:
     #   * nulls (Symbol) nulls sort order. `:last` or `:first`
+    #   * rename (String) field name in formatted output
     #
     # @return [self] Definition instance
     def field(name, defaults = {})
@@ -52,8 +53,8 @@ module SortParam
     #
     # @param sort_string [String] Sort expression. Comma-separated sort fields.
     # @param mode [Symbol, NilClass] Translation format
-    #   * `:pg` for PostgreSQL ORDER BY SQL
-    #   * `:mysql` for MySQL ORDER BY SQL
+    #   * `:pg` for PostgreSQL ORDER BY SQL.
+    #   * `:mysql` for MySQL ORDER BY SQL.
     #   * `:hash`/nil for the default hash representation.
     #
     # @example Sort by first_name ASC and then by last_name DESC

data/lib/sort_param/field.rb

@@ -1,10 +1,10 @@
 module SortParam
   class Field
+    include Utilities
+
     SORT_SYMBOL_DIRECTION = { "+" => :asc, "-" => :desc }.freeze
 
     class << self
-      include Utilities
-
       def from_string(sort_string)
         return nil if blank?(sort_string)
 

data/lib/sort_param/formatters/formatter.rb

@@ -3,6 +3,8 @@
 module SortParam
   module Formatters
     class Formatter
+      include Utilities
+
       def self.for(mode)
         return Formatters::PG if mode == :pg
         return Formatters::MySQL if mode == :mysql
@@ -34,6 +36,12 @@ module SortParam
       def format_field(field)
         raise NotImplementedError
       end
+
+      def formatted_field_name(field)
+        formatted_name = definition.field_defaults(field.name)[:rename]
+
+        blank?(formatted_name) ? field.name : formatted_name
+      end
     end
   end
 end

data/lib/sort_param/formatters/hash.rb

@@ -6,17 +6,21 @@ module SortParam
       private
 
       def format_field(field)
-        field_data = definition.field_defaults(field.name) || {}
-        field_data.merge!(direction: field.direction)
-        field_data.merge!(nulls: field.nulls) unless field.nulls.nil?
-
-        { field.name => field_data }
+        { formatted_field_name(field) => field_data(field) }
       end
 
       def format_collection(fields)
         fields.map { |field| format(field) }
               .inject(&:merge!)
       end
+
+      def field_data(field)
+        data = definition.field_defaults(field.name) || {}
+        data.merge!(direction: field.direction)
+        data.merge!(nulls: field.nulls) unless field.nulls.nil?
+        data.delete(:rename)
+        data
+      end
     end
   end
 end

data/lib/sort_param/formatters/mysql.rb

@@ -11,8 +11,8 @@ module SortParam
 
       def format_field(field)
         field_defaults = definition.field_defaults(field.name) || {}
-        column_name = field_defaults[:column_name] || field.name
 
+        column_name = formatted_field_name(field)
         nulls = (field.nulls || field_defaults[:nulls]).to_s
         nulls_sort_order = nulls_order(column_name, nulls)
         return "#{column_name} #{field.direction}" if nulls_sort_order.nil?

data/lib/sort_param/formatters/pg.rb

@@ -11,10 +11,9 @@ module SortParam
 
       def format_field(field)
         field_defaults = definition.field_defaults(field.name) || {}
-        column_name = field_defaults[:column_name] || field.name
 
         nulls = (field.nulls || field_defaults[:nulls]).to_s
-        "#{column_name} #{field.direction}#{nulls_order(nulls)}"
+        "#{formatted_field_name(field)} #{field.direction}#{nulls_order(nulls)}"
       end
 
       def nulls_order(nulls)

data/lib/sort_param/utilities.rb

@@ -1,11 +1,21 @@
 module SortParam
   module Utilities
-    def blank?(str)
-      return true if str.nil? || str == ""
-      return false unless str.is_a?(String)
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def blank?(str)
+        return true if str.nil? || str == ""
+        return false unless str.is_a?(String)
 
-      str.strip!
-      str.empty?
+        str.strip!
+        str.empty?
+      end
+    end
+
+    def blank?(str)
+      self.class.blank?(str)
     end
   end
 end

data/lib/sort_param/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SortParam
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sort_param
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-05 00:00:00.000000000 Z
+date: 2023-06-14 00:00:00.000000000 Z
 dependencies: []
 description: Sort records using a sort query parameter à la JSON-API style
 email: