@olympeio/runtime-web 9.1.0-dev → 9.1.0

package/types/cloud.d.ts

@@ -7,87 +7,306 @@
 // @ts-ignore
 import Observable from 'rxjs';
 import {Context, CloudObject, Relation, Property, Tag, Class} from "./base";
-import { BrickContext } from './runtime';
+import {Brick, BrickContext} from './runtime';
 import {Color} from "./utils";
 
 // --------------------------
 // -- Primitive data types --
 // --------------------------
+/**
+ * A property model defines a property of a data type.
+ * A property is defined by its type and the model it defines a property for.
+ * */
 export class PropertyModel extends CloudObject {
+    /**
+     * Relation from the property model to the data type (model)
+     * to which that property is attached.
+     *
+     * Example:
+     *
+     * ` myNumberPropertyModel --definingModelRel-> myDataTypeObject`
+     */
     static definingModelRel: Relation<PropertyModel, CloudObject>;
+
+    /**
+     * Relation from the `PropertyModel` to its type.
+     *
+     * Example :
+     *
+     * `myNumberPropertyModel --typeRel-> Number`
+     */
     static typeRel: Relation<PropertyModel, CloudObject>;
 }
 
+/**
+ * A relation model defines a relation between two data types.
+ * It defines what data types is the origin and the destination of the relation.
+ *
+ * It also defines follow rules properties on the relation.
+ * */
 export class RelationModel extends CloudObject {
+    /**
+     * Relation from the origin data type to the RelationModel
+     * */
     static originModelRel: Relation<CloudObject, RelationModel>;
+    /**
+     * Relation from a RelationModel to the destination data type
+     * */
     static destinationModelRel: Relation<RelationModel, CloudObject>;
+    /**
+     * Property for the *dump* follow rule
+     */
     static dumpFollowRuleProp: Property<number>;
+    /**
+     * Property for the *delete* follow rule
+     */
     static deleteFollowRuleProp: Property<number>;
+    /**
+     * Property for the *runtime* follow rule
+     */
     static runtimeFollowRuleProp: Property<number>;
 }
 
+/**
+ * StringModel represents a {@link PropertyModel} for a string property of a data type.
+ */
 export class StringModel extends CloudObject {
     static valueProp: Property<string>;
 }
 
+/**
+ * NumberModel represents a {@link PropertyModel} for a number property of a data type.
+ */
 export class NumberModel extends CloudObject {
     static valueProp: Property<number>;
 }
 
+/**
+ * BooleanModel represents a {@link PropertyModel} for a boolean property of a data type.
+ */
 export class BooleanModel extends CloudObject {
     static valueProp: Property<boolean>;
 }
 
+/**
+ * DatetimeModel represents a {@link PropertyModel} for a datetime property of a data type.
+ */
 export class DatetimeModel extends CloudObject {
     static valueProp: Property<Date>;
 }
 
+/**
+ * ColorModel represents a {@link PropertyModel} for a color property of a data type.
+ */
 export class ColorModel extends CloudObject {
     static valueProp: Property<Color>;
 }
 
+/**
+ * File with content as binary or string data
+ */
 export class File extends CloudObject {
+
     static nameProp: Property<string>;
     static creationDateProp: Property<Date>;
     static modificationDateProp: Property<Date>;
     static mimeTypeProp: Property<string>;
     static urlProp: Property<string>;
+
+    /**
+     * Create a `File` from its content
+     *
+     * @param transaction transaction in which to create the file
+     * @param name filename
+     * @param content byte content of the file
+     * @param mimeType optional mime type of the file
+     * @param source optional source where file will be stored ('server', 'self' or DBConnector tag)
+     * @param tag optional tag for the file
+     * @return tag string of the file
+     */
     static createFromContent(transaction: Transaction, name: string, content: ArrayBuffer, mimeType?: string, source?: string, tag?: string): string;
+
+    /**
+     * Create a `File` from a specified URL
+     *
+     * @param transaction transaction in which to create the file
+     * @param name filename
+     * @param url url to retrieve content from
+     * @param mimeType optional mime type of the file
+     * @param source optional source where file will be stored ('server', 'self' or DBConnector tag)
+     * @param tag optional tag for the file
+     * @return tag string of the file
+     */
     static createFromURL(transaction: Transaction, name: string, url: string, mimeType?: string, source?: string, tag?: string): string;
 
+    /**
+     * Retrieve content from this file asynchronously
+     *
+     * @param onSuccess callback to execute when byte content has been retrieved successfully
+     * @param onFailure callback to execute when content retrieval has failed
+     */
     getContentAsBinary(onSuccess: (content: ArrayBuffer) => void, onFailure?: (string) => void): void;
+
+    /**
+     * Retrieve string content from this file asynchronously
+     *
+     * @param onSuccess callback to execute when string content has been retrieved successfully
+     * @param onFailure callback to execute when content retrieval has failed
+     */
     getContentAsString(onSuccess: (content: string) => void, onFailure?: (string) => void): void;
+
+    /**
+     * Retrieve string content from URL asynchronously
+     *
+     * @param onSuccess callback to execute when content has been retrieved successfully
+     * @param onFailure callback to execute when content retrieval has failed
+     */
     getContentUrl(onSuccess: (content: string) => void, onFailure?: () => void): void;
+
+    /**
+     * Save this file with specified name
+     *
+     * @param name filename
+     */
     saveAs(name: string): void;
 }
 
+/**
+ * User object for authentication purposes
+ */
 export class User extends CloudObject {
     static loginProp: Property<string>;
     static saltProp: Property<string>;
     static verifierProp: Property<string>;
-    static SAMLNameIdProp: Property<string>;
+    static SAMLnameIdProp: Property<string>;
 }
 
+/**
+ * An Enum is an ordered list of string key-values mappings
+ */
 export class Enum extends CloudObject {
+    /**
+     * Create an empty `Enum?`  without any value
+     *
+     * See {@link EnumValue#createValue} to create values for an Enum.
+     *
+     * @param transaction transaction in which to create the Enum
+     * @param name optional name of the Enum
+     * @return string tag of the Enum object
+     */
     create(transaction: Transaction, name?: string): string;
+
+    /**
+     * Get the values defined for this `Enum`
+     */
     getValues(): QueryResult<EnumValue>;
 }
 
+/**
+ * An `EnumValue` is a single value part of an `Enum`.
+ * It has a `string` name, a rank (its position in the Enum list).
+ *
+ * The values for `EnumValue` are always stringified.
+ */
 export class EnumValue extends CloudObject {
+    /**
+     * Add a `EnumValue` to a specified `Enum`
+     *
+     * @param transaction transaction in which to add the EnumValue to the Enum
+     * @param enumModel `EnumModel` containing the specified `EnumValue`
+     * @param value value of the `EnumValue`
+     * @param name name of the `EnumValue`
+     * @param rank position of the `EnumValue` in the `Enum`
+     */
     static createValue(transaction: Transaction, enumModel: Tag, value: string, name?: string, rank?: number): string;
 
+    /**
+     * Name property for an EnumValue
+     */
     static nameProp: Property<string>;
+    /**
+     * Value property for an EnumValue
+     */
     static valueProp: Property<string>;
+    /**
+     * Rank property for an EnumValue
+     */
     static rankProp: Property<number>;
 }
 
+// -------------------------
+// -- Workflow data types --
+// -------------------------
+
+/**
+ * A `Workflow` is a sequence of {@link WorkflowState} in which instances of a model goes through.
+ * {@link WorkflowState} are linked by {@link WorkflowTransition} that can have an optional _process function_.
+ * The `Workflow` also historize the {@link WorkflowState} of the instance and optionally serialize the object itself in a {@link WorkflowObjectState}.
+ */
+export class Workflow extends CloudObject {
+    /** Is the instance serialization enabled or not */
+    static serializationEnabledProp: Property<boolean>;
+    /** The model to which the `Workflow` is associated */
+    static dataTypeRel: Relation<Workflow, CloudObject>;
+    /** The {@link WorkflowState} that are in the `Workflow` */
+    static statesRel: Relation<Workflow, WorkflowState>;
+    /** The initial {@link WorkflowState} of the `Workflow` */
+    static initialStateRel: Relation<Workflow, WorkflowState>;
+}
+
+/**
+ * A `WorkflowState` defines a state in a {@link Workflow}.
+ */
+export class WorkflowState extends CloudObject { /* empty */ }
+
+/**
+ * A `WorkflowTransition` defines a transition between 2 {@link WorkflowState}.
+ * It has a direction (`fromStateRel` to `toStateRel`) and can have an optional _process function_.
+ * The _process function_ (`processRefProp`) is automatically triggered when the transition occurs.
+ */
+export class WorkflowTransition extends CloudObject {
+    /**
+     * The `WorkflowTransition` optional _process function_.
+     * It has this signature: (ControlFlow, CloudObject, User, Map) -> (ControlFlow, ErrorFlow)
+     */
+    static processRefProp: Property<Brick>;
+    /** The {@link WorkflowState} from which this transition starts */
+    static fromStateRel: Relation<WorkflowTransition, WorkflowState>;
+    /** The {@link WorkflowState} to which this transition ends */
+    static toStateRel: Relation<WorkflowTransition, WorkflowState>;
+}
+
+/**
+ * A `WorkflowObjectState` represents the state of an instance at a certain point in time.
+ * It is automatically created when initializing a {@link Workflow} on an instance or when triggering a {@link WorkflowTransition}.
+ */
+export class WorkflowObjectState extends CloudObject {
+    /** The name of the {@link Workflow} associated */
+    static workflowProp: Property<string>;
+    /** The name of the {@link WorkflowState} */
+    static stateProp: Property<string>;
+    /** The name (login) of the {@link User} */
+    static assigneeProp: Property<string>;
+    /** The point in time of this object state */
+    static dateTimeProp: Property<Date>;
+    /** If the {@link Workflow} has serialization enabled, the object's property are saved here in JSON */
+    static serializedObjectProp: Property<string>;
+    /** The related instance this object state represents */
+    static objectRel: Relation<WorkflowObjectState, CloudObject>;
+    /** The related instance this object state represents. This relation only reference the current state */
+    static currentObjectRel: Relation<WorkflowObjectState, CloudObject>;
+}
+
 // ---------------------------
 // -- Database transactions --
 // ---------------------------
 
 /**
  * Transactions are the unique way to apply a list of operations to the datacloud.
- * A transaction can be merged into another transaction to be executed as a single set of operations.
+ * A transaction can be merged into another transaction so that both are executed as a single set of operations.
+ *
+ * All the operations for a transaction are executed atomically. Either all operations succeed, or none is applied.
+ *
  *
  * There are 5 types of basic operations :
  * - Create instance: create a node in the database with specified properties.
@@ -96,51 +315,226 @@ export class EnumValue extends CloudObject {
  * - Create relation: create a relation of a specific type between 2 existing node.
  * - Delete relation: remove the specified relation between 2 specified nodes.
  *
- * Classical transactions are executed using "execute()" method. The transaction size is limited but real-time but
- * all the changes applied on data "observed" by queries will be notified.
+ * In most cases, we apply the Transactions operations using the "execute()" method. The transaction size is limited but in real-time.
+ * It notifies observers of the data in real-time.
  *
- * Transactions with big set of operations (batch updates) can be executed using "executeAsLarge()" method. However no notification will be generated.
+ * Larger transactions with big set of operations (batch updates) must be executed using "executeAsLarge()" method. However no notification will be generated.
  *
  * Callbacks can be registered on transaction using "afterExecution()" method. They are executed once the transaction is applied.
  *
+ * Example of transaction:
+ *
+ * ```javascript
+ * const tx = new Transaction(true);
+ * const myNewInstanceTag = tx.create(<myModelTag>);
+ * tx.update(myNewInstanceTag, <myPropertyTag>, <myPropertyValue>)
+ *   .execute()
+ *   .then(() => {
+ *      // success tx case
+ *   })
+ *   .catch((err) => {
+ *      // error during tx case
+ *   })
+ * ```
+ *
  * Concurrency transactions do not guarantee their execution order.
  */
 export class Transaction {
     constructor(persist?: boolean);
 
+    /**
+     * Get the transaction id attached to this transaction
+     * @return this transaction id
+     */
     getId(): string;
 
     // Operations
+    /**
+     * Create a new instance.
+     *
+     * A custom map can specify property values for the instance.
+     *
+     * A source can be the orchestrator ('server'), local ('self') or
+     * an external data source ('<DBConnectorTag>'). The source is where
+     * the object is persisted and its true value outside local scopes.
+     *
+     * @param model tag of the model of the instance to be created
+     * @param properties custom map from tag to their value for properties of the instance to be created
+     * @param source optional source of the instance
+     * @param tag optional tag of the instance to be created and must be unique
+     * @return  the tag of the instance to be created
+     */
     create(model: Tag, properties?: Map<Tag, any>, source?: string, tag?: string): string;
+
+    /**
+     * Update the property of an instance
+     *
+     * @param instance tag of the instance to be updated
+     * @param property the property to be updated
+     * @param value the value of the property to be updated to
+     * @return this transaction
+     */
     update<T>(instance: Tag, property?: Property<T>, value?: T): this;
-    multiUpdate(instance: Tag, properties: Map<string, any>): this;
+
+    /**
+     * Update multiple properties of a single instance
+     *
+     * @param instance tag of the instance to be updated
+     * @param properties (<propertyTag>, <propertyValue>) map to update properties
+     * @return this transaction
+     */
+    multiUpdate(instance: Tag, properties: Map<Tag, any>): this;
+
+    /**
+     * Delete an instance
+     *
+     * @param instance tag of the instance to be deleted
+     * @return this transaction
+     */
     delete(instance: Tag): this;
+
+    /**
+     * Create relation between two instances
+     *
+     * @param relation tag of the relation to be created
+     * @param from tag of the ORIGIN instance of the relation
+     * @param to tag ofo the DESTINATION instance of the relation
+     * @return this transaction with the create relation operation registered
+     */
     createRelation(relation: Tag, from: Tag, to: Tag): this;
+
+    /**
+     * Delete a relation between two specified instances.
+     *
+     * The relation is only deleted for the relation parameter direction.
+     *
+     * @param relation tag of the relation to be deleted
+     * @param from origin instance tag
+     * @param to destination instance tag
+     * @return this transaction
+     */
     deleteRelation(relation: Tag, from: Tag, to: Tag): this;
+
+    /**
+     * Delete any number of the relation starting from specified node.
+     *
+     * The specified node might be the origin or (exclusive) the destination of the relation.
+     *
+     * For the relations :
+     * ```
+     * - a - [rel1] -> b,
+     * - c - [inverseRel(rel1)] -> a,
+     * - a - [rel1] -> d,
+     * - a - [rel2] -> d
+     * ```
+     * `tx.deleteAllRelation(rel1, a)` will remove the first and third relations
+     *
+     * @param relation deleted relation, indicates relation tag *and* direction
+     * @param origin starting node
+     */
     deleteAllRelations(relation: Relation<any, any>, origin: Tag): this;
 
-    // Change persistence of instances
+    /**
+     * Change the persistence mode of all instances in this transaction
+     *
+     * @param persist whether instances are persisted outside
+     * the local datacloud
+     * @return this transaction
+     */
     persist(persist?: boolean): this;
+
+    /**
+     * Change the persistence mode for a single instance in this transaction
+     *
+     * @param instance the instance to be persisted
+     * @param persist the persisting mode
+     * @return this transaction
+     */
     persistInstance(instance: Tag, persist?: boolean): this;
 
-    // Set source of all instances created in this transaction
+    /**
+     * Change the source of all instances created in this transaction
+     *
+     * `source` can be specified as :
+     * 1. the orchestrator ('server'),
+     * 2. local ('self') or
+     * 3. an external data source ('<DBConnectorTag>')
+     *
+     * The source of a data object is where the object is persisted.
+     *
+     * By default, the `source` is the default source configured in the project.
+     *
+     * @param source the new source for instances
+     * @return this transaction
+     */
     setSource(source: string): this;
+
+    /**
+     * Retrieve the tag of the model of the instance tag
+     * from the created instances in this transaction
+     * or from the local database.
+     *
+     * @param tag the instance to find the model of
+     * @return the tag of the model of the given instance
+     */
     model(tag: Tag): string;
 
+    /**
+     * Add all operations of another transaction into this transaction
+     *
+     * @param otherTransaction the other transaction to add operations from
+     * @return this transaction
+     */
     merge(otherTransaction: Transaction): this;
 
     // Execution methods
+    /**
+     * Set a callback to be executed after all the operations
+     * in the transaction were executed successfully
+     *
+     * @param callback the callback to be executed
+     * @return this transaction
+     */
     afterExecution(callback: (success: boolean, message?: string) => void): this;
+
+    /**
+     * Execute atomically the transaction at the source
+     *
+     * @return promise resolving if the transaction succeeds,
+     * rejecting if the transaction fails
+     */
     execute(): Promise<void>;
+
+    /**
+     * Execute atomically a transaction at the source
+     * The `large` mode sends the transaction over HTTP
+     *
+     * @return promise resolving if the transaction succeeds,
+     * rejecting if the transaction fails.
+     */
     executeAsLarge(): Promise<void>;
 
-    // Begin/End shared transaction helpers
+    /**
+     * Start a transaction using an existing transaction in the provided context
+     * or a new one if there is none.
+     *
+     * @param $ context in which the transaction executes
+     * @return transaction
+     */
     static from($: BrickContext): Transaction;
+
+    /**
+     * Execute a given transaction if there is no open transaction in the context.
+     *
+     * @param $ context
+     * @param transaction transaction to process
+     * @return boolean indicating if the argument transaction has been processed
+     */
     static process($: BrickContext, transaction: Transaction): Promise<boolean>;
 }
 
 /**
- * BurstTransactions are designed to apply updates of properties continuously with the matter of the order.
+ * BurstTransactions are designed to continuously apply high rates of updates on properties (FIFO ordering).
  * The only operation supported by BurstTransactions is to update properties of an instance.
  *
  * Unlike classical Transactions, a burst transaction preserves the order of update operations and
@@ -153,147 +547,663 @@ export class Transaction {
 export class BurstTransaction {
     constructor();
 
-    // Push all the property values from the specified Observable to update the specified object.
+    /**
+     * Push all property values from specified Observable to update specified object
+     *
+     * @param object the object to update
+     * @param values observable of a `Map<Property<T>, T>` mapping properties to new values
+     */
     push<T>(object: CloudObject, values: Observable<Map<Property<T>, T>>): void;
 
-    // Commit and close the burst transaction.
+    /**
+     * Commit and close the burst transaction
+     *
+     * @return Promise<void> completing with commit success/failure
+     */
     complete(): Promise<void>;
 }
 
 // ----------------------
 // -- Database queries --
 // ----------------------
-type Empty = [];
 
 /**
- * A CloudArray (type: QueryResult) is a array of tuple of CloudObjects that has been generated by a Query. It contains the result of a query at a specific time.
+ * A QueryResult is a list of key-value pairs that has been generated as a result of a `Query`.
+ * It contains the result of a query at a specific time.
  *
- * When a query is subscribed, it generates multiple CloudArrays along time and got via an observable.
- * Difference between CloudArrays from a Query is accessible using methods getAdded() and getRemoved().
+ * The keys are tags (e.g. `myTag`) that correspond to a `CloudObject` (e.g. `myCloudObject`).
+ * When the {@link Query} contains more than one [Query.andReturn()]{@link Query#andReturn} clause,
+ * keys are composite tags (e.g. `'tag1.tag2.tag3'`) and values are tuples of `CloudObjects` (e.g. `[cloudObj1, cloudObj2, cloudObj3]`).
+ * Such a QueryResult can be obtained via:
+ * ```javascript
+ * Query.instancesOf(myModel1).andReturn.follow(myRelation1).andReturn.follow(myRelation2).andReturn().execute().
+ * ```
  *
- * A CloudArray can be easily manipulated and transformed to a standard Array.
+ * When a query is subscribed, the returned observable generates multiple QueryResults over time.
  *
- * Keys of CloudObject tuples follow the rule: 'tag1.tag2.tag3' : [cloudObj1, cloudObj2, cloudObj3]
+ * A QueryResult can be easily manipulated and transformed to a standard Array.
  */
-export class QueryResult<T> {
+export class QueryResult<T extends CloudObject | CloudObject[]> {
+    /**
+     *@return empty `QueryResult`
+     */
     static empty(): QueryResult<any>;
 
+    /**
+     * Symbol iterator for `for..in` syntactic sugar
+     *
+     * @return iterator over the key-values pairs of this `QueryResult`
+     */
     [Symbol.iterator](): IterableIterator<[string, T]>;
+
+    /**
+     * Get an iterable iterator over the key-value pairs of this `QueryResult`
+     *
+     * @return iterator
+     */
     entries(): IterableIterator<[string, T]>;
+
+    /**
+     * Get an iterable iterator over the values of this `QueryResult`
+     *
+     * @return iterator
+     */
     values(): IterableIterator<T>
+
+    /**
+     * Get an iterable iterator over the keys of this `QueryResult`
+     *
+     * @return iterator
+     */
     keys(): IterableIterator<string>
 
+    /**
+     * Get an array containing the values of this `QueryResult`
+     *
+     * @return array of this `QueryResult`'s values
+     */
     toArray(): T[];
+
+    /**
+     * Get the number of key-value pairs this `QueryResult` contains
+     *
+     * @return size of this `QueryResult`
+     */
     size(): number;
+
+    /**
+     * Check whether a key / value is contained in this `QueryResult`.
+     *
+     * Returns true if the cloud array contains an element with the specified key.
+     *
+     * If no corresponding key is found, returns true if the cloud array contains an element with the specified value.
+     *
+     * @param key the value to search for
+     * @return true if the value `key` is found
+     */
     has(key: T | string): boolean;
+
+    /**
+     * Get index of a value in the keys or values of this `QueryResult`.
+     *
+     * If the key is a string, retrieve the index from the `string` keys of this `QueryResult`.
+     *
+     * If the key is not a string, get the index from the `CloudObject` tuples
+     *
+     * @param key the value to find the index of
+     * @return index of the argument value or -1 if the value is not found
+     */
     indexOf(key: T | string): number;
+
+    /**
+     * Get the value corresponding to a given key
+     *
+     * @param key tag or composite tag
+     * @return matching tuple or `null`
+     */
     get(key: string): T | null;
+
+    /**
+     * Get the first value
+     *
+     * @return first value or `null` if empty
+     */
     getFirst(): T | null;
+
+    /**
+     * Get the value at the specified index
+     *
+     * @param index
+     * @return value at position `index` or `null` if index is out of bounds
+     */
     getAt(index: number): T | null;
 
+    /**
+     * Returns an array equivalent to [this.toArray().push(...object)]{@link toArray}
+     *
+     * This operation returns a new array and does not modify this QueryResult.
+     *
+     * @param object new values to push in the values array.
+     * @return new values array with new elements appended
+     */
     push(...object: T[]): T[];
+
+    /**
+     * Returns the QueryResult values as an array whose last value has been removed.
+     *
+     * If [QueryResult.size()]{@link size} is 0 or 1, this method returns an empty array.
+     *
+     * This operation returns a new array and does not modify this QueryResult.
+     *
+     * @return new values array with last element removed
+     */
     pop(): T[];
+
+    /**
+     * Returns the QueryResult values as an array whose first value has been removed.
+     *
+     * If [QueryResult.size()]{@link size} is 0 or 1, this method returns an empty array.
+     *
+     * This operation returns a new array and does not modify this QueryResult.
+     *
+     * @return new values array with first element removed
+     */
     shift(): T[];
 
-    // Gives the difference between last cloud array => what instances added, and what where removed.
+    /**
+     * Returns the new values added since the last `QueryResult` update.
+     * In other words, `getAdded` returns the new values that exists in this query result, but did not in the previous query result pushed by the Observable.
+     *
+     * This applies only when *observing* a [Query]{@link Query#observe}.
+     *
+     * @return values added
+     */
     getAdded(): T[];
+
+    /**
+     * Returns the keys of values removed since the last `QueryResult` update.
+     * In other words, `getRemoved` returns the old values that existed in the previous query result, but are no longer present in this query result pushed by the Observable.
+     *
+     * This applies only when *observing* a [Query]{@link Query#observe}.
+     *
+     * @return keys of the removed values
+     */
     getRemoved(): string[] | string[][];
 
-    filter(predicate: (entry: T) => boolean): T[];
-    find(predicate: (entry: T) => boolean): T | null;
+    /**
+     * Returns an array containing the values matching the provided filter predicate.
+     *
+     * @param predicate filter {@link Predicate}
+     * @return array of matching values
+     */
+    filter(predicate: (entry: T, index: number) => boolean): T[];
+
+    /**
+     * Returns the first value matching the predicate, `null` otherwise.
+     *
+     * `find` calls `predicate` once for each element of the array until it returns true.
+     * If such an element is found, find immediately returns that element value.
+     *
+     * @param predicate
+     * @return the first value evaluating to true or `null`
+     */
+    find(predicate: (entry: T, index: number) => boolean): T | null;
+
+    /**
+     * Execute the specified callback function for each value of this `QueryResult`
+     *
+     * @param callback
+     */
+    forEach(callback: (entry: T, index: number) => void): void;
 
-    forEach(callback: (entry: T) => void): void;
-    map<S>(callback: (entry: T) => S): S[];
+    /**
+     * Execute the specified callback function for each value of this `QueryResult`.
+     * It returns a new array that contains the results of the callback execution.
+     *
+     * @param callback
+     * @return new array of transformed values
+     */
+    map<S>(callback: (entry: T, index: number) => S): S[];
+
+    /**
+     * Return a sorted copy of this QueryResult.
+     *
+     * The specified `comparator` used to determine the order of the QueryResult key-value pairs.
+     * It compares two QueryResult values and should return a negative number if the first value shall be present before the second, zero if they're at the same position, and a positive
+     * number otherwise.
+     *
+     * @param comparator comparator returning a negative, zero or positive number
+     * @return sorted copy of this QueryResult
+     */
     sort(comparator: (b1: T, b2: T) => number): QueryResult<T>;
-    reduce<S>(reducer: (accumulator: S, entry: T) => S, initial: S): S;
+
+    /**
+     * Return a reduced value for this QueryResult.
+     *
+     * The specified `reducer` callback reduces the QueryResult values as [reduce]{@link Array#reduce}
+     *
+     * @param reducer callback
+     * @param initial initial value of the accumulator
+     * @return  accumulated result applying the `reducer` function iteratively
+     */
+    reduce<S>(reducer: (accumulator: S, entry: T, index: number) => S, initial: S): S;
+
+    /**
+     * Return a new QueryResult that contains the concatenation of two or more QueryResults.
+     *
+     * Concatenating two QueryResults results in a new QueryResult with the following:
+     *
+     * - the keys of the QueryResults are concatenated
+     * - the values of the QueryResults are concatenated
+     * - the arrays returned by {@link getAdded} are concatenated
+     * - the arrays returned by {@link getRemoved} are concatenated
+     *
+     * Example : ```javascript
+     * const result1 = Query.fromInstances(myModel1).executeFromCache();
+     * // result1 is {tag1: cloudObj1, tag2: cloudObj2}
+     * const result2 = Query.fromInstances(myModel2).executeFromCache();
+     * // result2 is {tag3: cloudObj3}
+     * const concatenatedResult = result2.concat(result1);
+     * // concatenatedResult is {tag3: cloudObj3, tag1: cloudObj1, tag2: cloudObj2}
+     * ```
+     *
+     * @param others QueryResults to append to this `QueryResult`
+     * @return concatenated query results
+     */
     concat(...others: QueryResult<T>[]): QueryResult<T>;
 }
 
 /**
  * A Query is an immutable object used to build queries on the datacloud. It is a graph query builder.
- * Starting from an origin Tag (CloudObject or its unique id), it follows specified relations:
+ * It starts from an `origin` Tag (typically, the `Tag` of a data type or of an instance).
+ * From there, it can follow relations between data types and filter results.
  *
- *  origin --a--> X --b--> Y --c--> Z
+ * Example:
+ *
+ *  `origin --a--> X --b--> Y --c--> Z`
  *
- * At each level, "andReturn()" method can be called to add the current level to the result.
  * Example:
  *
+ * ```javascript
+ *  Query.from(origin)
+ *      .follow(a)
+ *      .execute();
+ * ```
+ *  This will return a Promise of a QueryResult whose values are of type X: `Promise<QueryResult<X>>`.
+ *
+ * A query defines a starting working set of nodes and operations that will mutate it.
+ * From our example,the working set is first the `origin` graph node. Then the `follow`
+ * operations create a new working set only containing the nodes related to the origin through relation *`a`*.
+ *
+ * Multiple relations can be followed at once to create the equivalent of JOIN operations in relational databases.
+ * ```javascript
  *  Query.from(origin)
  *      .follow(a).andReturn()
  *      .follow(b)
  *      .follow(c).andReturn()
  *      .execute();
+ * ```
+ * The next operation defines a working set containing the nodes related
+ * through relation *`b`* to nodes that are related through relation *`a`* to the origin.
+ * A similar operation is defined for relation `c`.
+ * At each level, "andReturn()" method can be called to add the current level to the result.
+ * This will return a Promise of a QueryResult whose values are of type [X, Z]: `Promise<QueryResult<[X, Z]>>`.
+ *
+ * Out of the 4 working sets created, only the second and fourth are flagged to be returned and part of the result.
+ * But the operations in the middle impact this result: e.g.,
+ * all returned tuples (t1, t2) are object that have an intermediate `i` of type Y.
+ * such that `t1 --b-> i --c-> t2` but the `i` was not flagged to be returned.
+ *
+ * Queries define a path from a starting point following a specific list of relations.
+ * As explained with our example, only nodes part of a full path can be returned.
  *
- *  This will return a Promise of a of tuple [X, Z]: Promise<CloudArray<[X, Z]>>.
  *
  * A query can be executed with 3 different ways:
  * - execute(): it runs the query on the datacloud and return the result as a QueryResult.
  * - observe(): it runs the query on the datacloud and subscribes to updates. It returns an Observable which provides a new QueryResult every time the result changes.
  * - executeFromCache(): it runs the query on the *local* datacloud which may be incomplete view of the datacloud (it is the local cache). It is executed synchronously.
  */
-export class Query<T extends CloudObject, R extends any[]> {
-    static from<T extends CloudObject>(tag: Tag): Query<T, Empty>;
-    static instancesOf<T extends CloudObject>(model: Class<T>, source?: string): Query<T, Empty>;
+export class Query<T extends CloudObject, R> {
 
-    follow<D extends CloudObject>(relation: Relation<T, D>): Query<D, R>; //
+    /**
+     * Create a query starting from the `CloudObject` specified tag
+     *
+     * @param tag tag of the `CloudObject` the query is starting from
+     * @param source optional source of the data to answer the query
+     * @return an empty Query whose starting point is defined by a single `CloudObject`
+     */
+    static from<T extends Tag>(tag: T, source?: string): Query<T extends CloudObject ? T : CloudObject, never>;
+
+    /**
+     * Create a query starting from the instances of the specified model
+     *
+     * @param model tag/class of the model to find the instances of
+     * @param source optional source of the data to answer the query
+     * A source can be the orchestrator ('server'), local ('self') or
+     * an external data source ('<DBConnectorTag>')
+     * @return a new query object starting from model instances
+     */
+    static instancesOf<T extends Tag>(model: Class<T> | Tag, source?: string): Query<T extends CloudObject ? T : CloudObject, never>;
+
+    /**
+     * Instruct the query to follow a specified relation. This does not add any key-value pair to the result.
+     * (see {@link andReturn}). This operation defines a new step in the path defined by our graph query.
+     *
+     * Example:
+     * Find the model of a single object.
+     * ```javascript
+     * Query.from(myTag).follow(CloudObject.modelRel).andReturn()
+     * ```
+     *
+     * @param relation relation to follow, specifies type and direction
+     * @return a new query object
+     */
+    follow<D extends CloudObject>(relation: Relation<T, D>): Query<D, R>;
+
+    /**
+     * Follow a relation recursively, see {@link follow}.
+     * The relation that is followed is automatically recursively followed.
+     * All nodes that are recursively followed are part of the same step in the path defined by this graph query.
+     *
+     * @param relation relation to follow recursively, specifies type and direction
+     * @param includeSelf  if a starting node includes itself when the relation loops on itself
+     * @return a new query object
+     */
     followRecursively<D extends CloudObject>(relation: Relation<T, D>, includeSelf?: boolean): Query<D, R>;
 
-    andReturn(): Query<T, [...R, T]>; // Add the current level of the query to the result. (Listdefs only support the last level to be returned).
+    /**
+     * Add the current working set of nodes to the result.
+     *
+     * Example:
+     * Query returning the instances of a model and the model itself
+     * ```javascript
+     * Query
+     *      .from(myModelTag).andReturn()
+     *      .follow(CloudObject.modelRel.getInverse()).andReturn()
+     *      .execute();
+     * ```
+     * The result tuples are [modelCloudObject, instance1], [modelCloudObject, instance2], ...
+     *
+     * @return a new query object with the current level flagged to be returned.
+     */
+    andReturn(): Query<T, R extends never ? T : R extends CloudObject[] ? [...R, T] : [R, T]>;
 
+    /**
+     * Define a filter operation on the current working set of nodes.
+     * It filters out instances that don't match the given {@link Predicate}
+     *
+     * @param predicate
+     * @return a new query object with the new filter operation
+     */
     filter(predicate: Predicate): Query<T, R>;
+
+    /**
+     * Cast the type of the instances in the current working set of nodes
+     *
+     * @param type cast type for `CloudObjects`
+     * @return the
+     */
     cast<S extends CloudObject>(type: Class<S>): Query<S, R>;
 
-    // Methods for which only the last call matters
+    /**
+     * Set the maximum number of tuples the executed query will return with an optional offset.
+     *
+     * Only the last call to limit matters.
+     *
+     * Example :
+     * ```javascript
+     * const queryLimited = query.limit(50).follow(myRel2).limit(100, 200).follow(myRel1);
+     * // is equivalent to
+     * const queryLimited2 = query.follow(myRel2).follow(myRel1).limit(100, 200);
+     * ```
+     * `queryLimited`, when executed, will return at most the 200th to the 299th (included) results.
+     *
+     * @param max maximum number of tuple to fetch from the final result
+     * @param offset number of skipped tuples for the final result
+     * @return new query with limit operation
+     */
     limit(max: number, offset?: number): Query<T, R>;
+
+    /**
+     * Sort the result tuples according to a property of a data type with a specified order.
+     **
+     * For the sortBy operator to be properly defined, the following must be true:
+     * - the property is defined on the instances that will be used for sorting.
+     * - the instances on which the sorting property is defined must be part of the result,
+     * i.e., `andReturn()` has been called before `sortBy()`.
+     *
+     * Only the last call to `sortBy` matters as it will be the last comparator set on the query.
+     * You should remove previous calls to `sortBy` for the same query.
+     *
+     * Example :
+     * ```javascript
+     * const sortQuery = Query
+     *      .fromInstances(myModel1).andReturn()
+     *      .sortBy(nameProperty)
+     *      .follow(rel1).andReturn()
+     *      .execute();
+     * ```
+     * This query fetches instances of a model, flags them as first element of result tuples.
+     * Then the query follows a relation to other instances and return them as second element of the result tuples.
+     * `sortBy` will sort the results according to the `nameProperty` of the first element in the result tuples in
+     * ascending order.
+     *
+     * @param property the property used for sorting
+     * @param order optional [Order.ASC]{@link Order#ASC} (default) or [Order.DESC]{@link Order#DESC} order
+     * @return new query with sort operation
+     */
     sortBy(property: Property<any>, order?: Order): Query<T, R>;
 
-    execute(context: Context): Promise<QueryResult<R>>; // Execute the query on the datacloud (as a listdef) and deletes it afterwards.
-    observe(context: Context): Observable<QueryResult<R>>; // Generate a subscription and get a new CloudArray for every update.
+    /**
+     * Execute the query asynchronously on the datacloud and deletes it afterwards.
+     * In other words, one cannot call execute twice on the same `Query`.
+     *
+     * @param context context in which the query must be executed. As this is an asynchronous operation,
+     * one has to provide a context that won't be destroyed before the query has a result.
+     * @return promise resolving to query result or failing otherwise.
+     */
+    execute(context: Context): Promise<QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>>;
+
+    /**
+     * Get an observable to the current value of the QueryResult for this Query instance.
+     *
+     * The observable gets the new value each time data modification in the datacloud changes the result of the query.
+     *
+     * The observable gets completed automatically once the specified context is [cleared]{@link Context#onClear}.
+     *
+     * @param context [context]{@link Context} to which the Observable is attached
+     * @return Observable of QueryResult values
+     */
+    observe(context: Context): Observable<QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>>;
 
-    executeFromCache(): QueryResult<R>; // Execute the query locally, using the DBView.
+    /**
+     * Execute synchronously the query on the local datacloud cache.
+     * `executeFromCache` can only be called once on a given `Query`.
+     *
+     * @return query result of the execution on the local cache
+     */
+    executeFromCache(): QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>;
 }
 
 /**
- * A QuerySingle is a Query which follows relations that should be unique between CloudObjects (0..1 and 1..1 cardinalities).
- * It returns the CloudObjects related to the origin, following the specified relation(s).
+ * A QuerySingle is a Query which follows relations that should be unique between data types (0..1 and 1..1 cardinalities).
+ * It returns the instance related to the origin, following the specified relation(s).
  *
- * It acts as a syntactic sugar to avoid having a CloudArray and get the first value.
+ * It acts as a syntactic sugar to avoid having a query result structure and get the first value out of it.
  *
  * A QuerySingle is immutable.
  */
 export class QuerySingle<T extends CloudObject> {
+    /**
+     * Create a `query single` from a single node.
+     * See [Query.from]{@link Query#from}
+     *
+     * @param object starting node for the graph query single
+     * @return new query single only accepting 0..1 relations
+     */
     static from<T extends CloudObject>(object: Tag): QuerySingle<T>;
 
+    /**
+     * Follow a 0..1 relation
+     * See [Query.follow()]{@link Query#follow}
+     *
+     * @param relation relation to next node
+     * @return new query single with follow operation
+     */
     follow<D extends CloudObject>(relation: Relation<T, D>): QuerySingle<D>;
+
+    /**
+     * See [Query.cast()]{@link Query#cast}
+     *
+     * @param type the new type
+     * @return query single on a node of the specified type
+     */
     cast<S extends CloudObject>(type: Class<S>): QuerySingle<S>;
 
-    execute(context: Context): Promise<T | null>; // Execute the query on the datacloud (as a listdef) and deletes it afterwards.
+    /**
+     * Execute the query single, see [Query.execute()]{@link Query#execute}
+     *
+     * @param context
+     * @return promise containing the single result or `null`
+     */
+    execute(context: Context): Promise<T | null>;
 
-    executeFromCache(): T | null; // Execute the query locally, using the DBView.
+    /**
+     * Execute the query single on the local data cloud,
+     * see [Query.executeFromCache()]{@link Query#executeFromCache}
+     *
+     * @return single result value or `null`
+     */
+    executeFromCache(): T | null;
 }
 
 /**
  * Predicates are used to filter queries.
+ *
+ * Example:
+ * ```javascript
+ * const predicate = Predicate.equals(myNumberProperty, 1);
+ * const filteredQuery = Query.instancesOf(myModel).filter(predicate).andReturn();
+ * ```
  */
 export class Predicate {
+    /**
+     * Create a predicate matching a specified property to a specified value.
+     *
+     * @param property the property to use for filtering
+     * @param value the value the property must match
+     * @return new Predicate with the equals operation
+     */
     static equals<T>(property: Property<T>, value: T): Predicate;
+
+    /**
+     * Create a predicate matching a specified string property to a specified string.
+     *
+     * @param property the string property to use for filtering
+     * @param value the value the string property must match
+     * @param caseSensitive if the match must pay attention to case sensitivity
+     * @return new Predicate with the contains string operation
+     */
     static contains(property: Property<string>, value: string, caseSensitive?: boolean): Predicate;
+
+    /**
+     * Create a predicate matching a specified string property to a regular expression.
+     *
+     * @param property the string property to use for filtering
+     * @param value the regex the string property must match
+     * @param caseSensitive if the match must pay attention to case sensitivity
+     * @return new Predicate with the match regex operation
+     */
     static regex(property: Property<string>, value: RegExp, caseSensitive?: boolean): Predicate;
 
+    /**
+     * Create a predicate matching a specified number property to a numerical lower bound
+     *
+     * @param property the number property to user for filtering
+     * @param value the lower bound
+     * @param strict if the inequality is strict or not
+     * @return new Predicate with the greaterThan mathematical operation
+     */
     static greaterThan(property: Property<number>, value: number, strict?: boolean): Predicate;
+
+    /**
+     * Create a predicate matching a specified number property to a numerical upper bound
+     *
+     * @param property the number property to user for filtering
+     * @param value the upper bound
+     * @param strict if the inequality is strict or not
+     * @return new Predicate with the smallerThan mathematical operation
+     */
     static smallerThan(property: Property<number>, value: number, strict?: boolean): Predicate;
 
+    /**
+     * Create a predicate matching a specified number property to a number property lower bound
+     *
+     * @param property1 the number property to user for filtering
+     * @param property2 the lower bound number property
+     * @param strict if the inequality is strict or not
+     * @return new Predicate with the greaterThan mathematical operation
+     */
     static greaterThan(property1: Property<number>, property2: Property<number>, strict?: boolean): Predicate;
+
+    /**
+     * Create a predicate matching a specified number property to a number property upper bound
+     *
+     * @param property1 the number property to user for filtering
+     * @param property2 the upper bound number property
+     * @param strict if the inequality is strict or not
+     * @return new Predicate with the smallerThan mathematical operation
+     */
     static smallerThan(property1: Property<number>, property2: Property<number>, strict?: boolean): Predicate;
 
+    /**
+     * Create an AND composite predicate matching a specified set of predicates
+     *
+     * @param predicates list of predicates to match
+     * @return new Predicate that should match all specified predicates
+     */
     static and(...predicates: Predicate[]): Predicate;
+
+    /**
+     * Create an OR composite predicate matching a specified set of predicates
+     *
+     * @param predicates list of predicates to match
+     * @return new Predicate that should match at least one specified predicate
+     */
     static or(...predicates: Predicate[]): Predicate;
+
+    /**
+     * Create a NOT  predicate matching the opposite of a specified predicate
+     *
+     * @param predicate the predicate to inverse
+     * @return new Predicate that match when the specified predicate does not
+     */
     static not(predicate: Predicate): Predicate;
 }
 
+/**
+ * Specific predicate class creator for filtering based on relations between objects
+ *
+ * A path is defined by a list of relations, and an object match the predicate if and only if the patch can be followed
+ * to a destination (which might be specified)
+ */
 export class RelatedTo extends Predicate {
     constructor(destination?: Tag);
+
+    /**
+     * Adds a relation to the path the RelatedTo predicate must match
+     *
+     * @param relation relation to add to the path
+     * @return new RelatedTo predicate with additional relation to match in the path
+     */
     follow(relation: Relation<any, any>): RelatedTo;
+
+    /**
+     * Adds a relation that can be followed recursively in the path for the RelatedTo predicate
+     *
+     * @param relation relation to add to the path that can be followed recursively
+     * @return new RelatedTo predicate with additional relation that can be matched recursively in the path
+     */
     followRecursive(relation: Relation<any, any>): RelatedTo;
 }