axn 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.2

data/lib/axn/factory.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Axn
+  class Factory
+    class << self
+      # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
+      def build(
+        # Builder-specific options
+        superclass: nil,
+        expose_return_as: :nil,
+
+        # Expose standard class-level options
+        exposes: {},
+        expects: {},
+        messages: {},
+        before: nil,
+        after: nil,
+        around: nil,
+
+        # Allow dynamically assigning rollback method
+        rollback: nil,
+        &block
+      )
+        args = block.parameters.each_with_object(_hash_with_default_array) { |(type, name), hash| hash[type] << name }
+
+        if args[:opt].present? || args[:req].present? || args[:rest].present?
+          raise ArgumentError,
+                "[Axn::Factory] Cannot convert block to action: block expects positional arguments"
+        end
+        raise ArgumentError, "[Axn::Factory] Cannot convert block to action: block expects a splat of keyword arguments" if args[:keyrest].present?
+
+        # TODO: is there any way to support default arguments? (if so, set allow_blank: true for those)
+        if args[:key].present?
+          raise ArgumentError,
+                "[Axn::Factory] Cannot convert block to action: block expects keyword arguments with defaults (ruby does not allow introspecting)"
+        end
+
+        expects = _hydrate_hash(expects)
+        exposes = _hydrate_hash(exposes)
+
+        Array(args[:keyreq]).each do |name|
+          expects[name] ||= {}
+        end
+
+        # NOTE: inheriting from wrapping class, so we can set default values (e.g. for HTTP headers)
+        Class.new(superclass || Object) do
+          include Action unless self < Action
+
+          define_method(:call) do
+            unwrapped_kwargs = Array(args[:keyreq]).each_with_object({}) do |name, hash|
+              hash[name] = public_send(name)
+            end
+
+            retval = instance_exec(**unwrapped_kwargs, &block)
+            expose(expose_return_as => retval) if expose_return_as.present?
+          end
+        end.tap do |axn| # rubocop: disable Style/MultilineBlockChain
+          expects.each do |name, opts|
+            axn.expects(name, **opts)
+          end
+
+          exposes.each do |name, opts|
+            axn.exposes(name, **opts)
+          end
+
+          axn.messages(**messages) if messages.present?
+
+          # Hooks
+          axn.before(before) if before.present?
+          axn.after(after) if after.present?
+          axn.around(around) if around.present?
+
+          # Rollback
+          if rollback.present?
+            raise ArgumentError, "[Axn::Factory] Rollback must be a callable" unless rollback.respond_to?(:call) && rollback.respond_to?(:arity)
+            raise ArgumentError, "[Axn::Factory] Rollback must be a callable with no arguments" unless rollback.arity.zero?
+
+            axn.define_method(:rollback) do
+              instance_exec(&rollback)
+            end
+          end
+
+          # Default exposure
+          axn.exposes(expose_return_as, allow_blank: true) if expose_return_as.present?
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/ParameterLists
+
+      private
+
+      def _hash_with_default_array = Hash.new { |h, k| h[k] = [] }
+
+      def _hydrate_hash(given)
+        return given if given.is_a?(Hash)
+
+        Array(given).each_with_object({}) do |key, acc|
+          acc[key] = {}
+        end
+      end
+    end
+  end
+end

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.1"
+  VERSION = "0.1.0-alpha.2"
 end

data/lib/axn.rb

@@ -4,19 +4,26 @@ module Axn; end
 require_relative "axn/version"
 
 require "interactor"
-
 require "active_support"
 
-require_relative "action/exceptions"
-require_relative "action/logging"
-require_relative "action/configuration"
-require_relative "action/top_level_around_hook"
-require_relative "action/contract"
-require_relative "action/swallow_exceptions"
-require_relative "action/hoist_errors"
+require_relative "action/core/exceptions"
+require_relative "action/core/logging"
+require_relative "action/core/configuration"
+require_relative "action/core/top_level_around_hook"
+require_relative "action/core/contract"
+require_relative "action/core/swallow_exceptions"
+require_relative "action/core/hoist_errors"
+require_relative "action/core/enqueueable"
+
+require_relative "axn/factory"
+
+require_relative "action/attachable"
 
-require_relative "action/organizer"
-require_relative "action/enqueueable"
+def Axn(callable, **) # rubocop:disable Naming/MethodName
+  return callable if callable.is_a?(Class) && callable < Action
+
+  Axn::Factory.build(**, &callable)
+end
 
 module Action
   def self.included(base)
@@ -37,6 +44,9 @@ module Action
 
       include Enqueueable
 
+      # --- Extensions ---
+      include Attachable
+
       # Allow additional automatic includes to be configured
       Array(Action.config.additional_includes).each { |mod| include mod }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.1
+  version: 0.1.0.pre.alpha.2
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-24 00:00:00.000000000 Z
+date: 2025-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -62,39 +62,44 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".tool-versions"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- axn.gemspec
 - docs/.vitepress/config.mjs
-- docs/about/index.md
+- docs/advanced/conventions.md
 - docs/advanced/rough.md
-- docs/advanced/validating-user-input.md
-- docs/guide/index.md
 - docs/index.md
+- docs/intro/about.md
+- docs/intro/overview.md
+- docs/recipes/memoization.md
+- docs/recipes/testing.md
+- docs/recipes/validating-user-input.md
 - docs/reference/action-result.md
 - docs/reference/class.md
 - docs/reference/configuration.md
 - docs/reference/instance.md
-- docs/usage/conventions.md
 - docs/usage/setup.md
-- docs/usage/testing.md
 - docs/usage/using.md
 - docs/usage/writing.md
-- lib/action/configuration.rb
-- lib/action/context_facade.rb
-- lib/action/contract.rb
-- lib/action/contract_validator.rb
-- lib/action/enqueueable.rb
-- lib/action/exceptions.rb
-- lib/action/hoist_errors.rb
-- lib/action/logging.rb
-- lib/action/organizer.rb
-- lib/action/swallow_exceptions.rb
-- lib/action/top_level_around_hook.rb
+- lib/action/attachable.rb
+- lib/action/attachable/base.rb
+- lib/action/attachable/steps.rb
+- lib/action/attachable/subactions.rb
+- lib/action/core/configuration.rb
+- lib/action/core/context_facade.rb
+- lib/action/core/contract.rb
+- lib/action/core/contract_validator.rb
+- lib/action/core/enqueueable.rb
+- lib/action/core/exceptions.rb
+- lib/action/core/hoist_errors.rb
+- lib/action/core/logging.rb
+- lib/action/core/swallow_exceptions.rb
+- lib/action/core/top_level_around_hook.rb
 - lib/axn.rb
+- lib/axn/factory.rb
 - lib/axn/version.rb
 - package.json
 - yarn.lock
@@ -114,14 +119,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: A terse convention for business logic

data/axn.gemspec

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/axn/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "axn"
-  spec.version = Axn::VERSION
-  spec.authors = ["Kali Donovan"]
-  spec.email = ["kali@teamshares.com"]
-
-  spec.summary = "A terse convention for business logic"
-  spec.description = "Pattern for writing callable service objects with contract validation and error swallowing"
-  spec.homepage = "https://github.com/teamshares/axn"
-  spec.license = "MIT"
-
-  # NOTE: uses endless methods from 3, literal value omission from 3.1
-  spec.required_ruby_version = ">= 3.1.0"
-
-  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
-  # spec.metadata["rubygems_mfa_required"] = "true"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "https://github.com/teamshares/axn/blob/main/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Core dependencies
-  spec.add_dependency "activemodel", "> 7.0"    # For contract validation
-  spec.add_dependency "activesupport", "> 7.0"  # For compact_blank and friends
-
-  # NOTE: for inheritance support, need to specify a fork in consuming applications' Gemfile (see Gemfile here for syntax)
-  spec.add_dependency "interactor", "3.1.2" # We're building on this scaffolding for organizing business logic
-  spec.metadata["rubygems_mfa_required"] = "true"
-end

data/lib/action/organizer.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-#
-# CAUTION - ALPHA - TODO -- this code is extremely rough -- we have not yet gotten around to using it in production, so
-# consider this a work in progress / an indicator of things to come.
-#
-
-module Action
-  # NOTE: replaces, rather than layers on, the upstream Interactor::Organizer module (only three methods, and
-  # we want ability to implement a more complex interface where we pass options into the organized interactors)
-  module Organizer
-    def self.included(base)
-      base.class_eval do
-        include ::Action
-
-        extend ClassMethods
-        include InstanceMethods
-      end
-    end
-
-    # NOTE: pulled unchanged from https://github.com/collectiveidea/interactor/blob/master/lib/interactor/organizer.rb
-    module ClassMethods
-      def organize(*interactors)
-        @organized = interactors.flatten
-      end
-
-      def organized
-        @organized ||= []
-      end
-    end
-
-    module InstanceMethods
-      # NOTE: override to use the `hoist_errors` method (internally, replaces call! with call + overrides to use @context directly)
-      def call
-        self.class.organized.each do |interactor|
-          hoist_errors { interactor.call(@context) }
-        end
-      end
-    end
-  end
-end