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

package/esm/helpers/kscript/Context.d.ts

@@ -0,0 +1,34 @@
+import { AnyNode } from 'acorn';
+import type { NodeType } from './nodes';
+/**
+ * A map of node types to a set of property names that are allowed to be accessed
+ * on the prototype of the object.
+ *
+ * If the set is null, all properties are allowed.
+ */
+export type PrototypeWhitelist = Map<unknown, Set<string> | null>;
+export type Scope = Map<string, unknown> | Record<string, unknown>;
+export interface ContextOptions {
+    nodeBlacklist?: Set<NodeType>;
+    prototypeWhitelist?: PrototypeWhitelist;
+    functionCallsAllowed?: boolean;
+}
+export default class Context {
+    readonly scope: Map<string, unknown>;
+    readonly isFunctionCallAllowed: boolean;
+    private readonly options;
+    constructor(scope?: Scope, options?: ContextOptions);
+    isNodeAllowed(nodeType: AnyNode['type']): boolean;
+    newChildContext(scope: Scope): Context;
+    /** Returns true if the property is allowed to be accessed on the prototype.
+     *
+     * - If the prototype is not in the whitelist, the property is allowed only if it is an own property.
+     * - If the prototype is in the whitelist, the property is allowed if it is in the set or the set is null.
+     *
+     * @param prototype The prototype which contains the property being accessed.
+     * @param property The name of the property being accessed.
+     * @param ownProperty Whether the property is owned by the object it is being accessed on.
+     */
+    isPrototypeAllowed(prototype: unknown, property: string, ownProperty: boolean): boolean;
+    private static buildMap;
+}

package/esm/helpers/kscript/Context.js

@@ -0,0 +1,49 @@
+export default class Context {
+    constructor(scope, options) {
+        this.scope = scope ? Context.buildMap(scope) : new Map();
+        this.options = {
+            nodeBlacklist: options?.nodeBlacklist ?? new Set(),
+            prototypeWhitelist: options?.prototypeWhitelist ?? new Map(),
+            functionCallsAllowed: options?.functionCallsAllowed ?? true,
+        };
+        this.isFunctionCallAllowed = this.options.functionCallsAllowed;
+    }
+    isNodeAllowed(nodeType) {
+        return !this.options.nodeBlacklist.has(nodeType);
+    }
+    newChildContext(scope) {
+        let newEntries;
+        if (scope instanceof Map) {
+            newEntries = [...scope.entries()];
+        }
+        else {
+            newEntries = Object.entries(scope);
+        }
+        const newScope = new Map([...this.scope.entries(), ...newEntries]);
+        return new Context(newScope, this.options);
+    }
+    /** Returns true if the property is allowed to be accessed on the prototype.
+     *
+     * - If the prototype is not in the whitelist, the property is allowed only if it is an own property.
+     * - If the prototype is in the whitelist, the property is allowed if it is in the set or the set is null.
+     *
+     * @param prototype The prototype which contains the property being accessed.
+     * @param property The name of the property being accessed.
+     * @param ownProperty Whether the property is owned by the object it is being accessed on.
+     */
+    isPrototypeAllowed(prototype, property, ownProperty) {
+        const whitelist = this.options.prototypeWhitelist.get(prototype);
+        // If the object owns the property, and it's not in the whitelist, it's allowed.
+        // This prevents direct calls to non-whitelisted properties on allowed prototypes
+        // e.g. Object.prototype.hasOwnProperty.call(obj, 'toString')
+        if (whitelist === undefined)
+            return ownProperty;
+        // all properties allowed if no set is provided
+        if (whitelist === null)
+            return true;
+        return whitelist.has(property);
+    }
+    static buildMap(obj) {
+        return obj instanceof Map ? obj : new Map(Object.entries(obj));
+    }
+}

package/esm/helpers/kscript/index.d.ts

@@ -0,0 +1 @@
+export * as kscript from './kscript';

package/esm/helpers/kscript/index.js

@@ -0,0 +1 @@
+export * as kscript from './kscript';

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

@@ -0,0 +1,6 @@
+import { ContextOptions, PrototypeWhitelist, Scope } from './Context';
+import { Node } from './nodes';
+export declare function execute(code: string, scope?: Scope, options?: ContextOptions): unknown;
+export declare function compile(code: string, scope?: Scope, options?: ContextOptions): Node;
+export declare const SAFE_GLOBALS: Map<string, unknown>;
+export declare const SAFE_PROTOTYPES: PrototypeWhitelist;

package/esm/helpers/kscript/kscript.js

@@ -0,0 +1,107 @@
+import Context from './Context';
+import { parse } from 'acorn';
+import { construct } from './utils';
+export function execute(code, scope, options) {
+    return compile(code, scope, options).run();
+}
+export function compile(code, scope, options) {
+    let program;
+    try {
+        // we add the brackets to ensure that object literals are parsed correctly
+        program = parse(`(${code})`, { ecmaVersion: 2020, sourceType: 'script' });
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            // fallback to non-wrapped code for edge cases where the brackets cause issues
+            program = parse(`${code}`, { ecmaVersion: 2020, sourceType: 'script' });
+        }
+        else {
+            throw error;
+        }
+    }
+    const context = new Context(scope ?? SAFE_GLOBALS, {
+        prototypeWhitelist: SAFE_PROTOTYPES,
+        ...options,
+    });
+    return construct(program, context);
+}
+export const SAFE_GLOBALS = new Map(Object.entries({
+    console: {
+        debug: console.debug,
+        error: console.error,
+        info: console.info,
+        log: console.log,
+        warn: console.warn,
+    },
+    isFinite,
+    isNaN,
+    Number,
+    Object,
+    Array,
+    Symbol,
+    Error,
+    JSON,
+    Math,
+    Date,
+    RegExp,
+}));
+export const SAFE_PROTOTYPES = new Map([
+    [Number.prototype, new Set(['toString', 'toFixed', 'toExponential', 'toPrecision'])],
+    [
+        String.prototype,
+        new Set([
+            'toString',
+            'charAt',
+            'charCodeAt',
+            'concat',
+            'indexOf',
+            'lastIndexOf',
+            'localeCompare',
+            'match',
+            'replace',
+            'search',
+            'slice',
+            'split',
+            'substring',
+            'toLowerCase',
+            'toUpperCase',
+            'trim',
+            'valueOf',
+        ]),
+    ],
+    [
+        Array.prototype,
+        new Set([
+            'filter',
+            'map',
+            'find',
+            'findIndex',
+            'forEach',
+            'every',
+            'some',
+            'reduce',
+            'reduceRight',
+            'sort',
+            'slice',
+            'splice',
+            'concat',
+            'indexOf',
+            'lastIndexOf',
+            'includes',
+            'join',
+            'reverse',
+            'shift',
+            'unshift',
+            'pop',
+            'push',
+            'copyWithin',
+            'fill',
+            'entries',
+            'keys',
+            'values',
+            'flat',
+            'flatMap',
+        ]),
+    ],
+    [Object.prototype, new Set(['toString'])],
+]);

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

@@ -0,0 +1,12 @@
+import { AnyNode, Identifier } from 'acorn';
+import type Context from '../Context';
+import Node from './Node';
+/** An Identifier is a reference to a variable.
+ *
+ * Variables must be declared in the current scope.
+ * If the variable is not found, undefined is returned.
+ */
+export default class IdentifierNode extends Node<Identifier> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

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

@@ -0,0 +1,14 @@
+import Node from './Node';
+/** An Identifier is a reference to a variable.
+ *
+ * Variables must be declared in the current scope.
+ * If the variable is not found, undefined is returned.
+ */
+export default class IdentifierNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'Identifier');
+    }
+    run() {
+        return this.scope.get(this.node.name);
+    }
+}

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

@@ -0,0 +1,11 @@
+import { AnyNode, Literal } from 'acorn';
+import Context from '../Context';
+import Node from './Node';
+/** Represents a literal value
+ *
+ * e.g. `1`, `'hello'`, `true`
+ */
+export default class LiteralNode extends Node<Literal> {
+    constructor(node: AnyNode, context: Context);
+    run(): unknown;
+}

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

@@ -0,0 +1,16 @@
+import Node from './Node';
+/** Represents a literal value
+ *
+ * e.g. `1`, `'hello'`, `true`
+ */
+export default class LiteralNode extends Node {
+    constructor(node, context) {
+        super(node, context, 'Literal');
+    }
+    run() {
+        if (this.node.bigint) {
+            throw new Error('BigInts are not supported');
+        }
+        return this.node.value;
+    }
+}

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

@@ -0,0 +1,9 @@
+import { AnyNode } from 'acorn';
+import type Context from '../Context';
+export default abstract class Node<T extends AnyNode = AnyNode> {
+    protected context: Context;
+    protected node: T;
+    protected scope: Context['scope'];
+    protected constructor(node: AnyNode, context: Context, expectedType: T['type'] | T['type'][]);
+    abstract run(): unknown;
+}

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

@@ -0,0 +1,12 @@
+export default class Node {
+    constructor(node, context, expectedType) {
+        this.context = context;
+        const expectedTypes = Array.isArray(expectedType) ? expectedType : [expectedType];
+        if (!expectedTypes.includes(node.type)) {
+            console.error(node);
+            throw new Error(`Expected node type to be ${expectedTypes.join(' or ')}, but got ${node.type}`);
+        }
+        this.node = node;
+        this.scope = context.scope;
+    }
+}

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();
+    }
+}