dorm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de1f49b44f40ef0f750331d7785409e97829545094a60e475c6f5407293d34e3
+  data.tar.gz: 4e388e613ce981392c831b09d0424493f9b2fb61a2972e797d31fad6b8cf6654
+SHA512:
+  metadata.gz: 45b0f4170cf44f50336f06c73e1aa342c8b32508aef823ec6a04310ba6b1346ccc1b4944bc7342355543f20d28e981a89b9270a2ec0d0f570bcf869e2fe138a8
+  data.tar.gz: cf1da5106c8acc1d6992d4b5353924e2098938410c4a820f1aeb73fe6b2421dd047806e1340e23431624cbe483f6f19f7a50c354da1860a56f51b1e4ed0df3ee

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.ruby-gemset

@@ -0,0 +1 @@
+dorm

data/.ruby-version

@@ -0,0 +1 @@
+3.4.5

data/README.md

@@ -0,0 +1,226 @@
+# Dorm
+
+**D**ata **ORM** - A lightweight, functional ORM for Ruby built on the `Data` class introduced in Ruby 3.2. Features immutable records, monadic error handling, and a functional programming approach to database operations.
+
+## Features
+
+- 🔧 **Immutable Records**: Built on Ruby's `Data` class for immutable, value-based objects
+- 🚂 **Railway-Oriented Programming**: Monadic error handling inspired by dry-monads
+- 🎯 **Functional Approach**: Pure functions in modules instead of stateful classes
+- 🔍 **Automatic CRUD**: Metaprogramming generates standard operations from Data class introspection
+- ✅ **Built-in Validations**: Declarative validation rules with clear error messages
+- 🔄 **Safe Updates**: Use `.with()` for immutable updates that return new objects
+- 🗄️ **Database Agnostic**: Support for PostgreSQL and SQLite3
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dorm'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+```bash
+$ gem install dorm
+```
+
+## Quick Start
+
+### 1. Configure Database Connection
+
+```ruby
+require 'dorm'
+
+Dorm.configure(
+  adapter: :postgresql,
+  host: 'localhost',
+  dbname: 'myapp_development',
+  user: 'postgres'
+)
+```
+
+### 2. Define Your Data Structures
+
+```ruby
+User = Data.define(:id, :name, :email, :created_at, :updated_at)
+Post = Data.define(:id, :title, :body, :user_id, :created_at, :updated_at)
+```
+
+### 3. Create Repositories
+
+```ruby
+Users = Dorm.repository_for(User,
+  validations: {
+    name: { required: true, length: 1..100 },
+    email: { required: true, format: /@/ }
+  }
+)
+
+Posts = Dorm.repository_for(Post,
+  validations: {
+    title: { required: true, length: 1..200 },
+    body: { required: true },
+    user_id: { required: true }
+  }
+)
+```
+
+### 4. Use With Monadic Error Handling
+
+```ruby
+# Chain operations - if any fail, the rest are skipped
+result = Users.create(name: "Alice", email: "alice@example.com")
+  .bind { |user| Posts.create(title: "Hello", body: "World", user_id: user.id) }
+  .map { |post| "Created post: #{post.title}" }
+
+if result.success?
+  puts result.value  # "Created post: Hello"
+else
+  puts "Error: #{result.error}"
+end
+
+# Safe value extraction with defaults
+user = Users.find(1).value_or(nil)
+
+# Check success/failure
+user_result = Users.find(999)
+if user_result.success?
+  puts "Found: #{user_result.value.name}"
+else
+  puts "Not found: #{user_result.error}"
+end
+```
+
+### 5. Immutable Updates
+
+```ruby
+user = Users.find(1).value
+updated_user = Users.save(user.with(name: "Alice Smith"))
+
+if updated_user.success?
+  puts "Updated: #{updated_user.value.name}"
+end
+```
+
+## Available Repository Methods
+
+Every repository automatically gets these methods:
+
+### CRUD Operations
+- `find(id)` - Find record by ID
+- `find_all` - Get all records
+- `create(attrs)` - Create new record
+- `update(record)` - Update existing record
+- `save(record)` - Create or update (based on presence of ID)
+- `delete(record)` - Delete record
+
+### Query Methods
+- `where(predicate)` - Filter with a lambda/proc
+- `find_by(**attrs)` - Find first record matching attributes
+- `find_all_by(**attrs)` - Find all records matching attributes
+- `count` - Count total records
+
+### Examples
+
+```ruby
+# Find operations
+user = Users.find(1)
+all_users = Users.find_all
+
+# Query operations
+active_users = Users.where(->(u) { u.active })
+user_by_email = Users.find_by(email: "alice@example.com")
+posts_by_user = Posts.find_all_by(user_id: user.value.id)
+
+# CRUD with validation
+new_user = Users.create(name: "Bob", email: "bob@example.com")
+updated = Users.save(new_user.value.with(name: "Robert"))
+deleted = Users.delete(updated.value)
+```
+
+## Functional Composition
+
+Use the included functional helpers for more complex operations:
+
+```ruby
+include Dorm::FunctionalHelpers
+
+# Pipeline processing
+result = pipe(
+  Users.find_all.value,
+  partial(method(:filter), ->(u) { u.name.length > 3 }),
+  partial(method(:map_over), ->(u) { u.email })
+)
+```
+
+## Validation Rules
+
+Support for common validation patterns:
+
+```ruby
+Users = Dorm.repository_for(User,
+  validations: {
+    name: {
+      required: true,
+      length: 1..100
+    },
+    email: {
+      required: true,
+      format: /@/
+    },
+    age: {
+      range: 0..150
+    }
+  }
+)
+```
+
+## Database Support
+
+### PostgreSQL
+```ruby
+Dorm.configure(
+  adapter: :postgresql,
+  host: 'localhost',
+  dbname: 'myapp',
+  user: 'postgres',
+  password: 'secret'
+)
+```
+
+### SQLite3
+```ruby
+Dorm.configure(
+  adapter: :sqlite3,
+  database: 'myapp.db'
+)
+```
+
+## Philosophy
+
+This ORM embraces functional programming principles:
+
+- **Immutability**: Records are immutable Data objects
+- **Pure Functions**: Repository methods are pure functions in modules
+- **Error Handling**: Railway-oriented programming with Result monads
+- **Composability**: Operations can be chained and composed
+- **Explicitness**: No hidden state or magic behavior
+
+## Requirements
+
+- Ruby >= 3.2.0 (for Data class support)
+- Database adapter gem (`pg` for PostgreSQL, `sqlite3` for SQLite)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/dorm.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+# Default task
+task default: :test
+
+# Test task configuration
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*test*.rb']
+  t.verbose = true
+  t.warning = false
+end
+
+# Unit tests only
+Rake::TestTask.new(:test_unit) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/unit/*test*.rb']
+  t.verbose = true
+  t.warning = false
+end
+
+# Integration tests only
+Rake::TestTask.new(:test_integration) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/integration/*test*.rb']
+  t.verbose = true
+  t.warning = false
+end
+
+# Run specific test file
+# Usage: rake test_file TEST=test/unit/test_result.rb
+Rake::TestTask.new(:test_file) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList[ENV['TEST']] if ENV['TEST']
+  t.verbose = true
+  t.warning = false
+end
+
+# Test coverage (if you add simplecov)
+desc "Run tests with coverage"
+task :test_coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task[:test].invoke
+end
+
+# Lint code (if you have rubocop)
+task :lint do
+  sh 'rubocop lib/ test/' if system('which rubocop > /dev/null 2>&1')
+end
+
+# Clean up test artifacts
+task :clean do
+  rm_f 'test.db'
+  rm_f 'coverage/'
+  rm_f '.coverage_results'
+end
+
+desc "Run all quality checks"
+task quality: [:lint, :test]
+
+# Documentation generation
+task :doc do
+  sh 'yard doc' if system('which yard > /dev/null 2>&1')
+end
+
+# Show available tasks
+desc "Show test statistics"
+task :test_stats do
+  unit_tests = FileList['test/unit/*test*.rb'].count
+  integration_tests = FileList['test/integration/*test*.rb'].count
+  total_tests = unit_tests + integration_tests
+
+  puts "Test Statistics:"
+  puts "  Unit tests: #{unit_tests}"
+  puts "  Integration tests: #{integration_tests}"
+  puts "  Total test files: #{total_tests}"
+
+  # Count individual test methods
+  test_methods = 0
+  FileList['test/**/*test*.rb'].each do |file|
+    content = File.read(file)
+    test_methods += content.scan(/def test_\w+/).count
+  end
+
+  puts "  Total test methods: #{test_methods}"
+end

data/examples/connection_pool_example.rb

@@ -0,0 +1,88 @@
+# Connection Pool Usage Examples
+
+require "dorm"
+
+# Configure with connection pooling
+Dorm.configure(
+  adapter: :postgresql,
+  host: "localhost",
+  dbname: "myapp_production",
+  user: "postgres",
+  password: "secret",
+
+  # Pool configuration
+  pool_size: 10,              # Maximum connections in pool
+  pool_timeout: 5,            # Seconds to wait for connection
+  max_connection_age: 3600,   # 1 hour - connections older than this get reaped
+  max_idle_time: 300,         # 5 minutes - idle connections get reaped
+  reap_frequency: 60          # 1 minute - how often to check for stale connections
+)
+
+# For SQLite3 with pooling (useful for testing)
+Dorm.configure(
+  adapter: :sqlite3,
+  database: "myapp.db",
+  pool_size: 3, # SQLite doesn't need many connections
+  pool_timeout: 2
+)
+
+# Usage is exactly the same - pooling is transparent
+User = Data.define(:id, :name, :email, :created_at, :updated_at)
+Users = Dorm.repository_for(User, validations: {
+                              name: { required: true },
+                              email: { required: true, format: /@/ }
+                            })
+
+# All operations automatically use the pool
+user_result = Users.create(name: "Alice", email: "alice@example.com")
+
+if user_result.success?
+  puts "Created user with pooled connection!"
+
+  # Multiple concurrent operations will use different connections from pool
+  threads = 10.times.map do |i|
+    Thread.new do
+      Users.create(name: "User #{i}", email: "user#{i}@example.com")
+    end
+  end
+
+  results = threads.map(&:join).map(&:value)
+  successful = results.count(&:success?)
+  puts "Successfully created #{successful} users concurrently"
+end
+
+# Monitor pool health
+stats = Dorm::Database.pool_stats
+puts "Pool stats: #{stats}"
+# => Pool stats: {:size=>3, :available=>2, :checked_out=>1, :adapter=>:postgresql}
+
+# Graceful shutdown - disconnect all connections
+at_exit do
+  Dorm::Database.disconnect!
+end
+
+# Example with error handling and pool exhaustion
+begin
+  # This will timeout if pool is exhausted
+  user = Users.find(1).value
+rescue Dorm::ConnectionPool::ConnectionTimeoutError => e
+  puts "Pool exhausted: #{e.message}"
+rescue Dorm::ConnectionPool::PoolExhaustedError => e
+  puts "No connections available: #{e.message}"
+end
+
+# Example: Custom pool monitoring
+class PoolMonitor
+  def self.log_stats
+    stats = Dorm::Database.pool_stats
+    puts "[#{Time.now}] Pool: #{stats[:checked_out]}/#{stats[:size]} connections in use"
+  end
+end
+
+# Log pool stats every 30 seconds
+Thread.new do
+  loop do
+    sleep(30)
+    PoolMonitor.log_stats
+  end
+end

data/examples/query_builder_examples.rb

@@ -0,0 +1,202 @@
+# Query Builder Usage Examples
+
+require 'dorm'
+
+# Setup
+User = Data.define(:id, :name, :email, :age, :created_at, :updated_at)
+Post = Data.define(:id, :title, :body, :user_id, :status, :created_at, :updated_at)
+
+Users = Dorm.repository_for(User)
+Posts = Dorm.repository_for(Post)
+
+# === BASIC QUERIES ===
+
+# Simple where conditions
+active_users = Users.query
+  .where(status: 'active')
+  .to_a
+
+# Multiple conditions (hash style)  
+young_active_users = Users.query
+  .where(status: 'active', age: 18..30)
+  .to_a
+
+# Raw SQL conditions
+power_users = Users.query
+  .where_raw("post_count > ? AND last_login > ?", 10, 1.week.ago)
+  .to_a
+
+# === DSL WHERE CONDITIONS ===
+
+# Elegant DSL syntax
+sophisticated_query = Users.query
+  .where { name.like("%admin%").and(age.gt(21)) }
+  .to_a
+
+# Complex conditions with OR
+complex_users = Users.query
+  .where { name.eq("Alice").or(email.like("%@admin.com")) }
+  .to_a
+
+# IN conditions
+specific_users = Users.query
+  .where { id.in([1, 2, 3, 4, 5]) }
+  .to_a
+
+# NULL checks
+incomplete_profiles = Users.query
+  .where { email.null.or(name.null) }
+  .to_a
+
+# === SELECT AND PROJECTION ===
+
+# Select specific fields
+user_emails = Users.query
+  .select(:name, :email)
+  .where(status: 'active')
+  .to_a
+
+# Raw select with calculations
+user_stats = Users.query
+  .select_raw("name, email, EXTRACT(year FROM created_at) as signup_year")
+  .to_a
+
+# === JOINS ===
+
+# Inner join with automatic field mapping
+posts_with_authors = Posts.query
+  .join(:users, user_id: :id)
+  .select("posts.*", "users.name as author_name")
+  .to_a
+
+# Left join with custom condition
+all_posts_with_optional_authors = Posts.query
+  .left_join(:users, "users.id = posts.user_id")
+  .to_a
+
+# Multiple joins
+posts_with_comments = Posts.query
+  .join(:users, user_id: :id)
+  .left_join(:comments, "comments.post_id = posts.id")
+  .group_by("posts.id", "users.name")
+  .select_raw("posts.*, users.name as author, COUNT(comments.id) as comment_count")
+  .to_a
+
+# === ORDERING AND LIMITING ===
+
+# Order by single field
+recent_posts = Posts.query
+  .order_by(:created_at => :desc)
+  .limit(10)
+  .to_a
+
+# Multiple order fields
+sorted_users = Users.query
+  .order_by(:status, :name => :asc)
+  .to_a
+
+# Pagination
+page_2_users = Users.query
+  .page(2, per_page: 20)  # page 2, 20 per page
+  .to_a
+
+# === AGGREGATIONS ===
+
+# Count records
+user_count = Users.query
+  .where(status: 'active')
+  .count
+  .value_or(0)
+
+# Sum, average, min, max  
+stats = {
+  total_age: Users.query.sum(:age).value_or(0),
+  avg_age: Users.query.avg(:age).value_or(0),
+  oldest: Users.query.max(:age).value_or(0),
+  youngest: Users.query.min(:age).value_or(0)
+}
+
+# Group by with aggregation
+posts_by_status = Posts.query
+  .group_by(:status)
+  .select_raw("status, COUNT(*) as post_count")
+  .to_a
+
+# Having clause
+popular_authors = Posts.query
+  .join(:users, user_id: :id)
+  .group_by("users.id", "users.name")
+  .having("COUNT(posts.id) > ?", 5)
+  .select_raw("users.name, COUNT(posts.id) as post_count")
+  .to_a
+
+# === EXECUTION METHODS ===
+
+# Convert to array (execute immediately)
+users_array = Users.query.where(status: 'active').to_a
+
+# Get first result
+first_admin = Users.query
+  .where { name.like("%admin%") }
+  .first
+
+if first_admin.success?
+  puts "Found admin: #{first_admin.value.name}"
+end
+
+# Check if any records exist
+has_active_users = Users.query
+  .where(status: 'active')
+  .exists?
+  .value_or(false)
+
+# Get raw SQL for debugging
+sql = Users.query
+  .where(status: 'active')
+  .join(:posts, user_id: :id)
+  .limit(10)
+  .to_sql
+
+puts "Generated SQL: #{sql}"
+
+# === FUNCTIONAL COMPOSITION ===
+
+# Chain query building functionally
+build_user_query = ->(status, min_age) {
+  Users.query
+    .where(status: status)
+    .where { age.gte(min_age) }
+    .order_by(:name)
+}
+
+# Use the builder
+active_adults = build_user_query.call('active', 18).to_a
+inactive_seniors = build_user_query.call('inactive', 65).limit(5).to_a
+
+# === RESULT HANDLING ===
+
+# All query results are wrapped in Result monads
+Users.query
+  .where(id: 999)
+  .first
+  .bind { |user| Posts.query.where(user_id: user.id).to_a }
+  .map { |posts| posts.map(&:title) }
+  .value_or([])
+
+# === COMPLEX EXAMPLE ===
+
+# Find popular posts by active users with recent activity
+popular_recent_posts = Posts.query
+  .join(:users, user_id: :id)
+  .where { status.eq('published') }
+  .where { created_at.gte(1.month.ago) }
+  .where("users.status = ?", 'active')
+  .left_join(:comments, "comments.post_id = posts.id")
+  .group_by("posts.id", "posts.title", "users.name")
+  .having("COUNT(comments.id) > ?", 5)
+  .order_by(created_at: :desc)
+  .select_raw("posts.*, users.name as author, COUNT(comments.id) as comment_count")
+  .limit(20)
+  .to_a
+
+puts "Found #{popular_recent_posts.length} popular recent posts"