@olympeio/runtime-node 8.6.1 → 8.7.0

package/index.d.ts

@@ -1,5 +1,5 @@
 // @ts-ignore
-import {Observable} from "rxjs";
+import { Observable } from "rxjs";
 
 /**
  * A client used to call remote services.
@@ -108,12 +108,12 @@ export abstract class Service {
 /**
  * A service that retrieves a value upon request.
  */
-export class GetService extends Service {}
+export class GetService extends Service { }
 
 /**
  * A service that executes remote procedures.
  */
-export class CallService extends Service {}
+export class CallService extends Service { }
 
 /**
  * A service that allows clients to subscribe to updates.
@@ -129,11 +129,20 @@ export class SubscribeService extends Service {
     notify(payload: Object): Promise<void>;
 }
 
+/**
+ * List of general properties keys used by the runtime engine to set specific values on BrickContexts
+ */
+export enum GlobalProperties {
+    TRANSACTION = '__transaction',
+    PRODUCTION = '__production',
+    EDITION = '__editionMode'
+}
+
 /**
  * The context of a brick is the object that contains the brick state, controls the brick lifecycle and provides
  * an API to observe and set values of this brick's properties.
  */
-export class Context {
+export class BrickContext {
 
     /**
      * Register a callback to execute when the context is destroyed. Return the callback id.
@@ -144,7 +153,7 @@ export class Context {
     onDestroy(callback: () => void): string;
 
     /**
-     * Remove a previously registered callback with {@link Context#onDestroy} method using its id.
+     * Remove a previously registered callback with {@link BrickContext#onDestroy} method using its id.
      *
      * @param id the id of the callback to unregister
      */
@@ -161,7 +170,7 @@ export class Context {
     onClear(callback: () => void): string;
 
     /**
-     * Remove a previously registered callback with {@link Context#onClear} method using its id.
+     * Remove a previously registered callback with {@link BrickContext#onClear} method using its id.
      *
      * @param id the id of the callback to unregister
      */
@@ -182,34 +191,91 @@ export class Context {
     /**
      * Set the specified property value and propagate the update to anyone observing it.
      *
-     * @param property the property
+     * @param key the property or key string
      * @param value the new value to set
+     * @return this
+     */
+    set<T>(key: PropertyDescriptor<T> | string, value: any): this;
+
+    /**
+     * Trigger the specified event and propagate the update to anyone observing it.
+     *
+     * @param key the event or key event
+     * @return this
      */
-    set<T>(property: PropertyDescriptor<T> | string, value: any);
+    trigger<T>(key: PropertyDescriptor<T> | string): this;
 
     /**
      * Clear the value of the specified property and propagate that event.
      *
-     * @param property the property
+     * @param key the property or key string
      */
-    remove<T>(property: PropertyDescriptor<T> | string);
+    remove<T>(key: PropertyDescriptor<T> | string);
 
     /**
      * Return the current value of the specified property. If there is currently no value, return null.
      *
-     * @param property the property
+     * @param key the property or key string
      * @return the current value
      */
-    get<T>(property: PropertyDescriptor<T> | string): T | null;
+    get<T>(key: PropertyDescriptor<T> | string): T | null;
+
+    /**
+     * Returns a boolean indicating whether a property has a value or not.
+     *
+     * @param key the property or key string
+     * @param global [=false] whether or not the method checks parent contexts
+     * @return whether `property` has a value or not
+     */
+    has<T>(key: PropertyDescriptor<T> | string, global?: boolean): boolean;
 
     /**
      * Return an observable to subscribe to value updates of the specified property.
+     * If `waitForValue` is set to FALSE (TRUE by default), the first value received by the observable is null
+     * if there is no value at subscription time.
+     * If `global` is set to TRUE (FALSE by default), it observes values coming from other contexts accessible from the current one.
+     *
+     * @param key the property or key string
+     * @param waitForValue [=true] whether or not the observable wait for a first value to get a value.
+     * @param global [=false] whether or not listen to a value coming from other contexts.
+     * @return the observable
+     */
+    observe<T>(key: PropertyDescriptor<T> | string, waitForValue?: boolean, global?: boolean): Observable<T>;
+
+    /**
+     * Subscribe to the specified observable and set its values to the context with the provided key.
+     *
+     * @param key the key used to set the values coming from the observable
+     * @param observable the observable providing values
+     * @return this context
+     */
+    repeat<T>(key: PropertyDescriptor<T> | string, observable:Observable<T>): this;
+
+    /**
+     * Run a runnable property and returns its context.
+     *
+     * @param property the runnable property or the runnable itself
+     * @return the child context or null if the runner was not found
+     */
+    runner<T>(property: PropertyDescriptor<T> | string | Brick): BrickContext | null;
+
+    /**
+     * Wait for the property to get a new value, wrapped in a promise.
      *
      * @param property the property
      * @param nullable whether or not the observable accept null values (when a value is removed from the context). False by default.
-     * @return an observable
+     * @param global [=false] whether or not the method checks parent contexts
+     * @return a promise of the next value of property
      */
-    observe<T>(property: PropertyDescriptor<T> | string, nullable?: boolean): Observable<T>;
+    waitFor<T>(property: PropertyDescriptor<T> | string, nullable?: boolean, global?: boolean): Promise<T>;
+
+    /**
+     * Set the parent element for visual brick to be rendered.
+     *
+     * @param parent the parent container
+     * @return this
+     */
+    setParentElement(parent: Element): this;
 
     /**
      * Create and return a new context, child of the current one.
@@ -217,7 +283,7 @@ export class Context {
      *
      * @param debugName a name to give to the context for debugging purpose.
      */
-    createChild(debugName?: string): Context;
+    createChild(debugName?: string): BrickContext;
 
     /**
      * Return the context with the specified id if accessible (in the hierarchy) from this context.
@@ -225,7 +291,7 @@ export class Context {
      *
      * @param id the context id we want to retrieve
      */
-    getOtherContext(id: string): Context | null;
+    getOtherContext(id: string): BrickContext | null;
 
     /**
      * Listen to the creation of the context with the specified id.
@@ -235,12 +301,12 @@ export class Context {
      * @param id the context id, which corresponds to the tag of the brick to be retrieved.
      * @param callback the function to execute when the specified brick context is available
      */
-    onContext(id: string, callback: (context: Context) => void): () => void;
+    onContext(id: string, callback: ($: BrickContext) => void): () => void;
 
     /**
      * Return the parent context if it exists.
      */
-    getParent(): Context | null;
+    getParent(): BrickContext | null;
 
     /**
      * Return the closest transaction from this context :
@@ -285,14 +351,21 @@ export class Context {
     popTransaction(): Transaction | null;
 }
 
+/**
+ * @deprecated use {@link BrickContext} instead
+ */
+export class Context extends BrickContext { }
+
 /**
  * Context of UI bricks with methods to get and observe properties.
+ * @deprecated use {@link BrickContext} instead and override render method of VisualBrick.
  */
-export class UIContext extends Context {
+export class UIContext extends BrickContext {
 
     /**
      * Return a Property to get, update and observe its value
      *
+     * @deprecated use {@link BrickContext#get} instead
      * @param name The property name
      */
     getProperty<T>(name: string): Property<T> | null;
@@ -300,6 +373,7 @@ export class UIContext extends Context {
     /**
      * Return an Event to trigger or observe
      *
+     * @deprecated use {@link BrickContext#trigger} instead
      * @param name The event name
      */
     getEvent(name: string): Event | null;
@@ -307,17 +381,10 @@ export class UIContext extends Context {
     /**
      * Observe multiple properties simultaneously.
      *
+     * @deprecated use {@link BrickContext#observe} with the RXJS operator combineLatestWith.
      * @param properties list of properties to observe simultaneously
      */
     observeMany(...properties: string[]): Observable<any[]>;
-
-    /**
-     * Create and return a new UIContext, child of the current one.
-     * Mainly used to run other bricks within the current one (e.g.: a list renderer).
-     *
-     * @param debugName a name to give to the context for debugging purpose.
-     */
-    createChild(debugName?: string): UIContext;
 }
 
 /**
@@ -334,6 +401,8 @@ declare interface PropertyDescriptor<T> {
 
 /**
  * A property allows a brick or a data object to store and provide a value under a specific identifier.
+ *
+ * @deprecated
  */
 declare interface Property<T> extends PropertyDescriptor<T> {
 
@@ -359,6 +428,8 @@ declare interface Property<T> extends PropertyDescriptor<T> {
 
 /**
  * Special brick property type that can be triggered.
+ *
+ * @deprecated
  */
 declare interface Event extends Property<number> {
 
@@ -399,109 +470,166 @@ declare interface Entry {
  * - initialisation: called whenever the brick is instantiated by its parent executor.
  * - updates: called whenever all the inputs of a brick have a value (default behaviour). This behaviour can be modified by overriding `configCoreUpdate`.
  * - destruction: when the parent executor starts to destroy itself, the brick destroys itself too.
+ *
+ * A headless brick that executes its core code every time an input gets a value.
  */
-declare class Brick {
+export class Brick {
+
     /**
      * Static reference to the entry of that brick.
      */
-    public static readonly entry:Entry;
+    public static readonly entry: Entry;
+
+    /**
+     * Return the list of inputs tags as an ordered array.
+     */
+    readonly getInputs: () => string[];
+
+    /**
+     * Return the list of outputs tags as an ordered array
+     */
+    readonly getOutputs: () => string[];
 
     /**
      * Run the brick itself using the specified context.
      *
-     * @param context the brick context
+     * @param $ the brick context
      */
-    run(context: Context);
+    run($: BrickContext);
 
     /**
      * Setup the brick and its context to listen to pipes and updates for its inputs and properties.
      * Typically used as the first instruction of the {@link Brick#run run} method.
      *
-     * @param context the brick context.
+     * @param $ the brick context.
      */
-    protected setup(context: Context);
+    protected setup($: BrickContext);
 
     /**
      * Called when the brick starts its lifecycle and gets initialized.
      *
-     * @param context the brick context
+     * @param $ the brick context
      */
-    protected onInit(context: Context);
+    protected init($: BrickContext);
 
     /**
      * Called when the brick ends its lifecycle and gets destroyed.
      *
-     * @param context the brick context
+     * @param $ the brick context
      */
-    protected onDestroy(context: Context);
-}
+    protected destroy($: BrickContext);
 
-/**
- * A headless brick that executes its core code every time an input gets a value.
- */
-export class FunctionBrick extends Brick {
+    /**
+     * Called every time the context is cleared.
+     *
+     * @param $ the brick context
+     */
+    protected clear($: BrickContext);
 
     /**
      * Called whenever the conditions to update the brick are satisfied (as defined by method `configCoreUpdate`).
      * By default, a function updates whenever an input gets a new value, but only if all inputs have a value.
      *
-     * @param context the brick context
+     * @param $ the brick context
      * @param inputs array of input values
      * @param outputs array of output setter functions. A setter updates a specific output value of the brick.
      */
-    protected onUpdate(context: Context, inputs: Array<any>, outputs: Array<(value: any) => void>);
+    protected update($: BrickContext, inputs: Array<any>, outputs: Array<(value: any) => void>): void;
+
+    /**
+     * Observe the context to define when the brick `update` method should be called.
+     *
+     * @param $ the brick context
+     * @return an observable that emit a value anytime the brick `update` method should be called.
+     */
+    protected setupExecution($: BrickContext): Observable<Array<any>>;
 
     /**
      * Execute the `onUpdate` class method. The `clear` callback destroys the context of the previous update and invalidates previous inputs.
      * Override this method to change the function brick default behaviour.
      *
-     * @param context the brick context
+     * @deprecated
+     * @param $ the brick context
      * @param runUpdate the function to call to update the brick
      * @param clear the function to clear previous run
      */
-    protected setupUpdate(context: Context, runUpdate: (inputs: any[]) => void, clear: () => void);
+    protected setupUpdate($: BrickContext, runUpdate: (inputs: any[]) => void, clear: () => void);
 
     /**
-     * Return the list of inputs tags as an ordered array.
+     * @deprecated use {@link BrickContext#init} instead
+     * @param $ the brick context
      */
-    readonly getInputs: () => string[];
+    protected onInit($: BrickContext): void;
 
     /**
-     * Return the list of outputs tags as an ordered array
+     * @deprecated use {@link BrickContext#init} instead
+     * @param $ the brick context
+     * @param inputs array of input values
+     * @param outputs array of output setter functions.
      */
-    readonly getOutputs: () => string[];
+    protected onUpdate($: BrickContext, inputs: Array<any>, outputs: Array<(value: any) => void>): void;
+
+    /**
+     * @deprecated use {@link BrickContext#init} instead
+     * @param $ the brick context
+     */
+    protected onDestroy($: BrickContext): void;
 }
 
- /**
-  * A headless brick whose update is triggered by an event (control flow). Unlike a `FunctionBrick`, an `ActionBrick` updates on each incoming event, even if an input still has no value.
-  * An `ActionBrick` also provides a specific output to forward the control flow (event).
-  */
-export class ActionBrick extends FunctionBrick {}
+/**
+ * A headless brick whose update is triggered by an event (control flow). Unlike a `FunctionBrick`, an `ActionBrick` updates on each incoming event, even if an input still has no value.
+ * An `ActionBrick` also provides a specific output to forward the control flow (event).
+ */
+export class ActionBrick extends Brick { }
 
 /**
  * A UI Brick aims to display something on the screen of a UI application.
  */
-export class UIBrick extends Brick {
+export class VisualBrick extends Brick {
+
+    /**
+     * Return the list of properties tags as an ordered array
+     */
+    readonly getProperties: () => string[];
 
     /**
-     * @override
+     * Render an element for the given `context`.
+     * Can return `null` if no element is rendered.
+     *
+     * @param $ the brick context
+     * @param properties property values that have been s
+     * @return the rendered element
      */
-    protected onInit(context: UIContext);
+    protected render($: BrickContext, properties: any[]): Element | null;
 
     /**
-     * @override
+     * Attach the `element` rendered by `render()` to its `parent` (in the DOM).
+     * Must return the function to clear the parent from that element.
+     * That function is called just before the next call to updateParent.
+     *
+     * If the `render()` method returns null, only the clear function of previous call to `updateParent()` will be called.
+     *
+     * @param parent the parent element
+     * @param element the element to attach
+     * @return the function to clear the element from its parent.
      */
-    protected onDestroy(context: UIContext);
+    protected updateParent(parent: Element, element: Element): () => void;
 
     /**
      * Called when the DOM Element associated to that brick has been added to the document and is ready to be drawn.
      *
-     * @param context the brick context
+     * @deprecated override {@link VisualBrick#render} and {@link VisualBrick#updateParent} instead.
+     * @param $ the brick context
      * @param domElement the associated DOM Element
      */
-    draw(context: UIContext, domElement:Element);
+    protected draw($: BrickContext, domElement: Element);
 }
 
+/**
+ * @deprecated use {@link VisualBrick} instead
+ */
+export class UIBrick extends VisualBrick { }
+
 /**
  * Static function that must be called for every brick used in an application.
  * It registers the brick code in the registry with the specified tag and return the Entry for that brick.
@@ -561,9 +689,9 @@ export class Auth {
     static getToken(): string;
 
     /**
-     * Return the SAML token (zipped & base64 encoded XML) for the current user.
+     * Return the IDP token (zipped & base64 encoded XML) for the current user.
      */
-    static getSAMLToken(): string;
+    static getIDPToken(): string;
 
     /**
      * Return the tag of the current authenticated user.
@@ -586,6 +714,7 @@ export class Auth {
      * Try to login using SRP protocol with the specified username and password.
      * Returns a promise resolved when logged in or that catches an error if refused.
      *
+     * @throws {Error} If the provider's configuration is incorrect.
      * @param username the username
      * @param password the password
      */
@@ -595,10 +724,9 @@ export class Auth {
      * Try to login using SAML protocol with the specified username and password.
      * Returns a promise resolved when logged in or that catches an error if refused.
      *
-     * @param username the username
-     * @param password the password
+     * @throws {Error} If the provider's configuration is incorrect.
      */
-    static loginSAML(username: string, password: string): Promise<void>;
+    static loginSAML(): Promise<void>;
 
     /**
      * Try to login using the specified token for the user.
@@ -609,6 +737,13 @@ export class Auth {
      */
     static loginToken(username: string, token: string): Promise<void>;
 
+    /**
+     * Try to login using the configured OpenID Provider.
+     * Returns a promise resolved when logged in or that catches an error if the login is not valid.
+     * @throws {Error} If the provider's configuration is incorrect.
+     */
+    static loginOpenID(): Promise<void>;
+
     /**
      * Log out the current user and invalidate its session token.
      * It returns a promise resolved when the operation is done.
@@ -831,7 +966,7 @@ export enum FollowRule {
 /* *************************
         Transformers
 ************************* */
-declare abstract class Transformer {}
+declare abstract class Transformer { }
 
 export namespace transformers {
     /** @deprecated */
@@ -936,7 +1071,7 @@ export namespace predicates {
 /* *************************
          ValueDefs
 ************************* */
-declare abstract class ValueDef {}
+declare abstract class ValueDef { }
 
 /** @deprecated */
 export namespace valuedefs {
@@ -996,7 +1131,7 @@ export namespace comparators {
     }
 }
 
-interface Operation {}
+interface Operation { }
 
 export class BurstTransaction {
     constructor();