@comunica/core

  • Version 2.5.1
  • 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

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 {}

    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> {}

                              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[];
                                                          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> {}

                                                                                      property bus

                                                                                      bus: Bus<Actor<I, IActorTest, O>, I, IActorTest, O>;
                                                                                      • The bus this observer can subscribe to.

                                                                                      property name

                                                                                      name: string;
                                                                                      • The name for this observer. {<rdf:subject>}

                                                                                      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.

                                                                                        property actor

                                                                                        actor: A;

                                                                                          property reply

                                                                                          reply: Promise<T>;

                                                                                            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
                                                                                                    > {}

                                                                                                      property bus

                                                                                                      bus: Bus<A, I, T, O>;
                                                                                                      • The bus this mediator will mediate over.

                                                                                                      property name

                                                                                                      name: string;
                                                                                                      • The name for this mediator. {<rdf:subject>}

                                                                                                      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 onejsDocs.io badgeto 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
                                                                                                              [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](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>