@elaraai/east 0.0.1-beta.0

package/dist/src/containers/sortedset.js

@@ -0,0 +1,312 @@
+/**
+ * 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;
+// Note: Enhanced SetIterator types from ES2024 aren't fully stabilized in TypeScript yet
+// Using type assertions as temporary workaround until tooling catches up
+/**
+ * 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 class SortedSet {
+    compare;
+    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, compare) {
+        this.compare = compare;
+        this.btree = new BTree(undefined, compare);
+        if (values !== undefined) {
+            for (const value of values) {
+                this.btree.set(value, undefined);
+            }
+        }
+    }
+    /** The number of elements in the set. */
+    get size() {
+        return this.btree.size;
+    }
+    /**
+     * 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) {
+        if (Object.isFrozen(this)) {
+            throw new TypeError("Cannot modify frozen SortedSet");
+        }
+        this.btree.set(value, undefined);
+        return this;
+    }
+    /**
+     * Removes all elements from the set.
+     *
+     * @throws {TypeError} When the set is frozen
+     */
+    clear() {
+        if (Object.isFrozen(this)) {
+            throw new TypeError("Cannot modify frozen SortedSet");
+        }
+        this.btree.clear();
+    }
+    /**
+     * 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) {
+        if (Object.isFrozen(this)) {
+            throw new TypeError("Cannot modify frozen SortedSet");
+        }
+        return this.btree.delete(value);
+    }
+    /**
+     * 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) {
+        return this.btree.has(value);
+    }
+    /**
+     * 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, thisArg) {
+        for (const key of this.btree.keys()) {
+            callbackfn.call(thisArg, key, key, this);
+        }
+    }
+    /**
+     * 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(other) {
+        // Note: ReadonlySetLike.keys() returns an Iterator<U> (not Iterable),
+        // so we must consume it manually rather than using for..of.
+        const result = new SortedSet(undefined, this.compare);
+        for (const key of this.btree.keys()) {
+            result.add(key);
+        }
+        const it = other.keys();
+        for (let n = it.next(); !n.done; n = it.next()) {
+            result.add(n.value);
+        }
+        return result;
+    }
+    /**
+     * 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(other) {
+        const result = new SortedSet(undefined, this.compare);
+        const it = other.keys();
+        for (let n = it.next(); !n.done; n = it.next()) {
+            const key = n.value;
+            if (this.has(key)) {
+                result.add(key);
+            }
+        }
+        return result;
+    }
+    /**
+     * 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(other) {
+        const result = new SortedSet(undefined, this.compare);
+        for (const key of this.btree.keys()) {
+            if (!other.has(key)) {
+                result.add(key);
+            }
+        }
+        return result;
+    }
+    /**
+     * 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(other) {
+        const result = new SortedSet(undefined, this.compare);
+        for (const key of this.btree.keys()) {
+            if (!other.has(key)) {
+                result.add(key);
+            }
+        }
+        const it = other.keys();
+        for (let n = it.next(); !n.done; n = it.next()) {
+            const key = n.value;
+            if (!this.has(key)) {
+                result.add(key);
+            }
+        }
+        return result;
+    }
+    /**
+     * 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) {
+        for (const key of this.btree.keys()) {
+            if (!other.has(key)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 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) {
+        const it = other.keys();
+        for (let n = it.next(); !n.done; n = it.next()) {
+            if (!this.has(n.value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 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) {
+        for (const key of this.btree.keys()) {
+            if (other.has(key)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 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() {
+        return this.btree.minKey();
+    }
+    /**
+     * 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() {
+        return this.btree.maxKey();
+    }
+    /**
+     * 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) {
+        return Iterator.from(this.btree.keys(firstKey));
+    }
+    /**
+     * 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) {
+        return Iterator.from(this.btree.keys(firstKey));
+    }
+    /**
+     * 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) {
+        const gen = (function* (btree) {
+            for (const key of btree.keys(firstKey)) {
+                yield [key, key];
+            }
+        })(this.btree);
+        return Iterator.from(gen);
+    }
+    /**
+     * 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]() {
+        return Iterator.from(this.btree.keys());
+    }
+    /** Returns the string tag for this object type. */
+    get [Symbol.toStringTag]() {
+        return "SortedSet";
+    }
+}
+//# sourceMappingURL=sortedset.js.map

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

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

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

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ *
+ * @remarks
+ */
+export declare const variant_symbol: unique symbol;
+export type variant_symbol = typeof variant_symbol;
+/**
+ * Represents a sum-type value with a type tag and associated value.
+ *
+ * @typeParam Type - The type of the discriminant tag
+ * @typeParam Value - The type of the associated value
+ *
+ * @remarks
+ * Variants are immutable and use nominal typing via the brand symbol.
+ * This is the foundation for East's variant types (sum types).
+ */
+export type variant<Type = string, Value = any> = {
+    /** The discriminant tag identifying which variant case this is */
+    type: Type;
+    /** The value associated with this variant case */
+    value: Value;
+    /** Brand symbol for nominal typing */
+    [variant_symbol]: null;
+};
+/**
+ * Constructs a sum-type value with a specific type tag and associated value.
+ *
+ * @typeParam Type - The string literal type of the discriminant tag
+ * @typeParam Value - The type of the value to associate with this variant
+ * @param type - The discriminant tag for this variant
+ * @param value - The value to associate with this variant
+ * @returns A branded variant object
+ *
+ * @example
+ * ```ts
+ * const success = variant("success", { data: [1, 2, 3] });
+ * const error = variant("error", "Connection failed");
+ * ```
+ */
+export declare function variant<Type extends string, Value = null>(type: Type, value?: Value): variant<Type, Value>;
+/**
+ * Deconstructs a variant by pattern matching on its type tag.
+ *
+ * @typeParam V - The variant type to match against, must have `type` and `value` properties
+ * @typeParam Fs - Object type mapping each variant case to its handler function
+ * @typeParam Default - The type of the default value when handler is optional
+ *
+ * @param variant - The variant to match against
+ * @param fs - Object mapping type tags to handler functions
+ * @param defaultValue - Optional default value if no handler matches
+ * @returns The result of calling the matching handler function
+ *
+ * @remarks
+ * This function has two overloads:
+ * 1. All handlers required - returns the handler's return type
+ * 2. Handlers optional with default - returns handler return type or default type
+ *
+ * The type system ensures exhaustive matching when all handlers are provided,
+ * and allows partial matching when a default value is supplied.
+ *
+ * @example
+ * ```ts
+ * // Exhaustive matching (all cases required)
+ * const result = match(maybeValue, {
+ *   some: (v) => v * 2,
+ *   none: () => 0
+ * });
+ *
+ * // Partial matching with default
+ * const result = match(response, {
+ *   success: (data) => data.length
+ * }, -1);
+ * ```
+ */
+export declare function match<V extends {
+    type: string;
+    value: any;
+}, Fs extends {
+    [K in V["type"]]: (value: (V & {
+        type: K;
+    })["value"]) => any;
+}>(variant: V, fs: Fs, defaultValue?: any): ReturnType<Fs[V["type"]]>;
+export declare function match<V extends {
+    type: string;
+    value: any;
+}, Fs extends {
+    [K in V["type"]]?: (value: (V & {
+        type: K;
+    })["value"]) => any;
+}, Default extends any>(variant: V, fs: Fs, defaultValue: Default): ReturnType<Exclude<Fs[keyof Fs], undefined>> | Default;
+/**
+ * Represents the absence of a value in an Option type.
+ *
+ * @remarks
+ * This is a singleton value representing the "none" case of the Option pattern.
+ */
+export declare const none: variant<"none", null>;
+export type none = typeof none;
+/**
+ * Wraps a value in the "some" case of an Option type.
+ *
+ * @typeParam T - The type of the value to wrap
+ * @param value - The value to wrap
+ * @returns A variant tagged as "some" containing the value
+ *
+ * @example
+ * ```ts
+ * const maybeNumber = some(42);
+ * const result = match(maybeNumber, {
+ *   some: (n) => n * 2,
+ *   none: () => 0
+ * }); // returns 84
+ * ```
+ */
+export declare function some<T>(value: T): variant<"some", T>;
+export type some<T> = variant<"some", T>;
+/**
+ * Represents an optional value that may be present (some) or absent (none).
+ *
+ * @typeParam T - The type of the value when present
+ *
+ * @remarks
+ * This is East's standard approach to representing nullable values safely.
+ * Use with the `match` function for exhaustive pattern matching.
+ */
+export type option<T> = none | some<T>;
+/** Check if a value is a variant */
+export declare function isVariant(v: any): v is variant;
+//# sourceMappingURL=variant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"variant.d.ts","sourceRoot":"","sources":["../../../src/containers/variant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,eAAoB,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,MAAM,OAAO,CAAC,IAAI,GAAG,MAAM,EAAE,KAAK,GAAG,GAAG,IAAI;IAC9C,kEAAkE;IAClE,IAAI,EAAE,IAAI,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,KAAK,CAAC;IACb,sCAAsC;IACtC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAE,KAAqB,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAMzH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,KAAK,CACjB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,EACtC,EAAE,SAAS;KAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG;CAAE,EAC7E,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,YAAY,CAAC,EAAE,GAAG,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;AACpE,wBAAgB,KAAK,CACjB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,EACtC,EAAE,SAAS;KAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG;CAAE,EAC5E,OAAO,SAAS,GAAG,EACrB,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,GAAG,OAAO,CAAA;AAOpG;;;;;GAKG;AACH,eAAO,MAAM,IAAI,uBAAwB,CAAC;AAC1C,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC;AAE/B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,sBAE/B;AACD,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAEvC,oCAAoC;AACpC,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,OAAO,CAE9C"}

package/dist/src/containers/variant.js

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ *
+ * @remarks
+ */
+export const variant_symbol = Symbol("variant");
+/**
+ * Constructs a sum-type value with a specific type tag and associated value.
+ *
+ * @typeParam Type - The string literal type of the discriminant tag
+ * @typeParam Value - The type of the value to associate with this variant
+ * @param type - The discriminant tag for this variant
+ * @param value - The value to associate with this variant
+ * @returns A branded variant object
+ *
+ * @example
+ * ```ts
+ * const success = variant("success", { data: [1, 2, 3] });
+ * const error = variant("error", "Connection failed");
+ * ```
+ */
+export function variant(type, value = null) {
+    return {
+        type,
+        value,
+        [variant_symbol]: null,
+    };
+}
+;
+export function match(e, fs, d) {
+    const f = fs[e.type];
+    if (f === undefined)
+        return d;
+    return f(e.value);
+}
+;
+/**
+ * Represents the absence of a value in an Option type.
+ *
+ * @remarks
+ * This is a singleton value representing the "none" case of the Option pattern.
+ */
+export const none = variant("none", null);
+/**
+ * Wraps a value in the "some" case of an Option type.
+ *
+ * @typeParam T - The type of the value to wrap
+ * @param value - The value to wrap
+ * @returns A variant tagged as "some" containing the value
+ *
+ * @example
+ * ```ts
+ * const maybeNumber = some(42);
+ * const result = match(maybeNumber, {
+ *   some: (n) => n * 2,
+ *   none: () => 0
+ * }); // returns 84
+ * ```
+ */
+export function some(value) {
+    return variant("some", value);
+}
+/** Check if a value is a variant */
+export function isVariant(v) {
+    return typeof v === "object" && v !== null && v[variant_symbol] === null;
+}
+//# sourceMappingURL=variant.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"variant.js","sourceRoot":"","sources":["../../../src/containers/variant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAsBhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,OAAO,CAAoC,IAAU,EAAE,QAAe,IAAa;IAC/F,OAAO;QACH,IAAI;QACJ,KAAK;QACL,CAAC,cAAc,CAAC,EAAE,IAAI;KACzB,CAAC;AACN,CAAC;AAAA,CAAC;AA6CF,MAAM,UAAU,KAAK,CAAC,CAAU,EAAE,EAA4C,EAAE,CAAO;IACnF,MAAM,CAAC,GAAI,EAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC;AAAA,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAG1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,IAAI,CAAI,KAAQ;IAC5B,OAAO,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAClC,CAAC;AAcD,oCAAoC;AACpC,MAAM,UAAU,SAAS,CAAC,CAAM;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;AAC7E,CAAC"}

package/dist/src/datetime_format/parse.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Datetime parsing runtime implementation.
+ *
+ * This module provides the runtime parsing logic for converting strings
+ * to Date objects according to parsed format token arrays. This is called by the
+ * DateTimeParseFormat builtin.
+ */
+import type { DateTimeFormatToken } from "./types.js";
+/**
+ * Result of parsing a datetime string.
+ */
+export type DateTimeParseResult = {
+    success: true;
+    value: Date;
+} | {
+    success: false;
+    error: string;
+    position: number;
+};
+/**
+ * Parses a datetime string according to format tokens.
+ *
+ * @param input - The string to parse
+ * @param tokens - Array of format tokens specifying the expected format
+ * @returns Parse result containing either the Date or an error with position
+ *
+ * @remarks
+ * All dates are treated as UTC (naive datetimes with no timezone information).
+ * The parsed components are used to construct a Date using Date.UTC().
+ *
+ * Weekday tokens (dd, ddd, dddd) are currently ignored during parsing - they
+ * are consumed from the input but not validated against the actual weekday.
+ *
+ * @example
+ * ```ts
+ * const tokens = tokenizeDateTimeFormat("YYYY-MM-DD");
+ * const result = parseDateTimeFormatted("2025-01-15", tokens);
+ * if (result.success) {
+ *   console.log(result.value); // Date object for 2025-01-15T00:00:00.000Z
+ * } else {
+ *   console.log(`Parse error at position ${result.position}: ${result.error}`);
+ * }
+ * ```
+ */
+export declare function parseDateTimeFormatted(input: string, tokens: DateTimeFormatToken[]): DateTimeParseResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/src/datetime_format/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/datetime_format/parse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC9B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AA8BxD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,CAk3BxG"}