Overview

The can-connect module exports a connect function that is used to assemble different behaviors (plugins)
and some configuration options into a connection. For example, the following uses connect and the
constructor/constructor and data/url behaviors
to create a todoConnection connection:

A typical connection provides the ability to create, read, update, or delete (CRUD) data hosted by some data
source. Those operations are usually performed via the connection InstanceInterface
methods:

Behavior Configuration

Whenever connect creates a connection, it always adds the base behavior.
This behavior is where the configuration options passed to connect are stored and it also defines
several configurable options that are used by most other behaviors. For example, if your backend
uses a property named _id to uniquely identify todos, you can specify this with
idProp like:

Behaviors list their configurable options in their own documentation pages.

Behavior Overwriting

If the configuration options available for a behavior are not enough, it's possible to overwrite any
behavior with your own behavior.

For example, constructor/constructor’s
updatedInstance method sets the instance’s
properties to match the result of updateData. But if the
PUT /api/todos/5 {name:"take out garbage""} request returns {}, the following example would
result in a todo with only an id property:

Both the above connections contain the constructor/store behavior.
This means when you create a binding to a Todo or Todo.List instance, they will automatically
call constructor/store.addInstanceReference
or constructor/store.addListReference.
constructor/store then retains the instance for the life
of the binding and ensures only single shared instance of a particular piece of data exists. This
prevents a common programming problem where multiple copies of an instance are held by parts of
an application that loaded the same data.

Other use

Integrating can-connect with another framework is typically pretty easy. In general, the pattern involves creating
a behavior that integrates with your framework’s observable instances. The can/map behavior
can serve as a good guide. You’ll typically want to implement the following methods in your behavior:

.createdInstance - Update an instance with data returned from createData.
.updatedInstance - Update an instance with data returned from updateData.
.destroyedInstance - Update an instance with data returned from destroyData.
.updatedList - Update a list with raw data.

And, in most frameworks you know when a particular observable is being used, typically
observed, and when it can be discarded. In those places, you should call:

Interfaces

The following is a list of the primary interface methods and properties implemented or consumed by the core behaviors.

Identifiers

.id( props | instance ) -> String - Returns a unique identifier for the instance or raw data..idProp -> String="id" - The name of the unique identifier property..listSet(list) -> set - Returns the set a list represents..listSetProp -> String="__listSet" - The property on a List that contains its set.

Instance Callbacks

.createdInstance(instance, props) - Called whenever an instance is created..updatedInstance(instance, props) - Called whenever an instance is updated..destroyedInstance(instance, props) - Called whenever an instance is destroyed..updatedList(list, updatedListData, set) - Called whenever a list has been updated.

Hydrators and Serializers

.instance(props) -> Instance - Create an instance given raw data..list({data: Array<Instance>}) -> List - Create a list given an array of instances..hydrateInstance(props) -> Instance - Provide an instance given raw data..hydrateList({ListData}, set) -> List - Provide a list given raw data..hydratedInstance(instance) - Called whenever an instance is created in memory..hydratedList(list, set) - Called whenever a list is created in memory..serializeInstance(instance) -> Object - Return the serialized form of an instance..serializeList(list) -> Array<Object> - Return the serialized form of a list and its instances.

Data Interface

The raw-data connection methods.

CRUD Methods

.getListData(set) -> Promise<ListData> - Retrieve list data..updateListData(listData[, set]) -> Promise<ListData> - Update a list’s data.
.getSets() -> Promise<Array<Set>> - Return the sets available to the connection, typically those stored in a cache connection..getData(params) -> Promise<Object> - Retrieve data for a particular item..createData(props, cid) -> Promise<props> - Create a data store record given the serialized form of the data. A
client ID is passed of the instance that is being created..updateData(props) -> Promise<props> - Update a data store record given the serialized form of the data..destroyData(props) -> Promise<props> - Delete a data store record given the serialized form of the data..clear() -> Promise - Clear all data in the connection. Typically used to remove all data from a cache connection.

Store Interface

.addInstanceReference(instance) - Add a reference to an instance so that multiple copies can be avoided..deleteInstanceReference(instance) - Remove a reference to an instance, freeing memory when an instance is no longer bound to.
.addListReference(list) - Add a reference to a list so that multiple copies can be avoided..deleteListReference(list) - Remove a reference to an list, freeing memory when a list is no longer bound to.

Real-time Methods

createInstance( props ) -> Promise<instance> - Inform the connection a new data record has been created.updateInstance( props ) -> Promise<instance> - Inform the connection a data record has been updated.destroyInstance( props ) -> Promise<instance> - Inform the connection a data record has been destroyed.