Introduction

A Group categorizes and preserves the ordering of structured data in a Collection. They allow us to cluster together data from a Collection as an array of primary Keys. A Group doesn't store the actual Items. It only keeps track of the primary Keys and retrieves the fitting Items from the Collection when needed.

// The actual Collection

Collection

data -> [Item('id1'), Item('id2'), Item('id10'), Item('id7'), Item('id5')]

// Group one which represetns the Collection in a specific order

Group1

value -> ['id1', 'id5', 'id7']

output -> [Item('id1'), Item('id5'), Item('id7')]

// Group two which represetns the Collection in another specific order

Group2

value -> ['id7', 'id1', 'id10']

output -> [Item('id7'), Item('id1'), Item('id10')]

We instantiate a Group with the help of an existing Collection. By doing so, the Group is automatically bound to the Collection it was created from and has access to its data. A Group can be created during the creation of a Collection in the configuration object.

const MY_COLLECTION = new Collection((collection) =>({

groups: {

groupName: collection.Group([/*initial Items*/])

}

}));

// or with the name

const MY_COLLECTION_2 = new Collection({

groups: ['groupName']

})

Or dynamically, after the Collection has been defined.

const MY_GROUP = MY_COLLECTION.createGroup("groupName", [/*initial Items*/]);

The Collection can have as many Groups as we want and won't lose its redundant behavior. This is due to the fact that each Item is stored in the Collection itself and not in the Group. You can imagine a Group like an interface to the Collection Data.

MY_COLLECTION.createGroup("group1", [1, 2, 3]);

MY_COLLECTION.createGroup("group2", [2, 5, 8]);

MY_COLLECTION.createGroup("group5000", [1, 10, 500, 5]);

The cool thing about Groups is that they are an extension of the State Class and offers the same powerful features.

MY_STATE.undo(); // Undo latest change

MY_GROUP.reset(); // Reset Group to its intial Value

MY_STATE.persist(); // Persist Group Value into Storage

But be aware that the value might not be the output you expect.

MY_GROUP.value; // Returns '[8, 5, 30, 1]'

In a Group, the value property manages the primaryKeys a Group represents. To get the Item Value to each primary Key, we use the output property.

MY_GROUP.output; // Returns '[{ id: 8, name: 'jeff' }, ...]'

If you want to find out more about specific methods of the Group, checkout the Methods Section. Most methods we use to modify, mutate and access the Group are chainable.

MY_GROUP.undo().add(1).watch(() => {}).reset().persist().undo().remove(1).replace(2, 3);

🔨 Use case

For instance, we can use a Group to cluster a Post Collection into User Posts of the logged-in user.

USERS.collect(user);

POSTS.collect(user.posts, user.id);

In the above code snippet, we have two Collections, one for users and another for posts. We can collect posts specific to a user and group them automatically by the user's id.

⛳️ Sandbox

Test the Group yourself. It's only one click away. Just select your preferred Framework below.

• React
• Vue (coming soon)
• Angular (coming soon)

📭 Props

initialItems

The itemKeys of the initial Items, the Group represents.

const MY_GROUP = MY_COLLECTION.createGroup([1, 2, 3]);

MY_GROUP.value; // Returns '[1, 2, 3]'

config

Beside the initial îtemKeys a Group takes an optional configuration object.

const MY_GROUP = MY_COLLECTION.createGroup([1, 2, 3], {

key: "myGroup",

});

Here is a Typescript Interface for quick reference. However, each property is explained in more detail below.

export interface GroupConfigInterface {

key?: GroupKey;

isPlaceholder?: boolean;

}

key

The optional property key/name should be a unique string/number to identify the Group later.

const MY_GROUP = MY_COLLECTION.createGroup([1, 2, 3], {

key: "myKey"

});

We recommend giving each Group a unique key, since it has only advantages:

• helps us during debug sessions
• makes it easier to identify the Collection
• no need for separate persist Key

Type	Default	Required
string \| number	undefined	No

isPlaceholder

🔥warning

This property is mainly thought for internal use.

Defines whether the Group is an placeholder or not.

const MY_GROUP = App.createGroup([1, 2, 3], {

isPlaceholder: true

});

MY_GROUP.exists(); // false

Groups are, for example, placeholder when AgileTs needs to hold a reference to them, although they aren't instantiated yet. This might be the case by using getGroupWithReference(), which returns a placeholder Group, if the Group doesn't exist, to hold a reference to it.

const myGroup = useAgile(MY_COLLECTION.getGroupWithReference("group1")); // Causes rerender if Group got created

const myGroup2 = useAgile(MY_COLLECTION.getGroup("group2")); // Doesn't Causes rerender if Group got created

This reference is essential to rerender the Component, whenever the Group got instantiated.

Type	Default	Required
boolean	false	No

🟦 Typescript

The Group Class is almost 100% typesafe.