trailblazer-loader 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bc05571c5342cd3e10a403596b59b87610bf1a84
-  data.tar.gz: c4277f78ae6dacb7dbe9253e89da03cbbbdf3547
+  metadata.gz: 8f993eca956a001ec251af5f8635dc5dd74ea5e0
+  data.tar.gz: 26a5ae8a81b39c05ac8de3bb81629d11ec1a456e
 SHA512:
-  metadata.gz: 47ba85836e3f64b7be756f212f2d37aeeae77d16d7ca8b264a8a1337f6e8216d4e8d88eccaed4a22b4ad1fede3c68c2002f4926678778f4bc22cb7ab0f69e639
-  data.tar.gz: d225d6e85f51363e24c582e63056c6aca2e018cc119206be4dd50aaf4bd629a2ced9cf9cb04d34ca3f890931f149438a63260339741b003f61844a6b2ae51a5e
+  metadata.gz: 40b4ecbc9a013b6ba73094130b85d31221fdfd8aff7f657248aa69a40707c68626dac426da94c2ce531ff346592b1020864fc7e6204fbf550e993853dfde4338
+  data.tar.gz: 7b53184a5e2558b3d116cb53fb70c2f5a9259e5e3cc42dcec6f898886fd17291c50f5d0d8178a309093f2c8a0127dcd16b87cd047eae55da6845fcad65e7be0f

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.0.4
+
+* Fix loading for explicit layouts.
+
 # 0.0.3
 
 * Bump to Representable 2.4.0 as we use `Pipeline::Collect`. This doesn't mean this dependency will last forever. We might switch to `call_sheet` for pipelines.

data/README.md

@@ -1,31 +1,176 @@
 # Trailblazer::Loader
 
-## Experimental!
+_Generic loader for Trailblazer projects._
 
-Note that this is not the finalized version of `trailblazer-loader`. We still need more input from you.
+ Reportedly works with Rails, Grape, Lotus, and Roda, and many more, for sure.
 
-Expect many minor version bumps.
+**Rails users**: This gem is bundled with [trailblazer-rails](https://github.com/trailblazer/trailblazer-rails).
 
-## Loading order
+## Overview
+
+While Trailblazer enforces a new file structure where you organize by concept, and not by technology, the naming and the structuring within each concept allows different styles.
+
+Trailblazer-loader supports the following directory layouts concurrently.
+
+## Compound-Singular
+
+Per concept, you have one file per abstraction layer (called a _compound_ file). All is singular and reflects the namespace (except for operations which sit in the concept's namespace).
+
+```
+app
+├── concepts
+│   ├── comment
+│   │   ├── callback.rb
+│   │   ├── cell.rb
+│   │   ├── contract.rb
+│   │   ├── operation.rb
+│   │   ├── policy.rb
+│   │   └── views
+│   │       ├── grid.haml
+│   │       └── show.haml
+```
+
+You may nest concepts in concepts.
+
+```
+app
+├── concepts
+│   ├── comment
+│   │   ├── contract.rb
+│   │   ├── operation.rb
+│   │   ├── admin
+│   │       ├── contract.rb
+│   │       └── operation.rb
+```
+
+Note: This is the structuring used in the [Trailblazer book](http://trailblazer.to/books/trailblazer.html).
+
+
+## Explicit-Singular
 
-Per concept. Lexically sorted. Then, sorted by depths, as follows.
+Per concept, you have one directory per abstraction layer and one file per class. All is singular and reflects the namespace (except for operations which sit in the concept's namespace).
 
 ```
-app/concepts/blog/operation.rb
-app/concepts/comment/operation.rb
-app/concepts/post/operation.rb
-app/concepts/api/v1/comment/operation.rb
-app/concepts/api/v1/post/operation.rb
+app
+├── concepts
+│   ├── comment
+│   │   ├── contract
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   ├── cell
+│   │   │   └── form.rb
+│   │   ├── operation
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   └── views
+│   │       ├── grid.haml
+│   │       └── show.haml
 ```
 
-1. Model. The model does not have dependencies to other layers. If it does, you're doing it wrong.
-2. Policy
-3. Representer
-4. Form
-5. Callbacks, etc.
-6. Operation. As an orchestrating object, this needs to be loaded last. It is very common for operations to reference form classes, etc. on the class level.
- first create.rb
- then operations.rb {configurable, could also be crud.rb}
+You may nest concepts in concepts.
+
+```
+app
+├── concepts
+│   ├── comment
+│   │   ├── contract
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   ├── operation
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   ├── admin
+│   │   │   └── contract
+│   │   │       ├── create.rb
+│   │   │       └── update.rb
+```
+
+## Explicit-Plural
+
+Per concept, you have one pluralized directory per abstraction layer and one file per class.
+
+```
+app
+├── concepts
+│   ├── comment
+│   │   ├── contracts
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   ├── cells
+│   │   │   └── form.rb
+│   │   ├── operations
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   └── views
+│   │       ├── grid.haml
+│   │       └── show.haml
+```
+
+And, yes, you may nest concepts in concepts.
+
+```
+app
+├── concepts
+│   ├── comment
+│   │   ├── contracts
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   ├── operation
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
+│   │   ├── admin
+│   │   │   └── contracts
+│   │   │       ├── create.rb
+│   │   │       └── update.rb
+```
+
+
+## Loading order
+
+The loading order is identical for all styles.
+
+1. The loader finds all concept directories.
+2. Concept directories are sorted by nesting level, deeper nestings are loaded later as they might reference concepts they're nested in. For example, `concepts/comment/admin` might reuse existing code from `concepts/comment`.
+3. Per concept, files are lexically sorted, e.g. `create.rb` will be loaded *before* `update.rb` as we mostly do `Update < Create`.
+4. Per concept, operation files will be loaded after all other layer files have been required. This is because abstraction files like representers or contracts should not reference their operation. The operation, howver, as an orchestrating asset needs to refer to various abstraction objects.
+
+Here's a sample of a explicit-singular session.
+
+```ruby
+[
+  "app/concepts/navigation/cell.rb",
+  "app/concepts/session/impersonate.rb",
+  "app/concepts/session/operation.rb",
+  "app/concepts/user/operation.rb",
+  "app/concepts/comment/cell/cell.rb",
+  "app/concepts/comment/cell/grid.rb",
+  "app/concepts/comment/operation/create.rb",
+  "app/concepts/api/v1.rb",
+  "app/concepts/thing/callback/default.rb",
+  "app/concepts/thing/callback/upload.rb",
+  "app/concepts/thing/cell.rb",
+  "app/concepts/thing/cell/decorator.rb",
+  "app/concepts/thing/cell/form.rb",
+  "app/concepts/thing/cell/grid.rb",
+  "app/concepts/thing/contract/create.rb",
+  "app/concepts/thing/contract/update.rb",
+  "app/concepts/thing/policy.rb",
+  "app/concepts/thing/signed_in.rb",
+  "app/concepts/thing/operation/create.rb",
+  "app/concepts/thing/operation/delete.rb",
+  "app/concepts/thing/operation/show.rb",
+  "app/concepts/thing/operation/update.rb",
+  "app/concepts/api/v1/comment/representer/show.rb",
+  "app/concepts/api/v1/comment/operation/create.rb",
+  "app/concepts/api/v1/comment/operation/show.rb",
+  "app/concepts/api/v1/thing/representer/create.rb",
+  "app/concepts/api/v1/thing/representer/index.rb",
+  "app/concepts/api/v1/thing/representer/show.rb",
+  "app/concepts/api/v1/thing/operation/create.rb",
+  "app/concepts/api/v1/thing/operation/index.rb",
+  "app/concepts/api/v1/thing/operation/update.rb"
+]
+```
 
 ## Installation
 
@@ -35,55 +180,60 @@ Add this line to your application's Gemfile:
 gem 'trailblazer-loader'
 ```
 
+You do not need this step should you use one of the following binding gems.
+
+* [trailblazer-rails](https://github.com/trailblazer/trailblazer-rails)
+* [trailblazer-grape](https://github.com/trailblazer/trailblazer-grape)
+* [trailblazer-roda](https://github.com/trailblazer/trailblazer-roda)
+* [trailblazer-lotus](https://github.com/trailblazer/trailblazer-lotus)
+
 ## API
 
 ```ruby
-Trailblazer::Loader.new.(Rails.app.root) { |file| require_dependency(file) }
+Trailblazer::Loader.new.() { |file| require_dependency(File.join(Rails.app.root, file)) }
 ```
 
+`:concepts_root`
+
+## Mixing
+
+Note that you're free to mix these styles the way it feels right for your project.
 
-## File Layout
+For example, you can have compound files and explicit layout in one concept.
 
 ```
 app
 ├── concepts
-│   ├── comment
-│   │   ├── cell.rb        [optional]
-│   │   ├── contract.rb    [optional]
-│   │   ├── operation.rb
-│   │   ├── policy.rb      [optional]
-│   │   ├── representer.rb [optional]
-│   │   ├── views
-│   │   │   ├── show.haml
-│   │   │   ├── list.haml
-│   │   │   ├── comment.css.sass
+│   ├── comment
+│   │   ├── contract.rb     - compound vs.
+│   │   ├── operation       -  explicit directory
+│   │   │   ├── create.rb
+│   │   │   └── update.rb
 ```
 
-### Alternative "explicit" layout
+## Namespacing Operations
 
-This works for cell, contract, operation, policy, representer and twin.
+Normally, operations in Trailblazer use the concept's namespace, e.g. `Comment::Create`, even though they can sit in an explicit file.
 
 ```
 app
 ├── concepts
-│   ├── comment
-│   │   ├── operation
-│   │   │   ├── create.rb
-│   │   │   ├── update.rb
+│   ├── comment
+│   │   ├── operation       - explicit directory
+│   │   │   ├── create.rb   -   contains Comment::Create
+│   │   │   └── update.rb
 ```
 
-### Nested
+You are free to namespace your operations, if you like that better.
 
+```ruby
+module Comment::Operation
+  class Create < Trailblazer::Operation
 ```
-app
-├── concepts
-│   ├── comment
-│   │   ├── cell
-│   │   │   ├── single
-│   │   │   │   ├── homepage.rb
-│   │   │   │   ├── search.rb
-│   │   │   │   ├── views
-│   │   │   │   │   ├── homepage.haml
-│   │   │   │   │   ├── search.haml
-│   │   │   ├── collection
-```
+
+## Debugging
+
+## Customizing
+
+Trailblazer-loader allows you to inject your own sorting and filtering logic, should you refuse to go mainstream.
+

data/lib/trailblazer/loader.rb

@@ -1,5 +1,6 @@
 require "trailblazer/loader/version"
 require "representable/pipeline"
+require "pp"
 
 module Trailblazer
   class Loader
@@ -9,35 +10,55 @@ module Trailblazer
     # NOTE: i will most probably use call_sheet and dry-container here soon.
     def call(options={}, &block)
       options[:concepts_root] ||= "app/concepts/"
+      options[:concept_dirs] = concept_dirs
 
       pipeline = options[:pipeline] || Representable::Pipeline[
+        FindDirectories,
         FindConcepts,
-        SortConcepts,
-        Representable::Collect[ConceptName, ConceptFiles] # per concept.
+        # PrintConcepts,
+        SortByLevel,
+        Representable::Collect[ConceptName, ConceptFiles, SortCreateFirst, SortOperationLast, AddConceptFiles] # per concept.
       ]
 
       if args = options[:insert] # FIXME: this only implements a sub-set.
         # pipeline = Representable::Pipeline::Insert.(pipeline, *args) # FIXME: implement :before in Pipeline.
-        pipeline[2].insert(pipeline[2].index(args.last[:before]), args.first)
+        pipeline[3].insert(pipeline[3].index(args.last[:before]), args.first)
       end
 
       files =  pipeline.([], options).flatten
 
-      # require "pp"
-      # pp files
+      pp files
 
       load_files(files, &block)
     end
 
-    FindConcepts  = ->(input, options) { Dir.glob("#{options[:concepts_root]}**/") }
-    # lame heuristic, but works for me: sort by nested levels.
+    def concept_dirs
+      %w{ callback cell contract operation policy representer view }
+    end
+
+    FindDirectories  = ->(input, options) { Dir.glob("#{options[:concepts_root]}**/") }
+    # Filter out all directories containing /(callback|cell|contract|operation|policy|representer|view)/
+    FindConcepts     = ->(input, options) { input.shift; input.reject { |dir| dir =~ /(#{options[:concept_dirs].join("|")})/ } }
+    PrintConcepts    = ->(input, options) { puts "  concepts: #{input.inspect}"; input }
+
+    # lame heuristic, but works for me: sort by directory levels.
     # app/concepts/comment
     # app/concepts/api/v1/comment
-    SortConcepts  = ->(input, options) { input.sort { |a, b| a.split("/").size <=> b.split("/").size } }
+    SortByLevel  = ->(input, options) { input.sort { |a, b| a.split("/").size <=> b.split("/").size } }
     # Extract concept name from path, e.g. /api/v1/comment.
     ConceptName   = ->(input, options) { options[:name] = input.sub(options[:concepts_root], "").chomp("/"); [] }
     # Find all .rb files in one particular concept directory, e.g. as in /concepts/comment/*.rb.
-    ConceptFiles  = ->(input, options) { input += Dir.glob("#{options[:concepts_root]}#{options[:name]}/*.rb") }
+    ConceptFiles  = ->(input, options) do
+      Dir.glob("#{options[:concepts_root]}#{options[:name]}/*.rb") +        # .rb files directly in this concept.
+        Dir.glob("#{options[:concepts_root]}#{options[:name]}/*/*.rb").     # .rb in :concept/operation/*.rb
+        find_all { |file| file =~ /(#{options[:concept_dirs].join("|")})/ } # but only those, no sub-concepts!
+    end
+
+    # operation files should be loaded after callbacks, policies, and the like: [callback.rb, contract.rb, policy.rb, operation.rb]
+    SortOperationLast = ->(input, options) { input.sort { |a, b| (a =~ /operation/ && b !~ /operation/) ? 1 : -1 } }
+    SortCreateFirst   = ->(input, options) { input.sort }
+    AddConceptFiles   = ->(input, options) { input }
+
 
   private
 

data/lib/trailblazer/loader/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Loader
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-loader
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-16 00:00:00.000000000 Z
+date: 2015-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler