cmdx 1.1.1 → 1.5.0

data/docs/tips_and_tricks.md

@@ -1,25 +1,16 @@
-# Tips & Tricks
+# Tips and Tricks
 
 This guide covers advanced patterns and optimization techniques for getting the most out of CMDx in production applications.
 
 ## Table of Contents
 
-- [TLDR](#tldr)
 - [Project Organization](#project-organization)
   - [Directory Structure](#directory-structure)
   - [Naming Conventions](#naming-conventions)
-- [Parameter Optimization](#parameter-optimization)
-  - [Efficient Parameter Definitions](#efficient-parameter-definitions)
-- [Monitoring and Observability](#monitoring-and-observability)
-  - [ActiveRecord Query Tagging](#activerecord-query-tagging)
-
-## TLDR
-
-- **Organization** - Group commands by domain in `/app/commands` with descriptive subdirectories
-- **Naming** - Tasks use "Verb + Noun + Task", workflows use "Noun + Verb + Workflow"
-- **Parameter optimization** - Use `with_options` to reduce duplication in parameter definitions
-- **Monitoring** - Enable ActiveRecord query tagging for better debugging and observability
-- **Base classes** - Create `ApplicationTask` and `ApplicationWorkflow` for shared configuration
+  - [Story Telling](#story-telling)
+  - [Style Guide](#style-guide)
+- [Attribute Options](#attribute-options)
+- [ActiveRecord Query Tagging](#activerecord-query-tagging)
 
 ## Project Organization
 
@@ -27,25 +18,22 @@ This guide covers advanced patterns and optimization techniques for getting the
 
 Create a well-organized command structure for maintainable applications:
 
-```txt
-/app
-  /commands
-    /orders
-      - process_order_task.rb
-      - validate_order_task.rb
-      - fulfill_order_task.rb
-      - order_processing_workflow.rb
-    /notifications
-      - send_email_task.rb
-      - send_sms_task.rb
-      - post_slack_message_task.rb
-      - notification_delivery_workflow.rb
-    /payments
-      - charge_payment_task.rb
-      - refund_payment_task.rb
-      - validate_payment_method_task.rb
-    - application_task.rb
-    - application_workflow.rb
+```text
+/app/
+└── /tasks/
+    ├── /invoices/
+    │   ├── calculate_tax.rb
+    │   ├── validate_invoice.rb
+    │   ├── send_invoice.rb
+    │   └── process_invoice.rb # workflow
+    ├── /reports/
+    │   ├── generate_pdf.rb
+    │   ├── compile_data.rb
+    │   ├── export_csv.rb
+    │   └── create_reports.rb # workflow
+    ├── application_task.rb # base class
+    ├── authenticate_session.rb
+    └── activate_account.rb
 ```
 
 ### Naming Conventions
@@ -53,60 +41,121 @@ Create a well-organized command structure for maintainable applications:
 Follow consistent naming patterns for clarity and maintainability:
 
 ```ruby
-# Tasks: Verb + Noun + Task
-class ProcessOrderTask < CMDx::Task; end
-class SendEmailTask < CMDx::Task; end
-class ValidatePaymentTask < CMDx::Task; end
-
-# Workflows: Noun + Verb + Workflow
-class OrderProcessingWorkflow < CMDx::Workflow; end
-class NotificationDeliveryWorkflow < CMDx::Workflow; end
+# Verb + Noun
+class ExportData < CMDx::Task; end
+class CompressFile < CMDx::Task; end
+class ValidateSchema < CMDx::Task; end
 
 # Use present tense verbs for actions
-class CreateUserTask < CMDx::Task; end      # ✓ Good
-class CreatingUserTask < CMDx::Task; end    # ❌ Avoid
-class UserCreationTask < CMDx::Task; end    # ❌ Avoid
+class GenerateToken < CMDx::Task; end      # ✓ Good
+class GeneratingToken < CMDx::Task; end    # ❌ Avoid
+class TokenGeneration < CMDx::Task; end    # ❌ Avoid
+```
+
+### Story Telling
+
+Consider using descriptive methods to express the task’s flow, rather than concentrating all logic inside the `work` method.
+
+```ruby
+class ProcessOrder < CMDx::Task
+  def work
+    charge_payment_method
+    assign_to_warehouse
+    send_notification
+  end
+
+  private
+
+  def charge_payment_method
+    order.primary_payment_method.charge!
+  end
+
+  def assign_to_warehouse
+    order.ready_for_shipping!
+  end
+
+  def send_notification
+    if order.products_out_of_stock?
+      OrderMailer.pending(order).deliver
+    else
+      OrderMailer.preparing(order).deliver
+    end
+  end
+end
 ```
 
-## Parameter Optimization
+### Style Guide
+
+Follow a style pattern for consistent task design:
 
-### Efficient Parameter Definitions
+```ruby
+class ExportReport < CMDx::Task
+
+  # 1. Register functions
+  register :middleware, CMDx::Middlewares::Correlate
+  register :validator, :format, FormatValidator
+
+  # 2. Define callbacks
+  before_execution :find_report
+  on_complete :track_export_metrics, if: ->(task) { Current.tenant.analytics? }
+
+  # 3. Declare attributes
+  attributes :user_id
+  required :report_id
+  optional :format_type
+
+  # 4. Define work method
+  def work
+    report.compile!
+    report.export!
+
+    context.exported_at = Time.now
+  end
+
+  # TIP: Favor private business logic to reduce the surface of the public API.
+  private
+
+  # 5. Build helper functions
+  def find_report
+    @report ||= Report.find(report_id)
+  end
+
+  def track_export_metrics
+    Analytics.increment(:report_exported)
+  end
+
+end
+```
+
+## Attribute Options
 
 Use Rails `with_options` to reduce duplication and improve readability:
 
 ```ruby
-class UpdateUserProfileTask < CMDx::Task
-  # Apply common options to multiple parameters
+class ConfigureCompany < CMDx::Task
+  # Apply common options to multiple attributes
   with_options(type: :string, presence: true) do
-    required :email, format: { with: URI::MailTo::EMAIL_REGEXP }
-    optional :first_name, :last_name
-    optional :phone, format: { with: /\A\+?[\d\s\-\(\)]+\z/ }
+    attributes :website, format: { with: URI::DEFAULT_PARSER.make_regexp(%w[http https]) }
+    required :company_name, :industry
+    optional :description, format: { with: /\A[\w\s\-\.,!?]+\z/ }
   end
 
-  # Nested parameters with shared prefix
-  required :address do
-    with_options(prefix: :address_) do
-      required :street, :city, :postal_code, type: :string
+  # Nested attributes with shared prefix
+  required :headquarters do
+    with_options(prefix: :hq_) do
+      attributes :street, :city, :zip_code, type: :string
       required :country, type: :string, inclusion: { in: VALID_COUNTRIES }
-      optional :state, type: :string
+      optional :region, type: :string
     end
   end
 
-  # Shared validation rules
-  with_options(type: :integer, numericality: { greater_than: 0 }) do
-    optional :age, numericality: { less_than: 150 }
-    optional :years_experience, numericality: { less_than: 80 }
-  end
-
-  def call
-    # Implementation
+  def work
+    # Your logic here...
   end
 end
 ```
 
-## Monitoring and Observability
-
-### ActiveRecord Query Tagging
+## ActiveRecord Query Tagging
 
 Automatically tag SQL queries for better debugging:
 
@@ -116,13 +165,14 @@ config.active_record.query_log_tags_enabled = true
 config.active_record.query_log_tags << :cmdx_task_class
 config.active_record.query_log_tags << :cmdx_chain_id
 
-# app/commands/application_task.rb
+# app/tasks/application_task.rb
 class ApplicationTask < CMDx::Task
   before_execution :set_execution_context
 
   private
 
   def set_execution_context
+    # NOTE: This could easily be made into a middleware
     ActiveSupport::ExecutionContext.set(
       cmdx_task_class: self.class.name,
       cmdx_chain_id: chain.id
@@ -131,10 +181,10 @@ class ApplicationTask < CMDx::Task
 end
 
 # SQL queries will now include comments like:
-# /*cmdx_task_class:ProcessOrderTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM orders WHERE id = 1
+# /*cmdx_task_class:ExportReportTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM reports WHERE id = 1
 ```
 
 ---
 
-- **Prev:** [AI Prompts](ai_prompts.md)
+- **Prev:** [Workflows](workflows.md)
 - **Next:** [Getting Started](getting_started.md)