rails-hyperdrive-layered-rails 0.1.0

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/active-delivery.md

@@ -0,0 +1,221 @@
+# Active Delivery
+
+Abstraction layer over delivery mechanisms (email, push, SMS, etc.).
+
+**GitHub**: https://github.com/palkan/active_delivery
+**Layer**: Application (delivery classes) / Infrastructure (notifiers)
+
+## Contents
+
+- Installation
+- Basic Usage
+- Multiple Channels
+- Conditional Delivery
+- User Preferences
+- Custom Delivery Lines
+- Testing
+- Inline Mode (Development)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "active_delivery"
+
+# Generate delivery
+rails generate delivery Posts
+```
+
+## Basic Usage
+
+### Define Delivery
+
+```ruby
+# app/deliveries/posts_delivery.rb
+class PostsDelivery < ApplicationDelivery
+  deliver_by :mailer
+
+  def published(post)
+    params(post: post, author: post.author)
+  end
+
+  def commented(post, comment)
+    params(post: post, comment: comment, author: post.author)
+  end
+end
+```
+
+### Define Mailer
+
+```ruby
+# app/mailers/posts_mailer.rb
+class PostsMailer < ApplicationMailer
+  def published
+    @post = params[:post]
+    @author = params[:author]
+
+    mail(to: @author.email, subject: "Your post is published!")
+  end
+
+  def commented
+    @post = params[:post]
+    @comment = params[:comment]
+
+    mail(to: params[:author].email, subject: "New comment on your post")
+  end
+end
+```
+
+### Trigger Delivery
+
+```ruby
+# Deliver later (async)
+PostsDelivery.with(post: post).published.deliver_later
+
+# Deliver now (sync)
+PostsDelivery.with(post: post).published.deliver_now
+```
+
+## Multiple Channels
+
+```ruby
+class PostsDelivery < ApplicationDelivery
+  deliver_by :mailer
+  deliver_by :push, to: PushNotifier
+  deliver_by :slack, to: SlackNotifier
+
+  def published(post)
+    params(post: post, author: post.author)
+  end
+end
+
+# Push notifier
+class PushNotifier < AbstractNotifier::Base
+  self.driver = PushDriver.new
+
+  def published
+    notification(
+      user: params[:author],
+      title: "Post Published",
+      body: "Your post '#{params[:post].title}' is now live!"
+    )
+  end
+end
+
+# Slack notifier
+class SlackNotifier < AbstractNotifier::Base
+  self.driver = SlackDriver.new
+
+  def published
+    notification(
+      channel: "#content",
+      text: "New post: #{params[:post].title}"
+    )
+  end
+end
+```
+
+## Conditional Delivery
+
+```ruby
+class PostsDelivery < ApplicationDelivery
+  deliver_by :mailer
+  deliver_by :push, if: :push_enabled?
+  deliver_by :slack, if: -> { params[:post].featured? }
+
+  private
+
+  def push_enabled?
+    params[:author]&.push_notifications_enabled?
+  end
+end
+```
+
+## User Preferences
+
+```ruby
+class ApplicationDelivery < ActiveDelivery::Base
+  deliver_by :mailer, if: :email_enabled?
+  deliver_by :push, if: :push_enabled?
+
+  private
+
+  def recipient
+    params[:user] || params[:recipient] || params[:author]
+  end
+
+  def email_enabled?
+    recipient&.email_notifications?
+  end
+
+  def push_enabled?
+    recipient&.push_notifications?
+  end
+end
+```
+
+## Custom Delivery Lines
+
+```ruby
+# Webhook delivery
+class WebhookLine < ActiveDelivery::Lines::Base
+  def resolve_class(name)
+    "#{name}Webhook".safe_constantize
+  end
+
+  def notify(handler, mid, **options)
+    handler.public_send(mid)&.deliver
+  end
+end
+
+ActiveDelivery::Base.register_line :webhook, WebhookLine
+
+class PostsDelivery < ApplicationDelivery
+  deliver_by :webhook
+end
+
+class PostsWebhook
+  def published
+    # Send webhook
+  end
+end
+```
+
+## Testing
+
+```ruby
+RSpec.describe PostsDelivery do
+  let(:post) { create(:post) }
+
+  describe "#published" do
+    it "delivers email" do
+      expect {
+        described_class.with(post: post).published.deliver_now
+      }.to have_delivered_to(PostsMailer, :published)
+    end
+
+    it "delivers push notification when enabled" do
+      post.author.update!(push_notifications: true)
+
+      expect {
+        described_class.with(post: post).published.deliver_now
+      }.to have_delivered_to(PushNotifier, :published)
+    end
+
+    it "skips push when disabled" do
+      post.author.update!(push_notifications: false)
+
+      expect {
+        described_class.with(post: post).published.deliver_now
+      }.not_to have_delivered_to(PushNotifier, :published)
+    end
+  end
+end
+```
+
+## Inline Mode (Development)
+
+```ruby
+# config/environments/development.rb
+config.active_delivery.deliver_later_queue_adapter = :inline
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/active-job-performs.md

@@ -0,0 +1,171 @@
+# active_job-performs
+
+Eliminate boilerplate job classes by declaring background methods directly on models.
+
+**Repository:** [kaspth/active_job-performs](https://github.com/kaspth/active_job-performs)
+
+## Contents
+
+- When to Use
+- The `performs` Pattern
+- Detection Signals
+- Configuration
+- Application-Wide `performs` Patterns
+- When NOT to Use
+- Migration Path
+- Layer Placement
+
+## When to Use
+
+Use when you have **anemic jobs** - job classes that just call a single method on a model:
+
+```ruby
+# BAD: Anemic job
+class NotifyRecipientsJob < ApplicationJob
+  def perform(notifiable)
+    notifiable.notify_recipients
+  end
+end
+
+# BAD: Model method just to enqueue job
+class Post < ApplicationRecord
+  def notify_recipients_later
+    NotifyRecipientsJob.perform_later(self)
+  end
+end
+```
+
+## The `performs` Pattern
+
+Replace anemic jobs with `performs`:
+
+```ruby
+# GOOD: Short form (no job options needed)
+class Post < ApplicationRecord
+  performs def notify_recipients
+    # Notification logic
+  end
+end
+
+# Usage
+post.notify_recipients_later
+```
+
+This generates:
+- `Post::NotifyRecipientsJob` (automatically)
+- `notify_recipients_later` instance method
+- `notify_recipients_later_bulk` class method (Rails 7.1+)
+
+### When to Use Short vs Long Form
+
+**Short form** - when no job configuration needed:
+```ruby
+performs def sync_with_provider
+  # Simple async execution
+end
+```
+
+**Long form** - when job options are required:
+```ruby
+performs :sync_with_provider, queue_as: :critical, discard_on: ApiError
+
+def sync_with_provider
+  # ...
+end
+```
+
+## Detection Signals
+
+**Anemic job indicators:**
+- Job's `perform` method is a single line calling a method on the argument
+- Model has `*_later` method that just calls `SomeJob.perform_later(self)`
+- Job class has no logic beyond delegation
+- Job folder has many similar thin wrapper jobs
+
+## Configuration
+
+### Job Options
+
+```ruby
+class Post < ApplicationRecord
+  performs :publish,
+           queue_as: :critical,
+           discard_on: ActiveRecord::RecordNotFound do
+    retry_on TimeoutError, wait: :polynomially_longer
+  end
+
+  def publish
+    # ...
+  end
+end
+```
+
+### Delayed Execution
+
+```ruby
+class Post < ApplicationRecord
+  performs :social_boost, wait: 5.minutes
+  performs :publish, wait_until: -> post { Date.tomorrow.noon }
+
+  def social_boost; end
+  def publish; end
+end
+```
+
+### Private Methods
+
+```ruby
+class Post < ApplicationRecord
+  performs :sync_to_warehouse
+
+  private
+
+  def sync_to_warehouse
+    # Only accessible via sync_to_warehouse_later
+  end
+end
+```
+
+### Method Suffixes
+
+```ruby
+class Post < ApplicationRecord
+  performs :publish!   # Creates publish_later!
+  performs :dangerous? # Creates dangerous_later?
+end
+```
+
+## Application-Wide `performs` Patterns
+
+Define common async operations in `ApplicationRecord`:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+
+  performs :destroy, queue_as: "active_record.destroy"
+end
+
+# Any model can now use:
+post.destroy_later
+```
+
+## When NOT to Use
+
+Keep separate job classes when:
+- Job has complex logic beyond calling one method
+- Job processes multiple records with custom batching
+- Job needs to be triggered from multiple models
+- Job has extensive retry/error handling configuration
+
+## Migration Path
+
+1. Identify anemic jobs (single method delegation)
+2. Add `performs :method_name` to the model
+3. Replace `SomeJob.perform_later(record)` with `record.method_name_later`
+4. Delete the job file
+5. Delete any `*_later` wrapper methods
+
+## Layer Placement
+
+The `performs` declaration belongs in the **Domain Layer** (model), keeping the async execution detail close to the domain logic it executes.

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/alba.md

@@ -0,0 +1,257 @@
+# Alba
+
+Fast JSON serialization with a clean DSL.
+
+**GitHub**: https://github.com/okuramasafumi/alba
+**Layer**: Presentation (API layer)
+
+## Contents
+
+- Installation
+- Basic Usage
+- Associations
+- Conditional Attributes
+- Computed Attributes
+- Root Key
+- Base Serializer
+- Key Transformation
+- TypeScript Generation
+- Performance Tips
+- Testing
+
+## Installation
+
+```ruby
+# Gemfile
+gem "alba"
+```
+
+## Basic Usage
+
+### Define Serializer
+
+```ruby
+class UserSerializer
+  include Alba::Resource
+
+  attributes :id, :email
+
+  attribute :full_name do |user|
+    "#{user.first_name} #{user.last_name}"
+  end
+end
+```
+
+### Serialize
+
+```ruby
+user = User.find(1)
+UserSerializer.new(user).serialize
+# => '{"id":1,"email":"user@example.com","full_name":"John Doe"}'
+
+# Collection
+users = User.all
+UserSerializer.new(users).serialize
+# => '[{"id":1,...},{"id":2,...}]'
+```
+
+### In Controller
+
+```ruby
+class UsersController < ApplicationController
+  def show
+    user = User.find(params[:id])
+    render json: UserSerializer.new(user)
+  end
+
+  def index
+    users = User.all
+    render json: UserSerializer.new(users)
+  end
+end
+```
+
+## Associations
+
+```ruby
+class PostSerializer
+  include Alba::Resource
+
+  attributes :id, :title, :body
+
+  # Nested serializer
+  one :author, resource: UserSerializer
+
+  # Collection
+  many :comments, resource: CommentSerializer
+
+  # Inline definition
+  many :tags do
+    attributes :id, :name
+  end
+end
+```
+
+## Conditional Attributes
+
+```ruby
+class UserSerializer
+  include Alba::Resource
+
+  attributes :id, :name, :email
+
+  # Conditional attribute
+  attribute :admin_notes, if: proc { |user, context|
+    context[:current_user]&.admin?
+  }
+
+  # Method-based condition
+  attribute :phone, if: :show_phone?
+
+  def show_phone?(user)
+    user.phone_public?
+  end
+end
+
+# Pass context
+UserSerializer.new(user, params: { current_user: current_user }).serialize
+```
+
+## Computed Attributes
+
+```ruby
+class PostSerializer
+  include Alba::Resource
+
+  attributes :id, :title
+
+  attribute :is_published do |post|
+    post.published_at.present?
+  end
+
+  attribute :reading_time do |post|
+    (post.body.split.size / 200.0).ceil
+  end
+
+  attribute :url do |post|
+    Rails.application.routes.url_helpers.post_url(post)
+  end
+end
+```
+
+## Root Key
+
+```ruby
+class UserSerializer
+  include Alba::Resource
+
+  root_key :user, :users  # singular, plural
+
+  attributes :id, :name
+end
+
+UserSerializer.new(user).serialize
+# => '{"user":{"id":1,"name":"John"}}'
+
+UserSerializer.new(users).serialize
+# => '{"users":[{"id":1,"name":"John"},...]}'
+```
+
+## Base Serializer
+
+```ruby
+class ApplicationSerializer
+  include Alba::Resource
+  include Rails.application.routes.url_helpers
+
+  # Common configuration
+  transform_keys :lower_camel
+
+  # Helper available to all serializers
+  def current_time
+    Time.current.iso8601
+  end
+end
+
+class UserSerializer < ApplicationSerializer
+  attributes :id, :name
+
+  attribute :serialized_at do
+    current_time
+  end
+end
+```
+
+## Key Transformation
+
+```ruby
+class UserSerializer
+  include Alba::Resource
+
+  # Transform all keys
+  transform_keys :lower_camel  # firstName
+  transform_keys :dash         # first-name
+
+  attributes :first_name, :last_name  # becomes firstName, lastName
+end
+```
+
+## TypeScript Generation
+
+With typelizer:
+
+```ruby
+# Gemfile
+gem "typelizer"
+
+class ApplicationSerializer
+  include Alba::Resource
+  include Typelizer::DSL
+end
+
+class UserSerializer < ApplicationSerializer
+  typelize_from User
+
+  attributes :id, :email
+  attribute :is_admin, &:admin?
+end
+```
+
+Generated TypeScript:
+
+```typescript
+interface User {
+  id: number;
+  email: string;
+  is_admin: boolean;
+}
+```
+
+## Performance Tips
+
+```ruby
+# Use select to avoid loading unused columns
+users = User.select(:id, :name, :email)
+UserSerializer.new(users).serialize
+
+# Preload associations
+posts = Post.includes(:author, :comments)
+PostSerializer.new(posts).serialize
+```
+
+## Testing
+
+```ruby
+RSpec.describe UserSerializer do
+  let(:user) { create(:user, first_name: "John", last_name: "Doe") }
+  let(:serialized) { JSON.parse(described_class.new(user).serialize) }
+
+  it "includes expected attributes" do
+    expect(serialized).to include(
+      "id" => user.id,
+      "email" => user.email,
+      "full_name" => "John Doe"
+    )
+  end
+end
+```