Use

A Set is a plain JavaScript object used to represent a set of data usually sent to the server to fetch a list of records. For example, a list of all completed todos might be represented by:

{complete: true}

This set might be passed to getList like:

Todo.getList({complete: true})

An Algebra is used to detail the behavior of these sets, often using already provided props comparators:

var todoAlgebra = new set.Algebra(
  set.props.boolean("complete"),
  set.props.id("_id")
);

Using an algebra, all sorts of special behaviors can be performed. For example, if we already loaded the incomplete todos ({complete: false}) and wanted to load all todos ({}), we could use a set difference to figure out how to load only the data that hasn't been loaded.

todoAlgebra.difference( {}, { complete: false } ); //-> {complete: true}

These algebra's are typically used internally by either can-connect or can-fixture to provide these special behaviors:

const cacheConnection = connect( [
    require( "can-connect/data/memory-cache/memory-cache" )
], {
    algebra: todoAlgebra
} );

const todoConnection = connect( [
    require( "can-connect/data/url/url" ),
    require( "can-connect/cache-requests/cache-requests" )
], {
    cacheConnection: cacheConnection,
    url: "/todos",
    algebra: todoAlgebra
} );

const todoStore = fixture.store( [
    { _id: 1, name: "Do the dishes", complete: true },
    { _id: 2, name: "Walk the dog", complete: false }
],
todoAlgebra );

fixture( "/todos/{_id}", todoStore );

The best way to think about can-set is that its a way to detail the behavior of your service layer so other utilities can benefit.

Solving Common Issues

Configuring the proper set.Algebra can be tricky. The best way to make sure you have things working is to create an algebra and make sure some of the basics work.

The most common problem is that your algebra isn't configured to know what instance data belongs in which set.

For example, {id: 1, name: "do dishes"} should belong to the set {sort: "name asc"}, but it doesn't:

const algebra = new set.Algebra();
algebra.has( { sort: "name asc" }, { id: 1, name: "do dishes" } ); //-> false

The fix is to either ignore sort like:

const algebra = new set.Algebra( {
    sort: function() {
        return true;
    }
} );
algebra.has( { sort: "name asc" }, { id: 1, name: "do dishes" } ); //-> false

Or even better, make sort actually able to understand sorting:

const algebra = new set.Algebra(
    set.props.sort( "sort" )
);
algebra.has( { sort: "name asc" }, { id: 1, name: "do dishes" } ); //-> true

Similarly, you can verify that getSubset works. The following, with a default algebra gives the wrong results:

const algebra = new set.Algebra();
algebra.getSubset(
    { offset: 1, limit: 2 },
    {},
    [
        { id: 1, name: "do dishes" },
        { id: 2, name: "mow lawn" },
        { id: 3, name: "trash" }
    ]
); //-> []

This is because it's looking for instance data where offset===1 and limit===2. Again, you can teach your algebra what to do with these properties like:

const algebra = new set.Algebra(
    set.props.offsetLimit( "offset", "limit" )
);
algebra.getSubset(
    { offset: 1, limit: 2 },
    {},
    [
        { id: 1, name: "do dishes" },
        { id: 2, name: "mow lawn" },
        { id: 3, name: "trash" }
    ]
); //-> [
//  {id: 2, name: "mow lawn"},
// {id: 3, name: "trash"}
// ]