brancusi 0.0.1

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+
+require 'guard/jasmine/task'
+
+Guard::JasmineTask.new('jasmine:specs') do |task|
+  task.options = "-s thin -p 3001"
+end
+
+Guard::JasmineTask.new('jasmine:stories') do |task|
+  task.options = "-s thin -p 3001 -u http://localhost:3001/jasmine-stories"
+end
+
+task 'jasmine:all' => ['guard:jasmine:specs', 'guard:jasmine:stories']

data/lib/assets/javascripts/brancusi/application/application.js.coffee

@@ -0,0 +1,114 @@
+#= require brancusi/events
+#= require brancusi/routes/mapper
+
+namespace "brancusi"
+
+class brancusi.Application extends brancusi.EventObject
+  
+  @dependency mediator: "Mediator"
+    
+  # Default configuration options, which may be overridden by instances
+  @config:
+    bootstrapper: brancusi.Bootstrapper
+
+  # Module classes for the application
+  @Modules: {}
+  
+  # Module instances
+  modules: {}
+  
+  # Controller classes for the application
+  @Controllers: {}
+  
+  # Controller instances
+  controllers: {}
+
+  # Model classes for the application
+  @Models: {}
+  
+  @routes: new brancusi.routes.Mapper
+
+  # Instantiates the application and bootstrapper, and resolves any dependencies, modules and controllers.
+  #
+  # @return [Application] an instance of the application.
+  #
+  @create: ->
+    @instance = new @
+    bootstrapper = new @Bootstrapper
+    @instance.resolve(bootstrapper)    
+
+  # Resolves, initializes, and runs the application.
+  #
+  # @return [Application] an instance of the application.
+  #
+  @run: ->
+    @create().initialize().run()
+
+  # Creates and assigns the application container with the bootstrapper, then resolves dependencies, modules and controllers.
+  #
+  # @return [Application] the application instance.
+  #
+  resolve: (bootstrapper) ->
+    @container = bootstrapper.configure_container(@)
+    @container.resolve(@)
+    @_resolve_modules()
+    @_resolve_controllers()
+    @
+    
+  # Binds event handlers on the modules and controllers, then publishes the application.initialize event.
+  #
+  # @return [Application] the application instance.
+  #
+  initialize: ->
+    @_bind_events()
+    @mediator.publish "application.initialize", @
+    @
+
+  # Publishes the application.ready event.
+  #
+  # @return [Application] the application instance.
+  #
+  run: (bootstrapper) ->
+    @mediator.publish "application.ready"
+    @
+
+  # @private
+  # Instantiates and resolves the application modules.
+  #
+  _resolve_modules: ->
+    # @modules.router = @router if @router?
+    # @modules.renderer = @renderer if @renderer?
+    module_regex = /(.*)Module/ # e.g. AuthModule
+    for klass_name, klass of @constructor.Modules when matches = module_regex.exec(klass_name)
+      module_name = _.string.underscored(matches[1]) # e.g. "auth"
+      module = @container.resolve(new klass(module_name))
+      # module.sandbox.bind_subscriptions(module)
+      @modules[module_name] = module
+      
+  # @private
+  # Instantiates and resolves the application controllers.
+  #
+  _resolve_controllers: ->
+    controller_regex = /(.*)Controller/ # e.g. HomeController
+    for klass_name, klass of @constructor.Controllers when matches = controller_regex.exec(klass_name)
+      controller_name = _.string.underscored(matches[1]) # e.g. home
+      controller = @container.resolve(new klass(controller_name))
+      # controller.sandbox.bind_subscriptions(controller)
+      @controllers[controller_name] = controller
+
+  # @private
+  # Binds event handlers on the modules and controllers.
+  #
+  _bind_events: ->
+    @router.sandbox.bind_subscriptions(@router)
+    @renderer.sandbox.bind_subscriptions(@renderer)
+    
+    for module_name, module of @modules
+      module.sandbox.bind_subscriptions(module)
+    
+    for controller_name, controller of @controllers
+      controller.sandbox.bind_subscriptions(controller)
+      
+    # route_mapper = new @container.resolve 'RouteMapper'
+    # route_mapper.draw(@constructor.routes.( config?.routes || -> )
+    # @router?.initialize?()

data/lib/assets/javascripts/brancusi/application/application_controller.js.coffee

@@ -0,0 +1,17 @@
+#= require ./application_module
+
+namespace "brancusi"
+
+class brancusi.ApplicationController extends brancusi.ApplicationModule
+  @dependency renderer: 'Renderer'
+  
+  begin_request: (action_name) ->
+    @request =
+      action: action_name
+  
+  render: (args...) ->
+    if args.length > 0
+      @renderer.render_page(args...)
+    else
+      @renderer.render_page("#{@name}/#{@request.action}")
+      

data/lib/assets/javascripts/brancusi/application/application_module.js.coffee

@@ -0,0 +1,29 @@
+#= require brancusi/events
+
+namespace "brancusi"
+
+class brancusi.ApplicationModule extends brancusi.EventObject    
+    constructor: (@name) ->
+    
+    @dependency sandbox: (container) ->
+        container.resolve "Sandbox", [@name]
+
+    @dependency container: (container) ->
+        container.child().register_instance "Sandbox", @sandbox
+
+    publish: (args...) ->
+        @sandbox.publish(args...)
+
+    # TODO: maybe bind subscriptions automatically after resolving any EventObject (or anything with subscriptions)
+    # e.g.
+    # resolve: (ref, opts) ->
+    #     resolution = @container.resolve(ref, opts)
+    #     @sandbox.bind_scriptions(resolution)
+    #     resolution.publish = @sandbox.publish
+    #     resolution
+    # bind_subscriptions: (target) ->
+    #     @sandbox.bind_subscriptions.apply( @sandbox, [target] )
+    #     target.publish = @sandbox.publish
+        
+    # create_model: ( class_name, opts ) ->
+    #     @env.create( class_name, opts )

data/lib/assets/javascripts/brancusi/application/bootstrapper.js.coffee

@@ -0,0 +1,18 @@
+#= require brancusi/container
+
+namespace "brancusi"
+
+class brancusi.Bootstrapper
+
+    configure_container: ( application ) ->
+        container = new brancusi.Container()
+        
+        # TODO: do we need these?
+        container.register_instance "Application", application
+        container.register_instance "Container", container
+        
+        container.register_class "Sandbox", brancusi.Sandbox
+        container.register_class "Mediator", brancusi.Mediator, singleton: true
+        container.register_class "RegionManager", brancusi.renderer.RegionManager, singleton: true
+        
+        container

data/lib/assets/javascripts/brancusi/application/index.js.coffee

@@ -0,0 +1 @@
+#= require_tree .

data/lib/assets/javascripts/brancusi/application/sandbox.js.coffee

@@ -0,0 +1,14 @@
+#= require brancusi/container
+
+namespace "brancusi"
+
+class brancusi.Sandbox extends brancusi.DependentObject
+  @dependency mediator: "Mediator"
+
+  constructor: (@scope) ->
+  
+  publish: (event, args...) =>
+    @mediator.publish_scoped(event, @scope, args...)
+      
+  bind_subscriptions: (target) =>
+    @mediator.bind_subscriptions(target, @scope)

data/lib/assets/javascripts/brancusi/container/container.js.coffee

@@ -0,0 +1,139 @@
+namespace "brancusi"
+
+# Implementation of a DI container.
+#
+class brancusi.Container
+
+  # Creates an instance of a container.
+  #
+  # @param parent [brancusi.Container] a parent container. When provided, if resolution of a dependency fails then resolution will be attempted with the parent container instead.
+  #
+  constructor: (@parent) ->
+    @_mappings = {}
+  
+  # Registers a class mapping with the container.
+  #
+  # @param name [String] the name of the mapping to the class.
+  # @param klass [Class] the class the dependency should resolve with.
+  # @option opts [Boolean] singleton indicates whether the resolved dependency should be memoized.
+  # @return [Container] the container.
+  #
+  register_class: (name, klass, opts = {}) ->
+    @_register_mapping name, klass, "class", opts
+    @
+  
+  
+  # Registers an instance mapping with the container.
+  #
+  # @param name [String] the name of the mapping to the instance.
+  # @param obj [Object] the instance the dependency should resolve to.
+  # @return [Container] the container.
+  #
+  register_instance: (name, obj) ->
+    @_register_mapping name, obj, "instance"
+    @
+      
+
+  # Registers a factory function for resolving dependencies
+  #
+  # @param name [String] the name of the mapping
+  # @param fn [Function] the factory function to resolve the mapping
+  # @return [Container] the container
+  #
+  register_factory: (name, fn) ->
+    @_register_mapping name, fn, "factory"
+    @
+
+
+  # Returns an instance of the given dependency, resolving any child dependencies.
+  #
+  # @overload resolve(name)
+  #   Resolves the dependency according to the name of the mapping.
+  #   @param name [String] the name of the dependency mapping.
+  #   @return [Object] the fully resolved dependency.
+  #
+  # @overload resolve(target, opts)
+  #   Resolves any unresolved dependencies on a given object.
+  #   @param target [Object] the object to resolve dependencies for.
+  #   @return [Object] target.
+  # 
+  resolve: (ref, opts) ->
+    if typeof ref == "string"
+      resolution = @_resolve_string(ref, opts)
+    else if typeof ref == "function"
+      resolution = @_resolve_function(ref, opts)
+    else if typeof ref == "object"
+      resolution = @_resolve_object(ref)
+    
+    if resolution?
+      resolution
+    else if @parent?
+      @parent.resolve ref, opts unless resolution?
+    else
+      throw new Error("Unable to resolve dependency: #{ref}") unless resolution?
+  
+  
+  # Creates a child container.
+  # @return [Container] a new child container.
+  #
+  child: ->
+    new Container(@)
+
+
+  # Helper method to set up a mapping.  Merges in the given options to the definition.
+  #
+  # @private
+  # @param name [String] the name of the mapping
+  # @param [Class|Object|Function] the dependency to map too
+  # @param [String] the kind of mapping.  Either 'class', 'object' or 'factory'
+  #
+  _register_mapping: (name, ref, kind, opts = {}) ->
+    @_mappings[name] = _.defaults({ kind: kind, ref: ref }, opts)
+
+
+  # Resolves a dependency by name, passing the given options (if provided) to the dependency when initialized.
+  #
+  # @private
+  # @param name [String] the name of the dependency.
+  # @param opts [Array] optional array of arguments to pass to the dependency
+  # 
+  _resolve_string: (name, opts) ->
+    mapping = @_mappings[name]
+    return null unless mapping?
+    
+    if mapping.kind == "instance"
+      mapping.ref
+    else if mapping.kind == "class" and mapping.singleton == true
+      mapping.instance = @resolve( mapping.ref, opts ) unless mapping.instance?
+      mapping.instance
+    else if mapping.kind == "factory"
+      mapping.ref.apply(null, opts)
+    else
+      @resolve(mapping.ref, opts)
+
+
+  # Resolves a dependency specified by a function.
+  # 
+  # @private
+  # @param fn [Function] the function to invoke
+  # @param opts [Array] an optional array of arguments to pass to the function
+  #
+  _resolve_function: (fn, opts) ->
+    opts ?= []
+    obj = new fn(opts...)
+    @resolve obj
+      
+      
+  # Resolves dependencies on the given object.
+  #
+  # @private
+  # @param target [Object] the target object.
+  #
+  _resolve_object: (target) ->
+    for name, args of target.constructor.dependencies
+      [dependency, dependency_args] = args
+      if typeof dependency == "function"
+        target[name] = dependency.apply(target, [@])
+      else
+        target[name] = @resolve dependency, dependency_args
+    target

data/lib/assets/javascripts/brancusi/container/dependent_module.js.coffee

@@ -0,0 +1,30 @@
+namespace "brancusi"
+
+# A module to facilitate the specification of dependencies.  Dependencies are defined on the
+# 'dependencies' property of the target's prototype, in the format:
+#
+#     {attr1: ['dep1', [<args1>]], attr2: ['dep2', [<args2>]]}
+#
+# @mixin
+#
+class brancusi.DependentModule
+
+  # Adds the named dependencies to the object's ::dependencies property
+  #
+  # @overload dependency(dependency, args...)
+  #   Defines the given dependency on the subject class
+  #   @param dependency [Object] an object with a single field in the format {<attribute>: '<dependency name>'}
+  #   @param args [Array] optional an array of arguments to store with the dependency, to be passed as arguments on resolution
+  #
+  # @overload dependency(dependencies)
+  #   Defines the given dependencies on the subject class
+  #   @param dependencies [Object] an object naming a number of dependencies
+  # 
+  @dependency: (dependencies, args...) ->
+    @dependencies ?= {}
+
+    if @__super__? and @__super__.constructor.dependencies == @dependencies
+      @dependencies = _.clone(@__super__.constructor.dependencies)
+    
+    for dependency_name, dependency_type of dependencies
+      @dependencies[dependency_name] = [dependency_type, args]

data/lib/assets/javascripts/brancusi/container/dependent_object.js.coffee

@@ -0,0 +1,9 @@
+#= require brancusi/object_model
+#= require ./dependent_module
+
+namespace "brancusi"
+
+# Base class for dependent classes.
+#
+class brancusi.DependentObject extends brancusi.BaseObject
+    @include brancusi.DependentModule

data/lib/assets/javascripts/brancusi/container/index.js.coffee

@@ -0,0 +1 @@
+#= require_tree .

data/lib/assets/javascripts/brancusi/events/event_object.js.coffee

@@ -0,0 +1,10 @@
+#= require ./events_module
+#= require ../container/dependent_object
+
+namespace "brancusi"
+
+# Base class for AER classes.
+#
+class brancusi.EventObject extends brancusi.DependentObject
+    @include brancusi.EventsModule
+    

data/lib/assets/javascripts/brancusi/events/events_module.js.coffee

@@ -0,0 +1,14 @@
+namespace "brancusi"
+
+# Provides convenience methods @on and publish for subscribing and publishing to application events with AER.
+#
+class brancusi.EventsModule
+
+  # Generates a named event handler for AER.
+  #
+  # @param event [String] the name of the event.
+  # @param handler [Function] the event handler.
+  #
+  @on: (event, handler) ->
+    @::["@#{event}"] = handler
+      

data/lib/assets/javascripts/brancusi/events/index.js.coffee

@@ -0,0 +1 @@
+#= require_tree .

data/lib/assets/javascripts/brancusi/events/mediator.js.coffee

@@ -0,0 +1,70 @@
+namespace "brancusi"
+
+# An implementation of the mediator pattern.  This class should not be referred to directly, as the AER pattern is preferred.
+#
+class brancusi.Mediator
+
+  constructor: ->
+    @subscribers = {}
+
+  # Subscribes the given handler to the content for the specified event.
+  #
+  # @param event [String] the (fully qualified) name of the event.
+  # @param handler [Function] the event handler.
+  # @param context [Object] optional the context to invoke the handler against
+  #
+  subscribe: (event, handler, context) ->
+    @subscribers[event] ?= []
+    @subscribers[event].push(-> handler.apply(context, arguments))
+
+  # Invokes all handlers for the given event.
+  #
+  # @param event [String] the (fully qualified) name of the event.
+  # @param args... the arguments to forward to the handler.
+  #
+  publish: (event, args...) ->
+    @publish_scoped(event, null, args...)
+
+  # Invokes all handlers for the given event.
+  #
+  # @param event [String] the name of the event (either qualified or unqualified)
+  # @param scope [String] the name of the scope for unqualified event names.
+  # @param args... the arguments to forward to the handler.
+  #
+  publish_scoped: (event, scope, args...) ->
+    event = @_scoped_name(event, scope, true) if scope?
+    subscribers = (@subscribers?[event] || {})
+    for handler in subscribers
+      handler(args...)
+  
+  # Binds all subscriptions on the target object (optionally using the given scope).
+  #
+  # @param target [Object] the target object.
+  # @param scope [String] optional the name of the scope of the object.
+  #
+  bind_subscriptions: (target, scope) ->
+    for name, handler of target when matches = /@(.*)/.exec(name)
+      event = matches[1]
+      event = @_scoped_name(event, scope) if scope?
+      @subscribe(event, handler, target)
+
+  # @private
+  # Returns the fully qualified name of the event, and optionally validates the inpute.
+  #
+  # @param input [String] the input to qualify (and maybe validate).
+  # @param scope [String] optional the name of the scope for unqualified event names.
+  # @param validate [Boolean] optional whether or not to error on invalid event names.
+  #
+  _scoped_name: (input, scope, validate) =>
+    regex = /^((\w+)\.)?(\w+)$/
+
+    if input.match(regex)
+      [_, _, event_scope, event] = regex.exec(input)
+      if scope?
+        event_scope ?= scope
+        "#{event_scope}.#{event}"
+      else
+        event
+    else if validate?
+      throw new Error("Invalid event name: #{input}")
+