familia 2.0.0.pre15 → 2.0.0.pre17

data/CHANGELOG.rst

@@ -12,6 +12,88 @@ 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
+========================
+
+Added
+-----
+
+- Added support for instance-scoped unique indexes via ``unique_index`` with ``within:`` parameter. Issue #128
+
+  Example: ``unique_index :badge_number, :badge_index, within: Company`` creates per-company unique badge lookups using HashKey DataType.
+
+Changed
+-------
+
+- **BREAKING**: Consolidated relationships API by replacing ``tracked_in`` and ``member_of`` with unified ``participates_in`` method. PR #110
+- **BREAKING**: Renamed ``context_class`` terminology to ``target_class`` throughout relationships module for clarity
+- **BREAKING**: Removed ``tracking.rb`` and ``membership.rb`` modules, merged functionality into ``participation.rb``
+- **BREAKING**: Updated method names and configuration keys to use ``target`` instead of ``context`` terminology
+- Added ``bidirectional`` parameter to ``participates_in`` to control generation of convenience methods (default: true)
+- Added support for different collection types (sorted_set, set, list) in unified ``participates_in`` API
+- Renamed ``class_tracked_in`` to ``class_participates_in`` for consistency
+
+- Renamed DataType classes to avoid Ruby namespace confusion: ``Familia::String`` → ``Familia::StringKey``, ``Familia::List`` → ``Familia::ListKey``
+- Added dual registration for both traditional and explicit method names (``string``/``stringkey``, ``list``/``listkey``)
+- Updated ``Counter`` and ``Lock`` to inherit from ``StringKey`` instead of ``String``
+
+- **BREAKING:** Renamed indexing API methods for clarity. Issue #128
+
+  - ``class_indexed_by`` → ``unique_index`` (1:1 field-to-object mapping via HashKey)
+  - ``indexed_by`` → ``multi_index`` (1:many field-to-objects mapping via UnsortedSet)
+  - Parameter ``target:`` → ``within:`` for consistency across both index types
+
+- **BREAKING:** Changed ``multi_index`` to use ``UnsortedSet`` instead of ``SortedSet``. Issue #128
+
+  Multi-value indexes no longer include temporal scoring. This aligns with the design philosophy that indexing is for finding objects by attribute, not ordering them. Sort results in Ruby when needed: ``employees.sort_by(&:hire_date)``
+
+Documentation
+-------------
+
+- Updated overview documentation to explain dual naming system and namespace safety benefits
+- Enhanced examples to demonstrate both traditional and explicit DataType method naming
+
+- Updated inline module documentation
+    - ``Familia::Features::Relationships::Indexing`` with comprehensive examples, terminology guide, and design philosophy.
+    - ``Familia::Features::Relationships::Participation`` to clarify differences from indexing module.
+
+AI Assistance
+-------------
+
+- Comprehensive analysis of existing ``tracked_in`` and ``member_of`` implementations
+- Design and implementation of unified ``participates_in`` API integrating both functionalities
+- Systematic refactoring of codebase terminology from context to target
+- Complete test suite updates to verify API consolidation and new functionality
+
+- DataType class renaming and dual registration system implementation designed and developed with Claude Code assistance
+- All test updates and documentation enhancements created with AI support
+
+- Architecture design, implementation, test updates, and documentation for indexing API refactoring completed with Claude Code assistance. Issue #128
+
 .. _changelog-2.0.0.pre14:
 
 2.0.0.pre14 — 2025-09-08
@@ -293,7 +375,7 @@ Fixed
    (e.g., ``find_by_email``) would fail to correctly instantiate objects
    from the index, returning partially-formed objects.
 
--  Refactored connection handling to properly cache and reuse Redis
+-  Refactored connection handling to properly cache and reuse Valkey/Redis
    connections. This eliminates repetitive “Overriding existing
    connection” warnings and improves performance.
 
@@ -342,9 +424,9 @@ Changed
 
 -  **BREAKING**: ``tracked_in :global, collection`` syntax now raises
    ArgumentError - use ``class_tracked_in collection`` instead
--  **BREAKING**: ``indexed_by field, index, context: :global`` syntax
+-  **BREAKING**: ``indexed_by field, index, target: :global`` syntax
    replaced with ``class_indexed_by field, index``
--  **BREAKING**: ``indexed_by field, index, context: SomeClass`` syntax
+-  **BREAKING**: ``indexed_by field, index, target: SomeClass`` syntax
    replaced with ``indexed_by field, index, parent: SomeClass``
 -  Relationships API now provides consistent parameter naming across all
    relationship types
@@ -498,7 +580,7 @@ Added
 ~~~~~
 
 -  Complete API redesign for clarity and modern Ruby conventions
--  Valkey compatibility alongside traditional Redis support
+-  Valkey compatibility alongside traditional Valkey/Redis support
 -  Ruby 3.4+ modernization with fiber and thread safety improvements
 -  Connection pooling foundation with provider pattern architecture
 

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, Set, SortedSet, HashKey implementations
+   - Provides String, 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
@@ -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

@@ -5,21 +5,22 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  gem 'tryouts', '~> 3.6.0', require: false
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'
   gem 'stackprof'
+  gem 'timecop', require: false
+  gem 'tryouts', '~> 3.6.0', require: false
 end
 
 group :development, :test do
-  # byebug only works with MRI
-  gem 'byebug', '~> 11.0', require: false if RUBY_ENGINE == 'ruby'
+  gem 'debug', require: false
   gem 'irb', '~> 1.15.2', require: false
-  gem 'kramdown', require: false # Required for YARD markdown processing
-  gem 'pry-byebug', '~> 3.10.1', require: false if RUBY_ENGINE == 'ruby'
+  gem 'redcarpet', require: false
+  gem 'reek', require: false
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
+  gem 'solargraph', require: false
   gem 'yard', '~> 0.9', require: false
 end
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre15)
+    familia (2.0.0.pre17)
       benchmark (~> 0.4)
       connection_pool (~> 2.5)
       csv (~> 3.3)
@@ -15,16 +15,47 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    backport (1.2.0)
     base64 (0.3.0)
     benchmark (0.4.1)
     bigdecimal (3.2.3)
-    byebug (11.1.3)
-    coderay (1.1.3)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
     csv (3.3.5)
     date (3.4.1)
+    debug (1.11.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
     diff-lcs (1.6.2)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.14.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.5)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
     erb (5.0.2)
     ffi (1.17.2)
     ffi (1.17.2-arm64-darwin)
@@ -33,20 +64,29 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.13.0)
+    jaro_winkler (1.6.1)
+    json (2.15.0)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    method_source (1.1.0)
+    mini_portile2 (2.8.9)
     minitest (5.25.5)
+    nokogiri (1.18.10)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm64-darwin)
+      racc (~> 1.4)
+    observer (0.1.2)
     oj (3.16.11)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
     parallel (1.27.0)
-    parser (3.3.8.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
@@ -54,13 +94,7 @@ GEM
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.4.0)
-    pry (0.14.2)
-      coderay (~> 1.1)
-      method_source (~> 1.0)
-    pry-byebug (3.10.1)
-      byebug (~> 11.0)
-      pry (>= 0.13, < 0.15)
+    prism (1.5.1)
     psych (5.2.6)
       date
       stringio
@@ -68,16 +102,27 @@ GEM
     rainbow (3.1.1)
     rbnacl (7.1.2)
       ffi (~> 1)
+    rbs (3.9.5)
+      logger
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
+    redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
     redis-client (0.25.1)
       connection_pool
-    regexp_parser (2.10.0)
+    reek (6.5.0)
+      dry-schema (~> 1.13)
+      logger (~> 1.6)
+      parser (~> 3.3.0)
+      rainbow (>= 2.0, < 4.0)
+      rexml (~> 3.1)
+    regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
+    reverse_markdown (3.0.0)
+      nokogiri
     rexml (3.4.1)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
@@ -92,7 +137,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.4)
-    rubocop (1.78.0)
+    rubocop (1.81.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -100,10 +145,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.45.1, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.25.0)
@@ -117,8 +162,32 @@ GEM
     ruby-prof (1.7.2)
       base64
     ruby-progressbar (1.13.0)
+    solargraph (0.57.0)
+      backport (~> 1.2)
+      benchmark (~> 0.4)
+      bundler (~> 2.0)
+      diff-lcs (~> 1.4)
+      jaro_winkler (~> 1.6, >= 1.6.1)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      logger (~> 1.6)
+      observer (~> 0.1)
+      ostruct (~> 0.6)
+      parser (~> 3.0)
+      prism (~> 1.4)
+      rbs (>= 3.6.1, <= 4.0.0.dev.4)
+      reverse_markdown (~> 3.0)
+      rubocop (~> 1.76)
+      thor (~> 1.0)
+      tilt (~> 2.0)
+      yard (~> 0.9, >= 0.9.24)
+      yard-activesupport-concern (~> 0.0)
+      yard-solargraph (~> 0.1)
     stackprof (0.2.27)
     stringio (3.1.7)
+    thor (1.4.0)
+    tilt (2.6.1)
+    timecop (0.9.10)
     tryouts (3.6.0)
       concurrent-ruby (~> 1.0)
       irb
@@ -131,29 +200,36 @@ GEM
     tty-color (0.6.0)
     tty-cursor (0.7.1)
     tty-screen (0.8.2)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
     uri-valkey (1.4.0)
     yard (0.9.37)
+    yard-activesupport-concern (0.0.1)
+      yard (>= 0.8)
+    yard-solargraph (0.1.0)
+      yard (~> 0.9)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-24
   ruby
 
 DEPENDENCIES
-  byebug (~> 11.0)
   concurrent-ruby (~> 1.3.5)
+  debug
   familia!
   irb (~> 1.15.2)
-  kramdown
-  pry-byebug (~> 3.10.1)
   rbnacl (~> 7.1, >= 7.1.1)
+  redcarpet
+  reek
   rubocop
   rubocop-performance
   rubocop-thread_safety
   ruby-prof
+  solargraph
   stackprof
+  timecop
   tryouts (~> 3.6.0)
   yard (~> 0.9)
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2010-2024 Delano Mandelbaum
+Copyright (c) 2010-ongoing delano, contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal