joosy 0.1.0.RC2 → 0.1.0.RC3

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

@@ -1,15 +1,15 @@
 #
-# Basic data wrapper with triggering
+# Basic data wrapper with triggering and entity name binding
 #
-# Example:
+# @example Basic usage
 #   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
@@ -21,68 +21,96 @@ class Joosy.Resource.Generic extends Joosy.Module
 
   #
   # Sets the data source description (which is NOT required)
-  # This has no use in Generic but is required in any descendant
+  # @note 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
+  # @param [mixed] Source can be any type including lambda.
+  #   If lambda is given resource will not expect direct {Joosy.Resource.Generic.create} calls
+  #   You'll have to prepare descendant with {Joosy.Resource.Generic.at} first.
   #
-  # Example:
+  # @example Simple case
   #   Class Y extends Joosy.Resource.Generic
   #     @source 'fluffies'
+  #   
+  #   r = Y.create {}
+  #
+  # @example Case with lambda
   #   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
+  
+  #
+  # Creates the proxy of current resource with proper {Joosy.Resource.Generic.source} value
+  #
+  # @note Should be used together with lambda source (see {Joosy.Resource.Generic.source} for example)
+  #
+  @at: ->
+    if !Object.isFunction @__source
+      throw new Error "#{Joosy.Module.__className @}> should be created directly (without `at')"
+
+    #
+    # Class inheritance used to create proxy
+    #
+    # @private
+    #
+    class clone extends this
+    clone.__source = @__source arguments...
+    clone
 
   #
-  # Required to do some magic like skipping the root node
+  # Sets the entity text name:
+  #   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
+  # Sets the collection to use
   #
-  # @param [Object] klass       Class to assign as collection
+  # @note By default will try to seek for `EntityNamesCollection`.
+  #   Will fallback to {Joosy.Resource.Collection}
+  #
+  # @param [Class] 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
+  # Implements {Joosy.Resource.Generic.collection} default behavior.
   #
   __collection: ->
     named = @__entityName.camelize().pluralize() + 'Collection'
     if window[named] then window[named] else Joosy.Resource.Collection
   
   #
-  # Allows to modify data before it gets stored
+  # Allows to modify data before it gets stored.
+  # You can define several beforeLoad filters that will be chained.
   #
   # @param [Function] action    `(Object) -> Object` to call
   #
-  @beforeLoad: (action) -> @::__beforeLoad = action
+  @beforeLoad: (action) ->
+    unless @::hasOwnProperty '__beforeLoads'
+      @::__beforeLoads = [].concat @.__super__.__beforeLoads || []
+    @::__beforeLoads.push action
 
   #
-  # Dynamically creates collection of inline resources
-  # Inline resource share the instance with direct data and therefore can be used
-  # to better handle inline changes
+  # Dynamically creates collection of inline resources.
+  #
+  # Inline resources share the instance with direct data and therefore can be used
+  #   to handle inline changes with triggers and all that resources stuff
   #
-  # Example:
+  # @example Basic usage
   #   class Zombie extends Joosy.Resource.Generic
-  #     @entity 'a'
+  #     @entity 'zombie'
   #   class Puppy extends Joosy.Resource.Generic
-  #     @entity 'b'
-  #     @maps 'zombies'
-  #
+  #     @entity 'puppy'
+  #     @map '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
@@ -103,18 +131,6 @@ class Joosy.Resource.Generic extends Joosy.Module
         @[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
@@ -138,12 +154,24 @@ class Joosy.Resource.Generic extends Joosy.Module
     shim
 
   #
-  # Should NOT be called directly, use .create() instead
+  # Should NOT be called directly, use {::create} instead
   #
+  # @private
   # @param [Object] data      Data to store
   #
   constructor: (data) ->
+    @__fillData data, false
+    
+  #
+  # Set the resource data manually
+  #
+  # @param [Object] data      Data to store
+  #
+  # @return [Joosy.Resource.Generic]      Returns self
+  #
+  reset: (data) ->
     @__fillData data
+    return this
   
   #
   # Getter for wrapped data
@@ -156,7 +184,7 @@ class Joosy.Resource.Generic extends Joosy.Module
     target[0][target[1]]
 
   #
-  # Setter for wrapped data, triggers 'changed'
+  # Setter for wrapped data, triggers `changed` event.
   #
   # @param [String] path    Attribute name to set. Can contain dots to get inline Objects values
   # @param [mixed] value    Value to set
@@ -168,9 +196,9 @@ class Joosy.Resource.Generic extends Joosy.Module
     null
 
   #
-  # Locates the actual instance of dotted path from get/set
+  # Locates the actual instance of attribute path `foo.bar` from get/set
   #
-  # @param [String] path    Path to the attribute ('foo.bar')
+  # @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) ->
@@ -188,7 +216,7 @@ class Joosy.Resource.Generic extends Joosy.Module
       [@e, path]
 
   #
-  # Wrapper for .create() magic
+  # Wrapper for {Joosy.Resource.Generic.create} magic
   #
   __call: (path, value) ->
     if arguments.length > 1
@@ -212,15 +240,15 @@ class Joosy.Resource.Generic extends Joosy.Module
   #
   # Prepares raw data: cuts the root node if it exists, runs before filters
   #
-  # @param [Object] data    Raw data to prepare
-  # @return [Object]
+  # @param [Hash] data    Raw data to prepare
+  # @return [Hash]
   #
   __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
+    if @__beforeLoads?
+      data = bl.call(this, data) for bl in @__beforeLoads
       
     data

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

@@ -1,20 +1,20 @@
 #= require ./rest_collection
 
 #
-# Resource with the HTTP REST as the backend
+# Resource with the HTTP REST as the backend.
 #
-# Example:
+# @example Basic usage
 #   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
@@ -24,31 +24,28 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
   #
   __primaryKey: 'id'
   
-  
   #
-  # Default value of resource collection
-  # Will try to seek for EntityNamesCollection
-  # Will fallback to Joosy.Resource.RESTCollection
+  # Implements `@collection` default behavior.
+  # Changes the default 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
+  # 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.
+  # @note It has no direct use inside the REST resource itself and can be omited.
+  #   But it usually should not since we have plans on adding some kind of Identity Map to Joosy.
   #
   # @param [String] primary     Name of the field
   #
   @primary: (primary) -> @::__primaryKey = primary
 
   #
-  # Should NOT be called directly, use .create() instead
+  # Should NOT be called directly, use {Joosy.Resource.Generic.create} instead
   #
-  # @param [Integer|String|Object] description    ID of entity or full data to store
+  # @param [Integer, String, Object] description    ID of entity or full data to store
   #
   constructor: (description={}) ->
     if @constructor.__isId description
@@ -58,18 +55,18 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
       @id = @e[@__primaryKey]
 
   #
-  # Queries for REST data and creates resources instances
+  # 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
+  # Returns single entity if integer or string given.
+  # Returns collection if no value or Object (with parameters) given.
   #
-  # If first parameter is a Function it's considered as a result callback
-  # In this case parameters will be considered equal to {}
+  # If first parameter is a Function it's considered as a result callback,
+  #   in this case parameters will be considered equal to `{ }`
   #
-  # Example:
+  # @example Different find
   #   class Rocket extends Joosy.Resource.REST
   #     @entity 'rocket'
-  #
+  #   
   #   Rocket.find 1
   #   Rocket.find {type: 'nuclear'}, (data) -> data
   #   Rocket.find (data) -> data
@@ -77,11 +74,11 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
   #     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
+  # @param [Integer, String, Object] description    ID of entity or full data to store
+  # @param [Hash, Function] options                 AJAX options.
+  #   Will be considered as a success callback if function is given.
   #
-  # @return [Joosy.Resource.REST|Joosy.Resource.RESTCollection]
+  # @return [Joosy.Resource.REST, Joosy.Resource.RESTCollection]
   #
   @find: (description, options) ->
     if Object.isFunction options
@@ -102,8 +99,8 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
   #
   # 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
+  # @param [Hash, Function] options     AJAX options.
+  #   Will be considered as a success callback if function is given.
   # @return [Joosy.Resource.REST]
   #
   fetch: (options) ->
@@ -124,8 +121,8 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
   #
   # Destroys the resource by DELETE query
   #
-  # @param [Function|Object] options  AJAX options.
-  #   Will be considered as a success callback if function given
+  # @param [Hash, Function] options     AJAX options.
+  #   Will be considered as a success callback if function is given.
   # @return [Joosy.Resource.REST]
   #
   destroy: (options) ->
@@ -140,11 +137,11 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
     this
     
   #
-  # Requests the REST member URL with POST or any method given in options.type
+  # 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
+  # @param [String] ending              Member url (like 'foo' or 'foo/bar')
+  # @param [Hash, Function] options     AJAX options.
+  #   Will be considered as a success callback if function is given.
   #
   request: (ending, options) ->
     if Object.isFunction options
@@ -163,18 +160,18 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
   #
   # Checks if given description can be considered as ID
   #
-  # @param [Integer|String|Object] something Value to test
+  # @param [Integer, String, Object] something      Value to test
   # @return [Boolean]
   #
   @__isId: (something) ->
     Object.isNumber(something) || Object.isString(something)
 
   #
-  # jQuery AJAX wrapper
+  # 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 [Hash] options       AJAX options to pass with request
   # @param [Function] callback  XHR callback
   #
   @__ajax: (method, url, options={}, callback) ->
@@ -185,11 +182,12 @@ class Joosy.Resource.REST extends Joosy.Resource.Generic
       dataType: 'json'
 
   #
-  # Builds URL for current resource location
+  # Builds URL for current resource location.
+  #
+  # @param [Hash] options     Handling options
   #
-  # @param [Object] options     Handling options
-  #   extension: string to add to resource base url
-  #   params: GET-params to add to resulting url
+  # @option options [String] extension      String to add to resource base url
+  # @option options [Hash] params           GET-params to add to resulting url
   #
   @__buildSource: (options={}) ->
     unless @hasOwnProperty '__source'

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

@@ -1,18 +1,18 @@
 #
-# Collection of Resources with REST-fetching capabilities
+# Collection of Resources with REST-fetching capabilities.
 #
-# Generally you should not use RESTCollection directly. It will be
-# automatically created by Joosy.Resource.REST#find.
+# @note Generally you should not use RESTCollection directly. It will be
+#   automatically created by Joosy.Resource.REST#find.
 #
-# Example:
+# @example Basic samples
 #   class R extends Joosy.Resource.REST
 #     @entity 'r'
-#
+#   
 #   collection = new Joosy.Resource.RESTCollection(R, {color: 'green'})
-#
+#   
 #   collection.fetch()
 #   collection.page 2
-#
+#   
 #   collection.params = {color: 'red', sort: 'date'}
 #   collection.fetch()
 #
@@ -21,22 +21,27 @@ class Joosy.Resource.RESTCollection extends Joosy.Resource.Collection
   @include Joosy.Modules.Events
 
   #
-  # Hash containing the cache for pages of raw data
-  # Keys are pages numbers, values are stored AJAX response
+  # Hash containing the cache for pages of raw data.
+  # Keys are pages numbers, values are stored AJAX response.
   #
   pages: Object.extended()
 
   #
   # @param [Class] model      Resource class this collection will handle
-  # @param [Object] params    Additional GET-parameters to supply when fetching
+  # @param [Hash] params      Additional parameters that will be added to all REST requests.
   #
-  constructor: (@model, params={}) ->
+  constructor: (model, params={}) ->
+    super model
     @params = Object.extended params
 
   #
-  # Clears the storage and attempts to import given JSON
+  # Clears the storage and attempts to import given array
   #
-  # @param [Object] entities    Entities to import
+  # @param [Array, Hash] entities     Array of entities to import.
+  #   If hash was given will seek for moodel name camelized and pluralized.
+  # @param [Boolean] notify           Indicates whether to trigger 'changed' event
+  #
+  # @return [Joosy.Resource.RESTCollection]   Returns self.
   #
   reset: (entities, notify=true) ->
     super entities, false
@@ -45,10 +50,12 @@ class Joosy.Resource.RESTCollection extends Joosy.Resource.Collection
     this
 
   #
-  # Clears the storage and gets new data from server
+  # Clears the storage and gets new data from server.
+  #
+  # @param [Hash, Function] options     AJAX options.
+  #   Will be considered as a success callback if function is given.
   #
-  # @param [Function|Object] options                AJAX options.
-  #   Will be considered as a success callback if function given
+  # @return [Joosy.Resource.RESTCollection]   Returns self.
   #
   fetch: (options) ->
     if Object.isFunction options
@@ -64,11 +71,13 @@ class Joosy.Resource.RESTCollection extends Joosy.Resource.Collection
     this
 
   #
-  # Returns the subset for requested page. Requests with &page=x if not found localy.
+  # Returns the subset for requested page: requests with &page=x.
+  #
+  # @param [Integer] number             Index of page
+  # @param [Hash, Function] options     AJAX options.
+  #   Will be considered as a success callback if function is given.
   #
-  # @param [Integer] number               Index of page
-  # @param [Function|Object] options      AJAX options.
-  #   Will be considered as a success callback if function given
+  # @return [Joosy.Resource.RESTCollection]   Returns self.
   #
   page: (number, options) ->
     if Object.isFunction options
@@ -84,11 +93,11 @@ class Joosy.Resource.RESTCollection extends Joosy.Resource.Collection
     this
     
   #
-  # Requests the REST collection URL with POST or any method given in options.type
+  # Requests the REST collection URL with POST or any method given in options.type.
   #
-  # @param [String] ending            Collection url (like 'foo' or 'foo/bar')
-  # @param [Function|Object] options  AJAX options.
-  #   Will be considered as a success callback if function given
+  # @param [String] ending              Collection url (like 'foo' or 'foo/bar')
+  # @param [Hash, Function] options     AJAX options.
+  #   Will be considered as a success callback if function is given.
   #
   request: (ending, options) ->
     if Object.isFunction options
@@ -105,10 +114,10 @@ class Joosy.Resource.RESTCollection extends Joosy.Resource.Collection
     @model.__ajax type, @model.__buildSource(extension: ending), options, callback
     
   #
-  # Does AJAX request
+  # Internal AJAX request implementation.
   #
-  # @param [Object] urlOptions      GET-params for request
-  # @param [Object] ajaxOptions     AJAX options to pass with request
+  # @param [Hash] urlOptions      GET-params for request
+  # @param [Hash] ajaxOptions     AJAX options to pass with request
   # @param [Function] callback
   #
   __fetch: (urlOptions, ajaxOptions, callback) ->