@olympeio/runtime-web 9.1.0-dev → 9.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olympeio/runtime-web",
-  "version": "9.1.0-dev",
+  "version": "9.1.2",
   "description": "Olympe Web Runtime Environment",
   "types": "types/index.d.ts",
   "dependencies": {

package/types/base.d.ts

@@ -1,34 +1,74 @@
 // @ts-ignore
 import Observable from 'rxjs';
-import {Empty, PropertyModel, Query, QueryResult, QuerySingle} from "./cloud";
+import {PropertyModel, Query, QueryResult, QuerySingle} from "./cloud";
 
 // **********************************
 // Primitives
 // **********************************
 
-declare type Class<T> = { new (): T };
-
+declare type Class<T> = { new(): T };
+/**
+ * A Tag can be either a `string`, a `HasTag` (CloudObject instance, Property, Relation, ...)
+ * or the class constructor for a `CloudObject`
+ */
 export type Tag = string | HasTag | Class<CloudObject>;
-export type List<T> = Array<T> | QueryResult<T>;
 
+export type List<T> = Array<T> | (T extends CloudObject | CloudObject[] ? QueryResult<T> : never);
+
+/**
+ * Generates a unique olympe tag used to identify `CloudObjects`
+ *
+ * @return {string} tag
+ */
 export function generateTag(): string;
+
+/**
+ * Get the unique identifier of the specified Tag as a string
+ *
+ * If the given tag is a `CloudObject` instance, the tag of that instance is returned.
+ * If a class constructor is given, the tag of the corresponding `CloudObject` is returned.
+ *
+ * @param tag
+ * @return string tag of given input
+ */
 export function tagToString(tag: Tag): string;
 
+/**
+ * The HasTag interface defines objects that have a tag.
+ * The tag of these objects must be returned by the override method: `getTag()`
+ */
 export interface HasTag {
+    /**
+     * @return tag of this instance
+     */
     getTag(): string;
 }
 
+/**
+ * Softcoded application context
+ *
+ * Contexts have parents and children, they represent the lifecycle of bricks.
+ * They contain callbacks executed at specific time of the brick lifespan.
+ *
+ * Each time a brick is updated with new inputs, {@link clear} is called,
+ * executing all callbacks registered with {@link onClear}.
+ *
+ * When a brick is destroyed, {@link destroy} is called,
+ * executing all callbacks registered with {@link onClear} and {@link onDestroy}
+ */
 export abstract class Context {
     /**
      * Destroy the current context. It destroys all children context attached to this one and clear their values.
      * The context cannot be reused after calling this function.
      */
     destroy(): void;
+
     /**
      * Clear the current context: detach and destroys all children context.
      * The context can be reused.
      */
     clear(): void;
+
     /**
      * Register a callback to execute when the context is destroyed. Return the callback id.
      *
@@ -36,12 +76,14 @@ export abstract class Context {
      * @return the callback id
      */
     onDestroy(callback: () => void): string;
+
     /**
      * Remove a previously registered callback with {@link Context#onDestroy} method using its id.
      *
      * @param callbackId the id of the callback to unregister
      */
     offDestroy(callbackId: string): boolean;
+
     /**
      * Register a callback to execute every time the context is cleared.
      * This happens every time the brick is refreshed with new inputs and during the brick destruction.
@@ -60,58 +102,359 @@ export abstract class Context {
     offClear(id: string): void;
 }
 
+/**
+ * A `CloudObject` is the base class for all objects that can be persisted and exchanged between Olympe applications.
+ * In essence, it represents a remote reference to an object in the data cloud.
+ * It is identified by its unique ID, or tag. From a `CloudObject` you can access related `CloudObjects`.
+ *
+ * A `CloudObject` can be instantiated via the [Tag]{@link Tag} of its model, and it can be instantiated multiple times with different properties values.
+ * *Data types* defined in DRAW are such `CloudObjects`, instances of Data types are also `CloudObjects`.
+ *
+ * **Example:**
+ * ```javascript
+ * const dcObject = olympe.dc.CloudObject.get(tag);
+ * ```
+ */
 export abstract class CloudObject implements HasTag {
+    /**
+     * The attributes of a CloudObject are called properties. Properties can be of different types,
+     * e.g. `Property<string>`, `Property<number>`, Property<Date>`.
+     *
+     * If a `Person` `CloudObject` has an `age` property, all the instances of `Person` can access
+     * the `age` property using the same tag, the tag of the `age` property. This method returns all
+     * properties defined by the Data Type associated to this class.
+     *
+     * @return All properties defined for a data type
+     */
     static getProperties(): Property<any>[];
-    static getRelations<O extends CloudObject, D extends CloudObject>(this: Class<O>): Relation<O, D>[];
-    static instancesOf<T extends CloudObject>(this: Class<T>): Query<T, Empty>;
 
+    /**
+     * Return all the relations whose origin OR destination is the `CloudObject` associated to this class.
+     *
+     * @return All relations defined on the current data type. It can be the destination or the origin of the relations.
+     */
+    static getRelations<O extends CloudObject, D extends CloudObject>(this: Class<O>): (Relation<O, D> | Relation<D, O>)[];
+
+    /**
+     * Return a query starting from all instances of this Data Type.
+     *
+     * @param model data type to get instances of
+     * @return A query starting from the instances of the specified model.
+     */
+    static instancesOf<T extends CloudObject>(model: Class<T> | Tag): Query<T, never>;
+
+    /**
+     * Get the CloudObject whose tag is specified.
+     *
+     * This only works if the `CloudObject` is already present in the local datacloud cache.
+     * (NB: you can use a {@link Query} to retrieve a distant `CloudObject`)
+     *
+     * @param tag tag of the `CloudObject`
+     * @return `CloudObject` specified by the tag
+     */
     static get<T extends CloudObject>(tag: Tag): T;
+    /**
+     * Create an instance of the specified data type (or `model`)
+     * in the local datacloud (not persisted) with the specified property values.
+     *
+     * If the model is not specified, it uses `this` DataType.
+     *
+     * @param properties mappings of (propertyTag -> propertyValue)
+     * @param model tag of the model of the `CloudObject` you want to create.
+     * @return newly created `CloudObject`
+     */
     static createWith<T>(this: Class<T>, properties: Map<Tag, any>, model?: Tag, source?: string): T;
+
+    /**
+     * Get this `CloudObject` class as a `CloudObject` instance.
+     *
+     * @return the current data type class as a CloudObject instance.
+     */
     static asInstance<T>(this: Class<T>): T;
 
+    /**
+     * Every `CloudObject` has a unique tag.
+     *
+     * @return tag of the CloudObject
+     */
     getTag(): string;
+
+    /**
+     * Every `CloudObject` can define a value for its `nameProperty`.
+     * This method returns the current value of that property for this instance.
+     *
+     * @return the value of the `name property` of `this`
+     */
     name(): string;
+
+    /**
+     * Every `CloudObject` has a model which defines relations and properties its instances may have.
+     *
+     * @return the tag of the model of this `CloudObject` instance
+     */
     getModelTag(): string;
+
+    /**
+     * Every `CloudObject` has a model which defines relations and properties its instances may have.
+     *
+     * @return the model of this `CloudObject` instance as a `CloudObject` instance
+     */
     getModel(): CloudObject;
-    query(): Query<this, Empty>;
+
+    /**
+     * Create and return a query starting from this instance
+     *
+     * @return a query starting at this `CloudObject` instance
+     */
+    query(): Query<this, never>;
+
+    /**
+     * Return the persistence state of this instance.
+     *
+     * `CloudObject`s can either be volatile, and only live in the local cache. In this case,
+     *  the `CloudObject` instance is *not* persisted. If a `CloudObject`is persisted, it is stored in an external data store.
+     *  This means that the instance can be accessible through other Olympe VMs in the same environment.
+     *
+     *  @return a boolean indicating if this object is persisted in a non-volatile way.
+     */
     isPersisted(): boolean;
     equals(object: any): boolean;
 
-    follow<D extends CloudObject>(relation: Relation<this, D>): Query<D, Empty>;
+    /**
+     * Start a query from this instance and follow the relation given as argument.
+     * The query starts from this single instance, and follows a relation to an arbitrary
+     * number of destination instances. See [Query.follow]{@link Query#follow}
+     *
+     * The following are equivalent:
+     * ```javascript
+     * myCloudObject.follow(relation);
+     * myCloudObject.query().follow(relation);
+     * ```
+     *
+     * @param relation the relation to follow from the starting instance (`this`)
+     * @return query starting from `this` and following the relation `relation` as first step of the query
+     */
+    follow<D extends CloudObject>(relation: Relation<this, D>): Query<D, never>;
+
+    /**
+     * Start a `querySingle` from this instance that follows 0..1 relations
+     *
+     * The query starts from this instance, and follow the relation to a single
+     * destination instance. It is equivalent to `QuerySingle.from(this).follow(relation)`.
+     *
+     * @param relation to follow from this starting instance
+     * @return a query following 0-1 relations
+     */
     followSingle<D extends CloudObject>(relation: Relation<this, D>): QuerySingle<D>;
 
     // Properties getters
-    get<T>(property: Property<T>): T | null;
-    observe<T>(context: Context, property: Property<T>): Observable<T>;
+    /**
+     * Get the current value of the specified property for this `CloudObject` instance
+     *
+     * @param property property or property's tag
+     * @return property value
+     */
+    get<T>(property: Property<T> | Tag): T | null;
+
+    /**
+     * Get an observable to the current value of the specified property for this `CloudObject` instance.
+     *
+     * The observable gets the new value each time the property gets updated in the datacloud.
+     * The observable gets completed automatically once the specified context is [cleared]{@link Context#onClear}.
+     * If `waitForValue` is set to FALSE (TRUE by default), the first value received by the observable is null if there is no value at call time.
+     *
+     * @param context [context]{@link Context} to which the Observable is attached
+     * @param property property or property's tag to observe
+     * @param waitForValue [=true] whether the observable wait for a first value to get a value.
+     * @return Observable of property values
+     */
+    observe<T>(context: Context, property: Property<T> | Tag, waitForValue?: boolean): Observable<T>;
+
+    /**
+     * Get an observable to pair [property, value] for this `CloudObject` instance.
+     *
+     * The observable gets the new value each time any property gets updated in the datacloud.
+     * 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 property values
+     */
+    observeProperties<T>(context: Context): Observable<[Property<T>, T]>;
+
+    /**
+     * Create a Javascript object from this CloudObject current state.
+     * @param namesAsKey If true, use the property name instead of the property tag as keys of the generated object.
+     * @param inheritedProperties If false, do not including inherited property. By default, it includes them.
+     */
+    toObject(namesAsKey?: boolean, inheritedProperties?: boolean): Object;
 
     // Properties and Relations
+    /**
+     * Name property for all `CloudObjects`
+     */
     static nameProp: Property<string>;
-    static instanceRel: Relation<CloudObject, CloudObject>;
+
+    /**
+     * Relation between a `CloudObject`and its model
+     * instance --modelRel-> model
+     */
     static modelRel: Relation<CloudObject, CloudObject>;
-    static containsRel: Relation<CloudObject, CloudObject>;
+
+    /**
+     * Inverse relation of {@link modelRel} between a model and its instances
+     * Equivalent to `modelRel.getInverse()`
+     */
+    static instanceRel: Relation<CloudObject, CloudObject>;
+    /**
+     * Model `CloudObjects` can inherit relations and properties
+     * from another `CloudObject` model to mimic their behaviour.
+     *
+     * Relation from a model to the CloudObject model it extends.
+     * A --extendRel-> B
+     * A inherits B's properties and relations.
+     */
     static extendRel: Relation<CloudObject, CloudObject>;
+    /**
+     * Inverse relation of {@link extendRel}
+     */
     static extendedByRel: Relation<CloudObject, CloudObject>;
+    /**
+     * Relation between a container (a `CloudObject`) that has children (other `CloudObject`s)
+     *
+     * For example, from a folder to the contained elements or from a function to the elements needed for that function to run.
+     */
+    static containsRel: Relation<CloudObject, CloudObject>;
+    /**
+     * Relation between a model and the properties it defines.
+     */
     static propertyRel: Relation<CloudObject, PropertyModel>;
 }
 
+/**
+ * A property of a model defines an attribute. A property has a `tag`.
+ * Each instance of a model can have value for these defined properties.
+ */
 export interface Property<T> extends HasTag {}
 
+/**
+ * Relations are directed from A -> B and can be followed in either direction.
+ */
 export enum Direction {
+    /**
+     * For relation A -> B, go to A, the origin
+     */
     ORIGIN = '<',
+    /**
+     * For relation A -> B, go to B, the destination
+     */
     DESTINATION = '>'
 }
 
-export class Relation<O extends CloudObject, D extends CloudObject> implements HasTag {
-    constructor(tag: Tag, direction?: Direction, origin?: Class<O>, destination?: Class<D>);
+interface RelationConstructor {
+    /**
+     * Create a relation between two CloudObject classes
+     * @param tag tag of the relation to create
+     * @param direction whether the relation points to the origin or destination
+     */
+    new(tag: Tag, direction?: Direction): Relation<CloudObject, CloudObject>;
+
+    /**
+     * Create a relation between two CloudObject classes
+     * @param tag tag of the relation to create
+     * @param direction whether the relation points to the origin or destination
+     * @param origin origin class of the relation
+     * @param destination destination class of the relation
+     */
+    new<O extends CloudObject, D extends CloudObject>(tag: Tag, direction?: Direction, origin?: Class<O>, destination?: Class<D>): Relation<O, D>;
+}
+
+/**
+ * Global variable, constructor of class Relation.
+ */
+export declare const Relation: RelationConstructor;
+
+/**
+ * Relations can be defined between from a `CloudObject` to another, for example between two data types.
+ * Relations are directed and have two types: the origin type, the destination type.
+ *
+ * Defining a relation between two data types means that instances of these data types can be related with that relation.
+ */
+export interface Relation<O extends CloudObject, D extends CloudObject> extends HasTag {
+
+    /**
+     * @return tag of the relation
+     */
     getTag(): string;
+
+    /**
+     * @return direction of the relation, whether it points to origin or destination
+     */
     getDirection(): Direction;
+
+    /**
+     * @return class type for the destination of the relation
+     */
     type(): Class<D>;
+
+    /**
+     * @return class type for the origin of the relation
+     */
     originType(): Class<O>;
+
+    /**
+     * @return inverse relation where newOrigin = oldDestination, newDestination = oldOrigin
+     */
     getInverse(): Relation<D, O>;
 }
 
+/**
+ * Register the class constructor as the class associated to the specified tag.
+ *
+ * This creates the link between a class and an DataType in the database.
+ * Once this link is created, all the instances of the DataType (model)
+ * are instantiated as JS objects using the specified class (see [CloudObject.get]{@link CloudObject#get})
+ *
+ * @param tag tag of the DataType
+ * @param object `CloudObject` constructor
+ */
 export function register(tag: Tag, object: Class<CloudObject>): void;
+
+/**
+ * Create a constant property object which has the specified tag and type to be used in coded bricks.
+ *
+ * @param tag the property tag
+ * @param type type the property holds values of
+ * @return newly defined property
+ */
 export function defineProperty<T>(tag: Tag, type?: Class<T>): Property<T>;
+
+/**
+ * Create a constant relation object between two specified DataTypes.
+ *
+ * That constant is used especially to create queries see [Query.follow(relation)]{@link Query#follow}
+ *
+ * @param tag tag of the relation
+ * @param origin origin DataType of the relation
+ * @param destination destination DataType of the relation. Default is `CloudObject`
+ * @param direction direction of the relation, pointing towards origin or destination. Default is `DESTINATION`
+ * @return newly defined relation
+ */
 export function defineRelation<O extends CloudObject, D extends CloudObject>(tag: Tag, origin?: Class<O>, destination?: Class<D>, direction?: Direction): Relation<O, D>;
+/**
+ * Create a constant relation object between two generic `CloudObjects`
+ *
+ * That constant is used especially to create queries see [Query.follow(relation)]{@link Query#follow}
+ *
+ * @param tag tag of the relation
+ * @param direction direction of the relation, pointing towards origin or destination. Default is `DESTINATION`
+ * @return newly defined relation
+ */
 export function defineRelation(tag: Tag, direction?: Direction): Relation<CloudObject, CloudObject>;
+
+/**
+ * Returns a constant object corresponding to the specified relation going to the opposite direction
+ *
+ * @param relation relation to inverse
+ * @return inverse relation
+ */
 export function defineInverseRelation<O extends CloudObject, D extends CloudObject>(relation: Relation<O, D>): Relation<D, O>;