activeitem 0.0.22 → 0.0.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7d5990fc9c0532dc9a65f803bd9886c1769dc2b4c3071fd4748c079fa7559b3
-  data.tar.gz: 1c480246c6a898502eacedda1b456e003f54910a3f8562893cc5c070c06f168e
+  metadata.gz: 296b80f6ec0f16823c99df6d3a041fe16d55eab4ce59118d95081566f13e01d4
+  data.tar.gz: 8ec0e73b20698346c67f96075c0ccc3070f2f6232c1e1b3607a61424c1a19f8b
 SHA512:
-  metadata.gz: db67b991fe6c8c9ed9ce18a362dc15dfd9f1b46c63ed20a49e8b1f82bf0bb2dfe3738b1e2f7d7b29a31396e61d40ee3e6d528393b01a93a92bf81c2e9d9f234b
-  data.tar.gz: dc5a3c76df184f02bf6fa4f0cd040e9a98e42729326f35243b198fc2d7c8ae4e4a86429bdc457be7f7e9198892ba93aaddf5a4d5650806afcba6cb528d6d54e7
+  metadata.gz: 8b5d8087d0cffede8296535868978d6dd24cddc70d1f6a1ba0741db31d5fc46caaea9635791f8984166aa8de92bfb50db000ecc935df4fe6498ecc2456fc1029
+  data.tar.gz: ef5ca8b2bb01a83a5673d0181d13627d5eb0b8bb01612f6e6ef146c5e4eb669cfd2ef0936c1aa09b15e6a5eed2367d7b1adb3c844c7e8aa4c72e7dc600201624

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # 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
+
+- **`read_attribute` / `write_attribute`** — ActiveItem now exposes the same attribute primitives as ActiveRecord. `write_attribute(:name, value)` records the change for dirty tracking; `read_attribute(:name)` returns the current value. Custom readers/writers can route through these instead of touching the ivar directly.
+
+### Fixed
+
+- **Custom attribute writers now persist on update, Rails-style** — Overriding a generated writer to coerce or normalize a value no longer silently drops the change. Generated readers/writers are now defined in an included module (like Rails' `GeneratedAttributeMethods`), so a hand-written `def foo=` can call `super` and get dirty tracking for free. Previously, a custom writer that assigned `@foo` directly left the attribute out of the changeset — `save` returned `true` with no error, but the update wrote nothing. Both `super` and `write_attribute` are now supported.
+
+  ```ruby
+  class Article < ActiveItem::Base
+    attr_accessor :tags, :payload
+
+    # Coerce to an Array, Rails-style: override and call super.
+    def tags=(value)
+      super(Array(value))
+    end
+
+    # Or be explicit with write_attribute.
+    def payload=(value)
+      write_attribute(:payload, value.is_a?(String) ? value : JSON.generate(value))
+    end
+  end
+  ```
+
 ## 0.0.22
 
 ### Changed

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
@@ -114,6 +126,38 @@ class Customer < ActiveItem::Base
 end
 ```
 
+### Custom Attribute Writers
+
+Like ActiveRecord, you can override a generated writer to coerce or normalize a
+value on assignment. Just route the assignment back through the generated
+writer — call `super`, or use `write_attribute`. Both record the change for
+dirty tracking, so `save` (and `update`) persist it. Assigning `@ivar` directly
+bypasses dirty tracking and the change is silently dropped on update.
+
+```ruby
+class Article < ActiveItem::Base
+  attr_accessor :tags, :payload
+
+  # Coerce to an Array, Rails-style: override and call super.
+  def tags=(value)
+    super(Array(value))
+  end
+
+  # Or be explicit with write_attribute.
+  def payload=(value)
+    write_attribute(:payload, value.is_a?(String) ? value : JSON.generate(value))
+  end
+end
+```
+
+`read_attribute(:name)` is available too, for custom readers:
+
+```ruby
+def display_name
+  read_attribute(:name).to_s.strip
+end
+```
+
 ## License
 
 MIT

data/lib/active_item/base.rb

@@ -100,15 +100,33 @@ module ActiveItem
 
           define_attribute_methods attr_name
 
-          define_method(attr_name) do
-            instance_variable_get("@#{attr_name}")
+          # Define the generated reader/writer in a dedicated module that is
+          # included into the model, rather than directly on the class. This
+          # mirrors Rails' GeneratedAttributeMethods: a hand-written
+          # `def foo=` on the model sits *above* the generated writer in the
+          # ancestor chain, so a custom writer can call `super` (or
+          # `write_attribute`) to get dirty tracking for free.
+          generated_attribute_methods.module_eval do
+            define_method(attr_name) do
+              read_attribute(attr_name)
+            end
+
+            define_method("#{attr_name}=") do |value|
+              write_attribute(attr_name, value)
+            end
           end
+        end
+      end
 
-          define_method("#{attr_name}=") do |value|
-            old_value = instance_variable_get("@#{attr_name}")
-            send("#{attr_name}_will_change!") if (old_value != value) && !changed_attributes.key?(attr_name)
-            instance_variable_set("@#{attr_name}", value)
-          end
+      # Per-class module that holds the generated attribute reader/writer
+      # methods. Included once, ahead of ActiveModel in the ancestor chain but
+      # behind the model class itself, so user-defined setters can `super`.
+      def generated_attribute_methods
+        @generated_attribute_methods ||= begin
+          mod = Module.new
+          include mod
+
+          mod
         end
       end
 
@@ -490,6 +508,50 @@ module ActiveItem
       end
     end
 
+    # Read the current value of an attribute by name.
+    #
+    # This is the Rails-like primitive that generated readers delegate to.
+    # Custom readers can call it (or `super`) instead of poking at the ivar
+    # directly.
+    #
+    #   def display_name
+    #     read_attribute(:name).to_s.strip
+    #   end
+    #
+    # @param attr_name [String, Symbol] the attribute name
+    # @return the attribute's current value
+    def read_attribute(attr_name)
+      instance_variable_get("@#{attr_name}")
+    end
+
+    # Write an attribute value, recording it for dirty tracking so `save`
+    # actually persists it.
+    #
+    # This is the single place dirty tracking happens for attributes, mirroring
+    # Rails' `write_attribute`. Generated writers delegate here, which means a
+    # custom writer gets dirty tracking for free by going through either
+    # `super` or `write_attribute` directly:
+    #
+    #   # coerce/normalize on assignment, Rails-style
+    #   def tags=(value)
+    #     super(Array(value))            # -> generated writer -> write_attribute
+    #   end
+    #
+    #   # or be explicit
+    #   def payload=(value)
+    #     write_attribute(:payload, value.is_a?(String) ? value : JSON.generate(value))
+    #   end
+    #
+    # @param attr_name [String, Symbol] the attribute name
+    # @param value the value to assign
+    # @return the assigned value
+    def write_attribute(attr_name, value)
+      attr_name = attr_name.to_s
+      old_value = instance_variable_get("@#{attr_name}")
+      mark_attribute_will_change(attr_name, old_value, value)
+      instance_variable_set("@#{attr_name}", value)
+    end
+
     def attribute_changed?(attr_name)
       super(attr_name.to_s)
     end
@@ -511,6 +573,18 @@ module ActiveItem
 
     private
 
+    # Record a pending change for dirty tracking. Guarded with `respond_to?`
+    # so it degrades gracefully for attributes that weren't declared via
+    # `attr_accessor` (and under test harnesses that stub the ORM), and skips
+    # re-recording an original value that's already been captured.
+    def mark_attribute_will_change(attr_name, old_value, new_value)
+      return if old_value == new_value
+      return if changed_attributes.key?(attr_name)
+      return unless respond_to?("#{attr_name}_will_change!", true)
+
+      send("#{attr_name}_will_change!")
+    end
+
     # Enroll this record's save operation in the current transaction.
     # Called when save is invoked inside a transaction block.
     def enroll_in_transaction

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.22'
+  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.22
+  version: 0.0.24
 platform: ruby
 authors:
 - Andy Davis
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 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