backbone.brace.js

Backbone Brace - 2012/10/29
Copyright 2012 Atlassian Software Systems Pty Ltd
Licensed under the Apache License, Version 2.0

node / browser imports, copied from here

Helper functions

Given an array, this function will return an object where each property name is an element of the original array. The value of each property will be null. Given anything else, this function will return the object untouched.

Return a value of the specified type, generated from the value parameter. If type conversion is necessary, this function will generate a new object using new type(value)

value Any value. null and undefined values will be untouched.

type When given:

• a falsy value: this function will do no type conversion.
• a string: this function will throw if typeof value !== type, and return value otherwise.
• an Array: this function will be recursively called for each element in value using type's first element as the type. E.g., ensureType([ Number ], [ 1 ]) will recursively call ensureType(Number, 1) It will return a new array consisting of the result of each recursive call.
• a Backbone.Collection constructor: this function may be recursively called for each element in value using type.model as the type. E.g., ensureType({ model : Number, __proto__ : Backbone.Collection.prototype }, [ 1 ]) will recursively call ensureType(Number, 1) It will return a Backbone.Collection via new type({array of recursive results})
• a function: This will check value instanceof type, and if false, will return new type(value) Otherwise it will return value directly

Returns true if obj is extend()'ed from Backbone.Collection (or from another collection)

obj distantly extends Backbone.Collection (most likely case)

obj directly extends Backbone.Collection (e.g., Brace.Collection) !(fn.prototype instanceof fn), so the above check doesn't catch this case.

obj is Backbone.Collection

array-like is currently defined by "has a length property, and is not a string or function or Backbone.Collection." Backbone.Collections are excluded because you can't do collection[0] to access models.

With namedAttributes, we want to allow both the mixin, and the extender to define types. We want to take the stricter of the two types where possible. Where the types conflict, throw an error.

One type assumes another when the conditions for meeting its type-check are a super set of the assumed type's conditions. E.g., [ 'string' ] assumes Array because you can't have an array of strings without an array.

if it's a string, only the previous strict equality check would have sufficed.

Brace.Mixins

Mixin utilities

Creates a camelCased method name

Applies a mixin to the given constructor's prototype.

initialize is not mixed in - we compose the mixin's initialize with the existing initialize method (if it exists).

validate is not mixed in - we compose the mixin's validate with the existing validate method (if it exists).

defaults are not mixed in - we compose the mixin's defaults with existing defaults if they exist

namedAttributes are added to the mixin, and we mixin in getters and setters for each attribute.

namedEvents are added to the mixin, and we mix in on and trigger methods for each event.

events must be an array

Name collisions with other mixins or or the object we're mixing into result in violent and forceful disapproval.

Brace.AttributesMixinCreator

Creates a mixin of getter and setter methods for each item in the given attribute list. A getter and setter for id is always generated.

TODO: has, escape, unset

Brace.EventsMixinCreator

Creates a mixin of on and trigger methods for each item in the given list of events.

TODO: off

Generates an extend method that overrides Backbone's default extend. The new extend calls Backbone's extend, then:

• Adds all mixins specified in the mixins array
• Adds a Brace.EventsMixinCreator to mix in on and trigger methods for events specified in the namedEvents array
• Adds a Brace.AttributesMixinCreator to mix in get and set methods for attributes specified in the attributes array

Remove mixins - we don't want to see them on the created prototype. Note that we do want to see namedAttributes and namedEvents for debugging

Overrides Backbone's get and set methods to validate that the attribute being get / set is a namedAttribute.

TODO: has, escape, unset

Applies extensions to the given constructor function. Sets extend to a method generated by generateMixinExtend

Applies extensions to the given constructor function. Sets extend to a method generated by generateMixinExtend

Extend base Backbone classes