ProAct.ArrayCore Class
Constructs a ProAct.ArrayCore
. ProAct.ArrayCore
is a ProAct.Core that manages all the updates/listeners for an ProAct.Array
.
It is responsible for updating length or index listeners and adding the right ones on read.
ProAct.ArrayCore
is part of the proact-arrays
module of ProAct.js.
Constructor
ProAct.ArrayCore
-
array
-
meta
Parameters:
-
array
ObjectThe shell ProAct.Array arround this core.
-
meta
ObjectOptional meta data to be used to define the observer-observable behavior of the array.
Item Index
Methods
- accumulate
- accumulation
- actionFunction
- addCaller
- afterInit
- beforeDestroy
- call
- canClose
- close
- defaultActions
- defaultListeners
- defer
- defineIndexProp
- destroy
- diff
- doClose
- doInit
- filter
- filtering
- flatMap
- flatMapFirst
- flatMapLast
- flatMapLimited
- fromLambda
- indexListener
- init
- into
- makeCloseListener
- makeErrListener
- makeEvent
- makeListener
- map
- mapping
- off
- offAll
- offClose
- offErr
- on
- onAll
- onClose
- onErr
- out
- prob
- reduce
- setup
- skip
- skipDuplicates
- skipWhile
- take
- takeWhile
- toProArray
- toProperty
- toStream
- transform
- transformStored
- updateByDiff
- updateSplice
- value
Properties
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
actionFunction
-
fun
Generates function wrapper around a normal function which sets the indexListener of the index calling the function.
This is used if the array is complex - contains other ProAct.js objects, and there should be special updates for their elements/properties.
Parameters:
-
fun
FunctionThe source function.
Returns:
The action function wrapper.
addCaller
-
type
Uses currentCaller to automatically add a new listener to this property if the caller is set.
This method is used by the index getters or the length getter to make every reader of the length/index a listener to it.
Parameters:
-
type
StringIf the caller should be added as an 'index' listener or a 'length' listener. If skipped or null it is added as both.
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.
call
-
event
ProAct.Core
can be used as a parent listener for its managed
ProAct.Actors, so it defines the call method.
By default this method calls update with this and the passed event.
Parameters:
-
event
ObjectThe value/event that this listener is notified for.
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
protected
A list of actions or action to be used when no action is passed for the methods working with actions.
For ProAct.ArrayCore
these are both 'length' and 'index' actions.
defaultListeners
()
Object
protected
Generates the initial listeners object. It is used for resetting all the listeners too.
For ProAct.ArrayCore
the default listeners object is
{ index: [], length: [] }
Returns:
A map containing the default listeners collections (index and length type of listeners).
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
defineIndexProp
-
i
Defines accessors for index of this' shell array.
For an index on every read, the currentCaller is added as an 'index' listener.
addCaller is used to retrieve the current caller and add it as the right listener.
Setting values for an index updates the 'index' listeners.
If on the index is reciding an array or an object, it is turned to reactive object/array.
Parameters:
-
i
NumberThe index to define accessor for.
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:
-
seed
ObjectA value to pass the
differ
function as previous on the inital notification from the source. -
differ
FunctionCreates the difference, receives two params - the previous update and the current. It can be skipped - the default
differ
function 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.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:
-
filteringFunction
ObjectThe 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:
-
filteringFunction
ObjectThe 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:
-
mapper
FunctionA function that returns an
ProAct.Actor
using 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:
-
mapper
FunctionA function that returns an
ProAct.Actor
using 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:
-
mapper
FunctionA function that returns an
ProAct.Actor
using 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:
-
lambda
FunctionA 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
,triggerErr
andtriggerClose
methods.
indexListener
-
i
Generates listener for given index or reuses already generated one.
This listener mimics a property listener, the idea is - if anything is listening to index changes in this' shell (array) and the shell is complex - has elements that are ProAct.js objects, if some of this element has property change, its notification should be dispatched to all the objects, listening to index changes in the array.
So this way we can listen for stuff like array.[].foo - the foo property change for every element in the array.
Parameters:
-
i
NumberThe index.
Returns:
A listener mimicing a property one.
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
-
eventData
Creates the event to be send to the listeners on update.
By default this method returns ProAct.Event.Types/array:property event.
Parameters:
-
source
ProAct.EventThe source event of the event. It can be null
-
eventData
ArrayAn array of four elements describing the changes:
- ProAct.Array.Operations member defining the changing operation - for example add
- The index on which the chage occures.
- The old values beginning from the index.
- The new values beginning from the index.
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.
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:
-
mappingFunction
ObjectFunction 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:
-
actions
Array | 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.
-
listener
ObjectThe 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:
-
listener
ObjectThe 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:
-
listener
ObjectThe 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:
-
listener
ObjectThe 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:
-
actions
Array | 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.
-
listener
ObjectThe 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:
-
listener
ObjectThe 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:
-
listener
ObjectThe 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:
-
listener
ObjectThe 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:
-
destination
ProAct.ActorThe actor to set as source this to.
Returns:
this
prob
()
ProAct.Core
Initializes this ProAct.Core. This method should be called when the core should become active.
The main idea of the method is to change the ProAct.States state of this to ready, by settuping everything needed by the shell to has observer-observable logic.
The abstract setup method is called for the actual setup. If it throws an error, this state is set to error and the core stays inactive.
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.
setup
()
protected
Initializes all the index accessors and the length accessor for this's shell array.
For the length on every read, the currentCaller is added as a 'length' listener.
For every index on every read, the currentCaller is added as an 'index' listener. Listener accessors are defined using defineIndexProp.
addCaller is used to retrieve the current caller and add it as the right listener.
Setting values for an index or the length updates the right listeners.
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:
-
n
NumberThe 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:
-
comparator
FunctionA 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:
-
condition
FunctionA 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:
-
limit
NumberThe 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:
-
condition
FunctionA 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:
-
transformation
ObjectThe transformation to add.
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
updateByDiff
-
array
Special update method for updating listeners by comparrison to another array.
For every difference between this shell's array and the passed one, there will be listeners notification.
Parameters:
-
array
ArrayThe array to compare to.
Returns:
this
updateSplice
-
index
-
spliced
-
newItems
Special update method for updating listeners after a splice call.
Depending on the changes the index listeners, the length listeners or both can be notified.
Parameters:
Returns:
this
value
()
Object
A function to be set to the shell object's p field (if it is configured in ProAct.Configuration.
This function is the link to the this ProAct.Core of the shell. It can be overridden to return different aspects of the core depending on parameters passed.
Returns:
Some aspects of this ProAct.Core
.