mkarkowski/nope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

Adding comments and adapting imports

Browse Source
This commit is contained in:
Martin Karkowski 2022-01-19 18:38:43 +01:00
parent 469e6601ba
commit 79227d5950
13 changed files with 450 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
00-compile.bat
View File

@ -3,6 +3,10 @@ set DIR=%~dp0
cd "%DIR%"
SETLOCAL
echo Compiling Backend
REM Add the Node Options for SSL these are requrired since Node v.17
set NODE_OPTIONS=--openssl-legacy-provider
(npm run-script prettier-format) && (
(npm run-script compile-nodejs) && (
(npm run-script compile-browser) && (

97
lib/dispatcher/ConnectivityManager/ConnectivityManager.ts
View File

@ -96,11 +96,11 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
>;
/**
* Generates the current Status Message of the Dispatcher.
* see {@link INopeConnectivityManager.info}
*
* @author M.Karkowski
* @protected
* @return {*} {IDispatcherInfo} The current status of our dispatcher.
* @readonly
* @type {INopeStatusInfo}
* @memberof NopeConnectivityManager
*/
public get info(): INopeStatusInfo {
@ -178,9 +178,11 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
}
/**
* Creates an instance of nopeDispatcher.
* @param {nopeRpcDispatcherOptions} options The Options, used by the Dispatcher.
* @param {() => INopeObservable<IExternalEventMsg>} _generateObservable A Helper, to generate Observables.
* Creates an instance of NopeConnectivityManager.
* @author M.Karkowski
* @param {INopeINopeConnectivityOptions} options The Options, used by the Manager.
* @param {<T>() => INopeObservable<T>} _generateObservable A Helper, to generate Observables.
* @param {string} [id=null] specific id. Otherwise a ID is generated
* @memberof NopeConnectivityManager
*/
constructor(
@ -231,7 +233,14 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
});
}
// See interface description.
/**
* see {@link INopeConnectivityManager.upTime}
*
* @author M.Karkowski
* @readonly
* @type {number}
* @memberof NopeConnectivityManager
*/
public get upTime(): number {
return Date.now() - this._connectedSince;
}
@ -246,11 +255,23 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
*/
protected __isMaster: boolean = null;
/**
* see {@link INopeConnectivityManager.isMaster}
*
* @author M.Karkowski
* @memberof NopeConnectivityManager
*/
public set isMaster(value: boolean) {
this.__isMaster = value;
}
// See interface description.
/**
* see {@link INopeConnectivityManager.isMaster}
*
* @author M.Karkowski
* @type {boolean}
* @memberof NopeConnectivityManager
*/
public get isMaster(): boolean {
if (this.__isMaster === null) {
const upTime = this.upTime;
@ -264,7 +285,14 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
return this.__isMaster;
}
// See interface description.
/**
* see {@link INopeConnectivityManager.master}
*
* @author M.Karkowski
* @readonly
* @type {INopeStatusInfo}
* @memberof NopeConnectivityManager
*/
public get master(): INopeStatusInfo {
const data = Array.from(this.dispatchers.originalData.values());
@ -284,7 +312,14 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
return masters[0];
}
// See interface description.
/**
* see {@link INopeConnectivityManager.now}
*
* @author M.Karkowski
* @readonly
* @type {number}
* @memberof NopeConnectivityManager
*/
public get now(): number {
return Date.now() + this._deltaTime;
}
@ -406,8 +441,8 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
*
* @author M.Karkowski
* @protected
* @param {string} dispatcher
* @param {boolean} [quite=false]
* @param {string} dispatcher The Id of the dispatcher
* @param {boolean} [quite=false] if set to quite, the *dispatchers* attribute wont be udpated.
* @memberof NopeConnectivityManager
*/
protected _removeDispatcher(dispatcher: string, quite = false): void {
@ -432,18 +467,21 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
/**
* Helper to send the current status to other statusmanagers.
*
* @author M.Karkowski
* @protected
* @memberof NopeConnectivityManager
*/
protected _sendStatus(): void {
this._communicator.emit("StatusChanged", this.info);
}
/**
* Helper function, which will synchronize the Timestamp.
* Timestamp must be provided in UTC (https://www.timeanddate.de/stadt/info/zeitzone/utc)
* see {@link INopeConnectivityManager.syncTime}
*
* @author M.Karkowski
* @param {number} timestamp The UTC-Timestamp
* @param {number} [delay=0] The Delay, since the Timestamp has been generated
* @param {number} timestamp
* @param {number} [delay=0]
* @memberof NopeConnectivityManager
*/
public syncTime(timestamp: number, delay = 0) {
@ -451,14 +489,23 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
this._deltaTime = _internalTimestamp - timestamp - delay / 2;
}
/**
* see {@link INopeConnectivityManager.getStatus}
*
* @author M.Karkowski
* @param {string} id
* @return {*}
* @memberof NopeConnectivityManager
*/
public getStatus(id: string) {
return this._externalDispatchers.get(id);
}
/**
* Helper Function to manually emit a Bonjour!
* see {@link INopeConnectivityManager.emitBonjour}
*
* @return {*} {Promise<void>}
* @author M.Karkowski
* @return {Promise<void>}
* @memberof NopeConnectivityManager
*/
public async emitBonjour(): Promise<void> {
@ -467,8 +514,9 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
}
/**
* Function to reset the Dispatcher.
* see {@link INopeConnectivityManager.reset}
*
* @author M.Karkowski
* @memberof NopeConnectivityManager
*/
public reset(): void {
@ -477,8 +525,7 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
}
/**
* Adapts the Timing Options and resets the internally used
* Timers etc.
* see {@link INopeConnectivityManager.setTimings}
*
* @author M.Karkowski
* @param {Partial<INopeINopeConnectivityTimeOptions>} options
@ -562,7 +609,13 @@ export class NopeConnectivityManager implements INopeConnectivityManager {
}
}
// See interface description
/**
* see {@link INopeConnectivityManager.getAllHosts}
*
* @author M.Karkowski
* @return {*} {string[]}
* @memberof NopeConnectivityManager
*/
public getAllHosts(): string[] {
const hosts = new Set<string>();
for (const info of this.dispatchers.originalData.values()) {

8
lib/dispatcher/ConnectivityManager/index.ts
View File

@ -1,9 +1,11 @@
/**
* @module connectivityManager
* @author Martin Karkowski
* @email m.karkowski@zema.de
* @create date 2022-01-04 13:31:35
* @modify date 2022-01-04 13:33:29
* @desc [description]
*
* # NopeConnectivityManager
*
*
*/
export {

74
lib/dispatcher/index.ts
View File

@ -1,18 +1,80 @@
/**
* @module dispatcher
* @author Martin Karkowski
* @email m.karkowski@zema.de
* @create date 2021-08-27 19:49:25
* @modify date 2021-09-04 07:48:28
* @desc [description]
* # NoPE - Dispatcher
*
*The NoPE-Dispatcher is designed as Layer between the different Modules / Dispatchers. They allow distributed computing or just a simple ***Service oriented Architecture*** (*SOA*). A dispatcher is used to link the modules, share data and events and provide a remote procedure call (rpc) interface.
*
*## Building Blocks of a Dispatcher:
*
*| element | description |
*|-|-|
*| `connectivityManager`: {@link connectivityManager} | establishes a connection to other dispatchers and manages the status of the remotely connected dispatchers. It checks their health and removes dead dispatchers. |
*| `eventDistributor`: {@link PubSubSystem} | shares events accross the network (or internally). You can use this element to listen for specific events. The subscription to those events allows `mqtt`-patterns. Additionaly, you are allowed to emit event on specific topics, or pattern based topics |
*| `dataDistributor`: {@link DataPubSubSystem} | shares data accross the network (or internally). In comperisson to events, data is persistent and is available all the time. You can use this sub-module to listen for specific data-changes (install data-hooks), pull specific data or push data. You can pull / push data using a `mqtt`-pattern based path. |
*| `rpcManager`: {@link rpcManager} | Used to perform `remote procedure calls` (see [here](https://de.wikipedia.org/wiki/Remote_Procedure_Call)). The manager keeps track of the available services. You must use the sub-module to register/unregister (new) services. |
*| `instanceManager`: {@link instanceManager} | Used to create/dispose (remote) instances. The manager keeps track of the available instances in the network, allows to create `wrappers` for those instances. You must use the sub-module to register/unregister (new) instances. To allow the system to provide a service for creating instances of as specific type, you can provide a generator and provide it as `service`. |
*
*## Create a Dispatcher
*
*To start exploring the capabilities of the dispatcher we will firstly create a dispatcher with the code below:
*
*
*```javascript
* // First lets install nope using npm
* const nope = require("../dist-nodejs/index.nodejs")
*
* // Lets create our dispatcher
* const dispatcher = nope.dispatcher.getDispatcher({
* // We will use the event layer (which just runs internally)
* communicator: nope.getLayer("event"),
*
* // We will adapt the timings (normally, we send a hartbeat and check for dead dispatchers)
* timings: {
*
* // Interval for the alive message given in [ms]. If "0" is provided,
* // no alive messages are provided
* sendAliveInterval: 0,
*
* // Interval, to check the other dispatcher for being slow, dead, etc..
* // should be lager then the "sendAliveInterval". The value is given in [ms]
* // If "0" is provided, no alive messages are provided
* checkInterval: 0
*
* }
* });
*```
*
*## Settings for creating:
*
*The relevant Settings are described by the {@link INopeDispatcherOptions}. This options allows to define:
* * the communication bridge. (use `getLayer` to receive a bridge with the specified layer)
* * define a specific `id`
* * provide a logger (otherwise the dispatcher wont log anything)
* * define the timings for `heartbeats` and `checks` (see {@link INopeINopeConnectivityTimeOptions} for more details)
* * a `defaultSelector` which is used as selector for a service provide
*
*## Playing with the dispatcher:
*
*To play with a dispatcher, you can use the `nope-js` repl tool. this tool creates a `dispatcher` and you are able to interact with the dispatcher in an interactive console.
*
*
*/
import * as baseServices from "./baseServices";
import * as connectivityManager from "./ConnectivityManager";
import * as instanceManager from "./InstanceManager";
import * as rpcManager from "./RpcManager";
export {
exportFunctionToDispatcher,
nopeEmitter,
nopeProperty,
nopeMethod,
IExportFunctionToDispatcherParameters,
nopeEmitter,
nopeMethod,
nopeProperty,
} from "../decorators/index";
export * from "../types/nope/nopeDispatcher.interface";
export { getDispatcher } from "./getDispatcher";
export { getLinkedDispatcher } from "./getLinkedDispatcher";
export { baseServices, connectivityManager, instanceManager, rpcManager };

10
lib/index.browser.ts
View File

@ -9,24 +9,30 @@
import "reflect-metadata";
import * as communcation from "./communication/index.browser";
import * as dispatcher from "./dispatcher/index";
import * as decorators from "./decorators";
import * as eventEmitter from "./eventEmitter";
import * as helpers from "./helpers/index.browser";
import * as loader from "./loader/index.browser";
import * as logger from "./logger/index.browser";
import * as modules from "./module/index";
import * as observables from "./observables/index";
import * as promises from "./promise/index";
import * as promise from "./promise/index";
import * as pubSub from "./pubSub";
import * as types from "./types/index";
export { getLayer } from "./communication/index.browser";
export * from "./logger/index.browser";
export {
communcation,
decorators,
dispatcher,
eventEmitter,
helpers,
loader,
logger,
types,
modules,
observables,
promises,
promise,
pubSub,
};

35
lib/index.nodejs.ts
View File

@ -7,30 +7,21 @@
*/
import "reflect-metadata";
import * as communcation from "./communication/index.nodejs";
import * as dispatcher from "./dispatcher/index";
import * as helpers from "./helpers/index.nodejs";
import * as loader from "./loader/index.nodejs";
import * as logger from "./logger/index.nodejs";
import * as modules from "./module/index";
import * as observables from "./observables/index";
import * as promises from "./promise/index";
import * as types from "./types/index";
export * as communcation from "./communication/index.nodejs";
export * as decorators from "./decorators";
export * as dispatcher from "./dispatcher";
export * as eventEmitters from "./eventEmitter";
export * as helpers from "./helpers/index.nodejs";
export * as loader from "./loader/index.nodejs";
export * from "./logger/index.nodejs";
export * as logger from "./logger/index.nodejs";
export * as modules from "./module/index";
export * as observables from "./observables";
export * as promises from "./promise";
export * as pubSub from "./pubSub";
export * as types from "./types";
export {
readInArgs as readInRunNopeBackendArgs,
runNopeBackend,
} from "./cli/runNopeBackend";
export { getLayer } from "./communication/index.nodejs";
export * from "./logger/index.nodejs";
export {
communcation,
dispatcher,
helpers,
loader,
logger,
types,
modules,
observables,
promises,
};

141
lib/observables/index.ts
View File

@ -1,9 +1,144 @@
/**
* @module observables
* @author Martin Karkowski
* @email m.karkowski@zema.de
* @create date 2021-08-27 20:29:38
* @modify date 2021-08-27 20:29:38
* @desc [description]
*
* # Observables
*
* ## Usage of `nope.observables`
*
* Import Nope.
*
* ```typescript
* import * as nope from "nope";
* ```
*
* In our nodebook, we have to use **javascript** instead of **typescript**:
*
* ```javascript
* // First lets install nope using npm
* const nope = require("../dist-nodejs/index.nodejs");
*
* // Create our Observable:
* const obs = new nope.observables.NopeObservable();
* ```
* ### `setContent`: Change the content of the Observable.
*
* To change the content of an observable use the function `setContent`.
*
* ```javascript
* // Set the content to "1337"
* obs.setContent(5);
*
* // Print the content (see getContent)
* console.log("current value =", obs.getContent());
* ```
*
* > ` current value = 5`
*
* #### `setter`: Define a specific setter for the observable.
*
* You can specify a specifc getter for the observable for instance, to limit the number to the following constrains `> 0` and `< 10`.
*
*
* The setter function will receive multiple parameters, as listed below:
*
* 1. `value`,
* 2. `options` containing:
* - `sender`: The Element, which changed the data
* - `timestamp`: The timestamp of the change
* - `args`: additional args.
*
*
*
* The setter function have to return a `dict` with the following keys:
*
* | key | type | content |
* | - | - | - |
* | `valid` | `bool` | A Flag, to show whether the data are valid or not. If the data is invalid, the observable wont store them |
* | `value` | `any` | The Data that has been adapted |
*
*
*
* Below, we will implement an example to show the setter above.
*
* ```javascript
* obs.setter = (value, options) => {
* // Print, which data we received
* console.log("setter received", value, options);
* // Show the result of our comparison
* console.log("data is valid:", value > 0 && value < 10);
* return {
* // The Value
* value: value,
* // Valid
* valid: value > 0 && value < 10,
* };
* };
*
* // Set the content to "1337" ==> But our setter will prevent using this value because it isnt valid.
* obs.setContent(1337);
*
* // Print the content (see getContent) ==> we expect to get "5"
* console.log("current value =", obs.getContent());
* ```
*
* > ```
* > setter received 1337 {}
* > data is valid: false
* > current value = 5
* > ```
*
* To remove such a getter just set the getter property to `null`.
*
* ```javascript
* obs.setter = null;
*
* // Set the content to "1337" we do not have any setter ==> we will use this parameter
* obs.setContent(1337);
*
* // Print the content (see getContent) ==> we expect to get "1337"
* console.log("current value =", obs.getContent());
* ```
*
* > `current value = 1337`
*
* ### `getContent`: Get the current content of the Observable.
*
* To extract the content of our observable, we are able to use the function `getContent`
*
* ```javascript
* let content = obs.getContent();
* console.log("current value =", content);
* ```
*
* > `current value = 1337`
*
* If no data is assigned, this will result in `undefined`. Otherwise the current data is returned.
*
* #### `getter`: Define a specific getter for the observable.
*
* You can specify a specifc getter for the observable for instance, to allways return a `string`
*
* ```javascript
* // Define a getter
* obs.getter = (value) => "Allways this result";
* console.log("current value (with getter) =", obs.getContent());
* ```
*
* > `current value (with getter) = Allways this result`
*
* To remove such a getter just set the getter property to `null`.
*
* The Original value is not changed ==> we expect to get "1337"
*
* ```javascript
* // Reset the getter.
* obs.getter = null;
* console.log("current value (after removing the getter) =", obs.getContent());
* ```
*
* > `current value (after removing the getter) = 1337`
*/
export * from "../types/nope/nopeObservable.interface";

8
lib/types/nope/nopeDispatcher.interface.ts
View File

@ -11,14 +11,14 @@ import { ICommunicationBridge } from "./nopeCommunication.interface";
import {
IHost,
INopeINopeConnectivityTimeOptions,
INopeStatusInfo
INopeStatusInfo,
} from "./nopeConnectivityManager.interface";
import { INopeCore } from "./nopeCore.interface";
import { INopeDescriptor } from "./nopeDescriptor.interface";
import {
IEventAdditionalData,
IEventCallback,
INopeObserver
INopeObserver,
} from "./nopeEventEmitter.interface";
import { INopeModule, INopeModuleDescription } from "./nopeModule.interface";
import { INopeObservable } from "./nopeObservable.interface";
@ -33,7 +33,7 @@ export type IGenerateRemoteInstanceCallback<I extends INopeModule> = (
) => Promise<I>;
export type IGenerateRemoteInstanceForOtherDispatcherCallback<
I extends INopeModule
> = (dispatcher: INopeDispatcher, identifier: string, ...args) => Promise<I>;
> = (dispatcher: INopeDispatcher, identifier: string, ...args) => Promise<I>;
export type IValidPromise<T> = Promise<T> | INopePromise<T>;
@ -102,7 +102,7 @@ export interface IHostOverview extends IHost {
}
export interface IDispatcherConstructor {
new(
new (
options: INopeDispatcherOptions,
_generateObservable: <T>() => INopeObservable<T>
): INopeDispatcher;

0
wiki/00-Getting-Started copy.md → wiki/00-Getting-Started.md
View File

83
wiki/11-Observables.ipynb
View File

@ -18,7 +18,7 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
@ -40,9 +40,17 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 2,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"current value = 5\n"
]
}
],
"source": [
"// Set the content to \"1337\"\n",
"obs.setContent(5);\n",
@ -84,9 +92,19 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 3,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"setter received 1337 {}\n",
"data is valid: false\n",
"current value = 5\n"
]
}
],
"source": [
"obs.setter = (value, options) => {\n",
" // Print, which data we received\n",
@ -117,9 +135,17 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 4,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"current value = 1337\n"
]
}
],
"source": [
"obs.setter = null\n",
"\n",
@ -140,9 +166,17 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 5,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"current value = 1337\n"
]
}
],
"source": [
"let content = obs.getContent();\n",
"console.log(\"current value =\", content)"
@ -161,9 +195,17 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 6,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"current value (with getter) = Allways this result\n"
]
}
],
"source": [
"// Define a getter\n",
"obs.getter = (value) => \"Allways this result\";\n",
@ -181,14 +223,29 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 7,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"current value (after removing the getter) = 1337\n"
]
}
],
"source": [
"// Reset the getter.\n",
"obs.getter = null;\n",
"console.log(\"current value (after removing the getter) =\", obs.getContent());"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {

56
wiki/12-Dispatcher.ipynb
View File

@ -25,9 +25,30 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 2,
"metadata": {},
"outputs": [],
"outputs": [
{
"ename": "SyntaxError",
"evalue": "Identifier 'nope' has already been declared",
"output_type": "error",
"traceback": [
"evalmachine.<anonymous>:1",
"// First lets install nope using npm",
"^",
"",
"SyntaxError: Identifier 'nope' has already been declared",
" at Script.runInThisContext (node:vm:129:12)",
" at Object.runInThisContext (node:vm:305:38)",
" at run ([eval]:1054:15)",
" at onRunRequest ([eval]:888:18)",
" at onMessage ([eval]:848:13)",
" at process.emit (node:events:390:28)",
" at emit (node:internal/child_process:915:12)",
" at processTicksAndRejections (node:internal/process/task_queues:84:21)"
]
}
],
"source": [
"// First lets install nope using npm\n",
"const nope = require(\"../dist-nodejs/index.nodejs\")\n",
@ -60,9 +81,33 @@
" checkInterval: 0\n",
" \n",
" }\n",
"});\n",
"console.log(dispatcher)"
"});"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Settings for creating:\n",
"\n",
"The relevant Settings are described by the `INopeDispatcherOptions`. This options allows to define:\n",
"* the communication bridge. (use `getLayer` to receive a bridge with the specified layer)\n",
"* define a specific `id`\n",
"* provide a logger (otherwise the dispatcher wont log anything)\n",
"* define the timings for `heartbeats` and `checks` (see `INopeINopeConnectivityTimeOptions` for more details)\n",
"* a `defaultSelector` which is used as selector for a service provide\n",
"\n",
"## Playing with the dispatcher:\n",
"\n",
"To play with a dispatcher, you can use the `nope-js` repl tool. this tool creates a `dispatcher` and you are able to interact with the dispatcher in an interactive console."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
@ -76,8 +121,7 @@
"mimetype": "application/javascript",
"name": "javascript",
"version": "17.3.1"
},
"orig_nbformat": 4
}
},
"nbformat": 4,
"nbformat_minor": 2