@n8n/expression-runtime 0.14.2 → 0.16.0

package/dist/cjs/bridge/bridge-messages.js

@@ -0,0 +1,263 @@
+/**
+ * Schemas for messages the in-isolate runtime sends to the host via the
+ * `callHost` typed-RPC dispatcher.
+ *
+ * The isolate is an untrusted source: anything that crosses the bridge must
+ * be validated for shape and types at the boundary. We do that with zod
+ * rather than relying on TypeScript discriminated unions, because TS types
+ * are erased at runtime and contribute zero security.
+ *
+ * Each operation has its own schema. The dispatcher entry validates the
+ * envelope against the discriminated union, throws on any deviation
+ * (unknown `type`, missing/typo'd fields, wrong field types), and then
+ * delegates to a handler that operates on the parsed (statically narrowed)
+ * message.
+ *
+ * Each additional typed RPC lands as a new schema here plus a new `case`
+ * in the bridge's dispatcher switch.
+ */
+(function (factory) {
+    if (typeof module === "object" && typeof module.exports === "object") {
+        var v = factory(require, exports);
+        if (v !== undefined) module.exports = v;
+    }
+    else if (typeof define === "function" && define.amd) {
+        define(["require", "exports", "zod"], factory);
+    }
+})(function (require, exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.bridgeMessageSchema = exports.getPairedItemMessage = exports.evaluateExpressionMessage = exports.getNodeItemMessage = exports.getNodeItemMatchingMessage = exports.getNodePairedItemMessage = exports.fromAiMessage = exports.getItemsMessage = exports.getInputAllMessage = exports.getInputLastMessage = exports.getInputFirstMessage = exports.getNodeAllMessage = exports.getNodeLastMessage = exports.getNodeFirstMessage = void 0;
+    const zod_1 = require("zod");
+    /**
+     * `$('NodeName').first(branchIndex?, runIndex?)` — fetch the first item of
+     * a named node's most recent execution data.
+     */
+    exports.getNodeFirstMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getNodeFirst'),
+        nodeName: zod_1.z.string(),
+        branchIndex: zod_1.z.number().int().nonnegative().optional(),
+        runIndex: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    /**
+     * `$('NodeName').last(branchIndex?, runIndex?)` — fetch the last item of
+     * a named node's most recent execution data.
+     */
+    exports.getNodeLastMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getNodeLast'),
+        nodeName: zod_1.z.string(),
+        branchIndex: zod_1.z.number().int().nonnegative().optional(),
+        runIndex: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    /**
+     * `$('NodeName').all(branchIndex?, runIndex?)` — fetch every item of a
+     * named node's most recent execution data as an array.
+     */
+    exports.getNodeAllMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getNodeAll'),
+        nodeName: zod_1.z.string(),
+        branchIndex: zod_1.z.number().int().nonnegative().optional(),
+        runIndex: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    /**
+     * `$input.first()` — fetch the first item of the current node's input.
+     * Host enforces zero arguments; the schema has no fields besides `type`.
+     */
+    exports.getInputFirstMessage = zod_1.z.object({ type: zod_1.z.literal('getInputFirst') }).strict();
+    /**
+     * `$input.last()` — fetch the last item of the current node's input.
+     */
+    exports.getInputLastMessage = zod_1.z.object({ type: zod_1.z.literal('getInputLast') }).strict();
+    /**
+     * `$input.all()` — fetch every item of the current node's input.
+     */
+    exports.getInputAllMessage = zod_1.z.object({ type: zod_1.z.literal('getInputAll') }).strict();
+    /**
+     * `$items(nodeName?, outputIndex?, runIndex?)` — fetch the execution data of
+     * a node by name (or the current node's input if `nodeName` is omitted).
+     *
+     * `runIndex` accepts negative values: the host uses `-1` as a sentinel for
+     * "latest run" (see `WorkflowDataProxy.$items` —
+     * `runIndex === undefined ? -1 : runIndex`). The schema uses
+     * `z.number().int()` without `.nonnegative()` so expressions can pass `-1`
+     * explicitly if they need to.
+     */
+    exports.getItemsMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getItems'),
+        nodeName: zod_1.z.string().optional(),
+        outputIndex: zod_1.z.number().int().nonnegative().optional(),
+        runIndex: zod_1.z.number().int().optional(),
+    })
+        .strict();
+    /**
+     * `$fromAI(name, description?, type?, defaultValue?)` — the AI-builder
+     * placeholder accessor (aliases: `$fromAi`, `$fromai`).
+     *
+     * Two deliberate looseness points in this schema, both to preserve host
+     * contract / parity:
+     *
+     * 1. `name` is `z.string().optional()` (not required) so a call missing
+     *    the argument or passing an empty string reaches the host, which
+     *    throws the user-friendly `ExpressionError("Add a key, e.g. $fromAI('placeholder_name')")`.
+     *    Requiring it here would replace that error with a generic zod
+     *    message. The host also validates the regex `[a-zA-Z0-9_-]{0,64}`;
+     *    we don't pre-empt that either.
+     * 2. `defaultValue` is `z.unknown()` because the host accepts any value
+     *    as the fallback return (`handleFromAi` returns it directly via
+     *    `??`). Structured-clone at the bridge boundary still prevents
+     *    functions and other non-cloneable values from crossing.
+     *
+     * `description` and `type` are forwarded even though the host currently
+     * ignores them (`_description`, `_type`), so the protocol matches the
+     * documented call signature.
+     */
+    exports.fromAiMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('fromAi'),
+        name: zod_1.z.string().optional(),
+        description: zod_1.z.string().optional(),
+        valueType: zod_1.z.string().optional(),
+        // `z.unknown()` already accepts `undefined`, so no `.optional()` needed.
+        defaultValue: zod_1.z.unknown(),
+    })
+        .strict();
+    /**
+     * `$('NodeName').pairedItem(itemIndex?)` / `.itemMatching(itemIndex)` /
+     * `.item` — resolve the paired item for a referenced node.
+     *
+     * All three host-side surface forms share one internal resolver
+     * (`pairedItemMethod` in `WorkflowDataProxy`), but the resolver closes
+     * over the literal property name the bridge accessed on the host proxy
+     * — so the error message and getter-vs-method form depend on *which*
+     * property the bridge reads. Three separate discriminators, each
+     * mapping a handler to a fixed literal property name, are the only way
+     * to preserve the host's friendly errors (e.g. "Missing item index for
+     * .itemMatching()") and the `.item` getter semantics without
+     * duplicating logic in-isolate.
+     *
+     * `itemIndex` is optional on all three at the schema level; the host
+     * throws the appropriate `ExpressionError` when it's missing for
+     * `.itemMatching()`, and applies the current-itemIndex default for
+     * `.pairedItem` and `.item`.
+     */
+    exports.getNodePairedItemMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getNodePairedItem'),
+        nodeName: zod_1.z.string(),
+        itemIndex: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    /**
+     * `itemIndex` is `.optional()` even though `.itemMatching()` requires it
+     * at the host. The host's `pairedItemMethod` closure throws the friendly
+     * `"Missing item index for .itemMatching()"` error when the field is
+     * absent — keeping the schema permissive lets that host error surface
+     * verbatim instead of being replaced by a generic zod parse failure.
+     */
+    exports.getNodeItemMatchingMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getNodeItemMatching'),
+        nodeName: zod_1.z.string(),
+        itemIndex: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    exports.getNodeItemMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getNodeItem'),
+        nodeName: zod_1.z.string(),
+    })
+        .strict();
+    /**
+     * `$evaluateExpression(expression, itemIndex?)` — evaluate a nested
+     * expression string at runtime against the same execution context.
+     *
+     * The host recursively invokes the expression engine on the `expression`
+     * string — under the VM engine this re-enters the bridge with a fresh
+     * evaluation. `itemIndex` is optional and defaults to the current item;
+     * the schema mirrors the existing "nonnegative int" constraint used by
+     * the node-data RPCs.
+     */
+    exports.evaluateExpressionMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('evaluateExpression'),
+        expression: zod_1.z.string(),
+        itemIndex: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    /**
+     * `ISourceData` — the source record that accompanies a paired-item
+     * traversal step. Mirrors the host interface used by
+     * `WorkflowDataProxy.getPairedItem`.
+     */
+    const sourceDataSchema = zod_1.z
+        .object({
+        previousNode: zod_1.z.string(),
+        previousNodeOutput: zod_1.z.number().int().nonnegative().optional(),
+        previousNodeRun: zod_1.z.number().int().nonnegative().optional(),
+    })
+        .strict();
+    /**
+     * `IPairedItemData` — one paired-item record. `sourceOverwrite` lets a
+     * node override the upstream source while the helper walks the ancestry
+     * chain; the field is optional and recurses through the same schema.
+     */
+    const pairedItemDataSchema = zod_1.z
+        .object({
+        item: zod_1.z.number().int().nonnegative(),
+        input: zod_1.z.number().int().nonnegative().optional(),
+        sourceOverwrite: sourceDataSchema.optional(),
+    })
+        .strict();
+    /**
+     * `$getPairedItem(destinationNodeName, incomingSourceData, initialPairedItem)` —
+     * traverse the paired-item ancestry chain back to the named upstream node
+     * and return the matching execution item.
+     *
+     * Two host-side fields are deliberately omitted from the schema:
+     * - `usedMethodName` defaults to `$getPairedItem` on the host; the isolate
+     *   has no reason to spoof a different method name in the error path.
+     * - `nodeBeforeLast` is an internal recursion argument; only the host
+     *   itself sets it during the recursive walk.
+     *
+     * `incomingSourceData` is nullable because the host's signature accepts
+     * `ISourceData | null` (and throws a paired-item-not-found error when null).
+     */
+    exports.getPairedItemMessage = zod_1.z
+        .object({
+        type: zod_1.z.literal('getPairedItem'),
+        destinationNodeName: zod_1.z.string(),
+        incomingSourceData: sourceDataSchema.nullable(),
+        initialPairedItem: pairedItemDataSchema,
+    })
+        .strict();
+    /**
+     * The full set of messages the bridge will accept. Discriminator is `type`.
+     *
+     * Use `.strict()` on each member so unknown fields are rejected rather than
+     * silently ignored — this catches typos in the runtime stubs and keeps the
+     * protocol surface tight.
+     */
+    exports.bridgeMessageSchema = zod_1.z.discriminatedUnion('type', [
+        exports.getNodeFirstMessage,
+        exports.getNodeLastMessage,
+        exports.getNodeAllMessage,
+        exports.getInputFirstMessage,
+        exports.getInputLastMessage,
+        exports.getInputAllMessage,
+        exports.getItemsMessage,
+        exports.fromAiMessage,
+        exports.getNodePairedItemMessage,
+        exports.getNodeItemMatchingMessage,
+        exports.getNodeItemMessage,
+        exports.evaluateExpressionMessage,
+        exports.getPairedItemMessage,
+    ]);
+});
+//# sourceMappingURL=bridge-messages.js.map

package/dist/cjs/bridge/bridge-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-messages.js","sourceRoot":"","sources":["../../../src/bridge/bridge-messages.ts"],"names":[],"mappings":"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"}

package/dist/cjs/bridge/isolated-vm-bridge.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeBridge, BridgeConfig, ExecuteOptions } from '../types';
+import type { RuntimeBridge, BridgeConfig, ExecuteOptions, WorkflowData } from '../types';
 /**
  * IsolatedVmBridge - Runtime bridge using isolated-vm for secure expression evaluation.
  *
@@ -81,7 +81,13 @@ export declare class IsolatedVmBridge implements RuntimeBridge {
      * Create an ivm.Reference callback for getting value/metadata at a path.
      *
      * Used by createDeepLazyProxy when accessing properties. Returns metadata
-     * markers for functions, arrays, and objects, or the primitive value directly.
+     * markers for arrays and objects, or the primitive value directly.
+     *
+     * Function-typed values are returned as `undefined` — every callable on
+     * the host data surface (`$('Foo').first()`, `$items()`, `$fromAI()`,
+     * `$evaluateExpression()`, `$getPairedItem()`) is wired in-isolate via
+     * the typed-RPC dispatcher (`callHost`). No expression form should
+     * reach a function through this path.
      *
      * @param data - Current workflow data to use for callback responses
      * @private
@@ -97,23 +103,140 @@ export declare class IsolatedVmBridge implements RuntimeBridge {
      */
     private createGetArrayElementRef;
     /**
-     * Create an ivm.Reference callback for calling functions at a path.
+     * Create the single typed-RPC dispatcher.
      *
-     * Used when expressions invoke functions from workflow data.
+     * The isolate sends one envelope per typed RPC invocation:
+     *   `callHost({ type: 'getNodeFirst', nodeName, branchIndex?, runIndex? })`
+     *
+     * Inputs cross a trust boundary, so the dispatcher parses every envelope
+     * with the host-side zod schema (`bridgeMessageSchema`) before any
+     * dispatch happens. Anything that deviates from the declared shape —
+     * unknown `type`, missing required fields, extra unexpected fields,
+     * wrong field types — fails the parse and an error sentinel is returned
+     * to the caller.
+     *
+     * After parsing, `switch (msg.type)` dispatches to a private handler with
+     * a fully narrowed message type. The operation set is exactly the cases
+     * in this switch; the `type` field selects a static branch in source,
+     * not a property lookup on a runtime object.
+     *
+     * @param data - Current workflow data
+     * @private
+     */
+    private createCallHostRef;
+    /**
+     * Handlers for the `$('Foo').{first,last,all}` typed RPCs.
+     *
+     * Each handler reads a fixed literal property name off the host-side node
+     * proxy — the isolate cannot influence which property is dereferenced.
+     * Eliminating `data.$` as a host-callable entirely would require reaching
+     * the `WorkflowDataProxy` internals (e.g. `getNodeExecutionOrPinnedData`)
+     * rather than the public `$()` API; that's a follow-up.
+     *
+     * `data.$` is a host-wired function (`WorkflowDataProxy`'s `$`). If it
+     * ever isn't, optional chaining short-circuits to `undefined` — the same
+     * observable result the runtime's `E()` handler produces from any thrown
+     * error here.
+     *
+     * @private
+     */
+    private handleGetNodeFirst;
+    private handleGetNodeLast;
+    private handleGetNodeAll;
+    /**
+     * Handlers for the `$input.{first,last,all}` typed RPCs.
+     *
+     * Each reads a fixed literal property name off `data.$input` (the host's
+     * `WorkflowDataProxy` input proxy). The host enforces zero arguments on
+     * these methods — the schemas have no fields besides `type`, so the
+     * isolate cannot pass anything that would trigger the "should have no
+     * arguments" error path on the host side.
+     *
+     * @private
+     */
+    private handleGetInputFirst;
+    private handleGetInputLast;
+    private handleGetInputAll;
+    /**
+     * Handler for `$items(nodeName?, outputIndex?, runIndex?)` — the
+     * global accessor for a node's execution data. Reads the literal
+     * `$items` property off `data` (host-wired by `WorkflowDataProxy`)
+     * and forwards the validated args verbatim. The host applies its own
+     * defaults when fields are `undefined`.
+     *
+     * @private
+     */
+    private handleGetItems;
+    /**
+     * Handler for `$fromAI(name, description?, type?, defaultValue?)` and its
+     * `$fromAi` / `$fromai` aliases. Reads the literal `$fromAI` property
+     * off `data` (host-wired) and forwards the args. The host validates
+     * `name` (required + regex) and applies its own resolution / fallback
+     * logic, so empty / invalid names surface as the host's structured
+     * `ExpressionError` rather than a generic zod parse error.
+     *
+     * Note: `msg.valueType` maps to the host's third positional parameter
+     * (`_type` in `WorkflowDataProxy.handleFromAi`). The bridge protocol
+     * renames it to avoid collision with the `type` discriminator on the
+     * envelope — the host parameter currently goes unused, but if it ever
+     * gains a name (`type`), this mapping should stay explicit.
+     *
+     * @private
+     */
+    private handleFromAi;
+    /**
+     * Handlers for the `$('Foo').pairedItem(itemIndex?)` / `.itemMatching(...)` /
+     * `.item` cluster. Three separate typed RPCs, each reading exactly one
+     * literal property off the host node proxy.
+     *
+     * The split is load-bearing: the host's `pairedItemMethod` closure
+     * captures which property name the proxy `get` trap saw, and uses
+     * that to pick the right error message (e.g. "Missing item index for
+     * .itemMatching()") and to decide between method-call vs getter
+     * semantics for `.item`. Reading the matching property here lets
+     * those host-side branches fire exactly as they do in the legacy
+     * engine; no in-isolate validation needed.
+     *
+     * @private
+     */
+    private handleGetNodePairedItem;
+    private handleGetNodeItemMatching;
+    private handleGetNodeItem;
+    /**
+     * Handler for `$evaluateExpression(expression, itemIndex?)`. Forwards
+     * the string to the host's nested-evaluation helper, which re-enters
+     * the expression engine on the inner expression. Under the VM engine
+     * this round-trips through the bridge again on a fresh evaluation
+     * cycle, which is the same shape the legacy engine supports.
+     *
+     * @private
+     */
+    private handleEvaluateExpression;
+    /**
+     * Handler for `$getPairedItem(destinationNodeName, incomingSourceData,
+     * initialPairedItem)`. Forwards directly to the host binding, which
+     * walks the paired-item ancestry chain back to the named upstream node
+     * and returns the matching execution item.
+     *
+     * The two trailing host parameters — `usedMethodName` and
+     * `nodeBeforeLast` — are deliberately not part of the wire protocol:
+     * the host's default for `usedMethodName` is already `$getPairedItem`,
+     * and `nodeBeforeLast` is an internal recursion argument the host sets
+     * during traversal.
      *
-     * @param data - Current workflow data to use for callback responses
      * @private
      */
-    private createCallFunctionAtPathRef;
+    private handleGetPairedItem;
     /**
      * Execute JavaScript code in the isolated context.
      *
      * Flow:
-     * 1. Create three ivm.Reference callbacks scoped to the current data
-     * 2. Use evalClosureSync to run the code in a closure where $0/$1/$2
-     *    are the callback references — no global mutable state
+     * 1. Create three ivm.Reference callbacks scoped to the current data:
+     *    `getValueAtPath`, `getArrayElement`, `callHost`.
+     * 2. Use evalClosureSync to run the code in a closure where `$0`/`$1`/`$2`
+     *    are the callback references — no global mutable state.
      * 3. buildContext() inside the isolate creates a fresh evaluation context
-     *    from the closure-scoped references
+     *    from the closure-scoped references.
      *
      * Each call gets its own closure, so nested and concurrent evaluations
      * cannot interfere with each other.
@@ -123,7 +246,7 @@ export declare class IsolatedVmBridge implements RuntimeBridge {
      * @returns Result of the expression
      * @throws {Error} If bridge not initialized or execution fails
      */
-    execute(code: string, data: Record<string, unknown>, options?: ExecuteOptions): unknown;
+    execute(code: string, data: WorkflowData, options?: ExecuteOptions): unknown;
     /**
      * Reconstruct an error from serialized isolate data.
      *

package/dist/cjs/bridge/isolated-vm-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isolated-vm-bridge.d.ts","sourceRoot":"","sources":["../../../src/bridge/isolated-vm-bridge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA0E5E;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,MAAM,CAAmC;gBAErC,MAAM,GAAE,YAAiB;IAYrC;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC;;;;;;;;;;;OAWG;YACW,mBAAmB;IAgCjC;;;;;;;;OAQG;YACW,iBAAiB;IA4B/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,kBAAkB;IAwBhC;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IAgE/B;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAyDhC;;;;;;;OAOG;IACH,OAAO,CAAC,2BAA2B;IAkCnC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO;IAsFvF;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;;;OAIG;IACH,UAAU,IAAI,OAAO;CAGrB"}
+{"version":3,"file":"isolated-vm-bridge.d.ts","sourceRoot":"","sources":["../../../src/bridge/isolated-vm-bridge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AA2E1F;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,MAAM,CAAmC;gBAErC,MAAM,GAAE,YAAiB;IAYrC;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC;;;;;;;;;;;OAWG;YACW,mBAAmB;IAgCjC;;;;;;;;OAQG;YACW,iBAAiB;IA4B/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,kBAAkB;IAwBhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,uBAAuB;IA+D/B;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAyDhC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,iBAAiB;IA+CzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,gBAAgB;IAOxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAOtB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,yBAAyB;IAOjC,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO;IA6F5E;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;;;OAIG;IACH,UAAU,IAAI,OAAO;CAGrB"}