wasm-cel 0.1.0

package/README.md

@@ -0,0 +1,324 @@
+# wasm-cel
+
+WebAssembly module for evaluating CEL (Common Expression Language) expressions in Node.js.
+
+## Installation
+
+```bash
+npm install wasm-cel
+# or
+pnpm add wasm-cel
+# or
+yarn add wasm-cel
+```
+
+## Usage
+
+The library follows the CEL pattern: create an environment, compile an expression, and then evaluate it:
+
+```typescript
+import { Env } from "wasm-cel";
+
+// Create an environment with variable declarations
+const env = await Env.new({
+  variables: [
+    { name: "x", type: "double" },
+    { name: "y", type: "double" },
+    { name: "name", type: "string" },
+    { name: "age", type: "double" },
+  ],
+});
+
+// Compile an expression
+const program = await env.compile("x + y");
+
+// Evaluate with variables
+const result = await program.eval({ x: 10, y: 20 });
+console.log(result); // 30
+
+// You can reuse the same program with different variables
+const result2 = await program.eval({ x: 5, y: 15 });
+console.log(result2); // 20
+
+// Compile and evaluate multiple expressions with the same environment
+const program2 = await env.compile(
+  'name + " is " + string(age) + " years old"',
+);
+const result3 = await program2.eval({ name: "Alice", age: 30 });
+console.log(result3); // "Alice is 30 years old"
+```
+
+## API
+
+### `Env.new(options?: EnvOptions): Promise<Env>`
+
+Creates a new CEL environment with variable declarations and optional function definitions.
+
+**Parameters:**
+
+- `options` (EnvOptions, optional): Options including:
+  - `variables` (VariableDeclaration[], optional): Array of variable declarations with name and type
+  - `functions` (CELFunctionDefinition[], optional): Array of custom function definitions
+
+**Returns:**
+
+- `Promise<Env>`: A promise that resolves to a new Env instance
+
+**Example:**
+
+```typescript
+const env = await Env.new({
+  variables: [
+    { name: "x", type: "int" },
+    { name: "y", type: "string" },
+  ],
+});
+```
+
+### `env.compile(expr: string): Promise<Program>`
+
+Compiles a CEL expression in the environment.
+
+**Parameters:**
+
+- `expr` (string): The CEL expression to compile
+
+**Returns:**
+
+- `Promise<Program>`: A promise that resolves to a compiled Program
+
+**Example:**
+
+```typescript
+const program = await env.compile("x + 10");
+```
+
+### `env.typecheck(expr: string): Promise<TypeCheckResult>`
+
+Typechecks a CEL expression in the environment without compiling it. This is useful for validating expressions and getting type information before compilation.
+
+**Parameters:**
+
+- `expr` (string): The CEL expression to typecheck
+
+**Returns:**
+
+- `Promise<TypeCheckResult>`: A promise that resolves to type information with a `type` property containing the inferred type
+
+**Example:**
+
+```typescript
+const env = await Env.new({
+  variables: [
+    { name: "x", type: "int" },
+    { name: "y", type: "int" },
+  ],
+});
+
+// Typecheck a simple expression
+const typeInfo = await env.typecheck("x + y");
+console.log(typeInfo.type); // "int"
+
+// Typecheck a list expression
+const listType = await env.typecheck("[1, 2, 3]");
+console.log(listType.type); // { kind: "list", elementType: "int" }
+
+// Typecheck a map expression
+const mapType = await env.typecheck('{"key": "value"}');
+console.log(mapType.type); // { kind: "map", keyType: "string", valueType: "string" }
+
+// Typechecking will throw an error for invalid expressions
+try {
+  await env.typecheck('x + "invalid"'); // Type mismatch
+} catch (error) {
+  console.error(error.message); // Typecheck error message
+}
+```
+
+### `program.eval(vars?: Record<string, any> | null): Promise<any>`
+
+Evaluates the compiled program with the given variables.
+
+**Parameters:**
+
+- `vars` (Record<string, any> | null, optional): Variables to use in the evaluation. Defaults to `null`.
+
+**Returns:**
+
+- `Promise<any>`: A promise that resolves to the evaluation result
+
+**Example:**
+
+```typescript
+const result = await program.eval({ x: 5 });
+```
+
+### `env.destroy(): void`
+
+Destroys the environment and marks it as destroyed. After calling `destroy()`, you cannot create new programs or typecheck expressions with this environment. However, programs that were already created from this environment will continue to work until they are destroyed themselves.
+
+**Note:** This method is idempotent - calling it multiple times is safe and has no effect after the first call.
+
+**Example:**
+
+```typescript
+const env = await Env.new();
+const program = await env.compile("10 + 20");
+
+// Destroy the environment
+env.destroy();
+
+// This will throw an error
+await expect(env.compile("5 + 5")).rejects.toThrow();
+
+// But existing programs still work
+const result = await program.eval();
+console.log(result); // 30
+```
+
+### `program.destroy(): void`
+
+Destroys the compiled program and frees associated WASM resources. After calling `destroy()`, you cannot evaluate the program anymore.
+
+**Note:** This method is idempotent - calling it multiple times is safe and has no effect after the first call.
+
+**Example:**
+
+```typescript
+const program = await env.compile("10 + 20");
+program.destroy();
+
+// This will throw an error
+await expect(program.eval()).rejects.toThrow();
+```
+
+### `init(): Promise<void>`
+
+Initializes the WASM module. This is called automatically by the API functions, but can be called manually to pre-initialize the module.
+
+## Memory Management
+
+This library implements comprehensive memory leak prevention mechanisms to ensure WASM resources are properly cleaned up.
+
+### Explicit Cleanup
+
+Both `Env` and `Program` instances provide a `destroy()` method for explicit cleanup:
+
+```typescript
+const env = await Env.new();
+const program = await env.compile("x + y");
+
+// When done, explicitly destroy resources
+program.destroy();
+env.destroy();
+```
+
+### Automatic Cleanup with FinalizationRegistry
+
+The library uses JavaScript's `FinalizationRegistry` (available in Node.js 14+) to automatically clean up resources when objects are garbage collected. This provides a **best-effort** safety net in case you forget to call `destroy()`.
+
+**Important limitations:**
+
+- FinalizationRegistry callbacks are not guaranteed to run immediately or at all
+- They may run long after an object is garbage collected, or not at all in some cases
+- The timing is non-deterministic and depends on the JavaScript engine's garbage collector
+
+**Best practice:** Always explicitly call `destroy()` when you're done with an environment or program. Don't rely solely on automatic cleanup.
+
+### Reference Counting for Custom Functions
+
+The library uses reference counting to manage custom JavaScript functions registered with environments:
+
+1. **When a program is created** from an environment, reference counts are incremented for all custom functions in that environment
+2. **When a program is destroyed**, reference counts are decremented
+3. **Functions are only unregistered** when their reference count reaches zero
+
+This means:
+
+- **Programs continue to work** even after their parent environment is destroyed
+- **Functions remain available** as long as any program that might use them still exists
+- **Functions are automatically cleaned up** when all programs using them are destroyed
+
+**Example:**
+
+```typescript
+const add = CELFunction.new("add")
+  .param("a", "int")
+  .param("b", "int")
+  .returns("int")
+  .implement((a, b) => a + b);
+
+const env = await Env.new({ functions: [add] });
+const program = await env.compile("add(10, 20)");
+
+// Destroy the environment - functions are still available
+env.destroy();
+
+// Program still works because functions are reference counted
+const result = await program.eval();
+console.log(result); // 30
+
+// When program is destroyed, functions are cleaned up
+program.destroy();
+```
+
+### Environment Lifecycle
+
+- **Destroyed environments** cannot create new programs or typecheck expressions
+- **Existing programs** from a destroyed environment continue to work
+- **The environment entry** is cleaned up when all programs using it are destroyed
+
+### Best Practices
+
+1. **Always call `destroy()`** when you're done with environments and programs
+2. **Destroy programs before environments** if you want to ensure functions are cleaned up immediately
+3. **Don't rely on automatic cleanup** - it's a safety net, not a guarantee
+4. **In long-running applications**, explicitly manage the lifecycle of resources to prevent memory leaks
+
+## TypeScript Support
+
+This package includes TypeScript type definitions. Import types as needed:
+
+```typescript
+import {
+  Env,
+  Program,
+  EnvOptions,
+  VariableDeclaration,
+  TypeCheckResult,
+} from "wasm-cel";
+```
+
+## Building from Source
+
+To build the package from source, you'll need:
+
+- Go 1.16 or later
+- Node.js 18 or later
+- pnpm (or npm/yarn)
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the WASM module and TypeScript
+pnpm run build:all
+
+# Run tests
+pnpm test
+
+# Run example
+pnpm run example
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Package Type
+
+This is an **ESM-only** package. It uses modern ES modules and NodeNext module resolution. If you're using TypeScript, make sure your `tsconfig.json` has `"module": "NodeNext"` or `"moduleResolution": "NodeNext"` for proper type resolution.
+
+## License
+
+MIT

package/dist/functions.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Type-safe builder for CEL function definitions
+ */
+import type { CELFunctionDefinition, CELFunctionParam, CELTypeDef } from "./types.js";
+/**
+ * Maps CEL types to TypeScript types
+ * Uses a depth counter to limit recursion and avoid "excessively deep" errors
+ */
+type CELTypeToTS<T extends CELTypeDef, Depth extends readonly unknown[] = []> = Depth["length"] extends 5 ? any : T extends "bool" ? boolean : T extends "int" | "uint" | "double" ? number : T extends "string" ? string : T extends "bytes" ? string : T extends {
+    kind: "list";
+    elementType: infer E;
+} ? E extends CELTypeDef ? Array<CELTypeToTS<E, [...Depth, unknown]>> : never : T extends {
+    kind: "map";
+    keyType: infer K;
+    valueType: infer V;
+} ? V extends CELTypeDef ? Record<string, CELTypeToTS<V, [...Depth, unknown]>> : never : T extends "dyn" ? any : T extends "null" ? null : T extends "timestamp" ? Date : T extends "duration" ? string : never;
+/**
+ * Extracts TypeScript parameter types from a tuple of CEL function parameters
+ */
+type ExtractParamTypes<P extends readonly CELFunctionParam[]> = {
+    [K in keyof P]: P[K] extends CELFunctionParam ? CELTypeToTS<P[K]["type"]> : never;
+};
+/**
+ * Builder class for creating type-safe CEL function definitions
+ *
+ * @example
+ * ```typescript
+ * const add = CELFunction.new("add")
+ *   .param("a", "int")
+ *   .param("b", "int")
+ *   .returns("int")
+ *   .implement((a, b) => a + b);
+ * ```
+ */
+export declare class CELFunction<Params extends readonly CELFunctionParam[] = readonly [], ReturnType extends CELTypeDef = "dyn"> {
+    private name;
+    private readonly params;
+    private returnType;
+    private overloads;
+    private constructor();
+    /**
+     * Create a new CEL function builder
+     * @param name - The name of the function
+     * @returns A builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const add = CELFunction.new("add")
+     *   .param("a", "int")
+     *   .param("b", "int")
+     *   .returns("int")
+     *   .implement((a, b) => a + b);
+     * ```
+     */
+    static new(name: string): CELFunction<readonly [], "dyn">;
+    /**
+     * Add a parameter to the function
+     */
+    param<T extends CELTypeDef>(name: string, type: T, optional?: boolean): CELFunction<[
+        ...Params,
+        {
+            name: string;
+            type: T;
+            optional: boolean;
+        }
+    ], ReturnType>;
+    /**
+     * Set the return type of the function
+     */
+    returns<T extends CELTypeDef>(type: T): CELFunction<Params, T>;
+    /**
+     * Set the implementation function and return the final definition
+     */
+    implement(impl: (...args: ExtractParamTypes<Params>) => CELTypeToTS<ReturnType>): CELFunctionDefinition;
+    /**
+     * Add an overload variant of this function
+     */
+    overload(overload: CELFunctionDefinition): this;
+}
+/**
+ * Helper function to create a list type
+ */
+export declare function listType(elementType: CELTypeDef): {
+    kind: "list";
+    elementType: CELTypeDef;
+};
+/**
+ * Helper function to create a map type
+ */
+export declare function mapType(keyType: CELTypeDef, valueType: CELTypeDef): {
+    kind: "map";
+    keyType: CELTypeDef;
+    valueType: CELTypeDef;
+};
+export {};
+//# sourceMappingURL=functions.d.ts.map

package/dist/functions.d.ts.map

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

package/dist/functions.js

@@ -0,0 +1,97 @@
+/**
+ * Type-safe builder for CEL function definitions
+ */
+/**
+ * Builder class for creating type-safe CEL function definitions
+ *
+ * @example
+ * ```typescript
+ * const add = CELFunction.new("add")
+ *   .param("a", "int")
+ *   .param("b", "int")
+ *   .returns("int")
+ *   .implement((a, b) => a + b);
+ * ```
+ */
+export class CELFunction {
+    constructor(name, params = [], returnType = "dyn") {
+        this.overloads = [];
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+            throw new Error(`Invalid function name: ${name}. Must be a valid CEL identifier.`);
+        }
+        this.name = name;
+        this.params = params;
+        this.returnType = returnType;
+    }
+    /**
+     * Create a new CEL function builder
+     * @param name - The name of the function
+     * @returns A builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const add = CELFunction.new("add")
+     *   .param("a", "int")
+     *   .param("b", "int")
+     *   .returns("int")
+     *   .implement((a, b) => a + b);
+     * ```
+     */
+    static new(name) {
+        return new CELFunction(name);
+    }
+    /**
+     * Add a parameter to the function
+     */
+    param(name, type, optional = false) {
+        const newParams = [
+            ...this.params,
+            { name, type, optional },
+        ];
+        return new CELFunction(this.name, newParams, this.returnType);
+    }
+    /**
+     * Set the return type of the function
+     */
+    returns(type) {
+        return new CELFunction(this.name, this.params, type);
+    }
+    /**
+     * Set the implementation function and return the final definition
+     */
+    implement(impl) {
+        const definition = {
+            name: this.name,
+            params: [...this.params],
+            returnType: this.returnType,
+            impl: impl,
+        };
+        if (this.overloads.length > 0) {
+            definition.overloads = this.overloads;
+        }
+        return definition;
+    }
+    /**
+     * Add an overload variant of this function
+     */
+    overload(overload) {
+        if (overload.name !== this.name) {
+            throw new Error(`Overload name mismatch: expected ${this.name}, got ${overload.name}`);
+        }
+        this.overloads.push(overload);
+        return this;
+    }
+}
+/**
+ * Helper function to create a list type
+ */
+export function listType(elementType) {
+    return { kind: "list", elementType };
+}
+/**
+ * Helper function to create a map type
+ */
+export function mapType(keyType, valueType) {
+    return { kind: "map", keyType, valueType };
+}
+//# sourceMappingURL=functions.js.map

package/dist/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../lib/functions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoDH;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,WAAW;IAStB,YACE,IAAY,EACZ,SAA6B,EAAE,EAC/B,aAAyB,KAAK;QALxB,cAAS,GAA4B,EAAE,CAAC;QAO9C,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,mCAAmC,CAClE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,GAAG,CAAC,IAAY;QACrB,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CACH,IAAY,EACZ,IAAO,EACP,QAAQ,GAAG,KAAK;QAKhB,MAAM,SAAS,GAAG;YAChB,GAAG,IAAI,CAAC,MAAM;YACd,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;SACH,CAAC;QACxB,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChE,CAAC;IAED;;OAEG;IACH,OAAO,CAAuB,IAAO;QACnC,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;IAED;;OAEG;IACH,SAAS,CACP,IAAqE;QAErE,MAAM,UAAU,GAA0B;YACxC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACxB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAA+B;SACtC,CAAC;QAEF,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACxC,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,QAA+B;QACtC,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,oCAAoC,IAAI,CAAC,IAAI,SAAS,QAAQ,CAAC,IAAI,EAAE,CACtE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,WAAuB;IAI9C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CACrB,OAAmB,EACnB,SAAqB;IAErB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import type { EnvOptions, TypeCheckResult } from "./types.js";
+/**
+ * Initialize the WASM module
+ * @returns {Promise<void>}
+ */
+export declare function init(): Promise<void>;
+/**
+ * A compiled CEL program that can be evaluated with variables
+ */
+export declare class Program {
+    private programID;
+    private destroyed;
+    constructor(programID: string);
+    /**
+     * Evaluate the compiled program with the given variables
+     * @param vars - Variables to use in the evaluation
+     * @returns Promise resolving to the evaluation result
+     * @throws Error if evaluation fails or program has been destroyed
+     */
+    eval(vars?: Record<string, any> | null): Promise<any>;
+    /**
+     * Destroy this program and free associated WASM resources.
+     * After calling destroy(), this program instance should not be used.
+     * If FinalizationRegistry is available, resources will be automatically
+     * cleaned up when the object is garbage collected, but explicit cleanup
+     * is recommended.
+     */
+    destroy(): void;
+}
+/**
+ * A CEL environment that holds variable declarations and function definitions
+ */
+export declare class Env {
+    private envID;
+    private destroyed;
+    private constructor();
+    /**
+     * Create a new CEL environment
+     * @param options - Options including variable declarations and function definitions
+     * @returns Promise resolving to a new Env instance
+     * @throws Error if environment creation fails
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [
+     *     { name: "x", type: "int" },
+     *     { name: "y", type: "int" }
+     *   ],
+     *   functions: [
+     *     CELFunction.new("add")
+     *       .param("a", "int")
+     *       .param("b", "int")
+     *       .returns("int")
+     *       .implement((a, b) => a + b)
+     *   ]
+     * });
+     * ```
+     */
+    static new(options?: EnvOptions): Promise<Env>;
+    /**
+     * Compile a CEL expression in this environment
+     * @param expr - The CEL expression to compile
+     * @returns Promise resolving to a compiled Program
+     * @throws Error if compilation fails or environment has been destroyed
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [{ name: "x", type: "int" }]
+     * });
+     * const program = await env.compile("x + 10");
+     * const result = await program.eval({ x: 5 });
+     * console.log(result); // 15
+     * ```
+     */
+    compile(expr: string): Promise<Program>;
+    /**
+     * Typecheck a CEL expression in this environment without compiling it
+     * @param expr - The CEL expression to typecheck
+     * @returns Promise resolving to the type information
+     * @throws Error if typechecking fails or environment has been destroyed
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [{ name: "x", type: "int" }, { name: "y", type: "int" }]
+     * });
+     * const typeInfo = await env.typecheck("x + y");
+     * console.log(typeInfo.type); // "int"
+     *
+     * const listType = await env.typecheck("[1, 2, 3]");
+     * console.log(listType.type); // { kind: "list", elementType: "int" }
+     * ```
+     */
+    typecheck(expr: string): Promise<TypeCheckResult>;
+    /**
+     * Destroy this environment and free associated WASM resources.
+     * This will also clean up any registered JavaScript functions associated
+     * with this environment.
+     * After calling destroy(), this environment instance should not be used.
+     * If FinalizationRegistry is available, resources will be automatically
+     * cleaned up when the object is garbage collected, but explicit cleanup
+     * is recommended.
+     */
+    destroy(): void;
+}
+export type { CELType, CELTypeDef, CELListType, CELMapType, CELFunctionDefinition, CELFunctionParam, EnvOptions, VariableDeclaration, TypeCheckResult, } from "./types.js";
+export { listType, mapType, CELFunction } from "./functions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,UAAU,EACV,eAAe,EAChB,MAAM,YAAY,CAAC;AAkCpB;;;GAGG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAuC1C;AA2GD;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAkB;gBAEvB,SAAS,EAAE,MAAM;IAQ7B;;;;;OAKG;IACG,IAAI,CAAC,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAyBjE;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAyBhB;AAED;;GAEG;AACH,qBAAa,GAAG;IACd,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO;IAQP;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACU,GAAG,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC;IAmCpD;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA+B7C;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA+BvD;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;CAyBhB;AAGD,YAAY,EACV,OAAO,EACP,UAAU,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}