joosy 1.2.0.beta.4 → 1.2.0.rc.1

data/source/joosy/modules/resources.coffee

@@ -1 +1,4 @@
+#
+# The namespace for resources modules
+#
 Joosy.Modules.Resources = {}

data/source/joosy/modules/resources/cacher.coffee

@@ -1,13 +1,73 @@
 #= require ../resources
 
+#
+# Cacher allows you to implement the delayed refresh of a resource.
+#
+# During the first fetch it stores the current value to localStorage
+# and on the second call it returns the cached value. At the same moment
+# it starts the new fetch and triggers 'changed' event as soon as
+# the new value arrives.
+#
+# When used in conjuction with `@renderDynamic` it allows you to render
+# template with cached value immediately. And the new arrived value will
+# automatically be injected into DOM.
+#
+# @example
+#   class Test extends Joosy.Resources.Hash
+#     @concern Joosy.Modules.Resources.Cacher
+#
+#     @cache 'test' # key to use at localStorage
+#     @fetcher (callback) ->
+#       $.get '...', (data) -> callback data
+#
+#   Test.cached (instance) ->
+#     # ...
+#
 # @mixin
 Joosy.Modules.Resources.Cacher =
 
-  included: ->
-    @cache   = (cacheKey) -> @::__cacheKey = cacheKey
-    @fetcher = (fetcher) -> @::__fetcher = fetcher
+  ClassMethods:
+    #
+    # Defines the key that will be used to reference
+    # the cached value at localStorage. Unless specified
+    # localStorage will not be used.
+    #
+    # @param [String] cacheKey
+    # @example
+    #   class Test extends Joosy.Resources.Hash
+    #     @concern Joosy.Modules.Resources.Cacher
+    #     @cache 'test'
+    #
+    cache: (cacheKey) -> @::__cacheKey = cacheKey
 
-    @cached = (callback, cacheKey=false, fetcher=false) ->
+    #
+    # Defines the asynchronous routine that will be used
+    # to load the actual value of resource when `cached` is called.
+    #
+    # @param [Function<Function>] fetcher
+    # @example
+    #   class Test extends Joosy.Resources.Hash
+    #     @concern Joosy.Modules.Resources.Cacher
+    #     @fetcher (callback) ->
+    #       $.get '...', (data) -> callback data
+    #
+    fetcher: (fetcher) -> @::__fetcher = fetcher
+
+    #
+    # The main resolver of current value. If the cached
+    # value is available it is returned immediately. Otherwise
+    # the actual value is loaded.
+    #
+    # During the first fetch it stores the current value to localStorage
+    # and on the second call it returns the cached value. At the same moment
+    # it starts the new fetch and triggers 'changed' event as soon as
+    # the new value arrives.
+    #
+    # @param [Function<Cacher>] callback        Action to perform with resulting instance of resource
+    # @param [String] cacheKey                  The override for {Joosy.Modules.Resources.Cacher.cache}
+    # @param [Function<Function>] fetcher       The override for {Joosy.Modules.Resources.Cacher.fetcher}
+    #
+    cached: (callback, cacheKey=false, fetcher=false) ->
       if typeof(cacheKey) == 'function'
         fetcher  = cacheKey
         cacheKey = undefined
@@ -23,16 +83,27 @@ Joosy.Modules.Resources.Cacher =
         @fetch (results) =>
           instance = @build results...
           callback? instance
-
-    @fetch = (callback) ->
+    #
+    # Low-level fetcher that gets the actual value and stores it to
+    # localStorage (if required)
+    #
+    # @param [Function<Mixed>] callback        Action to perform with raw fetched value
+    #
+    fetch: (callback) ->
       @::__fetcher (results...) =>
         localStorage[@::__cacheKey] = JSON.stringify(results) if @::__cacheKey && localStorage
         callback results
 
-  refresh: (callback) ->
-    @constructor.fetch (results) =>
-      @load results...
-      callback? @
+  InstanceMethods:
+    #
+    # Refreshes the value in both – the cache and the resource itself
+    #
+    # @param [Function<Cacher>] callback        Action to perform with resulting instance of resource
+    #
+    refresh: (callback) ->
+      @constructor.fetch (results) =>
+        @load results...
+        callback? @
 
 # AMD wrapper
 if define?.amd?

data/source/joosy/modules/resources/function.coffee

@@ -1,41 +1,38 @@
 #
 # Module allowing to emulate Fn-based instances in JS
 #
-# @mixin
-#
 # @example
-#   class Foo extends Joosy.Module
-#
-#     @extend Joosy.Module.Function
+#   class Foo extends Joosy.Modules.Resources.Hash
+#     @concern Joosy.Module.Function
 #
-#     constructor: (value)
-#       @value = value
+#   foo = Foo.build foo: 'bar'
+#   typeof(foo)                  # 'function'
+#   foo('foo')                   # 'bar'
 #
-#   __call: -> @value
-#
-#   foo = Foo.build 'test'
-#   typeof(foo)             # 'function'
-#   foo()                   # 'test'
+# @mixin
 #
 Joosy.Modules.Resources.Function =
 
-  extended: ->
-    if @build
-      @aliasStaticMethodChain 'build', 'function'
-    else
-      @build = @buildWithFunction
-      @buildWithoutFunction = ->
-        new @ arguments...
+  ClassMethods:
+    # @nodoc
+    extended: ->
+      if @build
+        @aliasStaticMethodChain 'build', 'function'
+      else
+        @build = @buildWithFunction
+        @buildWithoutFunction = ->
+          new @ arguments...
 
-  buildWithFunction: ->
-    shim  = -> shim.__call.apply shim, arguments
-    proto = @buildWithoutFunction arguments...
+    # @nodoc
+    buildWithFunction: ->
+      shim  = -> shim.__call.apply shim, arguments
+      proto = @buildWithoutFunction arguments...
 
-    if shim.__proto__
-      shim.__proto__ = proto
-    else
-      for key, value of proto
-        shim[key] = value
+      if shim.__proto__
+        shim.__proto__ = proto
+      else
+        for key, value of proto
+          shim[key] = value
 
-    shim.constructor = proto.constructor
-    shim
+      shim.constructor = proto.constructor
+      shim

data/source/joosy/modules/resources/identity_map.coffee

@@ -1,47 +1,69 @@
 #= require ../resources
 
+#
+# The basic implementation of Identity Map allowing you to automatically
+# make all the instances of the same model to be a single JS Object.
+#
+# @example
+#   class Model extends Joosy.Resources.Hash
+#      @concern Joosy.Modules.Resources.Model
+#      @concern Joosy.Modules.Resources.IdentityMap
+#
+#   foo = Test.build id: 1
+#   bar = Test.build id: 1   # bar === foo
+#
 # @mixin
+#
 Joosy.Modules.Resources.IdentityMap =
 
-  extended: ->
-    @::__identityHolder = @
-    @aliasStaticMethodChain 'build', 'identityMap'
-
-  #
-  # Clears the identity map cache. Recomended to be called during layout switch to
-  # ensure correct garbage collection.
-  #
-  identityReset: ->
-    @::__identityHolder.identity = {}
-
-  identityPath: (data) ->
-    [
-      @::__entityName,         # entity name as a first-level entry to make inheritance safe
-      "s#{@__source || ''}",   # save identity from overlaping on `@at` calls
-      data[@::__primaryKey]    # direct identifier as a main distinguisher
-    ]
-
-  #
-  # Wraps instance of resource inside shim-function allowing to track
-  # data changes. See class example
-  #
-  # @return [Joosy.Resources.REST]
-  #
-  buildWithIdentityMap: (data={}) ->
-    elements = @identityPath(data)
-
-    if elements.filter((element) -> !element?).length == 0
-      location    = @::__identityHolder.identity ?= {}
-      destination = elements.pop()
-      location    = location[element] ?= {} for element in elements
-
-      # Data can be circulary referenced so we have to
-      # init identity cell as a first step...
-      preload = {}
-      preload[@::__primaryKey] = data[@::__primaryKey]
-      location[destination] ?= @buildWithoutIdentityMap preload
-
-      # ...and load data as a second
-      location[destination].load data
-    else
-      @buildWithoutIdentityMap data
+  ClassMethods:
+    # @nodoc
+    extended: ->
+      @::__identityHolder = @
+      @aliasStaticMethodChain 'build', 'identityMap'
+
+    #
+    # Clears the identity map cache. Recomended to be called during layout switch to
+    # ensure correct garbage collection.
+    #
+    identityReset: ->
+      @::__identityHolder.identity = {}
+
+    #
+    # Defines the array of values identifying a unique object within a set
+    #
+    # @param [Mixed] data            The data given upon object creation
+    # @return [Array<Mixed>]         Uniqueness path
+    #
+    identityPath: (data) ->
+      [
+        @::__entityName,         # entity name as a first-level entry to make inheritance safe
+        "s#{@__source || ''}",   # save identity from overlaping on `@at` calls
+        data[@::__primaryKey]    # direct identifier as a main distinguisher
+      ]
+
+    #
+    # Wraps instance of resource inside shim-function allowing to track
+    # data changes. See class example
+    #
+    # @private
+    # @return [Mixed]
+    #
+    buildWithIdentityMap: (data={}) ->
+      elements = @identityPath(data)
+
+      if elements.filter((element) -> !element?).length == 0
+        location    = @::__identityHolder.identity ?= {}
+        destination = elements.pop()
+        location    = location[element] ?= {} for element in elements
+
+        # Data can be circulary referenced so we have to
+        # init identity cell as a first step...
+        preload = {}
+        preload[@::__primaryKey] = data[@::__primaryKey]
+        location[destination] ?= @buildWithoutIdentityMap preload
+
+        # ...and load data as a second
+        location[destination].load data
+      else
+        @buildWithoutIdentityMap data

data/source/joosy/modules/resources/model.coffee

@@ -1,18 +1,23 @@
 #= require ../resources
 
+#
+# The collection of methods extending basic implemenetation of resources
+# adding typical model features and making it aware of primary key and collection.
+#
+# @example
+#   class Test extends Joosy.Resources.Hash
+#     @concern Joosy.Modules.Resources.Model
+#
 # @mixin
 Joosy.Modules.Resources.Model =
 
-  included: ->
+  ClassMethods:
     #
     # Sets the field containing primary key.
     #
-    # @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
     #
-    @primaryKey = (primaryKey) ->
+    primaryKey: (primaryKey) ->
       @::__primaryKey = primaryKey
 
     #
@@ -20,7 +25,7 @@ Joosy.Modules.Resources.Model =
     #
     # @param [Class] klass       Class to use as a collection wrapper
     #
-    @collection = (klass) ->
+    collection: (klass) ->
       @::__collection = klass
 
     #
@@ -29,7 +34,7 @@ Joosy.Modules.Resources.Model =
     #
     # @param [String] name    Singular name of resource
     #
-    @entity = (name) ->
+    entity: (name) ->
       @::__entityName = name
 
     #
@@ -39,22 +44,26 @@ Joosy.Modules.Resources.Model =
     #   to handle inline changes with triggers and all that resources stuff
     #
     # @example Basic usage
-    #   class Zombie extends Joosy.Resources.REST
+    #   class Model extends Joosy.Resources.Hash
+    #     @concern Joosy.Modules.Resources.Model
+    #
+    #   class Zombie extends Model
     #     @entity 'zombie'
-    #   class Puppy extends Joosy.Resources.REST
+    #
+    #   class Puppy extends Model
     #     @entity 'puppy'
     #     @map 'zombies'
     #
     #   p = Puppy.build {zombies: [{foo: 'bar'}]}
     #
-    #   p('zombies')            # Direct access: [{foo: 'bar'}]
+    #   p.get('zombies')        # Direct access: [{foo: 'bar'}]
     #   p.zombies               # Wrapped Collection of Zombie instances
-    #   p.zombies.at(0)('foo')  # bar
+    #   p.zombies[0].get('foo') # bar
     #
     # @param [String] name    Pluralized name of property to define
     # @param [Class] klass    Resource class to instantiate
     #
-    @map = (name, klass=false) ->
+    map: (name, klass=false) ->
       unless klass
 
         klass = window[inflection.camelize inflection.singularize(name)]
@@ -77,10 +86,24 @@ Joosy.Modules.Resources.Model =
     #
     # @param [DOMElement] form      Form to grab
     #
-    @grab = (form) ->
+    grab: (form) ->
       @build({}).grab form
 
-    @attrAccessor = ->
+    #
+    # Registers dynamic accessors for given fields
+    #
+    # @example
+    #   class Test extends Joosy.Resources.Hash
+    #     @concern Joosy.Modules.Resources.Model
+    #
+    #     @attrAccessor 'field1', 'field2'
+    #
+    #   test = Test.build(field1: 'test', field2: 'test')
+    #
+    #   test.field1()               # 'test'
+    #   test.field2('new value')    # 'new value'
+    #
+    attrAccessor: ->
       for attribute in arguments
         do (attribute) =>
           @::[attribute] = (value) ->
@@ -89,63 +112,94 @@ Joosy.Modules.Resources.Model =
             else
               @get attribute
 
+  InstanceMethods:
+    #
+    # Default primary key field 'id'
+    #
+    __primaryKey: 'id'
+
+    #
+    # Default collection: Joosy.Resources.Array
+    #
+    __collection: Joosy.Resources.Array
+
+    #
+    # Getter for the primary key field
+    #
+    # @see Joosy.Modules.Resources.Model.primaryKey
+    #
+    id: ->
+      @data?[@__primaryKey]
+
+    #
+    # Returns the list of known fields for the resource
+    #
+    # @return [Array<String>]
+    #
+    # @example
+    #   class Test extends Joosy.Resources.Hash
+    #     @concern Joosy.Modules.Resources.Model
+    #
+    #   test = Test.build field1: 'test', field2: 'test'
+    #
+    #   test.knownAttributes() # ['field1', 'field2']
+    #
+    knownAttributes: ->
+      Object.keys @data
+
+    #
+    # Set the resource data manually.
+    #
+    # Unlike the basic implementation of load, this one
+    # merges newer and older fieldsets that allows you to
+    # receive different parts of model data from different endpoints.
+    #
+    # @param [Object] data      Data to store
+    # @param [Boolean] clear    Whether previous data should be overwriten (not merged)
+    #
+    # @return [Object]          Returns self
+    #
+    load: (data, clear=false) ->
+      @data = {} if clear
+      @__fillData data
+      @
+
+    #
+    # Defines how exactly prepared data should be saved
+    #
+    # @param [Object] data    Raw data to store
+    # @private
+    #
+    __fillData: (data, notify=true) ->
+      @raw  = data
+      @data = {} unless @hasOwnProperty 'data'
+
+      Joosy.Module.merge @data, @__applyBeforeLoads(data)
+      @trigger 'changed' if notify
+      null
+
+    #
+    # Updates the Resource with a data from given form
+    #
+    # @param [DOMElement] form      Form to grab
+    #
+    # @example
+    #   class Test extends Joosy.Resources.Hash
+    #     @concern Joosy.Modules.Resources.Model
+    #
+    #   test = Test.build().grab($ 'form')
+    #
+    grab: (form) ->
+      data = {}
+      for field in $(form).serializeArray()
+        unless data[field.name]
+          data[field.name] = field.value
+        else
+          data[field.name] = [data[field.name]] unless data[field.name] instanceof Array
+          data[field.name].push field.value
+
+      @load data
 
-  #
-  # Default primary key field 'id'
-  #
-  __primaryKey: 'id'
-
-  #
-  # Default collection: Joosy.Resources.Array
-  #
-  __collection: Joosy.Resources.Array
-
-  id: ->
-    @data?[@__primaryKey]
-
-  knownAttributes: ->
-    Object.keys @data
-
-  #
-  # Set the resource data manually
-  #
-  # @param [Object] data      Data to store
-  #
-  # @return [Object]          Returns self
-  #
-  load: (data, clear=false) ->
-    @data = {} if clear
-    @__fillData data
-    @
-
-  #
-  # Defines how exactly prepared data should be saved
-  #
-  # @param [Object] data    Raw data to store
-  #
-  __fillData: (data, notify=true) ->
-    @raw  = data
-    @data = {} unless @hasOwnProperty 'data'
-
-    Joosy.Module.merge @data, @__applyBeforeLoads(data)
-    @trigger 'changed' if notify
-    null
-
-  #
-  # Updates the Resource with a data from given form
-  #
-  # @param [DOMElement] form      Form to grab
-  #
-  grab: (form) ->
-    data = {}
-    for field in $(form).serializeArray()
-      unless data[field.name]
-        data[field.name] = field.value
-      else
-        data[field.name] = [data[field.name]] unless data[field.name] instanceof Array
-        data[field.name].push field.value
-
-    @load data
-
-  toString: ->
-    "<Resource #{@__entityName}> #{JSON.stringify(@data)}"
+    # @nodoc
+    toString: ->
+      "<Resource #{@__entityName}> #{JSON.stringify(@data)}"