axn 0.1.0.pre.alpha.2.8 → 0.1.0.pre.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 309f7b8f6587d121756b8c3ad5d1bf8d5ba7689935920a5cd7f8c791f4bf38c4
-  data.tar.gz: '08f91a0d7344b04df8db6d9bb74bdbfb4fd095deb8dba8a105e8211dbaaa2ce0'
+  metadata.gz: 62c8aec52fd200af8f2c3a7cd19c9a589c5353bca7bd6ed6ca08dbc990b381af
+  data.tar.gz: 0bae864b6bf77b4f5200f2671bbed65ff8fea1f22fbbaa9985e088d4be82d767
 SHA512:
-  metadata.gz: 1abdb9efc00cf6c9be0d73094c59a1322e84ca51968cf2d66af76178693db5c2fd20e99c2e2a0ee149665b92dd69ac7a3ed886ecd8567d2389b9e447978f79ac
-  data.tar.gz: 241899334f89065dec935093bbf1277a07b81101855d78e4ab56511af8561814abd372506c2f9f6df762cc79f8b1971000bfc3b425c35db8f09d3faa4d70336c
+  metadata.gz: 6fa6cabde451cec1eda5600f29131cbe78b7f0e66742bed84257e83d0b45418fc300452b24147a9bb4f319710c87da02ac541c17312e17993e1ea636c09b52c6
+  data.tar.gz: 4ee9dd287f81d027e0538fa94c959ffca9e560274a7d558196f163e7569f9ea7eae996857c55f5b0453a3a876863fa5b384171d368907c1c1c53ec30f72366ea

data/.cursor/rules/axn-framework-patterns.mdc

@@ -0,0 +1,43 @@
+# Axn Framework Usage Patterns
+
+## Basic Action Structure
+- Always include `Axn` module: `class MyAction; include Axn; end`
+- Declare interface with `expects` and `exposes` at class level
+- Implement `call` method for action logic
+- Use `expose` to return data (must be declared in `exposes` first)
+- Use `fail!` for expected failures, `done!` for early success completion
+
+## Execution Patterns
+- Use `call` for result objects (swallows exceptions, returns `Axn::Result`)
+- Use `call!` for exception-throwing behavior (re-raises exceptions)
+- Use `call_async` for background execution (requires async configuration)
+
+## Data Flow and Validation
+- `expects` declares required input parameters with validation options
+- `exposes` declares output data that must be provided via `expose`
+- Common validation options: `type:`, `optional:`, `allow_nil:`, `allow_blank:`, `default:`, `sensitive:`
+- Use `model: true` for auto-hydrating records from IDs
+- Use `on:` for nested field expectations and accessors
+
+## Composition Patterns
+- Use `step :name, expects: [:input], exposes: [:output]` for inline steps
+- Use `steps(Class1, Class2)` to compose existing action classes
+- Steps execute sequentially and share data through `expects`/`exposes`
+- Step failures are automatically prefixed with step name
+
+## Message and Error Handling
+- Use `success` and `error` declarations for custom messages
+- Support conditional messages with `if:`/`unless:` matchers
+- Use `from:` parameter for error message inheritance from child actions
+- Use `prefix:` for consistent error message formatting
+- Define static messages first, then conditional messages
+
+## Async and Background Processing
+- Configure with `async :sidekiq` or `async :active_job`
+- Use `call_async` for background execution
+- Supports all adapter-specific configuration options
+
+## Hooks and Callbacks
+- Hooks (`before`/`after`/`around`) execute as part of `call` - failures affect `result.ok?`
+- Callbacks (`on_success`/`on_error`/`on_failure`/`on_exception`) execute after `call` - failures don't affect `result.ok?`
+- Use `done!` for early completion (skips `after` hooks, allows `around` hooks to complete)

data/.cursor/rules/general-coding-standards.mdc

@@ -0,0 +1,27 @@
+# General Coding Standards
+
+## Code Quality Principles
+- Always prioritize clean, elegant, and maintainable code following these principles:
+- Write code that is both functional and beautiful - elegance should be a primary concern
+- Follow existing patterns in the codebase
+- Use DRY principles and eliminate duplication
+- Create reusable/shared examples for similar test patterns
+- Consolidate similar functionality where appropriate
+- Match existing code style and structure
+- Consider maintainability and extensibility first
+- Look for refactoring opportunities
+- Use parameterized testing and shared examples in specs
+- Prefer simple, readable solutions over clever but complex ones
+- Write code that tells a story and is self-documenting
+
+## Method Organization
+- Place private method declarations under a private stanza rather than marking them private after the fact
+- Use single-line changelog edits
+- Use Ruby endless method definitions for short helper methods
+- Use a series of return-early if statements instead of long if/else chains for stylistic consistency
+
+## Communication Style
+- Be direct, neutral, and concise
+- Be sparing with praise, flattery, or enthusiasm
+- Do not say the user is right unless verified; confirm first
+- Prefer: "It appears/It seems/Based on X…" over absolute claims

data/.cursor/rules/spec/testing-patterns.mdc

@@ -0,0 +1,40 @@
+# RSpec Testing Patterns
+
+## Use build_axn Spec Helper
+- Always use the `build_axn` spec helper instead of manually creating Axn classes
+- Prefer `build_axn { ... }` over `Axn::Factory.build { ... }` in test files
+- Prefer `build_axn { ... }` over `Class.new.send(:include, Axn)` patterns
+- The `build_axn` helper is already included via `Axn::Testing::SpecHelpers` and provides a cleaner, more readable way to create test Axn classes
+
+## DRY Test Setup
+- When writing RSpec tests with repeated object creation patterns, prefer using `let`/`let!` to define base objects once and override specific attributes in contexts
+- Use shared examples (`shared_examples`/`include_examples`) for testing similar methods with different parameters
+- Avoid recreating the same object structure multiple times - use `let` to override only the values that change between contexts
+
+### Example Pattern:
+```ruby
+# Instead of recreating objects in each context:
+context "scenario 1" do
+  let!(:object) { create(:model, attr1: value1, attr2: value2) }
+end
+context "scenario 2" do
+  let!(:object) { create(:model, attr1: value3, attr2: value4) }
+end
+
+# Prefer this pattern:
+let!(:object) { create(:model, attr1: attr1_value, attr2: attr2_value) }
+context "scenario 1" do
+  let(:attr1_value) { value1 }
+  let(:attr2_value) { value2 }
+end
+context "scenario 2" do
+  let(:attr1_value) { value3 }
+  let(:attr2_value) { value4 }
+end
+```
+
+## Test Organization
+- Use `it { expect(...).to eq(...) }` shorthand for simple assertions. `it { is_expected.to ... }` even better.
+- Group related tests with shared examples when testing similar methods
+- Prefer descriptive context names over verbose test descriptions
+- Don't open rails console - debug via scripts or runner instead.

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## Unreleased
+* N/A
+
+## 0.1.0-alpha.3
+* [FEAT] Added Vernier profiling support with `profile if:` conditional interface and `Axn.config.profiling` configuration
+* [FEAT] Extended model validation to support custom finder methods with `expects :user, model: { klass: User, finder: :find }` syntax
+* [BREAKING] Removed `#try` method
+* [BREAKING] Removed `Axn()` method sugar (use `Axn::Factory.build` directly)
+* [BREAKING] Renamed `Action::Configuration` + `Action.config` -> `Axn::Configuration` + `Axn.config`
+* [BREAKING] Move `Axn::Util` to `Axn::Internal::Logging`
+* [BREAKING] !! Move all `Action` to `Axn` (notably `include Action` is now `include Axn`)
+* [FEAT] Continues to support plain ruby usage, but when used alongside Rails now includes a Rails Engine integrate automatically (e.g. providing generators).
+  * Added Rails generator `rails generate axn Some::Action::Name foo bar` to create action classes with expectations
+  * Autoload actions from `app/actions` (add config.rails.app_actions_autoload_namespace to allow setting custom namespace)
+* [INTERNAL] Clearer hooks for supporting additional background providers in the future
+* [BREAKING] spec_helpers: removed rarely used `build_axn`; renamed existing `build_action` -> `build_axn`
+* [FEAT] `Axn::Factory.build` can receive a callable OR a block
+* [FEAT] Added `#finalized?` method to `Axn::Result` to check if result has completed execution
+* [FEAT] Added `type: :params` validation option for `expects`/`exposes` that accepts Hash or ActionController::Parameters (Rails-compatible)
+* [FEAT] Allow validations to access instance methods (e.g. `inclusion: { in: :some_method }`)
+* [FEAT] Allow message `prefix` to invoke callables/method name symbols the same way e.g. `if` does
+* [BREAKING] `default`s for `expects` and `exposes` are only applied to explicitly `nil` values (previous applied if given value was blank, which caused bugs for boolean handling)
+* [FEAT] Support `sensitive: true` on subfields (with `on:`)
+* [FEAT] Support `preprocess` on subfields (with `on:`)
+* [FEAT] Support `default` on subfields (with `on:`)
+* [FEAT] Added `#done!` method for early completion with success result
+* [FEAT] Extended `#fail!` and `#done!` methods to accept keyword arguments for exposing data before halting execution
+* [INTERAL] Renamed `Axn::Enqueueable` to `Axn::Async`
+* [BREAKING] Replaced `.enqueue` (only supported sidekiq) with `.call_async` (via a configurable registry of backgrounding libraries)
+* [FEAT] attachable now creates a foo_async to call call_async
+* `type` validator is not still applied to the blank value when allow_blank is true (`type: Hash` will no longer accept `false` or `""`)
+* [FEAT] `expects`/`exposes` now prefers new `optional: true` over allow_blank for simplicity
+* [FEAT] `Axn::Result` now supports Ruby 3's pattern matching feature
+* [FEAT] Extended attachable functionality: added `mount_axn_method` for creating class methods that return values directly instead of wrapped in `Axn::Result`
+* [Internal] Replaced `Axn::Attachable` with `Axn::Mountable` - complete refactor of action mounting system
+  * [BREAKING] `#axn` → `#mount_axn` for method mounting
+  * [BREAKING] `#axn_method` → `#mount_axn_method` for direct method mounting
+  * [NEW] `enqueue_all_via` - Mount batch enqueueing functionality for background job processing
+* [FEAT] Enhanced async execution with job scheduling support
+  * [NEW] Support for scheduled async jobs via `_async` parameter with `wait_until:` and `wait:` options
+  * [NEW] `enqueue` shortcut methods for all mounted actions
+
+## 0.1.0-alpha.2.8.1
+* [BUGFIX] Fixed symbol callback and message handlers not working in inherited classes due to private method visibility issues
+* [BUGFIX] `default_error` and `default_success` are now properly available for before hooks
+* [FEAT] Support scheduling async jobs (via new `_async` key)
+
 ## 0.1.0-alpha.2.8
 * [FEAT] Custom RuboCop cop `Axn/UncheckedResult` to enforce proper result handling in Actions with configurable nested/non-nested checking
 * [FEAT] Added `prefix:` keyword support to `error` method for customizing error message prefixes

data/Rakefile

@@ -10,10 +10,17 @@ RSpec::Core::RakeTask.new(:spec_rubocop) do |task|
   task.pattern = "spec_rubocop/**/*_spec.rb"
 end
 
+# Rails specs (separate from main specs to avoid loading Rails unnecessarily)
+task :spec_rails do
+  Dir.chdir("spec_rails/dummy_app") do
+    sh "BUNDLE_GEMFILE=Gemfile bundle exec rspec spec/"
+  end
+end
+
 require "rubocop/rake_task"
 
 # RuboCop with Axn custom cops (targeting examples/rubocop directory)
-task :rubocop_axn do
+task :rubocop_examples do
   sh "bundle exec rubocop --require axn/rubocop examples/rubocop/ || true"
 end
 
@@ -21,4 +28,7 @@ end
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
-task all_specs: %i[spec spec_rubocop]
+task rails_specs: %i[spec_rails]
+task rubocop_specs: %i[spec_rubocop]
+task all_specs: %i[spec spec_rubocop spec_rails]
+task specs: %i[all_specs]

data/docs/.vitepress/config.mjs

@@ -28,6 +28,7 @@ export default defineConfig({
           { text: 'Getting Started', link: '/usage/setup' },
           { text: 'Writing Actions', link: '/usage/writing' },
           { text: 'Using Actions', link: '/usage/using' },
+          { text: 'Steps', link: '/usage/steps' },
         ]
       },
       {
@@ -36,7 +37,8 @@ export default defineConfig({
           { text: 'Configuration', link: '/reference/configuration' },
           { text: 'Class Interface', link: '/reference/class' },
           { text: 'Instance Interface', link: '/reference/instance' },
-          { text: 'Result Interface', link: '/reference/action-result' },
+          { text: 'Result Interface', link: '/reference/axn-result' },
+          { text: 'Async', link: '/reference/async' },
         ]
       },
       {
@@ -45,6 +47,7 @@ export default defineConfig({
           { text: 'Memoization', link: '/recipes/memoization' },
           { text: 'Validating User Input', link: '/recipes/validating-user-input' },
           { text: 'Testing Actions', link: '/recipes/testing' },
+          { text: 'RuboCop Integration', link: '/recipes/rubocop-integration' },
         ]
       },
       {
@@ -55,10 +58,12 @@ export default defineConfig({
         ]
       },
       {
-        text: 'Additional Notes',
+        text: 'Advanced',
         items: [
-          { text: 'ROUGH NOTES', link: '/advanced/rough' },
+          { text: 'Profiling', link: '/advanced/profiling' },
           { text: 'Conventions', link: '/advanced/conventions' },
+          { text: 'Mountable', link: '/advanced/mountable' },
+          { text: 'ROUGH NOTES', link: '/advanced/rough' },
         ]
       },
     ],

data/docs/advanced/conventions.md

@@ -26,13 +26,13 @@ For us, we've found the maintenance benefits of knowing roughly how the class wi
 ## Naming conventions
 
 ### The responsible user
-When tracking _who_ is responsible for the action being taken, one option is to inject it globally via `Current.user` (see: [Current Attributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html)), but that only works if you're _sure_ you're never going to want to enqueue the job on a background processor.
+When tracking _who_ is responsible for the action being taken, one option is to inject it globally via `Current.user` (see: [Current Attributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html)), but that only works if you're _sure_ you're never going to want to execute the action asynchronously on a background processor.
 
 More generally, we've adopted the convention of passing in the responsible user as `actor`:
 
   ```ruby
   class Foo
-    include Action
+    include Axn
     expects :actor, type: User # [!code focus]
   end
   ```