@olympeio/runtime-node 9.10.5 → 9.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olympeio/runtime-node",
-  "version": "9.10.5",
+  "version": "9.11.1",
   "description": "Olympe Node Runtime Environment",
   "types": "types/index.d.ts",
   "dependencies": {
@@ -8,7 +8,8 @@
     "bufferutil": "~4.0.8",
     "utf-8-validate": "~6.0.4",
     "rxjs": "~7.8.1",
-    "fastify": "~4.28.1"
+    "fastify": "~5.2.1",
+    "@cloudamqp/amqp-client": "3.2.0"
   },
   "codeAsData": "import",
   "author": "Olympe S.A. <dev@olympe.ch>",

package/types/composition.d.ts

@@ -0,0 +1,122 @@
+import { Brick } from "./runtime";
+import { Class } from "./other";
+import { CloudObject, InstanceOrTag } from "./data";
+
+/**
+ * Generates a unique olympe tag used to identify `CloudObjects`
+ *
+ * @return {string} tag
+ */
+export function generateTag(): string;
+
+/**
+ * Get the unique identifier of the specified InstanceOrTag 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: InstanceOrTag): string;
+
+/**
+ * The HasTag interface defines objects that have a tag.
+ * The tag of these objects must be returned by the overridden method: `getTag()`
+ */
+export interface HasTag {
+    /**
+     * @return tag of this instance
+     */
+    getTag(): string;
+}
+
+/**
+ * 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 to B and can be followed in either direction.
+ */
+export enum Direction {
+    /**
+     * For relation A to B, go to A, the origin
+     */
+    ORIGIN = '<',
+    /**
+     * For relation A to B, go to B, the destination
+     */
+    DESTINATION = '>'
+}
+
+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: InstanceOrTag, 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: InstanceOrTag, 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>;
+}
+
+
+
+/**
+ * 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;

package/types/data-connector.d.ts

@@ -0,0 +1,356 @@
+import { BrickContext } from "./runtime";
+import { CloudObject, InstanceOrTag } from "./data";
+import { Order, Query } from "./query";
+import { Property, Relation } from "./composition";
+// @ts-ignore
+import { Readable } from "node:stream";
+
+export type FollowRule = Property<number>;
+
+
+
+/**
+ * Predefined data sources that can be used for {@link Transaction.setSource}.
+ */
+export enum PredefinedDataSource {
+    /**
+     * Local DataSource. By using this source, objects are not persisted
+     */
+    SELF = 'self',
+    /**
+     * Embedded Graph Database
+     */
+    SERVER = 'server'
+}
+
+/**
+ * When manipulating CloudObjects, sometimes it is required to manually set the data source of that object.
+ * `Source` determines where the object comes from: what data source is the owner of the object across the ecosystem.
+ */
+
+export type Source = PredefinedDataSource | string;
+
+/**
+ * A class representing the necessary operations to create the result of a query in the client database
+ * that emitted the query.
+ */
+export class DataResult {
+
+    /**
+     * Create a new {@link DataResult} instance from the specified {@link Query}.
+     * @param query The {@link Query} to create a {@link DataResult} from.
+     * @return A new {@link DataResult} instance.
+     */
+    static fromQuery(query: Query<CloudObject, any>): DataResult;
+
+    /**
+     * Create a new Data Type instance with the specified {@link InstanceOrTag}, Data Type and properties.
+     * @param tag The unique identifier of the object instance to create.
+     * @param model The Data Type of the instance to create.
+     * @param properties The properties to set on the instance.
+     * @return This {@link DataResult} instance.
+     */
+    create(tag: InstanceOrTag, model: InstanceOrTag, properties?: Map<InstanceOrTag, any>): this;
+
+    /**
+     * Create a relation between two instances with the specified {@link Relation}, `from`, and `to` instance tags.
+     * @param relation The type of relation to create.
+     * @param from The unique identifier of the source instance.
+     * @param to The unique identifier of the destination instance.
+     * @return This {@link DataResult} instance.
+     */
+    createRelation(relation: InstanceOrTag, from: InstanceOrTag, to: InstanceOrTag): this;
+}
+
+/**
+ * Represents an operation that can be performed regarding data type instances.
+ */
+export type Operation =
+    {
+        /** Creates a new instance of a data type with the given properties. */
+        type: 'CREATE',
+        /** The tag of the new instance. */
+        object: string,
+        /** The data type tag of the instance being created. */
+        model: string,
+        /** A map that maps the tag of a property to a new/updated value.
+         *  You may need to parse this value to store it in your data source (e.g. JS date)
+         * */
+        properties?: Map<string, any>
+    } |
+    {
+        /** Updates an existing instance of a data type with the given properties. */
+        type: 'UPDATE',
+        /** The tag of the instance being updated. */
+        object: string,
+        /** The data type tag of the instance being updated. */
+        model: string,
+        /** A map that maps the tag of a property to a new/updated value.
+         *  You may need to parse this value to store it in your data source (e.g. JS date)
+         * */
+        properties: Map<string, any>
+    } |
+    {
+        /** Deletes an existing instance of a data type. */
+        type: 'DELETE',
+        /** The tag of the instance being deleted. */
+        object: string,
+        /** The data type tag of the instance being deleted. */
+        model: string
+    } |
+    {
+        /** Creates a new relation between two instances of a data type. */
+        type: 'CREATE_RELATION',
+        /** The tag of the relation being created. */
+        relation: string,
+        /** The tag of the starting instance. */
+        from: string,
+        /** The tag of the ending instance. */
+        to: string,
+        /** The data type tag of the starting instance. */
+        fromModel: string,
+        /** The data type tag of the ending instance. */
+        toModel: string
+    } |
+    {
+        /** Deletes an existing relation between two instances of a data type. */
+        type: 'DELETE_RELATION',
+        /** The tag of the relation being deleted. */
+        relation: string,
+        /** The tag of the starting instance. */
+        from: string,
+        /** The tag of the ending instance. */
+        to: string,
+        /** The data type tag of the starting instance. */
+        fromModel: string,
+        /** The data type tag of the ending instance. */
+        toModel: string
+    };
+/**
+ * Details for a predicate from the OLYMPE query API
+ */
+export type ParsedPredicate =
+    {
+        /** Checks if the instance has any of the specified tags. */
+        name: 'IS',
+        /** An array of tags to check against. */
+        tags: string[]
+    } |
+    {
+        /** Checks if a string type property contains a specific string value. */
+        name: 'CONTAINS',
+        /** The tag of the property being checked. */
+        property: string,
+        /** The value being searched for. */
+        value: string,
+        /** Whether the search should be case-sensitive or not. */
+        caseSensitive: boolean
+    } |
+    {
+        /** Checks if a property equals a specific value. */
+        name: 'EQUALS',
+        /** The tag of the property being checked. */
+        property: string,
+        /** The value being compared to. */
+        value: any
+    } |
+    {
+        /** Checks if a property is greater than or less than a specific value. */
+        name: 'INEQUALITY_OPERATOR',
+        /** The tag of the property being compared. */
+        property: string,
+        /** The value being compared to. */
+        value: any,
+        /** The operator being used in the comparison (e.g. `<`, `>`). */
+        operator: string,
+        /** Whether the comparison should be strict (e.g. "\<" vs. "\<="). */
+        strict: boolean
+    } |
+    {
+        /** Negates a predicate. */
+        name: 'NOT',
+        /** The predicate being negated. */
+        predicate: ParsedPredicate
+    } |
+    {
+        /** Checks if a property matches a regular expression pattern. */
+        name: 'REGEX',
+        /** The tag of the property being checked. */
+        property: string,
+        /** The regular expression pattern being matched. */
+        pattern: RegExp,
+        /** Whether the matching should be case-sensitive or not. */
+        caseSensitive: boolean
+    };
+
+
+/**
+ * The first part of a {@link Query}.
+ * It breaks down the starting point of the query.
+ */
+export interface RootQueryPart extends QueryPart {
+    /**
+     * The tag of the starting point of a query built using {@link Query.from()}
+     * It is the tag of the instance where the first relation followed using {@link Query.follow()} starts from.
+     * For queries on instances of a data type, started with  {@link Query.instancesOf()}, this will be null.
+     */
+    root?: string
+    /**
+     * The tag of the Data Type of the instance(s) determining the starting point of the query.
+     * It is the tag of the Data Type provided to {@link Query.instancesOf()}, or the Data Type of the root instance provided
+     * to {@link Query.from()}
+     */
+    dataType: string
+    /**
+     * Specifies whether instances of the data types inheriting from the root data type should be included in the query or not.
+     * It is always `false` if `root` is specified.
+     */
+    inheritance: boolean
+    /**
+     * Limits the number of results retrieved by the query.
+     */
+    limit: number
+    /**
+     * Skips a specified number of results retrieved by the query.
+     */
+    offset: number
+}
+
+/**
+ * A part of a {@link Query} that specifies a relationship to traverse.
+ */
+export interface QueryPart {
+    /**
+     * Determines whether the relationship should be traversed recursively and whether the starting object should be included.
+     * `false`: Traverse the relationship once.
+     * `'EXCLUDE_SELF'`: Traverse the relationship recursively, excluding the starting object.
+     * `'INCLUDE_SELF'`: Traverse the relationship recursively, including the starting object.
+     */
+    recursive: false | 'EXCLUDE_SELF' | 'INCLUDE_SELF',
+    /**
+     * Specifies a relationship to traverse in the query.
+     */
+    relation: Relation<any, any>
+    /**
+     * Determines whether the relationship this part specifies is optional or not to traverse.
+     * If `true`, result tuples may have a null if this relationship can not be followed from some data objects.
+     * If `false`, all result tuples must contain this relationship.
+     */
+    optional: boolean,
+    /**
+     * Determines whether the related objects should be included in the result tuples.
+     * If `true`, related objects will be included.
+     * If `false`, the related objects are not included.
+     * This does not impact whether the relationship is `optional` to be traversed.
+     */
+    returned: boolean,
+    /**
+     * Specify if the instances obtained by following the relation should satisfy some condition
+     * See {@link ParsedPredicate}
+     */
+    filter: ParsedPredicate[][],
+    /**
+     * Set a sorting order on the result tuples according to the related objects.
+     * It will sort using native order of the type of the property.
+     * For multiple parts with sort information, the latest part will prevail.
+     */
+    sort?: {property: Property<any>, order: Order}
+    /**
+     * Returns the remaining {@link QueryPart}s of the query, empty if no {@link QueryPart}s are left.
+     */
+    next: QueryPart[]
+}
+
+/**
+ * Represents a data source that can be used to retrieve, manipulate and store data outside the Olympe application environment.
+ * This class provides several methods for performing CRUD (create, read, update, delete) operations on data,
+ * as well as file upload and download functionality.
+ *
+ * To create a new data source, add a _Data Connector_ in your project in DRAW and download the boilerplate.
+ * Then implement or extend the required methods: `init`, `destroy`, `healthCheck`, `executeQuery` and `applyTransaction`
+ * For file capabilities, you must also implement: `uploadFileContent`, `downloadFileContent` and `deleteFileContent`
+ *
+ * The CORE library already provide some default connectors such as PostgreSQL and MSSQL.
+ * Their implementation is open source and available in [CORE on Github](https://github.com/olympeio/CORE/tree/master/src/core/data/connectors).
+ *
+ * @abstract
+ * @extends {@link CloudObject}
+ */
+export abstract class DataSource extends CloudObject {
+
+    /**
+     * Returns the tag of the data source.
+     * @return tag of the data source.
+     */
+    getId(): string;
+
+    /**
+     * Retrieves the configuration value associated with the provided key in the data source oConfig.
+     * @param key - Key to retrieve the configuration value for.
+     * @return The configuration value associated with the provided key.
+     */
+    getConfig(key: string): any;
+
+    /**
+     * Initializes the data source connection with custom parameters provided in oConfig.
+     * It can also perform a health check to ensure the connection is active.
+     * Subscribes to the {@link DataSource.observeDataTypes} observable to handle changes to the data types in the data source.
+     *
+     * @param context a context with the same livecycle as the Data Source
+     * @return A promise that resolves with void when initialization is complete. Reject if initialization did not complete.
+     */
+    protected init(context: BrickContext): Promise<void>;
+
+    /**
+     * Performs a health check on the data source, checking if the connection is alive.
+     * @return A Promise that resolves when the health check is completed successfully, rejects otherwise.
+     */
+    protected healthCheck(): Promise<void>;
+
+    /**
+     * Disconnects the data source.
+     * @return A Promise that resolves when the data source is destroyed.
+     */
+    protected destroy(): Promise<void>;
+
+    /**
+     * Executes the provided {@link Query} once and returns a {@link DataResult}.
+     * @param query - The {@link Query} object to execute.
+     * @return A Promise that resolves with the {@link DataResult} object.
+     */
+    protected executeQuery(query: Query<CloudObject, any>): Promise<DataResult>;
+
+    /**
+     * Applies the provided {@link Operation} array to the data source as one transaction
+     * @param transaction - The {@link Operation} array to apply.
+     * @param options the options
+     * @param options.batch if true, it means that the transaction has been executed using the {@link Transaction.executeAsLarge()} function.
+     * @return A Promise that resolves when the transaction is completed. Rejects when the transaction fails.
+     */
+    protected applyTransaction(transaction: Operation[], options?: {batch: boolean}): Promise<void>;
+
+    /**
+     * Uploads one file's content to the data source.
+     * @param fileTag - The tag of the file.
+     * @param dataType - The file data type
+     * @param binary - The binary data of the file.
+     * @return A Promise that resolves when the file content is uploaded. Rejects otherwise.
+     */
+    protected uploadFileContent(fileTag: string, dataType: string, binary: Uint8Array): Promise<void>;
+
+    /**
+     * Downloads one file's content from the data source.
+     * @param fileTag - The tag of the file.
+     * @param dataType - The file data type
+     * @return A Promise that resolves with the binary data of the file as an Uint8Array or a node Readable Stream. Rejects otherwise.
+     */
+    protected downloadFileContent(fileTag: string, dataType: string): Promise<Uint8Array | Readable>;
+
+    /**
+     * Deletes file content from the data source.
+     * @param fileTag - The tag of the file.
+     * @param dataType - The file data type
+     * @return A Promise that resolves when the file content is successfully deleted. Rejects otherwise.
+     */
+    protected deleteFileContent(fileTag: string, dataType: string): Promise<void>;
+}