Export Functions

Guide to export functions from your plugin to be used by other language modules within Plugify.

In the Plugify ecosystem, JavaScript plugins can export functions to make them accessible to other plugins. This guide explains how to define and export functions in JavaScript and provides examples to help you integrate your plugins seamlessly.

Basic Type Mapping

The following table lists how types are exposed to the JavaScript API:

C++ Type	JavaScript Type	Plugify Alias	Ref Support ?
void	undefined	void	❌
bool	boolean	bool	✅
char	string	char8	✅
char16_t	string	char16	✅
int8_t	number	int8	✅
int16_t	number	int16	✅
int32_t	number	int32	✅
int64_t	BigInt	int64	✅
uint8_t	number	uint8	✅
uint16_t	number	uint16	✅
uint32_t	number	uint32	✅
uint64_t	BigInt	uint64	✅
uintptr_t	number	ptr64	✅
uintptr_t	number	ptr32	✅
float	number	float	✅
double	number	double	✅
void*	Function	function	❌
plg::string	string	string	✅
plg::any	any	any	✅
plg::vector<bool>	boolean[]	bool[]	✅
plg::vector<char>	string[]	char8[]	✅
plg::vector<char16_t>	string[]	char16[]	✅
plg::vector<int8_t>	number[]	int8[]	✅
plg::vector<int16_t>	number[]	int16[]	✅
plg::vector<int32_t>	number[]	int32[]	✅
plg::vector<int64_t>	BigInt[]	int64[]	✅
plg::vector<uint8_t>	number[]	uint8[]	✅
plg::vector<uint16_t>	number[]	uint16[]	✅
plg::vector<uint32_t>	number[]	uint32[]	✅
plg::vector<uint64_t>	BigInt[]	uint64[]	✅
plg::vector<uintptr_t>	number[]	ptr64[]	✅
plg::vector<uintptr_t>	number[]	ptr32[]	✅
plg::vector<float>	number[]	float[]	✅
plg::vector<double>	number[]	double[]	✅
plg::vector<plg::string>	string[]	string[]	✅
plg::vector<plg::any>	any[]	any[]	✅
plg::vector<plg::vec2>	Vector2[]	vec2[]	✅
plg::vector<plg::vec3>	Vector3[]	vec3[]	✅
plg::vector<plg::vec4>	Vector4[]	vec4[]	✅
plg::vector<plg::mat4x4>	Matrix4x4[]	mat4x4[]	✅
plg::vec2	Vector2	vec2	✅
plg::vec3	Vector3	vec3	✅
plg::vec4	Vector4	vec4	✅
plg::mat4x4	Matrix4x4	mat4x4	✅

Exporting Functions in JavaScript

Exporting functions in JavaScript is straightforward because JavaScript is a dynamically-typed language. You only need to define the function and specify it in the plugin manifest. Plugify's JavaScript Language Module handles the rest.

Basic Example

Here’s a simple example of exporting a function in a JavaScript plugin:

Function Definition

plugin.mjs

export function addNumbers_exported(a, b) {
    /**
     * Adds two integers.
     *
     * @param {number} a - First integer.
     * @param {number} b - Second integer.
     * @returns {number} Sum of a and b.
     */
    return a + b;
}

Plugin Manifest

To export the function, describe it in the plugin manifest under the methods section:

plugin_name.pplugin

{
  "name": "ExampleJavaScriptPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "addNumbers",
      "funcName": "addNumbers_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "a"
        },
        {
          "type": "int32",
          "name": "b"
        }
      ],
      "retType": {
        "type": "int32"
      }
    }
  ]
}

Advanced Example: Exporting Complex Functions

Here’s an example of exporting a function with complex parameter and return types:

Function Definition

plugin.mjs

export function processData_exported(data, prefix) {
    /**
     * Processes an array of numbers and returns an array of strings.
     *
     * @param {Array<number>} data - Array of numbers.
     * @param {string} prefix - Prefix to add to each value.
     * @returns {Array<string>} Array of formatted strings.
     */
    return data.map(value => `${prefix}${value}`);
}

Plugin Manifest

plugin_name.pplugin

{
  "name": "ExampleJavaScriptPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "processData",
      "funcName": "processData_exported",
      "paramTypes": [
        {
          "type": "float[]",
          "name": "data"
        },
        {
          "type": "string",
          "name": "prefix"
        }
      ],
      "retType": {
        "type": "string[]"
      }
    }
  ]
}

Exporting Functions with References

Plugify supports reference parameters in dynamically-typed languages like JavaScript, but they work differently than in statically-typed languages. In JavaScript, you cannot directly modify parameters passed by reference. Instead, you must return an array where:

First element: The function's return value (use undefined if the function returns void)
Remaining elements: Modified values for all reference parameters, in order

Function Definition with Reference Parameters

plugin.mjs

export function incrementValue_exported(value) {
    /**
     * Increments an integer value by reference.
     *
     * @param {number} value - The value to increment.
     * @returns {Array} Array of [undefined, modified_value].
     */
    return [null, value + 1];
}

export function calculate_exported(a, b, sum, product) {
    /**
     * Calculates sum and product of two numbers, returning both via reference.
     *
     * @param {number} a - First number.
     * @param {number} b - Second number.
     * @param {number} sum - Output parameter for sum (passed by reference).
     * @param {number} product - Output parameter for product (passed by reference).
     * @returns {Array} Array of [undefined, sum, product].
     */
    const calculatedSum = a + b;
    const calculatedProduct = a * b;
    return [null, calculatedSum, calculatedProduct];
}

export function processAndCount_exported(data, prefix, count) {
    /**
     * Processes data and returns both result and count.
     *
     * @param {Array<number>} data - Array of numbers.
     * @param {string} prefix - Prefix to add to each value.
     * @param {number} count - Output parameter for count (passed by reference).
     * @returns {Array} Array of [result, count].
     */
    const result = data.map(value => `${prefix}${value}`);
    return [result, data.length];
}

Plugin Manifest with Reference Parameters

In the manifest, mark parameters that should be treated as references using "ref": true:

plugin_name.pplugin

{
  "name": "ExampleJavaScriptPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "incrementValue",
      "funcName": "incrementValue_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "value",
          "ref": true
        }
      ],
      "retType": {
        "type": "void"
      }
    },
    {
      "name": "calculate",
      "funcName": "calculate_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "a"
        },
        {
          "type": "int32",
          "name": "b"
        },
        {
          "type": "int32",
          "name": "sum",
          "ref": true
        },
        {
          "type": "int32",
          "name": "product",
          "ref": true
        }
      ],
      "retType": {
        "type": "void"
      }
    },
    {
      "name": "processAndCount",
      "funcName": "processAndCount_exported",
      "paramTypes": [
        {
          "type": "float[]",
          "name": "data"
        },
        {
          "type": "string",
          "name": "prefix"
        },
        {
          "type": "int32",
          "name": "count",
          "ref": true
        }
      ],
      "retType": {
        "type": "string[]"
      }
    }
  ]
}

How It Works

Return Order: The first return value is the function's actual return value. Subsequent values correspond to reference parameters in order.
Void Functions: If the function returns void, the first element of the array must be undefined.
Mixed Returns: If a function has both a return value and reference parameters, the return value comes first, followed by all reference parameters.
Array Destructuring: Callers can use array destructuring to easily access the returned values.

Reference Parameter Support

Reference parameters work with most Plugify types as shown in the "Ref Support" column of the type mapping table. The following types do not support references:

void/undefined (cannot be passed by reference)
function (callback types)

All other types including primitives, strings, and arrays support reference parameters via the array return pattern.

Handling Callbacks

Plugify allows you to export functions that accept callbacks as parameters. Here’s an example:

Function Definition

plugin.mjs

export function executeWithCallback_exported(value, inputStr, callback) {
    /**
     * Executes a callback function with the provided parameters.
     *
     * @param {number} value - Integer value.
     * @param {string} inputStr - Input string.
     * @param {Function} callback - Callback function to execute.
     */
    const result = callback(value, inputStr);
    console.log(`Callback result: ${result}`);
}

Plugin Manifest

plugin_name.pplugin

{
  "name": "ExampleJavaScriptPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "executeWithCallback",
      "funcName": "executeWithCallback_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "value"
        },
        {
          "type": "string",
          "name": "inputStr"
        },
        {
          "type": "function",
          "name": "callback",
          "prototype": {
            "name": "exampleCallback",
            "funcName": "exampleCallback_exported",
            "paramTypes": [
              {
                "type": "int32",
                "name": "value"
              },
              {
                "type": "string",
                "name": "inputStr"
              }
            ],
            "retType": {
              "type": "string"
            }
          }
        }
      ],
      "retType": {
        "type": "void"
      }
    }
  ]
}

Best Practices

Define Functions Clearly: Ensure your functions are well-documented and easy to understand.
Follow Type Conventions: Adhere to Plugify's type conventions for parameters and return values.
Test Thoroughly: Test your exported functions to ensure they work as expected when called by other plugins.
Update the Manifest: Always describe exported functions in the plugin manifest under the methods section.

Conclusion

Exporting functions in JavaScript plugins is simple and straightforward. By defining your functions and describing them in the plugin manifest, you can create robust and interoperable plugins. For more advanced use cases, such as handling callbacks, use the techniques outlined in this guide.

Edit this page on GitHub

First Plugin

Learn how to create your first plugin with the language module, including basic syntax and setup.

Import Functions

Learn how to import functions from other plugins written in different languages and use them in your own.