activeitem 0.0.23 → 0.0.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3391ecc77f10aaffc7953d95d84691bdf4791ea11163fe45ba7b3b5be3b8418f
-  data.tar.gz: 02ad5cbf59628300f250fa972729ad503a53e197824350f7990e7d8cefd4281f
+  metadata.gz: 296b80f6ec0f16823c99df6d3a041fe16d55eab4ce59118d95081566f13e01d4
+  data.tar.gz: 8ec0e73b20698346c67f96075c0ccc3070f2f6232c1e1b3607a61424c1a19f8b
 SHA512:
-  metadata.gz: b60d3ec30ab2f3f5a593c320d6af5764e793574b03e4389661325942d9e31d8c7b40b25532816ac0e1a5b8cfd4c5b49650ea413673d2686dd05a3841aeb0ae56
-  data.tar.gz: 37398daa0b3af333ed40fb9dc2ad4571d9044df57ebaefe7f20fd21a5c714676cce31925e5b8d5a9a6a847768b15e0e53eca8138ed7b89b38fbf17d8cc71b665
+  metadata.gz: 8b5d8087d0cffede8296535868978d6dd24cddc70d1f6a1ba0741db31d5fc46caaea9635791f8984166aa8de92bfb50db000ecc935df4fe6498ecc2456fc1029
+  data.tar.gz: ef5ca8b2bb01a83a5673d0181d13627d5eb0b8bb01612f6e6ef146c5e4eb669cfd2ef0936c1aa09b15e6a5eed2367d7b1adb3c844c7e8aa4c72e7dc600201624

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.0.24
+
+### Added
+
+- **`ActiveItem.begins_with` for prefix queries** — Pass it as a `where` value. On an index's sort key it goes into the key condition (`begins_with(#sk, :sk_val)`), so DynamoDB reads only the matching items instead of scanning. On any other attribute it becomes a `begins_with` filter, and `where.not` gives `NOT begins_with(...)`. Works with `limit`, `order`, `count`, `explain`, and array (fan-out) partition keys.
+
+  ```ruby
+  # GSI PrefixIndex: partition = first 2 letters, sort = whole name (both lowercased)
+  Username.where(search_prefix: 'ab', search_name: ActiveItem.begins_with('abe')).limit(10)
+  ```
+
+### Changed
+
+- The equality / Range / prefix sort-key condition is now built in one place (`build_sort_key_condition`) instead of five copies in `Relation`.
+
 ## 0.0.23
 
 ### Added

data/README.md

@@ -75,6 +75,18 @@ User.count
 User.exists?('user-123')
 ```
 
+Sort-key conditions on an index go into the key condition, not a filter:
+
+```ruby
+Event.where(customer_id: id, created_at: 1.week.ago..)                 # >=, <=, BETWEEN via Range
+Username.where(search_prefix: 'ab', search_name: ActiveItem.begins_with('abe'))  # prefix
+```
+
+For prefix search (autocomplete), add a GSI whose partition key is the first few
+lowercased characters and whose sort key is the whole lowercased value, then
+`begins_with` on the sort key. `begins_with` on a non-key attribute works too, but
+it's a filter, so DynamoDB still reads every item in the query or scan.
+
 ### Associations
 
 ```ruby

data/lib/active_item/begins_with.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveItem
+  # A prefix match for `where`, built with ActiveItem.begins_with.
+  #
+  # On an index's sort key it becomes part of the key condition, so DynamoDB
+  # reads only the matching items. On any other attribute it is a filter.
+  #
+  # @example Prefix search on a GSI (partition = first letters, sort = whole name)
+  #   Username.where(search_prefix: 'ab', search_name: ActiveItem.begins_with('abc')).limit(10)
+  BeginsWith = Data.define(:prefix) do
+    def initialize(prefix:)
+      raise ArgumentError, 'begins_with needs a non-empty prefix' if prefix.to_s.empty?
+
+      super(prefix: prefix.to_s)
+    end
+  end
+end

data/lib/active_item/query_helpers.rb

@@ -411,6 +411,7 @@ module ActiveItem
     # - Range values (BETWEEN): { date: Date.today..Date.today + 7 }
     # - Beginless range (<=): { date: ..Date.today }
     # - Endless range (>=): { date: Date.today.. }
+    # - Prefix match: { name: ActiveItem.begins_with('ab') }
     # - Model objects: { parent_container: container } -> uses container.id
     #
     # Note: Attribute names are converted from Ruby snake_case to DynamoDB camelCase
@@ -452,6 +453,9 @@ module ActiveItem
       # Handle Range values (BETWEEN, >=, <=)
       return build_range_condition(dynamo_attr, val, idx) if val.is_a?(Range)
 
+      # Handle prefix match (begins_with)
+      return ["begins_with(#attr#{idx}, :val#{idx})", { "#attr#{idx}" => dynamo_attr }, { ":val#{idx}" => val.prefix }] if val.is_a?(ActiveItem::BeginsWith)
+
       # Handle array values (IN clause)
       return build_in_condition(dynamo_attr, val, idx) if val.is_a?(Array)
 
@@ -596,6 +600,24 @@ module ActiveItem
       end
     end
 
+    # Build the sort key part of a GSI key condition: equality, a Range
+    # (BETWEEN, >=, <=), or ActiveItem.begins_with.
+    def build_sort_key_condition(sort_key, value, placeholder_prefix = 'sk')
+      return build_sort_key_range_condition(sort_key, value, placeholder_prefix) if value.is_a?(Range)
+
+      expression = if value.is_a?(ActiveItem::BeginsWith)
+                     value = value.prefix
+                     "begins_with(##{placeholder_prefix}, :#{placeholder_prefix}_val)"
+                   else
+                     "##{placeholder_prefix} = :#{placeholder_prefix}_val"
+                   end
+      {
+        expression: expression,
+        names: { "##{placeholder_prefix}" => sort_key },
+        values: { ":#{placeholder_prefix}_val" => value }
+      }
+    end
+
     # Build sort key condition for Range values in GSI queries
     # Returns the key condition expression part and values for sort key
     def build_sort_key_range_condition(sort_key, range, placeholder_prefix = 'sk')

data/lib/active_item/relation.rb

@@ -660,16 +660,10 @@ module ActiveItem
             resolved_model.to_dynamo_key(k.to_s) == sort_key || k.to_s == sort_key
           end
 
-          if sort_value.is_a?(Range)
-            range_condition = resolved_model.send(:build_sort_key_range_condition, sort_key, sort_value)
-            params[:key_condition_expression] += " AND #{range_condition[:expression]}"
-            params[:expression_attribute_names].merge!(range_condition[:names])
-            params[:expression_attribute_values].merge!(range_condition[:values])
-          else
-            params[:key_condition_expression] += ' AND #sk = :sk_val'
-            params[:expression_attribute_names]['#sk'] = sort_key
-            params[:expression_attribute_values][':sk_val'] = sort_value
-          end
+          key_condition = resolved_model.send(:build_sort_key_condition, sort_key, sort_value)
+          params[:key_condition_expression] += " AND #{key_condition[:expression]}"
+          params[:expression_attribute_names].merge!(key_condition[:names])
+          params[:expression_attribute_values].merge!(key_condition[:values])
         end
       end
 
@@ -906,16 +900,10 @@ module ActiveItem
             resolved_model.to_dynamo_key(k.to_s) == sort_key || k.to_s == sort_key
           end
 
-          if sort_value.is_a?(Range)
-            range_condition = resolved_model.send(:build_sort_key_range_condition, sort_key, sort_value)
-            params[:key_condition_expression] += " AND #{range_condition[:expression]}"
-            params[:expression_attribute_names].merge!(range_condition[:names])
-            params[:expression_attribute_values].merge!(range_condition[:values])
-          else
-            params[:key_condition_expression] += ' AND #sk = :sk_val'
-            params[:expression_attribute_names]['#sk'] = sort_key
-            params[:expression_attribute_values][':sk_val'] = sort_value
-          end
+          key_condition = resolved_model.send(:build_sort_key_condition, sort_key, sort_value)
+          params[:key_condition_expression] += " AND #{key_condition[:expression]}"
+          params[:expression_attribute_names].merge!(key_condition[:names])
+          params[:expression_attribute_values].merge!(key_condition[:values])
         end
       end
 
@@ -1020,16 +1008,10 @@ module ActiveItem
             resolved_model.to_dynamo_key(k.to_s) == sort_key || k.to_s == sort_key
           end
 
-          if sort_value.is_a?(Range)
-            range_condition = resolved_model.send(:build_sort_key_range_condition, sort_key, sort_value)
-            params[:key_condition_expression] += " AND #{range_condition[:expression]}"
-            params[:expression_attribute_names].merge!(range_condition[:names])
-            params[:expression_attribute_values].merge!(range_condition[:values])
-          else
-            params[:key_condition_expression] += ' AND #sk = :sk_val'
-            params[:expression_attribute_names]['#sk'] = sort_key
-            params[:expression_attribute_values][':sk_val'] = sort_value
-          end
+          key_condition = resolved_model.send(:build_sort_key_condition, sort_key, sort_value)
+          params[:key_condition_expression] += " AND #{key_condition[:expression]}"
+          params[:expression_attribute_names].merge!(key_condition[:names])
+          params[:expression_attribute_values].merge!(key_condition[:values])
         end
       end
 
@@ -1186,16 +1168,10 @@ module ActiveItem
             resolved_model.to_dynamo_key(k.to_s) == sort_key || k.to_s == sort_key
           end
 
-          if sort_value.is_a?(Range)
-            range_condition = resolved_model.send(:build_sort_key_range_condition, sort_key, sort_value)
-            params[:key_condition_expression] += " AND #{range_condition[:expression]}"
-            params[:expression_attribute_names].merge!(range_condition[:names])
-            params[:expression_attribute_values].merge!(range_condition[:values])
-          else
-            params[:key_condition_expression] += ' AND #sk = :sk_val'
-            params[:expression_attribute_names]['#sk'] = sort_key
-            params[:expression_attribute_values][':sk_val'] = sort_value
-          end
+          key_condition = resolved_model.send(:build_sort_key_condition, sort_key, sort_value)
+          params[:key_condition_expression] += " AND #{key_condition[:expression]}"
+          params[:expression_attribute_names].merge!(key_condition[:names])
+          params[:expression_attribute_values].merge!(key_condition[:values])
         end
       end
 
@@ -1416,16 +1392,10 @@ module ActiveItem
       return unless sort_condition
 
       _, sort_value = sort_condition
-      if sort_value.is_a?(Range)
-        range_condition = resolved_model.send(:build_sort_key_range_condition, sort_key, sort_value)
-        params[:key_condition_expression] += " AND #{range_condition[:expression]}"
-        params[:expression_attribute_names].merge!(range_condition[:names])
-        params[:expression_attribute_values].merge!(range_condition[:values])
-      else
-        params[:key_condition_expression] += ' AND #sk = :sk_val'
-        params[:expression_attribute_names]['#sk'] = sort_key
-        params[:expression_attribute_values][':sk_val'] = sort_value
-      end
+      key_condition = resolved_model.send(:build_sort_key_condition, sort_key, sort_value)
+      params[:key_condition_expression] += " AND #{key_condition[:expression]}"
+      params[:expression_attribute_names].merge!(key_condition[:names])
+      params[:expression_attribute_values].merge!(key_condition[:values])
     end
 
     def sort_fanout_results(items, sort_key)
@@ -1616,6 +1586,9 @@ module ActiveItem
         return ["NOT (#attr#{idx} IN (#{placeholders.join(', ')}))", { "#attr#{idx}" => dynamo_attr }, values]
       end
 
+      # NOT begins_with
+      return ["NOT begins_with(#attr#{idx}, :val#{idx})", { "#attr#{idx}" => dynamo_attr }, { ":val#{idx}" => val.prefix }] if val.is_a?(ActiveItem::BeginsWith)
+
       # Simple not equal
       ["#attr#{idx} <> :val#{idx}", { "#attr#{idx}" => dynamo_attr }, { ":val#{idx}" => val }]
     end

data/lib/active_item/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveItem
-  VERSION = '0.0.23'
+  VERSION = '0.0.24'
 end

data/lib/activeitem.rb

@@ -5,6 +5,7 @@ require_relative 'active_item/configuration'
 require_relative 'active_item/logging'
 require_relative 'active_item/errors'
 require_relative 'active_item/database_helpers'
+require_relative 'active_item/begins_with'
 require_relative 'active_item/query_helpers'
 require_relative 'active_item/relation'
 require_relative 'active_item/embedded_collection'
@@ -32,5 +33,10 @@ module ActiveItem
     def logger
       configuration.logger
     end
+
+    # Prefix match for `where`; see ActiveItem::BeginsWith.
+    def begins_with(prefix)
+      BeginsWith.new(prefix)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeitem
 version: !ruby/object:Gem::Version
-  version: 0.0.23
+  version: 0.0.24
 platform: ruby
 authors:
 - Andy Davis
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -157,6 +157,7 @@ files:
 - README.md
 - lib/active_item/associations.rb
 - lib/active_item/base.rb
+- lib/active_item/begins_with.rb
 - lib/active_item/composed_of.rb
 - lib/active_item/configuration.rb
 - lib/active_item/database_helpers.rb