proact.js
ProAct.Actor Class
src/js/core/actor.js:5
ProAct.Actor is the basic observer-observable functionallity in ProAct.js
The actors in ProAct.js form the dependency graph. If some actor listens to changes from another - it depends on it.
The actors can transform the values or events incoming to them.
Every actor can have a parent actor, that will be notified for all the changes on the child-actor, it is something as special observer.
ProAct.Actor is part of the core module of ProAct.js. System.out.println();
Constructor
ProAct.Actor
-
[queueName] -
[transforms]
Parameters:
-
[queueName]String optionalThe name of the queue all the updates should be pushed to.
If this parameter is null/undefined the default queue of flow is used.
If this parameter is not a string it is used as the transforms.
-
[transforms]Array optionalA list of transformation to be used on all incoming chages.
Item Index
Methods
- accumulate
- accumulation
- afterInit
- beforeDestroy
- canClose
- close
- defaultActions
- defaultListeners
- defer
- destroy
- diff
- doClose
- doInit
- filter
- filter
- filtering
- flatMap
- flatMapFirst
- flatMapLast
- flatMapLimited
- fromLambda
- init
- into
- makeCloseListener
- makeErrListener
- makeEvent
- makeListener
- makeListener
- map
- mapping
- off
- offAll
- offClose
- offErr
- on
- onAll
- onClose
- onErr
- out
- reduce
- skip
- skipDuplicates
- skipWhile
- take
- takeWhile
- toProArray
- toProperty
- toStream
- transform
- transforms static
- transformStored
- transformStored
Properties
- BadValue static
- Close static
- constructor
Methods
accumulate
-
initVal -
accumulationFunction
Creates a new ProAct.Actor instance with source this and accumulation the passed accumulation function.
Should be overridden with creating the right actor.
var actor = sourceActor.accumulate(0, function (current, el) {
return current + el;
});or
var actor = sourceActor.accumulate('+');Parameters:
Returns:
A new ProAct.Actor instance with the accumulation applied.
accumulation
-
initVal -
accumulationFunction
Adds an accumulation transformation to this actor.
Accumulation is used to compute a value based on the previous one.
Parameters:
Returns:
this
afterInit
()
protected
Called automatically after initialization of this actor.
By default it changes the state of this to ready.
It can be overridden to define more complex initialization logic.
beforeDestroy
()
protected
Called immediately before destruction.
The idea is to be implemented by extenders to free additional resources on destroy.
canClose
()
protected
Checks if this can be closed.
Defaults to return true.
close
()
ProAct.Actor
Closes this actor => it state becomes closed.
This sends a close event to all the subscribers to closing.
After closing the actor it can't emit events anymore.
Example:
var actor = new ProAct.Actor();
actor.onClose(function () {
console.log('Done!');
});
actor.close(); // We will see 'Done!' on the console output.Returns:
This instance - can be chained.
defaultActions
()
Array | String
protected
A list of actions or action to be used when no action is passed for the methods working with actions.
defaultListeners
()
Object
protected
Generates the initial listeners object. It can be overridden for alternative listeners collections. It is used for resetting all the listeners too.
The default types of listeners are:
{
change: [],
error: [],
close: []
}Returns:
A map containing the default listeners collections.
defer
-
event -
listener
Defers a ProAct.Actor listener.
By default this means that the listener is put into active ProAct.Flow using it's pushOnce method, but it can be overridden.
This method determines the order of actions, triggered by the changes in the data flow.
The default implementation is executing only one update on this Actor per data flow change.
This means that if the Actor depends on other three Actors, and all of them get updated,
it is updated only once with the last update value.
Parameters:
Returns:
this
destroy
()
diff
-
seed -
differ
Creates a new ProAct.Stream with source - this.
It emits the difference between the last update and the current incomming update from the source.
source.diff(0, function(prev, v) {
return v - prev;
});
// source :
// --3---5------6---|->
// diff:
// --3---2------1---|->Parameters:
-
seedObjectA value to pass the
differfunction as previous on the inital notification from the source. -
differFunctionCreates the difference, receives two params - the previous update and the current. It can be skipped - the default
differfunction returns array with two elements - the previous and the curren updates.
doClose
()
protected
This method is called when a close event is pushed to this Actor.
It removes all the subscriptions to the Actor and sets its
state to closed.
Do not call this method; it is private!
doInit
()
protected
Allocating of resources or initializing is done here.
Empty by default.
filter
-
filteringFunction
Creates a new ProAct.Property instance with source this and filtering
the passed filtering function.
When the source changes, the product, may be updated.
TODO On creation if the filter fails, the property keeps the original value. What to do? Also these kinds of properties shouldn't be set manually.
var prop = ProAct.Property.value(4);
var even = sourceActor.filter(function (el) {
return el % 2 == 0;
});
even.get(); // 4
prop.set(5);
even.get(); // 4
prop.set(6);
even.get(); // 6or
var actor = sourceActor.filter('odd');Parameters:
-
filteringFunctionObjectThe filtering function or object with a call method, should return boolean.
Returns:
A new ProAct.Actor instance with the filtering applied.
filter
-
filteringFunction
Creates a new ProAct.Actor instance with source this and filtering the passed filtering function.
Should be overridden with creating the right actor.
var actor = sourceActor.filter(function (el) {
return el % 2 == 0;
});or
var actor = sourceActor.filter('odd');Parameters:
-
filteringFunctionObjectThe filtering function or object with a call method, should return boolean.
Returns:
A new ProAct.Actor instance with the filtering applied.
filtering
-
filteringFunction
Adds a filtering transformation to this actor.
Filtering can be used to filter the incoming update values. For example you can filter by only odd numbers as update values.
Parameters:
-
filteringFunctionObjectThe filtering function or object with a call method, should return boolean.
Returns:
this
flatMap
-
mapper
Creates a new ProAct.Stream with source - this.
For every update incomming from the source, a new Actor is created using the mapper
function. All the updates, emitted by the streams, returned by the mapper are emitted by the
Actor created by flatMap
source.flatMap(function (v) {
return ProAct.seq(100, [v, v +1 ]);
});
// source:
// -1---2----4-----3-----2-----1---->
// flatMap
// -1-2-2-3--4-5---3-4---2-3---1-2-->Parameters:
-
mapperFunctionA function that returns an
ProAct.Actorusing the incomming notification.
flatMapFirst
-
mapper
Creates a new ProAct.Stream with source - this.
For every update comming from this, a new ProAct.Actor is created using the logic
passed through mapper. The first such Actor becomes the source of the Actor, returned by this
method. When it finishes, if a new Actor is emitted, it becomes the source.
source.flatMapLast(function (v) {
return ProAct.seq(100, [v, v + 1, v + 2, v + 3]);
});
// source:
// -1---2----4-----3-----2-----1----|->
// flatMapFirst
// -1-2-3-4--4-5-6-7-----2-3-4-5-|->Parameters:
-
mapperFunctionA function that returns an
ProAct.Actorusing the incomming notification.
flatMapLast
-
mapper
Creates a new ProAct.Stream with source - this.
For every update comming from this, a new ProAct.Actor is created using the logic
passed through mapper. This new Actor becomes the current source of the ProAct.Stream,
returned by this method. The next update will create a new source, which will become
the current one and replace the old one. This is the same as flatMapLimited,
with limit of 1.
source.flatMapLast(function (v) {
return ProAct.seq(100, [v, v + 1, v + 2, v + 3]);
});
// source:
// -1---2----4-----3-----2-----1----|->
// flatMapLast
// -1-2-2-3-44-5-6-3-4-5-2-3-4-1-2-3-4-|->Parameters:
-
mapperFunctionA function that returns an
ProAct.Actorusing the incomming notification.
flatMapLimited
-
mapper -
limit
Creates a new ProAct.Stream with source - this.
For every update incomming from the source, a new Actor is created using the mapper
function. ALl the updates, emitted by the streams, returned by the mapper are emitted by the
Actor created by flatMap. The number of the currently active sources is limited by the
passed limit. All the sources created after the limit is reached are queued and reused as sources later.
fromLambda
-
lambda
Creates a new ProAct.Stream with source - this.
The logic of the stream is implemented through the passed lambda parameter.
TODO The first parameter of the lambda should be called something else and not stream.
source.fromLambda(function (stream, notification) {
stream.trigger(notification);
});
// Just forwards notifications..Parameters:
-
lambdaFunctionA function, with two arguments - the returned by this function stream and notification. For every update comming from
this, the lambda is called with the update and the stream in it. Has thetrigger,triggerErrandtriggerClosemethods.
init
()
into
-
[...]
Links source actors into this actor. This means that this actor is listening for changes from the sources.
A good example is one stream to have another as as source -> if data comes into the source stream, it is passed to the listening too. That way the source stream is plugged into the listening one.
The listeners from makeListener, makeErrListener and makeCloseListener are used.
Chaining actors is very powerful operation. It can be used to merge many source actors into one.
var sourceActor1 = <Actor implementation>;
var sourceActor2 = <Actor implementation>;
var actor = <Actor implementation>;
actor.into(sourceActor1, sourceActor2);
actor.on(function (v) {
console.log(v);
});Now if the any of the source actors is updated, the update will be printed on the console by the actor.
Parameters:
-
[...]Object optionalZero or more source ProAct.Actors to set as sources.
Returns:
this
makeCloseListener
()
Object
protected
Creates the closing listener of this actor.
Every actor should have one closing listener that should pass to other actors.
This listener turns the actor in a observer for closing events.
Should be overriden with specific listener, by default it returns N.
Returns:
The closing listener of this observer.
makeErrListener
()
Object
protected
Creates the error listener of this actor.
Every actor should have one error listener that should pass to other actors.
This listener turns the actor in a observer for errors.
Should be overriden with specific listener, by default it returns N.
Returns:
The error listener of this observer.
makeEvent
-
source
Creates the event to be send to the listeners on update.
The event should be an instance of ProAct.Event.
By default this method returns ProAct.Event.Types/value:property event.
Parameters:
-
sourceProAct.EventThe source event of the event. It can be null
Returns:
The event.
makeListener
()
Object
protected
Creates the listener of this actor.
Every actor should have one listener that should pass to other actors.
This listener turns the actor in a observer.
Should be overriden with specific listener, by default it returns N.
Returns:
The listener of this observer.
makeListener
()
Object
protected
Creates the listener of this ProAct.ArrayCore.
The right array typed events can change this' shell (array).
If a non-event element is passed to the listener, the element is pushed to the shell.
If a value event is passed to the listener, the new value is pushed to the shell.
Returns:
The listener of this ArrayCore.
map
-
mappingFunction
Creates a new ProAct.Actor instance with source this and mapping the passed mapping function.
Should be overridden with creating the right actor.
var actor = sourceActor.map(function (el) {
return el * el;
});or
var actor = sourceActor.map('+');Parameters:
Returns:
A new ProAct.Actor instance with the mapping applied.
mapping
-
mappingFunction
Adds a mapping transformation to this actor.
Mapping transformations just transform one value into another. For example if we get update with the value of 3 and we have mapping transformation that returns the updating value powered by 2, we'll get 9 as actual updating value.
Parameters:
-
mappingFunctionObjectFunction or object with a call method to use as map function.
Returns:
this
off
-
actions -
listener
Removes a listener from the passed action.
If this method is called without parameters, all the listeners for all the actions are removed. The listeners are reset using defaultActions.
Examples are:
Removing a listener:
var listener = function (v) {
console.log(v);
};
actor.on(listener);
actor.off(listener);Or for removing all the listeners attached to an actor:
actor.off();Or for removing all the listeners of a given type attached to an actor:
actor.off('error');Or for removing a listener from different type of actions:
var listener = function (v) {
console.log(v);
};
actor.on(listener);
actor.onErr(listener);
actor.off(['error', 'change'], listener);Parameters:
-
actionsArray | StringThe action/actions to stop listening for. If this parameter is skipped or null/undefined, the actions from defaultActions are used.
The actions can be skipped and on their place as first parameter to be passed the listener.
-
listenerObjectThe listener to detach. If it is skipped, null or undefined all the listeners are removed from this actor.
Returns:
this
offAll
-
listener
Removes all notifications listener from the passed action.
Parameters:
-
listenerObjectThe listener to detach. If it is skipped, null or undefined all the listeners are removed from this actor.
Returns:
this
offClose
-
listener
Removes a close notification listener from the passed action.
This is the same as calling off('close', listener) on an Actor...
Parameters:
-
listenerObjectThe listener to detach. If it is skipped, null or undefined all the listeners are removed from this actor.
Returns:
this
offErr
-
listener
Removes an error listener from the passed action.
This is the same as calling off('error', listener) on an Actor...
Parameters:
-
listenerObjectThe listener to detach. If it is skipped, null or undefined all the listeners are removed from this actor.
Returns:
this
on
-
actions -
listener
Attaches a new listener to this ProAct.Actor.
The listener may be function or object that defines a call method.
actor.on(function (v) {
console.log(v);
});
actor.on('error', function (v) {
console.error(v);
});
actor.on({
call: function (v) {
console.log(v);
}
});Parameters:
-
actionsArray | StringThe action/actions to listen for. If this parameter is skipped or null/undefined, the actions from defaultActions are used.
The actions can be skipped and on their place as first parameter to be passed the listener.
-
listenerObjectThe listener to attach. It must be instance of Function or object with a call method.
Returns:
this
onAll
-
listener
Attaches the passed listener to listen to values, errors and the close notification from this ProAct.Actor.
The listener may be function or object that defines a call method.
Parameters:
-
listenerObjectThe listener to attach. It must be instance of Function or object with a call method.
Returns:
this
onClose
-
listener
Attaches a new close notifcation listener to this ProAct.Actor.
The listener may be function or object that defines a call method.
This is the same as calling on('close', listener) on an Actor...
Parameters:
-
listenerObjectThe listener to attach. It must be instance of Function or object with a call method.
Returns:
this
onErr
-
listener
Attaches a new error listener to this ProAct.Actor.
The listener may be function or object that defines a call method.
This is the same as calling on('error', listener) on an Actor...
Parameters:
-
listenerObjectThe listener to attach. It must be instance of Function or object with a call method.
Returns:
this
out
-
destination
The reverse of into - sets this actor as a source to the passed destination actor.
var sourceActor = <Actor implementation>;
var actor = <Actor implementation>;
sourceActor.out(actor);
actor.on(function (v) {
console.log(v);
});
Now if the any of the source actors is updated, the update will be printed on the console by the actor.Parameters:
-
destinationProAct.ActorThe actor to set as source this to.
Returns:
this
reduce
-
initVal -
accumulationFunction
Generates a new ProAct.Property containing the state of an accumulations.
The value will be updated with every update coming to this actor.
Parameters:
Returns:
A ProAct.Property instance observing this with the accumulation applied.
skip
-
n
Creates a new ProAct.Stream with source - this.
It skips the first n updates incoming from this.
source : --3---4---5--4---3---4---5--|-> skip(3): -------------4---3---4---5--|->
Parameters:
-
nNumberThe number of notifications to skip.
skipDuplicates
-
comparator
Creates a new ProAct.Stream with source - this.
It skips dublicating elements, comming one after another.
source.skipDuplicates();
// source :
// --3---5---5--4---3---3---5--|->
// skipDuplicates:
// --3---5------4---3-------5--|->Parameters:
-
comparatorFunctionA function used to compare the elements. If nothing is passed it defaults to comparing using
===.
skipWhile
-
condition
Creates a new ProAct.Stream with source - this.
It skips notifications from its source, while a condition is true.
source.skipWhile(function (v) {
return v % 2 === 1;
});
// source :
// --3---5---2--4---3---4---5--|->
// skipWhile:
// ----------2--4---3---4---5--|->Parameters:
-
conditionFunctionA condition function, which is called for each of the incoming values While it returns true, the elements are skipped, after it returns false for the first time, the current and all the following values are emitted.
take
-
limit
Creates a new ProAct.Stream with source - this.
It takes the first limit updates incoming from this.
source : --3---4---5--4---3---4---5--|-> skip(3): --3---4---5--|->
Parameters:
-
limitNumberThe number of notifications to emit.
takeWhile
-
condition
Creates a new ProAct.Stream with source - this.
It emits notifications from its source, while a condition is true.
source.takeWhile(function (v) {
return v % 2 === 1;
});
// source :
// --3---5---2--4---3---4---5--|->
// takeWhile:
// --3---5--|->Parameters:
-
conditionFunctionA condition function, which is called for each of the incoming values While it returns true, the elements are emitted, after it returns false for the first time, the stream created by takeWhile closes.
toProArray
()
ProAct.Array
Creates and returns a ProAct.Array instance, which tracks the changes of this. Uses the current queue for queueing changes.
Returns:
A ProAct.Array instance tracking the changes of this.
toProperty
()
Creates a {{{#crossLink "ProAct.Property"}}{{/crossLink}} instance,
dependent on this.
Comes from the proact-properties module.
toStream
()
Turns this ProAct.Actor to a ProAct.Stream.
In reality this method creates a new Stream with source this.
transform
-
transformation
Adds a new transformation to the list of transformations of this actor.
A transformation is a function or an object that has a call method defined. This function or call method should have one argument and to return a transformed version of it. If the returned value is {@link ProAct.Actor.BadValue}, the next transformations are skipped and the updating value/event becomes - bad value.
Every value/event that updates this actor will be transformed using the new transformation.
Parameters:
-
transformationObjectThe transformation to add.
Returns:
this
transforms
-
actor -
val
Transforms the passed val using the transforms method of the passed actor.
Parameters:
-
actorProAct.ActorThe
ProAct.Actorwhich transformations should be used. -
valObjectThe value to transform.
Returns:
The transformed value.
transformStored
-
transformation -
type
Adds a new transformation to the list of transformations of this actor.
A transformation is a function or an object that has a call method defined. This function or call method should have one argument and to return a transformed version of it. If the returned value is BadValue, the next transformations are skipped and the updating value/event becomes - bad value.
Every value/event that updates this actor will be transformed using the new transformation.
This method uses transform, but can read transformation funtion/object stored in the registry (if the proact-dsl module is present) by it's string name.
Parameters:
Returns:
this
transformStored
-
transformation -
type
Adds a new transformation to the list of transformations of this actor.
A transformation is a function or an object that has a call method defined. This function or call method should have one argument and to return a transformed version of it. If the returned value is {@link ProAct.Actor.BadValue}, the next transformations are skipped and the updating value/event becomes - bad value.
Every value/event that updates this actor will be transformed using the new transformation.
The idea of this method is that it just calls transform, but it can be overidden from another module.
TODO Maybe transformStored is a bad name
Parameters:
Returns:
this
Properties
BadValue
Object
final
static
A constant defining bad values or bad events.
Part of the filtering mechainsm; If a transformation returns
a BadValue, based on uncomming event -> the event is skipped.
Close
Object
final
static
A constant defining closing or ending events.
If a transformation returns this value, the actor will be closed.
You can manually close Actors updating them with this constant as an event.