ts-data-forge 1.0.0 → 1.0.1

package/dist/collections/iset.mjs

@@ -0,0 +1,437 @@
+import '../functional/optional.mjs';
+import { Result } from '../functional/result.mjs';
+import '../number/branded-types/finite-number.mjs';
+import '../number/branded-types/int.mjs';
+import '../number/branded-types/int16.mjs';
+import '../number/branded-types/int32.mjs';
+import '../number/branded-types/non-negative-finite-number.mjs';
+import '../number/branded-types/non-negative-int16.mjs';
+import '../number/branded-types/non-negative-int32.mjs';
+import '../number/branded-types/non-zero-finite-number.mjs';
+import '../number/branded-types/non-zero-int.mjs';
+import '../number/branded-types/non-zero-int16.mjs';
+import '../number/branded-types/non-zero-int32.mjs';
+import '../number/branded-types/non-zero-safe-int.mjs';
+import '../number/branded-types/non-zero-uint16.mjs';
+import '../number/branded-types/non-zero-uint32.mjs';
+import '../number/branded-types/positive-finite-number.mjs';
+import '../number/branded-types/positive-int.mjs';
+import '../number/branded-types/positive-int16.mjs';
+import '../number/branded-types/positive-int32.mjs';
+import '../number/branded-types/positive-safe-int.mjs';
+import '../number/branded-types/positive-uint16.mjs';
+import '../number/branded-types/positive-uint32.mjs';
+import '../number/branded-types/safe-int.mjs';
+import '../number/branded-types/safe-uint.mjs';
+import '../number/branded-types/uint.mjs';
+import '../number/branded-types/uint16.mjs';
+import { asUint32 } from '../number/branded-types/uint32.mjs';
+import '../number/enum/int8.mjs';
+import '../number/enum/uint8.mjs';
+import '../number/num.mjs';
+import '../number/refined-number-utils.mjs';
+import { unknownToString } from '../others/unknown-to-string.mjs';
+
+/**
+ * Provides utility functions for ISet.
+ */
+var ISet;
+(function (ISet) {
+    /**
+     * Creates a new ISet instance from an iterable of elements.
+     *
+     * This factory function accepts any iterable of elements, including arrays,
+     * JavaScript Sets, other ISets, or custom iterables. Duplicate elements in the
+     * input iterable will be automatically deduplicated in the resulting set.
+     *
+     * **Performance:** O(n) where n is the number of elements in the iterable.
+     *
+     * @template K The type of the elements. Must extend MapSetKeyType.
+     * @param iterable An iterable of elements (e.g., Array, Set, ISet, etc.)
+     * @returns A new ISet instance containing all unique elements from the iterable.
+     *
+     * @example
+     * ```typescript
+     * // From array (duplicates automatically removed)
+     * const uniqueIds = ISet.create([1, 2, 3, 2, 1]); // Contains: 1, 2, 3
+     * console.log(uniqueIds.size); // Output: 3
+     *
+     * // From JavaScript Set
+     * const jsSet = new Set(["red", "green", "blue"]);
+     * const colors = ISet.create(jsSet);
+     * console.log(colors.has("red")); // Output: true
+     *
+     * // From another ISet (creates a copy)
+     * const originalTags = ISet.create(["typescript", "immutable"]);
+     * const copiedTags = ISet.create(originalTags);
+     * console.log(copiedTags.size); // Output: 2
+     *
+     * // Empty set
+     * const emptyPermissions = ISet.create<string>([]);
+     * console.log(emptyPermissions.isEmpty); // Output: true
+     *
+     * // Fluent operations
+     * const processedNumbers = ISet.create([1, 2, 3, 4, 5])
+     *   .filter(x => x % 2 === 0)  // Keep even numbers: 2, 4
+     *   .add(6)                    // Add 6: 2, 4, 6
+     *   .delete(2);                // Remove 2: 4, 6
+     * console.log(processedNumbers.toArray().sort()); // Output: [4, 6]
+     *
+     * // From generator function
+     * function* generatePrimes(): Generator<number> {
+     *   yield 2; yield 3; yield 5; yield 7;
+     * }
+     * const primes = ISet.create(generatePrimes());
+     * console.log(primes.size); // Output: 4
+     * ```
+     */
+    ISet.create = (iterable) => new ISetClass(iterable);
+    /**
+     * Checks if two ISet instances are structurally equal.
+     *
+     * Two ISets are considered equal if they have the same size and contain exactly the same
+     * elements. The order of elements does not matter for equality comparison since sets are
+     * unordered collections. Elements are compared using JavaScript's `===` operator.
+     *
+     * **Performance:** O(n) where n is the size of the smaller set.
+     *
+     * @template K The type of the elements.
+     * @param a The first ISet instance to compare.
+     * @param b The second ISet instance to compare.
+     * @returns `true` if the sets contain exactly the same elements, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * // Basic equality comparison
+     * const permissions1 = ISet.create(["read", "write", "execute"]);
+     * const permissions2 = ISet.create(["execute", "read", "write"]); // Order doesn't matter
+     * const permissions3 = ISet.create(["read", "write"]);
+     *
+     * console.log(ISet.equal(permissions1, permissions2)); // true
+     * console.log(ISet.equal(permissions1, permissions3)); // false (different sizes)
+     *
+     * // With different element types
+     * const numbers1 = ISet.create([1, 2, 3]);
+     * const numbers2 = ISet.create([3, 1, 2]);
+     * const numbers3 = ISet.create([1, 2, 4]); // Different element
+     *
+     * console.log(ISet.equal(numbers1, numbers2)); // true
+     * console.log(ISet.equal(numbers1, numbers3)); // false
+     *
+     * // Empty sets
+     * const empty1 = ISet.create<string>([]);
+     * const empty2 = ISet.create<string>([]);
+     * console.log(ISet.equal(empty1, empty2)); // true
+     *
+     * // Single element sets
+     * const single1 = ISet.create(["unique"]);
+     * const single2 = ISet.create(["unique"]);
+     * const single3 = ISet.create(["different"]);
+     *
+     * console.log(ISet.equal(single1, single2)); // true
+     * console.log(ISet.equal(single1, single3)); // false
+     * ```
+     */
+    ISet.equal = (a, b) => a.size === b.size && a.every((e) => b.has(e));
+    /**
+     * Computes the difference between two ISet instances, identifying added and deleted elements.
+     *
+     * This function performs a set difference operation to determine what elements were added
+     * and what elements were deleted when transitioning from the old set to the new set.
+     * This is useful for change detection, state management, and synchronization scenarios.
+     *
+     * **Performance:** O(n + m) where n and m are the sizes of the old and new sets respectively.
+     *
+     * @template K The type of the elements.
+     * @param oldSet The original set representing the previous state.
+     * @param newSet The new set representing the current state.
+     * @returns An object with `added` and `deleted` properties, each containing an ISet
+     *          of elements that were added or removed respectively.
+     *
+     * @example
+     * ```typescript
+     * // User permission changes
+     * const oldPermissions = ISet.create(["read", "write", "delete"]);
+     * const newPermissions = ISet.create(["read", "write", "execute", "admin"]);
+     *
+     * const permissionDiff = ISet.diff(oldPermissions, newPermissions);
+     *
+     * console.log("Permissions removed:", permissionDiff.deleted.toArray());
+     * // Output: ["delete"]
+     *
+     * console.log("Permissions added:", permissionDiff.added.toArray());
+     * // Output: ["execute", "admin"]
+     *
+     * // No changes
+     * const unchanged1 = ISet.create(["a", "b", "c"]);
+     * const unchanged2 = ISet.create(["a", "b", "c"]);
+     * const noDiff = ISet.diff(unchanged1, unchanged2);
+     *
+     * console.log(noDiff.added.isEmpty);   // true
+     * console.log(noDiff.deleted.isEmpty); // true
+     *
+     * // Complete replacement
+     * const oldTags = ISet.create(["javascript", "react"]);
+     * const newTags = ISet.create(["typescript", "vue"]);
+     * const tagDiff = ISet.diff(oldTags, newTags);
+     *
+     * console.log(tagDiff.deleted.toArray()); // ["javascript", "react"]
+     * console.log(tagDiff.added.toArray());   // ["typescript", "vue"]
+     * ```
+     */
+    ISet.diff = (oldSet, newSet) => ({
+        deleted: oldSet.subtract(newSet),
+        added: newSet.subtract(oldSet),
+    });
+    /**
+     * Computes the intersection of two ISet instances.
+     *
+     * Returns a new set containing only the elements that are present in both input sets.
+     * This operation is commutative: `intersection(a, b) === intersection(b, a)`.
+     *
+     * **Performance:** O(min(n, m)) where n and m are the sizes of the input sets.
+     *
+     * @template K The type of the elements.
+     * @param a The first set.
+     * @param b The second set.
+     * @returns A new ISet instance containing elements common to both sets.
+     *
+     * @example
+     * ```typescript
+     * // Finding common permissions between user and role
+     * const userPermissions = ISet.create(["read", "write", "delete", "admin"]);
+     * const rolePermissions = ISet.create(["read", "write", "execute"]);
+     *
+     * const commonPermissions = ISet.intersection(userPermissions, rolePermissions);
+     * console.log(commonPermissions.toArray()); // ["read", "write"]
+     *
+     * // No common elements
+     * const setA = ISet.create([1, 2, 3]);
+     * const setB = ISet.create([4, 5, 6]);
+     * const noCommon = ISet.intersection(setA, setB);
+     * console.log(noCommon.isEmpty); // true
+     *
+     * // Complete overlap
+     * const identical1 = ISet.create(["a", "b", "c"]);
+     * const identical2 = ISet.create(["a", "b", "c"]);
+     * const completeOverlap = ISet.intersection(identical1, identical2);
+     * console.log(ISet.equal(completeOverlap, identical1)); // true
+     *
+     * // Intersection with empty set
+     * const nonEmpty = ISet.create([1, 2, 3]);
+     * const empty = ISet.create<number>([]);
+     * const withEmpty = ISet.intersection(nonEmpty, empty);
+     * console.log(withEmpty.isEmpty); // true
+     * ```
+     */
+    ISet.intersection = (a, b) => a.intersect(b);
+    /**
+     * Computes the union of two ISet instances.
+     *
+     * Returns a new set containing all elements that are present in either input set.
+     * Duplicate elements are automatically handled since sets only contain unique values.
+     * This operation is commutative: `union(a, b) === union(b, a)`.
+     *
+     * **Performance:** O(n + m) where n and m are the sizes of the input sets.
+     *
+     * @template K1 The type of elements in the first set.
+     * @template K2 The type of elements in the second set.
+     * @param a The first set.
+     * @param b The second set.
+     * @returns A new ISet instance containing all elements from both sets.
+     *
+     * @example
+     * ```typescript
+     * // Combining permissions from multiple sources
+     * const userPermissions = ISet.create(["read", "write"]);
+     * const rolePermissions = ISet.create(["write", "execute", "admin"]);
+     *
+     * const allPermissions = ISet.union(userPermissions, rolePermissions);
+     * console.log(allPermissions.toArray().sort());
+     * // Output: ["admin", "execute", "read", "write"]
+     *
+     * // Union with different types (type widening)
+     * const numbers = ISet.create([1, 2, 3]);
+     * const strings = ISet.create(["a", "b"]);
+     * const mixed = ISet.union(numbers, strings); // ISet<number | string>
+     * console.log(mixed.size); // 5
+     *
+     * // Union with empty set
+     * const nonEmpty = ISet.create(["item1", "item2"]);
+     * const empty = ISet.create<string>([]);
+     * const withEmpty = ISet.union(nonEmpty, empty);
+     * console.log(ISet.equal(withEmpty, nonEmpty)); // true
+     *
+     * // Overlapping sets
+     * const featuresA = ISet.create(["feature1", "feature2", "feature3"]);
+     * const featuresB = ISet.create(["feature2", "feature3", "feature4"]);
+     * const allFeatures = ISet.union(featuresA, featuresB);
+     * console.log(allFeatures.size); // 4 (duplicates removed)
+     * ```
+     */
+    ISet.union = (a, b) => a.union(b);
+})(ISet || (ISet = {}));
+/**
+ * Internal class implementation for ISet providing immutable set operations.
+ *
+ * This class implements the ISet interface using JavaScript's native Set as the underlying
+ * storage mechanism for optimal performance. All mutation operations create new instances
+ * rather than modifying the existing set, ensuring immutability.
+ *
+ * **Implementation Details:**
+ * - Uses ReadonlySet<K> internally for type safety and performance
+ * - Implements copy-on-write semantics for efficiency
+ * - Provides optional debug messaging for development
+ *
+ * @template K The type of the elements. Must extend MapSetKeyType.
+ * @implements ISet
+ * @implements Iterable
+ * @internal This class should not be used directly. Use ISet.create() instead.
+ */
+class ISetClass {
+    #set;
+    #showNotFoundMessage;
+    /**
+     * Constructs an ISetClass instance with the given elements.
+     *
+     * @param iterable An iterable of elements to populate the set.
+     * @param showNotFoundMessage Whether to log warning messages when operations
+     *                           are performed on non-existent elements. Useful for debugging.
+     *                           Defaults to false for production use.
+     * @internal Use ISet.create() instead of calling this constructor directly.
+     */
+    constructor(iterable, showNotFoundMessage = false) {
+        this.#set = new Set(iterable);
+        this.#showNotFoundMessage = showNotFoundMessage;
+    }
+    /** @inheritdoc */
+    get size() {
+        return asUint32(this.#set.size);
+    }
+    /** @inheritdoc */
+    get isEmpty() {
+        return this.size === 0;
+    }
+    /** @inheritdoc */
+    has(key) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        return this.#set.has(key);
+    }
+    /** @inheritdoc */
+    every(predicate) {
+        for (const key of this.values()) {
+            if (!predicate(key))
+                return false;
+        }
+        return true;
+    }
+    /** @inheritdoc */
+    some(predicate) {
+        for (const key of this.values()) {
+            if (predicate(key))
+                return true;
+        }
+        return false;
+    }
+    /** @inheritdoc */
+    add(key) {
+        if (this.has(key))
+            return this;
+        return ISet.create([...this.#set, key]);
+    }
+    /** @inheritdoc */
+    delete(key) {
+        if (!this.has(key)) {
+            if (this.#showNotFoundMessage) {
+                const keyStr = unknownToString(key);
+                console.warn(`ISet.delete: key not found: ${Result.isOk(keyStr) ? keyStr.value : '<error converting key to string>'}`);
+            }
+            return this;
+        }
+        return ISet.create(Array.from(this.#set).filter((k) => !Object.is(k, key)));
+    }
+    /** @inheritdoc */
+    withMutations(actions) {
+        const mut_result = new Set(this.#set);
+        for (const action of actions) {
+            switch (action.type) {
+                case 'delete':
+                    mut_result.delete(action.key);
+                    break;
+                case 'add':
+                    mut_result.add(action.key);
+                    break;
+            }
+        }
+        return ISet.create(mut_result);
+    }
+    /** @inheritdoc */
+    map(mapFn) {
+        return ISet.create(this.toArray().map(mapFn));
+    }
+    /** @inheritdoc */
+    filter(predicate) {
+        return ISet.create(this.toArray().filter(predicate));
+    }
+    /** @inheritdoc */
+    filterNot(predicate) {
+        return ISet.create(this.toArray().filter((e) => !predicate(e)));
+    }
+    /** @inheritdoc */
+    forEach(callbackfn) {
+        for (const v of this.#set.values()) {
+            callbackfn(v);
+        }
+    }
+    /** @inheritdoc */
+    isSubsetOf(set) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        return this.every((k) => set.has(k));
+    }
+    /** @inheritdoc */
+    isSupersetOf(set) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        return set.every((k) => this.has(k));
+    }
+    /** @inheritdoc */
+    subtract(set) {
+        return ISet.create(this.toArray().filter((k) => !set.has(k)));
+    }
+    /** @inheritdoc */
+    intersect(set) {
+        return ISet.create(this.toArray().filter((k) => set.has(k)));
+    }
+    /** @inheritdoc */
+    union(set) {
+        return ISet.create([...this, ...set]);
+    }
+    /**
+     * @inheritdoc
+     */
+    [Symbol.iterator]() {
+        return this.#set[Symbol.iterator]();
+    }
+    /** @inheritdoc */
+    keys() {
+        return this.#set.keys();
+    }
+    /** @inheritdoc */
+    values() {
+        return this.#set.values();
+    }
+    /** @inheritdoc */
+    entries() {
+        return this.#set.entries();
+    }
+    /** @inheritdoc */
+    toArray() {
+        return Array.from(this.values());
+    }
+    /** @inheritdoc */
+    toRawSet() {
+        return this.#set;
+    }
+}
+
+export { ISet };
+//# sourceMappingURL=iset.mjs.map

package/dist/collections/iset.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"iset.mjs","sources":["../../src/collections/iset.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/collections/queue.d.mts

@@ -0,0 +1,190 @@
+import { Optional } from '../functional/index.mjs';
+/**
+ * Interface for a high-performance queue with FIFO (First-In, First-Out) behavior.
+ *
+ * This interface defines a mutable queue data structure where elements are added to the back
+ * and removed from the front, maintaining the order in which they were added. The implementation
+ * uses a circular buffer for optimal performance, providing O(1) operations for both enqueue
+ * and dequeue operations.
+ *
+ * **FIFO Behavior:**
+ * - **enqueue**: Adds elements to the back of the queue
+ * - **dequeue**: Removes and returns elements from the front of the queue
+ * - Elements are processed in the exact order they were added
+ *
+ * **Performance Characteristics:**
+ * - enqueue: O(1) amortized (O(n) when buffer needs resizing)
+ * - dequeue: O(1) always
+ * - size/isEmpty: O(1) always
+ * - Memory efficient with automatic garbage collection of removed elements
+ *
+ * **Use Cases:**
+ * - Task scheduling and job queues
+ * - Breadth-first search algorithms
+ * - Event processing systems
+ * - Producer-consumer patterns
+ * - Buffer management for streaming data
+ *
+ * @template T The type of elements stored in the queue.
+ *
+ * @example
+ * ```typescript
+ * import { createQueue, Queue } from './queue';
+ *
+ * // Example 1: Basic FIFO operations
+ * const messageQueue: Queue<string> = createQueue<string>();
+ *
+ * messageQueue.enqueue("first message");   // Add to back
+ * messageQueue.enqueue("second message");  // Add to back
+ * messageQueue.enqueue("third message");   // Add to back
+ *
+ * console.log(messageQueue.size); // Output: 3
+ *
+ * // Process messages in FIFO order
+ * console.log(messageQueue.dequeue().unwrap()); // "first message" (first in, first out)
+ * console.log(messageQueue.dequeue().unwrap()); // "second message"
+ * console.log(messageQueue.size); // Output: 1
+ *
+ * // Example 2: Task processing system
+ * type Task = { id: number; priority: string; action: () => void };
+ * const taskQueue: Queue<Task> = createQueue<Task>();
+ *
+ * taskQueue.enqueue({ id: 1, priority: "high", action: () => console.log("Task 1") });
+ * taskQueue.enqueue({ id: 2, priority: "low", action: () => console.log("Task 2") });
+ *
+ * // Process tasks in order
+ * while (!taskQueue.isEmpty) {
+ *   const task = taskQueue.dequeue().unwrap();
+ *   console.log(`Processing task ${task.id} with ${task.priority} priority`);
+ *   task.action();
+ * }
+ * ```
+ */
+export type Queue<T> = Readonly<{
+    /** Checks if the queue is empty. */
+    isEmpty: boolean;
+    /** The number of elements in the queue. */
+    size: SizeType.Arr;
+    /**
+     * Removes and returns the element at the front of the queue.
+     * @returns The element at the front of the queue, or `Optional.none` if the queue is empty.
+     */
+    dequeue: () => Optional<T>;
+    /**
+     * Adds an element to the back of the queue.
+     * @param value The element to add.
+     */
+    enqueue: (value: T) => void;
+}>;
+/**
+ * Creates a new Queue instance with FIFO (First-In, First-Out) behavior using a high-performance circular buffer.
+ *
+ * This factory function creates an optimized queue implementation that maintains excellent performance
+ * characteristics for both enqueue and dequeue operations. The underlying circular buffer automatically
+ * resizes to accommodate growing workloads while providing predictable O(1) operations.
+ *
+ * **Implementation Features:**
+ * - **O(1) enqueue operations** (amortized - occasionally O(n) when resizing)
+ * - **O(1) dequeue operations** (always)
+ * - **Automatic buffer resizing** - starts at 8 elements, doubles when full
+ * - **Memory efficient** - garbage collects removed elements immediately
+ * - **Circular buffer design** - eliminates need for array shifting operations
+ *
+ * **Performance Benefits:**
+ * - No array copying during normal operations
+ * - Minimal memory allocation overhead
+ * - Predictable performance under high load
+ * - Efficient memory usage with automatic cleanup
+ *
+ * @template T The type of elements stored in the queue.
+ * @param initialValues Optional array of initial elements to populate the queue.
+ *                      Elements will be dequeued in the same order they appear in the array.
+ *                      If provided, the initial buffer capacity will be at least twice the array length.
+ * @returns A new Queue instance optimized for high-performance FIFO operations.
+ *
+ * @example
+ * ```typescript
+ * import { createQueue } from './queue';
+ *
+ * // Example 1: Basic FIFO workflow
+ * const requestQueue = createQueue<string>();
+ *
+ * // Add requests to the queue
+ * requestQueue.enqueue("GET /api/users");     // O(1)
+ * requestQueue.enqueue("POST /api/orders");   // O(1)
+ * requestQueue.enqueue("DELETE /api/cache");  // O(1)
+ *
+ * // Process requests in order
+ * while (!requestQueue.isEmpty) {
+ *   const request = requestQueue.dequeue().unwrap(); // O(1)
+ *   console.log(`Processing: ${request}`);
+ * }
+ * // Output:
+ * // Processing: GET /api/users
+ * // Processing: POST /api/orders
+ * // Processing: DELETE /api/cache
+ *
+ * // Example 2: High-throughput event processing
+ * type Event = { timestamp: number; type: string; data: any };
+ * const eventQueue = createQueue<Event>();
+ *
+ * // Simulate high-volume event ingestion
+ * for (let i = 0; i < 10000; i++) {
+ *   eventQueue.enqueue({
+ *     timestamp: Date.now(),
+ *     type: `event-${i % 5}`,
+ *     data: { value: i }
+ *   }); // Each enqueue is O(1) amortized
+ * }
+ *
+ * // Process events efficiently
+ * let processedCount = 0;
+ * while (!eventQueue.isEmpty) {
+ *   const event = eventQueue.dequeue().unwrap(); // O(1)
+ *   // Process event...
+ *   processedCount++;
+ * }
+ * console.log(`Processed ${processedCount} events`); // 10000
+ *
+ * // Example 3: Queue with pre-populated data
+ * const priorityTasks = createQueue<string>([
+ *   "Initialize system",
+ *   "Load configuration",
+ *   "Start services",
+ *   "Begin processing"
+ * ]);
+ *
+ * console.log(priorityTasks.size); // Output: 4
+ *
+ * // Execute tasks in initialization order
+ * while (!priorityTasks.isEmpty) {
+ *   const task = priorityTasks.dequeue().unwrap();
+ *   console.log(`Executing: ${task}`);
+ * }
+ *
+ * // Example 4: Producer-Consumer pattern
+ * const workQueue = createQueue<() => Promise<void>>();
+ *
+ * // Producer: Add work items
+ * const addWork = (workFn: () => Promise<void>) => {
+ *   workQueue.enqueue(workFn);
+ * };
+ *
+ * // Consumer: Process work items
+ * const processWork = async () => {
+ *   while (!workQueue.isEmpty) {
+ *     const workItem = workQueue.dequeue().unwrap();
+ *     await workItem();
+ *   }
+ * };
+ *
+ * // Add some work
+ * addWork(async () => console.log("Work item 1"));
+ * addWork(async () => console.log("Work item 2"));
+ *
+ * // Process the work
+ * await processWork();
+ * ```
+ */
+export declare const createQueue: <T>(initialValues?: readonly T[]) => Queue<T>;
+//# sourceMappingURL=queue.d.mts.map

package/dist/collections/queue.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.mts","sourceRoot":"","sources":["../../src/collections/queue.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC9B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IAEjB,2CAA2C;IAC3C,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC;IAEnB;;;OAGG;IACH,OAAO,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE3B;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B,CAAC,CAAC;AAkMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAG,gBAAgB,SAAS,CAAC,EAAE,KAAG,KAAK,CAAC,CAAC,CACpC,CAAC"}