@olympeio/runtime-node 9.10.4 → 9.11.0

package/types/query.d.ts

@@ -0,0 +1,726 @@
+import { Class, Context } from "./other";
+import { CloudObject, InstanceOrTag } from "./data";
+import { FollowRule, RootQueryPart } from "./data-connector";
+import { Property, Relation } from "./composition";
+import { Source } from "./data-connector";
+// @ts-ignore
+import { Observable } from "rxjs";
+
+declare type ImplicitQueryOption = {
+    storeInCacheDB?: boolean // indicates if this follow rule query must be cached in browser DB (IndexedDB) for potential offline use. Default is false.
+}
+
+
+declare type QueryOptions = {
+    cacheBucketName?: string; // Name of the cache bucket - if provided, it means that the query must be cached under this name
+}
+
+// ----------------------
+// -- Database queries --
+// ----------------------
+
+/**
+ * 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.
+ *
+ * The keys are tags (e.g. `myTag`) that correspond to a `CloudObject` (e.g. `myCloudObject`).
+ * When the {@link Query} contains more than one {@link Query.andReturn 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().
+ * ```
+ *
+ * When a query is subscribed, the returned observable generates multiple QueryResults over time.
+ *
+ * A QueryResult can be easily manipulated and transformed to a standard Array.
+ */
+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;
+
+    /**
+     * Query Results, when used in a subscription, can be used to observe changes compare to the previous QueryResult.
+     * This method returns the values that have added from the previous QueryResult.
+     *
+     * @return array of added values (CloudObjects or tuples of CloudObjects)
+     */
+    getAdded(): T[];
+
+    /**
+     * Query Results, when used in a subscription, can be used to observe changes compare to the previous QueryResult.
+     * This method returns the values the keys (eg: tags) of values that have been removed from the previous QueryResult.
+     *
+     * @return array of removed keys (tags or tags concatenation (tuples))
+     */
+    getRemoved(): string[];
+
+    /**
+     * Returns an array equivalent to {@link QueryResult.toArray | this.toArray().push(...object)}
+     *
+     * 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 {@link QueryResult.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 {@link QueryResult.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[];
+
+    /**
+     * 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;
+
+    /**
+     * 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>;
+
+    /**
+     * Return a reduced value for this QueryResult.
+     *
+     * The specified `reducer` callback reduces the QueryResult values. Similar to `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 QueryResult.getAdded} are concatenated
+     * - the arrays returned by {@link QueryResult.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>;
+}
+
+
+/**
+ * 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 to match the specified object(s).
+     *
+     * @param tags the object or unique identifier (tag) of the objects to look for.
+     */
+    static in(...tags: InstanceOrTag[]): 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, default value is true
+     * @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 or pattern the string property must match
+     * @param caseSensitive if the match must pay attention to case sensitivity, default value is true
+     * @return new Predicate with the match regex operation
+     */
+    static regex(property: Property<string>, value: RegExp | string, 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;
+}
+
+
+
+/**
+ * A Query is an immutable object used to build queries on the datacloud. It is a graph query builder.
+ * It starts from an `origin` InstanceOrTag (typically, the `InstanceOrTag` of a data type or of an instance).
+ * From there, it can follow relations between data types and filter results.
+ *
+ * Example:
+ *
+ *  `origin --a--> X --b--> Y --c--> Z`
+ *
+ * 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.
+ *
+ *
+ * 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> {
+
+    /**
+     * Create a query starting from the `CloudObject` specified tag.
+     * That `CloudObject` must already exist in the local database. In case you have the tag as a `string` and need to get
+     * the object from a remote database, use {@link Query.fromTag} instead.
+     *
+     * @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 InstanceOrTag>(tag: T, source?: Source): Query<T extends CloudObject ? T : CloudObject, never>;
+
+    /**
+     * Create a query starting from the `CloudObject` specified tag.
+     * The difference with {@link Query.from} method is that you specify the data type of the Tag: this allows to execute
+     * queries with a tag that is unknown by the local database, on the right remote database.
+     *
+     * @param tag tag of the `CloudObject` the query is starting from
+     * @param dataType data type of the `tag` `CloudObject`.
+     * @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 fromTag<T extends CloudObject>(tag: string, dataType: Class<T> | InstanceOrTag, source?: Source): Query<T, never>;
+
+    /**
+     * Create a query starting from the instances of the specified model. By default, it does include the instances of
+     * the models that inherit from the given one.
+     *
+     * @param model tag/class of the model to find the instances of
+     * @param includeInheritance if set to false, the result will not include instances of models that inherit from the given model.
+     * @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 (Tag of a `DBConnectorTag`)
+     * @return a new query object starting from model instances
+     */
+    static instancesOf<T extends InstanceOrTag>(model: Class<T> | InstanceOrTag, includeInheritance?: boolean, source?: Source): Query<T extends CloudObject ? T : CloudObject, never>;
+
+    /**
+     * Create a query starting from a specific root instance, then following relations based on a rule constraint.
+     * @param ctx Context in which the {@link Query} is observed
+     * @param root Starting point of the query. See `root` of {@link RootQueryPart}
+     * @param rule Discriminate which relations to follow
+     * @param source The tag of the source responsible for executing the query
+     * @param options options
+     */
+    static followRule<T extends InstanceOrTag>(ctx: Context, root: T, rule: FollowRule, source?: Source, options?: ImplicitQueryOption): Observable<QueryResult<T extends CloudObject ? T : CloudObject>>;
+
+    /**
+     * Instruct the query to follow a specified relation. This does not add any key-value pair to the result.
+     * (see {@link Query.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
+     * @param optional whether or not the relation creates a mandatory path in the graph to be part of the result.
+     * @return a new query object
+     */
+    follow<D extends CloudObject>(relation: Relation<T, D>, optional?: boolean): Query<D, R>;
+
+    /**
+     * Follow a relation recursively, see {@link Query.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. (default: false)
+     * @param optional whether or not the relation creates a mandatory path in the graph to be part of the result. (default: false)
+     * @return a new query object
+     */
+    followRecursively<D extends CloudObject>(relation: Relation<T, D>, includeSelf?: boolean, optional?: boolean): Query<D, R>;
+
+    /**
+     * The Query.back() function is used to move the cursor of a query backwards to the previous level.
+     * This allows the query to start from the place where it was before a Query.follow() call,
+     * but with a different relation. The `times` parameter is optional and specifies the number of steps to go back.
+     * If hops is not specified, the default value of 1 is used.
+     * If a value equal to or smaller than 0 is specified, the output query is the same as the input query.
+     *
+     * Example:
+     * ```javascript
+     * const people = [
+     *   \{ name: "Alice", children: ["Bob", "Carol"], siblings: ["David"] \},
+     *   \{ name: "Bob", children: ["Emily"], siblings: ["Alice", "Carol", "David"] \},
+     *   \{ name: "Carol", children: ["Frank"], siblings: ["Alice", "Bob", "David"] \},
+     *   \{ name: "David", children: ["Greg"], siblings: ["Alice", "Bob", "Carol"] \},
+     *   \{ name: "Emily", children: [], siblings: [] \},
+     *   \{ name: "Frank", children: [], siblings: [] \},
+     *   \{ name: "Greg", children: [], siblings: [] \}
+     * ];
+     *
+     * // Create a new query starting from Alice
+     * const aliceQuery = Query.from("Alice");
+     *
+     * // Follow the "children" relation to get Alice's children (Bob, Carol)
+     * const aliceChildrenQuery = aliceQuery.follow("children").andReturn();
+     *
+     * // Go back to the previous level and follow the "siblings" relation to get Alice's siblings (David)
+     * const aliceSiblingsQuery = aliceChildrenQuery.back().follow("siblings").andReturn();
+     *
+     * // Execute the query, the output is:
+     * Output: [ \{ sibling: 'David', child: 'Bob' \}, \{ sibling: 'David', child: 'Carol' \} ]
+     * ```
+     * @param times
+     * @return {!Query}
+     */
+    back(times?: number): Query<CloudObject, R>;
+
+    /**
+     * 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>;
+
+    /**
+     * 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 {@link Order.ASC} (default) or {@link Order.DESC} order
+     * @return new query with sort operation
+     */
+    sortBy(property: Property<any>, order?: Order): Query<T, R>;
+
+    /**
+     * @return the query transformed as a tree of QueryPart. To be used by Data Source.
+     */
+    parse(): RootQueryPart;
+
+    /**
+     * Execute the query asynchronously on the datacloud and deletes it afterward.
+     * In other words, one cannot call execute twice on the same `Query`.
+     *
+     * @param options options
+     * @return promise resolving to query result or failing otherwise.
+     */
+    execute(options?: QueryOptions): 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 {@link Context.onClear | cleared}.
+     *
+     * @param context {@link Context} to which the Observable is attached
+     * @param options options
+     * @return Observable of QueryResult values
+     */
+    observe(context: Context, options?: QueryOptions): Observable<QueryResult<R extends never ? T : R extends CloudObject | CloudObject[] ? R : never>>;
+
+    /**
+     * 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 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 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 {@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: InstanceOrTag): QuerySingle<T>;
+
+    /**
+     * Follow a 0..1 relation
+     * See {@link Query.follow | 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 {@link Query.cast | 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 the query single, see {@link Query.execute | Query.execute()}
+     *
+     * @return promise containing the single result or `null`
+     */
+    execute(): Promise<T | null>;
+
+    /**
+     * Execute the query single on the local data cloud,
+     * see {@link Query.executeFromCache | Query.executeFromCache()}
+     *
+     * @return single result value or `null`
+     */
+    executeFromCache(): T | null;
+}
+
+/**
+ * The sorting order for a {@link QueryPart}.
+ */
+export enum Order {
+    /**
+     * Ascending order.
+     */
+    ASC,
+    /**
+     * Descending order.
+     */
+    DESC
+}
+