@b2bc-devkit/sheetorm 0.1.0

package/dist/npm/query/Query.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Fluent query builder for composing and executing queries against SheetORM data.
+ *
+ * Provides a chainable API inspired by common ORM patterns:
+ * ```ts
+ * const cars = Query.from(Car)
+ *   .where("make", "=", "Toyota")
+ *   .or("make", "=", "Honda")
+ *   .orderBy("year", "desc")
+ *   .limit(10)
+ *   .execute();
+ * ```
+ *
+ * Filter logic:
+ *   - `.where()` / `.and()` add filters to the current AND-group.
+ *   - `.or()` creates a new AND-group (groups are combined with OR logic).
+ *
+ * Execution methods:
+ *   - `execute()` — return all matching entities (with sort + pagination).
+ *   - `first()`   — return the first match (or null).
+ *   - `select()`  — paginated result with total count.
+ *   - `count()`   — return the number of matches.
+ *   - `groupBy()` — bucket results by a field value.
+ *   - `build()`   — export the builder state as a QueryOptions object.
+ *
+ * @module Query
+ */
+import type { Entity } from "../core/types/Entity.js";
+import type { FilterOperator } from "../core/types/FilterOperator.js";
+import type { QueryOptions } from "../core/types/QueryOptions.js";
+import type { PaginatedResult } from "../core/types/PaginatedResult.js";
+import type { GroupResult } from "../core/types/GroupResult.js";
+/**
+ * Callback registered by Record to resolve a class/name → data-provider function.
+ * This indirection allows Query to remain decoupled from Record and SheetRepository.
+ */
+type FromResolver = (classOrName: string | {
+    new (): Entity;
+    tableName: string;
+}) => () => Entity[];
+/**
+ * Fluent query builder that composes filter groups, sorting, and pagination,
+ * then delegates execution to QueryEngine.
+ *
+ * @typeParam T - Entity type returned by the query.
+ */
+export declare class Query<T extends Entity> {
+    /**
+     * Array of filter groups.  Each inner array is AND-connected;
+     * groups are OR-connected.  Starts with one empty group.
+     */
+    private filterGroups;
+    /** Ordered list of sort clauses to apply after filtering. */
+    private sorts;
+    /** Maximum number of results (undefined = no limit). */
+    private _limit?;
+    /** Number of results to skip (undefined = 0). */
+    private _offset?;
+    /** Callback that returns the full entity dataset (lazy-loaded). */
+    private dataProvider;
+    /**
+     * Module-level resolver injected by Record at import time.
+     * Converts a class constructor or table name to a data-provider function.
+     */
+    private static _fromResolverFn;
+    /**
+     * Register the from-resolver.  Called once by Record when it wires up
+     * the Query integration at module load time.
+     */
+    static _setFromResolver(resolver: FromResolver): void;
+    /**
+     * Create a new Query from a Record subclass.
+     * @typeParam U - Concrete Record type.
+     */
+    static from<U extends Entity>(ctor: {
+        new (): U;
+        tableName: string;
+    }): Query<U>;
+    /**
+     * Create a new Query from a table name string.
+     */
+    static from(name: string): Query<Entity>;
+    /**
+     * Construct a Query with the given data provider function.
+     * @param dataProvider - Callback returning the full set of entities to query.
+     */
+    constructor(dataProvider: () => T[]);
+    /**
+     * Add a filter to the current AND-group.
+     *
+     * @param field    - Entity field name (supports dot-paths for nested objects).
+     * @param operator - Comparison operator (=, !=, <, >, <=, >=, contains, startsWith, in, search).
+     * @param value    - Value to compare against.
+     * @returns this (for chaining).
+     */
+    where(field: string, operator: FilterOperator, value: unknown): Query<T>;
+    /**
+     * Alias for `where()` — adds another AND condition to the current group.
+     */
+    and(field: string, operator: FilterOperator, value: unknown): Query<T>;
+    /**
+     * Start a new OR-group with the given filter condition.
+     * Previous filters remain in their own AND-group.
+     */
+    or(field: string, operator: FilterOperator, value: unknown): Query<T>;
+    /**
+     * Add a sort clause (multiple orderBy calls are applied in order).
+     *
+     * @param field     - Entity field name to sort by.
+     * @param direction - "asc" (default) or "desc".
+     */
+    orderBy(field: string, direction?: "asc" | "desc"): Query<T>;
+    /**
+     * Set the maximum number of results to return.
+     * @throws If count is negative or non-finite.
+     */
+    limit(count: number): Query<T>;
+    /**
+     * Set the number of results to skip before returning.
+     * @throws If count is negative or non-finite.
+     */
+    offset(count: number): Query<T>;
+    /** True if any filter group contains at least one filter. */
+    private get hasFilters();
+    /** True if there are multiple non-empty filter groups (OR query). */
+    private get isOrQuery();
+    /** Return the first non-empty filter group (for simple AND queries). */
+    private get flatFilters();
+    /**
+     * Apply all filter groups to the entity dataset.
+     * Delegates to `QueryEngine.filterEntities` (AND) or
+     * `QueryEngine.filterEntitiesOr` (multiple OR groups).
+     */
+    private applyFilters;
+    /**
+     * Build a declarative QueryOptions object from the current builder state.
+     * Useful for passing to SheetRepository.find() or for serialisation.
+     */
+    build(): QueryOptions;
+    /**
+     * Execute the query and return all matching entities.
+     *
+     * Pipeline: load data → filter → sort → offset/limit.
+     */
+    execute(): T[];
+    /**
+     * Execute the query and return the first matching entity, or null.
+     *
+     * More efficient than `execute()[0]` when limit is already set.
+     */
+    first(): T | null;
+    /**
+     * Execute with explicit pagination, returning a PaginatedResult.
+     *
+     * @param offset - 0-based number of items to skip.
+     * @param limit  - Maximum items per page.
+     * @returns Object with items, total, offset, limit, hasNext.
+     */
+    select(offset: number, limit: number): PaginatedResult<T>;
+    /**
+     * Count the number of entities matching the current filters.
+     * No sorting or pagination is applied.
+     */
+    count(): number;
+    /**
+     * Group matching entities by a field value.
+     *
+     * Filters and sorts are applied before grouping.
+     *
+     * @param field - Entity field name to group by.
+     * @returns Array of GroupResult objects (one per distinct field value).
+     */
+    groupBy(field: string): GroupResult<T>[];
+}
+export {};
+//# sourceMappingURL=Query.d.ts.map

package/dist/npm/query/Query.d.ts.map

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

package/dist/npm/query/Query.js

@@ -0,0 +1,270 @@
+/**
+ * Fluent query builder for composing and executing queries against SheetORM data.
+ *
+ * Provides a chainable API inspired by common ORM patterns:
+ * ```ts
+ * const cars = Query.from(Car)
+ *   .where("make", "=", "Toyota")
+ *   .or("make", "=", "Honda")
+ *   .orderBy("year", "desc")
+ *   .limit(10)
+ *   .execute();
+ * ```
+ *
+ * Filter logic:
+ *   - `.where()` / `.and()` add filters to the current AND-group.
+ *   - `.or()` creates a new AND-group (groups are combined with OR logic).
+ *
+ * Execution methods:
+ *   - `execute()` — return all matching entities (with sort + pagination).
+ *   - `first()`   — return the first match (or null).
+ *   - `select()`  — paginated result with total count.
+ *   - `count()`   — return the number of matches.
+ *   - `groupBy()` — bucket results by a field value.
+ *   - `build()`   — export the builder state as a QueryOptions object.
+ *
+ * @module Query
+ */
+import { QueryEngine } from "./QueryEngine.js";
+import { SheetOrmLogger } from "../utils/SheetOrmLogger.js";
+/**
+ * Fluent query builder that composes filter groups, sorting, and pagination,
+ * then delegates execution to QueryEngine.
+ *
+ * @typeParam T - Entity type returned by the query.
+ */
+export class Query {
+    /**
+     * Register the from-resolver.  Called once by Record when it wires up
+     * the Query integration at module load time.
+     */
+    static _setFromResolver(resolver) {
+        Query._fromResolverFn = resolver;
+    }
+    /**
+     * Implementation: resolve the data provider and return a fresh Query.
+     * @throws If `_fromResolverFn` has not been set (Record not imported).
+     */
+    static from(classOrName) {
+        if (!Query._fromResolverFn) {
+            throw new Error("Query.from() is not available. Import Record from SheetORM to enable it.");
+        }
+        const provider = Query._fromResolverFn(classOrName);
+        return new Query(provider);
+    }
+    /**
+     * Construct a Query with the given data provider function.
+     * @param dataProvider - Callback returning the full set of entities to query.
+     */
+    constructor(dataProvider) {
+        /**
+         * Array of filter groups.  Each inner array is AND-connected;
+         * groups are OR-connected.  Starts with one empty group.
+         */
+        this.filterGroups = [[]];
+        /** Ordered list of sort clauses to apply after filtering. */
+        this.sorts = [];
+        this.dataProvider = dataProvider;
+    }
+    /**
+     * Add a filter to the current AND-group.
+     *
+     * @param field    - Entity field name (supports dot-paths for nested objects).
+     * @param operator - Comparison operator (=, !=, <, >, <=, >=, contains, startsWith, in, search).
+     * @param value    - Value to compare against.
+     * @returns this (for chaining).
+     */
+    where(field, operator, value) {
+        // Append to the last (current) filter group
+        this.filterGroups[this.filterGroups.length - 1].push({ field, operator, value });
+        return this;
+    }
+    /**
+     * Alias for `where()` — adds another AND condition to the current group.
+     */
+    and(field, operator, value) {
+        return this.where(field, operator, value);
+    }
+    /**
+     * Start a new OR-group with the given filter condition.
+     * Previous filters remain in their own AND-group.
+     */
+    or(field, operator, value) {
+        // Create a fresh AND-group for the OR branch
+        this.filterGroups.push([{ field, operator, value }]);
+        return this;
+    }
+    /**
+     * Add a sort clause (multiple orderBy calls are applied in order).
+     *
+     * @param field     - Entity field name to sort by.
+     * @param direction - "asc" (default) or "desc".
+     */
+    orderBy(field, direction = "asc") {
+        this.sorts.push({ field, direction });
+        return this;
+    }
+    /**
+     * Set the maximum number of results to return.
+     * @throws If count is negative or non-finite.
+     */
+    limit(count) {
+        if (!Number.isFinite(count) || count < 0) {
+            throw new Error(`limit() requires a non-negative finite number, got ${count}`);
+        }
+        this._limit = Math.floor(count);
+        return this;
+    }
+    /**
+     * Set the number of results to skip before returning.
+     * @throws If count is negative or non-finite.
+     */
+    offset(count) {
+        if (!Number.isFinite(count) || count < 0) {
+            throw new Error(`offset() requires a non-negative finite number, got ${count}`);
+        }
+        this._offset = Math.floor(count);
+        return this;
+    }
+    /** True if any filter group contains at least one filter. */
+    get hasFilters() {
+        return this.filterGroups.some((g) => g.length > 0);
+    }
+    /** True if there are multiple non-empty filter groups (OR query). */
+    get isOrQuery() {
+        return this.filterGroups.filter((g) => g.length > 0).length > 1;
+    }
+    /** Return the first non-empty filter group (for simple AND queries). */
+    get flatFilters() {
+        return this.filterGroups.find((g) => g.length > 0) ?? [];
+    }
+    /**
+     * Apply all filter groups to the entity dataset.
+     * Delegates to `QueryEngine.filterEntities` (AND) or
+     * `QueryEngine.filterEntitiesOr` (multiple OR groups).
+     */
+    applyFilters(entities) {
+        if (!this.hasFilters)
+            return entities;
+        if (this.isOrQuery) {
+            return QueryEngine.filterEntitiesOr(entities, this.filterGroups.filter((g) => g.length > 0));
+        }
+        return QueryEngine.filterEntities(entities, this.flatFilters);
+    }
+    /**
+     * Build a declarative QueryOptions object from the current builder state.
+     * Useful for passing to SheetRepository.find() or for serialisation.
+     */
+    build() {
+        const nonEmpty = this.filterGroups.filter((g) => g.length > 0);
+        const isOr = nonEmpty.length > 1;
+        return {
+            // Simple AND query → single where array
+            where: !isOr && nonEmpty.length === 1 ? [...nonEmpty[0]] : undefined,
+            // Multi-group OR query → whereGroups array of arrays
+            whereGroups: isOr ? nonEmpty.map((g) => [...g]) : undefined,
+            orderBy: this.sorts.length > 0 ? [...this.sorts] : undefined,
+            limit: this._limit,
+            offset: this._offset,
+        };
+    }
+    /**
+     * Execute the query and return all matching entities.
+     *
+     * Pipeline: load data → filter → sort → offset/limit.
+     */
+    execute() {
+        let entities = this.dataProvider();
+        const inputCount = entities.length;
+        // Apply filter groups
+        entities = this.applyFilters(entities);
+        // Apply sort clauses
+        if (this.sorts.length > 0) {
+            entities = QueryEngine.sortEntities(entities, this.sorts);
+        }
+        // Apply pagination (offset + limit)
+        const offset = this._offset ?? 0;
+        const limit = this._limit;
+        if (offset !== 0 || limit !== undefined) {
+            entities = entities.slice(offset, limit !== undefined ? offset + limit : undefined);
+        }
+        SheetOrmLogger.log(`[Query] execute input=${inputCount} filters=${this.filterGroups.flat().length} sort=${this.sorts.length} limit=${this._limit ?? "-"} offset=${this._offset ?? 0} → ${entities.length}`);
+        return entities;
+    }
+    /**
+     * Execute the query and return the first matching entity, or null.
+     *
+     * More efficient than `execute()[0]` when limit is already set.
+     */
+    first() {
+        let entities = this.dataProvider();
+        const inputCount = entities.length;
+        entities = this.applyFilters(entities);
+        if (this.sorts.length > 0) {
+            entities = QueryEngine.sortEntities(entities, this.sorts);
+        }
+        const offset = this._offset ?? 0;
+        const limit = this._limit;
+        // Short-circuit if limit is explicitly 0
+        if (limit === 0) {
+            SheetOrmLogger.log(`[Query] first  input=${inputCount} filters=${this.filterGroups.flat().length} → null (limit=0)`);
+            return null;
+        }
+        const visible = entities.slice(offset, limit !== undefined ? offset + limit : undefined);
+        const result = visible.length > 0 ? visible[0] : null;
+        SheetOrmLogger.log(`[Query] first  input=${inputCount} filters=${this.filterGroups.flat().length} → ${result ? "found" : "null"}`);
+        return result;
+    }
+    /**
+     * Execute with explicit pagination, returning a PaginatedResult.
+     *
+     * @param offset - 0-based number of items to skip.
+     * @param limit  - Maximum items per page.
+     * @returns Object with items, total, offset, limit, hasNext.
+     */
+    select(offset, limit) {
+        let entities = this.dataProvider();
+        const inputCount = entities.length;
+        entities = this.applyFilters(entities);
+        if (this.sorts.length > 0) {
+            entities = QueryEngine.sortEntities(entities, this.sorts);
+        }
+        // Delegate slicing + total count to QueryEngine
+        const paged = QueryEngine.paginateEntities(entities, offset, limit);
+        SheetOrmLogger.log(`[Query] select input=${inputCount} filters=${this.filterGroups.flat().length} offset=${offset} limit=${limit} → ${paged.items.length}/${paged.total}`);
+        return paged;
+    }
+    /**
+     * Count the number of entities matching the current filters.
+     * No sorting or pagination is applied.
+     */
+    count() {
+        let entities = this.dataProvider();
+        const inputCount = entities.length;
+        entities = this.applyFilters(entities);
+        SheetOrmLogger.log(`[Query] count  input=${inputCount} filters=${this.filterGroups.flat().length} → ${entities.length}`);
+        return entities.length;
+    }
+    /**
+     * Group matching entities by a field value.
+     *
+     * Filters and sorts are applied before grouping.
+     *
+     * @param field - Entity field name to group by.
+     * @returns Array of GroupResult objects (one per distinct field value).
+     */
+    groupBy(field) {
+        let entities = this.dataProvider();
+        entities = this.applyFilters(entities);
+        if (this.sorts.length > 0) {
+            entities = QueryEngine.sortEntities(entities, this.sorts);
+        }
+        return QueryEngine.groupEntities(entities, field);
+    }
+}
+/**
+ * Module-level resolver injected by Record at import time.
+ * Converts a class constructor or table name to a data-provider function.
+ */
+Query._fromResolverFn = null;
+//# sourceMappingURL=Query.js.map

package/dist/npm/query/Query.js.map

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

package/dist/npm/query/QueryEngine.d.ts

@@ -0,0 +1,140 @@
+/**
+ * QueryEngine — pure in-memory filter, sort, paginate, and group engine.
+ *
+ * Every function operates on plain entity arrays and returns new arrays
+ * without mutating the input.  The implementation is heavily optimised for
+ * the GAS V8 runtime (limited JIT, no SIMD, high GC cost):
+ *
+ *   - Filters are **compiled** into predicate closures once; the hot loop
+ *     invokes closures instead of evaluating operator strings.
+ *   - Sort keys are **pre-extracted** into column-major arrays to avoid
+ *     repeated field navigation during comparison callbacks.
+ *   - The `in` operator converts to a `Set` when the value list exceeds
+ *     8 elements for O(1) membership checks.
+ *   - String comparison operators (`contains`, `startsWith`, `search`)
+ *     are case-insensitive and pre-lower the filter value once.
+ *
+ * @module QueryEngine
+ */
+import type { Entity } from "../core/types/Entity.js";
+import type { Filter } from "../core/types/Filter.js";
+import type { SortClause } from "../core/types/SortClause.js";
+import type { QueryOptions } from "../core/types/QueryOptions.js";
+import type { PaginatedResult } from "../core/types/PaginatedResult.js";
+import type { GroupResult } from "../core/types/GroupResult.js";
+/**
+ * Filter entities by an array of filters using AND logic.
+ *
+ * All predicates are compiled once; the hot loop uses a labeled `continue outer`
+ * to short-circuit on the first failing predicate per entity (minimal GC pressure).
+ *
+ * @typeParam T - Entity type.
+ * @param entities - Source array (not mutated).
+ * @param filters  - Filters to apply (all must match — AND).
+ * @returns New array of matching entities.
+ */
+declare function filterEntities<T extends Entity>(entities: T[], filters: Filter[]): T[];
+/**
+ * Filter entities with OR-connected groups of AND-connected filters.
+ *
+ * An entity matches if it satisfies **any** group (OR), where within each
+ * group all filters must match (AND).  Empty groups never match.
+ *
+ * @typeParam T - Entity type.
+ * @param entities - Source array (not mutated).
+ * @param groups   - Array of filter groups (outer=OR, inner=AND).
+ * @returns New array of matching entities.
+ */
+declare function filterEntitiesOr<T extends Entity>(entities: T[], groups: Filter[][]): T[];
+/**
+ * Sort entities by multiple {@link SortClause} fields.
+ *
+ * **Performance strategy** (optimised for GAS V8):
+ *
+ * 1. Sort keys are **pre-extracted** into column-major arrays
+ *    (`keys[sortIndex][entityIndex]`) so the comparator never calls
+ *    field accessors — it reads from pre-populated primitive arrays.
+ * 2. An **index array** is sorted instead of the entities themselves,
+ *    avoiding expensive object moves in the V8 sort implementation.
+ * 3. The final result is assembled from the sorted indices in one pass.
+ *
+ * Null handling: `null`/`undefined` values sort **first** (before any
+ * non-null value) regardless of direction.
+ *
+ * @typeParam T - Entity type.
+ * @param entities - Source array (not mutated).
+ * @param sorts    - Sort clauses in priority order (first = primary sort).
+ * @returns New sorted array.
+ */
+declare function sortEntities<T extends Entity>(entities: T[], sorts: SortClause[]): T[];
+/**
+ * Apply pagination (offset + limit) to an entity array.
+ *
+ * Both `offset` and `limit` are sanitised: non-finite, negative, or
+ * fractional values are clamped to safe defaults (0 for offset, full
+ * length for limit).
+ *
+ * @typeParam T - Entity type.
+ * @param entities - Source array.
+ * @param offset   - Number of items to skip from the start.
+ * @param limit    - Maximum number of items to return.
+ * @returns Paginated result with metadata (total, hasNext, etc.).
+ */
+declare function paginateEntities<T>(entities: T[], offset: number, limit: number): PaginatedResult<T>;
+/**
+ * Group entities by a single field, producing one {@link GroupResult} per distinct value.
+ *
+ * Uses a `Map` keyed by the field value to collect entities in insertion
+ * order.  The pre-compiled field accessor avoids repeated path resolution.
+ *
+ * @typeParam T - Entity type.
+ * @param entities - Source array (not mutated).
+ * @param field    - Dot-separated field path to group by.
+ * @returns Array of group results, each containing key, count, and items.
+ */
+declare function groupEntities<T extends Entity>(entities: T[], field: string): GroupResult<T>[];
+/**
+ * Execute a complete query pipeline on an in-memory entity array.
+ *
+ * Pipeline stages (executed in order):
+ *
+ * 1. **Filter**: `whereGroups` (OR of ANDs) takes precedence over `where`
+ *    (simple AND).  If both are present, only `whereGroups` is applied.
+ * 2. **Sort**: Multi-field sort via {@link sortEntities}.
+ * 3. **Paginate**: `offset` and `limit` applied via `Array.slice`.
+ *
+ * This function does NOT call {@link paginateEntities} — it applies a
+ * lighter slice-only pagination without producing a `PaginatedResult`
+ * wrapper.  The caller (typically {@link SheetRepository}) is responsible
+ * for wrapping the result if needed.
+ *
+ * @typeParam T - Entity type.
+ * @param entities - Full entity array to query against.
+ * @param options  - Query options controlling filter, sort, and pagination.
+ * @returns Filtered, sorted, and paginated entity array.
+ */
+declare function executeQuery<T extends Entity>(entities: T[], options: QueryOptions): T[];
+/**
+ * Static facade exposing the query engine's pure functions as class methods.
+ *
+ * All methods are stateless — they operate on the provided entity array
+ * and return new arrays without side effects.  The class form exists so
+ * that callers can reference `QueryEngine.filterEntities(...)` instead of
+ * importing individual module-level functions.
+ */
+export declare class QueryEngine {
+    /** Filter entities with AND-connected conditions. */
+    static filterEntities: typeof filterEntities;
+    /** Filter entities with OR-connected groups of AND-connected conditions. */
+    static filterEntitiesOr: typeof filterEntitiesOr;
+    /** Sort entities by multiple fields with asc/desc directions. */
+    static sortEntities: typeof sortEntities;
+    /** Paginate entities and return metadata (total, hasNext, etc.). */
+    static paginateEntities: typeof paginateEntities;
+    /** Group entities by a field into key/count/items buckets. */
+    static groupEntities: typeof groupEntities;
+    /** Execute a full filter → sort → paginate pipeline. */
+    static executeQuery: typeof executeQuery;
+}
+export {};
+//# sourceMappingURL=QueryEngine.d.ts.map

package/dist/npm/query/QueryEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryEngine.d.ts","sourceRoot":"","sources":["../../../src/query/QueryEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAoIhE;;;;;;;;;;GAUG;AACH,iBAAS,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAuB/E;AAED;;;;;;;;;;GAUG;AACH,iBAAS,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,CA8ClF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,CA0D/E;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAY7F;AAED;;;;;;;;;;GAUG;AACH,iBAAS,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAuBvF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,CAAC,EAAE,CAqCjF;AAED;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,qDAAqD;IACrD,MAAM,CAAC,cAAc,wBAAkB;IACvC,4EAA4E;IAC5E,MAAM,CAAC,gBAAgB,0BAAoB;IAC3C,iEAAiE;IACjE,MAAM,CAAC,YAAY,sBAAgB;IACnC,oEAAoE;IACpE,MAAM,CAAC,gBAAgB,0BAAoB;IAC3C,8DAA8D;IAC9D,MAAM,CAAC,aAAa,uBAAiB;IACrC,wDAAwD;IACxD,MAAM,CAAC,YAAY,sBAAgB;CACpC"}