sort_param 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78cff5e96b34b0697aa50227db7186cbbbaac54290cdaf88ff6201ae35afda6e
-  data.tar.gz: 025b26afa452522750032d2be80f83dca0c0343ff00416e2a6d2299e47680980
+  metadata.gz: 410b605717d78b03414a2efa8fe9bcfc7db220f52b68ec20526068ee214dd695
+  data.tar.gz: 7b472ee03998faf9e05fb5aebb4a39e36d2a06853169598a9089a48cd04bf93a
 SHA512:
-  metadata.gz: 8c191c86a31f9a9c300ab3064d3b44b9be8f273fc4578de139482f7434bb07b5c69d44ef12077b262a2832757450f7ded50ced460e501cf602328a29e6e2d2ad
-  data.tar.gz: 788302acfbcf086d426fe2adebb1c5ee59aa85ece7e5e78e956e6ea81987b04efef002ed052d7b0615736648b17552a46c7a5d85c44e94a2f0d6f416ebf4b94e
+  metadata.gz: 2ad6f2f434973f1b1c25ce86d9949f02443a042ecc1a7279eb208c3eecfb04410adbcb0ea436b0341d729747c17665a8d7b25a9fb6d181f4d3623933b90e7a40
+  data.tar.gz: f838dd76a5d4e8231c6308f33575dae253c5cd4ab6f6e887488b3ab74da6252ee39ed4b3beb77e024c3f503e358a659788ee62ae78eeb6041f4049881a814ce2

data/CHANGELOG.md

@@ -6,3 +6,11 @@
 
 ## [1.0.0]
 - Rename :formatted_name option to :rename
+
+## [1.1.0]
+- Introduce definition#load to silently ignore non-whitelisted sort fields
+
+## [1.2.0]
+- Introduce #fields to whitelist multiple fields with the same field defaults at once
+- Allow field renaming using a Proc instead of hardcoding a string value
+

data/README.md

@@ -124,14 +124,26 @@ sort_param.load!("+first_name:nulls_last,-last_name:nulls_first", mode: :pg)
 
 => "first_name asc nulls last, last_name desc nulls first"
 ```
-<br/>
 
-### Render a different field name in the output
-Set the `:rename` field option to output a different field name:
+### Ignoring non-whitelisted sort fields instead of raising error
+Use `#load` method instead:
+
+```ruby
+  sort_param = SortParam.define do
+    field :first_name
+  end
+
+  sort_param.load("+first_name,+last_name", mode: :pg)
+  => "first_name asc"
+```
+
+### Output a different field name
+Set the `:rename` field option to a string value or a Proc to output a different field name.
 
 ```ruby
   sort_param = SortParam.define do
     field :first_name, rename: 'users.name'
+    field :last_name, rename: ->(col) { "users.#{col}" }
   end
   
   sort_param.load!("+first_name", mode: :pg)
@@ -142,12 +154,28 @@ Set the `:rename` field option to output a different field name:
   
   sort_param.load!("+first_name")
   => {"users.name"=>{:direction=>:asc}}
+
+  sort_param.load!("+last_name")
+  => {"users.last_name"=>{:direction=>:asc}}
 ```
 
-<br/>
+### Whitelisting multiple fields with the same options at once
+Use `#fields` instead of `#field`:
+
+```ruby
+  sort_param = SortParam.define do
+    fields :first_name, :last_name, nulls: :first, rename: ->(col) { "users.#{col}" }
+    field :email
+  end
+```
+
+NOTE: Unlike `#field`, `#fields` can only accept a Proc for the `:rename` option.
+
 
 ### Rails example
 
+### controller
+
 ```ruby
 def index 
   render json: User.all.order(sort_fields)
@@ -186,7 +214,7 @@ module HasSortParam
 end
 ```
 
-### controller
+### controller v2
 
 ```ruby
 def index 
@@ -207,7 +235,7 @@ end
 
 | Class | Description |
 | ----------- | ----------- |
-| `SortParam::UnsupportedSortField` | Raised when a sort field from the parameter isn't included in the whitelisted sort fields. |
+| `SortParam::UnsupportedSortField` | Raised when loading sort string via `#load!` and a sort field from the parameter isn't included in the whitelisted sort fields. |
 
 ## Development
 

data/lib/sort_param/definition.rb

@@ -21,19 +21,40 @@ module SortParam
       self
     end
 
-    # Add a whitelisted column
+    # Whitelist a column
     #
     # @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
+    #   * nulls [Symbol] nulls sort order. `:last` or `:first`
+    #   * rename [String, Proc] rename field in the formatted output.
+    #     This can be a Proc code block that receives the :name as argument and
+    #     returns a transformed field name.
     #
     # @return [self] Definition instance
-    def field(name, defaults = {})
+    def field(name, **defaults)
       name = name.to_s
       return if name.strip.empty?
 
-      fields_hash[name] = defaults
+      fields_hash[name] = preprocess_field_defaults(name, defaults)
+
+      self
+    end
+
+    # Whitelist multiple columns with the same column defaults.
+    #
+    # @param name [Array<String, Symbol>] list of column names
+    # @param defaults [Hash] column default options
+    #
+    # @see #field
+    #
+    # @return [self] Definition instance
+    #
+    def fields(*names, **defaults)
+      if defaults[:rename] && !defaults[:rename].is_a?(Proc)
+        raise ArgumentError.new(":rename should be a Proc")
+      end
+
+      names.each { |name| field(name, **defaults) }
 
       self
     end
@@ -49,6 +70,20 @@ module SortParam
       @fields_hash[name].dup
     end
 
+    # Parse then translate a sort string expression and raise an error if the sort string includes
+    # a non-whitelisted sort field.
+    #
+    # @see #load
+    #
+    # @raise [SortParam::UnsupportedSortField] if :sort_string includes a non-whitelisted sort field.
+    #
+    def load!(sort_string, mode: :hash)
+      fields = Fields.new(sort_string)
+      validate_fields!(fields)
+
+      format_fields(mode, fields)
+    end
+
     # Parse then translate a sort string expression
     #
     # @param sort_string [String] Sort expression. Comma-separated sort fields.
@@ -71,18 +106,35 @@ module SortParam
     # @return [Hash, String, NilClass] Translated to SQL or Hash.
     #   Returns nil if there is no column to sort.
     #
-    def load!(sort_string, mode: :hash)
+    def load(sort_string, mode: :hash)
       fields = Fields.new(sort_string)
-      validate_fields!(fields)
+      fields = fields.reject { |field| non_whitelisted_fields(fields).include?(field.name) }
 
-      formatter = Formatters::Formatter.for(mode)
-      formatter.new(self).format(*fields)
+      format_fields(mode, fields)
     end
 
     private
 
-    def validate_fields!(fields)
-      unknown_field = (fields.names - fields_hash.keys).first
+    def format_fields(mode, fields)
+      Formatters::Formatter.for(mode)
+                           .new(self)
+                           .format(*fields)
+    end
+
+    def preprocess_field_defaults(field, defaults)
+      rename = defaults[:rename]
+      return defaults unless rename.is_a?(Proc)
+
+      defaults[:rename] = defaults[:rename].call(field)
+      defaults
+    end
+
+    def non_whitelisted_fields(loaded_fields)
+      loaded_fields.names - fields_hash.keys
+    end
+
+    def validate_fields!(loaded_fields)
+      unknown_field = non_whitelisted_fields(loaded_fields).first
       return true if unknown_field.nil?
 
       raise SortParam::UnsupportedSortField.new("Unsupported sort field: #{unknown_field}")

data/lib/sort_param/version.rb

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

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: sort_param
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-14 00:00:00.000000000 Z
+date: 2023-06-27 00:00:00.000000000 Z
 dependencies: []
-description: Sort records using a sort query parameter à la JSON-API style
+description: Sort records using a sort query parameter à la JSON:API format
 email:
 - uy.json.dev@gmail.com
 executables: []
@@ -57,5 +57,5 @@ requirements: []
 rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
-summary: Sort records using a sort query parameter à la JSON-API style
+summary: Sort records using a sort query parameter à la JSON:API format
 test_files: []