rscarson / lavendeux-npm

NPM package for the JS extension wrapper

This package provides an interface for creating lavendeux extensions. It essentially functions as an API wrapper, providing bidirectional type conversion, as well as function argument resolution logic

The lavendeux-parser is a parsing engine for rust, acting as the backend for Lavendeux

Create a new extension using npx lavendeux init <extension_name>. The extension can be compiled for use with Lavendeux using npx lavendeux build Use npx lavendeux init <extension_name> --typescript if you wish to create a typescript template instead

The parser supports runtime loaded JS extensions for adding functionality in 2 ways:

• Functions, which can be called like so: add(2, 3)
• Decorators, which format the output of a statement and can be called like so: 22 @usd

Below is a simple example of an extension that would implement the add() and @usd features above:

import { name, author, version } from '../package.json';
import { Lavendeux } from 'lavendeux';

// Create a new extension from the configuration in package.json
let instance = new Lavendeux(name, author, version);

/**
 * Formats a given value as a string
 * A decorator that accepts a numeric value
 * Can be called from Lavendeux with @usd
 * @param {Number} input The value to decorate
 * @returns Formatted result
 */
instance.addNumericDecorator('usd', (input) => {
    let n = (Math.round(input * 100) / 100).toFixed(2);
     return `$${n}`;
});

/**
 * A function accepting 2 numeric arguments
 * Can be called from Lavendeux with add(5, 3)
 * @param {Number} left An argument to the function
 * @param {Number} right An argument to the function
 * @returns The resulting value
 */
instance.addFunction('add', (left, right) => {
    return left + right;
})
.addNumericArgument()
.addNumericArgument();

// Make the extension visible to the lavendeux parser
Lavendeux.register(instance);

Functions can also access variables set from within Lavendeux, in order to act statefully:

import { name, author, version } from './package.json';
import { Lavendeux } from 'lavendeux';

function statefulFunction(state) {
    return state.nextInt++;
}

let instance = new Lavendeux(name, author, version);
instance.addFunction('next', statefulFunction);

// Make the extension visible to the lavendeux parser
Lavendeux.register(instance);

Function arguments can be any of the following:

• addIntegerArgument: Supplied value must be numeric, and will be coorced to int
• addFloatArgument: Supplied value must be numeric, and will be coorced to a float
• addNumericArgument: Supplied value can be a float or integer
• addStringArgument: Supplied value will be cooerced to string
• addBooleanArgument: Supplied value will be cooerced to boolean
• addArrayArgument: Supplied value will be cooerced into an array
• addObjectArgument: Supplied value will be cooerced into an object
• addArgument: Any type is accepted, and no type cooersion occurs

Additionally, each of the above functions takes in an optional boolean to indicate that the parameter is optional.

Note that only the last parameter may be optional

Similarly, decorators are also typed using the same rules as above, and can be one of the following:

• addIntegerDecorator: Supplied value must be numeric, and will be coorced to int
• addFloatDecorator: Supplied value must be numeric, and will be coorced to a float
• addNumericDecorator: Supplied value can be a float or integer
• addStringDecorator: Supplied value will be cooerced to string
• addBooleanDecorator: Supplied value will be cooerced to boolean
• addArrayDecorator: Supplied value will be cooerced into an array
• addObjectDecorator: Supplied value will be cooerced into an object
• addDecorator: Any type is accepted, and no type cooersion occurs

Also - do not place anything in the global scope named 'extension' as the Lavendeux parser looks for a global function by that name in order to load the extension