@dronedeploy/rocos-js-sdk 3.0.1-alpha.20 → 3.0.1-alpha.21

package/cjs/helpers/index.d.ts

@@ -3,3 +3,4 @@ export * from './standardDeviation';
 export * from './generateUUID';
 export * from './getURLSearchParams';
 export * from './websandbox';
+export * from './kscript';

package/cjs/helpers/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./standardDeviation"), exports);
 __exportStar(require("./generateUUID"), exports);
 __exportStar(require("./getURLSearchParams"), exports);
 __exportStar(require("./websandbox"), exports);
+__exportStar(require("./kscript"), exports);

package/cjs/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/cjs/helpers/kscript/Context.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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));
+    }
+}
+exports.default = Context;

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

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

package/cjs/helpers/kscript/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kscript = void 0;
+exports.kscript = __importStar(require("./kscript"));

package/cjs/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/cjs/helpers/kscript/kscript.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAFE_PROTOTYPES = exports.SAFE_GLOBALS = exports.compile = exports.execute = void 0;
+const Context_1 = __importDefault(require("./Context"));
+const acorn_1 = require("acorn");
+const utils_1 = require("./utils");
+function execute(code, scope, options) {
+    return compile(code, scope, options).run();
+}
+exports.execute = execute;
+function compile(code, scope, options) {
+    let program;
+    try {
+        // we add the brackets to ensure that object literals are parsed correctly
+        program = (0, acorn_1.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 = (0, acorn_1.parse)(`${code}`, { ecmaVersion: 2020, sourceType: 'script' });
+        }
+        else {
+            throw error;
+        }
+    }
+    const context = new Context_1.default(scope ?? exports.SAFE_GLOBALS, {
+        prototypeWhitelist: exports.SAFE_PROTOTYPES,
+        ...options,
+    });
+    return (0, utils_1.construct)(program, context);
+}
+exports.compile = compile;
+exports.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,
+}));
+exports.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/cjs/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/cjs/helpers/kscript/nodes/Identifier.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("./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.
+ */
+class IdentifierNode extends Node_1.default {
+    constructor(node, context) {
+        super(node, context, 'Identifier');
+    }
+    run() {
+        return this.scope.get(this.node.name);
+    }
+}
+exports.default = IdentifierNode;

package/cjs/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/cjs/helpers/kscript/nodes/Literal.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("./Node"));
+/** Represents a literal value
+ *
+ * e.g. `1`, `'hello'`, `true`
+ */
+class LiteralNode extends Node_1.default {
+    constructor(node, context) {
+        super(node, context, 'Literal');
+    }
+    run() {
+        if (this.node.bigint) {
+            throw new Error('BigInts are not supported');
+        }
+        return this.node.value;
+    }
+}
+exports.default = LiteralNode;

package/cjs/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/cjs/helpers/kscript/nodes/Node.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+    }
+}
+exports.default = Node;

package/cjs/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/cjs/helpers/kscript/nodes/Program.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("./Node"));
+const utils_1 = require("../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.
+ */
+class ProgramNode extends Node_1.default {
+    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 (0, utils_1.construct)(children[0], this.context).run();
+    }
+}
+exports.default = ProgramNode;

package/cjs/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/cjs/helpers/kscript/nodes/TemplateLiteral.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("./Node"));
+const utils_1 = require("../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.
+ */
+class TemplateLiteralNode extends Node_1.default {
+    constructor(node, scope) {
+        super(node, scope, 'TemplateLiteral');
+    }
+    run() {
+        return this.node.quasis.reduce((acc, quasi, i) => {
+            const expression = this.node.expressions[i] ? (0, utils_1.construct)(this.node.expressions[i], this.context).run() : '';
+            return acc + quasi.value.raw + expression;
+        }, '');
+    }
+}
+exports.default = TemplateLiteralNode;

package/cjs/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/cjs/helpers/kscript/nodes/expressions/ArrayExpression.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("../Node"));
+const utils_1 = require("../../utils");
+class ArrayExpressionNode extends Node_1.default {
+    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(...(0, utils_1.construct)(element.argument, this.context).run());
+            }
+            else {
+                array.push((0, utils_1.construct)(element, this.context).run());
+            }
+        }
+        return array;
+    }
+}
+exports.default = ArrayExpressionNode;

package/cjs/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/cjs/helpers/kscript/nodes/expressions/ArrowFunctionExpression.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("../Node"));
+const utils_1 = require("../../utils");
+/** Represents an arrow function expression.
+ *
+ * e.g. `(a, b) => a + b`
+ *
+ * In the sandbox this is the only way to define a function.
+ */
+class ArrowFunctionExpressionNode extends Node_1.default {
+    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 (0, utils_1.construct)(this.node.body, newContext).run();
+        };
+    }
+}
+exports.default = ArrowFunctionExpressionNode;

package/cjs/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/cjs/helpers/kscript/nodes/expressions/BinaryExpression.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Node_1 = __importDefault(require("../Node"));
+const utils_1 = require("../../utils");
+/** A binary expression is an expression that consists of two operands and an operator
+ *
+ * e.g. `1 + 2`, `a === b`, `c < d`
+ */
+class BinaryExpressionNode extends Node_1.default {
+    constructor(node, context) {
+        super(node, context, 'BinaryExpression');
+    }
+    run() {
+        const left = (0, utils_1.construct)(this.node.left, this.context).run();
+        const right = (0, utils_1.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);
+    }
+}
+exports.default = BinaryExpressionNode;