Collection

Collections represent arrays of models. They are returned by a hasMany association, or by one of the ModelClass query methods:

let posts = user.blogPosts;
let posts = schema.blogPosts.all();
let posts = schema.blogPosts.find([1, 2, 4]);
let posts = schema.blogPosts.where({ published: true });

Note that there is also a PolymorphicCollection class that is identical to Collection, except it can contain a heterogeneous array of models. Thus, it has no modelName property. This lets serializers and other parts of the system interact with it differently.

Properties

length: Integer

The number of models in the collection.

user.posts.length; // 2

modelName: String

The dasherized model name this Collection represents.

let posts = user.blogPosts;

posts.modelName; // "blog-post"

The model name is separate from the actual models, since Collections can be empty.

models: Array

The underlying plain JavaScript array of Models in this Collection.

posts.models // [ post:1, post:2, ... ]

While Collections have many array-ish methods like filter and sort, it can be useful to work with the plain array if you want to work with methods like map, or use the [] accessor.

For example, in testing you might want to assert against a model from the collection:

let newPost = user.posts.models[0].title;

assert.equal(newPost, "My first post");

Methods

add(model: Model): any

Adds a model to this collection.

posts.length; // 1

posts.add(newPost);

posts.length; // 2

destroy(): any

Destroys the db record for all models in the collection.

let posts = user.blogPosts;

posts.destroy(); // all posts removed from db

filter(f: Function): Collection

Returns a new Collection with its models filtered according to the provided callback function.

let publishedPosts = user.posts.filter(post => post.isPublished);

includes(): Boolean

Checks if the Collection includes the given model.

posts.includes(newPost);

Works by checking if the given model name and id exists in the Collection, making it a bit more flexible than strict object equality.

let post = server.create('post');
let programming = server.create('tag', { text: 'Programming' });

visit(`/posts/${post.id}`);
click('.tag-selector');
click('.tag:contains(Programming)');

post.reload();
assert.ok(post.tags.includes(programming));

mergeCollection(collection: Collection): any

Modifies the Collection by merging the models from another collection.

user.posts.mergeCollection(newPosts);
user.posts.save();

reload(): any

Reloads each model in the collection.

let posts = author.blogPosts;

// ...

posts.reload(); // reloads data for each post from the db

remove(model: Model): any

Removes a model from this collection.

posts.length; // 5

let firstPost = posts.models[0];
posts.remove(firstPost);
posts.save();

posts.length; // 4

save(): any

Saves all models in the collection.

let posts = user.blogPosts;

posts.models[0].published = true;

posts.save(); // all posts saved to db

slice(begin: Integer, end: Integer): Collection

Returns a new Collection with a subset of its models selected from begin to end.

let firstThreePosts = user.posts.slice(0, 3);

sort(f: Function): Collection

Returns a new Collection with its models sorted according to the provided compare function.

let postsByTitleAsc = user.posts.sort((a, b) => {
  return b.title < a.title;
});

toString(): String

Simple string representation of the collection and id.

user.posts.toString(); // collection:post(post:1,post:4)

update(key: any, val: any): any

Updates each model in the collection, and immediately persists all changes to the db.

let posts = user.blogPosts;

posts.update('published', true); // the db was updated for all posts

Association