UCOD Parser

Description

This parser is designed specifically for UCOD nodes and flows. It efficiently interprets UCOD files, extracting nodes and flows to produce a corresponding JSON representation.

Usage

import { parseNode } from 'mod.ts';
/**
 * For node use
 * import { parseNode } from '@ucod-io/parser'
 */

const parsedNode = parseNode(`
export const $$name = "Addition";
export default (a: number, b: number): number => a + b;
`);
console.log(parsedNode);

{
  "name": "Addition",
  "description": "",
  "state": [],
  "config": [],
  "ports": {
    "flow": { "in": false, "out": [] },
    "data": {
      "in": [
        { "name": "a", "type": "number", "optional": false },
        { "name": "b", "type": "number", "optional": false }
      ],
      "out": [{ "name": "number", "type": "number" }]
    }
  }
}

API

Functions

parseNode

parseNode takes the code of a node as a string and returns a JSON representation of the node.

import { parseNode } from '@ucod-io/parser';
const additionCode = `
export const $$name = "Addition";
export default (a: number, b: number): number => a + b;
`;
const parsedNode = parseNode(additionCode);

parseFlow

parseFlow takes a json representation of the flow and returns a parsed flow JSON.

import { parseFlow } from '@ucod-io/parser';

const flow = {
  name: 'additionFlow',
  version: '1.0.0',
  nodes: [
    {
      id: 'core.math.addition',
      code: addition.code,
    },
    {
      id: 'core.math.randomNumber',
      code: randomNumber.code,
    },
  ],
  connections: [
    ['core.math.randomNumber', 'core.math.addition'],
    ['core.math.randomNumber', 'core.math.addition'],
  ],
};

const parsedFlow = parseFlow(flow);

parseAst

To allow the usage of the parser in the browser, the parser can be used with an AST instead of a string. The AST is generated by @swc/wasm-web.

import { parseAst } from '@ucod-io/parser';
import { useEffect, useState } from 'react';
import initSwc, { parseSync } from '@swc/wasm-web';

export default function App() {
  const [initialized, setInitialized] = useState(false);

  useEffect(() => {
    async function importAndRunSwcOnMount() {
      await initSwc();
      setInitialized(true);
    }
    importAndRunSwcOnMount();
  }, []);

  function parse() {
    if (!initialized) {
      return;
    }
    const additionCode = `
  export const $$name = "Addition";
  export default (a: number, b: number): number => a + b;
  `;
    const result = parseSync(additionCode, {
      syntax: 'typescript',
      target: 'esnext',
      comments: true,
    });
    const ast = result.body;
    const parsedNode = parseAst(ast);
    console.log(parsedNode);
  }

  return (
    <div className='App'>
      <button onClick={parse}>Parse</button>
    </div>
  );
}

parseAst accepts the body of the AST as a parameter. The AST body is the result of the parseSync function of @swc/wasm-web. For more information about the SWC project, please visit the SWC website.

Interfaces

ParsedNode

interface ParsedNode {
  name: string;
  description: string;
  state: ParsedNodeProperty[];
  config: ParsedNodeProperty[];
  ports: {
    flow: {
      in: boolean;
      out: string[];
    };
    data: {
      in: ParsedNodePort[];
      out: ParsedNodePort[];
    };
  };
}

Field	Type	Description	optional	default value	example
name	string	The name of the node	false	-	'Addition'
description	string	The description of the node	true	''	'This node adds two numbers'
state	ParsedNodeProperty[]	The state properties of the node	true	[]	`[{name: 'result', type: 'number', optional: false}]`
config	ParsedNodeProperty[]	The config properties of the node	true	[]	`[{name: 'result', type: 'number', optional: false}]`
ports	ParsedNodePorts	The ports of the node	false	-	`{flow: {in: false, out: []}, data: {in: [{name: 'a', type: 'number', optional: false}], out: [{name: 'result', type: 'number'}]}}`

Examples

Addition

export const $$name = 'Addition';
export const $$description = 'This node adds two numbers';
export default (a: number, b: number): number => a + b;

Http Request

import axios from 'axios';
interface Config {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
  url: string;
  headers?: Record<string, string>;
}
export const $$name = 'Http Request';
export const $$description = 'Make an HTTP request';
export const $$exec = true;

export const $$config: Config = {
  method: 'GET',
  url: 'https://example.com',
  headers: {
    'Content-Type': 'application/json',
  },
};
export const $$state = {
  data: null,
  error: null,
};
export default async (url?: string, method?: string, [err, suc]: Array<Function>): {
  data: any;
} => {
  const config: Config = {
    method: method || $$config.method,
    url: url || $$config.url,
    headers: $$config.headers,
  };
  try {
    const response = await axios(config);
    $$state.data = response.data;
    suc(response.data);
    return response.data;
  } catch (error) {
    $$state.error = error;
    err(error);
    return error;
  }
};

Importent Notes

Node Name

The Node name is required and must be exported and defined with the $$name variable. And it must be a string.

example

export const $$name = 'Addition';

Node Description

The Node description is optional but if you want to add a description to your node you have to export and define it with the $$description variable. And it must be a string. example:

export const $$description = 'This node adds two numbers';

Node State and Config

The Node state/config is optional but if you want to add a state/config to your node you have to export and define it with the $$state or/and $$config variable(s).

Typing

You can leave the typing of the state/config to the parser. It will automatically detect the type and mark them all as required.

export const $$state = {
  data: null,
  error: null,
};
export const $$config = {
  method: 'GET',
  url: 'https://example.com',
};

Inline Typing

You can also define the type of the state/config using typescript inline typing

export const $$state: {
  data: any;
  error: any;
} = {
  data: null,
  error: null,
};
export const $$config: {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
  url: string;
} = {
  method: 'GET',
  url: 'https://example.com',
};

Interface Typing

You can also define the type of the state using typescript interfaces.

interface State {
  data: any;
  error: any;
}
interface Config {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
  url: string;
}
export const $$state: State = {
  data: null,
  error: null,
};
export const $$config: Config = {
  method: 'GET',
  url: 'https://example.com',
};

Output Ports

Function Output

If you want to add an output to your node you have to explicitly define the return type of the default function.

export default (a: number, b: number): number => a + b;

you can also define the output type using typescript interfaces.

interface Output {
  data: any;
  error: any;
}
export default (a: number, b: number): Output => {
  return {
    data: a + b,
    error: null,
  };
};

Or you can define the output type using typescript inline typing.

export default (a: number, b: number): {
  data: any;
  error: any;
} => {
  return {
    data: a + b,
    error: null,
  };
};

Callback functions

Callback functions are functions that are passed as parameters to the default function. The type of the callback functions should be:

Array<Function>
Array<UCallback>
Function[]
UCallback[]

The callback functions should be called in the default function as the last parameter.

export default (a: number, b: number, [err, suc]: Array<Function>) => {};
export default (a: number, b: number, [err, suc]: Array<UCallback>) => {};
export default (a: number, b: number, [err, suc]: Function[]) => {};
export default (a: number, b: number, [err, suc]: UCallback[]) => {};

Tests

To run the UCOD-Parser execute this command

make test

Benchmarks

To run the UCOD-Parser benchmarks execute this command

make bench

Results

Benchmark	Time (avg)	iter/s	(min..max)	p75	p99	p995
Addition V1	105.44 ms/iter	9.5	(98.09 ms … 117.86 ms)	109 ms	117.86 ms	117.86 ms
Addition V2	101.83 µs/iter	9,820.7	(85.96 µs … 2.59 ms)	98.32 µs	190.21 µs	208.66 µs
Addition V5	97.24 µs/iter	10,284.2	(88.09 µs … 730.42 µs)	97.43 µs	161.98 µs	177.62 µs

summary Addition V5 1.05x faster than Addition V2 1084.36x faster than Addition V1

Benchmark	Time (avg)	iter/s	(min..max)	p75	p99	p995
Request V1	108.84 ms/iter	9.2	(101.15 ms … 126.58 ms)	113.82 ms	126.58 ms	126.58 ms
Request V2	163.29 µs/iter	6,124.0	(148.55 µs … 2.27 ms)	162.29 µs	239.24 µs	273.15 µs
Request V5	125.18 µs/iter	7,988.8	(115.45 µs … 714.9 µs)	123.63 µs	195.98 µs	223.82 µs

summary Request V5 1.3x faster than Request V2 869.52x faster than Request V1

License

Elastic License 2.0