@comunica/core
- Version 2.7.0
- Published
- 138 kB
- 2 dependencies
- MIT license
Install
npm i @comunica/core
yarn add @comunica/core
pnpm add @comunica/core
Overview
Lightweight, semantic and modular actor framework
Index
Variables
Classes
Interfaces
Type Aliases
Variables
variable CONTEXT_KEY_LOGGER
const CONTEXT_KEY_LOGGER: ActionContextKey<Logger>;
variable Logger
const Logger: any;
Deprecated
Logger should be imported from @comunica/types
Classes
class ActionContext
class ActionContext implements IActionContext {}
Implementation of IActionContext using Immutable.js.
constructor
constructor(data?: Record<string, any>);
method delete
delete: <V>(key: IActionContextKey<V>) => IActionContext;
method ensureActionContext
static ensureActionContext: ( maybeActionContext?: IActionContext | Record<string, any>) => IActionContext;
Convert the given object to an action context object if it is not an action context object yet. If it already is an action context object, return the object as-is.
Parameter maybeActionContext
An action context or record. {ActionContext} An action context object.
method get
get: <V>(key: IActionContextKey<V>) => V | undefined;
method getRaw
getRaw: (key: string) => any | undefined;
method getSafe
getSafe: <V>(key: IActionContextKey<V>) => V;
method has
has: <V>(key: IActionContextKey<V>) => boolean;
method hasRaw
hasRaw: (key: string) => boolean;
method keys
keys: () => IActionContextKey<any>[];
method merge
merge: (...contexts: IActionContext[]) => IActionContext;
method set
set: <V>(key: IActionContextKey<V>, value: V) => IActionContext;
method setDefault
setDefault: <V>(key: IActionContextKey<V>, value: V) => IActionContext;
Will only set the value if the key is not already set.
method setRaw
setRaw: (key: string, value: any) => IActionContext;
method toJS
toJS: () => any;
method toString
toString: () => string;
class ActionContextKey
class ActionContextKey<V> implements IActionContextKey<V> {}
Simple implementation of IActionContextKey.
constructor
constructor(name: string);
property name
readonly name: string;
A unique context key name.
class ActionObserver
abstract class ActionObserver<I extends IAction, O extends IActorOutput> {}
An ActionObserver can passively listen to Actor#run inputs and outputs for all actors on a certain bus.
ActionObserver should not edit inputs and outputs, they should be considered immutable.
See Also
Actor
Bus
I The input type of an actor. O The output type of an actor.
constructor
protected constructor(args: IActionObserverArgs<I, O>);
All enumerable properties from the
args
object are inherited to this observer.The observer will NOT automatically subscribe to the given bus when this constructor is called.
Parameter args
Arguments object
Throws
When required arguments are missing.
property bus
readonly bus: Bus<Actor<I, IActorTest, O>, I, IActorTest, O>;
property name
readonly name: string;
method onRun
abstract onRun: ( actor: Actor<I, IActorTest, O>, action: I, output: Promise<O>) => void;
Invoked when an action was run by an actor.
Parameter actor
The action on which the Actor#run method was invoked.
Parameter action
The original action input.
Parameter output
A promise resolving to the final action output.
class Actor
abstract class Actor<I extends IAction, T extends IActorTest, O extends IActorOutput> implements IActorArgs<I, T, O> {}
An actor can act on messages of certain types and provide output of a certain type.
The flow of an actor is as follows: 1. Send a message to Actor#test to test if an actor can run that action. 2. If the actor can reply to the message, let the actor run the action using Actor#run.
An actor is typically subscribed to a bus, using which the applicability to an action can be tested.
See Also
Bus
I The input type of an actor. T The test type of an actor. O The output type of an actor.
constructor
protected constructor(args: IActorArgs<I, T, O>);
All enumerable properties from the
args
object are inherited to this actor.The actor will subscribe to the given bus when this constructor is called.
Parameter args
Arguments object
Parameter
{string} args.name The name for this actor.
Parameter
{Bus<A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput>} args.bus The bus this actor subscribes to.
Throws
When required arguments are missing.
property beforeActors
readonly beforeActors: Actor<I, T, O>[];
property bus
readonly bus: Bus<Actor<I, T, O>, I, T, O>;
property name
readonly name: string;
method deinitialize
deinitialize: () => Promise<any>;
Deinitialize this actor. This should be used for cleaning up things when the application is shut down, such as closing files and removing temporary files.
{Promise} A promise that resolves when the actor has been deinitialized.
method getContextLogger
static getContextLogger: (context: IActionContext) => Logger | undefined;
Get the logger from the given context.
Parameter context
An optional context. {Logger} The logger or undefined.
method getDefaultLogData
protected getDefaultLogData: (context: IActionContext, data?: () => any) => any;
method initialize
initialize: () => Promise<any>;
Initialize this actor. This should be used for doing things that take a while, such as opening files.
{Promise} A promise that resolves when the actor has been initialized.
method logDebug
protected logDebug: ( context: IActionContext, message: string, data?: () => any) => void;
method logError
protected logError: ( context: IActionContext, message: string, data?: () => any) => void;
method logFatal
protected logFatal: ( context: IActionContext, message: string, data?: () => any) => void;
method logInfo
protected logInfo: ( context: IActionContext, message: string, data?: () => any) => void;
method logTrace
protected logTrace: ( context: IActionContext, message: string, data?: () => any) => void;
method logWarn
protected logWarn: ( context: IActionContext, message: string, data?: () => any) => void;
method run
abstract run: (action: I) => Promise<O>;
Run the given action on this actor.
In most cases, this method should not be called directly. Instead, should be called.
Parameter action
The action to run. {Promise} A promise that resolves to the run result.
method runObservable
runObservable: (action: I) => Promise<O>;
Run the given action on this actor AND invokes the Bus#onRun method.
Parameter action
The action to run. {Promise} A promise that resolves to the run result.
method test
abstract test: (action: I) => Promise<T>;
Check if this actor can run the given action, without actually running it.
Parameter action
The action to test. {Promise} A promise that resolves to the test result.
class Bus
class Bus< A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput> implements IBusArgs {}
A publish-subscribe bus for sending actions to actors to test whether or not they can run an action.
This bus does not run the action itself, for that a Mediator can be used.
See Also
Actor
Mediator
A The actor type that can subscribe to the sub. I The input type of an actor. T The test type of an actor. O The output type of an actor.
constructor
constructor(args: IBusArgs);
All enumerable properties from the
args
object are inherited to this bus.Parameter args
Arguments object
Parameter
{string} args.name The name for the bus
Throws
When required arguments are missing.
property actors
protected readonly actors: A[];
property dependencyLinks
protected readonly dependencyLinks: Map<A, A[]>;
property name
readonly name: string;
property observers
protected readonly observers: ActionObserver<I, O>[];
method addDependencies
addDependencies: (dependent: A, dependencies: A[]) => void;
Indicate that the given actor has the given actor dependencies.
This will ensure that the given actor will be present in the bus *before* the given dependencies.
Parameter dependent
A dependent actor that will be placed before the given actors.
Parameter dependencies
Actor dependencies that will be placed after the given actor.
method onRun
onRun: (actor: Actor<I, T, O>, action: I, output: Promise<O>) => void;
Invoked when an action was run by an actor.
Parameter actor
The action on which the Actor#run method was invoked.
Parameter action
The original action input.
Parameter output
A promise resolving to the final action output.
method publish
publish: (action: I) => IActorReply<A, I, T, O>[];
Publish an action to all actors in the bus to test if they can run the action.
Parameter action
An action to publish {IActorReply<A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput>[]} An array of reply objects. Each object contains a reference to the actor, and a promise to its Actor#test result.
method reorderForDependencies
reorderForDependencies: () => void;
Reorder the bus based on all present dependencies.
method subscribe
subscribe: (actor: A) => void;
Subscribe the given actor to the bus. After this, the given actor can be unsubscribed from the bus by calling Bus#unsubscribe.
An actor that is subscribed multiple times will exist that amount of times in the bus.
Parameter actor
The actor to subscribe.
method subscribeObserver
subscribeObserver: (observer: ActionObserver<I, O>) => void;
Subscribe the given observer to the bus. After this, the given observer can be unsubscribed from the bus by calling Bus#unsubscribeObserver.
An observer that is subscribed multiple times will exist that amount of times in the bus.
Parameter observer
The observer to subscribe.
method unsubscribe
unsubscribe: (actor: A) => boolean;
Unsubscribe the given actor from the bus.
An actor that is subscribed multiple times will be unsubscribed only once.
Parameter actor
The actor to unsubscribe {boolean} If the given actor was successfully unsubscribed, otherwise it was not subscribed before.
method unsubscribeObserver
unsubscribeObserver: (observer: ActionObserver<I, O>) => boolean;
Unsubscribe the given observer from the bus.
An observer that is subscribed multiple times will be unsubscribed only once.
Parameter observer
The observer to unsubscribe. {boolean} If the given observer was successfully unsubscribed, otherwise it was not subscribed before.
class BusIndexed
class BusIndexed< A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput> extends Bus<A, I, T, O> {}
A bus that indexes identified actors, so that actions with a corresponding identifier can be published more efficiently.
Multiple actors with the same identifier can be subscribed.
If actors or actions do not have a valid identifier, then this will fallback to the normal bus behaviour.
See Also
Bus
A The actor type that can subscribe to the sub. I The input type of an actor. T The test type of an actor. O The output type of an actor.
constructor
constructor(args: IBusIndexedArgs);
All enumerable properties from the
args
object are inherited to this bus.Parameter args
Arguments object
Parameter
{string} args.name The name for the bus
Throws
When required arguments are missing.
property actionIdentifierFields
protected readonly actionIdentifierFields: string[];
property actorIdentifierFields
protected readonly actorIdentifierFields: string[];
property actorsIndex
protected readonly actorsIndex: Record<string, A[]>;
method getActionIdentifier
protected getActionIdentifier: (action: I) => string;
method getActorIdentifier
protected getActorIdentifier: (actor: A) => string;
method publish
publish: (action: I) => IActorReply<A, I, T, O>[];
method subscribe
subscribe: (actor: A) => void;
method unsubscribe
unsubscribe: (actor: A) => boolean;
class Mediator
abstract class Mediator< A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput> implements IMediatorArgs<A, I, T, O> {}
A mediator can mediate an action over a bus of actors.
It does the following: 1. Accepts an action in Mediator#mediate. 2. Sends the action to the bus to test its applicability on all actors. 3. It _mediates_ over these test results. 4. It selects the _best_ actor. 5. The action is run by the _best_ actor, and the result if returned.
The _mediates_ and _best_ parts are filled in by subclasses of this abstract Mediator class.
A The type of actor to mediator over. I The input type of an actor. T The test type of an actor. O The output type of an actor.
constructor
protected constructor(args: IMediatorArgs<A, I, T, O>);
All enumerable properties from the
args
object are inherited to this mediator.Parameter args
Arguments object
Parameter
{string} args.name The name for this mediator.
Parameter
{Bus<A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput>} args.bus The bus this mediator will mediate over.
Throws
When required arguments are missing.
property bus
readonly bus: Bus<A, I, T, O>;
property name
readonly name: string;
method mediate
mediate: (action: I) => Promise<O>;
Mediate for the given action.
This will send the test action on all actors in the bus. The action will be run on the actor that tests _best_, of which the result will be returned.
Parameter action
The action to mediate for. {Promise<O extends IActorOutput>} A promise that resolves to the mediation result.
method mediateActor
mediateActor: (action: I) => Promise<A>;
Mediate for the given action to get an actor.
This will send the test action on all actors in the bus. The actor that tests _best_ will be returned.
Parameter action
The action to mediate for. {Promise<O extends IActorOutput>} A promise that resolves to the _best_ actor.
method mediateWith
protected abstract mediateWith: ( action: I, testResults: IActorReply<A, I, T, O>[]) => Promise<A>;
Mediate for the given action with the given actor test results for the action.
One actor must be returned that provided the _best_ test result. How '_best_' is interpreted, depends on the implementation of the Mediator.
Parameter action
The action to mediate for.
Parameter testResults
The actor test results for the action. {Promise<A extends Actor<I, T, O>>} A promise that resolves to the _best_ actor.
method publish
publish: (action: I) => IActorReply<A, I, T, O>[];
Publish the given action in the bus.
This will send the test action on all actors in the bus. All actor replies will be returned.
Parameter action
The action to mediate for. {IActorReply<A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput>[]} The list of actor replies.
Interfaces
interface IAction
interface IAction {}
Data interface for the type of action.
property context
context: IActionContext;
The input context that is passed through by actors.
interface IActionObserverArgs
interface IActionObserverArgs<I extends IAction, O extends IActorOutput> {}
interface IActorArgs
interface IActorArgs< I extends IAction, T extends IActorTest, O extends IActorOutput> {}
property beforeActors
beforeActors?: Actor<I, T, O>[];
Actor that must be registered in the bus before this actor.
property bus
bus: Bus<Actor<I, T, O>, I, T, O>;
The bus this actor subscribes to.
property name
name: string;
The name for this actor. {<rdf:subject>}
interface IActorOutput
interface IActorOutput {}
Data interface for the type of an actor run result.
interface IActorReply
interface IActorReply< A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput> {}
Data interface for holding an actor and a promise to a reply from that actor.
interface IActorTest
interface IActorTest {}
Data interface for the type of an actor test result.
interface IBusArgs
interface IBusArgs {}
property name
name: string;
The name for this bus. {<rdf:subject>}
interface IBusIndexedArgs
interface IBusIndexedArgs extends IBusArgs {}
property actionIdentifierFields
actionIdentifierFields: string[];
property actorIdentifierFields
actorIdentifierFields: string[];
interface IMediatorArgs
interface IMediatorArgs< A extends Actor<I, T, O>, I extends IAction, T extends IActorTest, O extends IActorOutput> {}
Type Aliases
type IBus
type IBus< I extends IAction = IAction, O extends IActorOutput = IActorOutput, T extends IActorTest = IActorTest> = Bus<Actor<I, T, O>, I, T, O>;
type IReply
type IReply< I extends IAction = IAction, O extends IActorOutput = IActorOutput, T extends IActorTest = IActorTest> = IActorReply<Actor<I, T, O>, I, T, O>;
type Logger
type Logger = _Logger;
Deprecated
Logger should be imported from @comunica/types
type Mediate
type Mediate< I extends IAction, O extends IActorOutput, T extends IActorTest = IActorTest> = Mediator<Actor<I, T, O>, I, T, O>;
Package Files (8)
Dependencies (2)
Dev Dependencies (0)
No dev dependencies.
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@comunica/core
.
- Markdown[](https://www.jsdocs.io/package/@comunica/core)
- HTML<a href="https://www.jsdocs.io/package/@comunica/core"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 4038 ms. - Missing or incorrect documentation? Open an issue for this package.