refactor: clean up

Author: danpoletaev

packages/math-utils/CHANGELOG.md renamed to packages/actor-memory-expression/CHANGELOG.md

@@ -1,5 +1,5 @@
 {
-    "name": "@apify/math-utils",
+    "name": "@apify/actor-memory-expression",
     "version": "0.0.1",
     "description": "Mathematical and numerical utility functions.",
     "main": "./dist/cjs/index.cjs",

packages/math-utils/package.json renamed to packages/actor-memory-expression/package.json

@@ -21,23 +21,12 @@ import {
 import { ACTOR_LIMITS } from '@apify/consts';
 
 import type { LruCache } from '../../datastructures/src/lru_cache';
+import type { ActorRunOptions, MemoryEvaluationContext } from './types.js';
 
-type ActorRunOptions = {
-    build?: string;
-    timeoutSecs?: number;
-    memoryMbytes?: number; // probably no one will need it, but let's keep it consistent
-    diskMbytes?: number; // probably no one will need it, but let's keep it consistent
-    maxItems?: number;
-    maxTotalChargeUsd?: number;
-    restartOnError?: boolean;
-}
-
-type MemoryEvaluationContext = {
-    runOptions: ActorRunOptions;
-    input: Record<string, unknown>;
-}
-
-export const DEFAULT_MEMORY_MBYTES_MAX_CHARS = 1000;
+// In theory, users could create expressions longer than 1000 characters,
+// but in practice, it's unlikely anyone would need that much complexity.
+// Later we can increase this limit if needed.
+export const DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH = 1000;
 
 /**
  * A Set of allowed keys from ActorRunOptions that can be used in
@@ -58,14 +47,18 @@ const ALLOWED_RUN_OPTION_KEYS = new Set<keyof ActorRunOptions>([
  * MathJS security recommendations: https://mathjs.org/docs/expressions/security.html
  */
 const math = create({
+    // expression dependencies
+    // Required for compiling and evaluating root expressions.
+    // We disable it below to prevent users from calling `evaluate()` inside their expressions.
+    // For example: defaultMemoryMbytes = "evaluate('2 + 2')"
+    compileDependencies,
+    evaluateDependencies,
+
     // arithmetic dependencies
     addDependencies,
     subtractDependencies,
     multiplyDependencies,
     divideDependencies,
-    // expression dependencies
-    compileDependencies,
-    evaluateDependencies,
     // statistics dependencies
     maxDependencies,
     minDependencies,
@@ -77,8 +70,7 @@ const math = create({
     // without that dependency 'null ?? 5', won't work
     nullishDependencies,
 });
-const limitedEvaluate = math.evaluate;
-const limitedCompile = math.compile;
+const { compile } = math;
 
 // Disable potentially dangerous functions
 math.import({
@@ -88,6 +80,8 @@ math.import({
     reviver() { throw new Error('Function reviver is disabled'); },
 
     // extra (has functional impact)
+    // We disable evaluate to prevent users from calling it inside their expressions.
+    // For example: defaultMemoryMbytes = "evaluate('2 + 2')"
     evaluate() { throw new Error('Function evaluate is disabled'); },
     parse() { throw new Error('Function parse is disabled'); },
     simplify() { throw new Error('Function simplify is disabled'); },
@@ -118,7 +112,7 @@ const customGetFunc = (obj: any, path: string, defaultVal?: number) => {
 */
 const roundToClosestPowerOf2 = (num: number): number | undefined => {
     if (typeof num !== 'number' || Number.isNaN(num)) {
-        throw new Error(`Failed to round number to a power of 2.`);
+        throw new Error(`Calculated memory value is not a valid number: ${num}.`);
     }
 
     // Handle 0 or negative values.
@@ -135,8 +129,14 @@ const roundToClosestPowerOf2 = (num: number): number | undefined => {
 };
 
 /**
- * Replaces `{{variable}}` placeholders in an expression string with the variable name.
- * Enforces strict validation to allow `{{input.*}}` paths or whitelisted `{{runOptions.*}}` keys.
+ * Replaces all `{{variable}}` placeholders in an expression into direct
+ * property access (e.g. `{{runOptions.memoryMbytes}}` → `runOptions.memoryMbytes`).
+ *
+ * Only variables starting with `input.` or whitelisted `runOptions.` keys are allowed.
+ * All `input.*` values are accepted, while `runOptions.*` are validated (only 7 variables - ALLOWED_RUN_OPTION_KEYS).
+ *
+ * Note: this approach allows developers to use a consistent double-brace
+ * syntax (`{{runOptions.timeoutSecs}}`) across the platform.
  *
  * @example
  * // Returns "runOptions.memoryMbytes + 1024"
@@ -145,26 +145,25 @@ const roundToClosestPowerOf2 = (num: number): number | undefined => {
  * @param defaultMemoryMbytes The raw string expression, e.g., "{{runOptions.memoryMbytes}} * 2".
  * @returns A safe, processed expression for evaluation, e.g., "runOptions.memoryMbytes * 2".
  */
-const preprocessRunMemoryExpression = (defaultMemoryMbytes: string): string => {
+const processTemplateVariables = (defaultMemoryMbytes: string): string => {
     const variableRegex = /{{\s*([a-zA-Z0-9_.]+)\s*}}/g;
 
     const processedExpression = defaultMemoryMbytes.replace(
         variableRegex,
         (_, variableName: string) => {
-            // 1. Validate that the variable starts with either 'input.' or 'runOptions.'
             if (!variableName.startsWith('runOptions.') && !variableName.startsWith('input.')) {
                 throw new Error(
                     `Invalid variable '{{${variableName}}}' in expression. Variables must start with 'input.' or 'runOptions.'.`,
                 );
             }
 
-            // 2. Check if the variable is accessing input (e.g. {{input.someValue}})
-            // We do not validate the specific property name because input is dynamic.
+            // 1. Check if the variable is accessing input (e.g. {{input.someValue}})
+            // We do not validate the specific property name because `input` is dynamic.
             if (variableName.startsWith('input.')) {
                 return variableName;
             }
 
-            // 3. Check if the variable is accessing runOptions (e.g. {{runOptions.memoryMbytes}}) and validate the keys.
+            // 2. Check if the variable is accessing runOptions (e.g. {{runOptions.memoryMbytes}}) and validate the keys.
             if (variableName.startsWith('runOptions.')) {
                 const key = variableName.slice('runOptions.'.length);
                 if (!ALLOWED_RUN_OPTION_KEYS.has(key as keyof ActorRunOptions)) {
@@ -185,11 +184,26 @@ const preprocessRunMemoryExpression = (defaultMemoryMbytes: string): string => {
     return processedExpression;
 };
 
+const getCompiledExpression = (expression: string, cache: LruCache<EvalFunction> | undefined): EvalFunction => {
+    if (!cache) {
+        return compile(expression);
+    }
+
+    let compiledExpression = cache.get(expression);
+
+    if (!compiledExpression) {
+        compiledExpression = compile(expression);
+        cache.add(expression, compiledExpression!);
+    }
+
+    return compiledExpression;
+};
+
 /**
  * Evaluates a dynamic memory expression string using the provided context.
  * Result is rounded to the closest power of 2 and clamped within allowed limits.
  *
- * @param defaultMemoryMbytes The string expression to evaluate (e.g., "get(input, 'size', 10) * 1024").
+ * @param defaultMemoryMbytes The string expression to evaluate (e.g., `get(input, 'urls.length', 10) * 1024` for `input = { urls: ['url1', 'url2'] }`).
  * @param context The `MemoryEvaluationContext` (containing `input` and `runOptions`) available to the expression.
  * @returns The calculated memory value rounded to the closest power of 2 clamped within allowed limits.
 */
@@ -198,33 +212,22 @@ export const calculateRunDynamicMemory = (
     context: MemoryEvaluationContext,
     options: { cache: LruCache<EvalFunction> } | undefined = undefined,
 ) => {
-    if (defaultMemoryMbytes.length > DEFAULT_MEMORY_MBYTES_MAX_CHARS) {
-        throw new Error(`The defaultMemoryMbytes expression is too long. Max length is ${DEFAULT_MEMORY_MBYTES_MAX_CHARS} characters.`);
+    if (defaultMemoryMbytes.length > DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH) {
+        throw new Error(`The defaultMemoryMbytes expression is too long. Max length is ${DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH} characters.`);
     }
 
     // Replaces all occurrences of {{variable}} with variable
     // e.g., "{{runOptions.memoryMbytes}} + 1024" becomes "runOptions.memoryMbytes + 1024"
-    const preprocessedExpression = preprocessRunMemoryExpression(defaultMemoryMbytes);
+    const preprocessedExpression = processTemplateVariables(defaultMemoryMbytes);
 
     const preparedContext = {
         ...context,
         get: customGetFunc,
     };
 
-    let finalResult: number | { entries: number[] };
-
-    if (options?.cache) {
-        let compiledExpr = options.cache.get(preprocessedExpression);
+    const compiledExpression = getCompiledExpression(preprocessedExpression, options?.cache);
 
-        if (!compiledExpr) {
-            compiledExpr = limitedCompile(preprocessedExpression);
-            options.cache.add(preprocessedExpression, compiledExpr!);
-        }
-
-        finalResult = compiledExpr.evaluate(preparedContext);
-    } else {
-        finalResult = limitedEvaluate(preprocessedExpression, preparedContext);
-    }
+    let finalResult: number | { entries: number[] } = compiledExpression.evaluate(preparedContext);
 
     // Mathjs wraps multi-line expressions in an object, so we need to extract the last entry.
     // Note: one-line expressions return a number directly.

packages/math-utils/src/index.ts renamed to packages/actor-memory-expression/src/index.ts

@@ -0,0 +1,14 @@
+export type ActorRunOptions = {
+    build?: string;
+    timeoutSecs?: number;
+    memoryMbytes?: number; // probably no one will need it, but let's keep it consistent
+    diskMbytes?: number; // probably no one will need it, but let's keep it consistent
+    maxItems?: number;
+    maxTotalChargeUsd?: number;
+    restartOnError?: boolean;
+}
+
+export type MemoryEvaluationContext = {
+    runOptions: ActorRunOptions;
+    input: Record<string, unknown>;
+}

packages/math-utils/src/memory_calculator.ts renamed to packages/actor-memory-expression/src/memory_calculator.ts

@@ -1,7 +1,7 @@
 import type { EvalFunction } from 'mathjs';
 
+import { calculateRunDynamicMemory, DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH } from '@apify/actor-memory-expression';
 import { LruCache } from '@apify/datastructures';
-import { calculateRunDynamicMemory, DEFAULT_MEMORY_MBYTES_MAX_CHARS } from '@apify/math-utils';
 
 describe('calculateDefaultMemoryFromExpression', () => {
     const emptyContext = { input: {}, runOptions: {} };
@@ -59,62 +59,64 @@ describe('calculateDefaultMemoryFromExpression', () => {
                 runOptions: { timeoutSecs: 60, memoryMbytes: 512 },
             };
 
+            // Note: all results are rounded to the closest power of 2 and clamped within limits.
             const cases = [
-                { expression: '5 + 5', desc: '+ allowed' },
-                { expression: '6 - 5', desc: '- allowed' },
-                { expression: '5 / 5', desc: '/ allowed' },
-                { expression: '5 * 5', desc: '* allowed' },
-                { expression: 'max(1, 2, 3)', desc: 'max() allowed' },
-                { expression: 'min(1, 2, 3)', desc: 'min() allowed' },
-                { expression: '(true and false) ? 0 : 5', desc: 'and allowed' },
-                { expression: '(true or false) ? 5 : 0', desc: 'or allowed' },
-                { expression: '(true xor false) ? 5 : 0', desc: 'xor allowed' },
-                { expression: 'not(false) ? 5 : 0', desc: 'not allowed' },
-                { expression: 'null ?? 256', desc: 'nullish coalescing allowed' },
-                { expression: 'a = 5', desc: 'variable assignment' },
+                { expression: '128 + 5', result: 128, name: '+' },
+                { expression: '128 - 5', result: 128, name: '-' },
+                { expression: '128 / 5', result: 128, name: '/' },
+                { expression: '128 * 5', result: 512, name: '*' },
+                { expression: 'max(128, 2, 3)', result: 128, name: 'max()' },
+                { expression: 'min(128, 512, 1024)', result: 128, name: 'min()' },
+                { expression: '(true and false) ? 0 : 128', result: 128, name: 'and' },
+                { expression: '(true or false) ? 128 : 0', result: 128, name: 'or' },
+                { expression: '(true xor false) ? 128 : 0', result: 128, name: 'xor' },
+                { expression: 'not(false) ? 128 : 0', result: 128, name: 'not' },
+                { expression: 'null ?? 256', result: 256, name: 'nullish coalescing' },
+                { expression: 'a = 128', result: 128, name: '=' },
             ];
 
             it.each(cases)(
-                '$desc',
-                ({ expression }) => {
+                `supports operation '$name'`,
+                ({ expression, result }) => {
                     // in case operation is not supported, mathjs will throw
-                    expect(calculateRunDynamicMemory(expression, context)).toBeDefined();
+                    // we round the result to the closest power of 2 and clamp within limits.
+                    expect(calculateRunDynamicMemory(expression, context)).toBe(result);
                 },
             );
         });
     });
 
-    describe('Preprocessing with {{variable}}', () => {
-        it('should throw error if variable doesn\'t start with .runOptions or .input', () => {
+    describe('Template {{variables}} support', () => {
+        it('should throw error if variable doesn\'t start with runOptions. or input.', () => {
             const context = { input: {}, runOptions: { memoryMbytes: 16 } };
-            const expr = '{{unexistingVariable}} * 1024';
+            const expr = '{{nonexistentVariable}} * 1024';
             expect(() => calculateRunDynamicMemory(expr, context))
-                .toThrow(`Invalid variable '{{unexistingVariable}}' in expression. Variables must start with 'input.' or 'runOptions.'.`);
+                .toThrow(`Invalid variable '{{nonexistentVariable}}' in expression. Variables must start with 'input.' or 'runOptions.'.`);
         });
 
-        it('correctly replaces {{runOptions.variable}} with valid runOptions.variable', () => {
+        it('correctly evaluates valid runOptions property', () => {
             const context = { input: {}, runOptions: { memoryMbytes: 16 } };
             const expr = '{{runOptions.memoryMbytes}} * 1024';
             const result = calculateRunDynamicMemory(expr, context);
             expect(result).toBe(16384);
         });
 
-        it('correctly replaces {{input.variable}} with valid input.variable', () => {
+        it('correctly evaluates input property', () => {
             const context = { input: { value: 16 }, runOptions: { } };
             const expr = '{{input.value}} * 1024';
             const result = calculateRunDynamicMemory(expr, context);
             expect(result).toBe(16384);
         });
 
-        it('should throw error if runOptions variable is invalid', () => {
+        it('should throw error if runOptions property is not supported', () => {
             const context = { input: { value: 16 }, runOptions: { } };
             const expr = '{{runOptions.customVariable}} * 1024';
             expect(() => calculateRunDynamicMemory(expr, context))
                 .toThrow(`Invalid variable '{{runOptions.customVariable}}' in expression. Only the following runOptions are allowed:`);
         });
     });
 
-    describe('Rounding Logic', () => {
+    describe('Rounding logic', () => {
         it('should round down (e.g., 10240 -> 8192)', () => {
             // 2^13 = 8192, 2^14 = 16384.
             const result = calculateRunDynamicMemory('10240', emptyContext);
@@ -140,9 +142,9 @@ describe('calculateDefaultMemoryFromExpression', () => {
 
     describe('Invalid/Error Handling', () => {
         it('should throw an error if expression length is greater than DEFAULT_MEMORY_MBYTES_MAX_CHARS', () => {
-            const expr = '1'.repeat(DEFAULT_MEMORY_MBYTES_MAX_CHARS + 1); // Assuming max length is 1000
+            const expr = '1'.repeat(DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH + 1); // Assuming max length is 1000
             expect(() => calculateRunDynamicMemory(expr, emptyContext))
-                .toThrow(`The defaultMemoryMbytes expression is too long. Max length is ${DEFAULT_MEMORY_MBYTES_MAX_CHARS} characters.`);
+                .toThrow(`The defaultMemoryMbytes expression is too long. Max length is ${DEFAULT_MEMORY_MBYTES_EXPRESSION_MAX_LENGTH} characters.`);
         });
 
         it('should throw an error for invalid syntax', () => {
@@ -160,11 +162,11 @@ describe('calculateDefaultMemoryFromExpression', () => {
         });
 
         it('should throw error if result is NaN', () => {
-            expect(() => calculateRunDynamicMemory('0 / 0', emptyContext)).toThrow('Failed to round number to a power of 2.');
+            expect(() => calculateRunDynamicMemory('0 / 0', emptyContext)).toThrow('Calculated memory value is not a valid number: NaN.');
         });
 
         it('should throw error if result is a non-numeric (string)', () => {
-            expect(() => calculateRunDynamicMemory("'hello'", emptyContext)).toThrow('Failed to round number to a power of 2.');
+            expect(() => calculateRunDynamicMemory("'hello'", emptyContext)).toThrow('Calculated memory value is not a valid number: hello.');
         });
 
         it('should throw error when disabled functionality of MathJS is used', () => {