batman.js

batman.js is a framework for building rich single-page browser applications. It is written in CoffeeScript and its API is developed with CoffeeScript in mind, but of course you can use plain old JavaScript too.

It's got:

• a stateful MVC architecture
• a powerful binding system
• routable controller actions
• pure HTML views
• toolchain support built on node.js and cake

Batman's API is heavily inspired by Rails and designed to make Rails devs feel right at home.

Platforms

Batman runs in node and the browser. Batman supports node v0.4.x and v0.6.x. We're targeting Chrome, Safari 4+, Firefox 3+, and IE 7+ for compatibility. Batman expects ES5 features like Function::bind and Array::map, so we recommend poly-filling these for older browsers with something like es5shim or augmentjs. Batman also expects JSON.parse, which can be implemented in browsers without it using json2.js.

Installation

Batman is available as a standalone download or as an npm package.

Standalone Browser Version

Versions of batman suitable for use in a web application are available at GitHub.

node.js

If you haven't already, you'll need to install node.js. Then:

npm install -g batman

Generate a new batman.js app somewhere, called my_app:

cd ~/code
batman new my_app

Fire it up:

cd my_app
batman server # (or just "batman s")

Now visit http://localhost:1047 and start playing around!

Architecture

Batman prescribes an MVC architecture for client side applications which fits together like this:

• Models have validations, lifecycle events, a built-in identity map, and can be told how to persist themselves. (Batman.LocalStorage, Batman.RestStorage, and Batman.RailsStorage are included).
• Views are JavaScript classes which render templates written in pure HTML. The templates use data-* attributes to create bindings to model data and trigger event handlers.
• Controllers are persistent objects which mediate access to the model data, render the views, and handle events from the views.

A batman.js application is served up in one page load, followed by asynchronous requests for various resources as the user interacts with the app. Navigation within the app can use pushState where supported, or fall back on to hash-bang fragment identifers.

Batman Helpers

Batman includes an number of useful, general purpose helper functions and references. They can all be found attached to the Batman object and can optionally be exported into the global namespace with a $ prefix.

container

Batman.container points to either the window object if running the browser, or the global object if running in node. This is useful if you want to add something to the global scope in all environments.

typeOf(object) : string

typeOf determines a more specific type of an object than the native typeof operator in JavaScript. This is useful for a number of situations like dealing with Object promoted strings and numbers, or arrays which look like objects to typeof. Use typeOf when you need more than "object" from typeof.

Note: typeOf is substantially slower than typeof. typeOf works in a somewhat hackish manner by getting the Object::toString representation of the object and slicing it to retrieve the name of the constructor.

primitive = "test"
objectified = new String("test")
typeof primitive
"string"
typeof objectified
"object"
Batman.typeOf(primitive)
"String"
Batman.typeOf(objectified)
"String"

  

array = []
typeof array
"object"
Batman.typeOf(array)
"Array"

  

mixin(subject, objects...) : subject

mixin, occasionally known elsewhere as extend or merge, flattens a series of objects onto the subject. Key/value pairs on objects passed as later arguments (arguments with a higher index) take precedence over earlier arguments. Returns the subject passed in with the new values.

mixin also has special properties that make it different than the canonical extend functions:

1. If the subject has a set function, subject.set(key, value) will be used to apply keys instead of subject[key] = value. This means that if the subject is a Batman.Object, observers and thus bindings on the object will be notified when other (Batmanified or not) objects are mixed into it.
2. If a mixed-in object has an initialize function defined, that function will be called and passed the subject. This is useful for custom extension logic, similar to self.included in Ruby. For this reason, the keys initialize and uninitialize are skipped by mixin.
3. mixin only iterates over keys for which the hasOwnProperty test passes.

Note: mixin is destructive to (only) the first argument. If you need a non-destructive version of mixin, just pass an empty object as the first object, and all keys from the successive arguments will be applied to the empty object.

subject = {}
Batman.mixin(subject, {
    fit: true
  }, {
    fly: true
  }, {
    funky: true
  })
{
    fit: true,
    fly: true,
    funky: true
  } // mixin returns the subject
subject
{
    fit: true,
    fly: true,
    funky: true
  } // the subject is modified destructively

  

unmodified = {
    fit: true
  }
Batman.mixin({}, unmodified, {
    fly: true
  }, {
    funky: true
  })
{
    fit: true,
    fly: true,
    funky: true
  } // mixin returns the subject
unmodified
{
    fit: true
  } // argument objects are untouched allowing non-destructive merge

  

subject = {}
Batman.mixin(subject, {
    x: 1,
    y: 1
  }, {
    x: 2
  })
{
    x: 2,
    y: 1
  }

  

unmixin(subject, objects...) : subject

unmixin "unmerges" the passes objects from the subject. If a key exists on any of the objects it will be deleted from the subject. Returns the subject.

unmixin, similar to mixin, supports calling an uninitialize function for each of the objects being unmixed in. If an uninitialize function exists on each

subject = {
    fit: true,
    fly: true,
    funky: true
  }
Batman.unmixin(subject, {
    fit: true
  }, {
    fly: true
  })
{
    funky: true
  } // unmixin returns the subject
subject
{
    funky: true
  } // the subject is destructively modified.

  

isChildOf(parent : HTMLElement, child : HTMLElement) : boolean

isChildOf is a simple DOM helper which returns a boolean describing if the passed child node can be found in the descendants of the passed parent node.

setImmediate(callback : Function) : object

setImmediate (and it's sister clearImmediate) are a more efficient version of setTimeout(callback, 0). Due to timer resolution issues, setTimeout passed a timeout of 0 doesn't actually execute the function as soon as the JS execution stack has been emptied, but at minimum 4ms and maxmium 25ms after. For this reason Batman provides a cross browser implementation of setImmediate which does it's best to call the callback immediately after the stack empties. Batman's setImmediate polyfill uses the native version if available, window.postmessage trickery if supported, and falls back on setTimeout(->, 0).

setImmediate returns a handle which can be passed to clearImmediate to cancel the future calling of the callback.

clearImmediate(handle)

clearImmediate stops the calling of a callback in the future when passed it's handle (which is returned from the setImmediate call used to enqueue it).

forEach(iterable : object, iterator : Function[, context : Object])

The forEach Batman helper is a universal iteration helper. When passed an iterable object, the helper will call the iterator (optionally in the context) for each item in the iterable. The iterable can be:

1. something which has it's own forEach, in which case the iterator whill just be passed to iterable.forEach.
2. an array like object, in which case a JavaScript for(;;) loop will be used to iterate over each entry
3. or an object, in which case a JavaScript for-in loop will be used to iterate over each entry.

The forEach helper is useful for iterating over objects when the type of those objects isn't guaranteed.

set = new Batman.SimpleSet('a')
Batman.forEach(set, function(x) {
    return log(x);
  })
logged.last
"a"

  

ArrayLike = function() {}
ArrayLike.prototype = []
imitation = new ArrayLike
Array.prototype.push.call(imitation, "a")
Array.prototype.push.call(imitation, "b")
Batman.forEach(imitation, function(x) {
    return log(x);
  })
logged.last
"b"

  

object = {
    x: true
  }
Batman.forEach(object, function(key, val) {
    return log({
      key: key,
      val: val
    });
  })
logged.last
{
    key: 'x',
    val: true
  }

  

objectHasKey(object, key) : boolean

objectHasKey returns a boolean describing the presence of the key in the passed object. objectHasKey delegates to the object's hasKey function if present, and otherwise just does a check using the JavaScript in operator.

subject = {
    fit: true
  }
Batman.objectHasKey(subject, 'fit')
true
Batman.objectHasKey(subject, 'flirty')
false

  

subject = new Batman.SimpleHash({
    fit: true
  })
Batman.objectHasKey(subject, 'fit')
true
Batman.objectHasKey(subject, 'flirty')
false

  

contains(object, item) : boolean

contains returns a boolean describing if the given object has member item. Membership in this context is defined as:

• the result of object.has(item) if the object has a has function defined
• the result of item in object if the object is arraylike
• the result of the Batman.objectHasKey otherwise

Note: When passed an object without a has function, contains will return true if the object has item as a key, not as a value at any key.

contains is useful for checking item membership when the type of the object can't be relied on.

get(object, key) : value

get is a general purpose function for retrieving the value from a key on an object of an indeterminate type. This is useful if code needs to work with both Batman.Objects and Plain Old JavaScript Objects. get has the following semantics:

• if the object has a get function defined, return the result of object.get(key)
• if the object does not have a get function defined, use an ephemeral Batman.Property to retrieve the key. This is equivalent to object[key] for single segment keys, but if the key is multi-segment (example: 'product.customer.name'), get will do nested gets until the either undefined or the end of the keypath is reached.

subject = {
    fit: true
  }
Batman.get(subject, 'fit')
true
Batman.get(subject, 'flirty')
void 0

  

subject = Batman({
    fit: true
  })
Batman.get(subject, 'fit')
true
Batman.get(subject, 'flirty')
void 0

  

subject = {
    customer: {
      name: "Joe"
    }
  }
Batman.get(subject, 'customer.name')
"Joe"
Batman.get(subject, 'customer.age')
void 0

  

subject = Batman({
    customer: {
      name: "Joe"
    }
  })
Batman.get(subject, 'customer.name')
"Joe"
Batman.get(subject, 'customer.age')
void 0

  

escapeHTML(string) : string

escapeHTML takes a string of unknown origin and makes it safe for display on a web page by encoding control characters in HTML into their HTML entities.

Warning: Do not rely on escapeHTML to purge unsafe data from user submitted content. While escapeHTML is applied to every binding's contents by default, it should not be your only line of defence against script injection attacks.

Batman.escapeHTML("& < > \" '")
"&amp; &lt; &gt; &#34; &#39;"

  

Batman.helpers

Batman.helpers is a namespace for Batman's helpful string manipulation helpers.

Note: Batman's pluralization functions mirror those of Rails' exactly.

ordinalize(value : [number|string]) : string

ordinalize converts a given integer into an ordinal string for describing position in a list, like 1st, 2nd, or 20th.

Batman.helpers.ordinalize(1)
"1st"
Batman.helpers.ordinalize("2")
"2nd"
Batman.helpers.ordinalize(1002)
"1002nd"
Batman.helpers.ordinalize("1003")
"1003rd"
Batman.helpers.ordinalize(-11)
"-11th"
Batman.helpers.ordinalize(-1021)
"-1021st"

  

singularize(pluralString : string) : string

singularize converts the plural form of a word to a singular form.

Batman.helpers.singularize("posts")
"post"
Batman.helpers.singularize("octopi")
"octopus"
Batman.helpers.singularize("sheep")
"sheep"
Batman.helpers.singularize("word")
"word"
Batman.helpers.singularize("CamelOctopi")
"CamelOctopus"

  

pluralize(singularString : string) : string

pluralize converts the singular form of a word to the plural form.

Batman.helpers.pluralize("post")
"posts"
Batman.helpers.pluralize("octopus")
"octopi"
Batman.helpers.pluralize("sheep")
"sheep"
Batman.helpers.pluralize("words")
"words"
Batman.helpers.pluralize("CamelOctopus")
"CamelOctopi"

  

camelize(string, [lowercaseFirstLetter = false]) : string

camelize converts the passed string to UpperCamelCase. If the second argument is passed as true, then lowerCamelCase is returned.

Batman.helpers.camelize("batman_object")
"BatmanObject"
Batman.helpers.camelize("batman_object", true)
"batmanObject"

  

underscore(string) : string

underscore returns the underscored version of a CamelCase word.

Batman.helpers.underscore("BatmanObject")
"batman_object"

  

capitalize(string) : string

capitalize does a word-wise capitalization of a phrase or word.

Batman.helpers.capitalize("batmanObject")
"BatmanObject"
Batman.helpers.capitalize("batman object")
"Batman Object"
Batman.helpers.capitalize("AlreadyCapitalized")
"AlreadyCapitalized"

  

Batman.EventEmitter

EventEmitter is a mixin which can be applied to any object to give it the ability to fire events and accept listeners for those events.

on(key, handler)

Attaches a function handler to the event with name key. This function will be executed every time the event fires.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.on('detonate', function() {
    return log("detonated");
  })
true

  

fire(key, arguments...)

Calls all previously attached handlers on the event with name key. All handlers will receive the passed arguments.

Note: Calling fire doesn't guarantee the event will fire since firing can be prevented with prevent or preventAll.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.on('detonate', function(noise) {
    return log("detonated with noise " + noise);
  })
dynamite.fire('detonate', "BOOM!")
logged.last
"detonated with noise BOOM!"

  

hasEvent(key) : boolean

Asks if the EventEmitter has an event with the given key.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.on('detonate', function() {
    return log("detonated");
  })
dynamite.hasEvent('detonate')
true
dynamite.hasEvent('click')
false

  

oneShot : boolean

Events can be set to fire only once, and then fire subsequently attached handlers immediately if they are attached after the initial firing. This is useful for events similar to window.onload where they really only happen once in the lifespan of the application, but you don't want to check if they have happened already when attaching event handlers.

Access the Event object to set the oneShot property on them using EventEmitter::event.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.event('detonate').oneShot = true
dynamite.fire('detonate')
dynamite.on('detonate', function() {
    return log("detonated immediately!!");
  })
logged.last
"detonated immediately!!" // The handler was called as soon as it was attached.

  

prevent(key) : EventEmitter

Prevents the event with name key from firing, even if .fire is called. This is useful if you need to guarantee a precondition is in fulfilled before allowing event handlers to execute. Returns the event emitting object.

Undo event prevention with allow or allowAndFire.

Note: prevent can be called more than once to effectively "nest" preventions. allow or allowAndFire must be called the same number of times or more for events to fire once more.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.prevent('detonate')
dynamite.on('detonate', function() {
    return log("This shouldn't fire");
  })
dynamite.fire('detonate')
logged.last
void 0 // The event handler wasn't fired.

  

dynamite = $mixin({}, Batman.EventEmitter)
dynamite
dynamite.prevent('detonate')

  

allow(key) : EventEmitter

Allows the event with name key to fire once more, after prevent had been called previously. allow will not fire the event when called, regardless of weather or not the event can now be fired or if an attempt to fire it was made while the event was prevented. Returns the event emitting object.

Note: prevent can be called more than once to effectively "nest" preventions. allow or allowAndFire must be called the same number of times or more for events to fire once more.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.prevent('detonate')
dynamite.on('detonate', function() {
    return log("This will only fire once");
  })
dynamite.fire('detonate')
logged.length
0 // The event handler wasn't fired.
dynamite.allow('detonate')
dynamite.fire('detonate')
logged.length
1 // The event handler was fired.

  

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.prevent('detonate')
dynamite.prevent('detonate')
dynamite.on('detonate', function() {
    return log("This will only fire once");
  })
dynamite.fire('detonate')
logged.length
0 // The event handler wasn't fired, the prevent count is at 2.
dynamite.allow('detonate')
dynamite.fire('detonate')
logged.length
0 // The event handler still wasn't fired, but the prevent count is now at 1.
dynamite.allow('detonate')
dynamite.fire('detonate')
logged.length
1 // The event handler was fired.

  

dynamite = $mixin({}, Batman.EventEmitter)
dynamite
dynamite.allow('detonate')

  

allowAndFire(key)

Allows the event with name key to fire once more, and tries to fire it. allowAndFire may fail to fire the event if prevent has been called more times than allow or allowAndFire have previous.

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.on('detonate', function() {
    return log("This will only fire once");
  })
dynamite.prevent('detonate')
dynamite.fire('detonate')
logged.length
0 // The event handler wasn't fired.
dynamite.allowAndFire('detonate')
logged.length
1 // The event handler was fired.

  

dynamite = $mixin({}, Batman.EventEmitter)
dynamite.on('detonate', function() {
    return log("This will only fire once");
  })
dynamite.prevent('detonate')
dynamite.prevent('detonate')
dynamite.allowAndFire('detonate')
logged.length
0 // The event handler wasn't fired.
dynamite.allowAndFire('detonate')
logged.length
1 // The event handler was fired.

  

Batman.Observable

Batman.Observable is a mixin which gives objects the ability to notify subscribers to changes on its properties. Observable also adds functionality for observing keypaths: arbitrarily deeply nested properties on objects.

get(keypath) : value

Retrieves the value at a key on an object. Accepts keypaths.

Note: get must be used for property access on any object in Batman's world. This is so that Batman can implement neat things like automatic dependency calculation for computed properties, property caching where it is safe, and smart storage mechanisms. With Batman, you must use get instead of normal . property access.

song = Batman({
    length: 340,
    bpm: 120
  })
song.get('length')
340
song.get('bpm')
120

  

post = Batman({
    text: "Hello World!",
    author: Batman({
      name: "Harry"
    })
  })
post.get('author.name')
"Harry"

  

song = new Batman.Model({
    length: 340,
    bpm: 120
  })
typeof song.length
"undefined"
song.get('length')
340

  

set(keypath, newValue) : newValue

Stores the value at a key on an object. Accepts keypaths. Returns the new value of the property.

Note: Once more, set must be used for property mutation on all objects in the Batman world. This is again so that Batman can implement useful functionality like cache busting, eager recalculation of computed properties, and smarter storage.

Note: Custom setters can mutate the value during setting, so the value which was passed to set and set's return value are not guaranteed to be identical.

song = Batman({
    length: 340,
    bpm: 120
  })
song.get('length')
340
song.set('length', 1000)
1000
song.get('length')
1000

  

author = Batman({
    name: "Harry"
  })
post = Batman({
    text: "Hello World!",
    author: author
  })
post.set('author.name', "Nick")
"Nick"
author.get('name')
"Nick" // The value was set on the nested object.

  

song = new Batman.Model({
    length: 340,
    bpm: 120
  })
song.get('length')
340
song.length = 1000
1000
song.get('length')
340 // The song length reported by Batman is unchanged because set wasn't used to change the value.

  

unset(keypath) : value

Removes the value at the given keypath, leaving it undefined. Accepts keypaths. Returns the value the property had before unsetting.

unset is roughly equivalent to set(keypath, undefined), however, custom properties can define a nonstandard unset function, so it is best to use unset instead of set(keypath, undefined) wherever possible.

song = Batman({
    length: 340,
    bpm: 120
  })
song.get('length')
340
song.unset('length')
340
song.get('length')
void 0 // The value is unset.

  

author = Batman({
    name: "Harry"
  })
post = Batman({
    text: "Hello World!",
    author: author
  })
post.unset('author.name')
"Harry"
author.get('name')
void 0 // The value was unset on the nested object.

  

observe(key, observerCallback) : this

Adds a handler to call when the value of the property at the key changes upon setting. Accepts keypaths.

observe is the very core of Batman's usefulness. As long as set is used everywhere to do property mutation, any object can be observed for changes to its properties. This is critical to the concept of bindings, which Batman uses for it's views.

The observerCallback gets called whenever the key changes with the arguments newValue, oldValue.

Returns the object observe was called upon.

song = Batman({
    length: 340,
    bpm: 120
  })
song.observe('length', function(newValue, oldValue) {
    return log([newValue, oldValue]);
  })
song.set('length', 200)
200
logged.last
[200, 340]
song.set('length', 300)
300
logged.last
[300, 200]

  

Note: observe works excellently on keypaths. If you attach a handler to a "deep" keypath, it will fire any time the value of that keypath changes, which is another way of saying the handler will fire when any segment of the keypath changes, passing in the new value at the end of the keypath.

author = Batman({
    name: "Harry"
  })
post = Batman({
    text: "Hello World!",
    author: author
  })
post.observe('author.name', function(newName, oldName) {
    return log([newName, oldName]);
  })
post.set('author', newAuthor = Batman({
    name: "James"
  }))
logged.last
["James", "Harry"] // The observer fired when the 'author' segment of the keypath changed.

  

observeAndFire(key, observerCallback) : this

Adds the observerCallback as an observer to key, and fires it immediately. Accepts the exact same arguments and follows the same semantics as Observable::observe, but the observer is fired with the current value of the keypath it observers synchronously during the call to observeAndFire.

During the initial synchronous firing of the callback, the newValue and oldValue arguments will be the same value: the current value of the property. This is because the old value of the property is not cached and therefore unavailable. If your observer needs the old value of the property, you must attach it before the set on the property happens.

song = Batman({
    length: 340,
    bpm: 120
  })
song.observeAndFire('length', function(newValue, oldValue) {
    return log([newValue, oldValue]);
  })
logged.last
[340, 340]
song.set('length', 300)
300
logged.last
[300, 340]

  

forget([key [, observerCallback]]) : this

If observerCallback and key are given, that observer is removed from the observers on key. If only a key is given, all observers on that key are removed. If no key is given, all observers on all keys are removed. Accepts keypaths.

Returns the object forget was called upon.

song = Batman({
    length: 340,
    bpm: 120
  })
observer = function(newValue, oldValue) {
    return log([newValue, oldValue]);
  }
song.observe('length', observer)
song.set('length', 200)
200
logged.last
[200, 340]
song.forget('length', observer)
song.set('length', 300)
300
logged.last
[200, 340] // The logged values haven't changed because the observer hasn't fired again.

  

song = Batman({
    length: 340,
    bpm: 120
  })
observerA = (function(newValue, oldValue) {
    return log([newValue, oldValue]);
  })
observerB = (function(newValue, oldValue) {
    return log([newValue, oldValue]);
  })
song.observe('length', observerA)
song.observe('length', observerB)
song.set('length', 200)
200
logged.length
2 // Both length observers fired.
song.forget('length')
song.set('length', 300)
300
logged.length
2 // Nothing more has been logged because neither observer fired.

  

song = Batman({
    length: 340,
    bpm: 120
  })
observerA = (function(newValue, oldValue) {
    return log([newValue, oldValue]);
  })
observerB = (function(newValue, oldValue) {
    return log([newValue, oldValue]);
  })
song.observe('length', observerA)
song.observe('bpm', observerB)
song.set('length', 200)
200
logged.length
1 // The length observer fired.
song.forget()
song.set('length', 300)
300
song.set('bpm', 130)
130
logged.length
1 // Nothing more has been logged because neither observer fired.

  

getOrSet(keypath, valueFunction) : value

Assigns the keypath to the result of calling the valueFunction if the current value at the keypath is falsey. Returns the value of the property after the operation, be it changed or not. Equivalent to CoffeeScript's ||= operator.

song = Batman({
    length: 340,
    bpm: 120
  })
song.getOrSet('length', function() {
    return 500;
  })
340
song.get('length')
340

  

song = Batman({
    length: 340,
    bpm: 120
  })
song.getOrSet('artist', function() {
    return "Elvis";
  })
"Elvis"
song.get('artist')
"Elvis"

  

Batman.Object

Batman.Object is the superclass for virtually all objects in a Batman application. Batman.Object mixes in Batman.Observable and Batman.EventEmitter for things like get, set, observe, and fire, and then defines some more useful things for tying everything together.

@accessor([keys...], objectOrFunction)

Accessors are used to create properties on a class, prototype, or instance which can be fetched, set, and unset. These properties can be static, computed as functions of the other properties on the object the accessor belongs to, or properties of any Batman object in the system. accessor is a Batman and old browser friendly version of ES5 Object.defineProperty missing some of the goodness.

The value of custom accessors can be observed just like any property. Accessors also track which other properties they rely on for computation, and recalculate eagerly when those other properties change. This way, when a source value is changed, any dependent accessors will automatically update any bindings to them with a new value. Accessors accomplish this feat by tracking get calls, so do be sure to use get to retrieve properties on Batman Objects inside accessors so those properties can be tracked as dependencies. The property dependencies of an accessor are called "sources" in the Batman world.

Importantly, accessors are also inherited, so accessors defined anywhere in an object's prototype chain will be used. Following this, @accessor is meant to be used during the class definition of a class extending Batman.Object.

Arguments

@accessor can be called with zero, one, or many keys for the accessor to define. This has the following effects:

• zero: create a defaultAccessor, which will be called when no other properties or accessors on an object match a keypath. This is similar to method_missing in Ruby or #doesNotUnderstand in Smalltalk.
• one: create a keyAccessor at the given key, which will only be called when that key is gotten, set, or unset.
• many: create keyAccessors for each given key, which will then be called whenever each one of the listed keys is gotten, set, or unset.

@accessor accepts as the last argument either an object with any combination of the get, set, and unset keys defined. Functions which implement the behaviour for those particular actions on the property should reside at these keys. @accessor also accepts a function as the last argument, which is a shorthand for specifying the get implementation for the accessor.

Uses

Accessors are a really useful addition to the world of JavaScript. You can now define transforms on simple properties which will automatically update when the properties they transform change, for example you might want to truncate a potentially long piece of text to display a summary elsewhere, or you might want to capitalize or encodeURIComponent a value before putting it in the view or the current URL.

Post = (function(_super) {

    __extends(Post, _super);

    function Post() {
      return Post.__super__.constructor.apply(this, arguments);
    }

    Post.accessor('summary', function() {
      return this.get('body').slice(0, 10) + "...";
    });

    return Post;

  })(Batman.Object)
post = new Post({
    body: "Why Batman is Useful: A lengthy post on an important subject"
  })
post.get('summary')
"Why Batman..."

  

You can also use accessors to combine properties; the colloquial fullName example comes to mind, but all sorts of other complex logic can be abstracted away using the accessor pattern.

User = (function(_super) {

    __extends(User, _super);

    function User() {
      return User.__super__.constructor.apply(this, arguments);
    }

    User.accessor('fullName', function() {
      return this.get('firstName') + " " + this.get('lastName');
    });

    return User;

  })(Batman.Object)
tim = new User({
    firstName: "Tim",
    lastName: "Thomas"
  })
tim.get('fullName')
"Tim Thomas"
tim.set('firstName', "Timmy")
tim.get('fullName')
"Timmy Thomas"

  

Accessors can define custom get, set, and unset functions to support each operation on the property:

AbsoluteNumber = (function(_super) {

    __extends(AbsoluteNumber, _super);

    function AbsoluteNumber() {
      return AbsoluteNumber.__super__.constructor.apply(this, arguments);
    }

    AbsoluteNumber.accessor('value', {
      get: function() {
        return this._value;
      },
      set: function(_, value) {
        return this._value = Math.abs(value);
      },
      unset: function() {
        return delete this._value;
      }
    });

    return AbsoluteNumber;

  })(Batman.Object)
number = new AbsoluteNumber({
    value: -10
  })
number.get('value')
10

  

Importantly, it is also safe to use branching, loops, or whatever logic you want in accessor bodies:

Player = (function(_super) {

    __extends(Player, _super);

    function Player() {
      return Player.__super__.constructor.apply(this, arguments);
    }

    Player.accessor('score', function() {
      if (this.get('played')) {
        return (this.get('goals') * 2) + (this.get('assists') * 1);
      } else {
        return 0;
      }
    });

    return Player;

  })(Batman.Object)
rick = new Player({
    played: false,
    goals: 0,
    assists: 0
  })
rick.get('score')
0
rick.set('played', true)
rick.get('score')
0
rick.set('goals', 3)
rick.get('score')
6
rick.set('assists', 1)
rick.get('score')
7

  

Caveats

Accessors are extremely useful but you must keep these items in mind while programming using them:

1. Accessors should be linear, so they can be cached.

Batman automatically memoizes the return value of accessors, and will not re-execute the body until one of the accessor's sources changes. If you need the accessor to recalculate every time the property is gotten, pass false for the cache option in the accessor descriptor object (the last argument to the @accessor function).

counter = 0
Example = (function(_super) {

    __extends(Example, _super);

    function Example() {
      return Example.__super__.constructor.apply(this, arguments);
    }

    Example.accessor('cachedCounter', function() {
      return ++counter;
    });

    Example.accessor('notCachedCounter', {
      get: function() {
        return ++counter;
      },
      cache: false
    });

    return Example;

  })(Batman.Object)
example = new Example()
example.get('cachedCounter')
1
example.get('cachedCounter')
1
example.get('cachedCounter')
1 // The second and third calls do not execute the function
example.get('notCachedCounter')
2
example.get('notCachedCounter')
3 // Passing cache: false does re-execute the function
example.get('cachedCounter')
1

  

1. Accessors must use get to access properties they use for computation

Batman tracks an accessor's sources by adding a global hook to all gets done, so if you don't use get to access properties on objects, Batman can't know that that property is a source of the property your accessor defines, so it can't recompute that property when the source property changes. All properties on Batman.Object should be accessed using get and set regardless if the code occurs in an accessor body or not, but it is critical to do so in accessors so the sources of the accessor can be tracked.

1. Accessors can create memory leaks or performance bottlenecks

If you return a brand new object by say merging a number of Batman.Sets or doing any sort of major and complete re-computation you run the risk of creating performance problems. This is because accessors can be called frequently and unpredictably, as they are recomputed every time one of their sources changes as well as upon every set. Instead of recomputing expensive things every time the accessor is called, try to use objects which do delta recomputation using observers. Practically this translates to using things like new SetUnion(@get('setA'), @get('setB')) instead of @get('setA').merge(@get('setB')) in an accessor body.

@classAccessor([keys...], objectOrFunction)

classAccessor defines an accessor on the class, in that gets and sets done on the class will use the accessor definition as an implementation. @accessor called on a class will define an accessor for all instances of that class, where as @classAccessor defines accessors on the class object itself. See @accessor for the details surrounding accessors.

SingletonDooDad = (function(_super) {

    __extends(SingletonDooDad, _super);

    function SingletonDooDad() {
      return SingletonDooDad.__super__.constructor.apply(this, arguments);
    }

    SingletonDooDad.classAccessor('instance', function() {
      return new this();
    });

    return SingletonDooDad;

  })(Batman.Object)
instance = SingletonDooDad.get('instance')
SingletonDooDad.get('instance') === instance
true // A second get returns the same instance

  

@mixin(objects...) : prototype

@mixin is a handy function for mixing in objects to a class' prototype. @mixin is implemented on top of the Batman level mixin helper, which means that keys from incoming objects will be applied using set, and any initialize functions on the objects will be called with the prototype being mixed into. Returns the prototype being mixed into.

Note: @mixin, similar to @accessor, applies to all instances of a class. If you need to mix in to the class itself, look at classMixin. note: @mixin, once more similar to @accessor, is intended for use during the class definition of a Batman.Object subclass.

FishBehaviour = {
    canBreathUnderwater: true
  }
MammalBehaviour = {
    canBreathAboveWater: true
  }
Platypus = (function(_super) {

    __extends(Platypus, _super);

    function Platypus() {
      return Platypus.__super__.constructor.apply(this, arguments);
    }

    Platypus.mixin(FishBehaviour, MammalBehaviour);

    return Platypus;

  })(Batman.Object)
platypus = new Platypus
platypus.get('canBreathAboveWater')
true
platypus.get('canBreathUnderwater')
true

  

@classMixin(objects...) : this

@classMixin allows mixing in objects to a class during that class' definition. See @mixin for information about the arguments passed to mixin, but note that @classMixin applies to the class object itself, and @mixin applies to all instances of the class. Returns the class being mixed into.

Singleton = {
    initialze: function(subject) {
      return subject.accessor('instance', function() {
        return new subject;
      });
    }
  }
Highlander = (function(_super) {

    __extends(Highlander, _super);

    function Highlander() {
      return Highlander.__super__.constructor.apply(this, arguments);
    }

    Highlander.classMixin(Singleton);

    return Highlander;

  })(Batman.Object)
instance = Highlander.get('instance')
instance === Highlander.get('instance')
true // There can only be one.

  

@observeAll(key, callback : function) : prototype

@observeAll extends the Batman.Object implementation of Batman.Observable with the ability to observe all instances of the class (and subclasses). Observers attached with @observeAll function exactly as if they were attached to the object directly. Returns the prototype of the class.

Note: @observeAll is intended to be used during the class definition for a Batman.Object subclass, but it can be called after the class has been defined as a function on the class. It supports being called after instances of the class have been instantiated as well.

Song = (function(_super) {

    __extends(Song, _super);

    function Song() {
      return Song.__super__.constructor.apply(this, arguments);
    }

    Song.observeAll('length', function(newValue, oldValue) {
      return log(newValue);
    });

    return Song;

  })(Batman.Object)
song = new Song({
    length: 340,
    bpm: 120
  })
song.set('length', 200)
200
logged.last
200

  

Song = (function(_super) {

    __extends(Song, _super);

    function Song() {
      return Song.__super__.constructor.apply(this, arguments);
    }

    return Song;

  })(Batman.Object)
song = new Song({
    length: 340,
    bpm: 120
  })
song.set('length', 360)
360
logged.last
void 0
Song.observeAll('length', function(newValue, oldValue) {
    return log(newValue);
  })
song.set('length', 200)
200
logged.last
200

  

constructor(objects...)

To create a new Batman.Object, the Batman.Object constructor can be used, or, the Batman namespace is also a utility function for creating Batman objects. Each object passed in to the constructor will have all its properties applied to the new Batman.Object using get and set, so any custom getters or setters will be respected. Objects passed in last will have precedence over objects passed in first in the event that they share the same keys. The property copy from these objects is shallow.

object = Batman({
    foo: 'bar'
  })
typeof object.get
'function'

  

song = Batman({
    length: 100,
    bpm: 120
  }, {
    bpm: 130
  })
song.get('length')
100
song.get('bpm')
130 // The property from the second object passed to the constructor overwrites that from the first.

  

toJSON() : object

toJSON returns a vanilla JavaScript object representing this Batman.Object.

object = Batman({
    foo: 'bar'
  })
object.toJSON()
{
    foo: 'bar'
  }

  

hashKey() : string

hashKey returns a unique string representing this particular Batman.Object. No two Batman.Objects will have the same hashKey.

accessor([keys...], objectOrFunction)

accessor defines an accessor on one instance of an object instead of on all instances like the class level @accessor. See @accessor for the details surrounding accessors.

Post = (function(_super) {

    __extends(Post, _super);

    function Post() {
      return Post.__super__.constructor.apply(this, arguments);
    }

    Post.accessor('summary', function() {
      return this.get('body').slice(0, 10) + "...";
    });

    return Post;

  })(Batman.Object)
post = new Post({
    body: "Why Batman is Useful: A lengthy post on an important subject"
  })
post.get('summary')
"Why Batman..."
post.accessor('longSummary', function() {
    return this.get('body').slice(0, 20) + "...";
  })
post.get('longSummary')
"Why Batman is Useful..."

  

Post = (function(_super) {

    __extends(Post, _super);

    function Post() {
      return Post.__super__.constructor.apply(this, arguments);
    }

    return Post;

  })(Batman.Object)
post = new Post({
    body: "Why Batman is Useful: A lengthy post on an important subject"
  })
otherPost = new Post({
    body: "Why State Machines Are Useful: Another lengthy post"
  })
post.accessor('longSummary', function() {
    return this.get('body').slice(0, 20) + "...";
  })
post.get('longSummary')
"Why Batman is Useful..."
otherPost.get('longSummary')
void 0

  

mixin(objects...) : this

mixin extends the object it's called on with the passed objects using the Batman.mixin helper. Returns the object it's called upon.

Note: Since the Batman.mixin helper is used, mixin functionality like using set to apply properties and calling initialize functions is included in the instance level mixin function.

Snake = (function(_super) {

    __extends(Snake, _super);

    function Snake() {
      return Snake.__super__.constructor.apply(this, arguments);
    }

    return Snake;

  })(Batman.Object)
snake = new Snake()
snake.mixin({
    canSlither: true
  }, {
    canHiss: true
  })
snake.get('canSlither')
true
snake.get('canHiss')
true

  

Batman.SimpleSet

SimpleSet is an implementation of the Set object you might expect to find in lots of other languages standard libraries. Sets are an enumerable but unordered collection of objects. A particular object may either be a member or not be a member of a particular set, but it may not belong to the set twice, as that would imply ordering. In the case of Batman, sets will tell you when items are added or removed through events, sets mix in the Enumerable module for handy iteration and aggregation, and can also generate indexes and sorts via SetIndex and SetSort.

SimpleSet vs Set

SimpleSet and Set are two distinct classes in Batman. SimpleSet implements the set semantics as described above, but it is not a Batman.Object, so properties on it (like it's length or toArray) can not be observed, and thus not bound. Set is a Batman.Object, so it can be observed, and thus plays nice with the accessor system. Use a SimpleSet only when you know nothing will need to be observed on the set you are creating, which usually isn't a valid assumption. If it is in fact correct, consider using a native array as well, because iteration and in fact membership checks will be faster.

constructor(items...)

When creating a SimpleSet, items forming the initial set can be passed as separate arguments to the constructor

set = new Batman.SimpleSet
set.toArray()
[]

  

set = new Batman.SimpleSet('a', 'b', 'c')
set.toArray().sort()
['a', 'b', 'c']

  

length : number

A count of the items in a SimpleSet can be found at it's length property.

has(item) : Boolean

has returns a boolean describing if the given item is a member of the set.

set = new Batman.SimpleSet('a', 'b', 'c')
set.has('a')
true
set.has('d')
false

  

add(items...) : Array

add adds 0 or more new items to the set. add returns an array of the items which have been newly added to the set, which is to say the intersection of the argument items and the set itself before addition.

set = new Batman.SimpleSet()
set.has('a')
false
set.add('a')
['a']
set.has('a')
true

  

set = new Batman.SimpleSet('a', 'b')
set.add('b', 'c', 'd').sort()
['c', 'd']
set.toArray().sort()
['a', 'b', 'c', 'd']

  

remove(items...) : Array

remove removes 0 or more items from the set. remove returns an array of the items which were successfully removed from the set, which is to say the intersection of the argument items and the set itself before removal.

set = new Batman.SimpleSet('a')
set.has('a')
true
set.remove('a')
['a']
set.has('a')
false

  

set = new Batman.SimpleSet('a', 'b')
set.remove('b', 'c', 'd').sort()
['b']
set.toArray()
['a']

  

find(testFunction : function) : [Object]

find returns the first item within the set for which the testFunction called with the item returns true, or undefined if no item passes the test.

Note: find returns the first item the test passes for, but since set iteration has no specified order, no guarantee can be made about which item will be returned if more than one item in the set passes the test. However, set iteration order is stable, so find called on the same set twice should return the same item.

set = new Batman.SimpleSet(1, 2, 3)
set.find(function(x) {
    return x % 2 === 0;
  })
2

  

set = new Batman.SimpleSet(1, 2, 3)
typeof set.find(function(x) {
    return x > 5;
  })
'undefined'

  

forEach(iteratorFunction : function[, context: Object])

forEach calls the iteratorFunction with each item in the set, optionally executing the iteratorFunction in the passed context. Returns undefined.

Note: Set iteration order is not defined, which is to say Set client code cannot rely on one item being iterated over before another, regardless of when the Set's items were added. If you need an ordered set, Batman provides SetSort for exactly this, while including the added benefit of observability. If you need a one time ordering of a set, you can get the array representation with toArray and then use vanilla JavaScript sort on that array.

sum = 0
set = new Batman.SimpleSet(1, 2, 3)
set.forEach(function(x) {
    return sum += x;
  })
sum
6

  

context = {
    sum: 0
  }
set = new Batman.SimpleSet(1, 2, 3)
set.forEach(function(x) {
    return this.sum += x;
  }, context)
context.sum
6

  

isEmpty() : boolean

isEmpty returns a boolean: true if the set has no items, and false if it has any items.

set = new Batman.SimpleSet()
set.isEmpty()
true
set.add('a')
set.isEmpty()
false

  

clear() : Array

clear removes all items from a set. Returns an array of all the items in the set.

Note: Set iteration order is not defined, so the order of the array of items returned by clear is undefined.

set = new Batman.SimpleSet('a', 'b', 'c')
set.isEmpty()
false
set.clear().sort()
['a', 'b', 'c']
set.isEmpty()
true

  

replace(collection : Enumerable) : Array

replace removes all the items in a set and then adds all the items found in another collection. The other collection must have a toArray function which returns an array representation of the collection. Returns the array of items added.

set = new Batman.SimpleSet('a', 'b', 'c')
secondSet = new Batman.SimpleSet('d', 'e', 'f')
set.replace(secondSet).sort()
['d', 'e', 'f']
set.toArray().sort()
['d', 'e', 'f']

  

toArray() : Array

toArray returns an array representation of the set.

Note: Set iteration order is not defined, so the order in which the set's items appear in the array is not defined. It is however stable, so the order of the items in two successive toArray calls where the set was not modified in between should be the same.

set = new Batman.SimpleSet()
set.toArray()
[]
set.add('a', 'b', 'c')
set.toArray().sort()
['a', 'b', 'c']

  

merge(collections... : Enumerable) : SimpleSet

merge adds all the items in a set and all the items in the passed collections to a new set and returns it. A collection is an object which has a forEach function. It is a non-destructive collection union. The set merge is called on and each collection passed to merge remain unaffected.

abc = new Batman.SimpleSet('a', 'b', 'c')
def = new Batman.SimpleSet('d', 'e', 'f')
Batman.typeOf(set = abc.merge(def))
'Object'
set.toArray().sort()
['a', 'b', 'c', 'd', 'e', 'f']

  

indexedBy(key : String) : SetIndex

indexedByUnique(key : String) : UniqueSetIndex

sortedBy(key: String) : SetSort

Batman.Set

Set is an observable, Batman.Object wrapper around SimpleSet.

SimpleSet vs Set

SimpleSet and Set are two distinct classes in Batman. SimpleSet implements the basic set semantics, but it is not a Batman.Object, so properties on it (like it's length or toArray) can not be bound. Set is a Batman.Object, so it can be observed, and thus plays nice with the accessor system. Use a SimpleSet only when you know nothing will need to be observed on the set you are creating, which usually isn't a valid assumption. If it is in fact correct, consider using a native array as well, because iteration and in fact membership checks will be faster.

constructor(items...)

When creating a Set, items forming the initial set can be passed as separate arguments to the constructor

set = new Batman.Set
set.toArray()
[]

  

set = new Batman.Set('a', 'b', 'c')
set.toArray().sort()
['a', 'b', 'c']

  

length : number

A count of the items in a Set can be found at it's length property.

isEmpty : boolean

Observable property for isEmpty()

toArray : Array

Observable property for toArray(). Whenever items are added or removed on the set, the toArray property will change. This is the mechanism by which Batman's view bindings get notified of collection updates.

set = new Batman.Set('a', 'b', 'c')
set.observe('toArray', function(newArray) {
    return log(newArray.sort());
  })
set.add('d')
['d']
logged.last
['a', 'b', 'c', 'd']
set.remove('b')
['b']
logged.last
['a', 'c', 'd']

  

has(item) : Boolean

has returns a boolean describing if the given item is a member of the set.

Note: Using has(item) in an accessor body will register the set has is called upon as a source of the property being calculated. This so that whenever the set changes, the property will be recalculated, because the set may now have or not have the item in question.

set = new Batman.Set('a', 'b', 'c')
set.has('a')
true
set.has('d')
false

  

(Team = (function(_super) {

    __extends(Team, _super);

    function Team() {
      this.awards = new Batman.Set();
    }

    Team.accessor('bestEver?', function() {
      return this.get('awards').has('Stanley Cup');
    });

    return Team;

  })(Batman.Object))
team = new Team
team.observeAndFire('bestEver?', function(status) {
    return log(status);
  })
team.get('awards').add('Eastern Conference Champs')
logged.last
false
team.get('awards').add('Stanley Cup')
logged.last
true

  

add(items...)

add adds 0 or more new items to the set. add returns an array of the items which have been newly added to the set, which is to say the intersection of the argument items and the set itself before addition.

add fires the itemsWereAdded event with the list of items newly added to the set if that list has length greater than 0. This is to say the event will not be fired if the items passed to add were all already members of the set.

set = new Batman.Set()
set.has('a')
false
set.add('a')
['a']
set.has('a')
true

  

set = new Batman.Set('a', 'b')
set.add('b', 'c', 'd').sort()
['c', 'd']
set.toArray().sort()
['a', 'b', 'c', 'd']

  

set = new Batman.Set('a', 'b')
set.on('itemsWereAdded', function() {
    var items;
    items = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
    return log(items);
  })
set.add('b', 'c', 'd')
logged.last.sort()
['c', 'd']

  

set = new Batman.Set('a', 'b')
set.on('itemsWereAdded', function() {
    var items;
    items = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
    return log(items);
  })
set.add('a', 'b')
typeof logged.last
'undefined'

  

remove(items...)

remove removes 0 or more items from the set. remove returns an array of the items which were successfully removed from the set, which is to say the intersection of the argument items and the set itself before removal.

remove fires the itemsWereRemoved event with the list of removed items if that list has length greater than 0. This is to say the event will not be fired if none of the passed items were members of the set.

set = new Batman.Set('a')
set.has('a')
true
set.remove('a')
['a']
set.has('a')
false

  

set = new Batman.Set('a', 'b')
set.remove('b', 'c', 'd').sort()
['b']
set.toArray()
['a']

  

set = new Batman.Set('a', 'b', 'c')
set.on('itemsWereRemoved', function() {
    var items;
    items = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
    return log(items);
  })
set.remove('b', 'c')
logged.last.sort()
['b', 'c']

  

set = new Batman.Set('a', 'b')
set.on('itemsWereRemoved', function() {
    var items;
    items = 1 <= arguments.length ? __slice.call(arguments, 0) : [];
    return log(items);
  })
set.remove('c', 'd')
typeof logged.last
'undefined'

  

find(testFunction : function) : [Object]

find returns the first item within the set for which the testFunction called with the item returns true, or undefined if no item passes the test.

Note: find returns the first item the test passes for, but since set iteration has no specified order, no guarantee can be made about which item will be returned if more than one item in the set passes the test. However, set iteration order is stable, so find called on the same set twice should return the same item.

set = new Batman.Set(1, 2, 3)
set.find(function(x) {
    return x % 2 === 0;
  })
2

  

set = new Batman.Set(1, 2, 3)
typeof set.find(function(x) {
    return x > 5;
  })
'undefined'

  

forEach(iteratorFunction : function[, context: Object])

forEach calls the iteratorFunction with each item in the set, optionally executing the iteratorFunction in the passed context. Returns undefined.

Note: Set iteration order is not defined, which is to say Set client code cannot rely on one item being iterated over before another, regardless of when the Set's items were added. If you need an ordered set, Batman provides SetSort for exactly this, while including the added benefit of observability. If you need a one time ordering of a set, you can get the array representation with toArray and then use vanilla JavaScript sort on that array.

Note: Using forEach() in an accessor body will register the set iterated over as a source of the property being calculated. This so that whenever the set changes, the property will be recalculated. This can be come an issue if you iterate over a set and modify the set's items, as when the property recalculates that modification will potentially happen on item's it's happened on previously.

sum = 0
set = new Batman.Set(1, 2, 3)
set.forEach(function(x) {
    return sum += x;
  })
sum
6

  

context = {
    sum: 0
  }
set = new Batman.Set(1, 2, 3)
set.forEach(function(x) {
    return this.sum += x;
  }, context)
context.sum
6

  

(Team = (function(_super) {

    __extends(Team, _super);

    function Team() {
      this.players = new Batman.Set();
    }

    Team.accessor('willWinTheCup?', function() {
      var sedinCount;
      sedinCount = 0;
      this.players.forEach(function(player) {
        if (player.split(' ')[1] === 'Sedin') {
          return sedinCount++;
        }
      });
      return sedinCount >= 2;
    });

    return Team;

  })(Batman.Object))
team = new Team()
team.observeAndFire('willWinTheCup?', function(status) {
    return log(status);
  })
team.get('willWinTheCup?')
false
team.get('players').add('Henrik Sedin')
logged.last
false
team.get('players').add('Daniel Sedin')
logged.last
true

  

isEmpty() : boolean

isEmpty returns a boolean: true if the set has no items, and false if it has any items.

Note: Using isEmpty() in an accessor body will register the set isEmpty is called on as a source of the property being calculated, so that whenever the set changes the property will be recalculated.

set = new Batman.Set()
set.isEmpty()
true
set.add('a')
set.isEmpty()
false