@dronedeploy/rocos-js-sdk 3.0.1-alpha.9 → 3.0.1

package/esm/helpers/kscript/nodes/Program.d.ts

@@ -0,0 +1,11 @@
+import { AnyNode, Program } from 'acorn';
+import Context from '../Context';
+import Node from './Node';
+/** Represents the root node of the program
+ *
+ * Since the sandbox only supports a single statement, this node will only ever run the first child.
+ */
+export default class ProgramNode extends Node<Program> {
+    constructor(node: AnyNode, scope: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/Program.js

@@ -0,0 +1,18 @@
+import Node from './Node';
+import { construct } from '../utils';
+/** Represents the root node of the program
+ *
+ * Since the sandbox only supports a single statement, this node will only ever run the first child.
+ */
+export default class ProgramNode extends Node {
+    constructor(node, scope) {
+        super(node, scope, 'Program');
+    }
+    run() {
+        const children = this.node.body;
+        if (children.length !== 1) {
+            throw new Error('Only a single statement is supported in the sandbox');
+        }
+        return construct(children[0], this.context).run();
+    }
+}

package/esm/helpers/kscript/nodes/TemplateLiteral.d.ts

@@ -0,0 +1,23 @@
+import { AnyNode, TemplateLiteral } from 'acorn';
+import Context from '../Context';
+import Node from './Node';
+/**
+ * A template literal is a string literal that allows embedded expressions.
+ *
+ * e.g. `Hello ${name}`
+ *
+ * The `quasis` property is an array of strings that are the static parts of the template literal.
+ * The `expressions` property is an array of expressions that are the dynamic parts of the template literal.
+ *
+ * The template literal is constructed by merging the static parts with the results of evaluating the dynamic parts.
+ *
+ * i.e. `Hello ${name}. My name is ${name}.`
+ * Would result in three quasi values: `Hello `, `. My name is ` and `.`
+ * And two expressions: `Identifier<name>` and `Identifier<name>`
+ *
+ * There is *always* one more quasi value than there are expressions, even if the last quasi is an empty string.
+ */
+export default class TemplateLiteralNode extends Node<TemplateLiteral> {
+    constructor(node: AnyNode, scope: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/TemplateLiteral.js

@@ -0,0 +1,29 @@
+import Node from './Node';
+import { construct } from '../utils';
+/**
+ * A template literal is a string literal that allows embedded expressions.
+ *
+ * e.g. `Hello ${name}`
+ *
+ * The `quasis` property is an array of strings that are the static parts of the template literal.
+ * The `expressions` property is an array of expressions that are the dynamic parts of the template literal.
+ *
+ * The template literal is constructed by merging the static parts with the results of evaluating the dynamic parts.
+ *
+ * i.e. `Hello ${name}. My name is ${name}.`
+ * Would result in three quasi values: `Hello `, `. My name is ` and `.`
+ * And two expressions: `Identifier<name>` and `Identifier<name>`
+ *
+ * There is *always* one more quasi value than there are expressions, even if the last quasi is an empty string.
+ */
+export default class TemplateLiteralNode extends Node {
+    constructor(node, scope) {
+        super(node, scope, 'TemplateLiteral');
+    }
+    run() {
+        return this.node.quasis.reduce((acc, quasi, i) => {
+            const expression = this.node.expressions[i] ? construct(this.node.expressions[i], this.context).run() : '';
+            return acc + quasi.value.raw + expression;
+        }, '');
+    }
+}

package/esm/helpers/kscript/nodes/expressions/ArrayExpression.d.ts

@@ -0,0 +1,7 @@
+import { AnyNode, ArrayExpression } from 'acorn';
+import type Context from '../../Context';
+import Node from '../Node';
+export default class ArrayExpressionNode extends Node<ArrayExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/expressions/ArrayExpression.js

@@ -0,0 +1,25 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+export default class ArrayExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'ArrayExpression');
+    }
+    run() {
+        const array = [];
+        for (const element of this.node.elements) {
+            if (element === null) {
+                // null implies an empty slot in the array (e.g. [1, , 3])
+                // an actual null value would be a literal node.
+                array.push(null);
+                delete array[array.length - 1];
+            }
+            else if (element.type === 'SpreadElement') {
+                array.push(...construct(element.argument, this.context).run());
+            }
+            else {
+                array.push(construct(element, this.context).run());
+            }
+        }
+        return array;
+    }
+}

package/esm/helpers/kscript/nodes/expressions/ArrowFunctionExpression.d.ts

@@ -0,0 +1,14 @@
+import { AnyNode, ArrowFunctionExpression } from 'acorn';
+import type Context from '../../Context';
+import Node from '../Node';
+/** Represents an arrow function expression.
+ *
+ * e.g. `(a, b) => a + b`
+ *
+ * In the sandbox this is the only way to define a function.
+ */
+export default class ArrowFunctionExpressionNode extends Node<ArrowFunctionExpression> {
+    private readonly params;
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/expressions/ArrowFunctionExpression.js

@@ -0,0 +1,34 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+/** Represents an arrow function expression.
+ *
+ * e.g. `(a, b) => a + b`
+ *
+ * In the sandbox this is the only way to define a function.
+ */
+export default class ArrowFunctionExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'ArrowFunctionExpression');
+        if (this.node.params.some((param) => param.type !== 'Identifier')) {
+            throw new Error('only identifiers are supported as parameters');
+        }
+        this.params = this.node.params;
+    }
+    run() {
+        if (!this.context.isFunctionCallAllowed)
+            throw new Error('functions are not allowed');
+        if (!this.node.expression)
+            throw new Error('functions must be an expression');
+        if (this.node.async)
+            throw new Error('async functions are not supported');
+        return (...args) => {
+            const scope = new Map();
+            for (const param of this.params) {
+                const index = this.params.indexOf(param);
+                scope.set(param.name, args?.[index]);
+            }
+            const newContext = this.context.newChildContext(scope);
+            return construct(this.node.body, newContext).run();
+        };
+    }
+}

package/esm/helpers/kscript/nodes/expressions/BinaryExpression.d.ts

@@ -0,0 +1,16 @@
+import { AnyNode, BinaryExpression } from 'acorn';
+import Context from '../../Context';
+import Node from '../Node';
+/** A binary expression is an expression that consists of two operands and an operator
+ *
+ * e.g. `1 + 2`, `a === b`, `c < d`
+ */
+export default class BinaryExpressionNode extends Node<BinaryExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+    private operate;
+    private arithmetic;
+    private comparison;
+    private equality;
+    private checkIn;
+}

package/esm/helpers/kscript/nodes/expressions/BinaryExpression.js

@@ -0,0 +1,98 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+/** A binary expression is an expression that consists of two operands and an operator
+ *
+ * e.g. `1 + 2`, `a === b`, `c < d`
+ */
+export default class BinaryExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'BinaryExpression');
+    }
+    run() {
+        const left = construct(this.node.left, this.context).run();
+        const right = construct(this.node.right, this.context).run();
+        return this.operate(left, right);
+    }
+    operate(left, right) {
+        switch (this.node.operator) {
+            case '==':
+            case '!=':
+            case '===':
+            case '!==':
+                return this.equality(this.node.operator, left, right);
+            case '<':
+            case '<=':
+            case '>':
+            case '>=':
+                return this.comparison(this.node.operator, left, right);
+            case 'in':
+                return this.checkIn(left, right);
+            case '**':
+            case '+':
+            case '-':
+            case '*':
+            case '/':
+            case '%':
+                return this.arithmetic(this.node.operator, left, right);
+            default:
+                throw new Error(`Unsupported operator: ${this.node.operator}`);
+        }
+    }
+    arithmetic(operator, left, right) {
+        if (operator === '+' && (typeof left === 'string' || typeof right === 'string')) {
+            return `${left}${right}`;
+        }
+        if (typeof left !== 'number' || typeof right !== 'number') {
+            throw new Error('Arithmetic operators are only supported for numbers');
+        }
+        switch (operator) {
+            case '+':
+                return left + right;
+            case '-':
+                return left - right;
+            case '*':
+                return left * right;
+            case '/':
+                return left / right;
+            case '%':
+                return left % right;
+            case '**':
+                return left ** right;
+        }
+    }
+    comparison(operator, left, right) {
+        if (typeof left !== 'number' || typeof right !== 'number') {
+            throw new Error('Comparison operators are only supported for numbers');
+        }
+        switch (operator) {
+            case '<':
+                return left < right;
+            case '<=':
+                return left <= right;
+            case '>':
+                return left > right;
+            case '>=':
+                return left >= right;
+        }
+    }
+    equality(operator, left, right) {
+        switch (operator) {
+            case '==':
+                // eslint-disable-next-line eqeqeq
+                return left == right;
+            case '!=':
+                // eslint-disable-next-line eqeqeq
+                return left != right;
+            case '===':
+                return left === right;
+            case '!==':
+                return left !== right;
+        }
+    }
+    checkIn(left, right) {
+        if (!Array.isArray(right)) {
+            throw new Error('The "in" operator is only supported for arrays');
+        }
+        return right.includes(left);
+    }
+}

package/esm/helpers/kscript/nodes/expressions/CallExpression.d.ts

@@ -0,0 +1,8 @@
+import { AnyNode, CallExpression } from 'acorn';
+import Context from '../../Context';
+import Node from '../Node';
+export default class CallExpressionNode extends Node<CallExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+    private spreadArgs;
+}

package/esm/helpers/kscript/nodes/expressions/CallExpression.js

@@ -0,0 +1,32 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+export default class CallExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'CallExpression');
+    }
+    run() {
+        if (!this.context.isFunctionCallAllowed)
+            throw new Error('Function calls are not allowed');
+        const callee = construct(this.node.callee, this.context).run();
+        let thisArg = {};
+        if (this.node.callee.type === 'MemberExpression') {
+            thisArg = construct(this.node.callee.object, this.context).run();
+        }
+        if (typeof callee !== 'function') {
+            throw new Error('callee is not a function');
+        }
+        const args = this.spreadArgs(this.node.arguments);
+        return callee.call(thisArg, ...args);
+    }
+    spreadArgs(args) {
+        return args.reduce((acc, arg) => {
+            if (arg.type === 'SpreadElement') {
+                acc.push(...construct(arg.argument, this.context).run());
+            }
+            else {
+                acc.push(construct(arg, this.context).run());
+            }
+            return acc;
+        }, []);
+    }
+}

package/esm/helpers/kscript/nodes/expressions/ChainExpression.d.ts

@@ -0,0 +1,16 @@
+import { AnyNode, ChainExpression } from 'acorn';
+import Context from '../../Context';
+import Node from '../Node';
+/**
+ * A ChainExpression node is created when the chain operator is used.
+ *
+ * e.g. `a?.b?.c`
+ *
+ * This node does not need to do anything special, as the chain operator is handled by the MemberExpressionNode.
+ *
+ * @see MemberExpressionNode
+ */
+export default class ExpressionStatementNode extends Node<ChainExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/expressions/ChainExpression.js

@@ -0,0 +1,19 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+/**
+ * A ChainExpression node is created when the chain operator is used.
+ *
+ * e.g. `a?.b?.c`
+ *
+ * This node does not need to do anything special, as the chain operator is handled by the MemberExpressionNode.
+ *
+ * @see MemberExpressionNode
+ */
+export default class ExpressionStatementNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'ChainExpression');
+    }
+    run() {
+        return construct(this.node.expression, this.context).run();
+    }
+}

package/esm/helpers/kscript/nodes/expressions/ConditionalExpression.d.ts

@@ -0,0 +1,14 @@
+import { AnyNode, ConditionalExpression, IfStatement } from 'acorn';
+import type Context from '../../Context';
+import Node from '../Node';
+/** Represents a ternary conditional expression (a ? b : c) or an if statement (if (a) b else c).
+ *
+ * If a (test) is truthy, b (consequent) is returned. Otherwise, c (alternate) is returned.
+ *
+ * Since the if statement and the conditional expression are so similar, they are both handled by this node,
+ * even though they are separate in the AST.
+ */
+export default class ConditionalExpressionNode extends Node<IfStatement | ConditionalExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/expressions/ConditionalExpression.js

@@ -0,0 +1,24 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+/** Represents a ternary conditional expression (a ? b : c) or an if statement (if (a) b else c).
+ *
+ * If a (test) is truthy, b (consequent) is returned. Otherwise, c (alternate) is returned.
+ *
+ * Since the if statement and the conditional expression are so similar, they are both handled by this node,
+ * even though they are separate in the AST.
+ */
+export default class ConditionalExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, ['ConditionalExpression', 'IfStatement']);
+    }
+    run() {
+        const test = construct(this.node.test, this.context).run();
+        if (test) {
+            return construct(this.node.consequent, this.context).run();
+        }
+        if (this.node.alternate === null || this.node.alternate === undefined) {
+            return undefined;
+        }
+        return construct(this.node.alternate, this.context).run();
+    }
+}

package/esm/helpers/kscript/nodes/expressions/ExpressionStatement.d.ts

@@ -0,0 +1,7 @@
+import { AnyNode, ExpressionStatement } from 'acorn';
+import Context from '../../Context';
+import Node from '../Node';
+export default class ExpressionStatementNode extends Node<ExpressionStatement> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

package/esm/helpers/kscript/nodes/expressions/ExpressionStatement.js

@@ -0,0 +1,12 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+export default class ExpressionStatementNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'ExpressionStatement');
+    }
+    run() {
+        if (this.node.directive)
+            throw new Error('Directives are not supported');
+        return construct(this.node.expression, this.context).run();
+    }
+}

package/esm/helpers/kscript/nodes/expressions/LogicalExpression.d.ts

@@ -0,0 +1,10 @@
+import { AnyNode, LogicalExpression } from 'acorn';
+import Context from '../../Context';
+import Node from '../Node';
+export default class BinaryExpressionNode extends Node<LogicalExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+    /** Try and skip evaluating the right operand */
+    private shortCircuit;
+    private operate;
+}

package/esm/helpers/kscript/nodes/expressions/LogicalExpression.js

@@ -0,0 +1,41 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+export default class BinaryExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'LogicalExpression');
+    }
+    run() {
+        const left = construct(this.node.left, this.context).run();
+        const shortCircuit = this.shortCircuit(left);
+        if (shortCircuit !== null) {
+            return shortCircuit;
+        }
+        const right = construct(this.node.right, this.context).run();
+        return this.operate(left, right);
+    }
+    /** Try and skip evaluating the right operand */
+    shortCircuit(left) {
+        if (this.node.operator === '&&' && !left) {
+            return false;
+        }
+        if (this.node.operator === '||' && left) {
+            return true;
+        }
+        if (this.node.operator === '??' && left !== null && left !== undefined) {
+            return left;
+        }
+        return null;
+    }
+    operate(left, right) {
+        switch (this.node.operator) {
+            case '||':
+                return left || right;
+            case '&&':
+                return left && right;
+            case '??':
+                return left ?? right;
+            default:
+                throw new Error(`Unsupported operator: ${this.node.operator}`);
+        }
+    }
+}

package/esm/helpers/kscript/nodes/expressions/MemberExpression.d.ts

@@ -0,0 +1,44 @@
+import { AnyNode, MemberExpression } from 'acorn';
+import Context from '../../Context';
+import Node from '../Node';
+/**
+ * A member expression is an expression that accesses a property of an object.
+ *
+ * Examples of member expressions are:
+ *  - `a.b`
+ *  - `a['b']`
+ *  - `a[0]`
+ *  - `a?.b`
+ *  - `a?.['b']`
+ *  - `a?.[0]`
+ *
+ *  A member access in the sandbox is considered secure if the following conditions are met:
+ *    - The property is not named 'constructor'
+ *    - Either:
+ *      * The property is owned by the object and is *not* on the whitelist.
+ *      * The prototype is whitelisted and the property list is null or contains the property.
+ *
+ *  @see Context.isPrototypeAllowed
+ */
+export default class MemberExpressionNode extends Node<MemberExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+    /** Returns the name of the property being accessed.
+     *
+     * Handles both computed and non-computed properties.
+     */
+    private getPropertyIdentifier;
+    /** Checks if the property can be accessed on the object.
+     *
+     * @throws {Error} If the property is not allowed to be accessed.
+     */
+    private checkPropertyAccess;
+    /** Searches the prototype chain of the object for the prototype that defines the property. */
+    private getPropertyPrototype;
+    /**
+     * Returns true if the property exists on the object.
+     *
+     * i.e. the property is defined somewhere on the prototype chain.
+     */
+    private propertyExists;
+}

package/esm/helpers/kscript/nodes/expressions/MemberExpression.js

@@ -0,0 +1,92 @@
+import Node from '../Node';
+import { construct } from '../../utils';
+/**
+ * A member expression is an expression that accesses a property of an object.
+ *
+ * Examples of member expressions are:
+ *  - `a.b`
+ *  - `a['b']`
+ *  - `a[0]`
+ *  - `a?.b`
+ *  - `a?.['b']`
+ *  - `a?.[0]`
+ *
+ *  A member access in the sandbox is considered secure if the following conditions are met:
+ *    - The property is not named 'constructor'
+ *    - Either:
+ *      * The property is owned by the object and is *not* on the whitelist.
+ *      * The prototype is whitelisted and the property list is null or contains the property.
+ *
+ *  @see Context.isPrototypeAllowed
+ */
+export default class MemberExpressionNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'MemberExpression');
+    }
+    run() {
+        const object = construct(this.node.object, this.context).run();
+        if (object === null || object === undefined) {
+            if (this.node.optional)
+                return undefined;
+            throw new Error(`Cannot read property of ${object}`);
+        }
+        const propertyIdentifier = this.getPropertyIdentifier();
+        if (!this.propertyExists(object, propertyIdentifier)) {
+            return undefined;
+        }
+        this.checkPropertyAccess(object, propertyIdentifier);
+        return object[propertyIdentifier];
+    }
+    /** Returns the name of the property being accessed.
+     *
+     * Handles both computed and non-computed properties.
+     */
+    getPropertyIdentifier() {
+        if (this.node.computed) {
+            const name = construct(this.node.property, this.context).run();
+            if (typeof name !== 'string' && typeof name !== 'number') {
+                throw new Error('Only string or number computed properties are supported');
+            }
+            return name;
+        }
+        if (this.node.property.type !== 'Identifier') {
+            throw new Error('Only identifiers are supported for non-computed member expression properties');
+        }
+        return this.node.property.name;
+    }
+    /** Checks if the property can be accessed on the object.
+     *
+     * @throws {Error} If the property is not allowed to be accessed.
+     */
+    checkPropertyAccess(object, propertyIdentifier) {
+        if (typeof propertyIdentifier === 'number')
+            return;
+        if (propertyIdentifier === 'constructor') {
+            throw new Error('Cannot access constructor property');
+        }
+        const definingProto = this.getPropertyPrototype(object, propertyIdentifier);
+        const ownProperty = Object.prototype.hasOwnProperty.call(object, propertyIdentifier);
+        if (!this.context.isPrototypeAllowed(definingProto, propertyIdentifier, ownProperty)) {
+            throw new Error(`SecurityError: Access to property '${propertyIdentifier}' is not allowed`);
+        }
+    }
+    /** Searches the prototype chain of the object for the prototype that defines the property. */
+    getPropertyPrototype(object, propertyIdentifier) {
+        let proto = object;
+        while (proto !== null) {
+            if (Object.prototype.hasOwnProperty.call(proto, propertyIdentifier)) {
+                return proto;
+            }
+            proto = Object.getPrototypeOf(proto);
+        }
+        return null;
+    }
+    /**
+     * Returns true if the property exists on the object.
+     *
+     * i.e. the property is defined somewhere on the prototype chain.
+     */
+    propertyExists(object, propertyIdentifier) {
+        return this.getPropertyPrototype(object, propertyIdentifier) !== null;
+    }
+}

package/esm/helpers/kscript/nodes/expressions/ObjectExpression.d.ts

@@ -0,0 +1,11 @@
+import { AnyNode, ObjectExpression } from 'acorn';
+import type Context from '../../Context';
+import Node from '../Node';
+export default class ObjectExpressionNode extends Node<ObjectExpression> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+    private addProperty;
+    private spreadProperty;
+    private getKey;
+    private getStaticKey;
+}