familia 2.0.0.pre26 → 2.1.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre26
+  version: 2.1.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
@@ -141,6 +127,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: 'Familia: An ORM for Valkey-compatible databases in Ruby.. Organize and
   store ruby objects in Valkey/Redis'
 email: gems@solutious.com
@@ -193,18 +193,8 @@ files:
 - docs/guides/optimized-loading.md
 - docs/guides/thread-safety-monitoring.md
 - docs/guides/time-literals.md
+- docs/guides/writing-migrations.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
@@ -214,9 +204,12 @@ files:
 - examples/datatype_standalone.rb
 - examples/encrypted_fields.rb
 - examples/json_usage_patterns.rb
+- examples/migrations/v1_to_v2_serialization_migration.rb
 - examples/relationships.rb
 - examples/safe_dump.rb
 - examples/sampling_demo.rb
+- examples/schemas/customer.json
+- examples/schemas/session.json
 - examples/single_connection_transaction_confusions.rb
 - examples/through_relationships.rb
 - familia.gemspec
@@ -282,6 +275,7 @@ files:
 - lib/familia/features/relationships/participation_relationship.rb
 - lib/familia/features/relationships/score_encoding.rb
 - lib/familia/features/safe_dump.rb
+- lib/familia/features/schema_validation.rb
 - lib/familia/features/transient_fields.rb
 - lib/familia/features/transient_fields/redacted_string.rb
 - lib/familia/features/transient_fields/single_use_redacted_string.rb
@@ -301,10 +295,21 @@ files:
 - lib/familia/instrumentation.rb
 - lib/familia/json_serializer.rb
 - lib/familia/logging.rb
+- lib/familia/migration.rb
+- lib/familia/migration/base.rb
+- lib/familia/migration/errors.rb
+- lib/familia/migration/model.rb
+- lib/familia/migration/pipeline.rb
+- lib/familia/migration/rake_tasks.rake
+- lib/familia/migration/rake_tasks.rb
+- lib/familia/migration/registry.rb
+- lib/familia/migration/runner.rb
+- lib/familia/migration/script.rb
 - lib/familia/refinements.rb
 - lib/familia/refinements/dear_json.rb
 - lib/familia/refinements/stylize_words.rb
 - lib/familia/refinements/time_literals.rb
+- lib/familia/schema_registry.rb
 - lib/familia/secure_identifier.rb
 - lib/familia/settings.rb
 - lib/familia/thread_safety/instrumented_mutex.rb
@@ -387,6 +392,8 @@ files:
 - try/features/relationships/relationships_try.rb
 - try/features/safe_dump/safe_dump_advanced_try.rb
 - try/features/safe_dump/safe_dump_try.rb
+- try/features/schema_registry_try.rb
+- try/features/schema_validation_feature_try.rb
 - try/features/transient_fields/redacted_string_try.rb
 - try/features/transient_fields/refresh_reset_try.rb
 - try/features/transient_fields/simple_refresh_test.rb
@@ -427,6 +434,17 @@ files:
 - try/integration/transaction_safety_workflow_try.rb
 - try/integration/verifiable_identifier_try.rb
 - try/investigation/pipeline_routing/README.md
+- try/migration/base_try.rb
+- try/migration/errors_try.rb
+- try/migration/integration_try.rb
+- try/migration/model_try.rb
+- try/migration/pipeline_try.rb
+- try/migration/rake_tasks_try.rb
+- try/migration/registry_try.rb
+- try/migration/runner_try.rb
+- try/migration/schema_validation_try.rb
+- try/migration/script_try.rb
+- try/migration/v1_to_v2_serialization_try.rb
 - try/performance/benchmarks_try.rb
 - try/performance/transaction_safety_benchmark_try.rb
 - try/support/benchmarks/deserialization_benchmark.rb
@@ -557,7 +575,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