This package has been deprecated

Author message:

republished package as active-resource@0.9.0 to fix name convention error and give more semantic versioning space for additional bug fixes that should have been done before v1.0.0 was released

activeresource

ActiveResource.js - Object-relational mapping in Javascript

Welcome to ActiveResource.js, an object relational mapping library for Javascript. ActiveResource.js is designed to make interacting with resources stored on a RESTful server more straightforward and holistic than simpler solutions like ngResource. ActiveResource.js constructs and executes requests and formats responses into meaningful resource representations on the client side, allowing you to perform CRUD operations, as well as interact with and modify the various relationships (often known as associations) of resources effortlessly.

ActiveResource.js is inspired heavily by Active Record, the well known ORM for Ruby on Rails. In the same way that Active Record makes interacting with relational databases trivial in most of the use cases that might be required of a server side application, ActiveResource.js hopes to make interacting with RESTful servers trivial in most of the use cases that might be required of a client side application.

The library provides a base class that, when subclassed, sets up a mapping between the new class and an existing resource scope on the server. In the context of an application, these classes are commonly referred to as models. Models can also be connected to other models in two ways: through client side interaction (whose behavior is defined by associations), and by making requests to persist the association on the server.

ActiveResource.js relies heavily on naming in that it uses class and association names to establish mappings between respective resource endpoints, subresource endpoints, and foreign key properties. Although these mappings can be defined explicitly, it's recommended to follow naming conventions, especially when getting started with the library.

---

WARNING: ActiveResource.js currently only works in browsers. A new release will soon allow it to work in Node, plus change some design decisions to use more universal idioms.

---

New in 2.0: Resource Libraries (Getting Started)

In order to use ActiveResource, you must first create a resource library to hold configuration data for accessing your resources:

# lib/myLibrary.coffee 
 
MyLibrary = ActiveResource.createResourceLibrary(
  'https://example.com/api/v1/', # base url for your server 
  headers: { Authorization: 'Basic ...' }
)

Then, you create a resource class for each resource in your library:

 
# lib/myLibrary/product.coffee 
 
class MyLibrary.Product extends MyLibrary.Base
  this.className = 'Product'
  this.queryName = 'products'
 
# **or** 
 
class MyLibrary::Product extends MyLibrary.Base
  this.className = 'Product'
  this.queryName = 'products'

Both className and queryName are required, and you can see what they do in the configuration section of this page.

Some of the major features include:

---

• Automated mapping between classes and endpoints, attributes and relationships

class MyLibrary.Product extends MyLibrary.Base
  this.className = 'Product'
  this.queryName = 'products'

The Product class is automatically mapped to the RESTful endpoints for product resources on the server, which would all have the URL:

http://example.com/api/v1/products/

---

• HTTP requests constructable through simple to use chained method calls (a Relation)

Product.where(title: 'A product title').includes('orders').order(createdAt: 'desc').all()
Product.select('title').first(5)
Product.page(2).perPage(1).all()
 
Product.limit(2).offset(2).all()
 
Product.find(1)
Product.findBy(title: 'A product title')
 
Product.each (p) ->
  ...
 
Product.includes('orders', merchant: ['currency']).all()

Method calls like all() will return a promise, and the response in the promise will be an ActiveResource::Collection (see below). If the response is expected to be a single resource (find, findBy, first) it will just be that resource.

Note: Due to the current design of JSON API, if you use both select and includes in the same Relation chain, you should add any includes to select. For example:

Product.includes('merchant').select('title').all()

should be:

Product.includes('merchant').select('title','merchant').all()

This is because the JSON API spec defines both attributes and relationships as fields, which is what the select method constructs. So if you want to include a relationship and you also plan on selecting fields, make sure that you specify any includes as a field using select. This does not apply if you only want to use includes without select.

---

• Persistence methods that simplify managing of resources

product = Product.build(title: 'A product title')
product.save ->
  if product.valid()
    product.persisted() # == true 
  else
    product.errors().empty() # == false 
 
Product.create title: 'A product title', (product) ->
  if product.valid()
    ...
  else
    product.newRecord() # == true 
 
Product.first()
.then (product) ->
  product.update title: 'A new title'
 
Product.first()
.then (product) ->
  product.destroy()
 
Product.first()
.then (product) ->
  product.reload()

---

• Associations between objects defined by simple class methods

class MyLibrary.Product extends MyLibrary.Base
  @hasMany 'orders'
 
class MyLibrary.Order extends MyLibrary.Base
  @belongsTo 'product'

This defines a number of methods on each class. For hasMany:

product = Product.build()
product.orders()             # collection proxy to use for more queries (see below) 
product.orders().toArray()   # read 
product.orders().build()     # local construction 
product.orders().create()    # persisted construction 
product.orders().assign()    # persisted assignment 
product.orders().push()      # persisted concatenation 
product.orders().delete()    # persisted deletion of association (not the resources themselves) 
product.orders().deleteAll()
product.orders().reload()
product.orders().empty()     # NOTE: Only indicates if the collection currently loaded is empty 
product.orders().size()      # NOTE: Only gives the size of the collection currently loaded 

In regards to association collection proxies, you can work off them just like you would any other ActiveResource Relation class:

product.orders().where(title: 'A product title').select('title').last(10)
.then (orders) ->
  # result will only be orders related to `product` 
 
product.orders().includes('merchant').create title: 'A product title', (order) ->
  if order.valid()
    order.merchant() # != null, was included in response 
  else
    order.errors()

It is important to note that none of the hasMany methods above will assign the actual target of the association to their result, nor will the association be considered "loaded." For example:

product.orders().where(title: 'A product title').select('title').last(10)
.then (orders) ->
  orders # != [] 
  product.orders().toArray() # == [] 
  product.association('orders').loaded() # == false 

To accomplish this, one must load the association either in the initial query, or at some later point in time:

Product.includes('orders').first()
.then (product) ->
  product.orders().toArray() # != [] 
  product.association('orders').loaded() # == true 
 
Product.first()
.then (product) ->
  product.association('orders').loaded() # == false 
 
  product.loadOrders()
  .then ->
    product.association('orders').loaded() # == true 
 
  product.orders().loadTarget()
  .then ->
    product.association('orders').loaded() # == true 
 
  product.orders().reload()
  .then ->
    product.association('orders').loaded() # == true 

In general, it is best to include every association you'll need to do your business in the very first query.

It is also worth noting that most Relation methods (and association Relation methods here) will return promises, and do not hit any sort of cache. If you want to make a synchronous method call that gives you the current target of the association (loaded or not), you have a few options:

Product.includes('orders').first()
.then (product) ->
  product.orders().all(cached: true)
 
  product.orders().toArray()

There are a number of methods defined for singular associations (hasOne, belongsTo) as well:

order = Order.build()
order.product()       # read locally 
order.loadProduct()   # read persisted 
order.assignProduct() # assign locally 
order.updateProduct() # persist assignment 
order.buildProduct()  # local construction 
order.createProduct() # persist construction 

You should never make a direct assignment like product=, because ActiveResource is not aware when this happens and it may cause unexpected results.

---

• Reflections on associations

Order.reflectOnAllAssociations().each (reflection) ->
  reflection.name # == 'product' 
  reflection.macro # == 'belongsTo' 
  reflection.klass() # == Product 
 
Order.reflectOnAssociation('product')

---

• Attribute management

order = Order.build()
 
order.assignAttributes(price: 5.0)
order.attributes() # == { price: 5.0 } 

---

• Better typing, constantizing, module mixins than Javascript alone

Order.build().isA(Order) # == true 
Order.build().isA(Product) # == false 
 
Order.build().klass() # == Order 

class MyLibrary.Order extends MyLibrary.Base
  this.className = 'Order'
 
MyLibrary.constantize('Order') # == MyLibrary.Order 

class MyModule
  @method1: ->
 
class Order extends MyLibrary.Base
  ActiveResource.extend(this, MyModule)
 
Order.method1 # defined 
 
class Product extends MyLibrary.Base
  ActiveResource.include(this, MyModule)
 
Order.build().method1 # defined 

---

• A wrapper class for Array that is similar to Ruby Array functionality

c = ActiveResource::Collection.build([product1, product2])
 
c.all()
c.toArray()
c.size()
c.empty()
c.include(item)
c.first(n)
c.last(n)
c.each (i) -> ...
c.inject {}, (h, i) -> ...
c.map (i) -> ...
c.compact()
c.flatten()
c.join()
c.push(items)
c.delete(items)
c.clear()
c.select (i) -> ...
c.detect (i) -> ...

These make use of Underscore.js. Learn more

This is the class that will be returned from Relation#all(), etc.

---

• Customization through properties/options on the library itself, as well as base classes and associations:

ResourceLibrary.baseUrl

ActiveResource.createResourceLibrary(
  'http://example.com/api/v1'
)

This property is required. It specifies the root URL to the resource server, and all requests for resources in the library will be made relative to this URL.

ResourceLibrary.headers

ActiveResource.createResourceLibrary(
  headers: {
    'Authorization': 'Basic xxx'
  }
)

This property is optional. It specifies any headers that should be added to every request for resources in the library. The most obvious use case is providing an Authorization header if your resource server requires authentication.

ResourceLibrary.constantizeScope

MyLibrary = ActiveResource.createResourceLibrary(
  constantizeScope: window
)
 
class window.Product extends MyLibrary.Base
  this.className = 'Product'
 
MyLibrary.constantize('Product') # == window.Product 

This property is optional, and defaults to null. It specifies the object to search properties of when looking up a class name to find a class constant. If null, ActiveResource will search both MyLibrary and MyLibrary::, if your resource library variable were named MyLibrary.

ResourceLibrary.interface

ActiveResource.createResourceLibrary(
  interface: MyCustomInterface
)

This property is optional and defaults to ActiveResource.Interfaces.JsonApi. Interfaces allow you to define the interface between a server and ActiveResource, constructing requests from input data, and constructing objects from response data. Right now, the only interface that is supported is JsonApi, which is in accordance with the JSON API specification.

Base.className

class Product extends MyLibrary.Base
  this.className = 'Product'

This property is required. It is so the library will continue to work in minified environments, where a call to constructor.name might yield a random result instead of the intended class name.

Base.queryName

class Product extends MyLibrary.Base
  this.queryName = 'products'

This property is required. This is the name that will be used in URLs, so a call like Product.all() will result in an HTTP request GET /api/v1/products

Base.primaryKey

class Product extends MyLibrary.Base
  this.primaryKey = 'token'

This property is optional. It tells ActiveResource which property in a response object is the primaryKey of the resource being returned, as well as telling ActiveResource which key to use when making foreign key assignments

Association.className

class Product extends MyLibrary.Base
  @hasMany 'specialOrders', className: 'Order'
 
class Order extends MyLibrary.Base
  @belongsTo 'product'

This option allows you to name an association by one name, but have that association refer to an existing class of a different name

Association.as && Association.polymorphic

class Product extends MyLibrary.Base
  @hasMany 'orders', as: 'resource'
 
class Store extends MyLibrary.Base
  @hasMany 'orders', as: 'resource'
 
class Order extends MyLibrary.Base
  @belongsTo 'resource', polymorphic: true

These options work together to allow for polymorphic associations between models.

Association.inverseOf

class Product extends MyLibrary.Base
  @hasMany 'orders', inverseOf: 'product'
 
class Order extends MyLibrary.Base
  @belongsTo 'product', inverseOf: 'orders'

This option allows you to define the inverse of an association on a class. Typically, this is done automatically, but there are cases, like polymorphic relationships, where this cannot be done automatically, and it is extremely useful and highly recommended to provide inverseOf in those instances.

Association.foreignKey

class Product extends MyLibrary.Base
  @hasMany 'orders', foreignKey: 'ownerProductId'
 
class Order extends MyLibrary.Base
  @belongsTo 'ownerProduct', className: 'Product'
 
Product.first()
.then (product) ->
  order = product.orders().build() # order.ownerProductId == product.id 

This option allows you to define the foreign key that is set on a child association (belongsTo) when assignments/constructions are made.

Association.primaryKey

class Product extends MyLibrary.Base
  @hasMany 'orders', primaryKey: 'token', foreignKey: 'ownerProductId'
 
class Order extends MyLibrary.Base
  @belongsTo 'ownerProduct', className: 'Product'
 
Product.first()
.then (product) ->
  order = product.orders().build() # order.ownerProductId == product.token 

This option allows you to define the primary key of the parent association that is assigned as the foreign key to the child association when assignments/constructions are made.

Association.autosave

class Order extends MyLibrary.Base
  @hasMany 'orderItems', autosave: true
 
class OrderItem extends MyLibrary.Base
  @belongsTo 'order'
 
order = Order.build(orderItems: [OrderItem.build(amount: 5.0)])
order.save() # sends orderItems attributes to server too 

This option allows you to specify that associated object(s) of a resource should be saved when the resource itself is saved.