Use

The constructor behavior allows you to instantiate the raw representation of the data source's data into a custom typed representation with additional methods and behaviors. An example might be loading data from a "/todos" service and being able to call .timeLeft() on the todos that you get back like:

todoConnection.get({id: 6}).then(function(todo){
  todo.timeLeft() //-> 60000
})

The following creates a todoConnection that does exactly that:

// require connection plugins
var constructor = require("can-connect/constructor/");
var dataUrl = require("can-connect/data/url/");

// define type constructor function
var Todo = function(data){
  // add passed properties to new instance
  for(var prop in data) {
   this[prop] = data;
  }
};

// add method to get time left before due, in milliseconds
Todo.prototype.timeLeft = function(){
  return new Date() - this.dueDate
};

// create connection, passing function to instantiate new instances
var todoConnection = connect([constuctor, dataUrl], {
  url: "/todos",
  instance: function(data){
    return new Todo(data);
  }
});

The constructor behavior is still useful even if you want to keep your data as untyped objects (which is the default behavior when no instance implementation is provided). The behavior provides an interface to the data held by the client. For example, updatedInstance provides an extension point for logic that needs to be executed after an instance held by the client finishes an update request. This is valuable whether that instance is typed or not. Extensions like real-time or fall-through-cache require this interface for advanced behavior.

Interface

constructor provides the following categories of methods to interact with typed data:

CRUD Methods

Methods that create, read, update and delete (CRUD) typed representations of raw connection data:

• get - retrieve a single typed instance from the data source
• getList - retrieve a typed list of instances from the data source
• save - save a typed instance's data to the data source
• destroy - delete a typed instance's data from the data source

CRUD Callbacks

"CRUD Methods" call these methods with request response data and a related instance. Their implementation here updates the related instance with that data:

• createdInstance - after saving new instance to data source, update that instance with response data
• updatedInstance - after saving existing instance to data source, update that instance with response data
• destroyedInstance - after deleting instance from data source, update that instance with response data
• updatedList - after new data is read from the data source, update an existing list with instances created from that data

Hydrators

These methods are used to create a typed instance or typed list given raw data objects:

• hydrateInstance - create a typed instance given raw instance data
• hydrateList - create a typed list of typed instances given given raw list data

Serializers

These methods convert a typed instance or typed list into a raw object:

• serializeInstance - return raw data representing the state of the typed instance argument
• serializeList - return raw data representing the state of the typed list argument