@uwdata/mosaic-core 0.17.0 → 0.18.0

package/LICENSE

@@ -0,0 +1,47 @@
+BSD 3-Clause License
+
+Copyright (c) 2023-2025, UW Interactive Data Lab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+Portions of this software are derived from Observable Plot, which is released
+under the ISC license.
+
+Copyright 2020-2023 Observable, Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -4,4 +4,3 @@
 
 The core Mosaic components: a central coordinator, parameters (`Param`) and selections (`Selection`) for linking scalar values or query predicates (respectively) across Mosaic clients, and filter groups with materialized views of pre-aggregated data. The Mosaic coordinator can send queries either over the network to a backing server (`socket` and `rest` clients) or to a client-side [DuckDB-WASM](https://github.com/duckdb/duckdb-wasm) instance (`wasm` client).
 
-The `mosaic-core` facilities are included as part of the [vgplot](https://github.com/uwdata/mosaic/tree/main/packages/vgplot) API.

package/dist/src/Coordinator.d.ts

@@ -0,0 +1,147 @@
+import { type Connector } from './connectors/Connector.js';
+import { PreAggregator, type PreAggregateOptions } from './preagg/PreAggregator.js';
+import { QueryManager } from './QueryManager.js';
+import { type Selection } from './Selection.js';
+import { type Logger, type QueryType } from './types.js';
+import { type QueryResult } from './util/query-result.js';
+import { type MosaicClient } from './MosaicClient.js';
+import { MaybeArray } from '@uwdata/mosaic-sql';
+interface FilterGroupEntry {
+    selection: Selection;
+    clients: Set<MosaicClient>;
+    disconnect(): void;
+}
+/**
+ * Set or retrieve the coordinator instance.
+ * @param instance The coordinator instance to set
+ * @returns The coordinator instance
+ */
+export declare function coordinator(instance?: Coordinator): Coordinator;
+/**
+ * A Mosaic Coordinator manages all database communication for clients and
+ * handles selection updates. The Coordinator also performs optimizations
+ * including query caching, consolidation, and pre-aggregation.
+ */
+export declare class Coordinator {
+    manager: QueryManager;
+    preaggregator: PreAggregator;
+    clients: Set<MosaicClient>;
+    filterGroups: Map<Selection, FilterGroupEntry>;
+    protected _logger: Logger;
+    /**
+     * @param db Database connector. Defaults to a web socket connection.
+     * @param options Coordinator options.
+     * @param options.logger The logger to use, defaults to `console`.
+     * @param options.manager The query manager to use.
+     * @param options.cache Boolean flag to enable/disable query caching.
+     * @param options.consolidate Boolean flag to enable/disable query consolidation.
+     * @param options.preagg Options for the Pre-aggregator.
+     */
+    constructor(db?: Connector, options?: {
+        logger?: Logger | null;
+        manager?: QueryManager;
+        cache?: boolean;
+        consolidate?: boolean;
+        preagg?: PreAggregateOptions;
+    });
+    /**
+     * Clear the coordinator state.
+     * @param options Options object.
+     * @param options.clients If true, disconnect all clients.
+     * @param options.cache If true, clear the query cache.
+     */
+    clear(options?: {
+        clients?: boolean;
+        cache?: boolean;
+    }): void;
+    /**
+     * Get or set the database connector.
+     * @param db The database connector to use.
+     * @returns The current database connector.
+     */
+    databaseConnector(): Connector | null;
+    databaseConnector(db: Connector): Connector;
+    /**
+     * Get or set the logger.
+     * @param logger The logger to use.
+     * @returns The current logger
+     */
+    logger(logger?: Logger | null): Logger;
+    /**
+     * Cancel previously submitted query requests. These queries will be
+     * canceled if they are queued but have not yet been submitted.
+     * @param requests An array of query result objects, such as those returned by the `query` method.
+     */
+    cancel(requests: QueryResult[]): void;
+    /**
+     * Issue a query for which no result (return value) is needed.
+     * @param query The query or an array of queries. Each query should be either a Query builder object or a SQL string.
+     * @param options An options object.
+     * @param options.priority The query priority, defaults to `Priority.Normal`.
+     * @returns A query result promise.
+     */
+    exec(query: MaybeArray<QueryType>, options?: {
+        priority?: number;
+    }): QueryResult;
+    /**
+     * Issue a query to the backing database. The submitted query may be
+     * consolidate with other queries and its results may be cached.
+     * @param query The query as either a Query builder object or a SQL string.
+     * @param options An options object.
+     * @param options.type The query result format type.
+     * @param options.cache If true, cache the query result client-side within the QueryManager.
+     * @param options.persist If true, request the database server to persist a cached query server-side.
+     * @param options.priority The query priority, defaults to `Priority.Normal`.
+     * @returns A query result promise.
+     */
+    query(query: QueryType, options?: {
+        type?: 'arrow' | 'json';
+        cache?: boolean;
+        persist?: boolean;
+        priority?: number;
+        [key: string]: unknown;
+    }): QueryResult;
+    /**
+     * Issue a query to prefetch data for later use. The query result is cached
+     * for efficient future access.
+     * @param query The query as either a Query builder object or a SQL string.
+     * @param options An options object.
+     * @param options.type The query result format type.
+     * @returns A query result promise.
+     */
+    prefetch(query: QueryType, options?: {
+        type?: 'arrow' | 'json';
+        [key: string]: unknown;
+    }): QueryResult;
+    /**
+     * Update client data by submitting the given query and returning the()
+     * data (or error) to the client.
+     * @param client A Mosaic client.
+     * @param query The data query.
+     * @param priority The query priority.
+     * @returns A Promise that resolves upon completion of the update.
+     */
+    updateClient(client: MosaicClient, query: QueryType, priority?: number): Promise<unknown>;
+    /**
+     * Issue a query request for a client. If the query is null or undefined,
+     * the client is simply updated. Otherwise `updateClient` is called. As a
+     * side effect, this method clears the current preaggregator state.
+     * @param client The client to update.
+     * @param query The query to issue.
+     */
+    requestQuery(client: MosaicClient, query?: QueryType | null): Promise<unknown>;
+    /**
+     * Connect a client to the coordinator.
+     * Throws an error if the client is already connected.
+     * @param client The Mosaic client to connect.
+     */
+    connect(client: MosaicClient): void;
+    /**
+     * Disconnect a client from the coordinator.
+     * This method has no effect if the client is already disconnected.
+     * @param client The Mosaic client to disconnect.
+     */
+    disconnect(client: MosaicClient): void;
+}
+export {};
+//# sourceMappingURL=Coordinator.d.ts.map

package/dist/src/Coordinator.d.ts.map

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

package/dist/src/Coordinator.js

@@ -0,0 +1,269 @@
+import { SocketConnector } from './connectors/socket.js';
+import { PreAggregator } from './preagg/PreAggregator.js';
+import { voidLogger } from './util/void-logger.js';
+import { QueryManager, Priority } from './QueryManager.js';
+/**
+ * The singleton Coordinator instance.
+ */
+let _instance;
+/**
+ * Set or retrieve the coordinator instance.
+ * @param instance The coordinator instance to set
+ * @returns The coordinator instance
+ */
+export function coordinator(instance) {
+    if (instance) {
+        _instance = instance;
+    }
+    else if (_instance == null) {
+        _instance = new Coordinator();
+    }
+    return _instance;
+}
+/**
+ * A Mosaic Coordinator manages all database communication for clients and
+ * handles selection updates. The Coordinator also performs optimizations
+ * including query caching, consolidation, and pre-aggregation.
+ */
+export class Coordinator {
+    manager;
+    preaggregator;
+    clients = new Set;
+    filterGroups = new Map;
+    _logger = voidLogger();
+    /**
+     * @param db Database connector. Defaults to a web socket connection.
+     * @param options Coordinator options.
+     * @param options.logger The logger to use, defaults to `console`.
+     * @param options.manager The query manager to use.
+     * @param options.cache Boolean flag to enable/disable query caching.
+     * @param options.consolidate Boolean flag to enable/disable query consolidation.
+     * @param options.preagg Options for the Pre-aggregator.
+     */
+    constructor(db = new SocketConnector(), options = {}) {
+        const { logger = console, manager = new QueryManager(), cache = true, consolidate = true, preagg = {} } = options;
+        this.manager = manager;
+        this.manager.cache(cache);
+        this.manager.consolidate(consolidate);
+        this.databaseConnector(db);
+        this.logger(logger);
+        this.clear();
+        this.preaggregator = new PreAggregator(this, preagg);
+    }
+    /**
+     * Clear the coordinator state.
+     * @param options Options object.
+     * @param options.clients If true, disconnect all clients.
+     * @param options.cache If true, clear the query cache.
+     */
+    clear(options = {}) {
+        const { clients = true, cache = true } = options;
+        this.manager.clear();
+        if (clients) {
+            this.filterGroups?.forEach(group => group.disconnect());
+            this.filterGroups = new Map;
+            this.clients?.forEach(client => this.disconnect(client));
+            this.clients = new Set;
+        }
+        if (cache)
+            this.manager.cache().clear();
+    }
+    databaseConnector(db) {
+        return db
+            ? this.manager.connector(db)
+            : this.manager.connector();
+    }
+    /**
+     * Get or set the logger.
+     * @param logger The logger to use.
+     * @returns The current logger
+     */
+    logger(logger) {
+        if (arguments.length) {
+            this._logger = logger || voidLogger();
+            this.manager.logger(this._logger);
+        }
+        return this._logger;
+    }
+    // -- Query Management ----
+    /**
+     * Cancel previously submitted query requests. These queries will be
+     * canceled if they are queued but have not yet been submitted.
+     * @param requests An array of query result objects, such as those returned by the `query` method.
+     */
+    cancel(requests) {
+        this.manager.cancel(requests);
+    }
+    /**
+     * Issue a query for which no result (return value) is needed.
+     * @param query The query or an array of queries. Each query should be either a Query builder object or a SQL string.
+     * @param options An options object.
+     * @param options.priority The query priority, defaults to `Priority.Normal`.
+     * @returns A query result promise.
+     */
+    exec(query, options = {}) {
+        const { priority = Priority.Normal } = options;
+        query = Array.isArray(query) ? query.filter(x => x).join(';\n') : query;
+        return this.manager.request({ type: 'exec', query }, priority);
+    }
+    /**
+     * Issue a query to the backing database. The submitted query may be
+     * consolidate with other queries and its results may be cached.
+     * @param query The query as either a Query builder object or a SQL string.
+     * @param options An options object.
+     * @param options.type The query result format type.
+     * @param options.cache If true, cache the query result client-side within the QueryManager.
+     * @param options.persist If true, request the database server to persist a cached query server-side.
+     * @param options.priority The query priority, defaults to `Priority.Normal`.
+     * @returns A query result promise.
+     */
+    query(query, options = {}) {
+        const { type = 'arrow', cache = true, priority = Priority.Normal, ...otherOptions } = options;
+        return this.manager.request({ type, query, cache, options: otherOptions }, priority);
+    }
+    /**
+     * Issue a query to prefetch data for later use. The query result is cached
+     * for efficient future access.
+     * @param query The query as either a Query builder object or a SQL string.
+     * @param options An options object.
+     * @param options.type The query result format type.
+     * @returns A query result promise.
+     */
+    prefetch(query, options = {}) {
+        return this.query(query, { ...options, cache: true, priority: Priority.Low });
+    }
+    // -- Client Management ----
+    /**
+     * Update client data by submitting the given query and returning the()
+     * data (or error) to the client.
+     * @param client A Mosaic client.
+     * @param query The data query.
+     * @param priority The query priority.
+     * @returns A Promise that resolves upon completion of the update.
+     */
+    updateClient(client, query, priority = Priority.Normal) {
+        client.queryPending();
+        return client._pending = this.query(query, { priority })
+            .then(data => client.queryResult(data).update(), err => { this._logger?.error(err); client.queryError(err); })
+            .catch(err => this._logger?.error(err));
+    }
+    /**
+     * Issue a query request for a client. If the query is null or undefined,
+     * the client is simply updated. Otherwise `updateClient` is called. As a
+     * side effect, this method clears the current preaggregator state.
+     * @param client The client to update.
+     * @param query The query to issue.
+     */
+    requestQuery(client, query) {
+        this.preaggregator.clear();
+        return query
+            ? this.updateClient(client, query)
+            : Promise.resolve(client.update());
+    }
+    /**
+     * Connect a client to the coordinator.
+     * Throws an error if the client is already connected.
+     * @param client The Mosaic client to connect.
+     */
+    connect(client) {
+        const { clients } = this;
+        if (clients?.has(client)) {
+            throw new Error('Client already connected.');
+        }
+        // add client to client set
+        clients?.add(client);
+        // register coordinator on client instance
+        client.coordinator = this;
+        // initialize client lifecycle
+        client.initialize();
+        // connect filter selection
+        connectSelection(this, client.filterBy, client);
+    }
+    /**
+     * Disconnect a client from the coordinator.
+     * This method has no effect if the client is already disconnected.
+     * @param client The Mosaic client to disconnect.
+     */
+    disconnect(client) {
+        const { clients, filterGroups } = this;
+        if (!clients?.has(client))
+            return;
+        clients.delete(client);
+        client.coordinator = null;
+        const group = filterGroups?.get(client.filterBy);
+        if (group) {
+            group.clients.delete(client);
+        }
+    }
+}
+/**
+ * Connect a selection-client pair to the coordinator to process updates.
+ * @param mc The Mosaic coordinator.
+ * @param selection A selection.
+ * @param client A Mosaic client that is filtered by the given selection.
+ */
+function connectSelection(mc, selection, client) {
+    if (!selection)
+        return;
+    let entry = mc.filterGroups?.get(selection);
+    if (!entry) {
+        const activate = (clause) => activateSelection(mc, selection, clause);
+        const value = () => updateSelection(mc, selection);
+        // @ts-expect-error todo: update selection dispatch types
+        selection.addEventListener('activate', activate);
+        selection.addEventListener('value', value);
+        entry = {
+            selection,
+            clients: new Set,
+            disconnect() {
+                // @ts-expect-error todo: update selection dispatch types
+                selection.removeEventListener('activate', activate);
+                selection.removeEventListener('value', value);
+            }
+        };
+        mc.filterGroups?.set(selection, entry);
+    }
+    entry.clients.add(client);
+}
+/**
+ * Activate a selection, providing a clause indicative of potential
+ * next updates. Activation provides a preview of likely next events,
+ * enabling potential precomputation to optimize updates.
+ * @param mc The Mosaic coordinator.
+ * @param selection A selection.
+ * @param clause A selection clause for the activation.
+ */
+function activateSelection(mc, selection, clause) {
+    const { preaggregator, filterGroups } = mc;
+    const { clients } = filterGroups.get(selection);
+    for (const client of clients) {
+        if (client.enabled) {
+            preaggregator.request(client, selection, clause);
+        }
+    }
+}
+/**
+ * Process an updated selection value, querying filtered data for any
+ * associated clients.
+ * @param mc The Mosaic coordinator.
+ * @param selection A selection.
+ * @returns A Promise that resolves when the update completes.
+ */
+function updateSelection(mc, selection) {
+    const { preaggregator, filterGroups } = mc;
+    const { clients } = filterGroups.get(selection);
+    const { active } = selection;
+    return Promise.allSettled(Array.from(clients, (client) => {
+        if (!client.enabled)
+            return client.requestQuery();
+        const info = preaggregator.request(client, selection, active);
+        const filter = info ? null : selection.predicate(client);
+        // skip due to cross-filtering
+        if (info?.skip || (!info && !filter))
+            return;
+        // @ts-expect-error FIXME
+        const query = info?.query(active.predicate) ?? client.query(filter);
+        return mc.updateClient(client, query);
+    }));
+}
+//# sourceMappingURL=Coordinator.js.map

package/dist/src/Coordinator.js.map

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

package/dist/src/MosaicClient.d.ts

@@ -0,0 +1,138 @@
+import { FilterExpr, type Query } from '@uwdata/mosaic-sql';
+import { type Coordinator } from './Coordinator.js';
+import { type Selection } from './Selection.js';
+export type ClientQuery = Query | string | null;
+export declare function isMosaicClient(x: unknown): x is MosaicClient;
+/**
+ * A Mosaic client is a data consumer that indicates its data needs to a
+ * Mosaic coordinator via the query method. The coordinator is responsible
+ * for issuing queries and returning results to the client.
+ *
+ * The client life-cycle consists of connection to a coordinator,
+ * initialization (potentially involving queries for data schema and summary
+ * statistic information), and then interactive queries that may be driven by
+ * an associated selection. When no longer needed, a client should be
+ * disconnected from the coordinator.
+ *
+ * When enabled, a client will initialize and respond to query update requests.
+ * If disabled, the client will delay initialization and not respond to queries
+ * until enabled again. Disabling a client can improve system performance when
+ * associated interface elements are offscreen or disabled.
+ */
+export declare class MosaicClient {
+    _filterBy: Selection | undefined;
+    _requestUpdate: () => void;
+    _coordinator: Coordinator | null;
+    _pending: Promise<unknown>;
+    _enabled: boolean;
+    _initialized: boolean;
+    _request: Query | boolean | null;
+    /**
+     * Create a new client instance.
+     * @param filterSelection An optional selection to
+     *  interactively filter this client's data. If provided, a coordinator
+     *  will re-query and update the client when the selection updates.
+     */
+    constructor(filterSelection?: Selection);
+    /**
+     * @returns this client's connected coordinator.
+     */
+    get coordinator(): Coordinator | null;
+    /**
+     * Set this client's connected coordinator.
+     */
+    set coordinator(coordinator: Coordinator | null);
+    /**
+     * Return this client's enabled state.
+     */
+    get enabled(): boolean;
+    /**
+     * Set this client's enabled state;
+     */
+    set enabled(state: boolean);
+    /**
+     * Return a Promise that resolves once the client has updated.
+     */
+    get pending(): Promise<unknown>;
+    /**
+     * @returns this client's filter selection.
+     */
+    get filterBy(): Selection | undefined;
+    /**
+     * Return a boolean indicating if the client query can be sped up with
+     * materialized views of pre-aggregated data. Should return true if changes
+     * to the filterBy selection do not change the groupby domain of the client
+     * query.
+     */
+    get filterStable(): boolean;
+    /**
+     * Prepare the client before the `query()` method is called. Subclasses
+     * should override this method as needed, potentially issuing one or more
+     * queries to gather data or metadata needed prior to `query` calls.
+     */
+    prepare(): Promise<void>;
+    /**
+     * Return a query specifying the data needed by this client.
+     * @param filter The filtering criteria to apply in the query.
+     * @returns The client query
+     */
+    query(filter?: FilterExpr | null): ClientQuery;
+    /**
+     * Called by the coordinator to inform the client that a query is pending.
+     * @returns this
+     */
+    queryPending(): this;
+    /**
+     * Called by the coordinator to return a query result.
+     * @param data The query result.
+     * @returns this
+     */
+    queryResult(data: unknown): this;
+    /**
+     * Called by the coordinator to report a query execution error.
+     * @param error
+     * @returns this
+     */
+    queryError(error: Error): this;
+    /**
+     * Request the coordinator to execute a query for this client.
+     * If an explicit query is not provided, the client `query` method will
+     * be called, filtered by the current `filterBy` selection. This method has
+     * no effect if the client is not connected to a coordinator. If the client
+     * is connected by currently disabled, the request will be serviced if the
+     * client is later enabled.
+     * @param query The query to request. If unspecified, the query
+     *  will be determined by the client's `query` method and the current
+     *  `filterBy` selection state.
+     */
+    requestQuery(query?: Query): Promise<unknown> | null;
+    /**
+     * Request that the coordinator perform a throttled update of this client
+     * using the default query. Unlike requestQuery, for which every call results
+     * in an executed query, multiple calls to requestUpdate may be consolidated
+     * into a single update. This method has no effect if the client is not
+     * connected to a coordinator. If the client is connected but currently
+     * disabled, the request will be serviced if the client is later enabled.
+     */
+    requestUpdate(): void;
+    /**
+     * Reset this client, calling the prepare method and query requests. This
+     * method has no effect if the client is not registered with a coordinator.
+     */
+    initialize(): void;
+    /**
+     * Remove this client: disconnect from the coordinator and free up any
+     * resource use. This method has no effect if the client is not connected
+     * to a coordinator.
+     *
+     * If overriding this method in a client subclass, be sure to also
+     * disconnect from the coordinator.
+     */
+    destroy(): void;
+    /**
+     * Requests a client update, for example to (re-)render an interface
+     * component.
+     */
+    update(): this | Promise<unknown>;
+}
+//# sourceMappingURL=MosaicClient.d.ts.map

package/dist/src/MosaicClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MosaicClient.d.ts","sourceRoot":"","sources":["../../src/MosaicClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAEhD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,YAAY,CAE5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IAEjC;;;;;OAKG;gBACS,eAAe,CAAC,EAAE,SAAS;IAUvC;;OAEG;IACH,IAAI,WAAW,IAAI,WAAW,GAAG,IAAI,CAEpC;IAED;;OAEG;IACH,IAAI,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,EAE9C;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAezB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAE9B;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,SAAS,GAAG,SAAS,CAEpC;IAED;;;;;OAKG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAG9B;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,WAAW;IAI9C;;;OAGG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAIhC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAK9B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAUpD;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI;IAQrB;;;OAGG;IACH,UAAU,IAAI,IAAI;IAWlB;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,MAAM,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;CAGlC"}