@shipfox/expression 2.0.0 → 2.2.0

package/dist/workflow-function-registry.js

@@ -0,0 +1,133 @@
+import { stringifyBigint } from './json.js';
+/** Maximum number of values one evaluation's range calls may materialize. */ export const MAX_RANGE_ELEMENTS = 1_000;
+/** Maximum context-byte fan-out one evaluation's range calls may represent. */ export const MAX_RANGE_FANOUT_BYTES = 1_000_000;
+/** Maximum UTF-8 bytes returned by toJson() calls in one evaluation. */ export const MAX_JSON_OUTPUT_BYTES = 1_000_000;
+const utf8Encoder = new TextEncoder();
+const RANGE_FUNCTION_SIGNATURE = 'range(dyn, dyn, dyn): list<int>';
+const TO_JSON_FUNCTION_SIGNATURE = 'toJson(dyn): string';
+const FROM_JSON_FUNCTION_SIGNATURE = 'fromJson(string): dyn';
+const workflowFunctionRegistry = [
+    {
+        signature: RANGE_FUNCTION_SIGNATURE,
+        createHandler: (budget)=>(start, stop, step)=>evaluateRange(budget, start, stop, step)
+    },
+    {
+        signature: TO_JSON_FUNCTION_SIGNATURE,
+        createHandler: (budget)=>(value)=>serializeJson(budget, value)
+    },
+    {
+        signature: FROM_JSON_FUNCTION_SIGNATURE,
+        createHandler: ()=>(value)=>{
+                if (typeof value !== 'string') throw new TypeError('fromJson() expects a JSON string');
+                return JSON.parse(value, reviveJsonNumber);
+            }
+    }
+];
+/**
+ * Register the shared functions and return the budgets their handlers close over.
+ *
+ * Callers that reuse one environment across evaluations must wrap each evaluation
+ * in `isolate` so it gets a full budget without consuming an enclosing one. A
+ * context accessor can re-enter the evaluator, so the enclosing budget is
+ * restored rather than reset.
+ */ export function registerWorkflowFunctions(environment) {
+    const budget = {
+        remainingRangeElements: MAX_RANGE_ELEMENTS,
+        remainingRangeFanoutBytes: MAX_RANGE_FANOUT_BYTES,
+        remainingJsonOutputBytes: MAX_JSON_OUTPUT_BYTES,
+        context: undefined,
+        contextBytes: undefined
+    };
+    for (const definition of workflowFunctionRegistry){
+        environment.registerFunction(definition.signature, definition.createHandler(budget));
+    }
+    return {
+        isolate (context, evaluation) {
+            const enclosing = {
+                rangeElements: budget.remainingRangeElements,
+                rangeFanoutBytes: budget.remainingRangeFanoutBytes,
+                jsonOutputBytes: budget.remainingJsonOutputBytes,
+                context: budget.context,
+                contextBytes: budget.contextBytes
+            };
+            budget.remainingRangeElements = MAX_RANGE_ELEMENTS;
+            budget.remainingRangeFanoutBytes = MAX_RANGE_FANOUT_BYTES;
+            budget.remainingJsonOutputBytes = MAX_JSON_OUTPUT_BYTES;
+            budget.context = context;
+            budget.contextBytes = undefined;
+            try {
+                return evaluation();
+            } finally{
+                budget.remainingRangeElements = enclosing.rangeElements;
+                budget.remainingRangeFanoutBytes = enclosing.rangeFanoutBytes;
+                budget.remainingJsonOutputBytes = enclosing.jsonOutputBytes;
+                budget.context = enclosing.context;
+                budget.contextBytes = enclosing.contextBytes;
+            }
+        }
+    };
+}
+function materializeRange(start, stop, step) {
+    const values = [];
+    for(let value = start; value <= stop; value += step)values.push(value);
+    return values;
+}
+function rangeElementCount(start, stop, step) {
+    if (step <= 0n) throw new RangeError('range step must be positive');
+    if (start > stop) return 0n;
+    return (stop - start) / step + 1n;
+}
+function toCelInteger(value, name) {
+    if (typeof value === 'bigint') return value;
+    if (typeof value === 'number' && Number.isSafeInteger(value)) return BigInt(value);
+    throw new RangeError(`${name} must be a safe integer`);
+}
+function evaluateRange(budget, start, stop, step) {
+    const startValue = toCelInteger(start, 'range start');
+    const stopValue = toCelInteger(stop, 'range stop');
+    const stepValue = toCelInteger(step, 'range step');
+    const count = rangeElementCount(startValue, stopValue, stepValue);
+    if (count > BigInt(budget.remainingRangeElements)) {
+        throw new RangeError(`range evaluation budget exceeded; ${count} elements requested with ${budget.remainingRangeElements} remaining`);
+    }
+    const contextBytes = getContextBytes(budget);
+    const fanoutBytes = count * BigInt(contextBytes);
+    if (fanoutBytes > BigInt(budget.remainingRangeFanoutBytes)) {
+        throw new RangeError(`range fan-out budget exceeded; ${count} elements requested for ${contextBytes} context bytes with ${budget.remainingRangeFanoutBytes} remaining`);
+    }
+    const values = materializeRange(startValue, stopValue, stepValue);
+    budget.remainingRangeElements -= values.length;
+    budget.remainingRangeFanoutBytes -= Number(fanoutBytes);
+    return values;
+}
+function getContextBytes(budget) {
+    if (budget.contextBytes !== undefined) return budget.contextBytes;
+    try {
+        const json = JSON.stringify(budget.context, stringifyBigint);
+        if (json === undefined) {
+            budget.contextBytes = 0;
+            return 0;
+        }
+        budget.contextBytes = Math.min(MAX_RANGE_FANOUT_BYTES + 1, utf8Encoder.encode(json).byteLength);
+        return budget.contextBytes;
+    } catch  {
+        // A context that cannot be serialized is not safe to fan out over.
+        budget.contextBytes = MAX_RANGE_FANOUT_BYTES + 1;
+        return budget.contextBytes;
+    }
+}
+function serializeJson(budget, value) {
+    const json = JSON.stringify(value, stringifyBigint);
+    if (json === undefined) throw new TypeError('toJson() value must be JSON-serializable');
+    const outputBytes = utf8Encoder.encode(json).byteLength;
+    if (outputBytes > budget.remainingJsonOutputBytes) {
+        throw new RangeError(`toJson evaluation budget exceeded; ${outputBytes} bytes requested with ${budget.remainingJsonOutputBytes} remaining`);
+    }
+    budget.remainingJsonOutputBytes -= outputBytes;
+    return json;
+}
+function reviveJsonNumber(_key, value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) ? BigInt(value) : value;
+}
+
+//# sourceMappingURL=workflow-function-registry.js.map

package/dist/workflow-function-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workflow-function-registry.ts"],"sourcesContent":["import type {Environment, RegisteredFunctionHandler} from '@marcbachmann/cel-js';\nimport {stringifyBigint} from './json.js';\n\n/** Maximum number of values one evaluation's range calls may materialize. */\nexport const MAX_RANGE_ELEMENTS = 1_000;\n\n/** Maximum context-byte fan-out one evaluation's range calls may represent. */\nexport const MAX_RANGE_FANOUT_BYTES = 1_000_000;\n\n/** Maximum UTF-8 bytes returned by toJson() calls in one evaluation. */\nexport const MAX_JSON_OUTPUT_BYTES = 1_000_000;\n\nconst utf8Encoder = new TextEncoder();\n\nconst RANGE_FUNCTION_SIGNATURE = 'range(dyn, dyn, dyn): list<int>';\nconst TO_JSON_FUNCTION_SIGNATURE = 'toJson(dyn): string';\nconst FROM_JSON_FUNCTION_SIGNATURE = 'fromJson(string): dyn';\n\ninterface WorkflowFunctionBudget {\n  remainingRangeElements: number;\n  remainingRangeFanoutBytes: number;\n  remainingJsonOutputBytes: number;\n  context: unknown;\n  contextBytes: number | undefined;\n}\n\n/** Per-evaluation budgets held by the handlers registered on an environment. */\nexport interface WorkflowFunctionBudgets {\n  isolate<T>(context: unknown, evaluation: () => T): T;\n}\n\ninterface WorkflowFunctionDefinition {\n  readonly signature: string;\n  readonly createHandler: (budget: WorkflowFunctionBudget) => RegisteredFunctionHandler;\n}\n\nconst workflowFunctionRegistry = [\n  {\n    signature: RANGE_FUNCTION_SIGNATURE,\n    createHandler:\n      (budget: WorkflowFunctionBudget): RegisteredFunctionHandler =>\n      (start: unknown, stop: unknown, step: unknown) =>\n        evaluateRange(budget, start, stop, step),\n  },\n  {\n    signature: TO_JSON_FUNCTION_SIGNATURE,\n    createHandler:\n      (budget: WorkflowFunctionBudget): RegisteredFunctionHandler =>\n      (value: unknown) =>\n        serializeJson(budget, value),\n  },\n  {\n    signature: FROM_JSON_FUNCTION_SIGNATURE,\n    createHandler: (): RegisteredFunctionHandler => (value: unknown) => {\n      if (typeof value !== 'string') throw new TypeError('fromJson() expects a JSON string');\n      return JSON.parse(value, reviveJsonNumber) as unknown;\n    },\n  },\n] satisfies readonly WorkflowFunctionDefinition[];\n\n/**\n * Register the shared functions and return the budgets their handlers close over.\n *\n * Callers that reuse one environment across evaluations must wrap each evaluation\n * in `isolate` so it gets a full budget without consuming an enclosing one. A\n * context accessor can re-enter the evaluator, so the enclosing budget is\n * restored rather than reset.\n */\nexport function registerWorkflowFunctions(environment: Environment): WorkflowFunctionBudgets {\n  const budget: WorkflowFunctionBudget = {\n    remainingRangeElements: MAX_RANGE_ELEMENTS,\n    remainingRangeFanoutBytes: MAX_RANGE_FANOUT_BYTES,\n    remainingJsonOutputBytes: MAX_JSON_OUTPUT_BYTES,\n    context: undefined,\n    contextBytes: undefined,\n  };\n  for (const definition of workflowFunctionRegistry) {\n    environment.registerFunction(definition.signature, definition.createHandler(budget));\n  }\n\n  return {\n    isolate<T>(context: unknown, evaluation: () => T): T {\n      const enclosing = {\n        rangeElements: budget.remainingRangeElements,\n        rangeFanoutBytes: budget.remainingRangeFanoutBytes,\n        jsonOutputBytes: budget.remainingJsonOutputBytes,\n        context: budget.context,\n        contextBytes: budget.contextBytes,\n      };\n      budget.remainingRangeElements = MAX_RANGE_ELEMENTS;\n      budget.remainingRangeFanoutBytes = MAX_RANGE_FANOUT_BYTES;\n      budget.remainingJsonOutputBytes = MAX_JSON_OUTPUT_BYTES;\n      budget.context = context;\n      budget.contextBytes = undefined;\n      try {\n        return evaluation();\n      } finally {\n        budget.remainingRangeElements = enclosing.rangeElements;\n        budget.remainingRangeFanoutBytes = enclosing.rangeFanoutBytes;\n        budget.remainingJsonOutputBytes = enclosing.jsonOutputBytes;\n        budget.context = enclosing.context;\n        budget.contextBytes = enclosing.contextBytes;\n      }\n    },\n  };\n}\n\nfunction materializeRange(start: bigint, stop: bigint, step: bigint): bigint[] {\n  const values: bigint[] = [];\n  for (let value = start; value <= stop; value += step) values.push(value);\n  return values;\n}\n\nfunction rangeElementCount(start: bigint, stop: bigint, step: bigint): bigint {\n  if (step <= 0n) throw new RangeError('range step must be positive');\n  if (start > stop) return 0n;\n\n  return (stop - start) / step + 1n;\n}\n\nfunction toCelInteger(value: unknown, name: string): bigint {\n  if (typeof value === 'bigint') return value;\n  if (typeof value === 'number' && Number.isSafeInteger(value)) return BigInt(value);\n  throw new RangeError(`${name} must be a safe integer`);\n}\n\nfunction evaluateRange(\n  budget: WorkflowFunctionBudget,\n  start: unknown,\n  stop: unknown,\n  step: unknown,\n): bigint[] {\n  const startValue = toCelInteger(start, 'range start');\n  const stopValue = toCelInteger(stop, 'range stop');\n  const stepValue = toCelInteger(step, 'range step');\n  const count = rangeElementCount(startValue, stopValue, stepValue);\n  if (count > BigInt(budget.remainingRangeElements)) {\n    throw new RangeError(\n      `range evaluation budget exceeded; ${count} elements requested with ${budget.remainingRangeElements} remaining`,\n    );\n  }\n\n  const contextBytes = getContextBytes(budget);\n  const fanoutBytes = count * BigInt(contextBytes);\n  if (fanoutBytes > BigInt(budget.remainingRangeFanoutBytes)) {\n    throw new RangeError(\n      `range fan-out budget exceeded; ${count} elements requested for ${contextBytes} context bytes with ${budget.remainingRangeFanoutBytes} remaining`,\n    );\n  }\n\n  const values = materializeRange(startValue, stopValue, stepValue);\n  budget.remainingRangeElements -= values.length;\n  budget.remainingRangeFanoutBytes -= Number(fanoutBytes);\n  return values;\n}\n\nfunction getContextBytes(budget: WorkflowFunctionBudget): number {\n  if (budget.contextBytes !== undefined) return budget.contextBytes;\n\n  try {\n    const json = JSON.stringify(budget.context, stringifyBigint);\n    if (json === undefined) {\n      budget.contextBytes = 0;\n      return 0;\n    }\n\n    budget.contextBytes = Math.min(MAX_RANGE_FANOUT_BYTES + 1, utf8Encoder.encode(json).byteLength);\n    return budget.contextBytes;\n  } catch {\n    // A context that cannot be serialized is not safe to fan out over.\n    budget.contextBytes = MAX_RANGE_FANOUT_BYTES + 1;\n    return budget.contextBytes;\n  }\n}\n\nfunction serializeJson(budget: WorkflowFunctionBudget, value: unknown): string {\n  const json = JSON.stringify(value, stringifyBigint);\n  if (json === undefined) throw new TypeError('toJson() value must be JSON-serializable');\n\n  const outputBytes = utf8Encoder.encode(json).byteLength;\n  if (outputBytes > budget.remainingJsonOutputBytes) {\n    throw new RangeError(\n      `toJson evaluation budget exceeded; ${outputBytes} bytes requested with ${budget.remainingJsonOutputBytes} remaining`,\n    );\n  }\n\n  budget.remainingJsonOutputBytes -= outputBytes;\n  return json;\n}\n\nfunction reviveJsonNumber(_key: string, value: unknown): unknown {\n  return typeof value === 'number' && Number.isSafeInteger(value) ? BigInt(value) : value;\n}\n"],"names":["stringifyBigint","MAX_RANGE_ELEMENTS","MAX_RANGE_FANOUT_BYTES","MAX_JSON_OUTPUT_BYTES","utf8Encoder","TextEncoder","RANGE_FUNCTION_SIGNATURE","TO_JSON_FUNCTION_SIGNATURE","FROM_JSON_FUNCTION_SIGNATURE","workflowFunctionRegistry","signature","createHandler","budget","start","stop","step","evaluateRange","value","serializeJson","TypeError","JSON","parse","reviveJsonNumber","registerWorkflowFunctions","environment","remainingRangeElements","remainingRangeFanoutBytes","remainingJsonOutputBytes","context","undefined","contextBytes","definition","registerFunction","isolate","evaluation","enclosing","rangeElements","rangeFanoutBytes","jsonOutputBytes","materializeRange","values","push","rangeElementCount","RangeError","toCelInteger","name","Number","isSafeInteger","BigInt","startValue","stopValue","stepValue","count","getContextBytes","fanoutBytes","length","json","stringify","Math","min","encode","byteLength","outputBytes","_key"],"mappings":"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"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shipfox/expression",
   "license": "MIT",
   "private": false,
-  "version": "2.0.0",
+  "version": "2.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,7 +23,7 @@
   "dependencies": {
     "@marcbachmann/cel-js": "7.6.1",
     "ajv": "^8.20.0",
-    "@shipfox/workflow-document": "3.0.0"
+    "@shipfox/workflow-document": "3.0.1"
   },
   "shipfox": {
     "architecture": {