rotulus 0.2.0

data/lib/rotulus/order.rb

@@ -0,0 +1,171 @@
+module Rotulus
+  class Order
+    # Creates an Order object that builds the column objects in the "ORDER BY" expression
+    #
+    # @param ar_model [Class] the ActiveRecord model class name of Page#ar_relation
+    # @param raw_hash [Hash<Symbol, Hash>, Hash<Symbol, Symbol>, nil] the order definition of columns
+    #
+    def initialize(ar_model, raw_hash = {})
+      @ar_model = ar_model
+      @raw_hash = raw_hash&.with_indifferent_access || {}
+      @definition = {}
+
+      build_column_definitions
+    end
+
+    # Returns an array of the ordered columns
+    #
+    # @return [Array<Rotulus::Column>] ordered columns
+    def columns
+      @columns ||= definition.values
+    end
+
+    # Returns an array of the ordered columns' names
+    #
+    # @return [Array<String>] ordered column names
+    def column_names
+      @column_names ||= columns.map(&:name)
+    end
+
+    # Returns an array of column names prefixed with table name
+    #
+    # @return [Array<String>] column names prefixed with the table name
+    def prefixed_column_names
+      @prefixed_column_names ||= definition.keys.map(&:to_s)
+    end
+
+    # Returns the SELECT expressions to include the ordered columns in the selected columns
+    # of a query.
+    #
+    # @return [String] the SELECT expressions
+    def select_sql
+      columns.map(&:select_sql).join(', ')
+    end
+
+    # Returns a hash containing the ordered column values of a given ActiveRecord::Base record
+    # instance. These values will be used to generate the query to fetch the preceding/succeeding
+    # records of a given :record.
+    #
+    # @param record [ActiveRecord::Base] a record/row returned from Page#records
+    # @return [Hash] the hash containing the column values with the column name as key
+    def selected_values(record)
+      return {} if record.blank?
+
+      record.slice(*select_aliases)
+            .transform_keys do |a|
+              Column.select_alias_to_name(a)
+            end
+    end
+
+    # Returns the reversed `ORDER BY` expression(s) for the current page when the page was accessed
+    # via a 'previous' cursor(i.e. navigating back/ page#paged_back?)
+    #
+    # @return [String] the ORDER BY clause
+    def reversed_sql
+      Arel.sql(columns.map(&:reversed_order_sql).join(', '))
+    end
+
+    # Returns the ORDER BY sort expression(s) to sort the records
+    #
+    # @return [String] the ORDER BY clause
+    def sql
+      Arel.sql(columns.map(&:order_sql).join(', '))
+    end
+
+    # Generate a 'state' so we can detect whether the order definition has changed.
+    #
+    # @return [String] the hashed state
+    def state
+      Digest::MD5.hexdigest(Oj.dump(to_h, mode: :rails))
+    end
+
+    # Returns a hash containing the hash representation of the ordered columns.
+    #
+    # @return [Hash] the hash representation of the ordered columns.
+    def to_h
+      definition.each_with_object({}) do |(name, column), h|
+        h.merge!(column.to_h)
+      end
+    end
+
+    private
+
+    attr_reader :ar_model, :definition, :raw_hash
+
+    def ar_model_primary_key
+      ar_model.primary_key
+    end
+
+    def ar_table
+      ar_model.table_name
+    end
+
+    def column_model(model_override, name)
+      prefix = name.match(/^.*?(?=\.)/).to_s
+      unprefixed_name = name.split('.').last
+
+      unless model_override.nil?
+        return model_override unless model_override.columns_hash[unprefixed_name].nil?
+
+        raise Rotulus::InvalidColumnError.new(
+          "Model '#{model_override}' doesnt have a '#{name}' column. \
+          Tip: check the :model option value in the column's order configuration.".squish
+        )
+      end
+
+      if (prefix.blank? && !ar_model.columns_hash[name].nil?) ||
+         (prefix == ar_table && !ar_model.columns_hash[unprefixed_name].nil?)
+        return ar_model
+      end
+
+      raise Rotulus::InvalidColumnError.new(
+        "Unable determine which model the column '#{name}' belongs to. \
+        Tip: set/check the :model option value in the column's order configuration.".squish
+      )
+    end
+
+    def primary_key_ordered?
+      !definition["#{ar_table}.#{ar_model_primary_key}"].nil?
+    end
+
+    def build_column_definitions
+      raw_hash.each do |column_name, options|
+        column_name = column_name.to_s
+
+        unless options.is_a?(Hash)
+          options = if options.to_s.downcase == 'desc'
+                      { direction: :desc }
+                    else
+                      { direction: :asc }
+                    end
+        end
+
+        model = column_model(options[:model].presence, column_name)
+        column = Column.new(model,
+                            column_name,
+                            direction: options[:direction],
+                            nulls: options[:nulls],
+                            nullable: options[:nullable],
+                            distinct: options[:distinct])
+        next unless definition[column.prefixed_name].nil?
+
+        definition[column.prefixed_name] = column
+      end
+
+      # Add tie-breaker using the PK
+      unless primary_key_ordered?
+        pk_column = Column.new(ar_model, ar_model_primary_key, direction: :asc)
+        definition[pk_column.prefixed_name] = pk_column
+      end
+
+      columns.first.as_leftmost!
+    end
+
+    # Returns an array of SELECT statement alias of the ordered columns
+    #
+    # @return [Array<String>] column SELECT aliases
+    def select_aliases
+      @select_aliases ||= columns.map(&:select_alias)
+    end
+  end
+end

data/lib/rotulus/page.rb

@@ -0,0 +1,278 @@
+module Rotulus
+  class Page
+    attr_reader :ar_relation, :order, :limit, :cursor
+
+    delegate :columns, to: :order, prefix: true
+
+    # Creates a new Page instance representing a subset of the given ActiveRecord::Relation
+    # records sorted using the given 'order' definition param.
+    #
+    # @param ar_relation [ActiveRecord::Relation] the base relation instance to be paginated
+    # @param order [Hash<Symbol, Hash>, Hash<Symbol, Symbol>, nil] the order definition of columns.
+    #   Same with SQL 'ORDER BY', columns listed first takes precedence in the sorting of records.
+    #   The order param allows 2 formats: expanded and compact. Expanded format exposes some config
+    #   which allows more control in generating the optimal SQL queries to filter page records.
+    #
+    #   Available options for each column in expanded order definition:
+    #   * direction (Symbol) the sort direction, +:asc+ or +:desc+. Default: +:asc+.
+    #   * nullable (Boolean) whether a null value is expected for this column in the query result.
+    #     Note that for queries with table JOINs, a column could have a null value
+    #     even if the column doesn't allow nulls in its table so :nullable might need to be set to
+    #     +true+ for such cases.
+    #     Default: +true+ if :nullable option value is nil and the
+    #     column is defined as nullable in its table otherwise, false.
+    #   * nulls (Symbol) null values sorting, +:first+ for +NULLS FIRST+ and
+    #     +:last+ for +NULLS LAST+. Applicable only if column is :nullable.
+    #   * distinct (Boolean) whether the column value is expected to be unique in the result.
+    #     Note that for queries with table JOINs, multiple rows could have the same column
+    #     value even if the column has a unique index defined in its table so :distinct might
+    #     need to be set to +false+ for such cases.
+    #     Default: true if :distinct option value is nil and the column is the PK of its
+    #     table otherwise, false.
+    #   * model (Class) Model where the column belongs to.
+    #
+    # @param limit [Integer] the number of records per page. Defaults to the +config.page_default_limit+.
+    #
+    # @example Using expanded order definition (Recommended)
+    #  Rotulus::Page.new(User.all, order: { last_name: { direction: :asc },
+    #                              first_name: { direction: :desc, nulls: :last },
+    #                              ssn: { direction: :asc, distinct: true } }, limit: 3)
+    #
+    # @example Using compact order definition
+    #  Rotulus::Page.new(User.all, order: { last_name: :asc, first_name: :desc, ssn: :asc }, limit: 3)
+    #
+    # @raise [InvalidLimit] if the :limit exceeds the configured :page_max_limit or if the
+    #  :limit is not a positive number.
+    def initialize(ar_relation, order: { id: :asc }, limit: nil)
+      unless limit_valid?(limit)
+        raise InvalidLimit.new("Allowed page limit is 1 up to #{config.page_max_limit}")
+      end
+
+      @ar_relation = ar_relation || model.none
+      @order = Order.new(model, order)
+      @limit = (limit.presence || config.page_default_limit).to_i
+    end
+
+    # Return a new page pointed to the given cursor(in encoded token format)
+    #
+    # @param token [String] Base64-encoded representation of cursor.
+    #
+    # @example
+    #   page = Rotulus::Page.new(User.where(last_name: 'Doe'), order: { first_name: :desc }, limit: 2)
+    #   page.at('eyI6ZiI6eyJebyI6IkFjdGl2ZVN1cHBvcnQ6Okhhc2hXaXRoSW5kaWZm...')
+    #
+    # @return [Page] page instance
+    def at(token)
+      page_copy = dup
+      page_copy.at!(token)
+      page_copy
+    end
+
+    # Point the same page instance to the given cursor(in encoded token format)
+    #
+    # @example
+    #   page = Rotulus::Page.new(User.where(last_name: 'Doe'), order: { first_name: :desc }, limit: 2)
+    #   page.at!('eyI6ZiI6eyJebyI6IkFjdGl2ZVN1cHBvcnQ6Okhhc2hXaXRoSW5kaWZm...')
+    #
+    # @param token [String] Base64-encoded representation of cursor
+    # @return [self] page instance
+    def at!(token)
+      @cursor = token.present? ? cursor_clazz.for_page_and_token!(self, token) : nil
+
+      reload
+    end
+
+    # Get the records for this page. Note an extra record is fetched(limit + 1)
+    # to make it easier to check whether a next or previous page exists.
+    #
+    # @return [Array<ActiveRecord::Base>] array of records for this page.
+    def records
+      return loaded_records[1..limit] if paged_back? && extra_row_returned?
+
+      loaded_records[0...limit]
+    end
+
+    # Clear memoized records to lazily force to initiate the query again.
+    #
+    # @return [self] page instance
+    def reload
+      @loaded_records = nil
+
+      self
+    end
+
+    # Check if a next page exists
+    #
+    # @return [Boolean] returns true if a next page exists, otherwise returns false.
+    def next?
+      ((cursor.nil? || paged_forward?) && extra_row_returned?) || paged_back?
+    end
+
+    # Check if a preceding page exists
+    #
+    # @return [Boolean] returns true if a previous page exists, otherwise returns false.
+    def prev?
+      (paged_back? && extra_row_returned?) || !cursor.nil? && paged_forward?
+    end
+
+    # Check if the page is the 'root' page; meaning, there are no preceding pages.
+    #
+    # @return [Boolean] returns true if the page is the root page, otherwise false.
+    def root?
+      cursor.nil? || !prev?
+    end
+
+    # Generate the cursor token to access the next page if one exists
+    #
+    # @return [String] Base64-encoded representation of cursor
+    def next_token
+      return unless next?
+
+      record = cursor_reference_record(:next)
+      return if record.nil?
+
+      cursor_clazz.new(record, :next).to_token
+    end
+
+    # Generate the cursor token to access the previous page if one exists
+    #
+    # @return [Cursor] Base64-encoded representation of cursor
+    def prev_token
+      return unless prev?
+
+      record = cursor_reference_record(:prev)
+      return if record.nil?
+
+      cursor_clazz.new(record, :prev).to_token
+    end
+
+    # Next page instance
+    #
+    # @return [Page] the next page with records after the last record of this page.
+    def next
+      return unless next?
+
+      at next_token
+    end
+
+    # Previous page instance
+    #
+    # @return [Page] the previous page with records preceding the first record of this page.
+    def prev
+      return unless prev?
+
+      at prev_token
+    end
+
+    # Generate a hash containing the previous and next page cursor tokens
+    #
+    # @return [Hash] the hash containing the cursor tokens
+    def links
+      return {} if records.empty?
+
+      {
+        previous: prev_token,
+        next: next_token
+      }.delete_if { |_, token| token.nil? }
+    end
+
+    # Return Hashed value of this page's state so we can check whether the ar_relation's filter,
+    # order definition, and limit are still consistent to the cursor. see Cursor.state_valid?.
+    #
+    # @return [String] the hashed state
+    def state
+      Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}~#{limit}")
+    end
+
+    # Returns a string showing the page's records in table form with the ordered columns
+    # as the columns. This method is primarily used to test/debug the pagination behavior.
+    #
+    # @return [String] table
+    def as_table
+      Rotulus::PageTableizer.new(self).tableize
+    end
+
+    def inspect
+      cursor_info = cursor.nil? ? '' : " cursor='#{cursor}'"
+
+      "#<#{self.class.name} ar_relation=#{ar_relation} order=#{order} limit=#{limit}#{cursor_info}>"
+    end
+
+    private
+
+    # If this is the root page or when paginating forward(#paged_forward), limit+1
+    # includes the first record of the next page. This lets us know whether there is a page
+    # succeeding the current page. When paginating backwards(#paged_back?), the limit+1 includes the
+    # record prior to the current page's first record(last record of the previous page, if it exists)
+    # -letting us know that the current page has a previous/preceding page.
+    def loaded_records
+      return @loaded_records unless @loaded_records.nil?
+
+      @loaded_records = ar_relation.where(cursor&.sql)
+                                   .order(order_by_sql)
+                                   .limit(limit + 1)
+                                   .select(*select_columns)
+      return @loaded_records.to_a unless paged_back?
+
+      # Reverse the returned records in case #paged_back? as the sorting is also reversed.
+      @loaded_records = @loaded_records.reverse
+    end
+
+    # Query in #loaded_records uses limit + 1. Returns true if an extra row was retrieved.
+    def extra_row_returned?
+      loaded_records.size > limit
+    end
+
+    def paged_back?
+      !!cursor&.prev?
+    end
+
+    def paged_forward?
+      !!cursor&.next?
+    end
+
+    def cursor_reference_record(direction)
+      record = direction == :next ? records.last : records.first
+
+      Record.new(self, order.selected_values(record))
+    end
+
+    # SELECT the ordered columns so we can use the values to generate the 'where' condition
+    # to filter next/prev page's records. Alias and normalize those columns so we can access
+    # the values using record#slice.
+    def select_columns
+      base_select_values = ar_relation.select_values.presence || [select_all_sql]
+      base_select_values << order.select_sql
+      base_select_values
+    end
+
+    def select_all_sql
+      Rotulus.db.select_all_sql(model.table_name)
+    end
+
+    def order_by_sql
+      return order.reversed_sql if paged_back?
+
+      order.sql
+    end
+
+    def limit_valid?(limit)
+      return true if limit.blank?
+
+      limit = limit.to_i
+      limit >= 1 && limit <= config.page_max_limit
+    end
+
+    def model
+      ar_relation.model
+    end
+
+    def config
+      @config ||= Rotulus.configuration
+    end
+
+    def cursor_clazz
+      @cursor_clazz ||= config.cursor_class
+    end
+  end
+end

data/lib/rotulus/page_tableizer.rb

@@ -0,0 +1,143 @@
+module Rotulus
+  class PageTableizer
+    def initialize(page)
+      @page = page
+    end
+
+    # Returns a string showing the page's records in table form with the ordered columns
+    # as the columns. Some data types are formatted so output is consistent regardless of the
+    # DB engine in use:
+    #  1. Datetime - iso8601(3) formatted
+    #  2. Float - converted to BigDecimal before converting to string
+    #  3. Float/BigDecimal - '.0' fractional portion is dropped
+    #  4. Nil - <NULL>
+    #
+    # @return [String] table
+    #
+    # example:
+    #   +-----------------------------------------------------------------------------------------+
+    #   |   users.first_name   |   users.last_name   |        users.email         |   users.id    |
+    #   +-----------------------------------------------------------------------------------------+
+    #   |        George        |       <NULL>        |     george@domain.com      |      1        |
+    #   |         Jane         |        Smith        |   jane.c.smith@email.com   |      2        |
+    #   |         Jane         |         Doe         |     jane.doe@email.com     |      3        |
+    #   +-----------------------------------------------------------------------------------------+
+    #
+    def tableize
+      return '' if records.blank?
+
+      s = ''
+      s << divider
+      s << header
+      s << divider
+      s << records.map { |record| record_to_string(record) }.join("\n")
+      s << "\n"
+      s << divider
+      s
+    end
+
+    private
+
+    attr_reader :page
+
+    def order
+      @order ||= page.order
+    end
+
+    def records
+      @records ||= page.records
+    end
+
+    def columns
+      @columns ||= order.prefixed_column_names
+    end
+
+    def col_padding
+      1
+    end
+
+    def col_widths
+      return @col_widths if instance_variable_defined?(:@col_widths)
+
+      @col_widths = columns.each_with_object({}) { |name, h| h[name] = name.size + (col_padding * 2) }
+      records.each do |record|
+        values = order.selected_values(record)
+
+        values.each do |col_name, value|
+          width = normalize_value(value).size + (col_padding * 2)
+
+          @col_widths[col_name] = width if @col_widths[col_name] <= width
+        end
+      end
+
+      @col_widths
+    end
+
+    def header
+      @header ||= columns.reduce('') do |names, name|
+        "#{names}|#{name.center(col_widths[name])}"
+      end + " |\n"
+    end
+
+    def divider
+      @divider ||= '+' + ('-' * (header.size - 3)) + "+\n"
+    end
+
+    def record_to_string(record)
+      values = order.selected_values(record)
+      s = values.each_with_object('') do |(k, v), s|
+        v = normalize_value(v)
+        s << "|#{v.center(col_widths[k])}"
+      end
+
+      s << ' |'
+    end
+
+    def normalize_value(value)
+      return '<NULL>' if value.nil?
+      return "'#{value}'" if value.blank? && value.is_a?(String)
+
+      value = if Rotulus.db.name == 'sqlite'
+                format_sqlite_value(value)
+              else
+                format_value(value)
+              end
+
+      value = value.to_s if value.is_a?(BigDecimal)
+      value = BigDecimal(value.to_s).to_s if value.is_a?(Float)
+      value = value.split('.').first if value.is_a?(String) && value =~ /^\-?\d+\.0$/ # drop decimal if it's 0
+
+      value.to_s
+    end
+
+    def format_sqlite_value(value)
+      return value unless value.is_a?(String)
+
+      date_pattern1 = /^\d{4}\-\d{2}\-\d{2} \d{2}:\d{2}:\d{2}\.\d{6}$/
+      date_pattern2 = /^\d{4}\-\d{2}\-\d{2} \d{2}:\d{2}:\d{2}$/
+
+      if value =~ date_pattern1
+        return DateTime.strptime(value, '%Y-%m-%d %H:%M:%S.%L')
+                       .utc
+                       .iso8601(3)
+                       .gsub('+00:00', 'Z')
+      elsif value =~ date_pattern2
+        return DateTime.strptime(value, '%Y-%m-%d %H:%M:%S')
+                       .utc
+                       .iso8601(3)
+                       .gsub('+00:00', 'Z')
+      end
+
+      value
+    end
+
+    def format_value(value)
+      value = value.utc if value.respond_to?(:utc)
+      if value.respond_to?(:iso8601)
+        value = value.method(:iso8601).arity.zero? ? value.iso8601 : value.iso8601(3)
+      end
+
+      value
+    end
+  end
+end

data/lib/rotulus/record.rb

@@ -0,0 +1,66 @@
+module Rotulus
+  class Record
+    attr_reader :page, :values
+
+    # Creates a new Record instance representing the first or last record of a :page
+    # wherein the :values include the ordered column values of the AR record. This
+    # instance serves as the reference point in generating the SQL query to fetch the the page's
+    # previous or next page's records. That is, the first record's values of a page are used
+    # in the WHERE condition to fetch the previous page's records and the last record's values
+    # are used to fetch next page's records.
+    #
+    # @param page [Rotulus::Page] the Page instance
+    # @param values [Hash] the ordered column values of an AR record
+    def initialize(page, values = {})
+      @page = page
+      @values = normalize_values(values || {})
+    end
+
+    # Get the records preceding or succeeding this record in respect to the sort direction of
+    # the ordered columns.
+    #
+    # @param direction [Symbol] `:next` to fetch succeeding records otherwise, `:prev`.
+    #
+    # @return [String] SQL 'where' condition
+    def sql_seek_condition(direction)
+      page.order_columns.reverse.reduce(nil) do |sql, column|
+        column_seek_sql = ColumnConditionBuilder.new(
+          column,
+          values[column.prefixed_name],
+          direction,
+          sql
+        ).build
+
+        parenthesize = !sql.nil? && !column.leftmost?
+        parenthesize ? "(#{column_seek_sql})" : column_seek_sql
+      end.squish
+    end
+
+    # Generate a 'state' so we can detect whether the record values changed/
+    # for integrity check. e.g. Record values prior to encoding in the cursor
+    # vs. the decoded values from an encoded cursor token.
+    #
+    # @return [String] the hashed state
+    def state
+      Digest::MD5.hexdigest(values.map { |k, v| "#{k}:#{v}" }.join('~'))
+    end
+
+    private
+
+    # Normalize values so that serialization-deserialization behaviors(e.g. values from/to encoded
+    # cursor data, SQL query generation) are predictable:
+    # 1. Date, Time, Datetime: iso8601 formatted
+    # 2. Float: converted to BigDecimal
+    def normalize_values(values)
+      values.transform_values! do |v|
+        v = v.utc if v.respond_to?(:utc)
+        if v.respond_to?(:iso8601)
+          v = v.method(:iso8601).arity.zero? ? v.iso8601 : v.iso8601(6)
+        end
+
+        v = BigDecimal(v.to_s) if v.is_a?(Float)
+        v
+      end
+    end
+  end
+end

data/lib/rotulus/version.rb

@@ -0,0 +1,3 @@
+module Rotulus
+  VERSION = '0.2.0'
+end

data/lib/rotulus.rb

@@ -0,0 +1,42 @@
+require 'active_record'
+require 'active_support'
+require 'active_support/core_ext/string/inquiry'
+require 'oj'
+require 'rotulus/version'
+require 'rotulus/configuration'
+require 'rotulus/db/database'
+require 'rotulus/record'
+require 'rotulus/column'
+require 'rotulus/column_condition_builder'
+require 'rotulus/order'
+require 'rotulus/cursor'
+require 'rotulus/page_tableizer'
+require 'rotulus/page'
+
+module Rotulus
+  class BaseError < StandardError; end
+  class CursorError < BaseError; end
+  class InvalidCursor < CursorError; end
+  class ExpiredCursor < CursorError; end
+  class InvalidCursorDirection < CursorError; end
+  class InvalidLimit < BaseError; end
+  class ConfigurationError < BaseError; end
+  class InvalidColumnError < BaseError; end
+
+  def self.db
+    @db ||= case ActiveRecord::Base.connection.adapter_name.downcase
+            when /(mysql).*/
+              require 'rotulus/db/mysql'
+
+              Rotulus::DB::MySQL.new
+            when /(postgres).*/
+              require 'rotulus/db/postgresql'
+
+              Rotulus::DB::PostgreSQL.new
+            else
+              require 'rotulus/db/sqlite'
+
+              Rotulus::DB::SQLite.new
+            end
+  end
+end