joosy 0.1.0.RC1 → 0.1.0.RC2

data/app/assets/javascripts/joosy/core/preloader.js.coffee

@@ -1,5 +1,5 @@
 # Preloader stub
-@Preloader = Object.extended
+@Preloader =
   load: (libraries, options) ->
-    @.merge options
-    @complete?.call window
+    @[key] = val for key, val of options
+    @complete?.call window

data/app/assets/javascripts/joosy/core/resource/collection.js.coffee

@@ -0,0 +1,137 @@
+#
+# Basic collection of Resources
+# Turns JSON array into array of Resources and manages them
+#
+# Generally you should not use Collection directly. It will be
+# automatically created by things like Joosy.Resource.Generic#map 
+# or Joosy.Resource.REST#find.
+#
+# Example:
+#   class R extends Joosy.Resource.Generic
+#     @entity 'r'
+#
+#   collection = new Joosy.Resource.Collection(R)
+#
+#   collection.reset [{foo: 'bar'}, {foo: 'baz'}]
+#   collection.each (resource) ->
+#     resource('foo')
+#
+class Joosy.Resource.Collection extends Joosy.Module
+  @include Joosy.Modules.Events
+  
+  #
+  # Allows to modify data before it gets stored
+  #
+  # @param [Function] action    `(Object) -> Object` to call
+  #
+  @beforeLoad: (action) -> @::__beforeLoad = action
+  
+  #
+  # Modelized data storage
+  #
+  data: []
+  
+  #
+  # @param [Class] model    Resource class this collection will handle
+  #
+  constructor: (@model) ->
+  
+  #
+  # Clears the storage and attempts to import given JSON
+  #
+  # @param [Object] entities    Entities to import
+  # @param [Boolean] notify     Indicates whether to trigger 'changed' event
+  #
+  reset: (entities, notify=true) ->
+    if @__beforeLoad?
+      entities = @__beforeLoad entities
+
+    @data = @modelize entities
+    
+    if notify
+      @trigger 'changed'
+    this
+  
+  #
+  # Turns Objects array into array of Resources
+  #
+  # @param [Array] collection     Array of Objects
+  #
+  modelize: (collection) ->
+    root = @model::__entityName.pluralize()
+
+    if collection not instanceof Array
+      collection = collection?[root.camelize(false)]
+
+      if collection not instanceof Array
+        throw new Error "Can not read incoming JSON" 
+
+    collection.map (x) =>
+      @model.create x
+      
+  #
+  # Calls callback for each Resource inside Collection
+  #
+  # @param [Function] callback
+  #
+  each: (callback) ->
+    @data.each callback
+    
+  #
+  # Gets first resource matching description (see Sugar.js Array#find)
+  #
+  # @param [Function] description       Callback matcher
+  #
+  find: (description) ->
+    @data.find description
+  
+  #
+  # Gets resource by id
+  #
+  # @param [Integer] id       Id to find
+  #
+  findById: (id) ->
+    @data.find (x) -> x('id').toString() == id.toString()
+  
+  #
+  # Gets resource by its index inside collection
+  #
+  # @param [Integer] i    Index
+  #
+  at: (i) ->
+    @data[i]
+
+  #
+  # Removes resource from collection by its index or by === comparison
+  #
+  # @param [Integer] target     Index
+  # @param [Resource] target    Resource by itself
+  # @param [Boolean] notify     Indicates whether to trigger 'changed' event
+  #
+  remove: (target, notify=true) ->
+    if Object.isNumber target
+      index = target
+    else
+      index = @data.indexOf target
+    if index >= 0
+      result = @data.splice(index, 1)[0]
+      if notify
+        @trigger 'changed'
+    result
+
+  #
+  # Adds resource to collection to given index or to the end
+  #
+  # @param [Resource] element       Resource to add
+  # @param [Integer] index          Index to add to. If omited will be pushed to the end
+  # @param [Boolean] notify         Indicates whether to trigger 'changed' event
+  #
+  add: (element, index=false, notify=true) ->
+    if index
+      @data.splice index, 0, element
+    else
+      @data.push element
+      
+    if notify
+      @trigger 'changed'
+    element

data/app/assets/javascripts/joosy/core/resource/generic.js.coffee

@@ -1,12 +1,129 @@
+#
+# Basic data wrapper with triggering
+#
+# Example:
+#   class R extends Joosy.Resource.Generic
+#     @entity 'r'
+#
+#     @beforeLoad (data) ->
+#       data.real = true
+#
+#   r = R.create {r: {foo: {bar: 'baz'}}}
+#
+#   r('foo')                  # {baz: 'baz'}
+#   r('real')                 # true
+#   r('foo.bar')              # baz
+#   r('foo.bar', 'fluffy')    # triggers 'changed'
+#
 class Joosy.Resource.Generic extends Joosy.Module
   @include Joosy.Modules.Log
   @include Joosy.Modules.Events
 
+  #
+  # Sets the data source description (which is NOT required)
+  # This has no use in Generic but is required in any descendant
+  # 
+  # @param [mixed] Source can be any type including lambda
+  #   If lambda is given resource will not expect direct .create() calls
+  #   You'll have to prepare descendant with .at() first
+  #
+  # Example:
+  #   Class Y extends Joosy.Resource.Generic
+  #     @source 'fluffies'
+  #   class R extends Joosy.Resource.Generic
+  #     @source -> (path) "/"+path
+  #
+  #   r = Y.create{}                  # will work as expected
+  #   r = R.create {}                 # will raise exception
+  #   r = R.at('foo/bar').create {}   # will work as expected
+  #
+  @source: (source) -> @__source = source
+
+  #
+  # Required to do some magic like skipping the root node
+  #
+  # @param [String] name    Singular name of resource
+  #
+  @entity: (name) -> @::__entityName = name
+  
+  #
+  # Sets the collection of current Resource
+  #
+  # @param [Object] klass       Class to assign as collection
+  #
+  @collection: (klass) -> @::__collection = -> klass
+  
+  #
+  # Default value of resource collection
+  # Will try to seek for EntityNamesCollection
+  # Will fallback to Joosy.Resource.Collection
+  #
+  __collection: ->
+    named = @__entityName.camelize().pluralize() + 'Collection'
+    if window[named] then window[named] else Joosy.Resource.Collection
+  
+  #
+  # Allows to modify data before it gets stored
+  #
+  # @param [Function] action    `(Object) -> Object` to call
+  #
   @beforeLoad: (action) -> @::__beforeLoad = action
 
-  @create: ->
+  #
+  # Dynamically creates collection of inline resources
+  # Inline resource share the instance with direct data and therefore can be used
+  # to better handle inline changes
+  #
+  # Example:
+  #   class Zombie extends Joosy.Resource.Generic
+  #     @entity 'a'
+  #   class Puppy extends Joosy.Resource.Generic
+  #     @entity 'b'
+  #     @maps 'zombies'
+  #
+  #   p = Puppy.create {zombies: [{foo: 'bar'}]}
+  #
+  #   p('zombies')            # Direct access: [{foo: 'bar'}]
+  #   p.zombies               # Wrapped Collection of Zombie instances
+  #   p.zombies.at(0)('foo')  # bar
+  #
+  # @param [String] name    Pluralized name of property to define
+  # @param [Class] klass    Resource class to instantiate
+  #
+  @map: (name, klass=false) ->
+    unless klass
+      klass = window[name.singularize().camelize()]
+      
+    if !klass
+      throw new Error "#{Joosy.Module.__className @}> class can not be detected for '#{name}' mapping"
+
+    @beforeLoad (data) ->
+      @[name] = new (klass::__collection()) klass
+      if Object.isArray data[name]
+        @[name].reset data[name]
+      data
+
+  #
+  # Creates the descnendant of current resource with proper source
+  # Should be used together with lambda source (see @source for example)
+  #
+  @at: ->
+    if !Object.isFunction @__source
+      throw new Error "#{Joosy.Module.__className @}> should be created directly (without `at')"
+
+    class clone extends this
+    clone.__source = @__source arguments...
+    clone
+
+  #
+  # Wraps instance of resource inside shim-function allowing to track
+  # data changes. See class example
+  #
+  # @return [Joosy.Resource.Generic]
+  #
+  @create: ->    
     shim = ->
-      shim.__call.apply(shim, arguments)
+      shim.__call.apply shim, arguments
 
     if shim.__proto__
       shim.__proto__ = @prototype
@@ -16,22 +133,46 @@ class Joosy.Resource.Generic extends Joosy.Module
         
     shim.constructor = @
     
-    @apply(shim, arguments)
+    @apply shim, arguments
 
     shim
 
+  #
+  # Should NOT be called directly, use .create() instead
+  #
+  # @param [Object] data      Data to store
+  #
   constructor: (data) ->
-    @__fillData(data)
-    
+    @__fillData data
+  
+  #
+  # Getter for wrapped data
+  #
+  # @param [String] path    Attribute name to get. Can contain dots to get inline Objects values
+  # @return [mixed]
+  #
   get: (path) ->
-    target = @__callTarget(path)
+    target = @__callTarget path
     target[0][target[1]]
 
+  #
+  # Setter for wrapped data, triggers 'changed'
+  #
+  # @param [String] path    Attribute name to set. Can contain dots to get inline Objects values
+  # @param [mixed] value    Value to set
+  #
   set: (path, value) ->
-    target = @__callTarget(path)    
+    target = @__callTarget path
     target[0][target[1]] = value
     @trigger 'changed'
+    null
 
+  #
+  # Locates the actual instance of dotted path from get/set
+  #
+  # @param [String] path    Path to the attribute ('foo.bar')
+  # @return [Array]         Instance of object containing last step of path and keyword for required field
+  #
   __callTarget: (path) ->
     if path.has(/\./) && !@e[path]?
       path    = path.split '.'
@@ -46,16 +187,40 @@ class Joosy.Resource.Generic extends Joosy.Module
     else
       [@e, path]
 
+  #
+  # Wrapper for .create() magic
+  #
   __call: (path, value) ->
-    if value
+    if arguments.length > 1
       @set path, value
     else
       @get path
 
-  __fillData: (data) ->
-    @e = @__prepareData(data)
+  #
+  # Defines how exactly prepared data should be saved
+  #
+  # @param [Object] data    Raw data to store
+  #
+  __fillData: (data, notify=true) ->
+    @e = @__prepareData data
+    
+    if notify
+      @trigger 'changed'
+
+    null
 
-  __prepareData: (data) ->
-    data = Object.extended(data)
-    data = @__beforeLoad(data) if @__beforeLoad?
+  #
+  # Prepares raw data: cuts the root node if it exists, runs before filters
+  #
+  # @param [Object] data    Raw data to prepare
+  # @return [Object]
+  #
+  __prepareData: (data) ->    
+    if Object.isObject(data) && Object.keys(data).length == 1 && @__entityName
+      name = @__entityName.camelize(false)
+      data = data[name] if data[name]
+
+    if @__beforeLoad?
+      data = @__beforeLoad data
+      
     data

data/app/assets/javascripts/joosy/core/resource/rest.js.coffee

@@ -1,76 +1,199 @@
 #= require ./rest_collection
 
+#
+# Resource with the HTTP REST as the backend
+#
+# Example:
+#   class Rocket extends Joosy.Resource.REST
+#     @entity 'rocket'
+#
+#   r = Rocket.find {speed: 'fast'}   # queries /rockets/?speed=fast to get RESTCollection
+#   r = Rocket.find 1                 # queries /rockets/1 to get Rocket instance
+#
+#   class Engine extends Joosy.Resource.REST
+#     @entity 'engine'
+#     @source -> 
+#       (rocket) "/rockets/#{rocket 'id'}/engines"
+#
+#   e = Engine.at(r).find {oil: true} # queries /rockets/1/engies?oil=true
+#
 class Joosy.Resource.REST extends Joosy.Resource.Generic
 
+  #
+  # Default primary key field 'id'
+  #
   __primaryKey: 'id'
-
-  @entity: (name) -> @::__entityName = name
-  @source: (source) -> @::__source = source
+  
+  
+  #
+  # Default value of resource collection
+  # Will try to seek for EntityNamesCollection
+  # Will fallback to Joosy.Resource.RESTCollection
+  #
+  __collection: ->
+    named = @__entityName.camelize().pluralize() + 'Collection'
+    if window[named] then window[named] else Joosy.Resource.RESTCollection
+
+  #
+  # Sets the field containing primary key
+  #
+  # It has no direct use inside the REST resource itself and can be omited
+  # That's said: REST resource can work without primary at all. It's here 
+  # just to improve end-users experience for cases when primary exists.
+  #
+  # @param [String] primary     Name of the field
+  #
   @primary: (primary) -> @::__primaryKey = primary
 
-  constructor: (description) ->
-    if @constructor.__isId(description)
+  #
+  # Should NOT be called directly, use .create() instead
+  #
+  # @param [Integer|String|Object] description    ID of entity or full data to store
+  #
+  constructor: (description={}) ->
+    if @constructor.__isId description
       @id = description
     else
       super description
       @id = @e[@__primaryKey]
 
-  @entityName: ->
-    unless @::hasOwnProperty '__entityName'
-      throw new Error "Joosy.Resource.REST does not have entity name"
-
-    @::__entityName
-
-  # Returns single entity if int/string given
+  #
+  # Queries for REST data and creates resources instances
+  #
+  # Returns single entity if integer or string given
   # Returns collection if no value or Object (with parameters) given
-  @find: (description, callback, options) ->
-    if @__isId(description)
-      resource = new @(description)
-      resource.fetch callback, options
+  #
+  # If first parameter is a Function it's considered as a result callback
+  # In this case parameters will be considered equal to {}
+  #
+  # Example:
+  #   class Rocket extends Joosy.Resource.REST
+  #     @entity 'rocket'
+  #
+  #   Rocket.find 1
+  #   Rocket.find {type: 'nuclear'}, (data) -> data
+  #   Rocket.find (data) -> data
+  #   Rocket.find 1, 
+  #     success: (data) -> data)
+  #     cache: true
+  #
+  # @param [Integer|String|Object] description      ID of entity or full data to store
+  # @param [Function|Object] options                AJAX options.
+  #   Will be considered as a success callback if function given
+  #
+  # @return [Joosy.Resource.REST|Joosy.Resource.RESTCollection]
+  #
+  @find: (description, options) ->
+    if Object.isFunction options
+      options = {success: options}
+    
+    if @__isId description
+      resource = @create description
+      resource.fetch options
       resource
     else
-      if Object.isFunction(description) && !callback
-        callback = description
+      if !options? && Object.isFunction description
+        options = {success: description}
         description = undefined
-      resources = new Joosy.Resource.RESTCollection(@, description)
-      resources.fetch callback, options
+      resources = new (@::__collection()) this, description
+      resources.fetch options
       resources
 
-  fetch: (callback, options) ->
-    @constructor.__ajax 'get', @constructor.__buildSource(extension: @id), options, (e) =>
-      @__fillData(e)
-      callback?(this)
+  #
+  # Queries the resource url and reloads the data from server
+  #
+  # @param [Function|Object] options  AJAX options.
+  #   Will be considered as a success callback if function given
+  # @return [Joosy.Resource.REST]
+  #
+  fetch: (options) ->
+    if Object.isFunction options
+      callback = options
+    else
+      callback = options?.success
+      delete options?.success
 
+    @constructor.__ajax 'get', @constructor.__buildSource(extension: @id), options, (e) =>
+      @__fillData e, false
+      callback? this
+      @trigger 'changed'
     this
 
   save: ->
 
-  destroy: (callback, options) ->
+  #
+  # Destroys the resource by DELETE query
+  #
+  # @param [Function|Object] options  AJAX options.
+  #   Will be considered as a success callback if function given
+  # @return [Joosy.Resource.REST]
+  #
+  destroy: (options) ->
+    if Object.isFunction options
+      callback = options
+    else
+      callback = options?.success
+      delete options?.success
+    
     @constructor.__ajax 'delete', @constructor.__buildSource(extension: @id), options, (e) =>
-      callback?(this)
-
+      callback? this
     this
-
-  @__isId: (something) -> Object.isNumber(something) || Object.isString(something)
-
+    
+  #
+  # Requests the REST member URL with POST or any method given in options.type
+  #
+  # @param [String] ending            Member url (like 'foo' or 'foo/bar')
+  # @param [Function|Object] options  AJAX options.
+  #   Will be considered as a success callback if function given
+  #
+  request: (ending, options) ->
+    if Object.isFunction options
+      callback = options
+    else
+      callback = options?.success
+      delete options?.success
+      
+    if options.method || options.type
+      type = options.method || options.type
+    else
+      type = 'post'
+    
+    @constructor.__ajax type, @constructor.__buildSource(extension: "#{@id}/#{ending}"), options, callback
+
+  #
+  # Checks if given description can be considered as ID
+  #
+  # @param [Integer|String|Object] something Value to test
+  # @return [Boolean]
+  #
+  @__isId: (something) ->
+    Object.isNumber(something) || Object.isString(something)
+
+  #
+  # jQuery AJAX wrapper
+  #
+  # @param [String] method      HTTP Method (GET/POST/PUT/DELETE)
+  # @param [String] url         URL to query
+  # @param [Object] options     AJAX options to pass with request
+  # @param [Function] callback  XHR callback
+  #
   @__ajax: (method, url, options={}, callback) ->
-    $.ajax url, Object.extended(
+    $.ajax url, Joosy.Module.merge options,
       type: method
       success: callback
       cache: false
       dataType: 'json'
-    ).merge options
 
+  #
+  # Builds URL for current resource location
+  #
+  # @param [Object] options     Handling options
+  #   extension: string to add to resource base url
+  #   params: GET-params to add to resulting url
+  #
   @__buildSource: (options={}) ->
-    unless @::hasOwnProperty '__source'
-      @::__source = "/" + @entityName().pluralize()
-
-    source = Joosy.buildUrl("#{@::__source}/#{options.extension || ''}", options.params)
-
-  __fillData: (data) ->
-    data = @__prepareData data
-    
-    if Object.isObject(data) && data[@constructor.entityName()] && data.keys().length == 1
-      @e = Object.extended data[@constructor.entityName()]
-    else
-      @e = data
+    unless @hasOwnProperty '__source'
+      @__source = "/" + @::__entityName.pluralize()
+      
+    source = if Object.isFunction(@__source) then @__source() else @__source
+    source = Joosy.buildUrl "#{source}/#{options.extension || ''}", options.params