hotstepper 0.1.0

data/lib/generators/hotstepper/typespace/typespace_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  class TypespaceGenerator < Rails::Generators::Base
+    include Hotstepper::Support::Generators::Common
+    include Hotstepper::Support::Generators::Namespaced
+
+    source_root File.expand_path("templates", __dir__)
+
+    def prepare!
+      set_up_namespace!
+
+      @types = namespaced_file("Types")
+    end
+
+    def generate_type!
+      template "types.rb", types.to_service_path
+    end
+
+    private
+
+    # @return [Hotstepper::Support::Generators::FileWrapper]
+    attr_reader :types
+  end
+end

data/lib/hotstepper/arel_ext/array_encoding.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # A module for encoding Postgres arrays in Arel expressions.
+    #
+    # It will cause errors when used with other databases, but only when the methods are called at runtime.
+    module ArrayEncoding
+      include BaseHelpers
+
+      class << self
+        def int_array
+          @int_array ||= ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.new(ActiveRecord::Type::Integer.new).freeze
+        end
+
+        def ltree_type
+          @ltree_type ||= ActiveRecord::ConnectionAdapters::PostgreSQL::OID::SpecializedString.new(:ltree)
+        end
+
+        def ltree_array
+          @ltree_array ||= ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.new(ltree_type).freeze
+        end
+
+        def lquery_type
+          @lquery_type ||= ActiveRecord::ConnectionAdapters::PostgreSQL::OID::SpecializedString.new(:lquery)
+        end
+
+        def lquery_array
+          @lquery_array ||= ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.new(lquery_type).freeze
+        end
+
+        def text_array
+          @text_array ||= ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.new(ActiveRecord::Type::Text.new).freeze
+        end
+      end
+
+      def arel_encode_enum_array(*elements, enum_type:)
+        arel_cast(arel_quote(Hotstepper::ArelExt::ArrayEncoding.lquery_array.serialize(elements.flatten)), "#{enum_type}[]")
+      end
+
+      def arel_encode_int_array(*elements)
+        arel_cast(arel_quote(Hotstepper::ArelExt::ArrayEncoding.int_array.serialize(elements.flatten)), "int[]")
+      end
+
+      def arel_encode_lquery_array(*elements)
+        arel_cast(arel_quote(Hotstepper::ArelExt::ArrayEncoding.lquery_array.serialize(elements.flatten)), "lquery[]")
+      end
+
+      # @return [Arel::Nodes::Quoted]
+      def arel_encode_ltree_array(*elements)
+        arel_cast(arel_quote(Hotstepper::ArelExt::ArrayEncoding.ltree_array.serialize(elements.flatten)), "ltree[]")
+      end
+
+      # @return [Arel::Nodes::Quoted]
+      def arel_encode_text_array(*elements)
+        arel_cast(arel_quote(Hotstepper::ArelExt::ArrayEncoding.text_array.serialize(elements.flatten)), "text[]")
+      end
+
+      def arel_value_in_array(value, array)
+        any_array = arel_named_fn("ANY", arel_quote(array))
+
+        arel_quote(value).eq(any_array)
+      end
+    end
+  end
+end

data/lib/hotstepper/arel_ext/base_helpers.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # Base helpers for building Arel expressions.
+    module BaseHelpers
+      # @param [Symbol, String] field
+      # @param [String] value
+      # @return [Arel::Nodes::Matches] an Arel expression that matches the field to the value with a `LIKE`
+      #   query, with the value wrapped in `%` wildcards and with any `%` or `_` characters in the value escaped.
+      def arel_text_contains(field, value) = arel_table[field].matches("%#{escape_ilike_needle(value)}%")
+
+      # @param [String] needle
+      # @return [String] the needle with `%` and `_` characters escaped for use in a `LIKE` or `ILIKE` query.
+      def escape_ilike_needle(needle) = needle.gsub("%", "\\%").gsub("_", "\\_")
+
+      # @param [Object] left
+      # @param [Object] right
+      # @return [Arel::Nodes::As]
+      def arel_as(left, right) = Arel::Nodes::As.new(left, right)
+
+      # @param [Object] expr
+      # @param [String, nil] cast_to if provided, the SQL type to cast the expression to
+      # @return [Arel::Nodes::Case]
+      # @return [Arel::Nodes::NamedFunction("CAST")] when a `cast_to` expression is provided
+      def arel_case(expr = nil, cast_to: nil, &block)
+        statement = Arel::Nodes::Case.new(expr).tap(&block)
+
+        if cast_to.present?
+          arel_cast(statement, cast_to)
+        else
+          statement
+        end
+      end
+
+      # @param [Object] value
+      # @param [String] type the SQL type to cast to, e.g. "int", "text", "ltree"
+      # @return [Arel::Nodes::NamedFunction("CAST")]
+      def arel_cast(value, type) = arel_named_fn("CAST", arel_as(arel_quote(value), arel_literal(type)))
+
+      # @param [Array] exprs
+      # @return [Arel::Nodes::NamedFunction("COALESCE")]
+      def arel_coalesce(*exprs) = arel_named_fn("COALESCE", *exprs)
+
+      # A helper for building a case expression that works like if/else.
+      #
+      # @param [Object] boolean_expr an expression that evaluates to a boolean value
+      # @param [Object] truthy_expr the value to return if the boolean expression is true
+      # @param [Object] falsey_expr the value to return if the boolean expression is false
+      # @return [Arel::Nodes::Case]
+      def arel_if_else(boolean_expr, truthy_expr, falsey_expr)
+        arel_case do |stmt|
+          stmt.when(arel_quote(boolean_expr)).then(arel_quote(truthy_expr))
+
+          stmt.else(arel_quote(falsey_expr))
+        end
+      end
+
+      # @param [String] operator
+      # @param [Object] left
+      # @param [Object] right
+      # @return [Arel::Nodes::InfixOperation]
+      def arel_infix(operator, left, right) = Arel::Nodes::InfixOperation.new(operator, left, right)
+
+      # Encode a raw SQL string as an Arel node.
+      #
+      # @note Don't use with untrusted input!
+      # @param [String] value
+      # @return [Arel::Nodes::SqlLiteral]
+      def arel_literal(value) = Arel.sql(value)
+
+      # @param [String] name
+      # @param [Array] args
+      # @return [Arel::Nodes::NamedFunction]
+      def arel_named_fn(name, *args)
+        quoted_args = args.map { arel_quote(_1) }
+
+        Arel::Nodes::NamedFunction.new name, quoted_args
+      end
+
+      # @param [Arel::Nodes::Node] expression
+      # @return [Arel::Nodes::Not]
+      def arel_not(expression) = Arel::Nodes::Not.new expression
+
+      # @param [Object] arg
+      # @return [Arel::Nodes::Quoted] if arg is not already an Arel node
+      # @return [Arel::Nodes::Node] if arg is already an Arel node
+      def arel_quote(arg)
+        return arg if arg.kind_of?(Arel::Nodes::Node)
+
+        Arel::Nodes.build_quoted arg
+      end
+
+      # @see #arel_expr_in_query
+      # @param [Symbol] attr (see #arel_attrify)
+      # @param [#to_sql, #to_s] query
+      # @return [Arel::Nodes::In]
+      def arel_attr_in_query(attr, query) = arel_expr_in_query arel_attrify(attr), query
+
+      # @param [#in] expr
+      # @param [#to_sql, #to_s] query
+      # @return [Arel::Nodes::In]
+      def arel_expr_in_query(expr, query)
+        wrapped_query = arel_quote_query query
+
+        expr.in(wrapped_query)
+      end
+
+      # @param [#to_sql] query
+      # @return [Arel::Nodes::SqlLiteral]
+      def arel_quote_query(query)
+        case query
+        when Hotstepper::ArelExt::Types::ToSQL then arel_literal query.to_sql
+        when String then arel_literal query
+        else
+          # :nocov:
+          raise TypeError, "cannot quote query #{query.inspect}"
+          # :nocov:
+        end
+      end
+
+      # @param [Arel::Nodes::Node] value
+      # @return [Arel::Nodes::Grouping]
+      def arel_grouped(value) = Arel::Nodes::Grouping.new(value)
+
+      alias arel_grouping arel_grouped
+
+      # @param [Arel::OrderPredications] expression
+      # @param ["asc", "desc"] dir
+      # @param ["first", "last", nil] nulls
+      # @return [Arel::Nodes::Ordering]
+      def arel_apply_order_to(expression, dir, nulls: nil)
+        direction = Hotstepper::ArelExt::Types::SortDir[dir]
+
+        nulls_value = Hotstepper::ArelExt::Types::NullsDir[nulls || direction]
+
+        if direction == "desc"
+          expression.desc
+        else
+          expression.asc
+        end.then do |ordered|
+          if nulls_value == "first"
+            ordered.nulls_first
+          else
+            ordered.nulls_last
+          end
+        end
+      end
+
+      # Makes a more legible series of AND conditions.
+      # @return [Arel::Nodes::Grouping(Arel::Nodes::And)]
+      def arel_and_expressions(*expressions)
+        expressions.flatten!
+
+        return block_given? ? yield(expressions[0]) : expressions[0] if expressions.one?
+
+        expressions.reduce do |grouping, expression|
+          expression = yield expression if block_given?
+
+          next grouping if expression.blank?
+
+          if grouping.kind_of?(Arel::Nodes::Grouping)
+            grouping.expr.and(expression)
+          else
+            # First expression
+            grouping = yield grouping if block_given?
+
+            grouping.and(expression)
+          end
+        end
+      end
+
+      # Makes a more legible series of OR conditions.
+      # @return [Arel::Nodes::Grouping(Arel::Nodes::Or)]
+      def arel_or_expressions(*expressions)
+        expressions.flatten!
+
+        return block_given? ? yield(expressions[0]) : expressions[0] if expressions.one?
+
+        expressions.reduce do |grouping, expression|
+          expression = yield expression if block_given?
+
+          next grouping if expression.blank?
+
+          if grouping.kind_of?(Arel::Nodes::Grouping)
+            grouping.expr.or(expression)
+          else
+            # First expression
+            grouping = yield grouping if block_given?
+
+            grouping.or(expression)
+          end
+        end
+      end
+
+      # @param [String, Symbol, Arel::Attributes::Attribute, Arel::Nodes::SqlLiteral, Arel::Expresions, Arel::Node] attribute
+      # @return [Arel::Attributes::Attribute]
+      # @return [Arel::Nodes::SqlLiteral]
+      # @return [Arel::Node]
+      def arel_attrify(attribute)
+        case attribute
+        when Arel::Attributes::Attribute, Arel::Nodes::SqlLiteral, Arel::Expressions, Arel::Nodes::Node
+          attribute
+        when arel_column_matcher
+          arel_table[attribute]
+        when /\A[^.\s]+\.[^.\s]+/
+          arel_literal attribute
+        else
+          raise TypeError, "Don't know how to turn #{attribute} into an Arel::Attribute"
+        end
+      end
+
+      # @!scope private
+      # @return [Regexp]
+      def arel_column_matcher
+        @arel_column_matcher ||= /\A#{Regexp.union(column_names)}\z/
+      end
+    end
+  end
+end

data/lib/hotstepper/arel_ext/helpers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # Helpers for building Arel expressions.
+    #
+    # @note This should be `extend`ed on the model class as it is not a concern,
+    #   it is sometimes used in instance methods on query building classes.
+    module Helpers
+      include Hotstepper::ArelExt::BaseHelpers
+      include Hotstepper::ArelExt::ArrayEncoding
+      include Hotstepper::ArelExt::JsonEncoding
+      include Hotstepper::ArelExt::LtreeEncoding
+      include Hotstepper::ArelExt::PostgresHelpers
+    end
+  end
+end

data/lib/hotstepper/arel_ext/json_encoding.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # A module for encoding JSON values in Arel expressions with Postgres syntax.
+    #
+    # The syntax will not work in other databases, but it should not raise errors
+    # unless actually passed to ActiveRecord.
+    module JsonEncoding
+      include BaseHelpers
+
+      def arel_json_contains(attribute, **values)
+        arel_infix "@>", arel_attrify(attribute), arel_cast(values.to_json, "jsonb")
+      end
+
+      def arel_json_has_key(attribute, key)
+        arel_infix ??, arel_attrify(attribute), arel_quote(key)
+      end
+
+      def arel_json_get_path(attribute, *path_parts)
+        raise "Must have at least one part" if path_parts.blank?
+
+        arel_infix "#>", arel_attrify(attribute), arel_encode_text_array(*path_parts)
+      end
+
+      def arel_json_get_path_as_text(attribute, *path_parts)
+        raise "Must have at least one part" if path_parts.blank?
+
+        arel_infix "#>>", arel_attrify(attribute), arel_encode_text_array(*path_parts)
+      end
+
+      def arel_json_get(attribute, key)
+        arel_infix "->", arel_attrify(attribute), arel_quote(key)
+      end
+
+      def arel_json_get_as_text(attribute, key)
+        arel_infix "->>", arel_attrify(attribute), arel_quote(key)
+      end
+
+      def arel_json_cast_property(attribute, key, type)
+        arel_cast(arel_json_get_as_text(attribute, key), type)
+      end
+
+      def arel_json_partial_update(attribute, **values)
+        arel_infix "||", arel_attrify(attribute), arel_cast(values.to_json, "jsonb")
+      end
+    end
+  end
+end

data/lib/hotstepper/arel_ext/ltree_encoding.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # A module for working with postgres' `ltree` extension in Arel.
+    #
+    # The syntax will not work in other databases, but it should not raise errors
+    # unless actually passed to ActiveRecord.
+    module LtreeEncoding
+      include BaseHelpers
+
+      # @param [Object] value
+      # @return [Arel::Nodes::NamedFunction("CAST")]
+      def arel_ltree(value) = arel_cast(value, "ltree")
+
+      # @param [String, Arel::Attribute] left
+      # @param [Object] right
+      # @return [Arel::Nodes::InfixOperation]
+      def arel_ltree_contains(left, right)
+        arel_infix "@>", arel_attrify(left), arel_quote(right)
+      end
+
+      # @param [String, Arel::Attribute] left
+      # @param [Object] right
+      # @return [Arel::Nodes::InfixOperation]
+      def arel_ltree_matches(left, right)
+        arel_infix ?~, arel_attrify(left), arel_quote(right)
+      end
+
+      # @param [String, Arel::Attribute] attribute
+      # @param [String, Array<String>, Hotstepper::ArelExt::Types::ManyArray] queries
+      # @return [Arel::Nodes::InfixOperation]
+      def arel_ltree_matches_any_query(attribute, *queries)
+        arel_infix(??, arel_attrify(attribute), arel_encode_lquery_array(*queries))
+      end
+
+      # @param [String, Arel::Attribute] left
+      # @param [String, Array<String>, Hotstepper::ArelExt::Types::ManyArray] right
+      # @return [Arel::Nodes::InfixOperation]
+      def arel_ltree_matches_one_or_any(left, right)
+        case right
+        when Hotstepper::ArelExt::Types::ManyArray
+          arel_ltree_matches_any_query left, *right
+        when Array
+          arel_ltree_matches left, right.first
+        else
+          arel_ltree_matches left, right
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/arel_ext/postgres_helpers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # Methods that specifically rely on Postgres syntax.
+    module PostgresHelpers
+      include BaseHelpers
+
+      # @param [String, Symbol, Arel::Attributes::Attribute] column
+      # @param [String] attribute
+      # @return [Arel::Nodes::Grouping] an expression that accesses the given attribute of a Postgres composite type.
+      def arel_composite_attr(column, attribute)
+        composite = arel_grouping(arel_attrify(column))
+
+        arel_literal("(%s.#{attribute})" % [composite.to_sql])
+      end
+
+      # @param [String, Symbol, Arel::Attributes::Attribute] attr_or_column
+      # @param [String] input
+      # @return [Arel::Nodes::Or(Arel::Nodes::InfixOperation("%"), Arel::Nodes::InfixOperation("%>"))] a condition that matches either the trigram similarity or the trigram match
+      def arel_trigram_match(attr_or_column, input)
+        attr = arel_attrify attr_or_column
+
+        quoted = arel_quote input
+
+        trigrams = arel_infix(?%, attr, quoted)
+
+        similarity = arel_infix("%>", attr, quoted)
+
+        trigrams.or(similarity)
+      end
+    end
+  end
+end

data/lib/hotstepper/arel_ext/types.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # A module for custom types used when matching Arel expressions.
+    module Types
+      extend Hotstepper::Typespace
+
+      # @return [Array] An array of at least two elements of any type.
+      ManyArray = Array.of(Any).constrained(min_size: 2)
+
+      # @return [Dry::Types::Type(String)]
+      NullsDir = Coercible::String.fallback("last").enum("last", "first").constructor do |raw|
+        value = raw.to_s.downcase
+
+        case value
+        when "asc" then "last"
+        when "desc" then "first"
+        else
+          value
+        end
+      end
+
+      SortDir = Coercible::String.fallback("asc").enum("asc", "desc").constructor do |value|
+        value.to_s.downcase
+      end
+
+      ToSQL = Interface(:to_sql)
+
+      ValueSelectCasts = Hash.map(Coercible::Symbol, Coercible::Symbol)
+
+      ValueSelectValue = Hash.map(Coercible::Symbol, Any).constrained(min_size: 1)
+
+      ValueSelectValues = Array.of(ValueSelectValue)
+    end
+  end
+end

data/lib/hotstepper/arel_ext/value_select_query.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module ArelExt
+    # A helper for building a `SELECT * FROM (VALUES (...)), ... ) AS tbl (col1, col2, ...)` query with proper type casts.
+    #
+    # @todo Make connection configurable if needed.
+    class ValueSelectQuery
+      include Dry::Initializer[undefined: false].define -> do
+        param :values, ::Hotstepper::ArelExt::Types::ValueSelectValues
+
+        option :casts, ::Hotstepper::ArelExt::Types::ValueSelectCasts, default: proc { Dry::Core::Constants::EMPTY_HASH }
+        option :table_name, ::Hotstepper::ArelExt::Types::String, default: proc { "tbl" }
+        option :model_class, ::Hotstepper::Support::Models::Types::ModelClass.optional, optional: true
+      end
+
+      DEFAULT_TYPE = ActiveRecord::Type::Value.new.freeze
+
+      # We won't bother casting columns with these types,
+      # since PG will figure it out.
+      SKIPPABLE_CASTS = [
+        nil,
+        :boolean,
+        :string,
+        :citext,
+        :text
+      ].freeze
+
+      # @return [Hash{Symbol => Symbol}]
+      attr_reader :column_casts
+
+      # @return [Array<Symbol>]
+      attr_reader :column_names
+
+      # @return [Hash{Symbol => ActiveRecord::Type}]
+      attr_reader :column_types
+
+      # @return [<String>]
+      attr_reader :quoted_columns
+
+      # @return [<<Arel::Nodes::SqlLiteral>>]
+      attr_reader :quoted_values
+
+      # @return [Arel::Table]
+      attr_reader :table
+
+      # @return [Arel::Nodes::ValuesList]
+      attr_reader :values_list
+
+      def initialize(...)
+        super
+
+        compile_columns!
+
+        compile_values_list!
+
+        compile_query!
+      end
+
+      def to_sql = @query.to_sql
+
+      private
+
+      # @return [void]
+      def compile_columns!
+        @column_names = values.reduce([]) { |n, v| n | v.keys }
+
+        @column_types = column_names.index_with { |name| model_class&.type_for_attribute(name.to_s) || DEFAULT_TYPE }
+
+        @column_casts = column_names.index_with { |name| normalize_cast(casts[name] || default_column_cast_for(name)) }
+
+        @quoted_columns = column_names.map { |name| quote_column(name) }
+
+        @table = Arel::Table.new(table_name)
+      end
+
+      # @return [void]
+      def compile_values_list!
+        @quoted_values = quote_values
+
+        @values_list = Arel::Nodes::Grouping.new(Arel::Nodes::ValuesList.new(quoted_values))
+      end
+
+      def compile_query!
+        source = Arel::Nodes::As.new(values_list, Arel.sql("#{table_name}(#{quoted_columns.join(", ")})"))
+
+        projections = column_names.map do |name|
+          cast = column_casts[name]
+
+          quoted = quote_column(name)
+
+          next quoted unless cast
+
+          Arel.sql("CAST(#{quoted} AS #{cast}) AS #{quoted}")
+        end
+
+        @query = table.project(*projections).from(source)
+      end
+
+      def connection = ActiveRecord::Base.connection
+
+      # @param [Symbol] attribute
+      # @return [String, nil]
+      def default_column_cast_for(attribute)
+        return unless model_class
+
+        column = model_class.columns_hash[attribute.to_s]
+
+        stm = column&.sql_type_metadata
+
+        return if stm.blank? || stm.type.in?(SKIPPABLE_CASTS)
+
+        stm.sql_type
+      end
+
+      def normalize_cast(input)
+        case input
+        when :json then :jsonb
+        when :string, :citext then nil
+        else input
+        end
+      end
+
+      def quote_column(name) = connection.quote_column_name(name)
+
+      def quote_value(value) = connection.quote(value)
+
+      # @return [<<Arel::Nodes::SqlLiteral>>]
+      def quote_values
+        values.map do |value_hash|
+          column_names.map do |name|
+            serialized = column_types[name].serialize(value_hash[name])
+
+            quoted = quote_value(serialized)
+
+            Arel.sql(quoted)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/common.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Common
+    # A container resolver that looks up keys in the `Hotstepper.config.common.container`.
+    #
+    # It does not memoize results, so it will work correctly in development mode / Rails reloading.
+    #
+    # @api private
+    class Resolver < Dry::Container::Resolver
+      def call(_, key)
+        common_container = Hotstepper.config.common.container or raise MissingCommonContainerError
+
+        common_container.resolve(key)
+      end
+    end
+
+    # A container that will defer to whatever the current value of the `Hotstepper.config.common.container`
+    # is at the time of resolution. This allows operations that include the `CallsOperation` mixin to call
+    # operations from the host application's container, without needing to worry about how that container is set up.
+    #
+    # In development, this will allow the value to be automatically reset as the host application reloads.
+    module Container
+      extend Dry::Container::Mixin
+
+      config.resolver = Resolver.new
+    end
+
+    # dry-auto_inject mixin for the common container.
+    Deps = Dry::AutoInject(Container)
+
+    # Common operation mixin for Rails applications.
+    #
+    # This is intended for allowing easy interop with the host Rails application, so long as it
+    # hooks its container into `Hotstepper.config.common.container`. If the host application is
+    # using dry-rails, this will automatically be set up by the engine.
+    module CallsOperation
+      extend ActiveSupport::Concern
+      extend Hotstepper::Monadic::Decorators
+
+      # Calls an operation from the common container.
+      #
+      # @see Hotstepper::Common::Container
+      # @param [String, Symbol] name
+      # @param [Object] ... all other args will be passed onto the operation's `call` method
+      # @return [Object] the return value of the operation's `call` method
+      monadic_operation! def call_operation(name, ...)
+        Hotstepper::Common::Container[name].(...)
+      end
+    end
+  end
+end