Introduction

CanJS provides several convenient ways of creating service layer interfaces (i.e connections) for your data models (i.e Lists & Maps). These include can-rest-model, can-realtime-rest-model and can-super-model. Underneath the surface, these are all just pre-defined sets of the building blocks of can-connect, behaviors.

These pre-defined sets of built-in behaviors can be configured to cover many use cases, but developers may need to modify their service integrations more extensively than what's possible with configuration alone. This could be to add new features or integrate with unusual backends not supported by the included behaviors. Deep customization of this sort is accomplished by creating connections that include new custom behaviors. Custom behaviors may extend or replace the functionality of built-in behaviors. Consequently, authors of custom behaviors need to have good knowledge of the functionality provided by existing behaviors and the points of interaction between them.

This guide covers the knowledge you need to write your own custom behaviors:

• how to implement behaviors, the layers of a connection
• the importance of behavior ordering
• the interfaces and their interface methods, the extension points used to implement behaviors

Interfaces Overview

Interfaces in can-connect refer to categorizations of related methods that may be implemented by a behavior. These methods define how the layers (behaviors) of can-connect interact with each other, and the public API of the connection. As an example, the can-connect "Data Interface" is made up of methods like the following:

Essentially, interfaces are a loose specification of shared "extension points" that are used in the implementation of behaviors. For example, the following shows two behaviors that implement the same extension point differently; one using XHR, another using fetch:

import { connect } from "//unpkg.com/can@6/core.mjs";

// two behaviors that implement the `getListData` method of the `Data Interface`

const xhrData = connect.behavior('xhr-data', (previousPrototype) => {
    return {
        getListData() {
            return new Promise((resolve, reject) => {
                const request = new XMLHttpRequest();
                request.addEventListener("load", function() {
                    resolve(JSON.parse(this.responseText));
                });
                request.open("GET", this.url);
                request.send();
            });
        }
        // ... an actual DataInterface implementation would also implement:
        //     getData, createData, updateData, destroyData
    };
});

const fetchData = connect.behavior(
    'fetch-data',
    (previousPrototype) => {
        return {
            getListData() {
                return fetch(this.url).then(response => response.json());
            }
            // ... an actual DataInterface implementation would also implement:
            //     getData, createData, updateData, destroyData
        };
    }
);

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/',
};

const xhrConn = xhrData(connectionOptions);
const fetchConn = fetchData(connectionOptions);

xhrConn.getListData({}).then(data =>
    console.log(`Used XHR to load ${data.length} todos.`)
);
fetchConn.getListData({}).then(data =>
    console.log(`Used fetch to load ${data.length} todos.`)
);

Considering interfaces are just potential points of extension, an entire interface doesn't need to be implemented for a connection to function. For example, getQueries isn’t implemented by data/url. Behaviors implement parts of an interface.

As an example of how interfaces are used as extension points, the Data Interface defines ~20 methods, but the data/url behavior only implements 5 of them. getListData is one of those 5 methods and its implementation simply makes an HTTP request. The other behaviors in a connection might extend data/url's getListData, possibly to add request combining or request caching. Alternatively, other behaviors may implement methods from another interface which consume getListData. A common scenario would be getList from the Instance Interface, whose implementation would call the getListData implementation of this connection.

Behaviors Overview

Behaviors are the "layers" of can-connect connections. A connection is an object with a prototype chain made of behavior instances. The default export of behavior modules are "object extension functions" that add an instance of the behavior to the prototype chain of the passed object instance, and by chaining these functions, connections are built:

import { connect, QueryLogic } from "//unpkg.com/can@6/core.mjs";

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/{id}',
    queryLogic: new QueryLogic({ identity: ["id"] }),
};

const baseInstance = connect.base(connectionOptions);
const dataUrlInstance = connect.dataUrl(base);
const connection = connect.dataCombineRequests(dataUrl);
connection.init();

// connection prototype chain is made up of the behavior instances
console.log(
    `First proto: ${connection.__proto__ === dataUrlInstance}`
);
console.log(
    `Second proto: ${connection.__proto__.__proto__ === baseInstance}`
);
console.log(
    `Third proto: ${connection.__proto__.__proto__.__proto__ === connectionOptions}`
);

connection.getData({id: 5}).then((result) => {
    console.log(`Fetched Todo JSON: `, result);
});

Illustrating the prototype chain in the example above:

Behaviors can be:

• Implementers: simply implementing interface methods
• Consumers: using interface methods provided by other behaviors
• Extenders: adding to other behavior's implementations of interface methods

To be a method implementer, a behavior just needs to include that method as part of their definition. The following implements getListData:

import { connect } from "//unpkg.com/can@6/core.mjs";

// a behavior that implements the `getListData` method of the `Data Interface`
const fetchData = connect.behavior(
    'fetch-data',
    (previousPrototype) => {
        return {
            getListData() {
                return fetch(this.url).then(response => response.json());
            }
            // ... a complete Data Interface implementation would also implement:
            //     getData, createData, updateData, destroyData
        };
    }
);

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/',
};

const fetchConn = fetchData(connectionOptions);

fetchConn.getListData({}).then(data =>
    console.log(`Used fetch to load ${data.length} todos.`)
);

Being a method consumer just means calling a method on the connection. Here the behavior is consuming the getData method:

import { ObservableObject, QueryLogic, connect } from "//unpkg.com/can@6/core.mjs";

class Todo extends ObservableObject {
  static props = {
    id: {
      identity: true,
      type: Number
    },
    userId: Number,
    title: String,
    completed: Boolean,
    lastAccessedDate: String,
  }
}

// a behavior that implements the `getList` method of the `Instance Interface`,
// consumes from `getListData`
const todoConstructor = connect.behavior(
    'todo-constructor',
    (previousPrototype) => {
        return {
            get(query) {
                return this.getData(query).then((data) => new Todo(data));
            }
            // ... an actual Instance Interface implementation would also implement:
            //     getList, destroy, save & update
        };
    }
);

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/{id}',
    queryLogic: new QueryLogic(Todo)
};

const connection = todoConstructor(connect.dataUrl(connect.base(
    connectionOptions
)));
connection.init();

connection.get({id: 5}).then((result) => {
    console.log(`Fetched A Todo: `, result);
});

Extending is a bit more complicated. Property access on a connection works like any ordinary JavaScript object, the property is first searched for on the "base" object instance, before searching up the objects on the base object's prototype chain. Since behaviors are instances on that chain, a behavior can override an implementation of a method from a behavior higher in the prototype chain. That feature, with behaviors being able to reference the prototype higher than them in the chain, is what allows them to extend interface methods. This is done by overriding a method and calling the previous implementation as part of that overriding implementation. The following extends getData to add some logging:

import { ObservableObject, QueryLogic, connect } from "//unpkg.com/can@6/core.mjs";

class Todo extends ObservableObject {
  static props = {
    id: {
      identity: true,
      type: Number
    },
    userId: Number,
    title: String,
    completed: Boolean,
    lastAccessedDate: String,
  }
}

// a behavior that extends the `getData` method of the `Data Interface`, to add
// logging whenever a single instance is loaded
const loggingBehavior = connect.behavior(
    'data-logging',
    (previousPrototype) => {
        return {
            getData(query) {
                return previousPrototype.getData(query).then((data) => {
                    console.log(
                        `Successfully fetched ${this.Map.shortName} ${this.id(data)} data from server.`
                    );
                    return data;
                });
            }
        };
    }
);

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/{id}',
    queryLogic: new QueryLogic(Todo),
    ObjectType: Todo,
};

const connection = connect.constructor(loggingBehavior(connect.dataUrl(connect.base(
    connectionOptions
))));
connection.init();

connection.get({id: 5}).then((instance) => {
    document.body.innerText = JSON.stringify(instance, null, 4);
});

Calling From Root vs Calling On Previous Behavior

As we've explained, extender and consumers both make calls to interface methods within the connection, but there's a distinction regarding how they make those calls that's worth highlighting. Typically when consumers call an interface method they call it on the connection object, which looks like this.getData(). That causes a lookup for getData starting at the "root" of the connection prototype chain. In contrast, when an extender calls the method they're extending, they call it on the behavior above them in the prototype chain e.g previousBehavior.getData(). This causes a lookup on the portion of the prototype chain higher than the current behavior.

Interface Index

A listing of the interfaces of can-connect and their most commonly used methods:

Built-In Behavior Index

A listing of the behaviors provided by can-connect and a short description of their functionality:

Ordering Behaviors

When placing a custom behavior in the prototype chain it's important to know what interface methods you intend to implement and those you intend to extend. You may not be the only implementer of a method and for your implementation to be executed, your behavior will need to be lower in the prototype chain. When extending an interface method you may want your extension to run before all other extensions, after all extensions, or at some point between particular extensions. Behaviors lower in the chain execute before extensions higher in the chain.

The built-in behaviors of can-connect have a canonical order to ensure they function. Understanding this order may help you better understand where your custom behavior should be ordered:

Combining Behaviors

The combining of behaviors by chaining functions (as shown in the Behaviors Overview) is very straightforward but can be tedious to read when combining many behaviors. can-connect offers the connect function to assemble behaviors, but to make it clearer to users how connections are assembled we now suggest that users deviating from the pre-built connections (e.g can-rest-model) assemble their behaviors themselves.

One way behaviors can be assembled cleanly is by using the reduce method of arrays which iterates over the elements of an array, assembling a result:

Note: the init function must be called after creating the connection to initialize some behaviors. When using the connect function this is called automatically.

import { ObservableObject, QueryLogic, connect } from "//unpkg.com/can@6/core.mjs";

class Todo extends ObservableObject {
  static props = {
    id: {
      identity: true,
      type: Number
    },
    userId: Number,
    title: String,
    completed: Boolean,
    lastAccessedDate: String,
  }
}

const behaviors = [
    connect.base,
    connect.dataUrl,
    connect.dataParse,
    connect.constructor,
];

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/{id}',
    queryLogic: new QueryLogic(Todo)
};

const connection = behaviors.reduce(
    (connection, behavior) => behavior(connection),
    connectionOptions
);
connection.init();

connection.get({id: 5}).then((result) => {
    console.log(`Fetched A Todo: `, result);
});

Practical Custom Behavior Examples

As a demo of the concepts shown above, below are examples of custom behaviors that add functionality via behavior implementation, consumption, and extension.

Fetch-based data/url

The following is an implementer behavior that implements the same functionality as the data/url behavior, but using the newer fetch API rather than the XHR API. This behavior may be useful if you want a feature fetch offers, like the ability to abort a request.

import { connect, key } from "//unpkg.com/can@6/core.mjs";

function _getRequestURLAndMethod(connUrl, requestName, params) {
    let url = null;
    let method = null;

    if (connUrl[requestName]) {
        [method, url] = connUrl[requestName].split(/ (.+)/);
    } else {
        switch(requestName) {
            case 'getListData':
                url = connUrl;
                method = 'GET';
                break;
            case 'createData':
                url = connUrl;
                method = 'POST';
                break;
            case 'getData':
                url = connUrl+"/{id}";
                method = 'GET';
                break;
            case 'updateData':
                url = connUrl+"/{id}";
                method = 'PUT';
                break;
            case 'destroyData':
                url = connUrl+"/{id}";
                method = 'DELETE';
                break;
        }
    }

    url = key.replaceWith(url, params, (key, value) => encodeURIComponent(value), true);

    return { url, method };
}

function _makeFetchRequest({ url, method }, params) {
    return fetch(url, {
        method,
        credentials: 'same-origin',
        body: method !== 'GET' ? JSON.stringify(params) : undefined,
        headers: {
            'Content-Type': 'application/json'
        }
    }).then(
        response => {
            if (response.ok) {
                return response.json();
            } else {
                throw new Error(`Server did not produce a successful response code: ${response.status}`);
            }
        },
        error => {
            console.log('There has been a network error during fetch execution: ', error.message);
        }
    );
}

const fetchData = connect.behavior(
    'fetch-data',
    () => {
        return {
            getListData(params) {
                return _makeFetchRequest(
                    _getRequestURLAndMethod(this.url, 'getListData', params),
                    params
                );
            },
            getData(params) {
                return _makeFetchRequest(
                    _getRequestURLAndMethod(this.url, 'getData', params),
                    params
                );
            },
            createData(params) {
                return _makeFetchRequest(
                    _getRequestURLAndMethod(this.url, 'createData', params),
                    params
                );
            },
            updateData(params) {
                return _makeFetchRequest(
                    _getRequestURLAndMethod(this.url, 'updateData', params),
                    params
                );
            },
            destroyData(params) {
                return _makeFetchRequest(
                    _getRequestURLAndMethod(this.url, 'destroyData', params),
                    params
                );
            },
        };
    }
);

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos',
};

const fetchConn = fetchData(connectionOptions);

fetchConn.getListData({}).then(data =>
    console.log(`Used fetch to load ${data.length} todos.`)
);

WebSocket update channel

The following is a consumer behavior that uses the API of real-time to allow real-time updates of models from a web socket connection. A behavior like this may be useful if your API allows you to subscribe via WebSocket to receive notifications of changes to models.

<script type="module">
    import { connect, ObservableObject, QueryLogic, realtimeRestModel, stache, type } from "//unpkg.com/can@6/everything.mjs";

    class Todo extends ObservableObject {
        static get props() {
            return {
                id: {
                    identity: true,
                    type: type.maybeConvert(Number)
                },
                userId: type.maybeConvert(Number),
                title: type.maybeConvert(String),
                completed: type.maybeConvert(Boolean)
            };
        }
    }

    const websocketSidechannel = connect.behavior('websocket-sidechannel', (previousPrototype) => {
        return {
            init() {
                // start listening to websocket when connection is built
                this.websocket.onmessage(({data}) => {
                    // merge partial instance from websocket with existing data
                    const mergedData = Object.assign(this.instanceStore.get(data.id), data);
                    this.updateInstance(mergedData);
                });
                previousPrototype.init();
            },
        }
    });

    // an object taking the place of an open websocket for the purpose of this test
    // receives a message updating a todo as completed every 3 seconds, starting
    //  from the first todo
    const mockWebsocket = {
        id: 1,
        onmessage(listener) {
            setInterval(() => {
                // send a message completing a todo 3 seconds
                listener({ data: { id: this.id, completed: true }});
                this.id = this.id + 1;
            }, 3000);
        }
    };

    const template = stache(`
        {{# for(todo of this.todos)}}
        <li>{{todo.title}} - {{todo.completed}}</li>
        {{/ for}}
    `);

    const connectionOptions = {
        url: 'https://jsonplaceholder.typicode.com/todos/',
        queryLogic: new QueryLogic(Todo),
        ObjectType: Todo,
        websocket: mockWebsocket,
    };
    const connection = websocketSidechannel(realtimeRestModel(connectionOptions));
    connection.init();

    connection.getList({}).then((todos) => {
        document.getElementById('todos').appendChild(template({todos}));
    });
</script>
<ul id="todos"></ul>

Auto-updating Field

The following is a extender behavior that extends the createdInstance callbacks to update instances with a "last viewed" time.

import { connect, restModel, QueryLogic, ObservableObject } from "//unpkg.com/can@6/core.mjs";

class Todo extends ObservableObject {
  static props = {
    id: {
      identity: true,
      type: Number
    },
    userId: Number,
    title: String,
    completed: Boolean,
    lastAccessedDate: String,
  }
}

const updateLastAccessed = connect.behavior(
    'update-last-accessed',
    (previousBehavior) => {
        function updateLastAccessed(instance) {
            instance.lastAccessedDate = new Date().toISOString();
            instance.save().then(() => console.log('Updated last accessed time for: ', instance));
        };

        return {
            get() {
                return previousBehavior.get.apply(this, arguments).then((instance) => {
                    updateLastAccessed(instance);
                    return instance;
                });
            },
            getList() {
                return previousBehavior.getList.apply(this, arguments).then((list) => {
                    list.forEach((instance) => updateLastAccessed(instance));
                    return list;
                });
            },
        };
    }
);

const connectionOptions = {
    url: 'https://jsonplaceholder.typicode.com/todos/',
    queryLogic: new QueryLogic(Todo),
    ObjectType: Todo,
};

const connection = updateLastAccessed(restModel(connectionOptions));

connection.getList({}).then(data =>
    console.log(`Loaded ${data.length} todos.`)
);

A Review of instance.save Execution

To illustrate the interactions between a connection's behaviors we're going to trace the execution of the most typical way of persisting a model. That is calling the save method on an instance of a CanJS Map that's been passed as the Map option to a connection; in this case a connection created by can-rest-model. The behaviors in can-rest-model are:

1. data/url
2. data/parse
3. constructor
4. can/map

We'll show how the instance methods of these behaviors interact to produce the final results and maintain the state of the connection:

Illustration Slides

Step-by-step Explanation