sort_param 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbe25d60eee31370137b39d3edaa1b0e90270ce37e710fda5bd8d4d46bf09763
+  data.tar.gz: 174b0d2fc448a461b6eef190f80d73c20ad21f90e821647714716f35e22b05d0
+SHA512:
+  metadata.gz: 283a35dd58cef523745ef97a097d0ba46548438b580947bc37d8754bdf326b99002f3ba145a270c7fa86978f8b0eca20ffc316b709f0c44b1cffc764dc01d888
+  data.tar.gz: 51b36c10d39d676274133664678c241c301050f64de7495764e1773124f5b17ecbbf8f334c1b62f6e8a943aed57e9cde8409926917e9ca7bbc0cf27bf3eb3364

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0]
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Jayson Uy
+
+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,135 @@
+# SortParam
+
+Sort records using a query parameter based on JSON API's sorting format.
+
+## Features
+
+* Supports `ORDER BY` expression generation for MySQL and PG.
+* Parse the sort string/expression into hash for any further processing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sort_param'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install sort_param
+```
+
+## Usage
+
+### Basic
+
+
+#### 1. Whitelist/define the sort fields
+
+```ruby
+sort_param = SortParam.define do
+               field :first_name, nulls: :first
+               field :last_name
+             end
+```
+
+
+OR we can do:
+
+```ruby
+sort_param = SortParam::Definition.new
+                                  .field(:first_name, nulls: :first)
+                                  .field(:last_name)
+```
+
+`field` method accepts the column name as the first argument. Any default column configuration such as `:nulls`(for `NULLS FIRST` or `NULLS LAST` sort order) follows the name.
+
+#### 2. Parse sort fields from a parameter
+
+The `load!` method translates a given sort string/fields parameter to an SQL ORDER BY expression or to a Hash: 
+
+##### I. PostgreSQL example
+
+```ruby
+sort_param.load!("+first_name,-last_name", mode: :pg)
+
+=> "first_name asc nulls first, last_name desc"
+```
+
+##### II. MySQL example
+
+```ruby
+sort_param.load!("+first_name,-last_name", mode: :mysql)
+
+=> "first_name is not null, first_name asc, last_name desc"
+```
+
+##### III. Hash example
+
+```ruby
+sort_param.load!("+first_name,-last_name")
+
+=> {"first_name"=>{:nulls=>:first, :direction=>:asc}, "last_name"=>{:direction=>:desc}}
+```
+
+#### IV. Example with explicit nulls sort order
+
+###### Example in PG mode:
+
+```ruby
+sort_param.load!("+first_name:nulls_last,-last_name:nulls_first", mode: :pg)
+
+=> "first_name asc nulls last, last_name desc nulls first"
+```
+<br/>
+
+### Rails example
+
+```ruby
+def index
+  users = User.all.order(order_by)
+end
+
+private
+
+def order_by
+  SortParam.define do
+    field :first_name
+    field :last_name, nulls: :first
+  end.load!(sort_param, mode: :pg)
+end
+
+# Fetch the sort fields from :sort query parameter.
+# If none is given, default sort by `first_name ASC` and `last_name ASC NULLS FIRST`.
+def sort_param
+  params[:sort].presence || "+first_name,+last_name"
+end
+```
+
+### Error
+
+| Class | Description |
+| ----------- | ----------- |
+| `SortParam::UnsupportedSortField` | Raised when a sort field from the parameter isn't included in the whitelisted sort fields. |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jsonb-uy/sort_param.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/sort_param/definition.rb

@@ -0,0 +1,90 @@
+module SortParam
+  class Definition
+    attr_reader :fields_hash
+
+    # Creates a new SortParam definition that whitelists the columns that are allowed to
+    # sorted (i.e. used in SQL ORDER BY).
+    def initialize
+      @fields_hash = {}
+    end
+
+    # Allows whitelisting columns using a block
+    #
+    # @param block [Proc] Field definition block
+    #
+    # @return [self] Definition instance
+    def define(&block)
+      raise ArgumentError.new("Missing block") unless block_given?
+
+      instance_eval(&block)
+
+      self
+    end
+
+    # Add a whitelisted column
+    #
+    # @param name [String, Symbol] column name
+    # @param defaults [Hash] column default options:
+    #   * nulls (Symbol) nulls sort order. `:last` or `:first`
+    #
+    # @return [self] Definition instance
+    def field(name, defaults = {})
+      name = name.to_s
+      return if name.strip.empty?
+
+      fields_hash[name] = defaults
+
+      self
+    end
+
+    # Get default column options
+    #
+    # @param name [String] column name
+    #
+    # @return [Hash, NilClass] Default options
+    def field_defaults(name)
+      return nil if @fields_hash[name].nil?
+
+      @fields_hash[name].dup
+    end
+
+    # Parse then translate a sort string expression
+    #
+    # @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
+    #   * `:hash`/nil for the default hash representation.
+    #
+    # @example Sort by first_name ASC and then by last_name DESC
+    #   definition.load!("+first_name,-last_name")
+    #   # OR
+    #   definition.load!("first_name,-last_name")
+    #
+    # @example Sort by first_name DESC NULLS LAST
+    #   definition.load!("-first_name:nulls_last")
+    #
+    # @example Sort by first_name ASC NULLS FIRST
+    #   definition.load!("+first_name:nulls_first")
+    #
+    # @return [Hash, String, NilClass] Translated to SQL or Hash.
+    #   Returns nil if there is no column to sort.
+    #
+    def load!(sort_string, mode: :hash)
+      fields = Fields.new(sort_string)
+      validate_fields!(fields)
+
+      formatter = Formatters::Formatter.for(mode)
+      formatter.new(self).format(*fields)
+    end
+
+    private
+
+    def validate_fields!(fields)
+      unknown_field = (fields.names - fields_hash.keys).first
+      return true if unknown_field.nil?
+
+      raise SortParam::UnsupportedSortField.new("Unsupported sort field: #{unknown_field}")
+    end
+  end
+end

data/lib/sort_param/field.rb

@@ -0,0 +1,54 @@
+module SortParam
+  class Field
+    SORT_SYMBOL_DIRECTION = { "+" => :asc, "-" => :desc }.freeze
+
+    class << self
+      include Utilities
+
+      def from_string(sort_string)
+        return nil if blank?(sort_string)
+
+        name = column_name(sort_string)
+        return nil if blank?(name)
+
+        direction = sort_direction(sort_string)
+        nulls = nulls_order(sort_string)
+
+        Field.new(name, direction, nulls)
+      end
+
+      private
+
+      def sort_direction(str)
+        return :asc unless SORT_SYMBOL_DIRECTION[str[0]]
+
+        SORT_SYMBOL_DIRECTION[str[0]]
+      end
+
+      def column_name(str)
+        name = SORT_SYMBOL_DIRECTION[str[0]].nil? ? str : str.slice(1..-1)
+        name.strip!
+
+        return nil if blank?(name)
+        return name if nulls_order(name).nil?
+
+        name.sub(/(:nulls_last|:nulls_first)$/, "")
+      end
+
+      def nulls_order(str)
+        return :first if str.end_with?(":nulls_first")
+        return :last if str.end_with?(":nulls_last")
+
+        nil
+      end
+    end
+
+    attr_reader :name, :direction, :nulls
+
+    def initialize(name, direction, nulls = nil)
+      @name = name
+      @direction = direction
+      @nulls = nulls
+    end
+  end
+end

data/lib/sort_param/fields.rb

@@ -0,0 +1,50 @@
+module SortParam
+  class Fields
+    include Enumerable
+    include Utilities
+
+    def initialize(sort_string = nil)
+      @fields = {}
+
+      return if blank?(sort_string)
+
+      parse_and_build_fields(sort_string)
+    end
+
+    def [](name)
+      fields[name]
+    end
+
+    def names
+      fields.keys
+    end
+
+    def <<(field)
+      fields[field.name] = field
+    end
+
+    def each(&block)
+      fields.values.each(&block)
+    end
+
+    def empty?
+      names.empty?
+    end
+
+    private
+
+    attr_reader :fields
+
+    def parse_and_build_fields(sort_string)
+      sort_string.split(",").each do |sort_token|
+        sort_token.strip!
+        field = Field.from_string(sort_token)
+        next if field.nil?
+
+        self << field
+      end
+
+      self
+    end
+  end
+end

data/lib/sort_param/formatters/formatter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SortParam
+  module Formatters
+    class Formatter
+      def self.for(mode)
+        return Formatters::PG if mode == :pg
+        return Formatters::MySQL if mode == :mysql
+
+        Formatters::Hash
+      end
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def format(*fields)
+        return format_collection(fields) if fields.size > 1
+
+        field = fields[0]
+        return nil if field.nil?
+
+        format_field(field)
+      end
+
+      private
+
+      attr_reader :definition
+
+      def format_collection(fields)
+        raise NotImplementedError
+      end
+
+      def format_field(field)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/sort_param/formatters/hash.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SortParam
+  module Formatters
+    class Hash < Formatter
+      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 }
+      end
+
+      def format_collection(fields)
+        fields.map { |field| format(field) }
+              .inject(&:merge!)
+      end
+    end
+  end
+end

data/lib/sort_param/formatters/mysql.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SortParam
+  module Formatters
+    class MySQL < Formatter
+      private
+
+      def format_collection(fields)
+        fields.map { |field| format(field) }.join(", ")
+      end
+
+      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
+        nulls_sort_order = nulls_order(column_name, nulls)
+        return "#{column_name} #{field.direction}" if nulls_sort_order.nil?
+
+        "#{nulls_sort_order}, #{column_name} #{field.direction}"
+      end
+
+      def nulls_order(column_name, nulls)
+        return "#{column_name} is not null" if nulls == "first"
+        return "#{column_name} is null" if nulls == "last"
+
+        nil
+      end
+    end
+  end
+end

data/lib/sort_param/formatters/pg.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SortParam
+  module Formatters
+    class PG < Formatter
+      private
+
+      def format_collection(fields)
+        fields.map { |field| format(field) }.join(", ")
+      end
+
+      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)}"
+      end
+
+      def nulls_order(nulls)
+        return " nulls first" if nulls == "first"
+        return " nulls last" if nulls == "last"
+
+        nil
+      end
+    end
+  end
+end

data/lib/sort_param/utilities.rb

@@ -0,0 +1,11 @@
+module SortParam
+  module Utilities
+    def blank?(str)
+      return true if str.nil? || str == ""
+      return false unless str.is_a?(String)
+
+      str.strip!
+      str.empty?
+    end
+  end
+end

data/lib/sort_param/version.rb

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

data/lib/sort_param.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "sort_param/utilities"
+require_relative "sort_param/formatters/formatter"
+require_relative "sort_param/formatters/hash"
+require_relative "sort_param/formatters/mysql"
+require_relative "sort_param/formatters/pg"
+require_relative "sort_param/field"
+require_relative "sort_param/fields"
+require_relative "sort_param/definition"
+require_relative "sort_param/version"
+
+module SortParam
+  class UnsupportedSortField < StandardError; end
+
+  # Creates a new SortParam definition that whitelists the columns that are allowed to
+  # sorted (i.e. used in SQL ORDER BY).
+  #
+  # @param block [Proc] Field definition block
+  #
+  # @example
+  #  SortParam.define do
+  #    field :first_name
+  #    field :last_name, nulls: :last
+  #  end
+  #
+  # @return [Definition] Sort param definition
+  #
+  def self.define(&block)
+    Definition.new.define(&block)
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: sort_param
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Uy Jayson B
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-06-05 00:00:00.000000000 Z
+dependencies: []
+description: Sort records using a sort query parameter à la JSON-API style
+email:
+- uy.json.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/sort_param.rb
+- lib/sort_param/definition.rb
+- lib/sort_param/field.rb
+- lib/sort_param/fields.rb
+- lib/sort_param/formatters/formatter.rb
+- lib/sort_param/formatters/hash.rb
+- lib/sort_param/formatters/mysql.rb
+- lib/sort_param/formatters/pg.rb
+- lib/sort_param/utilities.rb
+- lib/sort_param/version.rb
+homepage: https://github.com/jsonb-uy/sort_param
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jsonb-uy/sort_param
+  source_code_uri: https://github.com/jsonb-uy/sort_param
+  changelog_uri: https://github.com/jsonb-uy/sort_param/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/github/jsonb-uy/sort_param/main
+  bug_tracker_uri: https://github.com/jsonb-uy/sort_param/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Sort records using a sort query parameter à la JSON-API style
+test_files: []