familia 2.0.0.pre24 → 2.0.0.pre25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b6118ccf4f7a1ed2da6b080a8e256088481ecd93d9f60378f2fca40fe5bb364
-  data.tar.gz: 1960335d0f688f6b9fb8c8a0ccfc8c4314b85ee36cf4dc56281c1e6d0642f455
+  metadata.gz: 99afa47f80c0cbf07cf0c1c88dbf2fc6d9f720641d9404efbb181c90dd83631b
+  data.tar.gz: 91ea00ff6aa997daa9781b75723e90bd77534bdf7d32f159f305d50e33e6a62e
 SHA512:
-  metadata.gz: 51a4ab15e2181939e0b2b43f440e2629f149b9e774c7061737812c39f8b722280b20c8468d0e41ae6045c08a1751a661865622e0277f252edbd79e12eedbd9bc
-  data.tar.gz: 3cebb9d48404ce9b3aaffc43d74d605dda64d90463fbc604c8b0ad2a53853132683bb8b39be24e905ab8b86d5d4736a36fee91dc1fe9cd57b9fc18fd10331265
+  metadata.gz: d2e0bdba2c70ee453af1cf7601930ce44d434a1219eca2ae03786c40d8cb5c02ad689e6e1850d31df6e1a9525fbcd8a10aa95b0202bd68b9873fcb4084e2e10f
+  data.tar.gz: 47d6c6c5c8e51184124532754caced75d0e3c6f5ceace675c9ed2164f61ffdcbcb77370c0759ed70cf70ea3edc7290247e69f6d5dfe4a6a6dbd94831879c6054

data/CHANGELOG.rst

@@ -7,6 +7,43 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre25:
+
+2.0.0.pre25 — 2026-01-08
+========================
+
+Added
+-----
+
+- Class-level multi-value indexing with ``multi_index :field, :index_name`` (``within: :class`` is now the default). Creates class methods like ``Model.find_all_by_field(value)`` and ``Model.sample_from_field(value, count)`` for grouping objects by field values at the class level.
+
+- New ``JsonStringKey`` DataType for type-preserving string storage. Unlike
+  ``StringKey`` which uses raw strings (for INCR/DECR support), ``JsonStringKey``
+  uses JSON serialization to preserve Ruby types (Integer, Float, Boolean, Hash,
+  Array) across the Redis storage boundary. Registered as ``:json_string`` and
+  ``:json_stringkey``, enabling DSL methods like ``json_string :metadata`` and
+  ``class_json_string :last_synced_at``.
+
+Changed
+-------
+
+- ``multi_index`` now defaults to ``within: :class`` instead of requiring a scope class. Existing instance-scoped indexes (``within: SomeClass``) continue to work unchanged.
+
+Removed
+-------
+
+- **BREAKING**: Removed ``dump_method`` and ``load_method`` configuration options
+  from ``Familia::Base``, ``Familia::Horreum``, and ``Familia::DataType``. JSON
+  serialization via ``to_json``/``from_json`` is now hard-coded for consistency
+  and type safety. Custom serialization methods are no longer supported.
+
+AI Assistance
+-------------
+
+- Claude Opus 4.5 assisted with design, implementation, and testing of serialization consistency, the JsonStringKey feature, and multi_index :class mode.
+- Gemini 3 Flash assisted with editing and trimming this section.
+
+
 .. _changelog-2.0.0.pre24:
 
 2.0.0.pre24 — 2026-01-07

data/CLAUDE.md

@@ -75,7 +75,7 @@ Add changelog fragment with each user-facing or documented change (optional but
 
 2. **`Familia::DataType`** - Base class for Valkey data type wrappers
    - Located in `lib/familia/data_type.rb`
-   - Provides String, List, UnsortedSet, SortedSet, HashKey implementations
+   - Provides String, JsonStringKey, List, UnsortedSet, SortedSet, HashKey implementations
    - Each type has its own class in `lib/familia/data_type/types/`
 
 3. **`Familia::Base`** - Common module for both Horreum and DataType

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre24)
+    familia (2.0.0.pre25)
       benchmark (~> 0.4)
       concurrent-ruby (~> 1.3)
       connection_pool (~> 2.5)

data/docs/guides/feature-relationships-indexing.md

@@ -16,7 +16,8 @@ Indexing creates fast lookups for finding objects by field values:
 |------|-------|----------|-----------|
 | `unique_index` | Class | Global unique fields | Redis HashKey |
 | `unique_index` | Instance | Parent-scoped unique | Redis HashKey |
-| `multi_index` | Instance | Non-unique groupings | Redis Set |
+| `multi_index` | Class (default) | Global non-unique groupings | Redis Set per value |
+| `multi_index` | Instance | Parent-scoped groupings | Redis Set per value |
 
 ## Class-Level Unique Indexing
 
@@ -96,9 +97,80 @@ company2.find_by_badge_number('12345')  # => emp2
 | `remove_from_company_badge_index(company)` | Remove from index |
 | `in_company_badge_index?(company)` | Check if indexed |
 
-## Multi-Value Indexing
+## Class-Level Multi-Value Indexing
 
-One-to-many mappings for non-unique field values:
+Class-level multi-value indexes group objects by field values at the class level. This is the default behavior when no `within:` parameter is specified.
+
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+  field :role
+
+  # Class-level multi_index (within: :class is the default)
+  multi_index :role, :role_index
+end
+
+# Create customers with various roles
+alice = Customer.create(custid: 'cust_001', role: 'admin')
+bob = Customer.create(custid: 'cust_002', role: 'user')
+charlie = Customer.create(custid: 'cust_003', role: 'admin')
+
+# Manually add to index (or use auto-indexing via save hooks)
+alice.add_to_class_role_index
+bob.add_to_class_role_index
+charlie.add_to_class_role_index
+
+# Query all customers with a specific role
+admins = Customer.find_all_by_role('admin')  # => [alice, charlie]
+users = Customer.find_all_by_role('user')    # => [bob]
+
+# Random sampling
+sample = Customer.sample_from_role('admin', 1)  # => [random admin]
+```
+
+### Redis Key Pattern
+
+Class-level multi-indexes use the pattern: `{classname}:{index_name}:{field_value}`
+
+```ruby
+Customer.role_index_for('admin').dbkey  # => "customer:role_index:admin"
+Customer.role_index_for('user').dbkey   # => "customer:role_index:user"
+```
+
+### Generated Class Methods
+
+| Method | Description |
+|--------|-------------|
+| `Customer.role_index_for(value)` | Factory returning `Familia::UnsortedSet` for the field value |
+| `Customer.find_all_by_role(value)` | Find all objects with that field value |
+| `Customer.sample_from_role(value, count)` | Random sample of objects |
+| `Customer.rebuild_role_index` | Rebuild the entire index from source data |
+
+### Generated Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `customer.add_to_class_role_index` | Add this object to its field value's index |
+| `customer.remove_from_class_role_index` | Remove this object from its field value's index |
+| `customer.update_in_class_role_index(old_value)` | Move object from old index to new index |
+
+### Update Operations
+
+When a field value changes, use the update method to atomically move the object between indexes:
+
+```ruby
+old_role = customer.role
+customer.role = 'superadmin'
+customer.update_in_class_role_index(old_role)
+
+# Customer is now in 'superadmin' index, removed from old 'admin' index
+Customer.find_all_by_role('superadmin')  # => includes customer
+Customer.find_all_by_role('admin')       # => no longer includes customer
+```
+
+## Instance-Scoped Multi-Value Indexing
+
+For indexes scoped to a parent object, use `within:` to specify the scope class. This allows the same field values across different parent contexts.
 
 ```ruby
 class Employee < Familia::Horreum
@@ -125,13 +197,22 @@ sales_team = company.find_all_by_department('sales')       # => [emp3]
 sample = company.sample_from_department('engineering', 1)  # => [random engineer]
 ```
 
-### Generated Methods
+### Generated Methods (Instance-Scoped)
+
+**On scope class (Company):**
+| Method | Description |
+|--------|-------------|
+| `company.dept_index_for(value)` | Factory returning UnsortedSet for value |
+| `company.find_all_by_department(dept)` | Find all in department |
+| `company.sample_from_department(dept, count)` | Random sample |
+| `company.rebuild_dept_index` | Rebuild index from participation |
 
-**On scope class:**
+**On indexed class (Employee):**
 | Method | Description |
 |--------|-------------|
-| `find_all_by_department(dept)` | Find all in department |
-| `sample_from_department(dept, count)` | Random sample |
+| `employee.add_to_company_dept_index(company)` | Add to company's index |
+| `employee.remove_from_company_dept_index(company)` | Remove from index |
+| `employee.update_in_company_dept_index(company, old_dept)` | Move between indexes |
 
 ## Advanced Patterns
 
@@ -189,18 +270,30 @@ todays_events = user.find_all_by_daily_partition(today)
 
 ### Class vs Instance Scoping
 
-**Class-level (`unique_index :email, :email_lookup`):**
+**Class-level unique (`unique_index :email, :email_lookup`):**
 - Automatic indexing on save/destroy
 - System-wide uniqueness
 - No parent context needed
 - Examples: emails, usernames, API keys
 
+**Class-level multi (`multi_index :role, :role_index`):**
+- Default behavior (no `within:` needed)
+- Groups all objects by field value at class level
+- Manual indexing via instance methods
+- Examples: roles, categories, statuses
+
 **Instance-scoped (`unique_index :badge, :badge_index, within: Company`):**
 - Manual indexing required
 - Unique within parent only
 - Requires parent context
 - Examples: employee IDs, project names per team
 
+**Instance-scoped multi (`multi_index :dept, :dept_index, within: Company`):**
+- Groups objects by field value within parent scope
+- Same field value allowed across different parents
+- Manual indexing with parent context
+- Examples: departments per company, tags per project
+
 ### Unique vs Multi Indexing
 
 **Unique index (`unique_index`):**
@@ -212,6 +305,7 @@ todays_events = user.find_all_by_daily_partition(today)
 - 1:many field-to-objects mapping
 - Returns array of objects
 - Allows duplicate values
+- Default: class-level scope (use `within:` for instance scope)
 
 ## Rebuilding Indexes
 
@@ -277,8 +371,9 @@ end
 | Type | Pattern | Example |
 |------|---------|---------|
 | Class unique | `{class}:{index_name}` | `user:email_lookup` |
+| Class multi | `{class}:{index_name}:{value}` | `customer:role_index:admin` |
 | Instance unique | `{scope}:{id}:{index_name}` | `company:123:badge_index` |
-| Multi-value | `{scope}:{id}:{index_name}:{value}` | `company:123:dept_index:engineering` |
+| Instance multi | `{scope}:{id}:{index_name}:{value}` | `company:123:dept_index:engineering` |
 
 ## Troubleshooting
 

data/docs/guides/feature-relationships-methods.md

@@ -134,7 +134,30 @@ end
 | `employee.remove_from_company_badge_index(company)` | Remove from index |
 | `employee.in_company_badge_index?(company)` | Check if indexed |
 
-### Multi-Value Index
+### Class-Level Multi-Value Index
+
+```ruby
+class Customer < Familia::Horreum
+  multi_index :role, :role_index  # within: :class is the default
+end
+```
+
+**Class methods on indexed class (Customer):**
+| Method | Description |
+|--------|-------------|
+| `Customer.role_index_for(value)` | Factory returning UnsortedSet for value |
+| `Customer.find_all_by_role(role)` | Find all with that role |
+| `Customer.sample_from_role(role, count)` | Random sample |
+| `Customer.rebuild_role_index` | Rebuild index from instances |
+
+**Instance methods on indexed class (Customer):**
+| Method | Description |
+|--------|-------------|
+| `customer.add_to_class_role_index` | Add to index |
+| `customer.remove_from_class_role_index` | Remove from index |
+| `customer.update_in_class_role_index(old_value)` | Move between indexes |
+
+### Instance-Scoped Multi-Value Index
 
 ```ruby
 class Employee < Familia::Horreum
@@ -145,14 +168,17 @@ end
 **Methods on scope class (Company):**
 | Method | Description |
 |--------|-------------|
+| `company.dept_index_for(value)` | Factory returning UnsortedSet for value |
 | `company.find_all_by_department(dept)` | Find all in department |
 | `company.sample_from_department(dept, count)` | Random sample |
+| `company.rebuild_dept_index` | Rebuild index from participation |
 
 **Methods on indexed class (Employee):**
 | Method | Description |
 |--------|-------------|
 | `employee.add_to_company_dept_index(company)` | Add to index |
 | `employee.remove_from_company_dept_index(company)` | Remove from index |
+| `employee.update_in_company_dept_index(company, old_dept)` | Move between indexes |
 
 ## Method Naming Patterns
 
@@ -165,8 +191,9 @@ end
 ### Indexing
 
 - **Class unique**: `find_by_{field}`, `index_{field}_for`, `unindex_{field}_for`
+- **Class multi**: `{Class}.find_all_by_{field}`, `{Class}.sample_from_{field}`, `{item}.add_to_class_{index}`
 - **Scoped unique**: `{scope}.find_by_{field}`, `{item}.add_to_{scope}_{index}`
-- **Multi-value**: `{scope}.find_all_by_{field}`, `{scope}.sample_from_{field}`
+- **Scoped multi**: `{scope}.find_all_by_{field}`, `{scope}.sample_from_{field}`, `{item}.add_to_{scope}_{index}`
 
 ## Common Usage Examples
 
@@ -206,15 +233,20 @@ customer.domains.range(0, 9)  # First 10
 ### Working with Indexes
 
 ```ruby
-# Automatic class-level indexing
+# Automatic class-level unique indexing
 user = User.create(email: 'alice@example.com')
 User.find_by_email('alice@example.com')  # => user
 
-# Manual scoped indexing
+# Class-level multi-value indexing
+customer.add_to_class_role_index
+Customer.find_all_by_role('admin')       # => [customer, ...]
+Customer.sample_from_role('admin', 2)    # => random sample
+
+# Manual scoped unique indexing
 employee.add_to_company_badge_index(company)
 company.find_by_badge_number('12345')    # => employee
 
-# Multi-value indexing
+# Scoped multi-value indexing
 employee.add_to_company_dept_index(company)
 engineers = company.find_all_by_department('engineering')
 ```

data/docs/overview.md

@@ -76,6 +76,10 @@ class Product < Familia::Horreum
   string :view_count, default: '0'
   # Usage: view_count.increment (atomic increment)
 
+  # JSON string fields (type-preserving storage)
+  json_string :last_synced_at, default: 0.0
+  # Usage: last_synced_at stores Float, retrieves Float (not String)
+
   # Lists (ordered, allows duplicates)
   list :categories
   # Usage: categories.push('fruit'), categories.pop
@@ -110,6 +114,10 @@ class Product < Familia::Horreum
   stringkey :description # Creates StringKey instance
   listkey :history       # Creates ListKey instance
 
+  # JSON string (type-preserving alternative to StringKey)
+  json_string :metadata  # Creates JsonStringKey instance
+  json_stringkey :config # Creates JsonStringKey instance
+
   # Both work identically - choose based on preference
   set :tags              # UnsortedSet (unchanged)
   sorted_set :ratings    # SortedSet (unchanged)
@@ -119,6 +127,7 @@ end
 # Access patterns are identical
 product.view_count.class        # => Familia::StringKey
 product.description.class       # => Familia::StringKey
+product.metadata.class          # => Familia::JsonStringKey
 product.categories.class        # => Familia::ListKey
 product.history.class           # => Familia::ListKey
 ```

data/lib/familia/base.rb

@@ -29,7 +29,6 @@ module Familia
     #
     module ClassMethods
       attr_reader :features_available, :feature_definitions
-      attr_accessor :dump_method, :load_method
 
       def add_feature(klass, feature_name, depends_on: [], field_group: nil)
         @features_available ||= {}
@@ -111,7 +110,6 @@ module Familia
     # Module-level methods for Familia::Base itself
     class << self
       attr_reader :features_available, :feature_definitions
-      attr_accessor :dump_method, :load_method
 
       def add_feature(klass, feature_name, depends_on: [], field_group: nil)
         @features_available ||= {}

data/lib/familia/data_type/serialization.rb

@@ -70,11 +70,10 @@ module Familia
       # @param values [Array<String>] The values to deserialize.
       # @return [Array<Object, nil>] Deserialized objects, including nil values.
       #
-      # @raise [Familia::Problem] If the specified class doesn't respond to the
-      #   load method.
+      # @raise [Familia::Problem] If the specified class doesn't respond to from_json.
       #
       # @note This method attempts to deserialize each value using the specified
-      #   class's load method. If deserialization fails for a value, it's
+      #   class's from_json method. If deserialization fails for a value, it's
       #   replaced with nil.
       #
       def deserialize_values_with_nil(*values)
@@ -83,20 +82,20 @@ module Familia
 
         # If a class option is specified, use class-based deserialization
         if @opts[:class]
-          unless @opts[:class].respond_to?(load_method)
-            raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
+          unless @opts[:class].respond_to?(:from_json)
+            raise Familia::Problem, "No such method: #{@opts[:class]}.from_json"
           end
 
           values.collect! do |obj|
             next if obj.nil?
 
-            val = @opts[:class].send load_method, obj
-            Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
+            val = @opts[:class].from_json(obj)
+            Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}.from_json" if val.nil?
 
             val
           rescue StandardError => e
-            Familia.info val
-            Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
+            Familia.info obj
+            Familia.info "Parse error for #{dbkey} (from_json): #{e.message}"
             Familia.info e.backtrace
             nil
           end

data/lib/familia/data_type/settings.rb

@@ -85,14 +85,6 @@ module Familia
       def uri=(value)
         @uri = value
       end
-
-      def dump_method
-        self.class.dump_method
-      end
-
-      def load_method
-        self.class.load_method
-      end
     end
   end
 end

data/lib/familia/data_type/types/json_stringkey.rb

@@ -0,0 +1,155 @@
+# lib/familia/data_type/types/json_stringkey.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  # JsonStringKey - A string DataType that uses JSON serialization for type preservation.
+  #
+  # Unlike StringKey which uses raw string serialization (to support Redis operations
+  # like INCR/DECR/APPEND), JsonStringKey uses the base DataType's JSON serialization
+  # to preserve Ruby types across the Redis storage boundary.
+  #
+  # @example Basic usage
+  #   class MyIndex < Familia::Horreum
+  #     class_json_string :last_synced_at, default: 0.0
+  #   end
+  #
+  #   MyIndex.last_synced_at = Time.now.to_f  # Stored as JSON number
+  #   MyIndex.last_synced_at  #=> 1704067200.123 (Float preserved)
+  #
+  # @example Type preservation
+  #   json_str.value = 42        # Stored in Redis as: 42 (JSON number)
+  #   json_str.value = true      # Stored in Redis as: true (JSON boolean)
+  #   json_str.value = [1, 2, 3] # Stored in Redis as: [1,2,3] (JSON array)
+  #
+  # @note This class intentionally does NOT include increment/decrement or other
+  #   raw string operations that are incompatible with JSON serialization.
+  #
+  # @note Performance: Each call to value, to_s, to_i, to_f makes a Redis
+  #   roundtrip. If you need the value multiple times and don't expect it to
+  #   change, store it in a local variable:
+  #
+  #   # Inefficient (3 Redis calls):
+  #   puts json_str.to_s
+  #   puts json_str.to_i
+  #   puts json_str.to_f
+  #
+  #   # Efficient (1 Redis call):
+  #   val = json_str.value
+  #   puts val.to_s
+  #   puts val.to_i
+  #   puts val.to_f
+  #
+  class JsonStringKey < DataType
+    # Initialization hook (required by DataType contract)
+    def init; end
+
+    # Returns the number of characters in the string representation of the value.
+    #
+    # @return [Integer] number of characters
+    #
+    def char_count
+      to_s&.size || 0
+    end
+    alias size char_count
+    alias length char_count
+
+    # Returns the current value stored at the key.
+    #
+    # If a default option was provided during initialization, the default
+    # is set via SETNX (set if not exists) before retrieval.
+    #
+    # @return [Object] the deserialized value, or the default if not set
+    #
+    def value
+      echo :value, Familia.pretty_stack(limit: 1) if Familia.debug
+      if @opts.key?(:default)
+        was_set = dbclient.setnx(dbkey, serialize_value(@opts[:default]))
+        update_expiration if was_set
+      end
+      deserialize_value dbclient.get(dbkey)
+    end
+    alias content value
+    alias get value
+
+    # Sets the value at the key.
+    #
+    # The value is JSON-serialized before storage, preserving its Ruby type.
+    #
+    # @param val [Object] the value to store
+    # @return [String] "OK" on success
+    #
+    def value=(val)
+      ret = dbclient.set(dbkey, serialize_value(val))
+      update_expiration
+      ret
+    end
+    alias replace value=
+    alias set value=
+
+    # Sets the value only if the key does not already exist.
+    #
+    # @param val [Object] the value to store
+    # @return [Boolean] true if the key was set, false if it already existed
+    #
+    def setnx(val)
+      ret = dbclient.setnx(dbkey, serialize_value(val))
+      update_expiration if ret
+      ret
+    end
+
+    # Deletes the key from the database.
+    #
+    # @return [Boolean] true if the key was deleted, false if it didn't exist
+    #
+    def del
+      ret = dbclient.del dbkey
+      ret.positive?
+    end
+
+    # Checks if the value is nil (key does not exist or has no value).
+    #
+    # @return [Boolean] true if the value is nil
+    #
+    def empty?
+      value.nil?
+    end
+
+    # Returns the string representation of the deserialized value.
+    #
+    # @return [String, nil] the deserialized value converted to string, or nil
+    #
+    def to_s
+      val = deserialize_value(dbclient.get(dbkey))
+      return nil if val.nil?
+
+      val.to_s
+    end
+
+    # Returns the integer representation of the deserialized value.
+    #
+    # @return [Integer, nil] the deserialized value converted to integer, or nil
+    #
+    def to_i
+      val = deserialize_value(dbclient.get(dbkey))
+      return nil if val.nil?
+
+      val.to_i
+    end
+
+    # Returns the float representation of the deserialized value.
+    #
+    # @return [Float, nil] the deserialized value converted to float, or nil
+    #
+    def to_f
+      val = deserialize_value(dbclient.get(dbkey))
+      return nil if val.nil?
+
+      val.to_f
+    end
+
+    Familia::DataType.register self, :json_string
+    Familia::DataType.register self, :json_stringkey
+    Familia::DataType.register self, :jsonkey
+  end
+end

data/lib/familia/data_type.rb

@@ -14,7 +14,7 @@ module Familia
   # DataType - Base class for Database data type wrappers
   #
   # This class provides common functionality for various Database data types
-  # such as String, List, UnsortedSet, SortedSet, and HashKey.
+  # such as String, JsonStringKey, List, UnsortedSet, SortedSet, and HashKey.
   #
   # @abstract Subclass and implement Database data type specific methods
   class DataType
@@ -41,9 +41,9 @@ module Familia
     #
     # Options:
     #
-    # :class => A class that responds to Familia.load_method and
-    # Familia.dump_method. These will be used when loading and
-    # saving data from/to the database to unmarshal/marshal the class.
+    # :class => A class that responds to from_json. This will be used
+    # when loading data from the database to unmarshal the class.
+    # JSON serialization is used for all data storage.
     #
     # :parent => The Familia object that this datatype object belongs
     # to. This can be a class that includes Familia or an instance.
@@ -88,4 +88,5 @@ module Familia
   require_relative 'data_type/types/sorted_set'
   require_relative 'data_type/types/hashkey'
   require_relative 'data_type/types/stringkey'
+  require_relative 'data_type/types/json_stringkey'
 end