familia 2.0.0.pre26 → 2.0.0

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

@@ -87,9 +87,113 @@ module Familia
     end
     alias remove remove_element # deprecated
 
-    def intersection *setkeys
-      # TODO
+    # Returns the intersection of this set with one or more other sets.
+    # @param other_sets [Array<UnsortedSet, String>] Other sets (as UnsortedSet instances or raw keys)
+    # @return [Array] Deserialized members present in all sets
+    def intersection(*other_sets)
+      keys = extract_keys(other_sets)
+      elements = dbclient.sinter(dbkey, *keys)
+      deserialize_values(*elements)
+    end
+    alias inter intersection
+
+    # Returns the union of this set with one or more other sets.
+    # @param other_sets [Array<UnsortedSet, String>] Other sets (as UnsortedSet instances or raw keys)
+    # @return [Array] Deserialized members present in any of the sets
+    def union(*other_sets)
+      keys = extract_keys(other_sets)
+      elements = dbclient.sunion(dbkey, *keys)
+      deserialize_values(*elements)
+    end
+
+    # Returns the difference of this set minus one or more other sets.
+    # @param other_sets [Array<UnsortedSet, String>] Other sets (as UnsortedSet instances or raw keys)
+    # @return [Array] Deserialized members present in this set but not in any other sets
+    def difference(*other_sets)
+      keys = extract_keys(other_sets)
+      elements = dbclient.sdiff(dbkey, *keys)
+      deserialize_values(*elements)
+    end
+    alias diff difference
+
+    # Checks membership for multiple values at once.
+    # @param values [Array] Values to check for membership
+    # @return [Array<Boolean>] Array of booleans indicating membership for each value
+    def member_any?(*values)
+      values = values.flatten
+      serialized = values.map { |v| serialize_value(v) }
+      dbclient.smismember(dbkey, *serialized)
+    end
+    alias members? member_any?
+
+    # Iterates over set members using cursor-based iteration.
+    # @param cursor [Integer] Starting cursor position (default: 0)
+    # @param match [String, nil] Optional pattern to filter members
+    # @param count [Integer, nil] Optional hint for number of elements to return per call
+    # @return [Array<Integer, Array>] Two-element array: [new_cursor, deserialized_members]
+    def scan(cursor = 0, match: nil, count: nil)
+      opts = {}
+      opts[:match] = match if match
+      opts[:count] = count if count
+
+      new_cursor, elements = dbclient.sscan(dbkey, cursor, **opts)
+      [new_cursor.to_i, deserialize_values(*elements)]
+    end
+
+    # Returns the cardinality of the intersection without retrieving members.
+    # More memory-efficient than intersection when only the count is needed.
+    # @param other_sets [Array<UnsortedSet, String>] Other sets (as UnsortedSet instances or raw keys)
+    # @param limit [Integer] Stop counting after reaching this limit (0 = no limit)
+    # @return [Integer] Number of elements in the intersection
+    def intercard(*other_sets, limit: 0)
+      keys = extract_keys(other_sets)
+      all_keys = [dbkey, *keys]
+      if limit.positive?
+        dbclient.sintercard(all_keys.size, *all_keys, limit: limit)
+      else
+        dbclient.sintercard(all_keys.size, *all_keys)
+      end
+    end
+    alias intersection_cardinality intercard
+
+    # Stores the intersection of this set with other sets into a destination key.
+    # @param destination [UnsortedSet, String] Destination set (as UnsortedSet instance or raw key)
+    # @param other_sets [Array<UnsortedSet, String>] Other sets to intersect with
+    # @return [Integer] Number of elements in the resulting set
+    def interstore(destination, *other_sets)
+      dest_key = extract_key(destination)
+      keys = extract_keys(other_sets)
+      result = dbclient.sinterstore(dest_key, dbkey, *keys)
+      update_expiration
+      result
+    end
+    alias intersection_store interstore
+
+    # Stores the union of this set with other sets into a destination key.
+    # @param destination [UnsortedSet, String] Destination set (as UnsortedSet instance or raw key)
+    # @param other_sets [Array<UnsortedSet, String>] Other sets to union with
+    # @return [Integer] Number of elements in the resulting set
+    def unionstore(destination, *other_sets)
+      dest_key = extract_key(destination)
+      keys = extract_keys(other_sets)
+      result = dbclient.sunionstore(dest_key, dbkey, *keys)
+      update_expiration
+      result
+    end
+    alias union_store unionstore
+
+    # Stores the difference of this set minus other sets into a destination key.
+    # @param destination [UnsortedSet, String] Destination set (as UnsortedSet instance or raw key)
+    # @param other_sets [Array<UnsortedSet, String>] Other sets to subtract
+    # @return [Integer] Number of elements in the resulting set
+    def diffstore(destination, *other_sets)
+      dest_key = extract_key(destination)
+      keys = extract_keys(other_sets)
+      result = dbclient.sdiffstore(dest_key, dbkey, *keys)
+      update_expiration
+      result
     end
+    alias difference_store diffstore
 
     def pop
       dbclient.spop dbkey
@@ -115,6 +219,22 @@ module Familia
     end
     alias random sampleraw
 
+    private
+
+    # Extracts the database key from a set reference.
+    # @param set_ref [UnsortedSet, String] An UnsortedSet instance or raw key string
+    # @return [String] The database key
+    def extract_key(set_ref)
+      set_ref.respond_to?(:dbkey) ? set_ref.dbkey : set_ref.to_s
+    end
+
+    # Extracts database keys from an array of set references.
+    # @param set_refs [Array<UnsortedSet, String>] Array of UnsortedSet instances or raw keys
+    # @return [Array<String>] Array of database keys
+    def extract_keys(set_refs)
+      set_refs.flatten.map { |s| extract_key(s) }
+    end
+
     Familia::DataType.register self, :set
     Familia::DataType.register self, :unsorted_set
   end

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre26' unless defined?(Familia::VERSION)
+  VERSION = '2.0.0' unless defined?(Familia::VERSION)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre26
+  version: 2.0.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -9,20 +9,6 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: benchmark
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -194,17 +180,6 @@ files:
 - docs/guides/thread-safety-monitoring.md
 - docs/guides/time-literals.md
 - docs/migrating/.gitignore
-- docs/migrating/v2.0.0-pre.md
-- docs/migrating/v2.0.0-pre11.md
-- docs/migrating/v2.0.0-pre12.md
-- docs/migrating/v2.0.0-pre13.md
-- docs/migrating/v2.0.0-pre14.md
-- docs/migrating/v2.0.0-pre18.md
-- docs/migrating/v2.0.0-pre19.md
-- docs/migrating/v2.0.0-pre22.md
-- docs/migrating/v2.0.0-pre5.md
-- docs/migrating/v2.0.0-pre6.md
-- docs/migrating/v2.0.0-pre7.md
 - docs/overview.md
 - docs/qodo-merge-compliance.md
 - docs/reference/api-technical.md
@@ -557,7 +532,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.6
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/docs/migrating/v2.0.0-pre.md

@@ -1,84 +0,0 @@
-# Migrating Guide: v1.x to v2.0.0-pre
-
-This guide covers migrating from Familia v1.x to the v2.0.0-pre foundation release.
-
-## Overview
-
-The v2.0.0-pre series represents a major modernization of Familia with:
-- Complete API redesign for clarity and consistency
-- Valkey compatibility alongside Valkey/Redis support
-- Ruby 3.4+ modernization with improved thread safety
-- New connection pooling architecture
-
-## Step-by-Step Migration
-
-### 1. Update Connection Configuration
-
-**Before (v1.x):**
-```ruby
-Familia.connect('redis://localhost:6379/0')
-```
-
-**After (v2.0.0-pre):**
-```ruby
-Familia.configure do |config|
-  config.redis_uri = 'redis://localhost:6379/0'
-  config.connection_pool = true
-end
-```
-
-### 2. Migrate Identifier Declarations
-
-**Before (v1.x):**
-```ruby
-class User < Familia::Base
-  identifier :user_id
-end
-```
-
-**After (v2.0.0-pre):**
-```ruby
-class User < Familia::Horreum
-  identifier_field :user_id
-end
-```
-
-### 3. Update Feature Activations
-
-**Before (v1.x):**
-```ruby
-class User < Familia::Base
-  include Familia::Features::Expiration
-end
-```
-
-**After (v2.0.0-pre):**
-```ruby
-class User < Familia::Horreum
-  feature :expiration
-end
-```
-
-### 4. Review Method Calls
-
-Several methods were renamed for consistency:
-
-| v1.x Method | v2.0.0-pre Method | Notes |
-|-------------|------------------|-------|
-| `delete` | `destroy` | More semantic naming |
-| `exists` | `exists?` | Ruby predicate convention |
-| `dump` | `serialize` | Clearer intent |
-
-## Breaking Changes
-
-- `Familia::Base` replaced by `Familia::Horreum`
-- Connection configuration moved to block-based setup
-- Feature inclusion changed from `include` to `feature` declarations
-- Several method names updated for consistency
-
-## Next Steps
-
-After completing the foundation migration:
-1. Review [Security Feature Adoption](v2.0.0-pre5.md) for encrypted fields
-2. See [Architecture Migration](v2.0.0-pre6.md) for persistence improvements
-3. Explore [Relationships Migration](v2.0.0-pre7.md) for the new relationship system

data/docs/migrating/v2.0.0-pre11.md

@@ -1,253 +0,0 @@
-# Migrating Guide: v2.0.0-pre11
-
-This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.
-
-## Enhanced Feature System
-
-### Model-Specific Feature Registration
-
-Previously, all features were registered globally. Now you can register features specific to individual model classes, allowing for better organization and namespace management.
-
-#### Before
-```ruby
-# Global feature registration only
-module MyProjectFeature
-  # Feature implementation
-end
-Familia::Base.add_feature MyProjectFeature, :my_project_feature
-
-class Customer < Familia::Horreum
-  feature :my_project_feature
-end
-
-class Session < Familia::Horreum
-  feature :my_project_feature  # Same global feature
-end
-```
-
-#### After
-```ruby
-# Model-specific feature registration
-module CustomerSpecificFeature
-  # Feature implementation
-end
-
-# Register feature only for Customer and its subclasses
-Customer.add_feature CustomerSpecificFeature, :customer_specific
-
-class Customer < Familia::Horreum
-  feature :customer_specific  # Available via Customer's registry
-end
-
-class PremiumCustomer < Customer
-  feature :customer_specific  # Inherited via ancestry chain
-end
-
-class Session < Familia::Horreum
-  # feature :customer_specific  # Not available - would raise error
-end
-```
-
-**Benefits:**
-- Features can have the same name across different model hierarchies
-- Standardized naming: `deprecated_fields.rb` instead of `customer_deprecated_fields.rb`
-- Natural inheritance through Ruby's class hierarchy
-
-## SafeDump DSL Improvements
-
-The new DSL replaces the brittle `@safe_dump_fields` class instance variable pattern with clean, explicit methods.
-
-### Before
-```ruby
-class Customer < Familia::Horreum
-  feature :safe_dump
-
-  # Brittle - hard to move to feature modules, confusing syntax
-  @safe_dump_fields = [
-    :custid,
-    :email,
-    { active: ->(obj) { obj.active? } },
-    { display_name: ->(obj) { "#{obj.name} (#{obj.custid})" } }
-  ]
-end
-```
-
-### After
-```ruby
-class Customer < Familia::Horreum
-  feature :safe_dump
-
-  # Clean DSL - easy to understand and organize
-  safe_dump_field :custid
-  safe_dump_field :email
-  safe_dump_field :active, ->(obj) { obj.active? }
-  safe_dump_field :display_name, ->(obj) { "#{obj.name} (#{obj.custid})" }
-
-  # Or define multiple fields at once
-  safe_dump_fields :created, :updated, { status: ->(obj) { obj.role } }
-end
-```
-
-**New methods available:**
-- `safe_dump_field(name, callable = nil)` - Define a single field
-- `safe_dump_fields(*fields)` - Define multiple fields or get field names
-- `safe_dump_field_names` - Get array of field names
-- `safe_dump_field_map` - Get the internal callable map
-
-**Backward Compatibility:**
-- `set_safe_dump_fields(*fields)` - Legacy setter method (still works)
-- The old `@safe_dump_fields` pattern is no longer supported
-
-## Auto-loading Features
-
-### Before: Manual Loading
-```ruby
-# customer/features.rb
-
-# Manual feature loading (copied from Familia)
-features_dir = File.join(__dir__, 'features')
-if Dir.exist?(features_dir)
-  Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
-    require_relative feature_file
-  end
-end
-
-class Customer < Familia::Horreum
-  # Features now available for use
-  feature :deprecated_fields
-end
-```
-
-### After: Automatic Loading
-```ruby
-# customer/features.rb
-
-class Customer < Familia::Horreum
-  module Features
-    include Familia::Features::Autoloader
-    # Automatically discovers and loads all *.rb files from customer/features/
-  end
-end
-
-class Customer < Familia::Horreum
-  # Features automatically loaded and available
-  feature :deprecated_fields
-end
-```
-
-**Directory structure this enables:**
-```
-models/
-├── customer/
-│   ├── features/
-│   │   ├── deprecated_fields.rb      # Standardized names!
-│   │   ├── legacy_support.rb
-│   │   └── stripe_integration.rb
-│   └── features.rb                   # Include Autoloader here
-├── session/
-│   ├── features/
-│   │   ├── deprecated_fields.rb      # Same name, different implementation
-│   │   └── expiration_hooks.rb
-│   └── features.rb
-└── customer.rb
-```
-
-## Field Definitions in Feature Modules
-
-Feature modules can now define fields directly in their `ClassMethods` modules. When a class extends the module, the field definitions execute in the extending class's context.
-
-### Example
-```ruby
-# features/common_fields.rb
-
-module CommonFields
-  def self.included(base)
-    base.extend ClassMethods
-  end
-
-  module ClassMethods
-    # These field calls execute in the extending class's context
-    field :created
-    field :updated
-    field :version
-
-    def touch_updated
-      self.updated = Familia.now.to_i
-    end
-  end
-
-  Familia::Base.add_feature self, :common_fields
-end
-
-# Usage
-class Customer < Familia::Horreum
-  feature :common_fields
-  # Now has :created, :updated, :version fields and touch_updated class method
-end
-```
-
-## Migration Steps
-
-### 1. Update SafeDump Usage
-Replace all `@safe_dump_fields` definitions with the new DSL:
-
-```ruby
-# Find and replace pattern:
-# Old: @safe_dump_fields = [:field1, :field2, { field3: ->(obj) { ... } }]
-# New: safe_dump_fields :field1, :field2, { field3: ->(obj) { ... } }
-
-# Or use individual field definitions for better readability:
-safe_dump_field :field1
-safe_dump_field :field2
-safe_dump_field :field3, ->(obj) { ... }
-```
-
-### 2. UnsortedSet Up Auto-loading (Optional)
-If you have project-specific features, set up auto-loading:
-
-```ruby
-# Create: models/[model_name]/features.rb
-module YourProject
-  class ModelName < Familia::Horreum
-    module Features
-      include Familia::Features::Autoloader
-    end
-  end
-end
-
-# Require this file before your model definitions
-require_relative 'model_name/features'
-```
-
-### 3. Organize Features by Model (Optional)
-Consider reorganizing shared feature names by model:
-
-```ruby
-# Before: features/customer_deprecated_fields.rb
-# After: models/customer/features/deprecated_fields.rb
-
-# This allows multiple models to have their own deprecated_fields.rb
-```
-
-### 4. Test Your Changes
-Run your test suite to ensure all SafeDump functionality works correctly:
-
-```ruby
-# Verify SafeDump DSL works
-model = YourModel.new(field1: 'value')
-result = model.safe_dump
-puts result.keys  # Should include your defined fields
-```
-
-## Breaking Changes
-
-1. **`@safe_dump_fields` no longer supported** - Must migrate to DSL methods
-2. **SafeDump field order** - Fields are now returned in definition order via Hash keys (Ruby 1.9+ behavior)
-
-## New Capabilities Unlocked
-
-1. **Standardized feature names** across different models
-2. **Cleaner SafeDump definitions** that can be easily moved to feature modules
-3. **Automatic feature discovery** for better project organization
-4. **Model-specific feature registries** for better namespace management
-5. **Field definitions in feature modules** for shared functionality