anima-core 0.2.1 → 1.0.0

data/skills/activerecord/examples/associations/self_referential.rb

@@ -0,0 +1,302 @@
+# Self-Referential Association Examples
+# Model relates to itself for hierarchies and graphs
+
+# ============================================
+# Simple Hierarchy: Manager/Subordinates
+# ============================================
+
+class Employee < ApplicationRecord
+  # Employee has one manager (who is also an Employee)
+  belongs_to :manager,
+             class_name: "Employee",
+             optional: true,
+             inverse_of: :subordinates
+
+  # Employee has many subordinates (who are also Employees)
+  has_many :subordinates,
+           class_name: "Employee",
+           foreign_key: "manager_id",
+           dependent: :nullify,
+           inverse_of: :manager
+
+  validates :name, presence: true
+
+  # Convenience methods
+  def top_manager?
+    manager.nil?
+  end
+
+  def direct_reports_count
+    subordinates.count
+  end
+end
+
+# Migration
+# create_table :employees do |t|
+#   t.string :name, null: false
+#   t.belongs_to :manager, foreign_key: { to_table: :employees }
+#   t.timestamps
+# end
+
+# Usage
+ceo = Employee.create!(name: "CEO")
+vp = Employee.create!(name: "VP Engineering", manager: ceo)
+dev = Employee.create!(name: "Developer", manager: vp)
+
+dev.manager          # => VP Engineering
+vp.subordinates      # => [Developer]
+ceo.subordinates     # => [VP Engineering]
+
+# ============================================
+# Friendship: Many-to-Many Self-Join
+# ============================================
+
+class User < ApplicationRecord
+  has_many :friendships, dependent: :destroy
+  has_many :friends, through: :friendships
+
+  # Inverse friendships (where user is the friend)
+  has_many :inverse_friendships,
+           class_name: "Friendship",
+           foreign_key: "friend_id",
+           dependent: :destroy
+  has_many :inverse_friends,
+           through: :inverse_friendships,
+           source: :user
+
+  def all_friends
+    friends + inverse_friends
+  end
+
+  def friend_with?(other_user)
+    friends.include?(other_user) || inverse_friends.include?(other_user)
+  end
+end
+
+class Friendship < ApplicationRecord
+  belongs_to :user
+  belongs_to :friend, class_name: "User"
+
+  validates :user_id, uniqueness: { scope: :friend_id }
+  validate :not_self_friend
+
+  private
+
+  def not_self_friend
+    errors.add(:friend, "can't be yourself") if user_id == friend_id
+  end
+end
+
+# Migration
+# create_table :friendships do |t|
+#   t.belongs_to :user, null: false, foreign_key: true
+#   t.belongs_to :friend, null: false, foreign_key: { to_table: :users }
+#   t.timestamps
+# end
+# add_index :friendships, [:user_id, :friend_id], unique: true
+
+# Usage
+alice = User.create!(name: "Alice")
+bob = User.create!(name: "Bob")
+
+Friendship.create!(user: alice, friend: bob)
+alice.friends.include?(bob)     # => true
+bob.inverse_friends.include?(alice)  # => true
+
+# ============================================
+# Bidirectional Friendship (Mutual)
+# ============================================
+
+class User < ApplicationRecord
+  has_many :friendships, dependent: :destroy
+  has_many :friends, through: :friendships
+
+  def befriend(other_user)
+    return if self == other_user
+    return if friend_with?(other_user)
+
+    # Create bidirectional friendship
+    transaction do
+      friendships.create!(friend: other_user)
+      other_user.friendships.create!(friend: self)
+    end
+  end
+
+  def unfriend(other_user)
+    transaction do
+      friendships.find_by(friend: other_user)&.destroy
+      other_user.friendships.find_by(friend: self)&.destroy
+    end
+  end
+
+  def friend_with?(other_user)
+    friends.exists?(id: other_user.id)
+  end
+end
+
+# ============================================
+# Tree Structure: Parent/Children
+# ============================================
+
+class Category < ApplicationRecord
+  belongs_to :parent,
+             class_name: "Category",
+             optional: true,
+             inverse_of: :children,
+             counter_cache: :children_count
+
+  has_many :children,
+           class_name: "Category",
+           foreign_key: "parent_id",
+           dependent: :destroy,
+           inverse_of: :parent
+
+  validates :name, presence: true
+
+  scope :roots, -> { where(parent_id: nil) }
+  scope :leaves, -> { where(children_count: 0) }
+
+  def root?
+    parent_id.nil?
+  end
+
+  def leaf?
+    children.empty?
+  end
+
+  def ancestors
+    node = self
+    result = []
+    while node.parent
+      result << node.parent
+      node = node.parent
+    end
+    result.reverse
+  end
+
+  def descendants
+    children.flat_map { |c| [c] + c.descendants }
+  end
+
+  def depth
+    ancestors.size
+  end
+end
+
+# Migration
+# create_table :categories do |t|
+#   t.string :name, null: false
+#   t.belongs_to :parent, foreign_key: { to_table: :categories }
+#   t.integer :children_count, default: 0, null: false
+#   t.timestamps
+# end
+
+# Usage
+electronics = Category.create!(name: "Electronics")
+phones = Category.create!(name: "Phones", parent: electronics)
+smartphones = Category.create!(name: "Smartphones", parent: phones)
+
+smartphones.ancestors  # => [Electronics, Phones]
+electronics.descendants  # => [Phones, Smartphones]
+Category.roots  # => [Electronics]
+
+# ============================================
+# Adjacency List with Recursive CTE
+# ============================================
+
+class Category < ApplicationRecord
+  # ... same associations as above ...
+
+  # PostgreSQL recursive query for full tree
+  def self.tree_for(root_id)
+    sql = <<~SQL
+      WITH RECURSIVE category_tree AS (
+        SELECT id, name, parent_id, 0 AS depth
+        FROM categories
+        WHERE id = :root_id
+        UNION ALL
+        SELECT c.id, c.name, c.parent_id, ct.depth + 1
+        FROM categories c
+        INNER JOIN category_tree ct ON c.parent_id = ct.id
+      )
+      SELECT * FROM category_tree ORDER BY depth, name
+    SQL
+
+    find_by_sql([sql, { root_id: }])
+  end
+
+  def full_path
+    self.class.ancestors_for(id).pluck(:name).join(" > ")
+  end
+
+  def self.ancestors_for(category_id)
+    sql = <<~SQL
+      WITH RECURSIVE ancestors AS (
+        SELECT id, name, parent_id, 0 AS depth
+        FROM categories
+        WHERE id = :category_id
+        UNION ALL
+        SELECT c.id, c.name, c.parent_id, a.depth + 1
+        FROM categories c
+        INNER JOIN ancestors a ON c.id = a.parent_id
+      )
+      SELECT * FROM ancestors ORDER BY depth DESC
+    SQL
+
+    find_by_sql([sql, { category_id: }])
+  end
+end
+
+# ============================================
+# Follower/Following Pattern
+# ============================================
+
+class User < ApplicationRecord
+  # Users I follow
+  has_many :active_follows,
+           class_name: "Follow",
+           foreign_key: "follower_id",
+           dependent: :destroy
+  has_many :following, through: :active_follows, source: :followed
+
+  # Users who follow me
+  has_many :passive_follows,
+           class_name: "Follow",
+           foreign_key: "followed_id",
+           dependent: :destroy
+  has_many :followers, through: :passive_follows, source: :follower
+
+  def follow(other_user)
+    following << other_user unless self == other_user
+  end
+
+  def unfollow(other_user)
+    active_follows.find_by(followed: other_user)&.destroy
+  end
+
+  def following?(other_user)
+    following.exists?(id: other_user.id)
+  end
+end
+
+class Follow < ApplicationRecord
+  belongs_to :follower, class_name: "User"
+  belongs_to :followed, class_name: "User"
+
+  validates :follower_id, uniqueness: { scope: :followed_id }
+  validate :not_self_follow
+
+  private
+
+  def not_self_follow
+    errors.add(:followed, "can't follow yourself") if follower_id == followed_id
+  end
+end
+
+# Migration
+# create_table :follows do |t|
+#   t.belongs_to :follower, null: false, foreign_key: { to_table: :users }
+#   t.belongs_to :followed, null: false, foreign_key: { to_table: :users }
+#   t.timestamps
+# end
+# add_index :follows, [:follower_id, :followed_id], unique: true

data/skills/activerecord/examples/associations/through_associations.rb

@@ -0,0 +1,203 @@
+# Through Association Examples
+# Many-to-many relationships with join models
+
+# ============================================
+# has_many :through - Standard Pattern
+# ============================================
+
+# Physician <-> Appointment <-> Patient
+#
+# ┌──────────────┐       ┌──────────────┐       ┌──────────────┐
+# │   Physician  │       │  Appointment │       │   Patient    │
+# ├──────────────┤       ├──────────────┤       ├──────────────┤
+# │ id           │◄──────│ physician_id │       │ id           │
+# │ name         │       │ patient_id   │──────►│ name         │
+# │              │       │ scheduled_at │       │              │
+# └──────────────┘       └──────────────┘       └──────────────┘
+
+class Physician < ApplicationRecord
+  has_many :appointments, dependent: :destroy
+  has_many :patients, through: :appointments
+end
+
+class Appointment < ApplicationRecord
+  belongs_to :physician
+  belongs_to :patient
+
+  # Join model can have attributes
+  validates :scheduled_at, presence: true
+  validate :no_double_booking
+
+  scope :upcoming, -> { where("scheduled_at > ?", Time.current) }
+  scope :past, -> { where("scheduled_at <= ?", Time.current) }
+
+  private
+
+  def no_double_booking
+    return unless scheduled_at
+
+    conflict = Appointment.where(physician:, scheduled_at:).where.not(id:)
+    errors.add(:scheduled_at, "physician already has appointment") if conflict.exists?
+  end
+end
+
+class Patient < ApplicationRecord
+  has_many :appointments, dependent: :destroy
+  has_many :physicians, through: :appointments
+end
+
+# Migrations
+# create_table :appointments do |t|
+#   t.belongs_to :physician, null: false, foreign_key: true
+#   t.belongs_to :patient, null: false, foreign_key: true
+#   t.datetime :scheduled_at, null: false
+#   t.text :notes
+#   t.timestamps
+# end
+# add_index :appointments, [:physician_id, :scheduled_at], unique: true
+
+# ============================================
+# Usage Examples
+# ============================================
+
+# Creating through association
+physician = Physician.find(1)
+patient = Patient.find(1)
+
+# Via join model
+appointment = Appointment.create!(
+  physician:,
+  patient:,
+  scheduled_at: 1.day.from_now
+)
+
+# Shortcut - creates join record automatically
+physician.patients << patient  # Creates Appointment
+
+# With join model attributes
+physician.appointments.create!(
+  patient:,
+  scheduled_at: 2.days.from_now,
+  notes: "Follow-up visit"
+)
+
+# Querying through
+physician.patients.where(name: "John")
+physician.appointments.upcoming
+
+# ============================================
+# has_one :through
+# ============================================
+
+# Supplier -> Account -> AccountHistory
+
+class Supplier < ApplicationRecord
+  has_one :account
+  has_one :account_history, through: :account
+end
+
+class Account < ApplicationRecord
+  belongs_to :supplier
+  has_one :account_history
+end
+
+class AccountHistory < ApplicationRecord
+  belongs_to :account
+end
+
+# Usage
+supplier = Supplier.first
+supplier.account_history  # One query through Account
+
+# ============================================
+# Nested has_many :through
+# ============================================
+
+# Document -> Section -> Paragraph
+
+class Document < ApplicationRecord
+  has_many :sections
+  has_many :paragraphs, through: :sections
+end
+
+class Section < ApplicationRecord
+  belongs_to :document
+  has_many :paragraphs
+end
+
+class Paragraph < ApplicationRecord
+  belongs_to :section
+end
+
+# Access all paragraphs in document
+document.paragraphs
+
+# ============================================
+# Inverse Of - Critical for Nested Attributes
+# ============================================
+
+class Invoice < ApplicationRecord
+  has_many :line_items, inverse_of: :invoice  # REQUIRED!
+  accepts_nested_attributes_for :line_items
+
+  validates :total, presence: true
+end
+
+class LineItem < ApplicationRecord
+  belongs_to :invoice
+  validates :invoice, presence: true  # Fails without inverse_of!
+end
+
+# Without inverse_of:
+# Invoice.create!(line_items_attributes: [{...}])
+# => ValidationFailed: Invoice can't be blank
+
+# With inverse_of:
+# Invoice.create!(line_items_attributes: [{...}])
+# => Success! Rails knows line_item.invoice is the parent
+
+# ============================================
+# Source Option - When Names Don't Match
+# ============================================
+
+class Person < ApplicationRecord
+  has_many :readings
+  has_many :articles, through: :readings, source: :post  # post, not article
+end
+
+class Reading < ApplicationRecord
+  belongs_to :person
+  belongs_to :post  # Not called "article"
+end
+
+# ============================================
+# HABTM vs Through Comparison
+# ============================================
+
+# HABTM - Simple but limited
+class Assembly < ApplicationRecord
+  has_and_belongs_to_many :parts
+end
+
+class Part < ApplicationRecord
+  has_and_belongs_to_many :assemblies
+end
+
+# has_many :through - Flexible (PREFERRED)
+class Assembly < ApplicationRecord
+  has_many :assembly_parts
+  has_many :parts, through: :assembly_parts
+end
+
+class AssemblyPart < ApplicationRecord
+  belongs_to :assembly
+  belongs_to :part
+
+  # Can add attributes later!
+  # quantity, position, notes, etc.
+end
+
+class Part < ApplicationRecord
+  has_many :assembly_parts
+  has_many :assemblies, through: :assembly_parts
+end

data/skills/activerecord/examples/basics/crud_operations.rb

@@ -0,0 +1,209 @@
+# ActiveRecord CRUD Operations Examples
+
+# =============================================================================
+# CREATE
+# =============================================================================
+
+# Two-step creation
+user = User.new
+user.name = "Alice"
+user.email = "alice@example.com"
+if user.save
+  puts "User created: #{user.id}"
+else
+  puts "Errors: #{user.errors.full_messages}"
+end
+
+# One-step creation
+user = User.create(name: "Bob", email: "bob@example.com")
+if user.persisted?
+  puts "User created: #{user.id}"
+end
+
+# With block
+user = User.create(email: "charlie@example.com") do |u|
+  u.name = "Charlie"
+  u.role = :admin
+end
+
+# Bang methods (raise on failure)
+begin
+  user = User.create!(name: "", email: "invalid")
+rescue ActiveRecord::RecordInvalid => e
+  puts "Validation failed: #{e.message}"
+end
+
+# Bulk insert (skips validations and callbacks)
+User.insert_all([
+  { name: "User 1", email: "user1@example.com", created_at: Time.current, updated_at: Time.current },
+  { name: "User 2", email: "user2@example.com", created_at: Time.current, updated_at: Time.current }
+])
+
+# Upsert (insert or update on conflict)
+User.upsert_all(
+  [{ email: "alice@example.com", name: "Alice Updated" }],
+  unique_by: :email
+)
+
+# =============================================================================
+# READ
+# =============================================================================
+
+# find - raises RecordNotFound if not found
+user = User.find(1)
+
+# find with multiple IDs
+users = User.find([1, 2, 3])  # Returns array, raises if ANY not found
+
+# find_by - returns nil if not found
+user = User.find_by(email: "alice@example.com")
+user = User.find_by(status: :active, role: :admin)
+
+# find_by! - raises if not found
+user = User.find_by!(email: "nonexistent@example.com")
+
+# where - returns Relation
+users = User.where(active: true)
+users = User.where("created_at > ?", 1.week.ago)
+users = User.where(role: [:admin, :moderator])
+
+# Chainable queries
+users = User
+  .where(active: true)
+  .where.not(role: :guest)
+  .order(created_at: :desc)
+  .limit(10)
+
+# First/last
+user = User.first
+user = User.last
+user = User.order(:name).first(5)  # First 5 by name
+
+# Take (no order guarantee, faster)
+user = User.take
+users = User.take(3)
+
+# =============================================================================
+# UPDATE
+# =============================================================================
+
+# Standard update (with validations and callbacks)
+user = User.find(1)
+user.update(name: "New Name")
+
+# Update with bang (raises on failure)
+user.update!(name: "New Name")
+
+# Multiple attributes
+user.update(
+  name: "New Name",
+  email: "newemail@example.com",
+  settings: { theme: "dark" }
+)
+
+# Update attribute (skips validations, runs callbacks)
+user.update_attribute(:verified, true)
+
+# Update column (skips validations AND callbacks)
+user.update_column(:login_count, user.login_count + 1)
+
+# Update columns (multiple)
+user.update_columns(
+  login_count: user.login_count + 1,
+  last_login_at: Time.current
+)
+
+# Conditional update
+user.update(status: :premium) if user.eligible_for_premium?
+
+# Bulk update (skips validations and callbacks)
+User.where(status: :trial).update_all(status: :expired)
+User.where("last_login_at < ?", 1.year.ago).update_all(active: false)
+
+# Update with SQL expression
+User.update_all("login_count = login_count + 1")
+
+# =============================================================================
+# DELETE / DESTROY
+# =============================================================================
+
+# Destroy (with callbacks and dependent associations)
+user = User.find(1)
+user.destroy
+puts user.destroyed?  # => true
+puts user.frozen?     # => true
+
+# Delete (skip callbacks, orphans dependent records)
+user = User.find(2)
+user.delete
+
+# Bulk destroy (with callbacks)
+User.where(status: :banned).destroy_all
+
+# Bulk delete (without callbacks)
+User.where(status: :banned).delete_all
+
+# Delete by ID
+User.destroy(5)       # With callbacks
+User.delete(5)        # Without callbacks
+
+# =============================================================================
+# FIND OR CREATE
+# =============================================================================
+
+# Find or create
+user = User.find_or_create_by(email: "alice@example.com")
+
+# With additional attributes via block
+user = User.find_or_create_by(email: "alice@example.com") do |u|
+  u.name = "Alice"
+  u.role = :member
+end
+
+# Find or initialize (doesn't save)
+user = User.find_or_initialize_by(email: "newuser@example.com")
+user.name = "New User"
+user.save if user.new_record?
+
+# Create or find (handles race conditions - requires unique constraint)
+user = User.create_or_find_by(email: "alice@example.com") do |u|
+  u.name = "Alice"
+end
+
+# =============================================================================
+# PRACTICAL PATTERNS
+# =============================================================================
+
+# Safe lookup with fallback
+def find_user(id)
+  User.find_by(id:) || User.new(name: "Guest")
+end
+
+# Idempotent create
+def ensure_default_category
+  Category.find_or_create_by!(name: "Uncategorized") do |c|
+    c.slug = "uncategorized"
+    c.position = 0
+  end
+end
+
+# Soft delete pattern
+class User < ApplicationRecord
+  scope :active, -> { where(deleted_at: nil) }
+  scope :deleted, -> { where.not(deleted_at: nil) }
+
+  def soft_delete
+    update(deleted_at: Time.current)
+  end
+
+  def restore
+    update(deleted_at: nil)
+  end
+end
+
+# Increment/decrement counters
+user.increment!(:login_count)
+user.decrement!(:credits)
+
+# Toggle boolean
+user.toggle!(:email_notifications)