brainstem-js 0.2.1 → 0.3.0

data/vendor/assets/javascripts/brainstem/brainstem-collection.coffee

@@ -18,22 +18,32 @@ class window.Brainstem.Collection extends Backbone.Collection
       else
         Brainstem.Utils.warn "Unable to update collection with invalid model", model
 
-  loadNextPage: (options) =>
+  loadNextPage: (options) ->
     oldLength = @length
+    pageSize = 0
+    paginationOptions = {}
+
+    if @lastFetchOptions.perPage
+      paginationOptions.page = @lastFetchOptions.page + 1
+      pageSize = @lastFetchOptions.perPage
+    else
+      paginationOptions.offset = @lastFetchOptions.offset + @lastFetchOptions.limit
+      pageSize = @lastFetchOptions.limit
+
     success = (collection) =>
-      options.success(collection, collection.length == oldLength + @lastFetchOptions.perPage) if options.success?
-    base.data.loadCollection @lastFetchOptions.name, _.extend({}, @lastFetchOptions, options, page: @lastFetchOptions.page + 1, collection: this, success: success)
+      options.success(collection, collection.length == oldLength + pageSize) if options.success?
+    base.data.loadCollection @lastFetchOptions.name, _.extend({}, @lastFetchOptions, options, paginationOptions, collection: this, success: success)
 
-  reload: (options) =>
+  reload: (options) ->
     base.data.reset()
     @reset [], silent: true
     @setLoaded false
     base.data.loadCollection @lastFetchOptions.name, _.extend({}, @lastFetchOptions, options, page: 1, collection: this)
 
-  getWithAssocation: (id) =>
+  getWithAssocation: (id) ->
     @get(id)
 
-  toServerJSON: (method) =>
+  toServerJSON: (method) ->
     @toJSON()
 
   @getComparatorWithIdFailover: (order) ->

data/vendor/assets/javascripts/brainstem/brainstem-expectation.coffee

@@ -1,13 +1,13 @@
 window.Brainstem ?= {}
 
 class window.Brainstem.Expectation
-  constructor: (collectionName, options, manager) ->
-    @collectionName = collectionName
+  constructor: (name, options, manager) ->
+    @name = name
     @manager = manager
-    @manager._checkPageSettings options
+    @manager._setDefaultPageSettings options
     @options = options
-    @results = []
     @matches = []
+    @recursive = false
     @triggerError = options.triggerError
     @immediate = options.immediate
     delete options.immediate
@@ -16,50 +16,100 @@ class window.Brainstem.Expectation
     @requestQueue = []
     @options.response(@) if @options.response?
 
-  remove: =>
+  remove: ->
     @disabled = true
 
-  recordRequest: (collection, callOptions) =>
+  recordRequest: (loader) ->
     if @immediate
-      @handleRequest collection: collection, callOptions: callOptions
+      @handleRequest(loader)
     else
-      @requestQueue.push collection: collection, callOptions: callOptions
+      @requestQueue.push(loader)
 
-  respond: =>
+  respond: ->
     for request in @requestQueue
       @handleRequest request
     @requestQueue = []
 
-  handleRequest: (options) =>
-    @matches.push options.callOptions
+  handleRequest: (loader) ->
+    @matches.push loader.originalOptions
+
+    unless @recursive
+      # we don't need to fetch additional things from the server in an expectation.
+      loader.loadOptions.include = []
 
     if @triggerError?
-      return @manager.errorInterceptor(options.callOptions.error, options.collection, options.callOptions, @triggerError)
+      return @manager.errorInterceptor(loader.originalOptions.error, loader.externalObject, loader.originalOptions, @triggerError)
+
+    @_handleAssociations(loader)
+
+    if loader instanceof Brainstem.CollectionLoader
+      returnedData = @_handleCollectionResults(loader)
+    else
+      returnedData = @_handleModelResults(loader)
+
+    loader._onLoadSuccess(returnedData)
+
+  loaderOptionsMatch: (loader) ->
+    return false if @disabled
+    return false if @name != loader._getExpectationName()
+
+    @manager._checkPageSettings(loader.originalOptions)
+
+    _.all ['include', 'only', 'order', 'filters', 'perPage', 'page', 'limit', 'offset', 'search'], (optionType) =>
+      return true if @options[optionType] == '*'
+
+      option = _.compact(_.flatten([loader.originalOptions[optionType]]))
+      expectedOption = _.compact(_.flatten([@options[optionType]]))
 
+      if optionType == 'include'
+        option = Brainstem.Utils.wrapObjects(option)
+        expectedOption = Brainstem.Utils.wrapObjects(expectedOption)
+
+      Brainstem.Utils.matches(option, expectedOption)
+
+  _handleAssociations: (_loader) ->
     for key, values of @associated
       values = [values] unless values instanceof Array
       for value in values
         @manager.storage(value.brainstemKey).update [value]
 
+  _handleCollectionResults: (loader) ->
+    return if not @results
+
     for result in @results
       if result instanceof Brainstem.Model
         @manager.storage(result.brainstemKey).update [result]
 
-    returnedModels = _(@results).map (result) =>
+    returnedModels = _.map @results, (result) =>
       if result instanceof Brainstem.Model
         @manager.storage(result.brainstemKey).get(result.id)
       else
         @manager.storage(result.key).get(result.id)
 
-    @manager._success(options.callOptions, options.collection, returnedModels)
+    returnedModels
+
+  _handleModelResults: (loader) ->
+    return if !@result
 
-  optionsMatch: (name, options) =>
-    @manager._checkPageSettings options
-    if !@disabled && @collectionName == name
-      _(['include', 'only', 'order', 'filters', 'perPage', 'page', 'search']).all (optionType) =>
-        @options[optionType] == "*" || Brainstem.Utils.matches(_.compact(_.flatten([options[optionType]])), _.compact(_.flatten([@options[optionType]])))
+    # Put main (loader) model in storage manager.
+    if @result instanceof Brainstem.Model
+      key = @result.brainstemKey
+      attributes = @result.attributes
     else
-      false
+      key = @result.key
+      attributes = _.omit @result, 'key'
+
+    if !key
+      throw 'Brainstem key is required on the result (brainstemKey on model or key in JSON)'
+
+    existingModel = @manager.storage(key).get(attributes.id)
+
+    unless existingModel
+      existingModel = loader.getModel()
+      @manager.storage(key).add(existingModel)
+
+    existingModel.set(attributes)
+    existingModel
 
   lastMatch: ->
     @matches[@matches.length - 1]

data/vendor/assets/javascripts/brainstem/brainstem-model.coffee

@@ -2,10 +2,6 @@
 
 # Extend Backbone.Model to include associations.
 class window.Brainstem.Model extends Backbone.Model
-  constructor: ->
-    super
-    @setLoaded false
-
   # Parse ISO8601 attribute strings into date objects
   @parse: (modelObject) ->
     for k,v of modelObject
@@ -15,7 +11,7 @@ class window.Brainstem.Model extends Backbone.Model
     return modelObject
 
   # Handle create and update responses with JSON root keys
-  parse: (resp, xhr) =>
+  parse: (resp, xhr) ->
     @updateStorageManager(resp)
     modelObject = @_parseResultsResponse(resp)
     super(@constructor.parse(modelObject), xhr)
@@ -38,7 +34,11 @@ class window.Brainstem.Model extends Backbone.Model
         if collectionModel
           collectionModel.set(attributes)
         else
-          collection.add(attributes)
+          if @brainstemKey == underscoredModelName && (@isNew() || @id == attributes.id)
+            @set(attributes)
+            collection.add(this)
+          else
+            collection.add(attributes)
 
   _parseResultsResponse: (resp) ->
     return resp unless resp['results']
@@ -75,8 +75,10 @@ class window.Brainstem.Model extends Backbone.Model
   # provided, all associations are assumed.
   #   model.associationsAreLoaded(["project", "task"]) # => true|false
   #   model.associationsAreLoaded() # => true|false
-  associationsAreLoaded: (associations) =>
+  associationsAreLoaded: (associations) ->
     associations ||= _.keys(@constructor.associations)
+    associations = _.select associations, (association) => @constructor.associationDetails(association)
+
     _.all associations, (association) =>
       details = @constructor.associationDetails(association)
       if details.type == "BelongsTo"
@@ -85,7 +87,7 @@ class window.Brainstem.Model extends Backbone.Model
         @attributes.hasOwnProperty(details.key) && _.all(@attributes[details.key], (id) -> base.data.storage(details.collectionName).get(id))
 
   # Override Model#get to access associations as well as fields.
-  get: (field, options = {}) =>
+  get: (field, options = {}) ->
     if details = @constructor.associationDetails(field)
       if details.type == "BelongsTo"
         id = @get(details.key) # project_id
@@ -111,7 +113,7 @@ class window.Brainstem.Model extends Backbone.Model
     else
       super(field)
 
-  className: =>
+  className: ->
     @paramRoot
 
   defaultJSONBlacklist: ->
@@ -123,7 +125,7 @@ class window.Brainstem.Model extends Backbone.Model
   updateJSONBlacklist: ->
     []
 
-  toServerJSON: (method, options) =>
+  toServerJSON: (method, options) ->
     json = @toJSON(options)
     blacklist = @defaultJSONBlacklist()
 
@@ -136,6 +138,4 @@ class window.Brainstem.Model extends Backbone.Model
     for blacklistKey in blacklist
       delete json[blacklistKey]
 
-    json
-
-_.extend(Brainstem.Model.prototype, Brainstem.LoadingMixin);
+    json

data/vendor/assets/javascripts/brainstem/brainstem-sync.coffee

@@ -36,7 +36,7 @@ Backbone.sync = (method, model, options) ->
     else
       data = json
 
-    data.include = Brainstem.Utils.extractArray("include", options).join(";")
+    data.include = Brainstem.Utils.extractArray("include", options).join(",")
     data.filters = Brainstem.Utils.extractArray("filters", options).join(",")
     params.data = JSON.stringify(data)
 
@@ -57,6 +57,10 @@ Backbone.sync = (method, model, options) ->
       if beforeSend
         beforeSend.apply this, arguments
 
+  # Clear out default data for DELETE requests, fixes a firefox issue where this exception is thrown: JavaScript component does not have a method named: “available”
+  if params.type == 'DELETE'
+    params.data = null
+
   # Don't process data on a non-GET request.
   if params.type != 'GET' && !options.emulateJSON
     params.processData = false
@@ -67,8 +71,9 @@ Backbone.sync = (method, model, options) ->
   if params.type == 'PATCH' && window.ActiveXObject && !(window.external && window.external.msActiveXFilteringEnabled)
     params.xhr = -> new ActiveXObject("Microsoft.XMLHTTP")
 
-  errorHandler = options.error
-  options.error = (jqXHR, textStatus, errorThrown) -> base?.data?.errorInterceptor?(errorHandler, model, options, jqXHR, params)
+  if base?.data?.errorInterceptor?
+    errorHandler = options.error
+    options.error = (jqXHR, textStatus, errorThrown) -> base.data.errorInterceptor(errorHandler, model, options, jqXHR, params)
 
   # Make the request, allowing the user to override any Ajax options.
   xhr = options.xhr = Backbone.ajax(_.extend(params, options))

data/vendor/assets/javascripts/brainstem/loaders/abstract-loader.coffee

@@ -0,0 +1,289 @@
+window.Brainstem ?= {}
+
+class Brainstem.AbstractLoader
+  internalObject: null
+  externalObject: null
+
+  constructor: (options = {}) ->
+    @storageManager = options.storageManager
+
+    @_deferred = $.Deferred()
+    @_deferred.promise(this)
+
+    if options.loadOptions
+      @setup(options.loadOptions)
+
+  ###*
+   * Setup the loader with a list of Brainstem specific loadOptions
+   * @param  {object} loadOptions Brainstem specific loadOptions (filters, include, only, etc)
+   * @return {object} externalObject that was created.
+  ###
+  setup: (loadOptions) ->
+    @_parseLoadOptions(loadOptions)
+    @_createObjects()
+
+    @externalObject
+
+  ###*
+   * Parse supplied loadOptions, add defaults, transform them into appropriate structures, and pull out important pieces.
+   * @param  {object} loadOptions
+   * @return {object} transformed loadOptions
+  ###
+  _parseLoadOptions: (loadOptions = {}) ->
+    @originalOptions = _.clone(loadOptions)
+    @loadOptions = _.clone(loadOptions)
+    @loadOptions.include = Brainstem.Utils.wrapObjects(Brainstem.Utils.extractArray "include", @loadOptions)
+    @loadOptions.only = if @loadOptions.only then _.map((Brainstem.Utils.extractArray "only", @loadOptions), (id) -> String(id)) else null
+    @loadOptions.filters ?= {}
+    @loadOptions.thisLayerInclude = _.map @loadOptions.include, (i) -> _.keys(i)[0] # pull off the top layer of includes
+
+    # Determine whether or not we should look at the cache
+    @loadOptions.cache ?= true
+    @loadOptions.cache = false if @loadOptions.search
+
+    # Build cache key
+    filterKeys = _.map(@loadOptions.filters, (v, k) -> "#{k}:#{v}").join(',')
+    @loadOptions.cacheKey = [@loadOptions.order || "updated_at:desc", filterKeys, @loadOptions.page, @loadOptions.perPage, @loadOptions.limit, @loadOptions.offset].join('|')
+
+    @cachedCollection = @storageManager.storage @_getCollectionName()
+
+    @loadOptions
+
+  ###*
+   * Sets up both the `internalObject` and `externalObject`.
+   * In the case of models the `internalObject` and `externalObject` are the same.
+   * In the case of collections the `internalObject` is a proxy object that updates the `externalObject` when all loading is completed.
+   * @return {[type]} [description]
+  ###
+  _createObjects: ->
+    throw "Implement in your subclass"
+
+  ###*
+   * Loads the model from memory or the server.
+   * @return {object} the loader's `externalObject`
+  ###
+  load: ->
+    if not @loadOptions
+      throw "You must call #setup first or pass loadOptions into the constructor"
+
+    # Check the cache to see if we have everything that we need.
+    if @loadOptions.cache && data = @_checkCacheForData()
+      data
+    else
+      @_loadFromServer()
+
+  ###*
+   * Checks to see if the current requested data is available in the caching layer.
+   * If it is available then update the externalObject with that data (via `_onLoadSuccess`).
+   * @return {[boolean|object]} returns false if not found otherwise returns the externalObject.
+  ###
+  _checkCacheForData: ->
+    if @loadOptions.only?
+      @alreadyLoadedIds = _.select @loadOptions.only, (id) => @cachedCollection.get(id)?.associationsAreLoaded(@loadOptions.thisLayerInclude)
+      if @alreadyLoadedIds.length == @loadOptions.only.length
+        # We've already seen every id that is being asked for and have all the associated data.
+        @_onLoadSuccess(_.map @loadOptions.only, (id) => @cachedCollection.get(id))
+        return @externalObject
+    else
+      # Check if we have a cache for this request and if so make sure that all of the requested includes for this layer are loaded on those models.
+      if @storageManager.getCollectionDetails(@_getCollectionName()).cache[@loadOptions.cacheKey]
+        subset = _(@storageManager.getCollectionDetails(@_getCollectionName()).cache[@loadOptions.cacheKey]).map (result) => @storageManager.storage(result.key).get(result.id)
+        if (_.all(subset, (model) => model.associationsAreLoaded(@loadOptions.thisLayerInclude)))
+          @_onLoadSuccess(subset)
+          return @externalObject
+
+    return false
+
+  ###*
+   * Makes a GET request to the server via Backbone.sync with the built syncOptions.
+   * @return {object} externalObject that will be updated when everything is complete.
+  ###
+  _loadFromServer: ->
+    jqXhr = Backbone.sync.call @internalObject, 'read', @internalObject, @_buildSyncOptions()
+
+    if @loadOptions.returnValues
+      @loadOptions.returnValues.jqXhr = jqXhr
+
+    @externalObject
+
+  ###*
+   * Called when the Backbone.sync successfully responds from the server.
+   * @param  {object} resp    JSON response from the server.
+   * @param  {string} _status
+   * @param  {object} _xhr    jQuery XHR object
+   * @return {undefined}
+  ###
+  _onServerLoadSuccess: (resp, _status, _xhr) =>
+    data = @_updateStorageManagerFromResponse(resp)
+    @_onLoadSuccess(data)
+
+  ###*
+   * Called when the server responds with data and needs to be persisted to the storageManager.
+   * @param  {object} resp JSON data from the server
+   * @return {[array|object]} array of models or model that was parsed.
+  ###
+  _updateStorageManagerFromResponse: (resp) ->
+    throw "Implement in your subclass"
+
+  ###*
+   * Updates the internalObject with the data in the storageManager and either loads more data or resolves this load.
+   * Called after sync + storage manager upadting.
+   * @param  {array|object} data array of models or model from _updateStorageManagerFromResponse
+   * @return {undefined}
+  ###
+  _onLoadSuccess: (data) ->
+    @_updateObjects(@internalObject, data, true)
+    @_calculateAdditionalIncludes()
+
+    if @additionalIncludes.length
+      @_loadAdditionalIncludes()
+    else
+      @_onLoadingCompleted()
+
+  ###*
+   * Called after the server responds with the first layer of includes to determine if any more loads are needed.
+   * It will only make additional loads if there were IDs returned during this load for a given association.
+   * @return {undefined}
+  ###
+  _calculateAdditionalIncludes: ->
+    @additionalIncludes = []
+
+    for hash in @loadOptions.include 
+      associationName = _.keys(hash)[0]
+      associationIds = @_getIdsForAssociation(associationName)
+      associationInclude = hash[associationName]
+
+      if associationIds.length && associationInclude.length
+        @additionalIncludes.push
+          name: associationName
+          ids: associationIds
+          include: associationInclude
+
+  ###*
+   * Loads the next layer of includes from the server.
+   * When all loads are complete, it will call `_onLoadingCompleted` which will resolve this layer.
+   * @return {undefined}
+  ###
+  _loadAdditionalIncludes: ->
+    promises = []
+
+    for association in @additionalIncludes
+      collectionName = @_getModel().associationDetails(association.name).collectionName
+
+      loadOptions =
+        only: association.ids
+        include: association.include
+        error: @loadOptions.error
+
+      promises.push(@storageManager.loadObject(collectionName, loadOptions))
+
+    $.when.apply($, promises).done(@_onLoadingCompleted)
+
+  ###*
+   * Called when all loading (including nested loads) are complete.
+   * Updates the `externalObject` with the data that was gathered and resolves the promise.
+   * @return {undefined}
+  ###
+  _onLoadingCompleted: =>
+    @_updateObjects(@externalObject, @internalObject)
+    @_deferred.resolve(@externalObject)
+
+  ###*
+   * Updates the object with the supplied data. Will be called:
+   *   + after the server responds, `object` will be `internalObject` and data will be the result of `_updateStorageManagerFromResponse`
+   *   + after all loading is complete, `object` will be the `externalObject` and data will be the `internalObject`
+   * @param  {object} object object that will receive the data
+   * @param  {object} data data that needs set on the object
+   * @param  {boolean} silent whether or not to trigger loaded at the end of the update
+   * @return {undefined}
+  ###
+  _updateObjects: (object, data, silent = false) ->
+    throw "Implement in your subclass"
+
+  ###*
+   * Generates the Brainstem specific options that are passed to Backbone.sync.
+   * @return {object} options that are passed to Backbone.sync
+  ###
+  _buildSyncOptions: ->
+    syncOptions =
+      data: {}
+      parse: true
+      error: @loadOptions.error
+      success: @_onServerLoadSuccess
+
+    syncOptions.data.include = @loadOptions.thisLayerInclude.join(",") if @loadOptions.thisLayerInclude.length
+
+    if @loadOptions.only && @_shouldUseOnly()
+      syncOptions.data.only = _.difference(@loadOptions.only, @alreadyLoadedIds).join(",")
+
+    syncOptions.data.order = @loadOptions.order if @loadOptions.order?
+    _.extend(syncOptions.data, _(@loadOptions.filters).omit('include', 'only', 'order', 'per_page', 'page', 'limit', 'offset', 'search')) if _(@loadOptions.filters).keys().length
+
+    unless @loadOptions.only?
+      if @loadOptions.limit? && @loadOptions.offset?
+        syncOptions.data.limit = @loadOptions.limit
+        syncOptions.data.offset = @loadOptions.offset
+      else
+        syncOptions.data.per_page = @loadOptions.perPage
+        syncOptions.data.page = @loadOptions.page
+
+    syncOptions.data.search = @loadOptions.search if @loadOptions.search
+    syncOptions
+
+  ###*
+   * Decides whether or not the `only` filter should be applied in the syncOptions.
+   * Models will not use the `only` filter as they use show routes.
+   * @return {boolean} whether or not to use the `only` filter
+  ###
+  _shouldUseOnly: ->
+    @internalObject instanceof Backbone.Collection
+
+  ###*
+   * Returns the name of the collection that this loader maps to and will update in the storageManager.
+   * @return {string} name of the collection
+  ###
+  _getCollectionName: ->
+    throw "Implement in your subclass"
+
+  ###*
+   * Returns the name that expectations will be stubbed with (story or stories etc)
+   * @return {string} name of the stub
+  ###
+  _getExpectationName: ->
+    throw "Implement in your subclass"
+
+  ###*
+   * This needs to return a constructor for the model that associations will be compared with.
+   * This typically will be the current collection's model/current model constructor.
+   * @return {Brainstem.Model}
+  ###
+  _getModel: ->
+    throw "Implement in your subclass"
+
+  ###*
+   * This needs to return an array of models that correspond to the supplied association.
+   * @return {array} models that are associated with this association
+  ###
+  _getModelsForAssociation: (association) ->
+    throw "Implement in your subclass"
+
+  ###*
+   * Returns an array of IDs that need to be loaded for this association.
+   * @param  {string} association name of the association
+   * @return {array} array of IDs to fetch for this association.
+  ###
+  _getIdsForAssociation: (association) ->
+    models = @_getModelsForAssociation(association)
+    _(models).chain().flatten().pluck("id").compact().uniq().sort().value()
+
+  ###*
+   * Parses the result of model.get(associationName) to either return a collection's models
+   * or the model itself.
+   * @param  {object|Backbone.Collection} obj result of calling `.get` on a model with an association name.
+   * @return {object|array} either a model object or an array of models from a collection.
+  ###
+  _modelsOrObj: (obj) ->
+    if obj instanceof Backbone.Collection
+      obj.models
+    else
+      obj || [] # TODO: revisit this.. we shouldn't be getting to this stage.