@olympeio/runtime-node 9.10.4 → 9.11.0

package/types/runtime.d.ts

@@ -1,24 +1,8 @@
-// **********************************
-// Runtime classes
-// **********************************
+import { CloudObject, InstanceOrTag } from "./data";
+import { Context } from "./other";
+import { Property } from "./composition";
 // @ts-ignore
-import {Observable} from 'rxjs';
-import {CloudObject, Context, Property, InstanceOrTag} from "./base";
-import {ErrorFlow} from "./utils";
-
-/**
- * Label of global properties used by convention through bricks and applications.
- * Example of use:
- *
- *    const transaction = context.get(TRANSACTION).
- *
- * The brick "Begin Transaction" push a transaction inside the context so it can be reused by other bricks before the "End Transaction" brick.
- */
-export enum GlobalProperties {
-    EDITION = '__editionMode',
-    PRODUCTION = '__production',
-    TRANSACTION = '__transaction'
-}
+import { Observable } from "rxjs";
 
 export class BrickContext extends Context {
     /**
@@ -162,16 +146,6 @@ export class BrickContext extends Context {
     onContext(id: string, callback: (context: BrickContext) => void): () => void;
 }
 
-/**
- * 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.
- *
- * @param tag the brick unique id
- * @param brick the brick class
- * @param args Extra arguments
- */
-export function registerBrick(tag: string, brick: new () => Brick, ...args: any): void;
-
 export abstract class Brick extends CloudObject {
 
     /**
@@ -233,13 +207,13 @@ export abstract class Brick extends CloudObject {
     protected destroy($: BrickContext): void;
 
     /**
-     * @deprecated use {@apilink Brick.init} instead
+     * @deprecated use {@link Brick.init} instead
      * @param $ the brick context
      */
     protected onInit($: BrickContext): void;
 
     /**
-     * @deprecated use {@apilink Brick.update} instead
+     * @deprecated use {@link Brick.update} instead
      * @param $ the brick context
      * @param inputs array of input values
      * @param outputs array of output setter functions.
@@ -247,14 +221,14 @@ export abstract class Brick extends CloudObject {
     protected onUpdate($: BrickContext, inputs: Array<any>, outputs: Array<(value: any) => void>): void;
 
     /**
-     * @deprecated use {@apilink Brick.destroy} instead
+     * @deprecated use {@link Brick.destroy} instead
      * @param $ the brick context
      */
     protected onDestroy($: BrickContext): void;
 }
 
 /**
- * @deprecated use {@apilink Brick} instead
+ * @deprecated use {@link Brick} instead
  */
 export abstract class ActionBrick extends Brick { }
 
@@ -294,9 +268,49 @@ export abstract class VisualBrick extends Brick {
     /**
      * Called when the DOM Element associated to that brick has been added to the document and is ready to be drawn.
      *
-     * @deprecated override {@apilink VisualBrick.render} and {@apilink VisualBrick.updateParent} instead.
+     * @deprecated override {@link VisualBrick.render} and {@link VisualBrick.updateParent} instead.
      * @param $ the brick context
      * @param domElement the associated DOM Element
      */
     protected draw($: BrickContext, domElement: Element);
 }
+
+// -- Configuration --
+export class Config {
+    /**
+     * Return the value of the specified parameter.
+     * Parameters can get their values from the oConfig.json file or be overridden from the URL / command that opened the application.
+     *
+     * @param id the parameter id
+     */
+    static getParameter(id: string): unknown | undefined;
+}
+
+
+/**
+ * Error type used to propagate errors through flows between bricks.
+ */
+export class ErrorFlow extends Error {
+    /**
+     * Create a new Error object to be sent in an error flow
+     *
+     * @param message the error message
+     * @param code the code associated to the error
+     */
+    static create(message: string, code: number): ErrorFlow;
+
+    /**
+     * Return the message of this error
+     */
+    getMessage(): string;
+
+    /**
+     * Return the code associated to this error
+     */
+    getCode(): number;
+
+    /**
+     * Return the stack with the hierarchy of bricks that run the one having thrown the error.
+     */
+    getStack(): string;
+}

package/types/service.d.ts

@@ -0,0 +1,183 @@
+import { Context } from "./other";
+// @ts-ignore
+import { Observable } from "rxjs";
+
+/**
+ * Types of requests that can be received in a Service.
+ * This is used to know what method call on the request to answer the requester.
+ */
+export enum ServiceRequestType {
+    PUBLISH,
+    SEND,
+    GET,
+    SUBSCRIBE
+}
+
+/**
+ * A request consumed by a service.
+ */
+export class ServiceRequest {
+
+    /**
+     * Get the requesting client's user tag.
+     *
+     * @return the user tag
+     */
+    userTag(): Promise<string>;
+
+    /**
+     * Return the type of this Service Request
+     *
+     * @return the type of this request.
+     */
+    requestType(): ServiceRequestType;
+
+    /**
+     * Get the request body.
+     *
+     * @return the request body
+     */
+    body(): Object;
+
+    /**
+     * Acknowledge the request. Used for SEND requests
+     *
+     * @return a Promise that completes once the ack is sent
+     */
+    ack(): Promise<void>;
+
+    /**
+     * Send a reply to the request with a content payload. Used for GET requests
+     *
+     * @param payload the payload of the reply
+     * @return a Promise that completes once the reply is sent
+     */
+    reply(payload: Object): Promise<void>;
+
+    /**
+     * Send the topic where the requester should listen to get notifications. Used for OBSERVE requests.
+     * The string returned by the Promise is the id of that subscription. It can be used in parallel with
+     * the {@link Service.setUnsubscriptionHandler} method of the service to execute instructions when a subscription is removed.
+     *
+     * @param topic the topic where the client should
+     * @return a Promise that completes once the consumer has started to the listen to notifications. The
+     */
+    notifyOn(topic: string): Promise<string>;
+
+    /**
+     * Reply to the request with and error.
+     *
+     * @param error the error to send
+     * @return a Promise that completes once the error is sent
+     */
+    fail(error: Error): Promise<void>;
+}
+
+interface ServiceConfig {
+    /**
+     * After how much time (in ms) the message must be considered as timeout by the service.
+     */
+    timeout?: number
+}
+
+interface SubscriptionServiceConfig extends ServiceConfig {
+    /**
+     * A callback to be called in case the subscription to the service is re-sent to the service (eg: after a reconnection).
+     */
+    onRetry?: () => void;
+}
+
+/**
+ * A service that processes requests coming from other VMs connected to the data cloud.
+ */
+export class Service {
+
+    /**
+     * Create a new instance of the service with the specified id.
+     * It uses the context to make the lifecycle of the service related to the context one.
+     *
+     * @param serviceId the service id
+     * @param context the context of that service.
+     */
+    constructor(serviceId: string, context: Context);
+
+    /**
+     * Start and listen to incoming requests.
+     */
+    listen(): Observable<ServiceRequest>;
+
+    /**
+     * Set a function to be executed each time a subscription to that service is closed.
+     * The function receives the subscription id that has been closed.
+     * The subscription id is the one that has been set and returned by the {@link ServiceRequest.notifyOn} method.
+     *
+     * @param handler the handler function to be executed when a subscription is closed.
+     * @return this Service instance.
+     */
+    setUnsubscriptionHandler(handler: (subId: string) => void): this
+
+    /**
+     * Stop the service.
+     */
+    stop(): void
+
+    /**
+     * Publish a message on the specified service without waiting for any acknowledge
+     *
+     * @param service the service id
+     * @param payload
+     */
+    static publish(service: string, payload: Object): Promise<void>;
+
+    /**
+     * Returns a Publisher to publish a list of messages to the same service handler, to ensure the messages published
+     * are processed by the same processor instead of being balanced between the potential multiple instances of the service.
+     *
+     * @param service the service id
+     */
+    static getPublisher(service: string): Publisher;
+
+    /**
+     * Send a request to a {@link Service} and wait for an ack.
+     *
+     * @param service the service id
+     * @param payload the message payload, optional
+     * @param config optional parameters for the message
+     * @return a Promise that completes when the call has been executed
+     */
+    static send(service: string, payload?: Object, config?: ServiceConfig): Promise<void>;
+
+    /**
+     * Send a request to a {@link Service} and wait for a reply with a payload..
+     *
+     * @param service the service id
+     * @param payload the message payload
+     * @param config optional parameters for the message
+     * @return a Promise wrapping the resulting value
+     */
+    static get(service: string, payload: Object, config?: ServiceConfig): Promise<Object>;
+
+    /**
+     * Send a request to a {@link Service} and subscribe to notifications published from that service.
+     *
+     * @param service the service id
+     * @param context the context used to link its lifecycle to this subscription
+     * @param payload the message payload, optional
+     * @param config optional parameters for the message
+     * @return an Observable emitting notifications
+     */
+    static observe(service: string, context: Context, payload?: Object, config?: SubscriptionServiceConfig): {observable: Observable<Object>, publisher: Publisher};
+}
+
+/**
+ * A publisher is used to send messages to a subscription handler.
+ */
+export interface Publisher {
+
+    /**
+     * Publish a message to the subscription handler.
+     *
+     * @param payload the message payload
+     */
+    publish(payload: Object): Promise<void>;
+}

package/types/transaction-advanced.d.ts

@@ -0,0 +1,34 @@
+import { CloudObject } from "./data";
+import { Property } from "./composition";
+// @ts-ignore
+import { Observable } from "rxjs";
+
+/**
+ * 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
+ * is designed to handle many updates per second for smooth shared animations.
+ *
+ * Example of use:
+ * A marker representing a red dot on the screen which coordinate properties are controlled by motion sensors of an IoT device
+ * should use BurstTransaction instead of a bunch of continuous classical Transaction to have fluid movements on the screen.
+ */
+export class BurstTransaction {
+    constructor();
+
+    /**
+     * Push all property values from specified Observable to update specified object
+     *
+     * @param object the object to update
+     * @param values observable mapping properties to new values
+     */
+    push<T>(object: CloudObject, values: Observable<Map<Property<T>, T>>): void;
+
+    /**
+     * Commit and close the burst transaction
+     *
+     * @return A `Promise` completing with commit success/failure
+     */
+    complete(): Promise<void>;
+}

package/types/transaction.d.ts

@@ -0,0 +1,266 @@
+import { BrickContext } from "./runtime";
+import { CloudObject, InstanceOrTag } from "./data";
+import { Property, Relation } from "./composition";
+import { Source } from "./data-connector";
+
+
+// ---------------------------
+// -- Database transactions --
+// ---------------------------
+
+/**
+ * Transactions are the unique way to apply a list of operations to the datacloud.
+ * 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.
+ * - Update instance property: update an existing node in the database.
+ * - Delete instance: delete a node from the database. Delete only works if all the relations are removed too. Cascade delete can be activated.
+ * - Create relation: create a relation of a specific type between 2 existing node.
+ * - Delete relation: remove the specified relation between 2 specified nodes.
+ *
+ * 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.
+ *
+ * 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 {
+
+    /**
+     * Create a new transaction object.
+     *
+     * @param persist if set to `true`, will persist to the data source the objects {@link Transaction.create} created in that transaction. (Default = `true`)
+     */
+    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 ({@link {PredefinedDataSource.SERVER}}), local ({@link {PredefinedDataSource.SELF}}) or
+     * an external data source (tag of DBConnector). 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: InstanceOrTag, properties?: Map<InstanceOrTag, any>, source?: Source, 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: InstanceOrTag, property?: Property<T>, value?: T): this;
+
+    /**
+     * Update multiple properties of a single instance
+     *
+     * @param instance tag of the instance to be updated
+     * @param properties map of properties to update
+     * @return this transaction
+     */
+    multiUpdate(instance: InstanceOrTag, properties: Map<InstanceOrTag, any>): this;
+
+    /**
+     * Delete an instance
+     *
+     * @param instance tag of the instance to be deleted
+     * @return this transaction
+     */
+    delete(instance: InstanceOrTag): 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: InstanceOrTag, from: InstanceOrTag, to: InstanceOrTag): 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: InstanceOrTag, from: InstanceOrTag, to: InstanceOrTag): 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: InstanceOrTag): this;
+
+    /**
+     * Set the specified instance to be persisted or not in this transaction.
+     * Default value of persist is true.
+     *
+     * @param instance the instance to be persisted
+     * @param persist determine if the specified instance should be persisted or not (true by default).
+     * @return this transaction
+     */
+    persist(instance: InstanceOrTag, persist?: boolean): this;
+
+    /**
+     * Change the persistence mode for a single instance in this transaction
+     *
+     * @deprecated use {@link Transaction.persist} instead
+     * @param instance the instance to be persisted
+     * @param persist the persisting mode
+     * @return this transaction
+     */
+    persistInstance(instance: InstanceOrTag, persist?: boolean): this;
+
+    /**
+     * Change the source of all instances created in this transaction
+     *
+     * `source` can be specified as :
+     * 1. a predefined source type {@link {PredefinedDataSource}}
+     * 2. an external data source (Tag of a `DBConnector`)
+     *
+     * 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: Source): 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: InstanceOrTag): string | null;
+
+    /**
+     * 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 data sources. Return the transaction result if succeeds.
+     *
+     * @return promise resolving with the corresponding TransactionResult if the transaction succeeds,
+     * rejecting if the transaction fails
+     */
+    execute(): Promise<TransactionResult>;
+
+    /**
+     * Execute atomically a transaction at the data source and returns the transaction result if succeeds.
+     * The `large` mode sends the transaction over HTTP, this has the following incidence:
+     * - Quicker processing of transaction
+     * - Allows transactions with no limit of size
+     * - Cannot be used when logged as Guest
+     *
+     * @return promise resolving with the corresponding TransactionResult if the transaction succeeds,
+     * rejecting if the transaction fails.
+     */
+    executeAsLarge(): Promise<TransactionResult>;
+
+    /**
+     * 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>;
+}
+
+
+/**
+ * A transaction result is the object received after a transaction has been executed successfully.
+ * It provides information about what has been done.
+ */
+export class TransactionResult {
+
+    /**
+     * Return the ordered list of CloudObjects created in this transaction.
+     *
+     * @return the list of CloudObjects instances
+     */
+    getCreatedObjects(): CloudObject[];
+}