@elaraai/east 0.0.1-beta.0

package/dist/src/containers/sortedmap.d.ts

@@ -0,0 +1,165 @@
+/**
+ * A sorted map implementation using a B-tree data structure.
+ *
+ * @typeParam K - The type of keys in the map
+ * @typeParam T - The type of values in the map
+ *
+ * @remarks
+ * Implements the ES6 `Map` interface with additional capabilities:
+ * - Maintains entries in sorted order by key based on a comparison function
+ * - Supports {@link minKey} and {@link maxKey} for accessing key extrema
+ * - Provides range-based iteration starting from any key
+ * - Respects frozen state and throws errors on modification attempts
+ * - Includes static {@link groupBy} method for aggregation operations
+ *
+ * Used to implement East's {@link DictType} with total ordering semantics.
+ */
+export declare class SortedMap<K, T> implements Map<K, T> {
+    private btree;
+    /**
+     * Creates a new SortedMap.
+     *
+     * @param values - Optional initial entries as `[key, value]` pairs
+     * @param compare - Optional comparison function for ordering keys
+     *
+     * @remarks
+     * If no comparison function is provided, keys are compared using default ordering.
+     */
+    constructor(values?: Iterable<[K, T]>, compare?: (a: K, b: K) => number);
+    /** The number of key-value pairs in the map. */
+    get size(): number;
+    /**
+     * Retrieves the value associated with a key.
+     *
+     * @param key - The key to look up
+     * @returns The associated value, or `undefined` if the key is not present
+     */
+    get(key: K): T | undefined;
+    /**
+     * Associates a value with a key in the map.
+     *
+     * @param key - The key to set
+     * @param value - The value to associate with the key
+     * @returns This map for chaining
+     * @throws {TypeError} When the map is frozen
+     */
+    set(key: K, value: T): this;
+    /**
+     * Removes all entries from the map.
+     *
+     * @throws {TypeError} When the map is frozen
+     */
+    clear(): void;
+    /**
+     * Removes a key-value pair from the map.
+     *
+     * @param value - The key to remove
+     * @returns `true` if the key was present and removed, `false` otherwise
+     * @throws {TypeError} When the map is frozen
+     */
+    delete(value: K): boolean;
+    /**
+     * Checks if a key exists in the map.
+     *
+     * @param value - The key to check
+     * @returns `true` if the key is present, `false` otherwise
+     */
+    has(value: K): boolean;
+    /**
+     * Executes a callback for each entry in the map, in sorted order by key.
+     *
+     * @param callbackfn - Function to execute for each entry
+     * @param thisArg - Value to use as `this` when executing the callback
+     *
+     * @remarks
+     * The callback receives the value, key, and map (in that order for ES6 Map compatibility).
+     */
+    forEach(callbackfn: (value: T, key: K, set: Map<K, T>) => void, thisArg?: any): void;
+    /**
+     * Returns the smallest key in the map.
+     *
+     * @returns The minimum key, or `undefined` if the map is empty
+     *
+     * @remarks
+     * This is an O(log n) operation due to the B-tree structure.
+     */
+    minKey(): K | undefined;
+    /**
+     * Returns the largest key in the map.
+     *
+     * @returns The maximum key, or `undefined` if the map is empty
+     *
+     * @remarks
+     * This is an O(log n) operation due to the B-tree structure.
+     */
+    maxKey(): K | undefined;
+    /**
+     * Returns an iterator over the map's keys in sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding keys in sorted order
+     *
+     * @remarks
+     * If `firstKey` is provided, iteration starts from that key (or the next key if not present).
+     * This enables efficient range queries over sorted data.
+     */
+    keys(firstKey?: K | undefined): MapIterator<K>;
+    /**
+     * Returns an iterator over the map's values in key-sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding values in key-sorted order
+     *
+     * @remarks
+     * Values are returned in the order of their sorted keys, not sorted by value.
+     */
+    values(firstKey?: K | undefined): MapIterator<T>;
+    /**
+     * Returns an iterator over the map's entries in sorted order by key.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding `[key, value]` tuples in key-sorted order
+     *
+     * @remarks
+     * If `firstKey` is provided, iteration starts from that key.
+     */
+    entries(firstKey?: K | undefined): MapIterator<[K, T]>;
+    /**
+     * Returns an iterator over the map's entries in sorted order by key.
+     *
+     * @returns An iterator yielding `[key, value]` tuples in key-sorted order
+     *
+     * @remarks
+     * Makes {@link SortedMap} iterable with `for...of` loops.
+     */
+    [Symbol.iterator](): MapIterator<[K, T]>;
+    /** Returns the string tag for this object type. */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Groups items into a sorted map based on a key selector function.
+     *
+     * @typeParam K - The type of keys to group by
+     * @typeParam T - The type of items to group
+     * @param items - The items to group
+     * @param keySelector - Function that extracts the grouping key from each item
+     * @param compare - Optional comparison function for ordering keys
+     * @returns A {@link SortedMap} where each key maps to an array of items with that key
+     *
+     * @remarks
+     * This is a convenient aggregation function similar to SQL's `GROUP BY`.
+     * Items with the same key are collected into arrays in the order they appear.
+     *
+     * @example
+     * ```ts
+     * const people = [
+     *   { name: "Alice", age: 30 },
+     *   { name: "Bob", age: 25 },
+     *   { name: "Charlie", age: 30 }
+     * ];
+     * const byAge = SortedMap.groupBy(people, p => p.age);
+     * // Result: Map { 25 => [{name:"Bob",age:25}], 30 => [{name:"Alice",age:30}, {name:"Charlie",age:30}] }
+     * ```
+     */
+    static groupBy<K, T>(items: Iterable<T>, keySelector: (item: T) => K, compare?: (a: K, b: K) => number): SortedMap<K, T[]>;
+}
+//# sourceMappingURL=sortedmap.d.ts.map

package/dist/src/containers/sortedmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortedmap.d.ts","sourceRoot":"","sources":["../../../src/containers/sortedmap.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,KAAK,CAAc;IAE3B;;;;;;;;OAQG;gBACS,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM;IAStE,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAI1B;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAQ3B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAOzB;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAItB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAMpF;;;;;;;OAOG;IACH,MAAM,IAAI,CAAC,GAAG,SAAS;IAIvB;;;;;;;OAOG;IACH,MAAM,IAAI,CAAC,GAAG,SAAS;IAIvB;;;;;;;;;OASG;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC;IAI9C;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC;IAIhD;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAStD;;;;;;;OAOG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAIxC,mDAAmD;IACnD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;CAa7H"}

package/dist/src/containers/sortedmap.js

@@ -0,0 +1,237 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import sorted_btree from "sorted-btree";
+// Deal with CJS default import
+const BTree = sorted_btree.default;
+/**
+ * A sorted map implementation using a B-tree data structure.
+ *
+ * @typeParam K - The type of keys in the map
+ * @typeParam T - The type of values in the map
+ *
+ * @remarks
+ * Implements the ES6 `Map` interface with additional capabilities:
+ * - Maintains entries in sorted order by key based on a comparison function
+ * - Supports {@link minKey} and {@link maxKey} for accessing key extrema
+ * - Provides range-based iteration starting from any key
+ * - Respects frozen state and throws errors on modification attempts
+ * - Includes static {@link groupBy} method for aggregation operations
+ *
+ * Used to implement East's {@link DictType} with total ordering semantics.
+ */
+export class SortedMap {
+    btree;
+    /**
+     * Creates a new SortedMap.
+     *
+     * @param values - Optional initial entries as `[key, value]` pairs
+     * @param compare - Optional comparison function for ordering keys
+     *
+     * @remarks
+     * If no comparison function is provided, keys are compared using default ordering.
+     */
+    constructor(values, compare) {
+        this.btree = new BTree(undefined, compare);
+        if (values !== undefined) {
+            for (const [key, value] of values) {
+                this.btree.set(key, value);
+            }
+        }
+    }
+    /** The number of key-value pairs in the map. */
+    get size() {
+        return this.btree.size;
+    }
+    /**
+     * Retrieves the value associated with a key.
+     *
+     * @param key - The key to look up
+     * @returns The associated value, or `undefined` if the key is not present
+     */
+    get(key) {
+        return this.btree.get(key);
+    }
+    /**
+     * Associates a value with a key in the map.
+     *
+     * @param key - The key to set
+     * @param value - The value to associate with the key
+     * @returns This map for chaining
+     * @throws {TypeError} When the map is frozen
+     */
+    set(key, value) {
+        if (Object.isFrozen(this)) {
+            throw new TypeError("Cannot modify frozen SortedMap");
+        }
+        this.btree.set(key, value);
+        return this;
+    }
+    /**
+     * Removes all entries from the map.
+     *
+     * @throws {TypeError} When the map is frozen
+     */
+    clear() {
+        if (Object.isFrozen(this)) {
+            throw new TypeError("Cannot modify frozen SortedMap");
+        }
+        this.btree.clear();
+    }
+    /**
+     * Removes a key-value pair from the map.
+     *
+     * @param value - The key to remove
+     * @returns `true` if the key was present and removed, `false` otherwise
+     * @throws {TypeError} When the map is frozen
+     */
+    delete(value) {
+        if (Object.isFrozen(this)) {
+            throw new TypeError("Cannot modify frozen SortedMap");
+        }
+        return this.btree.delete(value);
+    }
+    /**
+     * Checks if a key exists in the map.
+     *
+     * @param value - The key to check
+     * @returns `true` if the key is present, `false` otherwise
+     */
+    has(value) {
+        return this.btree.has(value);
+    }
+    /**
+     * Executes a callback for each entry in the map, in sorted order by key.
+     *
+     * @param callbackfn - Function to execute for each entry
+     * @param thisArg - Value to use as `this` when executing the callback
+     *
+     * @remarks
+     * The callback receives the value, key, and map (in that order for ES6 Map compatibility).
+     */
+    forEach(callbackfn, thisArg) {
+        for (const [key, value] of this.btree.entries()) {
+            callbackfn.call(thisArg, value, key, this);
+        }
+    }
+    /**
+     * Returns the smallest key in the map.
+     *
+     * @returns The minimum key, or `undefined` if the map is empty
+     *
+     * @remarks
+     * This is an O(log n) operation due to the B-tree structure.
+     */
+    minKey() {
+        return this.btree.minKey();
+    }
+    /**
+     * Returns the largest key in the map.
+     *
+     * @returns The maximum key, or `undefined` if the map is empty
+     *
+     * @remarks
+     * This is an O(log n) operation due to the B-tree structure.
+     */
+    maxKey() {
+        return this.btree.maxKey();
+    }
+    /**
+     * Returns an iterator over the map's keys in sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding keys in sorted order
+     *
+     * @remarks
+     * If `firstKey` is provided, iteration starts from that key (or the next key if not present).
+     * This enables efficient range queries over sorted data.
+     */
+    keys(firstKey) {
+        return Iterator.from(this.btree.keys(firstKey));
+    }
+    /**
+     * Returns an iterator over the map's values in key-sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding values in key-sorted order
+     *
+     * @remarks
+     * Values are returned in the order of their sorted keys, not sorted by value.
+     */
+    values(firstKey) {
+        return Iterator.from(this.btree.values(firstKey));
+    }
+    /**
+     * Returns an iterator over the map's entries in sorted order by key.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding `[key, value]` tuples in key-sorted order
+     *
+     * @remarks
+     * If `firstKey` is provided, iteration starts from that key.
+     */
+    entries(firstKey) {
+        const gen = (function* (btree) {
+            for (const [key, value] of btree.entries(firstKey)) {
+                yield [key, value];
+            }
+        })(this.btree);
+        return Iterator.from(gen);
+    }
+    /**
+     * Returns an iterator over the map's entries in sorted order by key.
+     *
+     * @returns An iterator yielding `[key, value]` tuples in key-sorted order
+     *
+     * @remarks
+     * Makes {@link SortedMap} iterable with `for...of` loops.
+     */
+    [Symbol.iterator]() {
+        return Iterator.from(this.btree.entries());
+    }
+    /** Returns the string tag for this object type. */
+    get [Symbol.toStringTag]() {
+        return "SortedMap";
+    }
+    /**
+     * Groups items into a sorted map based on a key selector function.
+     *
+     * @typeParam K - The type of keys to group by
+     * @typeParam T - The type of items to group
+     * @param items - The items to group
+     * @param keySelector - Function that extracts the grouping key from each item
+     * @param compare - Optional comparison function for ordering keys
+     * @returns A {@link SortedMap} where each key maps to an array of items with that key
+     *
+     * @remarks
+     * This is a convenient aggregation function similar to SQL's `GROUP BY`.
+     * Items with the same key are collected into arrays in the order they appear.
+     *
+     * @example
+     * ```ts
+     * const people = [
+     *   { name: "Alice", age: 30 },
+     *   { name: "Bob", age: 25 },
+     *   { name: "Charlie", age: 30 }
+     * ];
+     * const byAge = SortedMap.groupBy(people, p => p.age);
+     * // Result: Map { 25 => [{name:"Bob",age:25}], 30 => [{name:"Alice",age:30}, {name:"Charlie",age:30}] }
+     * ```
+     */
+    static groupBy(items, keySelector, compare) {
+        const map = new SortedMap(undefined, compare);
+        for (const item of items) {
+            const key = keySelector(item);
+            const group = map.get(key);
+            if (group === undefined) {
+                map.set(key, [item]);
+            }
+            else {
+                group.push(item);
+            }
+        }
+        return map;
+    }
+}
+//# sourceMappingURL=sortedmap.js.map

package/dist/src/containers/sortedmap.js.map

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

package/dist/src/containers/sortedset.d.ts

@@ -0,0 +1,185 @@
+/**
+ * A sorted set implementation using a B-tree data structure.
+ *
+ * @typeParam K - The type of keys stored in the set
+ *
+ * @remarks
+ * Implements the ES6 `Set` interface with additional capabilities:
+ * - Maintains keys in sorted order based on a comparison function
+ * - Supports {@link minKey} and {@link maxKey} for accessing extrema
+ * - Provides range-based iteration starting from any key
+ * - Implements ES2024 set operations (union, intersection, difference, etc.)
+ * - Respects frozen state and throws errors on modification attempts
+ *
+ * Used to implement East's {@link SetType} with total ordering semantics.
+ */
+export declare class SortedSet<K> implements Set<K> {
+    private compare?;
+    private btree;
+    /**
+     * Creates a new SortedSet.
+     *
+     * @param values - Optional initial values to add to the set
+     * @param compare - Optional comparison function for ordering keys
+     *
+     * @remarks
+     * If no comparison function is provided, keys are compared using default ordering.
+     */
+    constructor(values?: Iterable<K>, compare?: ((a: K, b: K) => number) | undefined);
+    /** The number of elements in the set. */
+    get size(): number;
+    /**
+     * Adds a value to the set.
+     *
+     * @param value - The value to add
+     * @returns This set for chaining
+     * @throws {TypeError} When the set is frozen
+     */
+    add(value: K): this;
+    /**
+     * Removes all elements from the set.
+     *
+     * @throws {TypeError} When the set is frozen
+     */
+    clear(): void;
+    /**
+     * Removes a value from the set.
+     *
+     * @param value - The value to remove
+     * @returns `true` if the value was present and removed, `false` otherwise
+     * @throws {TypeError} When the set is frozen
+     */
+    delete(value: K): boolean;
+    /**
+     * Checks if a value exists in the set.
+     *
+     * @param value - The value to check
+     * @returns `true` if the value is present, `false` otherwise
+     */
+    has(value: K): boolean;
+    /**
+     * Executes a callback for each value in the set, in sorted order.
+     *
+     * @param callbackfn - Function to execute for each element
+     * @param thisArg - Value to use as `this` when executing the callback
+     *
+     * @remarks
+     * The callback receives the value twice (for ES6 Set compatibility) and the set itself.
+     */
+    forEach(callbackfn: (value: K, value2: K, set: Set<K>) => void, thisArg?: any): void;
+    /**
+     * Returns a new set containing all elements from this set and another.
+     *
+     * @typeParam U - The type of elements in the other set
+     * @param other - The set to union with
+     * @returns A new {@link SortedSet} containing all elements from both sets
+     */
+    union<U>(other: ReadonlySetLike<U>): SortedSet<K | U>;
+    /**
+     * Returns a new set containing only elements present in both sets.
+     *
+     * @typeParam U - The type of elements in the other set
+     * @param other - The set to intersect with
+     * @returns A new {@link SortedSet} containing common elements
+     */
+    intersection<U>(other: ReadonlySetLike<U>): SortedSet<K & U>;
+    /**
+     * Returns a new set containing elements in this set but not in another.
+     *
+     * @typeParam U - The type of elements in the other set
+     * @param other - The set to subtract
+     * @returns A new {@link SortedSet} with elements only in this set
+     */
+    difference<U>(other: ReadonlySetLike<U>): SortedSet<K>;
+    /**
+     * Returns a new set containing elements in either set but not both.
+     *
+     * @typeParam U - The type of elements in the other set
+     * @param other - The set to compare with
+     * @returns A new {@link SortedSet} with elements exclusive to each set
+     */
+    symmetricDifference<U>(other: ReadonlySetLike<U>): SortedSet<K | U>;
+    /**
+     * Checks if this set is a subset of another set.
+     *
+     * @param other - The potential superset
+     * @returns `true` if all elements of this set are in the other set
+     */
+    isSubsetOf(other: ReadonlySetLike<unknown>): boolean;
+    /**
+     * Checks if this set is a superset of another set.
+     *
+     * @param other - The potential subset
+     * @returns `true` if all elements of the other set are in this set
+     */
+    isSupersetOf(other: ReadonlySetLike<unknown>): boolean;
+    /**
+     * Checks if this set has no elements in common with another set.
+     *
+     * @param other - The set to compare with
+     * @returns `true` if the sets share no elements, `false` otherwise
+     */
+    isDisjointFrom(other: ReadonlySetLike<unknown>): boolean;
+    /**
+     * Returns the smallest value in the set.
+     *
+     * @returns The minimum value, or `undefined` if the set is empty
+     *
+     * @remarks
+     * This is an O(log n) operation due to the B-tree structure.
+     */
+    minKey(): K | undefined;
+    /**
+     * Returns the largest value in the set.
+     *
+     * @returns The maximum value, or `undefined` if the set is empty
+     *
+     * @remarks
+     * This is an O(log n) operation due to the B-tree structure.
+     */
+    maxKey(): K | undefined;
+    /**
+     * Returns an iterator over the set's keys in sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding keys in sorted order
+     *
+     * @remarks
+     * If `firstKey` is provided, iteration starts from that key (or the next key if not present).
+     * This enables efficient range queries over sorted data.
+     */
+    keys(firstKey?: K | undefined): SetIterator<K>;
+    /**
+     * Returns an iterator over the set's values in sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding values in sorted order
+     *
+     * @remarks
+     * Identical to {@link keys} for sets (values and keys are the same).
+     */
+    values(firstKey?: K | undefined): SetIterator<K>;
+    /**
+     * Returns an iterator over the set's entries in sorted order.
+     *
+     * @param firstKey - Optional starting key for range-based iteration
+     * @returns An iterator yielding `[key, key]` tuples in sorted order
+     *
+     * @remarks
+     * For ES6 Set compatibility, entries are `[key, key]` tuples.
+     * If `firstKey` is provided, iteration starts from that key.
+     */
+    entries(firstKey?: K | undefined): SetIterator<[K, K]>;
+    /**
+     * Returns an iterator over the set's values in sorted order.
+     *
+     * @returns An iterator yielding values in sorted order
+     *
+     * @remarks
+     * Makes {@link SortedSet} iterable with `for...of` loops.
+     */
+    [Symbol.iterator](): SetIterator<K>;
+    /** Returns the string tag for this object type. */
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=sortedset.d.ts.map

package/dist/src/containers/sortedset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortedset.d.ts","sourceRoot":"","sources":["../../../src/containers/sortedset.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,YAAW,GAAG,CAAC,CAAC,CAAC;IAYL,OAAO,CAAC,OAAO,CAAC;IAXlD,OAAO,CAAC,KAAK,CAAsB;IAEnC;;;;;;;;OAQG;gBACS,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAU,OAAO,CAAC,GAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,aAAA;IAS1E,yCAAyC;IACzC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAQnB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAOzB;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAItB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAMpF;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC;IAcrD;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC;IAY5D;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAUtD;;;;;;OAMG;IACH,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC;IAiBnE;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,OAAO;IASpD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,OAAO;IAUtD;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,OAAO;IASxD;;;;;;;OAOG;IACH,MAAM,IAAI,CAAC,GAAG,SAAS;IAIvB;;;;;;;OAOG;IACH,MAAM,IAAI,CAAC,GAAG,SAAS;IAIvB;;;;;;;;;OASG;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC;IAI9C;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC;IAIhD;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAStD;;;;;;;OAOG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC;IAInC,mDAAmD;IACnD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;CAEJ"}