origin 0.0.0.alpha → 1.0.0.alpha

data/lib/origin/mergeable.rb

@@ -0,0 +1,226 @@
+# encoding: utf-8
+module Origin
+
+  # Contains behaviour for merging existing selection with new selection.
+  module Mergeable
+
+    # @attribute [rw] strategy The name of the current strategy.
+    attr_accessor :strategy
+
+    # Instruct the next mergeable call to use intersection.
+    #
+    # @example Use intersection on the next call.
+    #   mergeable.intersect.in(field: [ 1, 2, 3 ])
+    #
+    # @return [ Mergeable ] The intersect flagged mergeable.
+    #
+    # @since 1.0.0
+    def intersect
+      use(:__intersect__)
+    end
+
+    # Instruct the next mergeable call to use override.
+    #
+    # @example Use override on the next call.
+    #   mergeable.override.in(field: [ 1, 2, 3 ])
+    #
+    # @return [ Mergeable ] The override flagged mergeable.
+    #
+    # @since 1.0.0
+    def override
+      use(:__override__)
+    end
+
+    # Instruct the next mergeable call to use union.
+    #
+    # @example Use union on the next call.
+    #   mergeable.union.in(field: [ 1, 2, 3 ])
+    #
+    # @return [ Mergeable ] The union flagged mergeable.
+    #
+    # @since 1.0.0
+    def union
+      use(:__union__)
+    end
+
+    private
+
+    # Adds the criterion to the existing selection.
+    #
+    # @api private
+    #
+    # @example Add the criterion.
+    #   mergeable.__add__({ name: 1 }, "$in")
+    #
+    # @param [ Hash ] criterion The criteria.
+    # @param [ String ] operator The MongoDB operator.
+    #
+    # @return [ Mergeable ] The new mergeable.
+    #
+    # @since 1.0.0
+    def __add__(criterion, operator)
+      with_strategy(:__add__, criterion, operator)
+    end
+
+    # Adds the criterion to the existing selection.
+    #
+    # @api private
+    #
+    # @example Add the criterion.
+    #   mergeable.__expanded__([ 1, 10 ], "$within", "$center")
+    #
+    # @param [ Hash ] criterion The criteria.
+    # @param [ String ] outer The outer MongoDB operator.
+    # @param [ String ] inner The inner MongoDB operator.
+    #
+    # @return [ Mergeable ] The new mergeable.
+    #
+    # @since 1.0.0
+    def __expanded__(criterion, outer, inner)
+      selection(criterion) do |selector, field, value|
+        selector.store(field, { outer => { inner => value }})
+      end
+    end
+
+    # Adds the criterion to the existing selection.
+    #
+    # @api private
+    #
+    # @example Add the criterion.
+    #   mergeable.__intersect__([ 1, 2 ], "$in")
+    #
+    # @param [ Hash ] criterion The criteria.
+    # @param [ String ] operator The MongoDB operator.
+    #
+    # @return [ Mergeable ] The new mergeable.
+    #
+    # @since 1.0.0
+    def __intersect__(criterion, operator)
+      with_strategy(:__intersect__, criterion, operator)
+    end
+
+    # Adds the criterion to the existing selection.
+    #
+    # @api private
+    #
+    # @example Add the criterion.
+    #   mergeable.__multi__([ 1, 2 ], "$in")
+    #
+    # @param [ Hash ] criterion The criteria.
+    # @param [ String ] operator The MongoDB operator.
+    #
+    # @return [ Mergeable ] The new mergeable.
+    #
+    # @since 1.0.0
+    def __multi__(criterion, operator)
+      clone.tap do |query|
+        sel = query.selector
+        criterion.flatten.each do |expr|
+          next unless expr
+          criteria = sel[operator] || []
+          normalized = expr.inject({}) do |hash, (field, value)|
+            hash.merge!(field.specify(value))
+            hash
+          end
+          sel.store(operator, criteria.push(normalized))
+        end
+      end
+    end
+
+    # Adds the criterion to the existing selection.
+    #
+    # @api private
+    #
+    # @example Add the criterion.
+    #   mergeable.__override__([ 1, 2 ], "$in")
+    #
+    # @param [ Hash ] criterion The criteria.
+    # @param [ String ] operator The MongoDB operator.
+    #
+    # @return [ Mergeable ] The new mergeable.
+    #
+    # @since 1.0.0
+    def __override__(criterion, operator)
+      selection(criterion) do |selector, field, value|
+        selector.store(field, { operator => prepare(field, operator, value) })
+      end
+    end
+
+    # Adds the criterion to the existing selection.
+    #
+    # @api private
+    #
+    # @example Add the criterion.
+    #   mergeable.__union__([ 1, 2 ], "$in")
+    #
+    # @param [ Hash ] criterion The criteria.
+    # @param [ String ] operator The MongoDB operator.
+    #
+    # @return [ Mergeable ] The new mergeable.
+    #
+    # @since 1.0.0
+    def __union__(criterion, operator)
+      with_strategy(:__union__, criterion, operator)
+    end
+
+    # Prepare the value for merging.
+    #
+    # @api private
+    #
+    # @example Prepare the value.
+    #   mergeable.prepare("field", 10)
+    #
+    # @param [ String ] field The name of the field.
+    # @param [ Object ] value The value.
+    #
+    # @return [ Object ] The serialized value.
+    #
+    # @since 1.0.0
+    def prepare(field, operator, value)
+      return value if operator =~ /exists|type|size/
+      serializer = serializers[field]
+      serializer ? serializer.evolve(value) : value
+    end
+
+    # Use the named strategy for the next operation.
+    #
+    # @api private
+    #
+    # @example Use intersection.
+    #   mergeable.use(:__intersect__)
+    #
+    # @param [ Symbol ] strategy The strategy to use.
+    #
+    # @return [ Mergeable ] The existing mergeable.
+    #
+    # @since 1.0.0
+    def use(strategy)
+      tap do |mergeable|
+        mergeable.strategy = strategy
+      end
+    end
+
+    # Add criterion to the selection with the named strategy.
+    #
+    # @api private
+    #
+    # @example Add criterion with a strategy.
+    #   selectable.with_strategy(:__union__, [ 1, 2, 3 ], "$in")
+    #
+    # @param [ Symbol ] strategy The name of the strategy method.
+    # @param [ Object ] criterion The criterion to add.
+    # @param [ String ] operator The MongoDB operator.
+    #
+    # @return [ Mergeable ] The cloned query.
+    #
+    # @since 1.0.0
+    def with_strategy(strategy, criterion, operator)
+      selection(criterion) do |selector, field, value|
+        selector.store(
+          field,
+          selector[field].send(strategy, { operator => prepare(field, operator, value) })
+        )
+      end
+    end
+  end
+end

data/lib/origin/optional.rb

@@ -1,35 +1,320 @@
 # encoding: utf-8
 module Origin
+
+  # The optional module includes all behaviour that has to do with extra
+  # options surrounding queries, like skip, limit, sorting, etc.
   module Optional
+    extend Macroable
+
+    # @attribute [rw] options The query options.
+    attr_accessor :options
+
+    # Add ascending sorting options for all the provided fields.
+    #
+    # @example Add ascending sorting.
+    #   optional.ascending(:first_name, :last_name)
+    #
+    # @param [ Array<Symbol> ] fields The fields to sort.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def ascending(*fields)
+      sort_with_list(*fields, 1)
+    end
+    alias :asc :ascending
+    key :asc, :override, 1
+    key :ascending, :override, 1
+
+    # Adds the option for telling MongoDB how many documents to retrieve in
+    # it's batching.
+    #
+    # @example Apply the batch size options.
+    #   optional.batch_size(500)
+    #
+    # @param [ Integer ] value The batch size.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def batch_size(value = nil)
+      option(value) { |options| options.store(:batch_size, value) }
+    end
+
+    # Add descending sorting options for all the provided fields.
+    #
+    # @example Add descending sorting.
+    #   optional.descending(:first_name, :last_name)
+    #
+    # @param [ Array<Symbol> ] fields The fields to sort.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def descending(*fields)
+      sort_with_list(*fields, -1)
+    end
+    alias :desc :descending
+    key :desc, :override, -1
+    key :descending, :override, -1
+
+    # Add an index hint to the query options.
+    #
+    # @example Add an index hint.
+    #   optional.hint("$natural" => 1)
+    #
+    # @param [ Hash ] value The index hint.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def hint(value = nil)
+      option(value) { |options| options.store(:hint, value) }
+    end
+
+    # Add the number of documents to limit in the returned results.
+    #
+    # @example Limit the number of returned documents.
+    #   optional.limit(20)
+    #
+    # @param [ Integer ] value The number of documents to return.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def limit(value = nil)
+      option(value) { |options| options.store(:limit, value.to_i) }
+    end
+
+    # Adds the option to limit the number of documents scanned in the
+    # collection.
+    #
+    # @example Add the max scan limit.
+    #   optional.max_scan(1000)
+    #
+    # @param [ Integer ] value The max number of documents to scan.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def max_scan(value = nil)
+      option(value) { |options| options.store(:max_scan, value) }
+    end
+
+    # Tell the query not to timeout.
+    #
+    # @example Tell the query not to timeout.
+    #   optional.no_timeout
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def no_timeout
+      clone.tap { |query| query.options.store(:timeout, false) }
+    end
+
+    # Limits the results to only contain the fields provided.
+    #
+    # @example Limit the results to the provided fields.
+    #   optional.only(:name, :dob)
+    #
+    # @param [ Array<Symbol> ] args The fields to return.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def only(*args)
+      option(*args) do |options|
+        options.store(
+          :fields, args.inject({}){ |sub, field| sub.tap { sub[field] = 1 }}
+        )
+      end
+    end
+
+    # Adds sorting criterion to the options.
+    #
+    # @example Add sorting options via a hash with integer directions.
+    #   optional.order_by(name: 1, dob: -1)
+    #
+    # @example Add sorting options via a hash with symbol directions.
+    #   optional.order_by(name: :asc, dob: :desc)
+    #
+    # @example Add sorting options via a hash with string directions.
+    #   optional.order_by(name: "asc", dob: "desc")
+    #
+    # @example Add sorting options via an array with integer directions.
+    #   optional.order_by([[ name, 1 ], [ dob, -1 ]])
+    #
+    # @example Add sorting options via an array with symbol directions.
+    #   optional.order_by([[ name, :asc ], [ dob, :desc ]])
+    #
+    # @example Add sorting options via an array with string directions.
+    #   optional.order_by([[ name, "asc" ], [ dob, "desc" ]])
+    #
+    # @example Add sorting options with keys.
+    #   optional.order_by(:name.asc, :dob.desc)
+    #
+    # @example Add sorting options via a string.
+    #   optional.order_by("name ASC, dob DESC")
+    #
+    # @param [ Array, Hash, String ] spec The sorting specification.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def order_by(*spec)
+      option(spec) do |options|
+        spec.compact.each do |criterion|
+          criterion.__sort_option__.each_pair do |field, direction|
+            add_sort_option(options, field, direction)
+          end
+        end
+      end
+    end
+
+    # Add the number of documents to skip.
+    #
+    # @example Add the number to skip.
+    #   optional.skip(100)
+    #
+    # @param [ Integer ] value The number to skip.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def skip(value = nil)
+      option(value) { |options| options.store(:skip, value.to_i) }
+    end
+
+    # Limit the returned results via slicing embedded arrays.
+    #
+    # @example Slice the returned results.
+    #   optional.slice(aliases: [ 0, 5 ])
+    #
+    # @param [ Hash ] criterion The slice options.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def slice(criterion = nil)
+      option(criterion) do |options|
+        options.__union__(
+          fields: criterion.inject({}) do |option, (field, val)|
+            option.tap { |opt| opt.store(field, { "$slice" => val }) }
+          end
+        )
+      end
+    end
+
+    # Tell the query to operate in snapshot mode.
+    #
+    # @example Add the snapshot option.
+    #   optional.snapshot
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def snapshot
+      clone.tap do |query|
+        query.options.store(:snapshot, true)
+      end
+    end
+
+    # Limits the results to only contain the fields not provided.
+    #
+    # @example Limit the results to the fields not provided.
+    #   optional.without(:name, :dob)
+    #
+    # @param [ Array<Symbol> ] args The fields to ignore.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def without(*args)
+      option(*args) do |options|
+        options.store(
+          :fields, args.inject({}){ |sub, field| sub.tap { sub[field] = 0 }}
+        )
+      end
+    end
+
+    private
+
+    # Add a single sort option.
+    #
+    # @api private
+    #
+    # @example Add a single sort option.
+    #   optional.add_sort_option({}, :name, 1)
+    #
+    # @param [ Hash ] options The options.
+    # @param [ String ] field The field name.
+    # @param [ Integer ] direction The sort direction.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def add_sort_option(options, field, direction)
+      sorting = (options[:sort] || {}).dup
+      sorting[field] = direction
+      options.store(:sort, sorting)
+    end
+
+    # Take the provided criterion and store it as an option in the query
+    # options.
+    #
+    # @api private
+    #
+    # @example Store the option.
+    #   optional.option({ skip: 10 })
+    #
+    # @param [ Array ] args The options.
+    #
+    # @return [ Queryable ] The cloned queryable.
+    #
+    # @since 1.0.0
+    def option(*args)
+      clone.tap do |query|
+        unless args.compact.empty?
+          yield(query.options)
+        end
+      end
+    end
+
+    # Add multiple sort options at once.
+    #
+    # @api private
+    #
+    # @example Add multiple sort options.
+    #   optional.sort_with_list(:name, :dob, 1)
+    #
+    # @param [ Array<String> ] fields The field names.
+    # @param [ Integer ] direction The sort direction.
+    #
+    # @return [ Optional ] The cloned optional.
+    #
+    # @since 1.0.0
+    def sort_with_list(*fields, direction)
+      option(fields) do |options|
+        fields.flatten.compact.each do |field|
+          add_sort_option(options, field, direction)
+        end
+      end
+    end
+
+    class << self
 
-    autoload :BatchSize, "origin/optional/batch_size"
-    autoload :Hint, "origin/optional/hint"
-    autoload :Limit, "origin/optional/limit"
-    autoload :MaxScan, "origin/optional/max_scan"
-    autoload :NoTimeout, "origin/optional/no_timeout"
-    autoload :Only, "origin/optional/only"
-    autoload :Read, "origin/optional/read"
-    autoload :ReturnKey, "origin/optional/return_key"
-    autoload :ShowDiskLoc, "origin/optional/show_disk_loc"
-    autoload :Skip, "origin/optional/skip"
-    autoload :Slice, "origin/optional/slice"
-    autoload :Snapshot, "origin/optional/snapshot"
-    autoload :Transformer, "origin/optional/transformer"
-    autoload :Without, "origin/optional/without"
-
-    include BatchSize
-    include Hint
-    include Limit
-    include MaxScan
-    include NoTimeout
-    include Only
-    include Read
-    include ReturnKey
-    include ShowDiskLoc
-    include Skip
-    include Slice
-    include Snapshot
-    include Transformer
-    include Without
+      # Get the methods on the optional that can be forwarded to from a model.
+      #
+      # @example Get the forwardable methods.
+      #   Optional.forwardables
+      #
+      # @return [ Array<Symbol> ] The names of the forwardable methods.
+      #
+      # @since 1.0.0
+      def forwardables
+        public_instance_methods(false) - [ :options, :options= ]
+      end
+    end
   end
 end