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

@ucod-io/parser

UCOD Parser

Description

Usage

API

Functions

parseNode

parseFlow

parseAst

Interfaces

ParsedNode

Examples

Addition

Http Request

Importent Notes

Node Name

example

Node Description

Node State and Config

Typing

Inline Typing

Interface Typing

Output Ports

Function Output

Callback functions

Tests

Benchmarks

Results

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads