Olympe SDK

Namespace: df

olympe. df

Core DataFlow namespace. Contains all the classes and methods related to building and interacting with basic data-flows. A data flow is a graph of connected nodes. When one node changes (i.e. its value changed) all its downstream nodes are notified of the new value so they can process it. If their own value changes as a result of this, then they notify their own downstream nodes, and so on and so forth, until the graph stabilises (i.e. no more changes in nodes).

See Introduction to data flows for an overview.

The two core classes in this namespace are Node and Proxy.

Classes

AbstractList
AbstractMap
AnimatedFlowSource
Color
FlowSource
FunctionSignature
List
Map
OBoolean
ONumber
OString
Proxy
RootContext
SimpleContext
SlotManager
Vector2

Members

<package, static> Config :string

DF Config

Type:
  • string
Properties:
Name Type Default Description
NODE_CREATION_THRESHOLD string df.nodeCreationThreshold

<static> currentExecutingNode :olympe.df.ExecutionContext|undefined

Stores the current executing node, that is the node used as creator node.

Type:

<static> Enumerable :function

Type:
  • function

<static> logger :olympe.logging.Channel|undefined

Used by the DF module, will be injected at runtime by the container.

Type:
  • olympe.logging.Channel | undefined

<static> rootExecutingNode :olympe.df.ExecutionContext|undefined

Stores the root node, that is the node at the top of the nodes tree.

Type:

Methods

<static> createFlowSource(valueType, callback [, debugName])

Creates a Flow Source of a specified type. A flow source is a special type of node that gets its value from an external source, like a timer or a UI event. This methods takes a simple callback that will be provided an instance of the FlowSource interface. Calling update from this object will update the value of the node.

Example:

const rng = olympe.df.createFlowSource(olympe.df.ONumber, (source) => {
       setInterval(
           () => { source.update(olympe.df.oNumber(Math.floor(Math.random() * 100) + 1)); },
           1000
       );
       }
);

Creates a data flow that generates a new random number every second.

Parameters:
Name Type Argument Default Description
valueType function

The type of the data flow
callback olympe.df.FlowSourceCallback.<T>

The initialisation callback that will receive the updater
debugName string <optional>
 'flowSource'

An optional name for debugging purposes.
Deprecated:
  • User newFlowSource instead.
Returns:

the created data-flow

Type
olympe.df.Proxy.<T> | T

<static> createNode( [valueType] [, processingFunction] [, processingScope] [, args] [, argsToResolve] [, debugName] [, debug] [, alternateCallingAFunction])

Creates a node.

Parameters:
Name Type Argument Description
valueType function | Object <optional>

Type of the value of the node (i.e. the constructor of the value of the node)
processingFunction function | string <optional>

The internal node function, called as soon as all arguments and scope are ready
processingScope olympe.df.Node | Object <optional>

The scope of the internal function, can be a Node as well. If it's a node it needs to be resolved before running the function (i.e. a function cannot be run with an unresolved 'this')
args Array <optional>
<nullable>

Array of values (can include nodes, if nodes needs to be resolved then specify their index in argsToResolve)
argsToResolve Array.<number> <optional>
<nullable>

An array containing the index of the arguments to be resolve (zero based)
debugName string <optional>

Name to be displayed for the node in debug mode
debug boolean <optional>

Turn this to true to get debugging information for this node, nota: can be highly verbose
alternateCallingAFunction function <optional>

Function to handle method calls on the proxy. This is needed for some specific nodes
See:
Returns:

the created Node

Type
olympe.df.Node.<T>

<static> createNodeExecutingContext(logger)

Creates the root executing node and set it as current node Note: this helper should only be used in container run callbacks !

Parameters:
Name Type Description
logger olympe.logging.Channel

<static> createProxy( [type] [, initialValue] [, debugName])

Creates a proxy for a specific class with an optional initial value.

Parameters:
Name Type Argument Description
type function | Object <optional>

Type of the proxy.
initialValue olympe.df.Proxy.<T> | olympe.df.Node.<T> | T <optional>

Initial value of the proxy.
debugName string <optional>

An optional name for debugging purposes.
See:
Returns:
Type
olympe.df.Proxy.<T> | T

<static> dumpContextStack()

Logs on the console the name of the current context and of its ancestors

<static> dumpDataFlow(proxy [, info] [, displayStack])

Dumps a proxy to the console.

Parameters:
Name Type Argument Default Description
proxy olympe.df.Proxy <nullable>

Proxy object to dump
info string <optional>

Informational message
displayStack boolean <optional>
 false

true to display a stack trace.

<static> dumpObjectNode(node [, info] [, displayStack])

Dumps a node's values to the console

Parameters:
Name Type Argument Default Description
node olympe.df.Node <nullable>

Node to dump
info string <optional>

Informational message
displayStack boolean <optional>
 false

Wether to display a stack trace or not

<static> fakeCurrentExecutingNode(nodeToUseAsCreator, callback, args)

Executes the specified callback in the context of another node.

Parameters:
Name Type Argument Description
nodeToUseAsCreator olympe.df.Node

Node to use as current executing node.
callback function

Callback function to execute
args * <repeatable>

arguments to pass to the callback
Deprecated:
Returns:

Return value of the callback if any

Type
*

<static> fromJSON(json)

Parameters:
Name Type Description
json string | Object
Returns:
Type
*

<static> getCurrentContext()

Returns the current execution context.

Returns:
Type
olympe.df.ExecutionContext

<static> getCurrentValue(nodeOrProxy [, defaultValue])

Gets the current value of the specified node or proxy. When a Node hasn't been resolved yet the provided default value is returned.

Parameters:
Name Type Argument Description
nodeOrProxy olympe.df.Node.<T> | olympe.df.Proxy.<T> | olympe.df.FlowSource.<T>

Node, Proxy or other object to get the current value from.
defaultValue T <optional>

Optional default value to return if the current value is undefined.
Returns:
Type
T | undefined

<static> getGlobalContext()

Returns the Global Execution Context, also known as the root node. That context can not be destroyed.

Returns:
Type
olympe.df.ExecutionContext

<static> if(testValue, callbackIfTrue [, callbackIfFalse] [, returnType] [, callbackArgs] [, debugName])

Create a 'If' node with two callbacks. The first one is triggered when the test value is true and the second, optional, one when the test value is false.

Parameters:
Name Type Argument Description
testValue olympe.df.POBoolean | olympe.df.FlowSource.<olympe.df.OBoolean> | boolean | olympe.df.Node

The boolean expression to test.
callbackIfTrue function

Can return a value of type T
callbackIfFalse function <optional>

Can return a value of type T
returnType function <optional>

the return type of the callbacks.
callbackArgs Array <optional>

Arguments to pass to the callbacks.
debugName string <optional>

An optional name for debugging purposes.
Returns:

The created Proxy.

Type
T | olympe.df.Proxy.<T>

<static> isExecutionContext(value)

Checks whether an object is an ExecutionContext.

Parameters:
Name Type Description
value *

The object to be tested.
See:
Returns:

true if this object is an ExecutionContext.

Type
boolean

<static> isFlowSource(value)

Checks whether an object is a FlowSource.

Parameters:
Name Type Description
value *

The object to be tested.
See:
Returns:

true if this object is an FlowSource.

Type
boolean

<static> isNode(value)

Checks whether an object is a Node.

Parameters:
Name Type Description
value *

The object to be tested
See:
Returns:

true is the object is a Node.

Type
boolean

<static> isNodeOrProxy(value)

Checks whether an object is a Node or a Proxy.

Parameters:
Name Type Description
value *

The object to be tested.
See:
Returns:

true if the object is a Node or a Proxy.

Type
boolean

<static> isPrimitiveOType(value)

Check whether a value is a primitive olympe type olympe.df.OBoolean, olympe.df.ONumber, or olympe.df.OString.

Parameters:
Name Type Description
value *
Returns:
Type
boolean

<static> isProxy(value)

Checks whether an object is a Proxy or not.

Parameters:
Name Type Description
value *

The object to be tested.
See:
Returns:

true if the object is a Proxy.

Type
boolean

<static> newAnimatedFlowSource(duration [, easingFunction])

Creates an animated numerical Flow Source, that smoothly transitions, over the specified duration, to the new value when it is updated.

Example:

const animatedAngle = olympe.df.newAnimatedFlowSource(200)
     .setEasing(olympe.df.ONumber.EASING.EaseOutQuad);
olympe.df.if(isCollapsedFS.getFlow(), () => animatedAngle.update(0), () => animatedAngle.update(90));

Creates a data flow that smoothly transition between 90 and 0 degrees over a 200 milliseconds period.

Parameters:
Name Type Argument Default Description
duration olympe.df.PONumber | number

The duration in milliseconds.
easingFunction olympe.df.ONumber.EASING <optional>
 olympe.df.ONumber.EASING.LinearTween

The optional easing function.
Returns:

the created FlowSource

Type
olympe.df.AnimatedFlowSource

<static> newFlowSource(valueType [, debugName])

Creates a Flow Source of a specified type. A flow source is a special type of node that gets its value from an external source, like a timer or a UI event.

Example:

const rng = olympe.df.newFlowSource(olympe.df.ONumber);
setInterval(
  () => { rng.update(olympe.df.oNumber(Math.floor(Math.random() * 100) + 1)); },
  1000
);
const random = rng.getFLow();

Creates a data flow that generates a new random number every second.

Parameters:
Name Type Argument Default Description
valueType function

The type of the data flow
debugName string <optional>
 'flowSource'

An optional name for debugging purposes.
Returns:

the created FlowSource

Type
olympe.df.FlowSource.<T>

<static> oAnimate(value, duration [, animationFunction] [, onDone])

Compute the animation with requestAnimationFrame. A new duration value is not taken into account if there is an animation running.

Parameters:
Name Type Argument Description
value olympe.df.ONumber | number | olympe.df.Proxy | olympe.df.Node
duration olympe.df.ONumber | number | olympe.df.Proxy | olympe.df.Node
animationFunction function <optional>

animation function takes as first parameter a number between 0 and 1 (time) and returns a number (the position)
onDone olympe.df.ONumber.AnimateCallback <optional>

function to be called when animation is finished
Returns:
Type
olympe.df.PONumber

<static> oBoolean( [value])

Returns an instance of OBoolean. This static factory is the preferred way to create OBooleans as it avoids creating unnecessary instances.

Parameters:
Name Type Argument Default Description
value olympe.df.OBoolean | boolean | Boolean <optional>
<nullable>
 false

The boolean value to assign to this OBoolean
Returns:

The instance of OBoolean

Type
olympe.df.OBoolean

<static> oDateTime(date)

Returns an instance of ODateTime. This static factory is the preferred way to create ODateTimes.

Parameters:
Name Type Description
date Date
Returns:

The instance of ODateTime.

Type
olympe.df.ODateTime

<static> onResolved(nodeOrProxy, callback [, returnType] [, debugName])

Executes the callback when the node (or proxy) is resolved. This creates a node with a single entry, the callback as the associated function and the specified return type.

Parameters:
Name Type Argument Description
nodeOrProxy olympe.df.Node.<T> | olympe.df.Proxy.<T> | olympe.df.FlowSource.<T> | T

The node or proxy to use as entry for the node
callback function

The function to invoke when the entry node is resolved and every time it is updated.
returnType function <optional>

The return type of the function. Default is undefined, which means no return value.
debugName string <optional>

An optional name for debugging purposes.
Returns:

The created Node

Type
olympe.df.Node.<T> | T

<static> oNumber( [value])

Returns an instance of ONumber. Default value is ZERO. This is the preferred way to create ONumbers as it is optimised to avoid creating unnecessary instances.

Parameters:
Name Type Argument Default Description
value olympe.df.ONumber | number | Number <optional>
 0

The numerical value to assign to this ONumber
Returns:

The instance of ONumber.

Type
olympe.df.ONumber

<static> oString( [value])

Returns an instance of OString. This will attempt to convert the value passed in the argument into a string. For instance oString(false) will return an OString containing "false" while oString(102) with return an OString containing "102". This is the preferred way to create OStrings as it is optimised to avoid creating unnecessary instances.

Parameters:
Name Type Argument Default Description
value olympe.df.OString | olympe.df.ONumber | olympe.df.OBoolean | string | number | boolean | String <optional>
 ''

The value to convert into an OString.
Returns:

The instance of OString

Type
olympe.df.OString

<static> pColor( [r] [, g] [, b] [, a])

Creates a proxy of Color. This function can be invoked in two forms:

var c1 = pColor(color); // Creates a proxy of an existing Color instance
var c2 = pColor(255, 255, 255, 0.5); // Creates a Color and its associated Proxy.
Parameters:
Name Type Argument Default Description
r number | olympe.df.PONumber | olympe.df.Color | olympe.df.Node <optional>
 0

The red channel initial value, or the initial olympe.df.Color.
g number | olympe.df.PONumber | olympe.df.Node <optional>
 0

The green channel initial value.
b number | olympe.df.PONumber | olympe.df.Node <optional>
 0

The blue channel initial value.
a number | olympe.df.PONumber | olympe.df.Node <optional>
 1

The alpha channel initial value, default value is 1 (opaque).
Returns:

The created Proxy.

Type
olympe.df.PColor

<static> pOBoolean( [value])

Creates a proxy of a OBoolean. If no value is specified the created proxy will be 'unresolved'.

Parameters:
Name Type Argument Description
value olympe.df.OBoolean | boolean | olympe.df.Proxy | olympe.df.Node <optional>

The initial value to assign to this OBoolean
Returns:

The created proxy.

Type
olympe.df.POBoolean

<static> pODateTime( [date])

Creates a proxy of a ODateTime.

Parameters:
Name Type Argument Description
date Date <optional>
Returns:

The created proxy.

Type
olympe.df.PODateTime

<static> pONumber( [value])

Creates a proxy of an ONumber. If no value is specified the created proxy will be 'unresolved'.

Parameters:
Name Type Argument Description
value olympe.df.PONumber | number | olympe.df.Node <optional>

The initial value.
Returns:

The created proxy.

Type
olympe.df.PONumber

<static> pOString( [value])

Creates a proxy of an OString. If no value is specified the created proxy will be 'unresolved'.

Parameters:
Name Type Argument Description
value olympe.df.POString | string | number | boolean | olympe.df.Node <optional>

The initial value.
Returns:

The created proxy.

Type
olympe.df.POString

<static> processFlows(flows, processFunction [, debugName])

Applies a specified processing to a set of flows. The processing function is called every time the value of one of the flows changes and all flows have a valid value.

Important Note: If none of the elements in the array are flows (i.e. they are all fixed values), the execution happens immediately and only once.

Example:

olympe.df.processFlows(
    [p],
    v => { console.log(`value changed to ${v.valueOf()}`); }
);
Parameters:
Name Type Argument Default Description
flows Array

the set of flows to process
processFunction function

the processing function to apply to the flows
debugName string <optional>
 'processFlows'

An optional name for debugging purposes.

<static> processFlowsOnce(flows, processFunction [, debugName])

Applies a specified processing to a set of flows only once. The processing function is called once all flows have a valid value.

Example:

olympe.df.processFlowsOnce(
    [p],
    v => { console.log(`value changed to ${v.valueOf()}`); }
);
Parameters:
Name Type Argument Default Description
flows Array

the set of flows to process
processFunction function

the processing function to apply to the flows
debugName string <optional>
 'processFlowsOnce'

An optional name for debugging purposes.

<static> processFutureFlows(flows, processFunction [, debugName])

Applies a specified processing to a set of flows, but does not execute immediately even if all flows are resolved at invocation time. The processing function is called every time the value of one of the flows changes and all flows have a valid value.

Note: If none of the flows are actual flows (Proxy, FlowSource, or Node) then this becomes a no-op.

Example:

olympe.df.processFutureFlows(
    [p],
    v => { console.log(`value changed to ${v.valueOf()}`); }
);
Parameters:
Name Type Argument Default Description
flows Array

the set of flows to process
processFunction function

the processing function to apply to the flows
debugName string <optional>
 'processFlows'

An optional name for debugging purposes.

<static> processFutureFlowsOnce(flows, processFunction [, debugName])

Applies a specified processing to a set of flows, but does not execute immediately even if all flows are resolved at invocation time, and only once. The processing function is called the first time the value of one of the flows changes and all flows have a valid value.

Note: If none of the flows are actual flows (Proxy, FlowSource, or Node) then this becomes a no-op.

Example:

olympe.df.processFutureFlowsOnce(
    [p],
    v => { console.log(`value changed to ${v.valueOf()}`); }
);
Parameters:
Name Type Argument Default Description
flows Array

the set of flows to process
processFunction function

the processing function to apply to the flows
debugName string <optional>
 'processFlows'

An optional name for debugging purposes.

<static> pVector2( [x] [, y])

Creates a proxy of a Vector2. If x or y is defined creates a initialised node otherwise returns an unresolved typed node.

Parameters:
Name Type Argument Default Description
x olympe.df.PONumber | number | olympe.df.Node <optional>
 0

Initial value for the x coordinate.
y olympe.df.PONumber | number | olympe.df.Node <optional>
 0

Initial value for the y coordinate.
Returns:

The created Proxy.

Type
olympe.df.PVector2

<static> setCurrentContext(context)

Sets the current executing context to the specified one. Returns the previous one.

Parameters:
Name Type Description
context olympe.df.ExecutionContext

The new execution context.
Returns:

Previous context.

Type
olympe.df.ExecutionContext

<static> setDefaultValue(nodeOrProxy, value)

Sets the default value for a data flow. This is the value that this flow will revert back to when it is unresolved.

Parameters:
Name Type Description
nodeOrProxy olympe.df.Proxy.<T> | olympe.df.Node.<T> | olympe.df.FlowSource.<T>

The data flow.
value T | olympe.df.Proxy.<T>

The value to use as a default.
Returns:
Type
!olympe.df.Proxy.<T> | !olympe.df.Node.<T>

<static> syncNodes(nodesOrProxies, callback [, returnType] [, debugName])

Triggers the callback when all the nodes have a value and when any of the nodes is updated with a new value.

Parameters:
Name Type Argument Description
nodesOrProxies Array

The nodes, or proxies, to synchronize.
callback function

The function to execute.
returnType function <optional>

The return type of the callback. Default is 'undefined'.
debugName string <optional>

An optional name for debugging purposes.
Returns:

The created node.

Type
olympe.df.Node.<T>

<static> syncProxies(nodesOrProxies, callback [, returnType] [, debugName])

Triggers the callback when all the nodes have a value and when any of them is updated with a new value. In essence this creates an anonymous node whose function is the callback and the upstream nodes (or parameters) are the proxies specified as argument.

Example:

olympe.df.syncProxies(
    [p],
    v => { console.log(`value changed to ${v.valueOf()}`); }
);
Parameters:
Name Type Argument Default Description
nodesOrProxies Array

The nodes, or proxies, to synchronize.
callback function

the function to execute
returnType function <optional>

the return type of the callback function, default is undefined
debugName string <optional>
 'syncProxies'

An optional name for debugging purposes.
Returns:

A proxy to the return value of the callback.

Type
olympe.df.Proxy.<T> | T

<static> syncProxiesOnce(nodesOrProxies, callback [, returnType] [, debugName])

Wait for all the proxies to be resolved, and execute the callback only once.

Parameters:
Name Type Argument Default Description
nodesOrProxies Array

The nodes, or proxies, to synchronize.
callback function

the function to execute
returnType function <optional>

the return type of the callback function
debugName string <optional>
 'syncProxiesOnce'

An optional name for debugging purposes.

<static> transformFlows(flows, transformFunction, returnType [, debugName] [, defaultValue])

Creates a data flow that is the result of transforming, via the specified transformation function, a set of flows. The transformation function is called every time the value of one of the flows changes and all flows have a valid value.

Important Note: If none of the elements in the array are flows (i.e. they are all fixed values), the execution happens immediately and only once, in which case the results is also a fixed value.

Example:

res = olympe.df.transformFlows(
    [a1, a2],
    (v1, v2) => olympe.df.oNumber(v1.valueOf() ** v2.valueOf()),
    olympe.df.ONumber
);
Parameters:
Name Type Argument Default Description
flows Array

The set of flows to transform.
transformFunction function

The transformation function to apply to the flows.
returnType function

The return type of the transformation function.
debugName string <optional>
 'TransformFlows'

An optional name for debugging purposes.
defaultValue T <optional>

An optional default value to use when the flow is unresolved.
Returns:

The resulting data-flow or value.

Type
!olympe.df.Proxy.<T> | T

<static> withCurrentExecutingNode(callback)

Returns a function that wraps the specified callback in the context of the current executing node.

Parameters:
Name Type Description
callback function

The function to wrap.
Deprecated:
Returns:

The created function.

Type
function

Type Definitions

FlowSourceCallback(setter)

Flow source callback. Takes a FlowSource parameter.

Parameters:
Name Type Description
setter olympe.df.FlowSource

PColor

Type:

POBoolean

Type:

PODateTime

Type:

PONumber

Type:

POString

Type:

PPrimitive

Type:

PVector2

Type: