brainstem-js 0.2.1

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

@@ -0,0 +1,141 @@
+#= require ./loading-mixin
+
+# 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
+      # Date.parse will parse ISO 8601 in ECMAScript 5, but we include a shim for now
+      if /\d{4}-\d{2}-\d{2}T\d{2}\:\d{2}\:\d{2}[-+]\d{2}:\d{2}/.test(v)
+        modelObject[k] = Date.parse(v)
+    return modelObject
+
+  # Handle create and update responses with JSON root keys
+  parse: (resp, xhr) =>
+    @updateStorageManager(resp)
+    modelObject = @_parseResultsResponse(resp)
+    super(@constructor.parse(modelObject), xhr)
+
+  updateStorageManager: (resp) ->
+    results = resp['results']
+    return if _.isEmpty(results)
+
+    keys = _.reject(_.keys(resp), (key) -> key == 'count' || key == 'results')
+    primaryModelKey = results[0]['key']
+    keys.splice(keys.indexOf(primaryModelKey), 1)
+    keys.push(primaryModelKey)
+
+    for underscoredModelName in keys
+      models = resp[underscoredModelName]
+      for id, attributes of models
+        @constructor.parse(attributes)
+        collection = base.data.storage(underscoredModelName)
+        collectionModel = collection.get(id)
+        if collectionModel
+          collectionModel.set(attributes)
+        else
+          collection.add(attributes)
+
+  _parseResultsResponse: (resp) ->
+    return resp unless resp['results']
+
+    if resp['results'].length
+      key = resp['results'][0].key
+      id = resp['results'][0].id
+      resp[key][id]
+    else
+      {}
+
+
+  # Retreive details about a named association.  This is a class method.
+  #     Model.associationDetails("project") # => {}
+  #     timeEntry.constructor.associationDetails("project") # => {}
+  @associationDetails: (association) ->
+    @associationDetailsCache ||= {}
+    if @associations && @associations[association]
+      @associationDetailsCache[association] ||= do =>
+        if @associations[association] instanceof Array
+          {
+            type: "HasMany"
+            collectionName: @associations[association][0]
+            key: "#{association.singularize()}_ids"
+          }
+        else
+          {
+            type: "BelongsTo"
+            collectionName: @associations[association]
+            key: "#{association}_id"
+          }
+
+  # This method determines if all of the provided associations have been loaded for this model.  If no associations are
+  # provided, all associations are assumed.
+  #   model.associationsAreLoaded(["project", "task"]) # => true|false
+  #   model.associationsAreLoaded() # => true|false
+  associationsAreLoaded: (associations) =>
+    associations ||= _.keys(@constructor.associations)
+    _.all associations, (association) =>
+      details = @constructor.associationDetails(association)
+      if details.type == "BelongsTo"
+        @attributes.hasOwnProperty(details.key) && (@attributes[details.key] == null || base.data.storage(details.collectionName).get(@attributes[details.key]))
+      else
+        @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 = {}) =>
+    if details = @constructor.associationDetails(field)
+      if details.type == "BelongsTo"
+        id = @get(details.key) # project_id
+        if id?
+          base.data.storage(details.collectionName).get(id) || (Brainstem.Utils.throwError("Unable to find #{field} with id #{id} in our cached #{details.collectionName} collection.  We know about #{base.data.storage(details.collectionName).pluck("id").join(", ")}"))
+      else
+        ids = @get(details.key) # time_entry_ids
+        models = []
+        notFoundIds = []
+        if ids
+          for id in ids
+            model = base.data.storage(details.collectionName).get(id)
+            models.push(model)
+            notFoundIds.push(id) unless model
+          if notFoundIds.length
+            Brainstem.Utils.throwError("Unable to find #{field} with ids #{notFoundIds.join(", ")} in our cached #{details.collectionName} collection.  We know about #{base.data.storage(details.collectionName).pluck("id").join(", ")}")
+        if options.order
+          comparator = base.data.getCollectionDetails(details.collectionName).klass.getComparatorWithIdFailover(options.order)
+          collectionOptions = { comparator: comparator }
+        else
+          collectionOptions = {}
+        base.data.createNewCollection(details.collectionName, models, collectionOptions)
+    else
+      super(field)
+
+  className: =>
+    @paramRoot
+
+  defaultJSONBlacklist: ->
+    ['id', 'created_at', 'updated_at']
+
+  createJSONBlacklist: ->
+    []
+
+  updateJSONBlacklist: ->
+    []
+
+  toServerJSON: (method, options) =>
+    json = @toJSON(options)
+    blacklist = @defaultJSONBlacklist()
+
+    switch method
+      when "create"
+        blacklist = blacklist.concat @createJSONBlacklist()
+      when "update"
+        blacklist = blacklist.concat @updateJSONBlacklist()
+
+    for blacklistKey in blacklist
+      delete json[blacklistKey]
+
+    json
+
+_.extend(Brainstem.Model.prototype, Brainstem.LoadingMixin);

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

@@ -0,0 +1,76 @@
+Backbone.sync = (method, model, options) ->
+  methodMap =
+    create: 'POST'
+    update: 'PUT'
+    patch:  'PATCH'
+    delete: 'DELETE'
+    read:   'GET'
+
+  type = methodMap[method];
+
+  # Default options, unless specified.
+  _.defaults(options || (options = {}), {
+    emulateHTTP: Backbone.emulateHTTP,
+    emulateJSON: Backbone.emulateJSON
+  })
+
+  # Default JSON-request options.
+  params = { type: type, dataType: 'json' }
+
+  # Ensure that we have a URL.
+  if (!options.url)
+    params.url = _.result(model, 'url') || urlError()
+
+  # Ensure that we have the appropriate request data.
+  if !options.data? && model && (method == 'create' || method == 'update' || method == 'patch')
+    params.contentType = 'application/json'
+    data = options.attrs || {}
+
+    if model.toServerJSON?
+      json = model.toServerJSON(method, options)
+    else
+      json = model.toJSON(options)
+
+    if model.paramRoot
+      data[model.paramRoot] = json
+    else
+      data = json
+
+    data.include = Brainstem.Utils.extractArray("include", options).join(";")
+    data.filters = Brainstem.Utils.extractArray("filters", options).join(",")
+    params.data = JSON.stringify(data)
+
+  # For older servers, emulate JSON by encoding the request into an HTML-form.
+  if options.emulateJSON
+    params.contentType = 'application/x-www-form-urlencoded'
+    params.data = if params.data then {model: params.data} else {}
+
+  # For older servers, emulate HTTP by mimicking the HTTP method with `_method`
+  # And an `X-HTTP-Method-Override` header.
+  if options.emulateHTTP && (type == 'PUT' || type == 'DELETE' || type == 'PATCH')
+    params.type = 'POST'
+    if options.emulateJSON
+      params.data._method = type
+    beforeSend = options.beforeSend
+    options.beforeSend = (xhr) ->
+      xhr.setRequestHeader 'X-HTTP-Method-Override', type
+      if beforeSend
+        beforeSend.apply this, arguments
+
+  # Don't process data on a non-GET request.
+  if params.type != 'GET' && !options.emulateJSON
+    params.processData = false
+
+  # If we're sending a `PATCH` request, and we're in an old Internet Explorer
+  # that still has ActiveX enabled by default, override jQuery to use that
+  # for XHR instead. Remove this line when jQuery supports `PATCH` on IE8.
+  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)
+
+  # Make the request, allowing the user to override any Ajax options.
+  xhr = options.xhr = Backbone.ajax(_.extend(params, options))
+  model.trigger 'request', model, xhr, options
+  xhr

data/vendor/assets/javascripts/brainstem/index.js

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

data/vendor/assets/javascripts/brainstem/iso8601.js

@@ -0,0 +1,41 @@
+/**
+ * Date.parse with progressive enhancement for ISO 8601 <https://github.com/csnover/js-iso8601>
+ * © 2011 Colin Snover <http://zetafleet.com>
+ * Released under MIT license.
+ */
+(function (Date, undefined) {
+    var origParse = Date.parse, numericKeys = [ 1, 4, 5, 6, 7, 10, 11 ];
+    Date.parse = function (date) {
+        var timestamp, struct, minutesOffset = 0;
+
+        // ES5 §15.9.4.2 states that the string should attempt to be parsed as a Date Time String Format string
+        // before falling back to any implementation-specific date parsing, so that’s what we do, even if native
+        // implementations could be faster
+        //              1 YYYY                2 MM       3 DD           4 HH    5 mm       6 ss        7 msec        8 Z 9 ±    10 tzHH    11 tzmm
+        if ((struct = /^(\d{4}|[+\-]\d{6})(?:-(\d{2})(?:-(\d{2}))?)?(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{3}))?)?(?:(Z)|([+\-])(\d{2})(?::(\d{2}))?)?)?$/.exec(date))) {
+            // avoid NaN timestamps caused by “undefined” values being passed to Date.UTC
+            for (var i = 0, k; (k = numericKeys[i]); ++i) {
+                struct[k] = +struct[k] || 0;
+            }
+
+            // allow undefined days and months
+            struct[2] = (+struct[2] || 1) - 1;
+            struct[3] = +struct[3] || 1;
+
+            if (struct[8] !== 'Z' && struct[9] !== undefined) {
+                minutesOffset = struct[10] * 60 + struct[11];
+
+                if (struct[9] === '+') {
+                    minutesOffset = 0 - minutesOffset;
+                }
+            }
+
+            timestamp = Date.UTC(struct[1], struct[2], struct[3], struct[4], struct[5] + minutesOffset, struct[6], struct[7]);
+        }
+        else {
+            timestamp = origParse ? origParse(date) : NaN;
+        }
+
+        return timestamp;
+    };
+}(Date));

data/vendor/assets/javascripts/brainstem/loading-mixin.coffee

@@ -0,0 +1,13 @@
+window.Brainstem ?= {}
+
+Brainstem.LoadingMixin =
+  setLoaded: (state, options) ->
+    options = { trigger: true } unless options? && options.trigger? && !options.trigger
+    @loaded = state
+    @trigger 'loaded', @ if state && options.trigger
+
+  whenLoaded: (func) ->
+    if @loaded
+      func()
+    else
+      @bind "loaded", => func()

data/vendor/assets/javascripts/brainstem/storage-manager.coffee

@@ -0,0 +1,275 @@
+window.Brainstem ?= {}
+
+# Todo: Record access timestamps on all Brainstem.Models by overloading #get and #set.  Keep a sorted list (Heap?) of model references.
+#    clean up the oldest ones if memory is low
+#    allow passing a recency parameter to the StorageManager
+
+# The StorageManager class is used to manage a set of Brainstem.Collections.  It is responsible for loading data and
+# maintaining caches.
+class window.Brainstem.StorageManager
+  constructor: (options = {}) ->
+    @collections = {}
+    @setErrorInterceptor(options.errorInterceptor)
+
+  # Add a collection to the StorageManager.  All collections that will be loaded or used in associations must be added.
+  #    manager.addCollection "time_entries", App.Collections.TimeEntries
+  addCollection: (name, collectionClass) ->
+    @collections[name] =
+      klass: collectionClass
+      modelKlass: collectionClass.prototype.model
+      storage: new collectionClass()
+      cache: {}
+
+  # Access the cache for a particular collection.
+  #    manager.storage("time_entries").get(12).get("title")
+  storage: (name) =>
+    @getCollectionDetails(name).storage
+
+  dataUsage: =>
+    sum = 0
+    for dataType in @collectionNames()
+      sum += @storage(dataType).length
+    sum
+
+  reset: =>
+    for name, attributes of @collections
+      attributes.storage.reset []
+      attributes.cache = {}
+
+  # Access details of a collection.  An error will be thrown if the collection cannot be found.
+  getCollectionDetails: (name) =>
+    @collections[name] || @collectionError(name)
+
+  collectionNames: =>
+    _.keys(@collections)
+
+  collectionExists: (name) =>
+    !!@collections[name]
+
+  setErrorInterceptor: (interceptor) =>
+    @errorInterceptor = interceptor || (handler, modelOrCollection, options, jqXHR, requestParams) -> handler?(modelOrCollection, jqXHR)
+
+  # Request a model to be loaded, optionally ensuring that associations be included as well.  A collection is returned immediately and is reset
+  # when the load, and any dependent loads, are complete.
+  #     model = manager.loadModel "time_entry"
+  #     model = manager.loadModel "time_entry", fields: ["title", "notes"]
+  #     model = manager.loadModel "time_entry", include: ["project", "task"]
+  loadModel: (name, id, options) =>
+    options = _.clone(options || {})
+    oldSuccess = options.success
+    collectionName = name.pluralize()
+    model = new (@getCollectionDetails(collectionName).modelKlass)()
+    @loadCollection collectionName, _.extend options,
+      only: id
+      success: (collection) ->
+        model.setLoaded true, trigger: false
+        model.set collection.get(id).attributes
+        model.setLoaded true
+        oldSuccess(model) if oldSuccess
+    model
+
+  # Request a set of data to be loaded, optionally ensuring that associations be included as well.  A collection is returned immediately and is reset
+  # when the load, and any dependent loads, are complete.
+  #     collection = manager.loadCollection "time_entries"
+  #     collection = manager.loadCollection "time_entries", only: [2, 6]
+  #     collection = manager.loadCollection "time_entries", fields: ["title", "notes"]
+  #     collection = manager.loadCollection "time_entries", include: ["project", "task"]
+  #     collection = manager.loadCollection "time_entries", include: ["project:title,description", "task:due_date"]
+  #     collection = manager.loadCollection "tasks",      include: ["assets", { "assignees": "account" }, { "sub_tasks": ["assignees", "assets"] }]
+  #     collection = manager.loadCollection "time_entries", filters: ["project_id:6", "editable:true"], order: "updated_at:desc", page: 1, perPage: 20
+  loadCollection: (name, options) =>
+    options = $.extend({}, options, name: name)
+    @_checkPageSettings options
+    include = @_wrapObjects(Brainstem.Utils.extractArray "include", options)
+    if options.search
+      options.cache = false
+
+    collection = options.collection || @createNewCollection name, []
+    collection.setLoaded false
+    collection.reset([], silent: false) if options.reset
+    collection.lastFetchOptions = _.pick($.extend(true, {}, options), 'name', 'filters', 'include', 'page', 'perPage', 'order', 'search')
+
+    if @expectations?
+      @handleExpectations name, collection, options
+    else
+      @_loadCollectionWithFirstLayer($.extend({}, options, include: include, success: ((firstLayerCollection) =>
+        expectedAdditionalLoads = @_countRequiredServerRequests(include) - 1
+        if expectedAdditionalLoads > 0
+          timesCalled = 0
+          @_handleNextLayer firstLayerCollection, include, =>
+            timesCalled += 1
+            if timesCalled == expectedAdditionalLoads
+              @_success(options, collection, firstLayerCollection)
+        else
+          @_success(options, collection, firstLayerCollection)
+      )))
+
+    collection
+
+  _handleNextLayer: (collection, include, callback) =>
+    # Collection is a fully populated collection of tasks whose first layer of associations are loaded.
+    # include is a hierarchical list of associations on those tasks:
+    #   [{ 'time_entries': ['project': [], 'task': [{ 'assignees': []}]] }, { 'project': [] }]
+
+    _(include).each (hash) => # { 'time_entries': ['project': [], 'task': [{ 'assignees': []}]] }
+      association = _.keys(hash)[0] # time_entries
+      nextLevelInclude = hash[association] # ['project': [], 'task': [{ 'assignees': []}]]
+      if nextLevelInclude.length
+        association_ids = _(collection.models).chain().
+        map((m) -> if (a = m.get(association)) instanceof Backbone.Collection then a.models else a).
+        flatten().uniq().compact().pluck("id").sort().value()
+        newCollectionName = collection.model.associationDetails(association).collectionName
+        @_loadCollectionWithFirstLayer name: newCollectionName, only: association_ids, include: nextLevelInclude, success: (loadedAssociationCollection) =>
+          @_handleNextLayer(loadedAssociationCollection, nextLevelInclude, callback)
+          callback()
+
+  _loadCollectionWithFirstLayer: (options) =>
+    options = $.extend({}, options)
+    name = options.name
+    only = if options.only then _.map((Brainstem.Utils.extractArray "only", options), (id) -> String(id)) else null
+    search = options.search
+    include = _(options.include).map((i) -> _.keys(i)[0]) # pull off the top layer of includes
+    filters = options.filters || {}
+    order = options.order || "updated_at:desc"
+    cacheKey = "#{order}|#{_.chain(filters).pairs().map(([k, v]) -> "#{k}:#{v}" ).value().join(",")}|#{options.page}|#{options.perPage}"
+
+    cachedCollection = @storage name
+    collection = @createNewCollection name, []
+
+    unless options.cache == false
+      if only?
+        alreadyLoadedIds = _.select only, (id) => cachedCollection.get(id)?.associationsAreLoaded(include)
+        if alreadyLoadedIds.length == only.length
+          # We've already seen every id that is being asked for and have all the associated data.
+          @_success options, collection, _.map only, (id) => cachedCollection.get(id)
+          return collection
+      else
+        # Check if we have, at some point, requested enough records with this this order and filter(s).
+        if @getCollectionDetails(name).cache[cacheKey]
+          subset = _(@getCollectionDetails(name).cache[cacheKey]).map (result) -> base.data.storage(result.key).get(result.id)
+          if (_.all(subset, (model) => model.associationsAreLoaded(include)))
+            @_success options, collection, subset
+            return collection
+
+    # If we haven't returned yet, we need to go to the server to load some missing data.
+    syncOptions =
+      data: {}
+      parse: true
+      error: options.error
+      success: (resp, status, xhr) =>
+        # The server response should look something like this:
+        #  {
+        #    count: 200,
+        #    results: [{ key: "tasks", id: 10 }, { key: "tasks", id: 11 }],
+        #    time_entries: [{ id: 2, title: "te1", project_id: 6, task_id: [10, 11] }]
+        #    projects: [{id: 6, title: "some project", time_entry_ids: [2] }]
+        #    tasks: [{id: 10, title: "some task" }, {id: 11, title: "some other task" }]
+        #  }
+        # Loop over all returned data types and update our local storage to represent any new data.
+
+        results = resp['results']
+        keys = _.reject(_.keys(resp), (key) -> key == 'count' || key == 'results')
+        unless _.isEmpty(results)
+          keys.splice(keys.indexOf(name), 1) if keys.indexOf(name) != -1
+          keys.push(name)
+
+        for underscoredModelName in keys
+          @storage(underscoredModelName).update _(resp[underscoredModelName]).values()
+
+        unless options.cache == false || only?
+          @getCollectionDetails(name).cache[cacheKey] = results
+
+        if only?
+          @_success options, collection, _.map(only, (id) -> cachedCollection.get(id))
+        else
+          @_success options, collection, _(results).map (result) -> base.data.storage(result.key).get(result.id)
+
+
+    syncOptions.data.include = include.join(",") if include.length
+    syncOptions.data.only = _.difference(only, alreadyLoadedIds).join(",") if only?
+    syncOptions.data.order = options.order if options.order?
+    _.extend(syncOptions.data, _(filters).omit('include', 'only', 'order', 'per_page', 'page', 'search')) if _(filters).keys().length
+    syncOptions.data.per_page = options.perPage unless only?
+    syncOptions.data.page = options.page unless only?
+    syncOptions.data.search = search if search
+
+    Backbone.sync.call collection, 'read', collection, syncOptions
+
+    collection
+
+  _success: (options, collection, data) =>
+    if data
+      data = data.models if data.models?
+      collection.setLoaded true, trigger: false
+      if collection.length
+        collection.add data
+      else
+        collection.reset data
+    collection.setLoaded true
+    options.success(collection) if options.success?
+
+  _checkPageSettings: (options) =>
+    options.perPage = options.perPage || 20
+    options.perPage = 1 if options.perPage < 1
+    options.page = options.page || 1
+    options.page = 1 if options.page < 1
+
+  collectionError: (name) =>
+    Brainstem.Utils.throwError("Unknown collection #{name} in StorageManager.  Known collections: #{_(@collections).keys().join(", ")}")
+
+  createNewCollection: (collectionName, models = [], options = {}) =>
+    loaded = options.loaded
+    delete options.loaded
+    collection = new (@getCollectionDetails(collectionName).klass)(models, options)
+    collection.setLoaded(true, trigger: false) if loaded
+    collection
+
+  createNewModel: (modelName, options) =>
+    new (@getCollectionDetails(modelName.pluralize()).modelKlass)(options || {})
+
+  _wrapObjects: (array) =>
+    output = []
+    _(array).each (elem) =>
+      if elem.constructor == Object
+        for key, value of elem
+          o = {}
+          o[key] = @_wrapObjects(if value instanceof Array then value else [value])
+          output.push o
+      else
+        o = {}
+        o[elem] = []
+        output.push o
+    output
+
+  _countRequiredServerRequests: (array, wrapped = false) =>
+    if array?.length
+      array = @_wrapObjects(array) unless wrapped
+      sum = 1
+      _(array).each (elem) =>
+        sum += @_countRequiredServerRequests(_(elem).values()[0], true)
+      sum
+    else
+      0
+
+  # Expectations and stubbing
+
+  stub: (collectionName, options) =>
+    if @expectations?
+      expectation = new Brainstem.Expectation(collectionName, options, @)
+      @expectations.push expectation
+      expectation
+    else
+      throw "You must call #enableExpectations on your instance of Brainstem.StorageManager before you can set expectations."
+
+  stubImmediate: (collectionName, options) =>
+    @stub collectionName, $.extend({}, options, immediate: true)
+
+  enableExpectations: =>
+    @expectations = []
+
+  handleExpectations: (name, collection, options) =>
+    for expectation in @expectations
+      if expectation.optionsMatch(name, options)
+        expectation.recordRequest(collection, options)
+        return
+    throw "No expectation matched #{name} with #{JSON.stringify options}"

data/vendor/assets/javascripts/brainstem/utils.coffee

@@ -0,0 +1,35 @@
+window.Brainstem ?= {}
+
+class window.Brainstem.Utils
+  @warn: (args...) ->
+    console?.log "Error:", args...
+
+  @throwError: (message) =>
+    throw new Error("#{Backbone.history.getFragment()}: #{message}")
+
+  @matches: (obj1, obj2) =>
+    if @empty(obj1) && @empty(obj2)
+      true
+    else if obj1 instanceof Array && obj2 instanceof Array
+      obj1.length == obj2.length && _.every obj1, (value, index) => @matches(value, obj2[index])
+    else if obj1 instanceof Object && obj2 instanceof Object
+      obj1Keys = _(obj1).keys()
+      obj2Keys = _(obj2).keys()
+      obj1Keys.length == obj2Keys.length && _.every obj1Keys, (key) => @matches(obj1[key], obj2[key])
+    else
+      String(obj1) == String(obj2)
+
+  @empty: (thing) =>
+    if thing == null || thing == undefined || thing == ""
+      true
+    if thing instanceof Array
+      thing.length == 0 || thing.length == 1 && @empty(thing[0])
+    else if thing instanceof Object
+      _.keys(thing).length == 0
+    else
+      false
+
+  @extractArray: (option, options) =>
+    result = options[option]
+    result = [result] unless result instanceof Array
+    _.compact(result)