@comunica/core - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

index.d.ts

 export * from './lib/Bus';
+export * from './lib/ActionObserver';
 export * from './lib/Actor';
+export * from './lib/Logger';
 export * from './lib/Mediator';

index.js

@@ -7,4 +7,6 @@ "use strict";
 __export(require("./lib/Bus"));
+__export(require("./lib/ActionObserver"));
 __export(require("./lib/Actor"));
+__export(require("./lib/Logger"));
 __export(require("./lib/Mediator"));
 //# sourceMappingURL=index.js.map

lib/Actor.d.ts

@@ -0,2 +1,4 @@
+import { Map } from "immutable";
 import { Bus } from "./Bus";
+import { Logger } from "./Logger";
 /**
@@ -34,2 +36,8 @@ * An actor can act on messages of certain types and provide output of a certain type.
     /**
+     * Get the logger from the given context.
+     * @param {ActionContext} context An optional context.
+     * @return {Logger} The logger or null.
+     */
+    static getContextLogger(context: ActionContext): Logger;
+    /**
      * Check if this actor can run the given action,
@@ -45,2 +53,5 @@ * without actually running it.
      *
+     * In most cases, this method should not be called directly.
+     * Instead, {@link #runObservable} should be called.
+     *
      * @param {I} action The action to run.
@@ -51,2 +62,10 @@ * @return {Promise<T>} A promise that resolves to the run result.
     /**
+     * Run the given action on this actor
+     * AND invokes the {@link Bus#onRun} method.
+     *
+     * @param {I} action The action to run.
+     * @return {Promise<T>} A promise that resolves to the run result.
+     */
+    runObservable(action: I): Promise<O>;
+    /**
      * Initialize this actor.
@@ -67,2 +86,9 @@ * This should be used for doing things that take a while,
     deinitialize(): Promise<any>;
+    protected getDefaultLogData(context: ActionContext, data?: any): any;
+    protected logTrace(context: ActionContext, message: string, data?: any): void;
+    protected logDebug(context: ActionContext, message: string, data?: any): void;
+    protected logInfo(context: ActionContext, message: string, data?: any): void;
+    protected logWarn(context: ActionContext, message: string, data?: any): void;
+    protected logError(context: ActionContext, message: string, data?: any): void;
+    protected logFatal(context: ActionContext, message: string, data?: any): void;
 }
@@ -74,5 +100,37 @@ export interface IActorArgs<I extends IAction, T extends IActorTest, O extends IActorOutput> {
 /**
+ * An immutable key-value mapped context that can be passed to any (@link IAction}.
+ * All actors that receive a context must forward this context to any actor, mediator or bus that it calls.
+ * This context may be transformed before forwarding.
+ *
+ * Each bus should describe in its action interface which context entries are possible (non-restrictive)
+ * and expose a `KEY_CONTEXT_${ENTRY_NAME}` constant for easy reuse.
+ * If actors support any specific context entries next to those inherited by the bus action interface,
+ * then this should be described in its README file.
+ *
+ * To avoid entry conflicts, all keys must be properly namespaced using the following convention:
+ *   Each key must be prefixed with the package name followed by a `:`.
+ *   For example, the `rdf-resolve-quad-pattern` bus declares the `sources` entry,
+ *   which should be named as `@comunica/bus-rdf-resolve-quad-pattern:sources`.
+ *
+ * This context can contain any information that might be relevant for certain actors.
+ * For instance, this context can contain a list of datasources over which operators should query.
+ */
+export declare type ActionContext = Map<string, any>;
+/**
+ * A convenience constructor for {@link ActionContext} based on a given hash.
+ * @param {{[p: string]: any}} hash A hash that maps keys to values.
+ * @return {ActionContext} The immutable action context from the hash.
+ * @constructor
+ */
+export declare function ActionContext(hash: {
+    [key: string]: any;
+}): ActionContext;
+/**
  * Data interface for the type of action.
  */
 export interface IAction {
+    /**
+     * The optional input context that is passed through by actors.
+     */
+    context?: ActionContext;
 }
@@ -79,0 +137,0 @@ /**

lib/Actor.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const immutable_1 = require("immutable");
+const Logger_1 = require("./Logger");
 /**
@@ -36,2 +38,22 @@ * An actor can act on messages of certain types and provide output of a certain type.
     /**
+     * Get the logger from the given context.
+     * @param {ActionContext} context An optional context.
+     * @return {Logger} The logger or null.
+     */
+    static getContextLogger(context) {
+        return context ? context.get(Logger_1.KEY_CONTEXT_LOG) : null;
+    }
+    /**
+     * Run the given action on this actor
+     * AND invokes the {@link Bus#onRun} method.
+     *
+     * @param {I} action The action to run.
+     * @return {Promise<T>} A promise that resolves to the run result.
+     */
+    runObservable(action) {
+        const output = this.run(action);
+        this.bus.onRun(this, action, output);
+        return output;
+    }
+    /**
      * Initialize this actor.
@@ -56,4 +78,58 @@ * This should be used for doing things that take a while,
     }
+    /* Proxy methods for the (optional) logger that is defined in the context */
+    getDefaultLogData(context, data) {
+        if (!data) {
+            data = {};
+        }
+        data.actor = this.name;
+        return data;
+    }
+    logTrace(context, message, data) {
+        const logger = Actor.getContextLogger(context);
+        if (logger) {
+            logger.trace(message, this.getDefaultLogData(context, data));
+        }
+    }
+    logDebug(context, message, data) {
+        const logger = Actor.getContextLogger(context);
+        if (logger) {
+            logger.debug(message, this.getDefaultLogData(context, data));
+        }
+    }
+    logInfo(context, message, data) {
+        const logger = Actor.getContextLogger(context);
+        if (logger) {
+            logger.info(message, this.getDefaultLogData(context, data));
+        }
+    }
+    logWarn(context, message, data) {
+        const logger = Actor.getContextLogger(context);
+        if (logger) {
+            logger.warn(message, this.getDefaultLogData(context, data));
+        }
+    }
+    logError(context, message, data) {
+        const logger = Actor.getContextLogger(context);
+        if (logger) {
+            logger.error(message, this.getDefaultLogData(context, data));
+        }
+    }
+    logFatal(context, message, data) {
+        const logger = Actor.getContextLogger(context);
+        if (logger) {
+            logger.fatal(message, this.getDefaultLogData(context, data));
+        }
+    }
 }
 exports.Actor = Actor;
+/**
+ * A convenience constructor for {@link ActionContext} based on a given hash.
+ * @param {{[p: string]: any}} hash A hash that maps keys to values.
+ * @return {ActionContext} The immutable action context from the hash.
+ * @constructor
+ */
+function ActionContext(hash) {
+    return immutable_1.Map(hash);
+}
+exports.ActionContext = ActionContext;
 //# sourceMappingURL=Actor.js.map

lib/Bus.d.ts

@@ -0,1 +1,2 @@
+import { ActionObserver } from "./ActionObserver";
 import { Actor, IAction, IActorOutput, IActorTest } from "./Actor";
@@ -20,2 +21,3 @@ /**
     protected readonly actors: A[];
+    protected readonly observers: ActionObserver<I, O>[];
     /**
@@ -39,2 +41,11 @@ * All enumerable properties from the `args` object are inherited to this bus.
     /**
+     * Subscribe the given observer to the bus.
+     * After this, the given observer can be unsubscribed from the bus by calling {@link Bus#unsubscribeObserver}.
+     *
+     * An observer that is subscribed multiple times will exist that amount of times in the bus.
+     *
+     * @param {ActionObserver<I, O>} observer The observer to subscribe.
+     */
+    subscribeObserver(observer: ActionObserver<I, O>): void;
+    /**
      * Unsubscribe the given actor from the bus.
@@ -50,2 +61,12 @@ *
     /**
+     * Unsubscribe the given observer from the bus.
+     *
+     * An observer that is subscribed multiple times will be unsubscribed only once.
+     *
+     * @param {ActionObserver<I, O>} observer The observer to unsubscribe.
+     * @return {boolean} If the given observer was successfully unsubscribed,
+     *         otherwise it was not subscribed before.
+     */
+    unsubscribeObserver(observer: ActionObserver<I, O>): boolean;
+    /**
      * Publish an action to all actors in the bus to test if they can run the action.
@@ -60,2 +81,10 @@ *
     publish(action: I): IActorReply<A, I, T, O>[];
+    /**
+     * Invoked when an action was run by an actor.
+     *
+     * @param actor               The action on which the {@link Actor#run} method was invoked.
+     * @param {I}          action The original action input.
+     * @param {Promise<O>} output A promise resolving to the final action output.
+     */
+    onRun(actor: Actor<I, T, O>, action: I, output: Promise<O>): void;
 }
@@ -62,0 +91,0 @@ export interface IBusArgs {

lib/Bus.js

@@ -28,2 +28,3 @@ "use strict";
         this.actors = [];
+        this.observers = [];
         require('lodash.assign')(this, args);
@@ -43,2 +44,13 @@ }
     /**
+     * Subscribe the given observer to the bus.
+     * After this, the given observer can be unsubscribed from the bus by calling {@link Bus#unsubscribeObserver}.
+     *
+     * An observer that is subscribed multiple times will exist that amount of times in the bus.
+     *
+     * @param {ActionObserver<I, O>} observer The observer to subscribe.
+     */
+    subscribeObserver(observer) {
+        this.observers.push(observer);
+    }
+    /**
      * Unsubscribe the given actor from the bus.
@@ -61,2 +73,19 @@ *
     /**
+     * Unsubscribe the given observer from the bus.
+     *
+     * An observer that is subscribed multiple times will be unsubscribed only once.
+     *
+     * @param {ActionObserver<I, O>} observer The observer to unsubscribe.
+     * @return {boolean} If the given observer was successfully unsubscribed,
+     *         otherwise it was not subscribed before.
+     */
+    unsubscribeObserver(observer) {
+        const index = this.observers.indexOf(observer);
+        if (index >= 0) {
+            this.observers.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
      * Publish an action to all actors in the bus to test if they can run the action.
@@ -75,4 +104,16 @@ *
     }
+    /**
+     * Invoked when an action was run by an actor.
+     *
+     * @param actor               The action on which the {@link Actor#run} method was invoked.
+     * @param {I}          action The original action input.
+     * @param {Promise<O>} output A promise resolving to the final action output.
+     */
+    onRun(actor, action, output) {
+        for (const observer of this.observers) {
+            observer.onRun(actor, action, output);
+        }
+    }
 }
 exports.Bus = Bus;
 //# sourceMappingURL=Bus.js.map

lib/Mediator.js

@@ -80,3 +80,3 @@ "use strict";
         const actor = await this.mediateActor(action);
-        return actor.run(action);
+        return actor.runObservable(action);
     }
@@ -83,0 +83,0 @@ }

package.json

 {
   "name": "@comunica/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Lightweight, semantic and modular actor framework",
@@ -8,4 +8,7 @@ "lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/@comunica/core",
   "lsd:contexts": {
-    "https://linkedsoftwaredependencies.org/contexts/comunica-core.jsonld": "components/context.jsonld"
+    "https://linkedsoftwaredependencies.org/bundles/npm/@comunica/core/^1.0.0/components/context.jsonld": "components/context.jsonld"
   },
+  "lsd:importPaths": {
+    "https://linkedsoftwaredependencies.org/bundles/npm/@comunica/core/^1.0.0/components/": "components/"
+  },
   "main": "index.js",
@@ -40,2 +43,3 @@ "engines": {
   "dependencies": {
+    "immutable": "^3.8.2",
     "lodash.assign": "^4.2.0"
@@ -45,7 +49,4 @@ },
     "transform": {
-      "^.+\\.ts$": "<rootDir>/../../node_modules/ts-jest/preprocessor.js"
+      "^.+\\.ts$": "ts-jest"
     },
-    "transformIgnorePatterns": [
-      "[/\\\\]node_modules[/\\\\].+\\.(js|jsx)$"
-    ],
     "testRegex": "(/test/.*|(\\.|/)(test|spec))\\.ts$",
@@ -52,0 +53,0 @@ "moduleFileExtensions": [

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

37520

increased by67.48%

Number of package files

21

increased by40%

Lines of code

801

increased by76.04%

Worsened metrics

Dependency count

2

increased by100%

Dependency changes

• + Addedimmutable@^3.8.2

• + Addedimmutable@3.8.2(transitive)