@webda/ql 4.0.0-beta.5 → 4.0.0-beta.6

package/lib/aggregation-query.d.ts

@@ -0,0 +1,95 @@
+import type { Expression } from "./query.js";
+import { WebdaQLError } from "./webdaql-string.js";
+/**
+ * Aggregation functions supported on every backend
+ */
+export type AggregateFunction = "COUNT" | "COUNT_DISTINCT" | "SUM" | "AVG" | "MIN" | "MAX";
+/**
+ * One computed column of an aggregation
+ */
+export interface Metric {
+    fn: AggregateFunction;
+    /**
+     * Dotted path of the aggregated attribute; omitted only for COUNT, meaning COUNT(*)
+     */
+    field?: string;
+}
+/**
+ * Ordering of aggregated rows
+ */
+export interface AggregationOrder {
+    /**
+     * A groupBy path or a metric alias
+     */
+    key: string;
+    direction: "ASC" | "DESC";
+}
+/**
+ * Canonical aggregation AST consumed by every store
+ */
+export interface AggregationQuery {
+    /**
+     * Filter applied before grouping; `new AndExpression([])` matches everything
+     */
+    filter: Expression;
+    /**
+     * Dotted paths; an empty array produces a single global row
+     */
+    groupBy: string[];
+    /**
+     * alias → metric
+     */
+    metrics: Record<string, Metric>;
+    orderBy?: AggregationOrder[];
+    limit?: number;
+}
+/**
+ * Result of an aggregation
+ */
+export interface AggregationResult<Row = Record<string, unknown>> {
+    rows: Row[];
+    /**
+     * false when the in-memory fallback ran, fully or partially
+     */
+    native: boolean;
+}
+/**
+ * Error codes raised by aggregations
+ */
+export type AggregationErrorCode = "AGGREGATION_NOT_NATIVE" | "AGGREGATION_TOO_MANY_GROUPS";
+/**
+ * Error raised when an aggregation is refused at runtime
+ */
+export declare class AggregationError extends WebdaQLError {
+    readonly code: AggregationErrorCode;
+    /**
+     * @param code - machine readable code
+     * @param message - human readable message
+     */
+    constructor(code: AggregationErrorCode, message: string);
+}
+/**
+ * Valid attribute path: dotted identifiers, the only form translators interpolate
+ */
+export declare const AGGREGATION_PATH: RegExp;
+/**
+ * Valid metric alias
+ */
+export declare const AGGREGATION_ALIAS: RegExp;
+/**
+ * Check a metric alias
+ * @param alias - the alias
+ * @throws WebdaQLError when invalid or reserved
+ */
+export declare function checkAlias(alias: string): void;
+/**
+ * Validate an aggregation query
+ *
+ * Paths and aliases that pass are safe to interpolate in native queries. Path segments cannot be
+ * all digits (array indexes are not portable). A missing `groupBy` is normalized to `[]`.
+ * @param query - the query to validate
+ * @returns the same query
+ * @throws WebdaQLError when the query is invalid
+ */
+export declare function validateAggregation(query: AggregationQuery): AggregationQuery;
+//# sourceMappingURL=aggregation-query.d.ts.map

package/lib/aggregation-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregation-query.d.ts","sourceRoot":"","sources":["../src/aggregation-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,gBAAgB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,iBAAiB,CAAC;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,GAAG,6BAA6B,CAAC;AAE5F;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;aAM9B,IAAI,EAAE,oBAAoB;IAL5C;;;OAGG;IACH,YACkB,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM,EAIhB;CACF;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAsC,CAAC;AACpE;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAA4B,CAAC;AAwB3D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAwC7E"}

package/lib/aggregation-query.js

@@ -0,0 +1,104 @@
+import { WebdaQLError } from "./webdaql-string.js";
+/**
+ * Error raised when an aggregation is refused at runtime
+ */
+export class AggregationError extends WebdaQLError {
+    code;
+    /**
+     * @param code - machine readable code
+     * @param message - human readable message
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AggregationError";
+    }
+}
+/**
+ * Valid attribute path: dotted identifiers, the only form translators interpolate
+ */
+export const AGGREGATION_PATH = /^[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*$/;
+/**
+ * Valid metric alias
+ */
+export const AGGREGATION_ALIAS = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+/**
+ * All-digit segment: MongoDB `$a.0` does not index arrays, so such paths would differ across backends
+ */
+const DIGITS = /^[0-9]+$/;
+const FUNCTIONS = new Set(["COUNT", "COUNT_DISTINCT", "SUM", "AVG", "MIN", "MAX"]);
+/**
+ * Check an attribute path
+ * @param path - the path
+ * @param what - description for the error
+ */
+function checkPath(path, what) {
+    if (typeof path !== "string" ||
+        !AGGREGATION_PATH.test(path) ||
+        path.split(".").some(segment => FORBIDDEN_SEGMENTS.has(segment) || DIGITS.test(segment))) {
+        throw new WebdaQLError(`Invalid ${what} '${path}'`);
+    }
+}
+/**
+ * Check a metric alias
+ * @param alias - the alias
+ * @throws WebdaQLError when invalid or reserved
+ */
+export function checkAlias(alias) {
+    if (!AGGREGATION_ALIAS.test(alias) || FORBIDDEN_SEGMENTS.has(alias)) {
+        throw new WebdaQLError(`Invalid metric alias '${alias}'`);
+    }
+}
+/**
+ * Validate an aggregation query
+ *
+ * Paths and aliases that pass are safe to interpolate in native queries. Path segments cannot be
+ * all digits (array indexes are not portable). A missing `groupBy` is normalized to `[]`.
+ * @param query - the query to validate
+ * @returns the same query
+ * @throws WebdaQLError when the query is invalid
+ */
+export function validateAggregation(query) {
+    query.groupBy ??= [];
+    const groupBy = query.groupBy;
+    groupBy.forEach(path => checkPath(path, "group by path"));
+    if (new Set(groupBy).size !== groupBy.length) {
+        throw new WebdaQLError("Duplicate group by path");
+    }
+    const aliases = Object.keys(query.metrics ?? {});
+    if (!aliases.length) {
+        throw new WebdaQLError("An aggregation needs at least one metric");
+    }
+    for (const alias of aliases) {
+        checkAlias(alias);
+        if (groupBy.includes(alias)) {
+            throw new WebdaQLError(`Metric alias '${alias}' collides with a group by path`);
+        }
+        const metric = query.metrics[alias];
+        if (!FUNCTIONS.has(metric?.fn)) {
+            throw new WebdaQLError(`Unknown aggregate function '${metric?.fn}'`);
+        }
+        if (metric.field === undefined) {
+            if (metric.fn !== "COUNT") {
+                throw new WebdaQLError(`${metric.fn} needs a field`);
+            }
+        }
+        else {
+            checkPath(metric.field, "metric field");
+        }
+    }
+    for (const order of query.orderBy ?? []) {
+        if (!groupBy.includes(order.key) && !aliases.includes(order.key)) {
+            throw new WebdaQLError(`ORDER BY '${order.key}' is neither a group by path nor a metric alias`);
+        }
+        if (order.direction !== "ASC" && order.direction !== "DESC") {
+            throw new WebdaQLError(`Invalid ORDER BY direction '${order.direction}'`);
+        }
+    }
+    if (query.limit !== undefined && !(Number.isInteger(query.limit) && query.limit > 0)) {
+        throw new WebdaQLError(`Invalid LIMIT '${query.limit}'`);
+    }
+    return query;
+}
+//# sourceMappingURL=aggregation-query.js.map

package/lib/aggregation-query.js.map

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

package/lib/aggregation-select.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=aggregation-select.spec.d.ts.map

package/lib/aggregation-select.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregation-select.spec.d.ts","sourceRoot":"","sources":["../src/aggregation-select.spec.ts"],"names":[],"mappings":""}

package/lib/aggregation-select.spec.js

@@ -0,0 +1,164 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { suite, test } from "@webda/test";
+import * as assert from "assert";
+import { toAggregationQuery } from "./aggregation.js";
+import { assertFilterQuery, normalizeQuery, parse } from "./query.js";
+/**
+ * Comparable form of an aggregation query
+ * @param query - the query
+ * @returns a plain object
+ */
+function plain(query) {
+    return { ...query, filter: query.filter.toString() };
+}
+let AggregationSelectTest = (() => {
+    let _classDecorators = [suite];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _instanceExtraInitializers = [];
+    let _roundTrip_decorators;
+    let _globalAggregation_decorators;
+    let _plainSelectUnchanged_decorators;
+    let _rejects_decorators;
+    let _reservedAliases_decorators;
+    let _allowedFields_decorators;
+    let _keywords_decorators;
+    var AggregationSelectTest = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _roundTrip_decorators = [test];
+            _globalAggregation_decorators = [test];
+            _plainSelectUnchanged_decorators = [test];
+            _rejects_decorators = [test];
+            _reservedAliases_decorators = [test];
+            _allowedFields_decorators = [test];
+            _keywords_decorators = [test];
+            __esDecorate(this, null, _roundTrip_decorators, { kind: "method", name: "roundTrip", static: false, private: false, access: { has: obj => "roundTrip" in obj, get: obj => obj.roundTrip }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _globalAggregation_decorators, { kind: "method", name: "globalAggregation", static: false, private: false, access: { has: obj => "globalAggregation" in obj, get: obj => obj.globalAggregation }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _plainSelectUnchanged_decorators, { kind: "method", name: "plainSelectUnchanged", static: false, private: false, access: { has: obj => "plainSelectUnchanged" in obj, get: obj => obj.plainSelectUnchanged }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _rejects_decorators, { kind: "method", name: "rejects", static: false, private: false, access: { has: obj => "rejects" in obj, get: obj => obj.rejects }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _reservedAliases_decorators, { kind: "method", name: "reservedAliases", static: false, private: false, access: { has: obj => "reservedAliases" in obj, get: obj => obj.reservedAliases }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _allowedFields_decorators, { kind: "method", name: "allowedFields", static: false, private: false, access: { has: obj => "allowedFields" in obj, get: obj => obj.allowedFields }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _keywords_decorators, { kind: "method", name: "keywords", static: false, private: false, access: { has: obj => "keywords" in obj, get: obj => obj.keywords }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            AggregationSelectTest = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        roundTrip() {
+            const query = parse("SELECT status, owner.uuid, COUNT(*) AS n, COUNT(tag) AS withTag, COUNT(DISTINCT tag) AS tags, " +
+                "SUM(points) AS total, AVG(points) AS mean, MIN(createdAt) AS first, MAX(points) AS top " +
+                "WHERE completed = FALSE AND owner.uuid = 'u1' GROUP BY status, owner.uuid ORDER BY n DESC, status LIMIT 10");
+            assert.strictEqual(query.type, "SELECT");
+            assert.deepStrictEqual(query.fields, ["status", "owner.uuid"]);
+            assert.deepStrictEqual(plain(query.aggregation), plain(toAggregationQuery({
+                filter: "completed = FALSE AND owner.uuid = 'u1'",
+                groupBy: ["status", "owner.uuid"],
+                metrics: {
+                    n: { count: "*" },
+                    withTag: { count: "tag" },
+                    tags: { countDistinct: "tag" },
+                    total: { sum: "points" },
+                    mean: { avg: "points" },
+                    first: { min: "createdAt" },
+                    top: { max: "points" }
+                },
+                orderBy: [
+                    { key: "n", direction: "DESC" },
+                    { key: "status", direction: "ASC" }
+                ],
+                limit: 10
+            })));
+            assert.deepStrictEqual(plain(parse(query.toString()).aggregation), plain(query.aggregation));
+        }
+        globalAggregation() {
+            const query = parse("SELECT COUNT(*) AS n");
+            assert.deepStrictEqual(query.fields, []);
+            assert.deepStrictEqual(plain(query.aggregation), {
+                filter: "",
+                groupBy: [],
+                metrics: { n: { fn: "COUNT" } },
+                orderBy: undefined,
+                limit: undefined
+            });
+            // Repository query() / iterate() refuse it like any SELECT field list
+            assert.throws(() => assertFilterQuery(query));
+            assert.deepStrictEqual(plain(parse(query.toString()).aggregation), plain(query.aggregation));
+            assert.throws(() => normalizeQuery(query), /Aggregation/);
+        }
+        plainSelectUnchanged() {
+            const query = parse("SELECT a, b WHERE a = 1");
+            assert.deepStrictEqual(query.fields, ["a", "b"]);
+            assert.strictEqual(query.aggregation, undefined);
+        }
+        rejects() {
+            for (const bad of [
+                "SELECT status, COUNT(*) AS n",
+                "SELECT COUNT(*) AS n GROUP BY status",
+                "SELECT status, owner GROUP BY status",
+                "SELECT COUNT(*)",
+                "SELECT SUM(*) AS s",
+                "SELECT COUNT(*) AS n, COUNT(a) AS n",
+                "SELECT COUNT(*) AS n OFFSET 'x'",
+                "SELECT COUNT(*) AS n ORDER BY nope",
+                "SELECT status GROUP BY status"
+            ]) {
+                assert.throws(() => parse(bad), undefined, bad);
+            }
+        }
+        reservedAliases() {
+            for (const bad of ["SELECT COUNT(*) AS n, SUM(x) AS __proto__", "SELECT SUM(x) AS __proto__"]) {
+                assert.throws(() => parse(bad), /Invalid metric alias/, bad);
+            }
+        }
+        allowedFields() {
+            assert.throws(() => parse("SELECT SUM(secret) AS s", ["points"]), /secret/);
+            assert.ok(parse("SELECT SUM(points) AS s", ["points"]).aggregation);
+        }
+        keywords() {
+            assert.strictEqual(parse("count = 1 AND min = 2").filter.toString(), "count = 1 AND min = 2", "lowercase stays an attribute");
+            assert.throws(() => parse("COUNT = 1"), undefined, "uppercase COUNT is now a keyword");
+            assert.throws(() => parse("a = 1 GROUP BY a"), undefined, "GROUP BY only in a SELECT");
+        }
+        constructor() {
+            __runInitializers(this, _instanceExtraInitializers);
+        }
+    };
+    return AggregationSelectTest = _classThis;
+})();
+//# sourceMappingURL=aggregation-select.spec.js.map

package/lib/aggregation-select.spec.js.map

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

package/lib/aggregation.d.ts

@@ -0,0 +1,97 @@
+import { type QueryParameters } from "./bind.js";
+import { type AggregationOrder, type AggregationQuery } from "./aggregation-query.js";
+export * from "./aggregation-query.js";
+/**
+ * Compare two values the way every backend orders aggregated rows
+ *
+ * null / undefined first, then numbers, strings (code unit order), booleans, then anything
+ * else by its JSON representation.
+ * @param a - first value
+ * @param b - second value
+ * @returns negative, zero or positive
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+/**
+ * Running computation of one metric
+ */
+interface Accumulator {
+    add(item: any): void;
+    result(): unknown;
+}
+/**
+ * Streaming reference implementation of an aggregation
+ *
+ * Items must already match the query filter. Memory is O(groups), plus one Set per group per
+ * COUNT_DISTINCT. It is the fallback engine of repositories and the oracle of the
+ * conformance tests.
+ */
+export declare class Aggregator {
+    protected query: AggregationQuery;
+    protected maxGroups: number;
+    protected groups: Map<string, {
+        keys: unknown[];
+        accumulators: [string, Accumulator][];
+    }>;
+    /**
+     * @param query - the aggregation; validated here
+     * @param maxGroups - throw AGGREGATION_TOO_MANY_GROUPS beyond this number of groups
+     */
+    constructor(query: AggregationQuery, maxGroups?: number);
+    /**
+     * Create an empty group
+     * @param keys - group key values
+     * @returns the group
+     */
+    protected createGroup(keys: unknown[]): {
+        keys: unknown[];
+        accumulators: [string, Accumulator][];
+    };
+    /**
+     * Add a matching item
+     * @param item - the item
+     */
+    add(item: any): void;
+    /**
+     * Compute the rows, ordered and limited
+     * @returns flat rows keyed by group path and metric alias
+     */
+    rows(): Record<string, unknown>[];
+}
+/**
+ * Ergonomic metric definition used by the object API
+ */
+export type MetricInput = {
+    count: string;
+} | {
+    countDistinct: string;
+} | {
+    sum: string;
+} | {
+    avg: string;
+} | {
+    min: string;
+} | {
+    max: string;
+};
+/**
+ * Untyped object form of an aggregation, as accepted by repositories
+ */
+export interface AggregationInput {
+    /**
+     * WebdaQL filter, without ORDER BY / LIMIT / OFFSET
+     */
+    filter?: string;
+    groupBy?: readonly string[];
+    metrics: Record<string, MetricInput>;
+    orderBy?: readonly AggregationOrder[];
+    limit?: number;
+}
+/**
+ * Convert the object form of an aggregation to the canonical AST
+ * @param input - the object form
+ * @param params - values for the `?` / `:name` placeholders of the filter
+ * @returns the validated AST
+ * @throws WebdaQLError when the input is invalid
+ */
+export declare function toAggregationQuery(input: AggregationInput, params?: QueryParameters): AggregationQuery;
+//# sourceMappingURL=aggregation.d.ts.map

package/lib/aggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregation.d.ts","sourceRoot":"","sources":["../src/aggregation.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EAItB,MAAM,wBAAwB,CAAC;AAGhC,cAAc,wBAAwB,CAAC;AAIvC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAc5D;AAED;;GAEG;AACH,UAAU,WAAW;IACnB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IACrB,MAAM,IAAI,OAAO,CAAC;CACnB;AAkFD;;;;;;GAMG;AACH,qBAAa,UAAU;IAQnB,SAAS,CAAC,KAAK,EAAE,gBAAgB;IACjC,SAAS,CAAC,SAAS,EAAE,MAAM;IAR7B,SAAS,CAAC,MAAM;cAA2B,OAAO,EAAE;sBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE;OAAM;IAEjG;;;OAGG;IACH,YACY,KAAK,EAAE,gBAAgB,EACvB,SAAS,GAAE,MAAiC,EAGvD;IAED;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE;;;MAOpC;IAED;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAcnB;IAED;;;OAGG;IACH,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAyBhC;CACF;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACrB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAExH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAWD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,gBAAgB,CA8BtG"}