revelry_data 0.0.7

data/app/assets/javascripts/revelry_data/store.es6

@@ -0,0 +1,638 @@
+Rev.Store = class Store {
+  /*
+   * # Constructor
+   */
+
+  /**
+   * Create a base data store and associate it with a component.
+   *
+   * Example:
+   *
+   * ```
+   * constructor(props) {
+   *   super(props)
+   *   this.store = new Store(this)
+   * }
+   * ```
+   *
+   * @constructor
+   * @param {React.Component} component - The component to associate this store
+   *   with. It will be re-rendered as data is updated.
+   */
+  constructor(component) {
+    this.attach(component)
+    _.extend(this, Backbone.Events)
+    this.errors = {}
+    this.loadPrimary(component.props)
+  }
+
+  /**
+   * Load `data` from the JSON API response as the 'primary resource' on this
+   * store. Account for both arrays and single resources. Do nothing if there
+   * is no `data` on the resp
+   * @param {Object} resp - the JSON API style response object
+   */
+  loadPrimary(resp) {
+    if(!resp.data) {
+      return
+    }
+    // Load `data` from the props by default. Assign it to `this.primary`
+    if(_.isArray(resp.data)) {
+      this.loadPrimaryCollection(resp)
+    } else {
+      this.loadPrimaryModel(resp)
+    }
+  }
+
+  /**
+   * Load `data` into a model for the singular resource case
+   * @param {Object} props - the JSON API style response object
+   */
+  loadPrimaryModel(props) {
+    let resourceName = _.singularize(props.data.type)
+    // If our type is 'foos', make this.foo with App.Models.Foo and load
+    // `props.data` into it
+    this.primary = this.new(
+      resourceName,
+      App.Models[_.str.classify(resourceName)],
+      props.data
+    )
+    this.handleTopLevelLinks(props.links)
+    return this.primary
+  }
+
+  /**
+   * Load `data` into a collection for the multiple resource case
+   * @param {Object} props - the JSON API style response object
+   */
+  loadPrimaryCollection(props) {
+    // TODO: How do we handle polymorphic collections as primary?
+    if(props.data.length > 0) {
+      let resourceName = props.data[0].type
+      this.loadCollectionsFrom(props.data)
+      this.primary = this[resourceName]
+      this.handleTopLevelLinks(props.links)
+      return this.primary
+    }
+    return null
+  }
+
+  handleTopLevelLinks(links) {
+    if(this.primary && this.primary.handleLinks) {
+      this.primary.handleLinks(links)
+    }
+  }
+
+  // TODO: Split each of these sections out as a module once we have the time
+
+  /*
+   * # Interacting with the attached component
+   */
+
+  /**
+   * Attach to a component so we force a render when the store is updated
+   * @private
+   * @param {React.Component} component - The component to which to attach.
+   */
+  attach(component) {
+    if(component && component.forceUpdate) {
+      this.__changeCallback = component.forceUpdate.bind(component)
+    } else if(Rev.env == 'development') {
+      console.warn('You initialized a store without an attached component')
+    }
+  }
+
+  /**
+   * Detach the attached component so it will not receive any more updates and so
+   * we don't have a dangling reference
+   * @private
+   */
+  detach() {
+    this.__changeCallback = null
+    this.stopListening()
+  }
+
+  /**
+   * Called when we have changed the data in the store to tell the attached
+   * component that it is time to re-render
+   * @protected
+   */
+  triggerChange() {
+    if(this.__changeCallback) {
+      this.__changeCallback()
+    } else {
+      if(Rev.env == 'development') {
+        console.warn('Change triggered on detached store.')
+      }
+    }
+  }
+
+  /*
+   * # Working with models
+   */
+
+  /**
+   * Get or create a collection for a given resource type
+   * For example `getCollectionForResourceName('beers')` would either
+   * find `store.beers` or create a new `Beer.Collection` at `store.beers`.
+   * @protected
+   * @param {String} resourceName - The name of the resource class (API object).
+   */
+  getCollectionForResourceName(resourceName) {
+    if(Rev.env == 'development' && !resourceName) {
+      throw 'resourceName arg was not given to getCollectionForResourceName'
+    }
+
+    if(this[resourceName]) {
+      return this[resourceName]
+    } else {
+      let modelClass = _.str.classify(_.singularize(resourceName))
+      let collectionClass = App.Models[modelClass].Collection
+      return this.new(resourceName, collectionClass)
+    }
+  }
+
+  /**
+   * Loop through an array of objects, and put into collections based on their
+   * type. For example, if the list was:
+   *
+   * Example:
+   * ```
+   *  [
+   *    {type: 'users', id: '1'},
+   *    {type: 'messages', id: '1'},
+   *    {type: 'users', id: '2'}
+   *  ]
+   * ```
+   * We'd end up with a collections this.users with two entries, and
+   * this.messages with one entry.
+   * @protected
+   * @param {Array} list - The list of data objects to consume and place in
+   *   collections. Each should contain a 'type' property.
+   */
+  loadCollectionsFrom(list) {
+    return (list || []).map(this.loadIntoCollection.bind(this))
+  }
+
+  /**
+   * Load one item into the collection which corresponds to its resource type.
+   * @protected
+   * @param {Object} item - The item to load into the collection. It must have
+   *   a 'type' property which corresponds to its resource type.
+   */
+  loadIntoCollection(item) {
+    let collection = this.getCollectionForResourceName(item.type)
+    return collection.add(item, {silent: true})
+  }
+
+  /**
+   * Look through the list, find the first item with the given JSON API type
+   *
+   */
+  findByType(list, type) {
+    if(!type) {
+      throw 'Type not given in call to findByType'
+    }
+
+    return _(list).find((item) => {
+      return item.type == type
+    })
+  }
+
+  filterByType(list, type) {
+    if(!type) {
+      throw 'Type not given in call to filterByType'
+    }
+
+    return _(list).filter((item) => {
+      return item.type == type
+    })
+  }
+
+  // Create a new instance of klass, with the attributes 'defaults' and store
+  // it in this[handle]. Bind events for our event handling
+  // NOTE: I think I'll change this API before we go public. Not sure about
+  //   the automatic binding anymore.
+  new(handle, klass, defaults) {
+    if(this[handle]) {
+      // So we don't leak event handlers if this is a re-assignment
+      this.stopListening(this[handle])
+    }
+
+    this[handle] = new klass(defaults)
+    this.listenTo(this[handle], 'change', this.triggerChange)
+    this.listenTo(this[handle], 'error', this.errorHandler(handle))
+    this.bindEvents(handle)
+    return this[handle]
+  }
+
+  // Call .save() on the model at this[handle].
+  // NOTE: We may move away from backbone, so this may eventually handle AJAX
+  //   directly.
+  save(handle, attributes, options) {
+    // First save the related items, then save the model to which handle points
+    // Note that if relationships is not set or empty, this will immediately
+    // call the inner function (and save)
+    this.saveRelations(handle, (options || {}).relationships, () => {
+      this.lookupHandle(handle).save(attributes, options)
+    })
+  }
+
+  // Look through the associations of handle which are named in 'relationships'
+  // and save any unsaved related items (in parallel), then call a callback when
+  // all the saves have been completed (either success or failure)
+  saveRelations(handle, relationships, callback) {
+    let unsaveds = this.unsavedRelatedModels(handle, relationships)
+    if(_.isEmpty(relationships) || _.isEmpty(unsaveds)) {
+      return callback()
+    }
+
+    let groupCallback = _.after(unsaveds.length, callback)
+    unsaveds.map((mdl) => {
+      mdl.save(null, {complete: groupCallback})
+    })
+  }
+
+  // Look through the associations of handle which are named in 'relationships'
+  // and return all the unsaved (new or changed) objects
+  unsavedRelatedModels(handle, relationships) {
+    // Return early if relationships is unset or empty
+    if(_.isEmpty(relationships)) {
+      return []
+    }
+
+    let unsaveds = []
+    relationships.forEach((relationName) => {
+      _.mapIfArray(this.getLink(handle, relationName), (model) => {
+        if(model.hasChanged() || model.isNew()) {
+          unsaveds.push(model)
+        }
+      })
+    })
+    return unsaveds
+  }
+
+  /*
+   * SECTION: JSON path utilties
+   */
+
+  // Return the object at JSON path 'handle'
+  lookupHandle(handle) {
+    return JSONPath({ json: this, path: handle })[0]
+  }
+
+  // Split the path, and return the path of the object which contains the object
+  // at `path`.
+  // 'contact.links.user' -> 'contact.links'
+  parentPath(path) {
+    var parts = path.split('.')
+    parts.pop()
+    return parts.join('.')
+  }
+
+  // Split the path and return just the last part, the final attribute name
+  // 'contact.name.' -> 'name'
+  childPath(path) {
+    var parts = path.split('.')
+    return parts[parts.length - 1]
+  }
+
+  // Return the object which contains the object at the given path.
+  // E.g. if your store is like this:
+  // {
+  //   "contact": {
+  //     "name": "foo"
+  //   }
+  // }
+  // parentPath('contact.name') -> {"name": "foo"}
+  // We primarily use this in setters, so that we can update the parent object
+  // with the new value of a child.
+  parent(path) {
+    if(this.parentPath(path) == '') {
+      return this;
+    }
+    return JSONPath({ json: this, path: this.parentPath(path) })[0]
+  }
+
+  /*
+   * SECTION: Setters and getters
+   */
+
+  // Get the value of the model attribute at path
+  // Assumes that the parent of the attribute is a backbone model/collection or
+  // at the least, responds to `get`
+  // E.g. if my store is
+  // {
+  //   "contact": { // A backbone model
+  //     ...,
+  //      attributes: {
+  //        name: 'Mr. Foo Bar'
+  //      }
+  //   }
+  // }
+  // then store.get('contact.name') -> 'Mr. Foo Bar'
+  get(path) {
+    let parent = this.parent(path)
+    if(parent.get && parent != this) {
+      return parent.get(this.childPath(path))
+    } else {
+      return parent[this.childPath(path)]
+    }
+  }
+
+  // Set the value of the model attribute at path
+  // Similar to get in operation, but sets the value instead of simply
+  // returning it.
+  // TODO: Figure out our action-lifecycle and update batching strategy
+  set(path, value) {
+    let parent = this.parent(path)
+    if(parent.set && parent != this) {
+      parent.set(this.childPath(path), value)
+    } else {
+      parent[this.childPath(path)] = value
+      this.triggerChange()
+    }
+  }
+
+  // Traverse a included related resources, following a JSON API
+  // linkage-included structure: http://jsonapi.org/format/#fetching-includes
+  // It assumes you have already loaded the objects into collections named
+  // after their types (e.g. with loadCollectionFrom)
+  // - Takes variable arguments. The first is the path of the base resource,
+  //   and each additional argument is a related item named link which should be
+  // followed.
+  getLink(target, ...relatedItemNames) {
+    var target = this.lookupHandle(arguments[0])
+
+    let relationsLen = relatedItemNames.length
+    for(let i = 0; i < relationsLen; i++) {
+      let linkName = relatedItemNames[i]
+
+      target = _.flatMapIfArray(target, (target2) => {
+        return this.followLinkFromTarget(target2, linkName)
+      })
+      if(!target) {
+        return
+      }
+    }
+    return target
+  }
+
+  linkExists(target, linkName) {
+    if(target) {
+      var linkRecords = this.linksAndRelationships(target)
+      return target &&
+             linkRecords &&
+             linkRecords[linkName] &&
+             this.linkageForName(linkRecords, linkName)
+    } else {
+      return false
+    }
+  }
+
+  // Get target's linkName link and then look up and return the associated
+  // object
+  followLinkFromTarget(target, linkName) {
+    let linkage
+    if(this.linkExists(target, linkName)) {
+      return this.lookupLinkage(
+        this.linkageForName(this.linksAndRelationships(target), linkName)
+      )
+    }
+  }
+
+  // Take a linkage object that looks like {"id": "1", "type": "persons"}
+  // or an array of linkage objects, and look up the corresponding objects
+  lookupLinkage(linkage) {
+    return _.mapIfArray(linkage, (linkageItem) => {
+      if(linkageItem.id) {
+        // Saved linkage item (has id)
+        return this[linkageItem.type].get(linkageItem.id)
+      } else {
+        // Unsaved linkage item (compare on cid instead)
+        return this[linkageItem.type].find((candidateRelated) => {
+          return candidateRelated.cid == linkageItem.cid
+        })
+      }
+    })
+  }
+
+  // help deal with key name differences between JSON API < 1 and JSON API >= 1
+  // by supporting both 'links' and 'relationships'
+  // Can handle single targets, or an array of targets (via mapIfArray)
+  // If target is array-like, then we return an array of linkage/relationship
+  // objects
+  linksAndRelationships(target) {
+    return _.mapIfArray(target, (targetItem) => {
+      return _.extend({}, targetItem.get('links'), targetItem.get('relationships'))
+    })
+  }
+
+  // help deal with key name differences between JSON API < 1 and JSON API >= 1
+  // by supporting both 'data' and 'linkage'
+  linkageForName(links, linkName) {
+    return (links[linkName].data || links[linkName].linkage)
+  }
+
+
+  // Follow a set of links from a base handle and then set the value of the last
+  // link to a new value (which is a linkage object as defined by JSON API)
+  setLink(/* handle, links..., newValue */) {
+    // parsing out the variable args
+    let argCount = arguments.length
+    let newValue = _(arguments).last()
+    let childLinkName = arguments[argCount - 2]
+    let parentArgs = Array.prototype.slice.call(arguments, 0, argCount - 2)
+
+    // lookup the object which contains the terminal link we want to set
+    let parent = this.getLink.apply(this, parentArgs)
+
+    // Actually set the linkage to the new linkage object and make sure to
+    // trigger a re-render
+    this.linksAndRelationships(parent)[childLinkName].data = newValue
+    this.triggerChange()
+  }
+
+  // Friendly method for setting a relation. This handles both sides of the
+  // operation: 1. Updating the collection of objects of the type, so that the
+  // new value is present in the collection (and can be linked to) and 2.
+  // actually updating the link in the parent resource, associated the parent
+  // and related objects
+  setRelation() {
+    // Build a linkage (or array of linkages) for the new value of the relation
+    let newValue = _(arguments).last()
+    let newValueLink = this.linkageForObject(newValue)
+
+    let setLinkArgs = Array.prototype.slice.call(arguments)
+    setLinkArgs[setLinkArgs.length - 1] = newValueLink
+
+    this.setLink.apply(this, setLinkArgs)
+  }
+
+  // Take an object, make sure it is stored in its type collection, and then
+  // provide the linkage object needed to associate it with other items
+  linkageForObject(valueObject) {
+    if(_.isArray(valueObject)) {
+       return this.linkageAttributes(this.loadCollectionsFrom(valueObject))
+    } else {
+      return this.linkageAttributes(this.loadIntoCollection(valueObject))
+    }
+  }
+
+  // Take a full object and convert it to the corresponding linkage as defined
+  // for JSON API
+  linkageAttributes(relatedObject) {
+    return _.mapIfArray(relatedObject, (item) => {
+      return {
+        id: item.id,
+        type: item.type || item.get('type'),
+        cid: item.cid,
+      }
+    })
+  }
+
+  pathForModel(model) {
+    let type = model.get('type')
+    let index = this[type].indexOf(model)
+    return `${type}.models[${index}]`
+  }
+
+  /*
+   * SECTION: Model event handling
+   */
+
+  // Read the declarative event map and bind the appropriate event handlers
+  bindEvents(handle) {
+    var eventDefs = this.handlersForHandle(handle)
+
+    _(eventDefs).each((value, key) => {
+      this.listenTo(this.lookupHandle(handle), key, value.bind(this))
+    })
+  }
+
+  /**
+   * Lookup the event handlers in the declarative map for the object referenced
+   * by the given handle. Also merge in the default handlers
+   * @param {String} handle - the handle of the object to look up the event
+   *   handlers for
+   */
+  handlersForHandle(handle) {
+    let handlers = {}
+    let specs = this.handlerSpecs(handle)
+    let defaults = this.defaultEventHandlers()
+    let defaultHandler, specHandler
+
+    let allKeys = _.union(_.keys(specs), _.keys(defaults))
+
+    _.forEach(allKeys, (key) => {
+      defaultHandler = defaults[key]
+      specHandler = specs[key]
+      handlers[key] = this.makeCompoundHandler(defaultHandler, specHandler)
+    })
+
+    return handlers
+  }
+
+  makeCompoundHandler(firstFn, secondFn) {
+    if(firstFn && secondFn) {
+      return (...eventArgs) => {
+        firstFn.apply(this, eventArgs)
+        secondFn.apply(this, eventArgs)
+      }
+    } else {
+      return firstFn || secondFn
+    }
+  }
+
+  handlerSpecs(handle) {
+    return ((this.events && this.events[handle]) || {})
+  }
+
+  /**
+   * Default event handlers for any newly allocated model or collection on the
+   * store. Currently, this is one generic sync handler that processes related
+   * items into collections and handles new top level links (i.e. pagination)
+   */
+  defaultEventHandlers() {
+    return {
+      sync: this.handleDefaultSync.bind(this)
+    }
+  }
+
+  /**
+   * Default sync handler. Processes included items into collections so we can
+   * look them up via links later. Also handles new pagination info from the
+   * top level links.
+   */
+  handleDefaultSync(modelOrCollection, resp, options) {
+    // If the thing we synced was the main collection, the top level links
+    // object contains our pagination stuff. Make sure that gets set on the
+    // collection
+    if(modelOrCollection == this.primary) {
+      this.handleTopLevelLinks(resp.links)
+    }
+    this.loadCollectionsFrom(resp.included)
+    this.triggerChange()
+  }
+
+  unbindEvents(handle) {
+    this.stopListening(this.lookupHandle(handle))
+  }
+
+  // Return an error handler bound to this, and curry in the handle so it is
+  // available when the handler is called
+  errorHandler(handle) {
+    return this.handleError.bind(this, handle)
+  }
+
+  // Default error behavior-- process the errors in the JSON API format,
+  // and put them in an errors object so we can display them later
+  // http://jsonapi.org/format/#errors
+  handleError(handle, model, resp, options) {
+    var error, path, parent, index
+    // If we don't have JSON API errors, skip the rest of this method.
+    // We'll still get the error in the console for diagnostic purposes.
+    if(!resp || !resp.responseJSON || !resp.responseJSON.errors) {
+      return
+    }
+    var errors = resp.responseJSON.errors
+
+    for(error of errors) {
+      path = handle;
+      parent = this.lookupHandle(handle)
+
+      if(parent.length != null) {
+        index = parent.indexOf(model)
+        /* parent is array or collection */
+        if(parent.models) {
+          path = `${handle}.models[${index}]`
+        } else {
+          path = `${handle}[${index}]`
+        }
+      }
+
+      // TODO: Remove support for error.path once JSON API Resources no longer
+      // sends it.
+      if(error.path){
+        path += _.dasherize(error.path).replace('/', '.')
+      } else if(error.source && error.source.pointer) {
+        let attributeName = _.last(error.source.pointer.split('/'))
+        path += '.' + _.dasherize(attributeName)
+      }
+
+      if(this.errors[path] == null) {
+        this.errors[path] = []
+      }
+      this.errors[path].push(error.detail)
+    }
+    this.triggerChange()
+  }
+
+  resetErrors() {
+    this.errors = {}
+  }
+
+  resetErrorFor(handle) {
+    this.errors[handle] = null
+  }
+}

data/app/assets/javascripts/revelry_data/utils.es6

@@ -0,0 +1,32 @@
+_.mixin({
+  // Strip an object any keys paired with null values
+  compactObject: function(object) {
+    let newObject = _.extend({}, object)
+    _(newObject).each((v, k) => {
+      if(v == null) {
+        delete newObject[k]
+      }
+    })
+    return newObject
+  },
+  // If arrayOrObject is an array, map over it with iteree, otherwise pass
+  // arrayOrObject to iteree once. Useful for removing conditionals from methods
+  // that need to handle individual items and also handle arrays of items by
+  // performing the same operation on each item. This is common when processing
+  // JSON API structures.
+  mapIfArray: function(arrayOrObject, iteree) {
+    if(_.isArray(arrayOrObject)) {
+      return arrayOrObject.map(iteree)
+    } else {
+      return iteree(arrayOrObject)
+    }
+  },
+  // Similar to mapIfArray from above, but it also flattens the resulting array
+  flatMapIfArray: function(arrayOrObject, iteree) {
+    if(_.isArray(arrayOrObject)) {
+      return _.flatten(arrayOrObject.map(iteree))
+    } else {
+      return iteree(arrayOrObject)
+    }
+  },
+})

data/app/assets/javascripts/revelry_data.js

@@ -0,0 +1,10 @@
+//= require revelry_data/utils
+//= require revelry/extensions/mixins
+//= require vendor/underscore.inflections
+//= require vendor/backbone-jsonapi
+//= require vendor/jsonpath
+//= require revelry_data/models/BaseModel
+//= require revelry_data/models/BaseCollection
+//= require revelry_data/store
+//= require_tree ./revelry_data/mixins
+//= require_tree ./revelry_data/components