pynect 0.0.0-stage → 0.2.0

package/dist/core/PyCallable.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * pynect - PyCallable
+ * Represents a Python callable (function, method, class constructor).
+ * Extends PyProxy with call metadata and convenience methods.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyCallable = void 0;
+const PyProxy_1 = require("./PyProxy");
+/**
+ * PyCallable - wraps a Python function or method.
+ *
+ * @example
+ * ```typescript
+ * const np = await py.import('numpy');
+ * const zeros = await np.zeros;  // PyCallable
+ * const arr = await zeros([3, 3], { dtype: 'float64' });
+ *
+ * // Or more concisely:
+ * const arr2 = await np.zeros([3, 3]);
+ * ```
+ */
+class PyCallable extends PyProxy_1.PyProxy {
+    _callableName;
+    constructor(objectId, path, callableName, addon, callTimeout, executionTimeout) {
+        super({
+            objectId,
+            path,
+            addon,
+            callTimeout,
+            executionTimeout,
+        });
+        this._callableName = callableName;
+    }
+    /** Callable name */
+    get callableName() {
+        return this._callableName;
+    }
+    /**
+     * Call the callable with given arguments.
+     * Same as using the callable directly (proxy syntax).
+     *
+     * @example
+     * ```typescript
+     * const result = await callable.invoke([1, 2, 3], { axis: 0 });
+     * // equivalent to: await callable([1, 2, 3], { axis: 0 })
+     * ```
+     */
+    async invoke(...args) {
+        return this(...args);
+    }
+    /** Invoke with cancellation or per-call timeout overrides. */
+    async invokeWithOptions(options, ...args) {
+        return this.withOptions(options, ...args);
+    }
+    /**
+     * Call with explicit positional args and keyword args.
+     *
+     * @example
+     * ```typescript
+     * const result = await callable.call([1, 2, 3], { axis: 0, keepdims: true });
+     * ```
+     */
+    async call(args, kwargs, options = {}) {
+        return this.callWithOptions(args, options, kwargs);
+    }
+    /**
+     * Partially apply arguments (like functools.partial in Python).
+     *
+     * @example
+     * ```typescript
+     * const readCsvUtf8 = await pd.read_csv.partial({ encoding: 'utf-8' });
+     * const df = await readCsvUtf8('data.csv');
+     * ```
+     */
+    partial(...partialArgs) {
+        const internal = this[PyProxy_1.PYPROXY_INTERNAL];
+        const callableName = `${this._callableName}(partial)`;
+        const wrapper = new PyCallable(internal.objectId, internal.path, callableName, internal.addon, internal.callTimeout, internal.executionTimeout);
+        // Override: always prepend partialArgs (use arrow to capture outer `this` lexically)
+        const callSelf = (...a) => this(...a);
+        const overrideProxy = new Proxy(wrapper, {
+            apply(_target, _thisArg, args) {
+                return callSelf(...partialArgs, ...args);
+            },
+        });
+        return overrideProxy;
+    }
+    /**
+     * Get introspection information about this callable.
+     */
+    async getInfo() {
+        return null;
+    }
+    static fromProxy(proxy, name) {
+        const internal = proxy[PyProxy_1.PYPROXY_INTERNAL];
+        return new PyCallable(internal.objectId, internal.path, name, internal.addon, internal.callTimeout, internal.executionTimeout);
+    }
+    toString() {
+        return `[PyCallable '${this._callableName}' id=${this[PyProxy_1.PYPROXY_INTERNAL].objectId}]`;
+    }
+}
+exports.PyCallable = PyCallable;
+//# sourceMappingURL=PyCallable.js.map

package/dist/core/PyCallable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyCallable.js","sourceRoot":"","sources":["../../src/core/PyCallable.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,uCAAsD;AAKtD;;;;;;;;;;;;GAYG;AACH,MAAa,UAAW,SAAQ,iBAAO;IACpB,aAAa,CAAS;IAEvC,YACE,QAAoB,EACpB,IAAmB,EACnB,YAAoB,EACpB,KAAkB,EAClB,WAAoB,EACpB,gBAAyB;QAEzB,KAAK,CAAC;YACJ,QAAQ;YACR,IAAI;YACJ,KAAK;YACL,WAAW;YACX,gBAAgB;SACjB,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;IACpC,CAAC;IAED,oBAAoB;IACpB,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,CAAC,GAAG,IAAe;QAC7B,OAAQ,IAAgD,CAAC,GAAG,IAAI,CAAC,CAAC;IACpE,CAAC;IAED,8DAA8D;IAC9D,KAAK,CAAC,iBAAiB,CAAC,OAAsB,EAAE,GAAG,IAAe;QAChE,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CACR,IAAe,EACf,MAAgC,EAChC,UAAyB,EAAE;QAE3B,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,GAAG,WAAsB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,0BAAgB,CAAC,CAAC;QACxC,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,aAAa,WAAW,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,UAAU,CAC5B,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,IAAI,EACb,YAAY,EACZ,QAAQ,CAAC,KAAK,EACd,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,gBAAgB,CAC1B,CAAC;QAEF,qFAAqF;QACrF,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAY,EAAE,EAAE,CAClC,IAAgD,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,MAAM,aAAa,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE;YACvC,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAe;gBACtC,OAAO,QAAQ,CAAC,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,CAAC;YAC3C,CAAC;SACF,CAAC,CAAC;QAEH,OAAO,aAA2B,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,KAAc,EAAE,IAAY;QAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,0BAAgB,CAAC,CAAC;QACzC,OAAO,IAAI,UAAU,CACnB,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,IAAI,EACb,IAAI,EACJ,QAAQ,CAAC,KAAK,EACd,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,gBAAgB,CAC1B,CAAC;IACJ,CAAC;IAEQ,QAAQ;QACf,OAAO,gBAAgB,IAAI,CAAC,aAAa,QAAQ,IAAI,CAAC,0BAAgB,CAAC,CAAC,QAAQ,GAAG,CAAC;IACtF,CAAC;CACF;AApHD,gCAoHC"}

package/dist/core/PyContext.d.ts

@@ -0,0 +1,76 @@
+/**
+ * pynect - PyContext
+ * Manages an isolated Python execution context (namespace).
+ * Useful for running code in isolation without polluting the global namespace.
+ */
+import type { NativeAddon } from '../types/addon';
+import { PyProxy } from './PyProxy';
+/**
+ * PyContext - an isolated Python execution environment.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await PyContext.create(addon);
+ *
+ * // Run code in isolation
+ * await ctx.exec('x = 42');
+ * await ctx.exec('y = x * 2');
+ * const result = await ctx.eval('x + y');
+ * console.log(result);  // 126
+ *
+ * // Import into context
+ * const pd = await ctx.import('pandas');
+ * await ctx.exec("df = pd.DataFrame({'a': [1,2,3]})");
+ * const df = await ctx.get('df');
+ * ```
+ */
+export declare class PyContext {
+    private readonly _addon;
+    private readonly _namespacePyId;
+    private _variables;
+    private _destroyed;
+    private constructor();
+    /**
+     * Create a new isolated Python context.
+     */
+    static create(addon: NativeAddon): Promise<PyContext>;
+    /**
+     * Execute Python code in this context.
+     */
+    exec(code: string): Promise<void>;
+    /**
+     * Evaluate a Python expression in this context and return the result.
+     */
+    eval(expression: string): Promise<unknown>;
+    /**
+     * Import a module into this context.
+     */
+    import(moduleName: string): Promise<PyProxy>;
+    /**
+     * Get a variable from the context namespace.
+     */
+    get(name: string): Promise<unknown>;
+    /**
+     * Set a variable in the context namespace.
+     */
+    set(name: string, value: unknown): Promise<void>;
+    /**
+     * Check if a name is defined in the context.
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Delete a variable from the context.
+     */
+    delete(name: string): Promise<void>;
+    /**
+     * Clear all variables in the context.
+     */
+    clear(): Promise<void>;
+    /**
+     * Destroy the context and free resources.
+     */
+    destroy(): Promise<void>;
+    private _ensureNotDestroyed;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=PyContext.d.ts.map

package/dist/core/PyContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyContext.d.ts","sourceRoot":"","sources":["../../src/core/PyContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AAMtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO;IAMP;;OAEG;WACU,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IA2B3D;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvC;;OAEG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyChD;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA+BlD;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmDzC;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBtD;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUzC;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,mBAAmB;IAM3B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvC"}

package/dist/core/PyContext.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * pynect - PyContext
+ * Manages an isolated Python execution context (namespace).
+ * Useful for running code in isolation without polluting the global namespace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyContext = void 0;
+const PyProxy_1 = require("./PyProxy");
+const ErrorTranslator_1 = require("../utils/ErrorTranslator");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('PyContext');
+/**
+ * PyContext - an isolated Python execution environment.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await PyContext.create(addon);
+ *
+ * // Run code in isolation
+ * await ctx.exec('x = 42');
+ * await ctx.exec('y = x * 2');
+ * const result = await ctx.eval('x + y');
+ * console.log(result);  // 126
+ *
+ * // Import into context
+ * const pd = await ctx.import('pandas');
+ * await ctx.exec("df = pd.DataFrame({'a': [1,2,3]})");
+ * const df = await ctx.get('df');
+ * ```
+ */
+class PyContext {
+    _addon;
+    _namespacePyId;
+    _variables;
+    _destroyed = false;
+    constructor(addon, namespacePyId) {
+        this._addon = addon;
+        this._namespacePyId = namespacePyId;
+        this._variables = new Map();
+    }
+    /**
+     * Create a new isolated Python context.
+     */
+    static async create(addon) {
+        // Create a fresh namespace dict in Python
+        const result = await addon.evalPython('{}');
+        if (!result.success) {
+            if (result.error) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            throw new Error('Failed to create Python context');
+        }
+        if (!result.objectId) {
+            throw new Error('Context namespace object ID not returned');
+        }
+        return new PyContext(addon, result.objectId);
+    }
+    /**
+     * Execute Python code in this context.
+     */
+    async exec(code) {
+        this._ensureNotDestroyed();
+        const result = await this._addon.runPythonCode(code);
+        if (!result.success && result.error) {
+            throw (0, ErrorTranslator_1.translatePythonError)({
+                type: result.error.type,
+                message: result.error.message,
+                traceback: result.error.traceback || '',
+            });
+        }
+    }
+    /**
+     * Evaluate a Python expression in this context and return the result.
+     */
+    async eval(expression) {
+        this._ensureNotDestroyed();
+        const result = await this._addon.evalPython(expression);
+        if (!result.success) {
+            if (result.error) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            throw new Error('Evaluation failed');
+        }
+        if (result.isObject && result.objectId) {
+            return PyProxy_1.PyProxy._createFromObjectId(result.objectId, [], this._addon);
+        }
+        if (result.resultJson !== undefined) {
+            try {
+                return JSON.parse(result.resultJson);
+            }
+            catch {
+                return result.resultJson;
+            }
+        }
+        return null;
+    }
+    /**
+     * Import a module into this context.
+     */
+    async import(moduleName) {
+        this._ensureNotDestroyed();
+        const result = await this._addon.importModule(moduleName);
+        if (!result.success) {
+            if (result.error) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            throw new Error(`Failed to import module '${moduleName}'`);
+        }
+        if (!result.objectId) {
+            throw new Error('Module object ID not returned');
+        }
+        return PyProxy_1.PyProxy._createFromObjectId(result.objectId, [], this._addon);
+    }
+    /**
+     * Get a variable from the context namespace.
+     */
+    async get(name) {
+        this._ensureNotDestroyed();
+        const pyId = this._variables.get(name);
+        if (pyId) {
+            return PyProxy_1.PyProxy._createFromObjectId(pyId, [], this._addon);
+        }
+        // Try to get from Python global namespace
+        const result = await this._addon.evalPython(name);
+        if (!result.success) {
+            if (result.error?.type === 'NameError') {
+                return undefined;
+            }
+            if (result.error) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            return undefined;
+        }
+        if (result.isObject && result.objectId) {
+            return PyProxy_1.PyProxy._createFromObjectId(result.objectId, [], this._addon);
+        }
+        if (result.resultJson !== undefined) {
+            try {
+                return JSON.parse(result.resultJson);
+            }
+            catch {
+                return result.resultJson;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Set a variable in the context namespace.
+     */
+    async set(name, value) {
+        this._ensureNotDestroyed();
+        assertPythonIdentifier(name);
+        if (value instanceof PyProxy_1.PyProxy) {
+            const internal = value[PyProxy_1.PYPROXY_INTERNAL];
+            this._variables.set(name, internal.objectId);
+            return;
+        }
+        // For primitives and serializable values: set via exec
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined) {
+            throw new TypeError(`Value for '${name}' is not JSON serializable`);
+        }
+        const encoded = Buffer.from(serialized, 'utf8').toString('base64');
+        await this.exec(`${name} = __import__('json').loads(__import__('base64').b64decode('${encoded}'))`);
+    }
+    /**
+     * Check if a name is defined in the context.
+     */
+    async has(name) {
+        this._ensureNotDestroyed();
+        try {
+            const val = await this.get(name);
+            return val !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete a variable from the context.
+     */
+    async delete(name) {
+        this._ensureNotDestroyed();
+        assertPythonIdentifier(name);
+        this._variables.delete(name);
+        await this.exec(`del ${name}`).catch(() => { }); // ignore if not defined
+    }
+    /**
+     * Clear all variables in the context.
+     */
+    async clear() {
+        this._ensureNotDestroyed();
+        this._variables.clear();
+    }
+    /**
+     * Destroy the context and free resources.
+     */
+    async destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        this._destroyed = true;
+        this._variables.clear();
+        this._addon.decRef(this._namespacePyId);
+        logger.debug('PyContext destroyed');
+    }
+    _ensureNotDestroyed() {
+        if (this._destroyed) {
+            throw new Error('PyContext has been destroyed');
+        }
+    }
+    [Symbol.asyncDispose]() {
+        return this.destroy();
+    }
+}
+exports.PyContext = PyContext;
+function assertPythonIdentifier(name) {
+    if (!/^[A-Za-z_]\w*$/u.test(name)) {
+        throw new TypeError(`Invalid Python identifier: ${JSON.stringify(name)}`);
+    }
+}
+//# sourceMappingURL=PyContext.js.map

package/dist/core/PyContext.js.map

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

package/dist/core/PyIterator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * pynect - PyIterator
+ * Wraps a Python iterator for use with JavaScript's for await...of.
+ * Provides both async iteration and manual .next() calls.
+ */
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId } from '../types/python';
+import { PyProxy } from './PyProxy';
+export interface PyIteratorOptions {
+    /** Maximum number of items to yield (0 = no limit) */
+    limit?: number;
+    /** Whether to wrap Python objects in PyProxy */
+    wrapObjects?: boolean;
+    /** Timeout per .next() call (ms) */
+    timeout?: number;
+}
+/**
+ * PyIterator - manages a Python iterator lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const iterator = await PyIterator.create(pyList, addon);
+ *
+ * for await (const item of iterator) {
+ * console.log(item);
+ * }
+ *
+ * // Or manually:
+ * const { value, done } = await iterator.next();
+ * ```
+ */
+export declare class PyIterator<T = unknown> implements AsyncIterable<T>, AsyncIterator<T> {
+    private readonly _iteratorId;
+    private readonly _addon;
+    private readonly _objectId;
+    private readonly _options;
+    private _done;
+    private _position;
+    private _destroyed;
+    private constructor();
+    /**
+     * Create a PyIterator from a PyProxy.
+     */
+    static create(source: PyProxy, options?: PyIteratorOptions): Promise<PyIterator>;
+    /**
+     * Create a PyIterator from an object ID and iterator ID directly.
+     */
+    static fromIds(iteratorId: number, objectId: PyObjectId, addon: NativeAddon, options?: PyIteratorOptions): PyIterator;
+    /** Current position in iteration */
+    get position(): number;
+    /** Whether iteration is complete */
+    get isDone(): boolean;
+    next(): Promise<IteratorResult<T>>;
+    return(value?: T): Promise<IteratorResult<T>>;
+    throw(error?: unknown): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Collect all items into an array.
+     * Use with care for large iterators!
+     */
+    toArray(maxItems?: number): Promise<T[]>;
+    /**
+     * Process items in batches.
+     */
+    batch(batchSize: number): AsyncGenerator<T[]>;
+    /**
+     * Map items through a transform function.
+     */
+    map<U>(fn: (item: T, index: number) => U | Promise<U>): AsyncGenerator<U>;
+    /**
+     * Filter items.
+     */
+    filter(fn: (item: T, index: number) => boolean | Promise<boolean>): AsyncGenerator<T>;
+    /**
+     * Take first N items.
+     */
+    take(n: number): Promise<T[]>;
+    /**
+     * Destroy the underlying Python iterator (frees resources).
+     * Called automatically when iteration completes.
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=PyIterator.d.ts.map

package/dist/core/PyIterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyIterator.d.ts","sourceRoot":"","sources":["../../src/core/PyIterator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AAKtD,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;IAChF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO;IAYP;;OAEG;WACU,MAAM,CACjB,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAgCtB;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,UAAU;IAIb,oCAAoC;IACpC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,oCAAoC;IACpC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAIK,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA4ElC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAK7C,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAOxD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAM1C;;;OAGG;IACG,OAAO,CAAC,QAAQ,SAAS,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAS9C;;OAEG;IACI,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC;IAcpD;;OAEG;IACI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAOhF;;OAEG;IACI,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAO5F;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAUnC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAU/B"}