navigable 0.3.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1a6a151995a3fc11306a19e5aa456017782233ad8b2ca399938e68228a21a8e
-  data.tar.gz: 0ebc72581760f1227772e55327796a68b9496997321db0d9c5de69ef0e418bee
+  metadata.gz: 520f70790477a269841be1b936c03978f41335ea88c69150dbca17396fbe4e7c
+  data.tar.gz: ee4181d29ac606c64f961fdcc627ca7e7ffda72871e78c3bac57fdc5bea72ac5
 SHA512:
-  metadata.gz: 910da8ec34c9f5679eed5e6ad2e1fb51040b483ab17d1b8202c8ded1f4dff7e180aa5c36985fd236824760eef045fca66a3310db52d2fddd9092d23114565e35
-  data.tar.gz: 17dbf68108f529820220c6017fbb5ce574a0525534a5b9bde7bf3534ac2a097396f83d5ae1837d6240d37a928c338df6f38fe71cdad4815c9b32c90f8244ac73
+  metadata.gz: b1de4110a432e1f1a4f7736ca02f0c53db9f4ea73fb42f3964b3f706c37f361dbd8c03f754e66862f8dcbee75f99776a4915000c6d69c0153b068290404bf950
+  data.tar.gz: b9ddbc9bd4a5ce9f4d67de84c74789ecf76c9040bce0f695bf3e1403f98308e7cbf28ce8d76bd573b4b167c67d670928d527b6743c572ea42fb138e51effffa8

data/.gitignore

@@ -13,5 +13,6 @@
 # rspec failure tracking
 .rspec_status
 
+.DS_Store
 Gemfile.lock
 

data/.travis.yml

@@ -2,5 +2,13 @@
 language: ruby
 cache: bundler
 rvm:
-  - 2.7.0
+  - 2.7.1
 before_install: gem install bundler -v 2.1.4
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at navigable@firsttry.software. All
+reported by contacting the project team at [navigable@firsttry.software][mail]. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.
@@ -72,3 +72,4 @@ available at [https://contributor-covenant.org/version/1/4][version]
 
 [homepage]: https://contributor-covenant.org
 [version]: https://contributor-covenant.org/version/1/4/
+[mail]: mailto:navigable@firsttry.software

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Alan Ridlehoover
+Copyright (c) 2020 Alan Ridlehoover and Fito von Zastrow
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,184 @@
-<img src="assets/navigable.png">
+<a target="top" href="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/navigable.png"><img alt="Navigable" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/header.png"></a>
 
 # Navigable
 
+[![Gem Version](https://badge.fury.io/rb/navigable.svg)](https://badge.fury.io/rb/navigable) [![Build Status](https://travis-ci.org/first-try-software/navigable.svg?branch=main)](https://travis-ci.org/first-try-software/navigable) [![Maintainability](https://api.codeclimate.com/v1/badges/33ca28cb17e1b512e006/maintainability)](https://codeclimate.com/github/first-try-software/navigable/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/33ca28cb17e1b512e006/test_coverage)](https://codeclimate.com/github/first-try-software/navigable/test_coverage)
+
+Navigable is a family of gems that together provide all the tools you need to build fast, testable, and reliable JSON and/or GraphQL based APIs with isolated, composable business logic. The gems include:
+
+<table style="margin: 20px 0">
+<tr height="140">
+<td width="130"><img alt="Clipper Ship" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/clipper.png"></td>
+<td>
+
+**[Navigable][navigable]**<br>
+A stand-alone tool for isolating business logic from external interfaces and cross-cutting concerns. Navigable composes self-configured command and observer objects to allow you to extend your business logic without modifying it. Navigable is compatible with any Ruby-based application development framework, including Rails, Hanami, and Sinatra.
+
+</td>
+</tr>
+<tr height="140">
+<td width="130"><img alt="Compass" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/sextant.png"></td>
+<td>
+
+**[Navigable Router][router]** *(coming soon)*<br>
+A simple, highly-performant, Rack-based router.
+
+</td>
+</tr>
+<tr height="140">
+<td width="130"><img alt="Compass" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/compass.png"></td>
+<td>
+
+**[Navigable Server][server]** *(coming soon)*<br>
+A Rack-based server for building Ruby and Navigable web applications.
+
+</td>
+</tr>
+<tr height="140">
+<td width="130"><img alt="Telescope" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/telescope.png"></td>
+<td>
+
+**Navigable API** *(coming soon)*<br>
+An extension of Navigable Server for building restful JSON APIs.
+
+</td>
+</tr>
+<tr height="140">
+<td width="130"><img alt="Map" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/map.png"></td>
+<td>
+
+**Navigable GraphQL** *(coming soon)*<br>
+An extension of Navigable Server for building GraphQL APIs.
+
+</td>
+</tr>
+</table>
+
+<br><br>
+
+<img style="width: 600px; display: block; margin: 0 auto;" alt="Lighthouse" src="https://raw.githubusercontent.com/first-try-software/navigable/main/assets/lighthouse.png">
+
+# The Navigable Charter
+
+We hold these truths to be self-evident, that not all objects are created equal, that poorly structured code leads to poorly tested code, and that poorly tested code leads to rigid software and fearful engineers.
+
+We believe a framework should break free of this tyranny. It should be simple, testable, and fast. It can be opinionated. But, it should leverage SOLID principles to guide us toward well structured, well tested, maleable code that is truly navigable.
+
+## Who We Are
+
+We are professional Rubyists. We could write software in any language, but we choose to work in Ruby because it is so beautiful and expressive. We love Ruby.
+
+We are test-oriented developers. We always write tests for our code, often before we've written the code. And, despite the conventional wisdom that investing in tests produces diminishing returns as you approach 100% coverage, we prefer the confidence we get with full coverage.
+
+We are also students of software architecture. We apply SOLID object-oriented design principles like the [Single Responsibility][srp] and [Open/Closed][ocp] Principles to everything we build. And, we follow [Sandi Metz's Rules][sandi] as much as possible. This leads us to write small, loosely coupled, highly cohesive classes.
+
+## Why We Wrote Navigable
+
+Besides being Rubyists, we are also seasoned Rails developers. Most of our experience with Ruby has involved Rails. We've also built applications in Sinatra, and dabbled with Hanami. And, while they all have strengths, we're not completely satisfied with any of them.
+
+### Rails
+
+In our experience, Rails is a fantastic tool for building complex web applications. But, too often, we see engineers let Rails constrain them into thinking that all of their business logic belongs in models (and controllers, and even views!). This leads to overly complex classes with too many responsibilities that are difficult to test. It also reduces the reusability of any one bit of business logic to have it burried in a 5,000 line file. (Yes, we've seen 5,000 line models and controllers, and much worse!) Rails is also a bit of a large toolbox when all you want to do is build a JSON and/or GraphQL API.
+
+### Hanami
+
+In dabbling with Hanami, we feel it has a great deal of promise. As proponents of [Domain Driven Design][ddd], we agree with many of the decisions that went into the framework. But, given that it uses convention as much as Rails, and given the lack of a dedicated home for business logic, we worry that Hanami applications will fall prey to the same problem many large Rails apps face: bloated models/entities and controller actions.
+
+### Sinatra
+
+In our experience, Sinatra is a great tool for small, simple applications. But, it's too slow to be of much use with larger, enterprise applications. So, we've limited our use to very specific types of applications with limited scope.
+
+### And, finally...
+
+All three of these frameworks take a central role in the organization of an application. We've worked on Rails applications in multiple different domains. They all looked like Rails applications. You had to dig into them to discover the core concepts of each specific domain. We believe software should be more reflective of the problem space than it is of the framework used to solve the problem.
+
+## How is Navigable Different?
+
+So, we built Navigable to help separate the web adapter (controller) and persistence layer (model) from your actual business logic. And, we did it in a composable manner that allows for incredible flexibility. Here's a peek:
+
+```ruby
+class CreateAlert
+  extend Navigable::Command
+
+  corresponds_to :create_alert
+  corresponds_to :create_alert_with_notifications
+
+  def execute
+    return failed_to_validate(new_alert) unless new_alert.valid?
+    return failed_to_create(new_alert) unless created_alert.persisted?
+
+    successfully created_alert
+  end
+
+  # ...
+end
+
+class AllRecipientsNotifier
+  extend Navigable::Observer
+
+  observes :create_alert_with_notifications
+
+  def on_success(alert)
+    NotifyAllRecipientsWorker.perform_async(alert_id: alert.id)
+  end
+end
+```
+
+In these two classes, Navigable enables you to execute multiple use cases. You can create an alert:
+
+```ruby
+Navigable::Dispatcher.dispatch(:create_alert, params: alert_params)
+```
+
+Or, create an alert and notify all recipients:
+
+```ruby
+Navigable::Dispatcher.dispatch(:create_alert_with_notifications, params: alert_params)
+```
+
+All without having to add conditional logic about the notifications to the `CreateAlert` class.
+
+Similarly, you can add cross-cutting concerns to an application just as easily:
+
+```ruby
+class Monitor
+  extend Navigable::Observer
+
+  observes_all_commands
+
+  def on_success(*args)
+    increment_counter(observed_command_key, :success)
+  end
+
+  def on_failed_to_validate(*args)
+    increment_counter(observed_command_key, :failed_to_validate)
+  end
+
+  def on_failed_to_create(*args)
+    increment_counter(observed_command_key, :failed_to_create)
+  end
+
+  # ...
+end
+```
+Here are a few things to look for in the code above:
+
+* The DSL in the `execute` method of the `CreateAlert` class is built into Navigable. Methods like `successfully` tell Navigable the results of the command so that it can notify the observers.
+
+* The two `corresponds_to` statements in `CreateAlert` tell Navigable to execute that command when either key is dispatched. You can register a command under as many different keys as you need.
+
+* The single `observes` statement in `AllRecipientsNotifier` class tells Navigable to send a message to that class only when the `:create_alert_with_notifications` key is dispatched. One observer can observe as many commands as you need. And, many observers can observe the same command.
+
+* Use the `observes_all_commands` statement (as shown in the `Monitor` class) for cross-cutting concerns. It tells Navigable to send messages to the observer no matter which command was executed.
+
+For a deeper look at the core concepts introduced by Navigable, please have a look at our [wiki][wiki].
+
+## Feedback
+
+We are really excited about Navigable! We think it solves the problem of seperating business logic from the web interface, persistence layer, and even cross-cutting concerns in an elegant and simple way.
+
+We're thrilled you're checking out Navigable! If you have any questions or comments, please feel free to reach out to [navigable@firsttry.software][mail].
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -35,3 +212,14 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the Navigable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/first-try-software/navigable/blob/main/CODE_OF_CONDUCT.md).
+
+
+[sandi]: https://thoughtbot.com/blog/sandi-metz-rules-for-developers
+[srp]: https://en.wikipedia.org/wiki/Single-responsibility_principle
+[ocp]: https://en.wikipedia.org/wiki/Open–closed_principle
+[ddd]: https://en.wikipedia.org/wiki/Domain-driven_design
+[mail]: mailto:navigable@firsttry.software
+[wiki]: https://github.com/first-try-software/navigable/wiki
+[navigable]: https://github.com/first-try-software/navigable
+[router]: https://github.com/first-try-software/navigable-router
+[server]: https://github.com/first-try-software/navigable-server

data/lib/navigable/basic_resolver.rb

@@ -0,0 +1,24 @@
+# frozen-string-literal: true
+
+require 'navigable/resolver'
+
+module Navigable
+  class BasicResolver
+    extend Navigable::Resolver
+
+    def resolve
+      @result
+    end
+
+    def on_success(result)
+      @result = result
+    end
+
+    alias_method :on_failure_to_validate, :on_success
+    alias_method :on_failure_to_find, :on_success
+    alias_method :on_failure_to_create, :on_success
+    alias_method :on_failure_to_update, :on_success
+    alias_method :on_failure_to_delete, :on_success
+    alias_method :on_failure, :on_success
+  end
+end

data/lib/navigable/command.rb

@@ -4,6 +4,8 @@ require 'navigable/observable'
 
 module Navigable
   module Command
+    class NotFoundError < StandardError; end
+
     TYPE = :__command__
     EXECUTE_NOT_IMPLEMENTED_MESSAGE = 'Class must implement `execute` method.'
 
@@ -20,7 +22,7 @@ module Navigable
       base.class_eval do
         attr_reader :params, :observers
 
-        def initialize(params: {}, observers: [])
+        def inject(params: {}, observers: [])
           @params = params
           @observers = observers
         end

data/lib/navigable/dispatcher.rb

@@ -1,12 +1,12 @@
 # frozen-string-literal: true
 
-require 'navigable/null_resolver'
+require 'navigable/basic_resolver'
 require 'navigable/observer'
 require 'navigable/command'
 
 module Navigable
   class Dispatcher
-    def self.dispatch(key, params: {}, resolver: NullResolver.new)
+    def self.dispatch(key, params: {}, resolver: BasicResolver.new)
       self.new(key, params: params, resolver: resolver).dispatch
     end
 
@@ -25,11 +25,15 @@ module Navigable
     end
 
     def observers
-      Manufacturable.build_all(Observer::TYPE, key, params: params).push(resolver)
+      Manufacturable.build_all(Observer::TYPE, key) { |observer| observer.inject(params: params) }.push(resolver)
     end
 
     def command
-      Manufacturable.build_one(Command::TYPE, key, params: params, observers: observers)
+      build_command.tap { |command| raise Navigable::Command::NotFoundError unless command }
+    end
+
+    def build_command
+      Manufacturable.build_one(Command::TYPE, key) { |command| command.inject(params: params, observers: observers) }
     end
   end
 end

data/lib/navigable/observer.rb

@@ -23,7 +23,7 @@ module Navigable
       base.class_eval do
         attr_reader :params
 
-        def initialize(params: {})
+        def inject(params: {})
           @params = params
         end
 

data/lib/navigable/observer_interface.rb

@@ -2,12 +2,12 @@
 
 module Navigable
   module ObserverInterface
-    def on_success(*args); end
-    def on_failure_to_validate(*args); end
-    def on_failure_to_find(*args); end
-    def on_failure_to_create(*args); end
-    def on_failure_to_update(*args); end
-    def on_failure_to_delete(*args); end
-    def on_failure(*args); end
+    def on_success(*args, **kwargs); end
+    def on_failure_to_validate(*args, **kwargs); end
+    def on_failure_to_find(*args, **kwargs); end
+    def on_failure_to_create(*args, **kwargs); end
+    def on_failure_to_update(*args, **kwargs); end
+    def on_failure_to_delete(*args, **kwargs); end
+    def on_failure(*args, **kwargs); end
   end
 end

data/lib/navigable/version.rb

@@ -1,5 +1,5 @@
 # frozen-string-literal: true
 
 module Navigable
-  VERSION = "0.3.1"
+  VERSION = "1.2.0"
 end

data/navigable.gemspec

@@ -7,28 +7,28 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Alan Ridlehoover", "Fito von Zastrow"]
   spec.email         = ["navigable@firsttry.software"]
 
-  spec.summary       = %q{Ahoy! Navigable will get you there!}
-  spec.description   = %q{We hold these truths to be self-evident, that not all objects are created equal, that poorly structured code leads to poorly tested code, and that poorly tested code leads to rigid software and fearful engineers. We believe a framework should break free of this tyranny. It should be simple, testable, and fast. It can be opinionated. But, it should leverage SOLID principles to guide us toward well structured, well tested, maleable code that is truly navigable.}
-  spec.homepage      = "https://github.com/first-try-software/navigable"
+  spec.summary       = %q{Ahoy! Welcome aboard Navigable!}
+  spec.description   = %q{A stand-alone tool for isolating business logic from external interfaces and cross-cutting concerns. Navigable composes self-configured command and observer objects to allow you to extend your business logic without modifying it. Navigable is compatible with any Ruby-based application development framework, including Rails, Hanami, and Sinatra.}
+  spec.homepage      = "https://firsttry.software"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/first-try-software/navigable"
   spec.metadata["bug_tracker_uri"] = "https://github.com/first-try-software/navigable/issues"
 
   spec.files         = Dir.chdir(File.expand_path("..", __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|assets)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib", "assets"]
+  spec.require_paths = ["lib"]
 
-  spec.add_dependency "manufacturable", "~> 1.4"
+  spec.add_dependency "manufacturable", "~> 1.5"
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 12.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec_junit_formatter", "~>0.4"
-  spec.add_development_dependency "simplecov", "~>0.16"
+  spec.add_development_dependency "simplecov", "~>0.17.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: navigable
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Alan Ridlehoover
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-09-12 00:00:00.000000000 Z
+date: 2020-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: manufacturable
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -87,20 +87,19 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: 0.17.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
-description: We hold these truths to be self-evident, that not all objects are created
-  equal, that poorly structured code leads to poorly tested code, and that poorly
-  tested code leads to rigid software and fearful engineers. We believe a framework
-  should break free of this tyranny. It should be simple, testable, and fast. It can
-  be opinionated. But, it should leverage SOLID principles to guide us toward well
-  structured, well tested, maleable code that is truly navigable.
+        version: 0.17.0
+description: A stand-alone tool for isolating business logic from external interfaces
+  and cross-cutting concerns. Navigable composes self-configured command and observer
+  objects to allow you to extend your business logic without modifying it. Navigable
+  is compatible with any Ruby-based application development framework, including Rails,
+  Hanami, and Sinatra.
 email:
 - navigable@firsttry.software
 executables: []
@@ -116,36 +115,34 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- assets/navigable.png
 - bin/console
 - bin/setup
 - lib/navigable.rb
+- lib/navigable/basic_resolver.rb
 - lib/navigable/command.rb
 - lib/navigable/dispatcher.rb
-- lib/navigable/null_resolver.rb
 - lib/navigable/observable.rb
 - lib/navigable/observer.rb
 - lib/navigable/observer_interface.rb
 - lib/navigable/resolver.rb
 - lib/navigable/version.rb
 - navigable.gemspec
-homepage: https://github.com/first-try-software/navigable
+homepage: https://firsttry.software
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/first-try-software/navigable
+  homepage_uri: https://firsttry.software
   source_code_uri: https://github.com/first-try-software/navigable
   bug_tracker_uri: https://github.com/first-try-software/navigable/issues
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
-- assets
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -155,5 +152,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Ahoy! Navigable will get you there!
+summary: Ahoy! Welcome aboard Navigable!
 test_files: []

data/lib/navigable/null_resolver.rb

@@ -1,11 +0,0 @@
-# frozen-string-literal: true
-
-require 'navigable/resolver'
-
-module Navigable
-  class NullResolver
-    extend Resolver
-
-    def resolve; end
-  end
-end