Naming :

Hydration :

Providing a Resource to a PartialItem. So a Hydrator has an attribute "target" and will only interact with that target.

Irrigation :

Providing a Resource to a bunch of PartialItems. Contrary to Hydrators, Irrigators doesn't have a target and will instead provide Resources to every PartialItems that are interested.

Introduction :

A PartialObj is a wrapper around an object. It represents an object that is not "finished".

What is an unfinished object :

In short, an object is considered as "unfinished" if some of its attributes contains some objects that are themselves unfinished OR contains some objects that doesn't even exist yet (only a string to refer to an object).

So in reality, an object is unfinished if it contains any unfinished Field (a Field is representation of a single attribute of a PartialObj). A Field is unfinished if it contains an object that it itself unfinished OR if it only contains a Reference to an object (explained later).

Hydrator :

The purpose of a Hydrator is to provide some Resources to a set of PartialObjs and/or PartialLists. You should use the class Hydrator to create a new Hydrator. Classes named "RestrictedHydrator", "HydrationsManager" and "VersatileHydrator" are utilities used by the parent class Hydrator.

Do not manually provide Resources to PartialObjs :

You should not ever manually provide Resources to a PartialObj. Instead, always use an instance of Hydrator.

Specific cases and default patterns :

Transform a Rough-Resource into a Resource :

Some methods of Hydrator to provide Rough-Resources will automatically upgrade those Roughs to Resources when possible. To do so, the default pattern is to replace the Rough Resource by a Resource whose value equal to Rough.core.

However, that might not be the expected pattern. Most likely if you want your Resource to be typed instances. In that case you should do stuff in a more imperative approach :

• Create you PartialObj

Mutable PartialObj vs Static PartialObj :

A PartialObj is considered as mutable if some fields might be added to it. While it's mutable, checking its status is never relevant (while it can change if some new fields are added to it). A PartialObj doesn't have any attribute to define it as mutable. This is defined when you add it to a Hydrator by calling the method addMutablePartialObj. You can then use the method freezeMutablePartialObj to define that it's not mutable anymore.

ProgressiveAsset :

It can be tedious to manage PartialObj that are used as Rough Resource. You might want to replace that Rough Resource by a Plain Resource when the PartialObj is fulfilled. You so need to add a listener for upgrades of the PartialObj to remove the previous Rough Resource. Maybe you want your Plain Resource to be typed. You so need to add some extra stuff in you upgrade callback. Using ProgressiveAsset is a utility to really simplify and abstract the work when you want to use a PartialObj as a Resource. It's named progressive because we expect it to become a Plain Resource.