Collections

All Sutando methods that return more than one model result will return instances of the Collection class, including results retrieved via the get method or accessed via a relationship. The Sutando collection object extends collect.js collection, so it naturally inherits dozens of methods used to fluently work with the underlying array of Sutando models. Be sure to review the Laravel collection documentation to learn all about these helpful methods!

All collections also serve as iterators, allowing you to loop over them as if they were arrays:

const { User } = require('./models');
 
const users = await User.query().where('active', 1).get();

users.map(user => {
  console.log(user.name);
});
 
for (let user of users) {
  console.log(user.name);
}

However, as previously mentioned, collections are much more powerful than arrays and expose a variety of map / reduce operations that may be chained using an intuitive interface. For example, we may remove all inactive models and then gather the first name for each remaining user:

const names = (await User.query().all()).reject(user => {
  return user.active === false;
}).map(user => {
  return user.name;
});

Available Methods

All Sutando collections extend the base collect.js object; therefore, they inherit all of the powerful methods provided by the base collection class.

In addition, the Collection class provides a superset of methods to aid with managing your model collections. Most methods return Collection instances; however, some methods, like modelKeys, return an collect.js instance.

• contains
• diff
• except
• find
• fresh
• intersect
• load
• loadCount / loadMax / loadMin / loadSum / loadAvg
• modelKeys
• makeVisible
• makeHidden
• only
• toQuery
• unique
• toData
• toJson

contains(key, operator = null, value = null)

The contains method may be used to determine if a given model instance is contained by the collection. This method accepts a primary key or a model instance:

users.contains(1);

const user = await User.query().find(1);
users.contains(user);

diff(items)

The diff method returns all of the models that are not present in the given collection:

const otherUsers = await User.query().whereIn('id', [1, 2, 3]).get()
const diffUsers = users.diff(otherUsers);

except(keys)

The except method returns all of the models that do not have the given primary keys:

const exceptUsers = users.except([1, 2, 3]);

find(key)

The find method returns the model that has a primary key matching the given key. If key is a model instance, find will attempt to return a model matching the primary key. If key is an array of keys, find will return all models which have a primary key in the given array:

const users = await User.query().all();
 
const user = users.find(1);

fresh(with = [])

The fresh method retrieves a fresh instance of each model in the collection from the database. In addition, any specified relationships will be eager loaded:

const newUsers = await users.fresh();
 
const newUsers = await users.fresh('comments');

intersect(items)

The intersect method returns all of the models that are also present in the given collection:

const otherUsers = await User.query().whereIn('id', [1, 2, 3]).get();
const newUsers = users.intersect(otherUsers);

load(relations)

The load method eager loads the given relationships for all models in the collection:

await users.load(['comments', 'posts']);
 
await users.load('comments.author');

loadCount / loadMax / loadMin / loadSum / loadAvg

await users.loadCount(['comments', 'posts']);

await users.loadMax('posts', 'vote');

await users.loadMin('posts', 'vote');

await users.loadSum('posts', 'vote');

await users.loadAvg('posts', 'vote');

modelKeys()

The modelKeys method returns the primary keys for all models in the collection:

users.modelKeys();
 
// [1, 2, 3, 4, 5]

makeVisible(attributes)

The makeVisible method makes attributes visible that are typically "hidden" on each model in the collection:

const newUsers = users.makeVisible(['address', 'phone_number']);

makeHidden(attributes)

The makeHidden method hides attributes that are typically "visible" on each model in the collection:

const newUsers = users.makeHidden(['address', 'phone_number']);

only(keys)

The only method returns all of the models that have the given primary keys:

const newUsers = users.only([1, 2, 3]);

toQuery()

The toQuery method returns an query builder instance containing a whereIn constraint on the collection model's primary keys:

const { User } = require('./models');
 
const users = await User.query().where('status', 'VIP').get();
 
await users.toQuery().update([
  'status' => 'Administrator',
]);

unique(key = null, strict = false)

The unique method returns all of the unique models in the collection. Any models of the same type with the same primary key as another model in the collection are removed:

const newUsers = users.unique();

toData()

const users = await User.query().all();

return users.toData();

toJson()

const users = await User.query().all();

return users.toJson();