familia 2.0.0.pre4 → 2.0.0.pre6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c17c7c0fbd21ec7edf380a157f36bcf50632838c083474ac56291653e5e5b5f2
-  data.tar.gz: 496226f45b28c48a20f4a7c0901e45f048407b53cb80d4d373f5840f06673bd5
+  metadata.gz: 93cb8ea627c19daff3566c7373aa45ff04adb6d37a3346c3b3049712c18838ea
+  data.tar.gz: 9d359e2067062a4c6afe91a76985362989a569611400f10f7155e505dd55e39b
 SHA512:
-  metadata.gz: bfce15edc52796648eb1356be796260d8e8dae8bcba38f11a435b86cd732f73acacc8959e67d2bb3e3025d82a962e63ca2627fecb2f88dfc0e76bb1da174592d
-  data.tar.gz: 3cc196dc11aaf65409061ed5772043c151dfbc0fe39701b86e2808d2c9f1a55a5647f9ba22cb80cc806752ad17d41a05c2cce743fecf2258e8ff6b91f9868c12
+  metadata.gz: e020a48703858e929eeb11188029893656ef84ce98113e4c448d41e354edb4fe77df420aa4bab33b7775f0719ad5a693fc672c8159cd0e963be7750daa12d5b9
+  data.tar.gz: c3e66800df77ccd33ccd5a6027d031173642446210309e60bf83243f59585a0416ea99002063f0080828eb24d1aa1fa50f3013e7dbf408b2299f2fea617b2fa3

data/.gitignore

@@ -5,6 +5,7 @@
 .history
 .devcontainer
 .vscode
+.*.json
 *.env
 *.log
 *.md
@@ -21,4 +22,6 @@ vendor
 *.gem
 doc/
 .yardoc
+!docs/overview.md
 !docs/connection_pooling.md
+!docs/wiki/**/*.md

data/.rubocop_todo.yml

@@ -26,14 +26,14 @@ Layout/EmptyLines:
 # SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
 Layout/EmptyLinesAroundClassBody:
   Exclude:
-    - "lib/familia/datatype/types/list.rb"
-    - "lib/familia/datatype/types/unsorted_set.rb"
+    - "lib/familia/data_type/types/list.rb"
+    - "lib/familia/data_type/types/unsorted_set.rb"
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 Layout/SpaceAfterComma:
   Exclude:
-    - "lib/familia/datatype/types/hashkey.rb"
+    - "lib/familia/data_type/types/hashkey.rb"
 
 # Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
@@ -61,9 +61,9 @@ Metrics/PerceivedComplexity:
 # SupportedStyles: anonymous, explicit
 Naming/BlockForwarding:
   Exclude:
-    - "lib/familia/datatype/types/list.rb"
-    - "lib/familia/datatype/types/sorted_set.rb"
-    - "lib/familia/datatype/types/unsorted_set.rb"
+    - "lib/familia/data_type/types/list.rb"
+    - "lib/familia/data_type/types/sorted_set.rb"
+    - "lib/familia/data_type/types/unsorted_set.rb"
     - "lib/familia/refinements.rb"
 
 # Offense count: 8
@@ -73,8 +73,8 @@ Naming/MethodParameterName:
   Exclude:
     - "lib/familia/core_ext.rb"
     - "lib/familia/horreum/class_methods.rb"
-    - "lib/familia/datatype/types/sorted_set.rb"
-    - "lib/familia/datatype/types/unsorted_set.rb"
+    - "lib/familia/data_type/types/sorted_set.rb"
+    - "lib/familia/data_type/types/unsorted_set.rb"
 
 # Offense count: 1
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
@@ -104,9 +104,9 @@ Naming/PredicatePrefix:
 Style/ArgumentsForwarding:
   Exclude:
     - "lib/familia/horreum/class_methods.rb"
-    - "lib/familia/datatype/types/list.rb"
-    - "lib/familia/datatype/types/sorted_set.rb"
-    - "lib/familia/datatype/types/unsorted_set.rb"
+    - "lib/familia/data_type/types/list.rb"
+    - "lib/familia/data_type/types/sorted_set.rb"
+    - "lib/familia/data_type/types/unsorted_set.rb"
     - "lib/familia/refinements.rb"
 
 # Offense count: 11
@@ -118,11 +118,11 @@ Style/Documentation:
     - "lib/familia/errors.rb"
     - "lib/familia/horreum/class_methods.rb"
     - "lib/familia/horreum/related_fields_management.rb"
-    - "lib/familia/datatype/types/hashkey.rb"
-    - "lib/familia/datatype/types/list.rb"
-    - "lib/familia/datatype/types/sorted_set.rb"
-    - "lib/familia/datatype/types/string.rb"
-    - "lib/familia/datatype/types/unsorted_set.rb"
+    - "lib/familia/data_type/types/hashkey.rb"
+    - "lib/familia/data_type/types/list.rb"
+    - "lib/familia/data_type/types/sorted_set.rb"
+    - "lib/familia/data_type/types/string.rb"
+    - "lib/familia/data_type/types/unsorted_set.rb"
     - "lib/familia/version.rb"
 
 # Offense count: 1
@@ -150,7 +150,7 @@ Style/FrozenStringLiteralComment:
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/HashTransformValues:
   Exclude:
-    - "lib/familia/datatype/types/hashkey.rb"
+    - "lib/familia/data_type/types/hashkey.rb"
 
 # Offense count: 1
 # This cop supports unsafe autocorrection (--autocorrect-all).

data/CLAUDE.md

@@ -6,11 +6,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing
 
-A couple rules when writing tests:
-1) Every tryouts file has three sections: setup, testcases, teardown.
-2) Every tryouts testcase also has three parts: description, code, expectations.
-3) Tryouts tests are meant to double as documentation examples; keep that in mind when considering syntax choices.
-4) There are multiple kinds of expectations: `#=>` is the default comparison, `#=:>` is a class comparison via `is_a?` or `kind_of?`, `#=!>` is an exception class which allows you to knowingly raise an exception without needing a begin/rescue.
+Tryouts framework rules:
+1) **Structure**: 3 sections - setup (optional), testcases, teardown (optional)
+2) **Test cases**: Use `##` for descriptions, Ruby code, then `#=>` expectations
+3) **Variables**: Instance variables (`@var`) persist across all sections
+4) **Expectations**: `#=>` (value), `#==>` (boolean), `#=:>` (type), `#=!>` (exception)
+5) **Comments**: Use single `#` prefix, DO NOT label sections
+6) **Philosophy**: Plain realistic code, avoid mocks/test DSL
+7) **Result**: Last expression in each test case is the result
 
 - **Run tests**: `bundle exec try` (uses tryouts testing framework)
 - **Run specific test file, verbose**: `bundle exec try -v try/specific_test_try.rb`
@@ -51,9 +54,9 @@ This project uses `tryouts` instead of RSpec/Minitest. Test files are located in
    - Supports multiple identifier strategies: symbols, procs, arrays
 
 2. **`Familia::DataType`** - Base class for Valkey data type wrappers
-   - Located in `lib/familia/datatype.rb`
+   - Located in `lib/familia/data_type.rb`
    - Provides String, List, Set, SortedSet, HashKey implementations
-   - Each type has its own class in `lib/familia/datatype/types/`
+   - Each type has its own class in `lib/familia/data_type/types/`
 
 3. **`Familia::Base`** - Common module for both Horreum and DataType
    - Located in `lib/familia/base.rb`
@@ -89,7 +92,7 @@ end
 
 - `lib/familia.rb` - Main entry point and module definition
 - `lib/familia/horreum/` - Horreum class implementation (class_methods, commands, serialization, etc.)
-- `lib/familia/datatype/` - Valkey/Redis type implementations and commands
+- `lib/familia/data_type/` - Valkey/Redis type implementations and commands
 - `lib/familia/features/` - Modular feature implementations
 - `try/` - Test files using tryouts framework
 - `try/test_helpers.rb` - Shared test utilities and sample classes

data/Gemfile

@@ -9,7 +9,7 @@ group :test do
     gem 'tryouts', path: '../tryouts'
     gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
-    gem 'tryouts', '~> 3.1.2', require: false
+    gem 'tryouts', '~> 3.3.2', require: false
   end
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'
@@ -27,3 +27,7 @@ group :development, :test do
   gem 'yard', '~> 0.9', require: false
   gem 'irb', '~> 1.15.2', require: false
 end
+
+group :optional do
+  gem 'rbnacl', '~> 7.1', '>= 7.1.1'
+end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre4)
+    familia (2.0.0.pre6)
       benchmark
       connection_pool
       csv
@@ -24,6 +24,8 @@ GEM
     date (3.4.1)
     diff-lcs (1.6.2)
     erb (5.0.2)
+    ffi (1.17.2)
+    ffi (1.17.2-arm64-darwin)
     io-console (0.8.1)
     irb (1.15.2)
       pp (>= 0.6.0)
@@ -41,6 +43,8 @@ GEM
     parser (3.3.8.0)
       ast (~> 2.4.1)
       racc
+    pastel (0.8.0)
+      tty-color (~> 0.5)
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
@@ -56,6 +60,8 @@ GEM
       stringio
     racc (1.8.1)
     rainbow (3.1.1)
+    rbnacl (7.1.2)
+      ffi (~> 1)
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
@@ -107,9 +113,18 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.1.2)
+    tryouts (3.3.2)
+      concurrent-ruby (~> 1.0)
+      irb
       minitest (~> 5.0)
+      pastel (~> 0.8)
+      prism (~> 1.0)
       rspec (~> 3.0)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+    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)
@@ -127,12 +142,13 @@ DEPENDENCIES
   irb (~> 1.15.2)
   kramdown
   pry-byebug (~> 3.10.1)
+  rbnacl (~> 7.1, >= 7.1.1)
   rubocop
   rubocop-performance
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.1.2)
+  tryouts (~> 3.3.2)
   yard (~> 0.9)
 
 BUNDLED WITH

data/README.md

@@ -1,191 +1,70 @@
-# Familia - 2.0.0
+# Familia - 2.0
 
 **Organize and store Ruby objects in Valkey/Redis. A powerful Ruby ORM (of sorts) for Valkey/Redis.**
 
 Familia provides a flexible and feature-rich way to interact with Valkey using Ruby objects. It's designed to make working with Valkey as natural as working with Ruby classes, while offering advanced features for complex data management.
 
-## Installation
+## Quick Start
 
+### 1. Installation
 
-Get it in one of the following ways:
+```bash
+# Add to Gemfile
+gem 'familia', '>= 2.0.0'
 
-* In your Gemfile: `gem 'familia', '>= 1.1.0-rc1'`
-* Install it by hand: `gem install familia --pre`
-* Or for development: `git clone git@github.com:delano/familia.git`
-
-
-## Core Concepts and Features
-
-### 1. Defining Horreum Classes
-
-Familia uses the concept of "Horreum" classes to represent Valkey-compatible objects:
-
-```ruby
-class Flower < Familia::Horreum
-  identifier_field :token
-  field :name
-  list :owners
-  set :tags
-  zset :metrics
-  hashkey :props
-  string :counter
-end
-```
-
-### 2. Flexible Identifiers
-
-You can define identifiers in various ways:
-
-```ruby
-class User < Familia::Horreum
-  identifier_field :email
-  # or
-  identifier_field -> (user) { "user:#{user.email}" }
-  # or
-  identifier_field [:type, :email]
-
-  field :email
-  field :type
-end
-```
-
-### 3. Data Types
-
-Familia supports various Valkey-compatible data types:
-
-```ruby
-class Product < Familia::Horreum
-  string :name
-  list :categories
-  set :tags
-  zset :ratings
-  hashkey :attributes
-end
-```
-
-### 4. Class-level Valkey-compatible Types
-
-You can also define Valkey-compatible types at the class level:
-
-```ruby
-class Customer < Familia::Horreum
-  class_sorted_set :values, key: 'project:customers'
-  class_hashkey :projects
-  class_list :customers, suffix: []
-  class_string :message
-end
-```
-
-### 5. Automatic Expiration
-
-Use the expiration feature to set default TTL for objects:
-
-```ruby
-class Session < Familia::Horreum
-  feature :expiration
-  default_expiration 180.minutes
-end
+# Or install directly
+gem install familia
 ```
 
-### 6. Safe Dumping for APIs
-
-Control which fields are exposed when serializing objects:
+### 2. Configure Connection
 
 ```ruby
-class User < Familia::Horreum
-  feature :safe_dump
-
-  @safe_dump_fields = [
-    :id,
-    :username,
-    {full_name: ->(user) { "#{user.first_name} #{user.last_name}" }}
-  ]
-end
-```
+# config/initializers/familia.rb (Rails)
+# or at the top of your script
 
-### 7. Quantization for Time-based Data
+require 'familia'
 
-Use quantization for time-based metrics:
+# Basic configuration
+Familia.uri = 'redis://localhost:6379/0'
 
-```ruby
-class DailyMetric < Familia::Horreum
-  feature :quantization
-  string :counter, default_expiration: 1.day, quantize: [10.minutes, '%H:%M']
-end
+# Or with authentication
+Familia.uri = 'redis://user:password@localhost:6379/0'
 ```
 
-### 8. Custom Methods and Logic
-
-Add custom methods to your Horreum classes:
+### 3. Create Your First Model
 
 ```ruby
 class User < Familia::Horreum
-  def full_name
-    "#{first_name} #{last_name}"
-  end
-
-  def active?
-    status == 'active'
-  end
+  identifier_field :email
+  field :email
+  field :name
+  field :created_at
 end
 ```
 
-### 9. Custom Methods and Logic
-
-You can add custom methods to your Horreum classes:
+### 4. Basic Operations
 
 ```ruby
-class Customer < Familia::Horreum
-  def active?
-    verified && !reset_requested
-  end
-end
-```
-### 10. Open-ended Serialization
+# Create
+user = User.new(email: 'alice@example.com', name: 'Alice')
+user.save
 
-```ruby
-class ComplexObject < Familia::Horreum
-  def serialize_value
-    custom_serialization_method
-  end
-
-  def self.deserialize_value(data)
-    custom_deserialization_method(data)
-  end
-end
-```
+# Find
+user = User.load('alice@example.com')
 
-### 11. Transactional Operations
+# Update
+user.name = 'Alice Smith'
+user.save
 
-```ruby
-user.transaction do |conn|
-  conn.set("user:#{user.id}:status", "active")
-  conn.zadd("active_users", Time.now.to_i, user.id)
-end
+# Check existence
+User.exists?('alice@example.com')  #=> true
 ```
 
-### 12. Connection Management and Pooling
-
-Familia supports custom connection providers for advanced scenarios like connection pooling:
-
-```ruby
-# Using connection_pool gem for thread-safe pooling
-require 'connection_pool'
-
-# Create pools for each logical database
-pools = {
-  "redis://localhost:6379/0" => ConnectionPool.new(size: 10) { Redis.new(db: 0) },
-  "redis://localhost:6379/1" => ConnectionPool.new(size: 5) { Redis.new(db: 1) }
-}
-
-# Configure Familia to use the pools
-Familia.connection_provider = lambda do |uri|
-  pool = pools[uri] || pools["redis://localhost:6379/0"]
-  pool.with { |conn| conn }
-end
-```
+## Prerequisites
 
-See the [Connection Pooling Guide](docs/connection_pooling.md) for detailed examples.
+- **Ruby**: 3.4+ (3.4+ recommended)
+- **Valkey/Redis**: 6.0+
+- **Gems**: `redis` (automatically installed)
 
 
 ## Usage Examples