Usage

npm install @rkmodules/rules

Engine

An engine creates a namespace for functions, so create an engine to start with:

const engine = new Engine()

editor

• Create an instance of the rules engine
• import the css
• create a function to work with
• use the <Flow> component to create the editor
• use the <DDContext> component around the flow

import "@rkmodules/rules/index.css";
import {
    DDContext,
    Engine,
    Flow,
    GraphedFunction,
} from "@rkmodules/rules";

const engine = new Engine({
    // map of custom rules
});

const emptyFunction: GraphedFunction = {
    name: "test",
    body: {},
    outputs: {
        documents: "",
    },
};

export default function MyComponent() {
    const [fn, setFn] = React.useState(emptyFunction);
    return (
        <div>
            <DDContext>
                <Flow function={fn} engine={engine} onChange={setFn} />
            </DDContext>
        <div>
    );
}

Specifying a function

A function definition is just a json object. It can be assembled together via code or just hardcoded. It is of type GraphedFunction and at least has to have a name and body field. The latter defines a graph with calls to primitives or other graphed functions:

const testFunction: GraphedFunction = {
    name: "test",
    label: "optional label",
    description: "optional description",
    body: {
        myVal: {
            name: "value",
            params: {
                type: "string",
            },
        },
        myLog: {
            name: "log",
            inputs: {
                data: "<myVal.value>",
            },
        },
    },
};

Inputs, params and outputs

A function may also define params, inputs and outputs to indicate how to call the function and what it returns. This allows to create custom functions and to use them in others

Specifying primitives

A primitive is a function definition that also had code

We get back to function definitions later

Running the function

• build all the custom functions
• run the one you need

use in react

useFunction

custom styling

import the css for basic styling:

import "@rkmodules/rules/index.css";

The following css variables are defined on root, overwrite if needed

:root {
    --node-line: #ccc;
    --node-select-line: #007bff;
    --node-active-line: crimson;
    --node-background: #f9f9f9;
    --node-connection: #007bff;
    --node-shadow: none;
    --node-radius: 4px;
}

custom controls

node inputs and params have a particular type. There are standard controls for string, number and boolean. Additional controls can be created using a component with the following props signature:

export interface WidgetProps<T> {
    value: T;
    vardef: NormalizedVarDef;
    data: FunctionNode["data"];
    onChange?: (value: T) => void;
}

custom contols can be passed into the <Flow> component with the customControls prop. It should be a map from type to component:

<Flow
    engine={engine}
    function={fn}
    onChange={setFn}
    customControls={{
        color: ColorControl,
    }}
/>

custom nodes

alternatively, the entire node can be customized. There are the following standard nodes Default, Calc, and

• Default: the default node
• Calc: specialized node for the Calc function that renders the expression and creates input ports based on variables in the expression
• DynamicInput: creates additional input ports, useful for allowing a dynamic number of inputs
• DynamicOutput: creates output ports on the fly based on the function result
• NamedInput: allows adding and renaming input ports by the user
• Input and Output: used for rule input and output

Components / functions reference

List

• List Input: creates a list of strings or numbers based on textfield input
• List Item: selects items from a list based on their indices
• List Length: returns the length of a list
• Relative Item
• Relative Items
• Unique Items: removes duplicates from a list

Logic

• And: returns true if both inputs are true
• Or: returns true if one or both of the inputs are true
• Not: negates all elements in the list
• Group And: returns true if all elements in the list are true
• Group Or: returns true if some elements in the list are true
• Group stats: returns min, max, avg, std, sum and count of a list of numbers

Math

• Add
• Subtract
• Multiply
• Divide
• Modulo
• Pow
• Sqrt
• Round
• Floor
• Ceil
• Sin
• Cos
• Tan
• Sum
• Less Than
• Greater Than

String

• Join Strings
• String Equal To
• String Template
• To String

Date

• Duration
• Format Date
• Iso Date
• Parse Date
• Today

Util

• Get Type
• Get Value
• Log
• Value

Sequence

• Series

JSON

• Array To List
• Destructure Object
• Explode Object
• List To Array
• Merge Object
• Object
• Entries
• Set Field

Group

• Cartesian Groups
• Filter Tree
• Group All
• Merge Group
• Merge Tree
• Normalize Tree
• SimplifyTree
• Split Group
• Tree Item

IO

• Input
• Output

TODO:

• [ ] filtering of lists
  • document grasshopper nodes
  • build them
• [ ] set value
• [ ] inspection
  • run time
  • running flag
  • intermediate results

Text

• formatting
• text replacement

grasshopper investigation

value

using functions

in React context

• use useFunction. This will build the function, mount it if needed and provides a run function.

in Vanilla context

• use engine.build(fn) to build the function
• use engine.mount(fn) to mount the function (if it has a mount function)
• use engine.run(fn, inputs) to run the function

considerations

For Supa Lipu we have quite a lot of functions that need to be called on various events

• when propobjects are updated / created / deleted.

  • currently, each propobject has its own engine and 1 single rule. This is fired when the object is mutated
  • all functions need to be propobjects as well, then referenced in various places
  • the engine needs to be global, so that functions can reference each other
    • for these references, we need propobject refs, to that dependency functions are loaded
  • in useObjectMutation, we fire an event such that mounted eventlisteners can react

• we need deep references. On change, oldProps and changedProps are passed in as an object. So we need

  • primitives to getValue and setValue
  • [x] reference strings that can directly reference deeper objects to eliminate the need for getValue

• [x] also need to think about data tree handling for outputs

Entries

• in finance I had filterLine(on, match) function that filters return a boolean if any of the lines match. This is a hardcoded solition, which is ok for finance. But we might come up with something more generic