familia 2.0.0.pre16 → 2.0.0.pre17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebaf394ebbccf9d096e87da84c693040c71d963860002a9d970d9b04edc11b6c
-  data.tar.gz: 4862991d1b2a1538876089030657986eb1b56f5551c7e5e9978a1009c77e86f9
+  metadata.gz: e760a3ff094446126c56a0c2b76fd5bed0f6ff64d8eed89580e19d98a5a9ba66
+  data.tar.gz: 74545b0bbb8c89b06ffd385c1448a95a7808b168686a955155a004b91160dafa
 SHA512:
-  metadata.gz: 533af9a33a115e8a59c87ae35e5b82401e1d72edbe43fd4a2963a3ca25a2c1ac259e5aaf02e68945d9d2f576393c6f77e9843ec87c4ed92696ca41d0b06e4d4c
-  data.tar.gz: b74dca7e415cbd0d6933beb77185e7738d33b3c10a704569120892fa9062fe92874fe2b879439f8d9508b8d02ba0e8154c79cb1546b029ac9e6bbdde442fd5e1
+  metadata.gz: cd9cd6c374f24859279125ef05199b0dfdac51f7cccdf2bcdf0489c7cca5126ac03d7cab1d54aa8021ce38b286203212514b2b412322ea151b8957fa16c9b445
+  data.tar.gz: 3e44e06249e6daf715ce09b02643b8faf153c85fc2d8451d4cf56d77c5115e5e5fdb1b752acef3f1fdd46f7b7eb7f019213f22850ffe728ec51a05d98ecc5528

data/.github/workflows/ci.yml

@@ -35,8 +35,8 @@ jobs:
           --health-retries 5
         ports:
           # https://docs.github.com/en/actions/using-containerized-services/creating-redis-service-containers#running-jobs-in-containers
-          # Maps port 6379 on service container to the host
-          - 6379:6379
+          # Maps port 6379 on service container to 2525 on the host
+          - 2525:6379
 
     steps:
       - uses: actions/checkout@v4

data/.github/workflows/{code-smellage.yml → code-smells.yml}

@@ -1,4 +1,6 @@
-name: Any Code Smellage?
+# ..github/workflows/code-smells.yml
+---
+name: Code Smells
 
 on:
   pull_request:
@@ -81,65 +83,3 @@ jobs:
             reek-report.html
           if-no-files-found: ignore
           retention-days: 30
-
-  # Add other code quality checks here
-  additional-quality-checks:
-    name: Additional Quality Checks
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.4
-          bundler-cache: true
-
-      - name: Configure Bundler for secure gem installation
-        run: |
-          bundle config set --local path 'vendor/bundle'
-          bundle config set --local deployment 'false'
-
-      - name: Install dependencies
-        run: bundle install --jobs 4 --retry 3
-
-      - name: Check for TODO/FIXME comments
-        run: |
-          echo "=== Scanning for TODO/FIXME comments ==="
-          echo "This helps track technical debt and action items."
-          echo ""
-
-          # Find TODO/FIXME comments (excluding this workflow file)
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            xargs grep -Hn -i -E "(TODO|FIXME|HACK|XXX|NOTE):" 2>/dev/null | \
-            head -20 || echo "No TODO/FIXME comments found"
-        continue-on-error: true
-
-      - name: Check Ruby file syntax
-        run: |
-          echo "=== Checking Ruby syntax ==="
-          echo "Validates that all Ruby files have correct syntax."
-          echo ""
-
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            while read -r file; do
-              if ! ruby -c "$file" > /dev/null 2>&1; then
-                echo "Syntax error in: $file"
-                ruby -c "$file"
-              fi
-            done
-        continue-on-error: true
-
-      - name: Check for long lines
-        run: |
-          echo "=== Checking for long lines (>120 characters) ==="
-          echo "Identifies potentially hard-to-read code lines."
-          echo ""
-
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            xargs grep -Hn "^.\{121,\}$" | \
-            head -10 || echo "No overly long lines found"
-        continue-on-error: true

data/.gitignore

@@ -14,7 +14,9 @@
 *.log
 *.txt
 .ruby-version
+dump.rdb
 appendonlydir
+data
 log
 tmp
 vendor

data/.rubocop.yml

@@ -124,6 +124,9 @@ Style/NegatedIfElseCondition:
 Naming/AsciiIdentifiers:
   Enabled: false
 
+Naming/PredicateMethod:
+  Enabled: false
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: single_quotes
@@ -135,6 +138,9 @@ Style/FrozenStringLiteralComment:
 Naming/MemoizedInstanceVariableName:
   Enabled: false
 
+ThreadSafety/ClassAndModuleAttributes:
+  Enabled: false
+
 ThreadSafety/ClassInstanceVariable:
   Enabled: false
 

data/CHANGELOG.rst

@@ -12,6 +12,28 @@ Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre17:
+
+2.0.0.pre17 — 2025-10-03
+========================
+
+Added
+-----
+
+- **SortedSet#add**: Full ZADD option support (NX, XX, GT, LT, CH) for atomic conditional operations and accurate change tracking. This enables proper index management with timestamp preservation, update-only operations, conditional score updates, and analytics tracking. Closes issue #135.
+
+Fixed
+-----
+
+- Restored objid provenance tracking when loading objects from Redis. The ``ObjectIdentifier`` feature now infers the generator type (:uuid_v7, :uuid_v4, :hex) from the objid format, enabling dependent features like ``ExternalIdentifier`` to derive external identifiers from loaded objects. PR #131
+
+AI Assistance
+-------------
+
+- Claude Code assisted with implementing the ``infer_objid_generator`` method and updating the setter logic in ``lib/familia/features/object_identifier.rb``.
+
+- Claude Code assisted with Redis ZADD option semantics research, mutual exclusivity validation design, comprehensive test case matrix creation (50+ test cases), and YAML documentation examples.
+
 .. _changelog-2.0.0.pre16:
 
 2.0.0.pre16 — 2025-09-30

data/CLAUDE.md

@@ -92,6 +92,44 @@ Familia uses a modular feature system where features are mixed into classes:
 
 **Inheritance Chain**: `MyClass < Familia::Horreum` automatically extends `ClassMethods` and `Features`
 
+**Common Pitfall: Overriding initialize**
+
+⚠️ **Do NOT override `initialize` without calling `super`** - this breaks related field initialization.
+
+**Bad - will cause crashes:**
+```ruby
+class User < Familia::Horreum
+  def initialize(email)
+    @email = email  # Missing super! Related fields won't work
+  end
+end
+```
+
+**Good - use the `init` hook instead:**
+```ruby
+class User < Familia::Horreum
+  def init(email = nil)
+    @email = email  # Called after super, related fields work
+  end
+end
+```
+
+**Good - call super explicitly:**
+```ruby
+class User < Familia::Horreum
+  def initialize(email = nil, **kwargs)
+    super(**kwargs)  # ✓ Related fields initialized
+    @email = email
+  end
+end
+```
+
+**Why this matters**: Familia's `initialize` method calls `initialize_relatives` to set up DataType objects (lists, sets, etc.). Without calling `super`, these objects remain nil and you'll get helpful errors pointing to the missing super call.
+
+**When to use each approach:**
+- **Use `init` hook** (preferred): For simple initialization logic that doesn't need to intercept constructor arguments. The `init` method is called automatically after `super` with the same arguments passed to `new`.
+- **Use explicit `super`**: When you need full control over initialization order or need to transform arguments before passing to parent. Remember to pass `**kwargs` to preserve keyword argument handling.
+
 **DataType Definition**: Use class methods to define keystore database-backed attributes:
 ```ruby
 class User < Familia::Horreum

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre16)
+    familia (2.0.0.pre17)
       benchmark (~> 0.4)
       connection_pool (~> 2.5)
       csv (~> 3.3)

data/docs/archive/FAMILIA_TECHNICAL.md

@@ -722,7 +722,7 @@ require 'familia'
 
 # Use separate Valkey/Redis database for tests
 Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:6379/15')
+  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:2525/3')
 end
 
 module TestHelpers

data/docs/overview.md

@@ -708,7 +708,7 @@ when 'production'
 when 'development'
   Familia.uri = 'redis://localhost:6379/0'
 when 'test'
-  Familia.uri = 'redis://localhost:6379/15'
+  Familia.uri = 'redis://localhost:2525/3'
 end
 ```
 
@@ -868,7 +868,7 @@ Familia.redis.keys('*')  # List all keys (use carefully in production)
 require 'familia'
 
 # Use separate test database
-Familia.uri = 'redis://localhost:6379/15'
+Familia.uri = 'redis://localhost:2525/3'
 
 # Setup encryption for tests
 test_keys = {

data/docs/reference/api-technical.md

@@ -1167,7 +1167,7 @@ require 'familia'
 
 # Use separate Valkey/Redis database for tests
 Familia.configure do |config|
-  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:6379/15')
+  config.redis_uri = ENV.fetch('REDIS_TEST_URI', 'redis://localhost:2525/3')
 end
 
 module TestHelpers

data/examples/encrypted_fields.rb

@@ -10,7 +10,7 @@ $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'familia'
 
 # Configure connection
-Familia.uri = 'redis://localhost:6379/15'
+Familia.uri = 'redis://localhost:2525/3'
 
 puts '=== Encrypted Fields Feature Examples ==='
 puts

data/examples/safe_dump.rb

@@ -10,7 +10,7 @@ $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'familia'
 
 # Configure connection
-Familia.uri = 'redis://localhost:6379/15'
+Familia.uri = 'redis://localhost:2525/3'
 
 puts '=== SafeDump Feature Examples ==='
 puts

data/lib/familia/base.rb

@@ -31,14 +31,15 @@ module Familia
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
 
-      def add_feature(klass, feature_name, depends_on: [])
+      def add_feature(klass, feature_name, depends_on: [], field_group: nil)
         @features_available ||= {}
         Familia.trace :ADD_FEATURE, klass, feature_name if Familia.debug?
 
         # Create field definition object
         feature_def = FeatureDefinition.new(
           name: feature_name,
-          depends_on: depends_on
+          depends_on: depends_on,
+          field_group: field_group
         )
 
         # Track field definitions after defining field methods
@@ -112,14 +113,15 @@ module Familia
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
 
-      def add_feature(klass, feature_name, depends_on: [])
+      def add_feature(klass, feature_name, depends_on: [], field_group: nil)
         @features_available ||= {}
         Familia.trace :ADD_FEATURE, klass, feature_name if Familia.debug?
 
         # Create field definition object
         feature_def = FeatureDefinition.new(
           name: feature_name,
-          depends_on: depends_on
+          depends_on: depends_on,
+          field_group: field_group
         )
 
         # Track field definitions after defining field methods

data/lib/familia/data_type/class_methods.rb

@@ -0,0 +1,63 @@
+# lib/familia/data_type/definition.rb
+
+module Familia
+  class DataType
+    # ClassMethods - Class-level DSL methods for defining DataType behavior
+    #
+    # This module is extended into classes that inherit from Familia::DataType,
+    # providing class methods for type registration, configuration, and inheritance.
+    #
+    # Key features:
+    # * Type registration system for creating DataType subclasses
+    # * Database and connection configuration
+    # * Inheritance hooks for propagating settings
+    # * Option validation and filtering
+    #
+    module ClassMethods
+      attr_accessor :parent, :suffix, :prefix, :uri
+      attr_writer :logical_database
+
+      # To be called inside every class that inherits DataType
+      # +methname+ is the term used for the class and instance methods
+      # that are created for the given +klass+ (e.g. set, list, etc)
+      def register(klass, methname)
+        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}" if Familia.debug?
+
+        @registered_types[methname] = klass
+      end
+
+      # Get the registered type class from a given method name
+      # +methname+ is the method name used to register the class (e.g. :set, :list, etc)
+      # Returns the registered class or nil if not found
+      def registered_type(methname)
+        @registered_types[methname]
+      end
+
+      def logical_database(val = nil)
+        @logical_database = val unless val.nil?
+        @logical_database || parent&.logical_database
+      end
+
+      def uri(val = nil)
+        @uri = val unless val.nil?
+        @uri || (parent ? parent.uri : Familia.uri)
+      end
+
+      def inherited(obj)
+        Familia.trace :DATATYPE, nil, "#{obj} is my kinda type" if Familia.debug?
+        obj.logical_database = logical_database
+        obj.default_expiration = default_expiration # method added via Features::Expiration
+        obj.uri = uri
+        super
+      end
+
+      def valid_keys_only(opts)
+        opts.slice(*DataType.valid_options)
+      end
+
+      def relations?
+        @has_related_fields ||= false
+      end
+    end
+  end
+end

data/lib/familia/data_type/connection.rb

@@ -0,0 +1,83 @@
+# lib/familia/data_type/connection.rb
+
+module Familia
+  class DataType
+    # Connection - Instance-level connection and key generation methods
+    #
+    # This module provides instance methods for database connection resolution
+    # and Redis key generation for DataType objects.
+    #
+    # Key features:
+    # * Database connection resolution with Chain of Responsibility pattern
+    # * Redis key generation based on parent context
+    # * Direct database access for advanced operations
+    #
+    module Connection
+      # TODO: Replace with Chain of Responsibility pattern
+      def dbclient
+        return Fiber[:familia_transaction] if Fiber[:familia_transaction]
+        return @dbclient if @dbclient
+
+        # Delegate to parent if present, otherwise fall back to Familia
+        parent ? parent.dbclient : Familia.dbclient(opts[:logical_database])
+      end
+
+      # Produces the full dbkey for this object.
+      #
+      # @return [String] The full dbkey.
+      #
+      # This method determines the appropriate dbkey based on the context of the DataType object:
+      #
+      # 1. If a hardcoded key is set in the options, it returns that key.
+      # 2. For instance-level DataType objects, it uses the parent instance's dbkey method.
+      # 3. For class-level DataType objects, it uses the parent class's dbkey method.
+      # 4. For standalone DataType objects, it uses the keystring as the full dbkey.
+      #
+      # For class-level DataType objects (parent_class? == true):
+      # - The suffix is optional and used to differentiate between different types of objects.
+      # - If no suffix is provided, the class's default suffix is used (via the self.suffix method).
+      # - If a nil suffix is explicitly passed, it won't appear in the resulting dbkey.
+      # - Passing nil as the suffix is how class-level DataType objects are created without
+      #   the global default 'object' suffix.
+      #
+      # @example Instance-level DataType
+      #   user_instance.some_datatype.dbkey  # => "user:123:some_datatype"
+      #
+      # @example Class-level DataType
+      #   User.some_datatype.dbkey  # => "user:some_datatype"
+      #
+      # @example Standalone DataType
+      #   DataType.new("mykey").dbkey  # => "mykey"
+      #
+      # @example Class-level DataType with explicit nil suffix
+      #   User.dbkey("123", nil)  # => "user:123"
+      #
+      def dbkey
+        # Return the hardcoded key if it's set. This is useful for
+        # support legacy keys that aren't derived in the same way.
+        return opts[:dbkey] if opts[:dbkey]
+
+        if parent_instance?
+          # This is an instance-level datatype object so the parent instance's
+          # dbkey method is defined in Familia::Horreum::InstanceMethods.
+          parent.dbkey(keystring)
+        elsif parent_class?
+          # This is a class-level datatype object so the parent class' dbkey
+          # method is defined in Familia::Horreum::DefinitionMethods.
+          parent.dbkey(keystring, nil)
+        else
+          # This is a standalone DataType object where it's keystring
+          # is the full database key (dbkey).
+          keystring
+        end
+      end
+
+      # Provides a structured way to "gear down" to run db commands that are
+      # not implemented in our DataType classes since we intentionally don't
+      # have a method_missing method.
+      def direct_access
+        yield(dbclient, dbkey)
+      end
+    end
+  end
+end

data/lib/familia/data_type/settings.rb

@@ -0,0 +1,96 @@
+# lib/familia/data_type/settings.rb
+
+module Familia
+  class DataType
+    # Settings - Instance-level configuration and introspection methods
+    #
+    # This module provides instance methods for accessing and managing
+    # DataType object configuration, parent relationships, and serialization.
+    #
+    # Key features:
+    # * Parent object relationship management
+    # * URI and database configuration
+    # * Serialization method delegation
+    # * Type introspection
+    #
+    module Settings
+      attr_reader :keystring, :opts, :logical_database
+      attr_reader :uri
+
+      alias url uri
+
+      def class?
+        !@opts[:class].to_s.empty? && @opts[:class].is_a?(Familia)
+      end
+
+      def parent_instance?
+        parent&.is_a?(Horreum::ParentDefinition)
+      end
+
+      def parent_class?
+        parent.is_a?(Class) && parent.ancestors.include?(Familia::Horreum)
+      end
+
+      def parent?
+        parent_class? || parent_instance?
+      end
+
+      def parent
+        # Return cached ParentDefinition if available
+        return @parent if @parent
+
+        # Return class-level parent if no instance parent
+        return self.class.parent unless @parent_ref
+
+        # Create ParentDefinition dynamically from stored reference.
+        # This ensures we get the current identifier value (available after initialization)
+        # rather than a stale nil value from initialization time. Cannot cache due to frozen object.
+        Horreum::ParentDefinition.from_parent(@parent_ref)
+      end
+
+      def parent=(value)
+        case value
+        when Horreum::ParentDefinition
+          @parent = value
+        when nil
+          @parent = nil
+          @parent_ref = nil
+        else
+          # Store parent instance reference for lazy ParentDefinition creation.
+          # During initialization, the parent's identifier may not be available yet,
+          # so we defer ParentDefinition creation until first access for memory efficiency.
+          # Note: @parent_ref is not cleared after use because DataType objects are frozen.
+          @parent_ref = value
+          @parent = nil  # Will be created dynamically in parent method
+        end
+      end
+
+      def uri
+        # Return explicit instance URI if set
+        return @uri if @uri
+
+        # If we have a parent with logical_database, build URI with that database
+        if parent && parent.respond_to?(:logical_database) && parent.logical_database
+          new_uri = (self.class.uri || Familia.uri).dup
+          new_uri.db = parent.logical_database
+          new_uri
+        else
+          # Fall back to class-level URI or global Familia.uri
+          self.class.uri || Familia.uri
+        end
+      end
+
+      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/hashkey.rb

@@ -95,7 +95,8 @@ module Familia
     def remove_field(field)
       dbclient.hdel dbkey, field.to_s
     end
-    alias remove remove_field # deprecated
+    alias remove remove_field
+    alias remove_element remove_field
 
     def increment(field, by = 1)
       dbclient.hincrby(dbkey, field.to_s, by).to_i