@b2bc-devkit/sheetorm 0.1.0

package/dist/npm/core/Registry.js

@@ -0,0 +1,206 @@
+/**
+ * Global singleton registry that manages the ORM runtime state.
+ *
+ * Responsibilities:
+ * - Holds the single {@link ISpreadsheetAdapter} (defaults to GAS active spreadsheet).
+ * - Maintains a per-table {@link SheetRepository} cache so the same repo
+ *   is reused for the lifetime of the script execution.
+ * - Creates and wires up the shared {@link IndexStore} used by all repos.
+ * - Keeps a class map so `Query.from("ClassName")` can resolve by name.
+ *
+ * @module Registry
+ */
+import { SheetRepository } from "./SheetRepository.js";
+import { IndexStore } from "../index/IndexStore.js";
+import { MemoryCache } from "./cache/MemoryCache.js";
+import { GoogleSpreadsheetAdapter } from "../storage/GoogleSpreadsheetAdapter.js";
+import { Decorators } from "./Decorators.js";
+import { SheetOrmLogger } from "../utils/SheetOrmLogger.js";
+/**
+ * Central registry for SheetORM.
+ *
+ * Accessed via `Registry.getInstance()`.  Call `Registry.reset()` in
+ * tests to start with a clean slate.
+ */
+export class Registry {
+    constructor() {
+        /** The spreadsheet-level adapter (wraps GAS Spreadsheet or mock). */
+        this.adapter = null;
+        /** Optional entity data cache (defaults to MemoryCache). */
+        this.cache = null;
+        /** Shared secondary-index manager. */
+        this.indexStore = null;
+        /** tableName → SheetRepository cache. */
+        this.repos = new Map();
+        /** tableName → RecordStatic class map for lookup by table name. */
+        this.classesByTable = new Map();
+        /** className → RecordStatic class map for lookup by constructor name. */
+        this.classesByName = new Map();
+    }
+    /** Return (or create) the singleton Registry instance. */
+    static getInstance() {
+        if (!Registry.instance) {
+            Registry.instance = new Registry();
+        }
+        return Registry.instance;
+    }
+    /** Destroy the singleton — used by test suites to reset state between runs. */
+    static reset() {
+        Registry.instance = null;
+    }
+    /**
+     * Configure the registry with a custom adapter and/or cache.
+     * Clears all previously created repos, class maps, and the index store.
+     */
+    configure(options) {
+        SheetOrmLogger.log(`[Registry] configure (adapter=${options.adapter?.constructor.name ?? "default"})`);
+        this.adapter = options.adapter ?? null;
+        this.cache = options.cache ?? null;
+        this.indexStore = null;
+        this.repos.clear();
+        this.classesByTable.clear();
+        this.classesByName.clear();
+    }
+    /**
+     * Return the current adapter, falling back to a default
+     * GoogleSpreadsheetAdapter (active spreadsheet) if none was configured.
+     */
+    getAdapter() {
+        if (!this.adapter) {
+            this.adapter = new GoogleSpreadsheetAdapter();
+        }
+        return this.adapter;
+    }
+    /**
+     * Lazily create the shared IndexStore.
+     * The IndexStore receives its **own** MemoryCache instance so that
+     * `cache.clear()` inside it does not wipe the entity data cache.
+     */
+    ensureIndexStore() {
+        if (!this.indexStore) {
+            const adapter = this.getAdapter();
+            if (!this.cache)
+                this.cache = new MemoryCache();
+            // IndexStore gets its own cache instance so that invalidateCache() → cache.clear()
+            // does NOT contaminate the entity data cache used by SheetRepository.
+            this.indexStore = new IndexStore(adapter, new MemoryCache());
+        }
+        return this.indexStore;
+    }
+    /**
+     * Ensure the sheet tab for a given schema exists, and register
+     * any declared secondary indexes with the IndexStore.
+     *
+     * @param schema     - The table schema (name, fields, indexes).
+     * @param indexStore - The shared IndexStore.
+     * @returns The sheet adapter and whether it was freshly created.
+     */
+    ensureTable(schema, indexStore) {
+        const adapter = this.getAdapter();
+        SheetOrmLogger.log(`[Registry] ensureTable "${schema.tableName}" (indexes=${schema.indexes.length})`);
+        // Check if the sheet tab already exists
+        let sheet = adapter.getSheetByName(schema.tableName);
+        let created = false;
+        if (!sheet) {
+            sheet = adapter.insertSheet(schema.tableName);
+            created = true;
+        }
+        SheetOrmLogger.log(`[Registry] ensureTable "${schema.tableName}" → ${created ? "insertSheet (G4 new)" : "existing sheet"}`);
+        // L1 optimisation: headers for newly-created sheets are deferred —
+        // they will be written together with the first data flush in
+        // SheetRepository, saving one GAS API call (~700 ms).
+        if (!created) {
+            // Nothing to do — existing sheet already has headers from a prior execution.
+        }
+        // If no indexes are defined, skip index table creation
+        if (schema.indexes.length === 0)
+            return { sheet, created };
+        if (!schema.indexTableName) {
+            throw new Error(`Table schema "${schema.tableName}" defines indexes but has no indexTableName. ` +
+                "Legacy per-field _idx_* indexes were removed; use a combined index table name (e.g. idx_ClassName).");
+        }
+        // Create the combined index sheet and register each field index
+        indexStore.createCombinedIndex(schema.indexTableName);
+        for (const idx of schema.indexes) {
+            indexStore.registerIndex(schema.indexTableName, idx.field, idx.unique ?? false);
+        }
+        return { sheet, created };
+    }
+    /**
+     * Register a Record subclass so it can be looked up by table name or
+     * class name via `getClassByName()`.
+     */
+    registerClass(ctor) {
+        if (!this.classesByTable.has(ctor.tableName)) {
+            this.classesByTable.set(ctor.tableName, ctor);
+        }
+        if (ctor.name && !this.classesByName.has(ctor.name)) {
+            this.classesByName.set(ctor.name, ctor);
+        }
+    }
+    /**
+     * Return (or create) the SheetRepository for a given Record subclass.
+     *
+     * On first call for a table name the method:
+     * 1. Registers the class in the class map.
+     * 2. Builds a {@link TableSchema} from decorator metadata.
+     * 3. Ensures the sheet tab exists (createSheet / insertSheet).
+     * 4. Creates a new SheetRepository with all optimisation flags
+     *    (L1 deferred headers, K2 index skipping, B5 known row count).
+     *
+     * Subsequent calls return the cached repository instance.
+     */
+    ensureRepository(ctor) {
+        const tableName = ctor.tableName;
+        // Return cached repo if it already exists
+        if (this.repos.has(tableName)) {
+            SheetOrmLogger.log(`[Registry] ensureRepository "${tableName}" → cache hit`);
+            return this.repos.get(tableName);
+        }
+        SheetOrmLogger.log(`[Registry] ensureRepository "${tableName}" → creating`);
+        this.registerClass(ctor);
+        const indexStore = this.ensureIndexStore();
+        // Build schema from decorator metadata
+        const indexes = Decorators.getIndexes(ctor);
+        const schema = {
+            tableName,
+            // K2: only populate indexTableName when the class has @Indexed fields.
+            // Record.indexTableName always returns a string (e.g. "idx_Cars"), but for classes
+            // without indexes this causes every update/delete to call getSheetByName() on a
+            // non-existent index sheet, wasting ~700 ms per API call.
+            indexTableName: indexes.length > 0 ? ctor.indexTableName : undefined,
+            fields: Decorators.getFields(ctor),
+            indexes,
+        };
+        // Create the sheet tab (or get existing) and register indexes
+        const { sheet, created } = this.ensureTable(schema, indexStore);
+        // Construct the repository with performance optimisation flags:
+        // - sheet:    pre-resolved ISheetAdapter (B7 cache seed)
+        // - created ? 0 : undefined:  B5 known row count (0 for new sheets)
+        // - created:  L1 defer header write to first data flush
+        const repo = new SheetRepository(this.getAdapter(), schema, indexStore, this.cache, undefined, sheet, created ? 0 : undefined, created);
+        this.repos.set(tableName, repo);
+        return repo;
+    }
+    /**
+     * Look up a previously registered Record subclass by constructor name
+     * or table name.
+     */
+    getClassByName(name) {
+        return this.classesByName.get(name) ?? this.classesByTable.get(name);
+    }
+    /** Return the shared IndexStore (creates it if needed). */
+    getIndexStore() {
+        return this.ensureIndexStore();
+    }
+    /** Flush both the entity data cache and the index store caches. */
+    clearCache() {
+        if (this.cache)
+            this.cache.clear();
+        if (this.indexStore)
+            this.indexStore.clearAllCaches();
+    }
+}
+/** Singleton instance (lazy-initialised). */
+Registry.instance = null;
+//# sourceMappingURL=Registry.js.map

package/dist/npm/core/Registry.js.map

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

package/dist/npm/core/SheetRepository.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Main CRUD and query interface for a single entity type.
+ *
+ * Each `SheetRepository<T>` manages one Google Sheets tab, converting
+ * between in-memory {@link Entity} objects and sheet rows via
+ * {@link Serialization}.  Inspired by the Repository pattern from
+ * common ORM architectures (Hibernate, TypeORM, etc.).
+ *
+ * Performance optimisations (referenced by codename in comments):
+ *   - **B5**  — Known row count passed from Registry avoids getLastRow().
+ *   - **B7**  — `sheetCache` memoises the ISheetAdapter for the tab.
+ *   - **K1**  — Reuses physicalRowCount across saves inside saveAll().
+ *   - **K2**  — Skips index sheet lookup when the class has no @Indexed fields.
+ *   - **L1**  — Defers header write to the first data flush (saves ~700 ms).
+ *   - **L2**  — Bulk delete rewrite for delete-only batch commits.
+ *
+ * @module SheetRepository
+ */
+import type { Entity } from "../core/types/Entity.js";
+import type { ISpreadsheetAdapter } from "../core/types/ISpreadsheetAdapter.js";
+import type { ISheetAdapter } from "../core/types/ISheetAdapter.js";
+import type { TableSchema } from "../core/types/TableSchema.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";
+import type { LifecycleHooks } from "../core/types/LifecycleHooks.js";
+import type { ICacheProvider } from "../core/types/ICacheProvider.js";
+import { IndexStore } from "../index/IndexStore.js";
+import { Query } from "../query/Query.js";
+/**
+ * Repository providing CRUD, query, pagination, and batch operations
+ * for entities of type `T` stored in a single Google Sheet tab.
+ *
+ * @typeParam T - Entity type managed by this repository.
+ */
+export declare class SheetRepository<T extends Entity> {
+    private adapter;
+    private schema;
+    private indexStore;
+    private cache;
+    private hooks;
+    private headers;
+    private idColIdx;
+    private requiredFields;
+    private defaultableFields;
+    private dataCacheKey;
+    private fieldMap;
+    /** Fast-lookup map: entity ID → 1-based sheet row index for O(1) row access. */
+    private idToRowIndex;
+    /** Buffered operations when a batch is active (beginBatch/commitBatch). */
+    private batchBuffer;
+    /**
+     * Entity batch accumulator used by saveAll().
+     * Each entry stores the entity, its serialised row, 0-based data index, and
+     * whether it is a "create" or "update".  Flushed via flushEntityBatch().
+     */
+    private entityBatch;
+    /** Cached sheet reference for the duration of saveAll() — avoids 1000× getSheetByName(). */
+    private batchSheet;
+    /** Row count captured once at saveAll() start — avoids 1000× getLastRow(). */
+    private batchBaseRowCount;
+    /** Cached entity array used by updateCacheAfterSave in batch mode — avoids 1000× cache.get() log calls. */
+    private batchCachedData;
+    /** Indexed fields metadata, cached for the duration of saveAll() — avoids 1000× getIndexedFields() array alloc. */
+    private batchIndexedFields;
+    /** Physical sheet row count, tracked to avoid repeated getLastRow() API calls in non-batch save sequences. */
+    private physicalRowCount;
+    /** True when idToRowIndex was built from a complete sheet scan (bootstrap or loadAllEntities/rowIndexById). */
+    private idToRowIndexComplete;
+    /** Memoized sheet reference — avoids repeated getSheetByName() API calls within a session (B7). */
+    private sheetCache;
+    /** Memoized set of indexed field names — avoids repeated getIndexedFields() array allocations in find(). */
+    private indexedFieldNames;
+    /** L1: true when headers haven't been written to the sheet yet (new sheet from ensureTable). */
+    private headersDeferred;
+    /**
+     * Constructs a new repository for the given table schema.
+     *
+     * @param adapter         - Spreadsheet adapter providing sheet management.
+     * @param schema          - Table schema (name, fields, indexes).
+     * @param indexStore      - Shared IndexStore for secondary indexes.
+     * @param cache           - Optional cache provider for in-memory row caching.
+     * @param hooks           - Optional lifecycle hooks (onValidate, beforeSave, afterSave, beforeDelete, afterDelete).
+     * @param initialSheet    - Pre-resolved sheet adapter (B7 optimisation).
+     * @param initialRowCount - Pre-fetched row count (B5 optimisation).
+     * @param headersDeferred - True if the sheet was just created and headers still need writing (L1).
+     */
+    constructor(adapter: ISpreadsheetAdapter, schema: TableSchema, indexStore: IndexStore, cache?: ICacheProvider, hooks?: LifecycleHooks<T>, initialSheet?: ISheetAdapter, initialRowCount?: number, headersDeferred?: boolean);
+    /**
+     * Save (create or update) an entity.
+     *
+     * When a batch is active (see {@link beginBatch}), the operation is buffered
+     * and deferred until {@link commitBatch} is called.  Otherwise delegates
+     * immediately to {@link doSave}.
+     *
+     * @param partial - Partial entity with optional `__id`.
+     * @returns The saved entity with system columns populated.
+     */
+    save(partial: Partial<T> & {
+        __id?: string;
+    }): T;
+    /**
+     * Internal save implementation — resolves existence, validates, applies
+     * defaults, and writes to the sheet or buffers into an entity batch.
+     *
+     * @param partial - Partial entity data with optional `__id`.
+     * @returns Fully populated entity with system columns.
+     */
+    private doSave;
+    /**
+     * Save multiple entities in a single optimised batch.
+     *
+     * 1. Captures the sheet reference and row count once (K1, B7).
+     * 2. Calls {@link doSave} for each entity — rows are buffered instead of
+     *    written individually.
+     * 3. Flushes all buffered rows via {@link flushEntityBatch} (single API call).
+     * 4. Flushes index writes via {@link IndexStore.flushIndexBatch}.
+     *
+     * On error the batch state is fully reset and the cache is invalidated.
+     *
+     * @param entities - Array of partial entities to save.
+     * @returns Array of fully populated saved entities.
+     */
+    saveAll(entities: Array<Partial<T>>): T[];
+    /**
+     * Find an entity by its primary key (`__id`).
+     *
+     * Uses a fast path when idToRowIndex + cache are populated, falling back
+     * to a full {@link loadAllEntities} scan otherwise.
+     *
+     * @param id - Entity `__id` value.
+     * @returns The matching entity or `null` if not found.
+     */
+    findById(id: string): T | null;
+    /**
+     * Find entities matching query options (filter, sort, paginate, group).
+     *
+     * When a `search` operator targets an `@Indexed` field and a combined index
+     * sheet exists, the n-gram search index is used to narrow candidates before
+     * the full filter pipeline runs (Solr-like optimisation).
+     *
+     * @param options - Optional query options (where, whereGroups, orderBy, offset, limit).
+     * @returns Array of matching entities.
+     */
+    find(options?: QueryOptions): T[];
+    /**
+     * Find the first entity matching query options.
+     *
+     * Delegates to {@link find} with `limit: 1`.
+     *
+     * @param options - Optional query options.
+     * @returns The first matching entity or `null`.
+     */
+    findOne(options?: QueryOptions): T | null;
+    /**
+     * Delete an entity by ID.
+     *
+     * When a batch is active, the delete is queued and `true` is returned
+     * immediately; actual removal happens on {@link commitBatch}.
+     *
+     * @param id - Entity `__id` to delete.
+     * @returns `true` if the entity was found and deleted (or queued).
+     */
+    delete(id: string): boolean;
+    /**
+     * Internal delete implementation.
+     *
+     * 1. Runs `beforeDelete` lifecycle hook (can veto deletion by returning `false`).
+     * 2. Resolves the row index via in-memory cache or sheet scan.
+     * 3. Removes from secondary indexes.
+     * 4. Deletes the sheet row and adjusts `idToRowIndex`.
+     * 5. Updates entity cache and runs `afterDelete` hook.
+     *
+     * @param id - Entity `__id` to delete.
+     * @returns `true` if the entity was found and deleted.
+     */
+    private doDelete;
+    /**
+     * Delete all entities matching a query (or all entities if no options given).
+     *
+     * Uses bulk write (replaceAllData) for 3+ deletions — two API calls instead
+     * of N individual deleteRow() calls.  For 1–2 deletions, individual deletes
+     * are cheaper due to lower overhead.
+     *
+     * @param options - Optional query options to select entities to delete.
+     * @returns Number of entities deleted.
+     */
+    deleteAll(options?: QueryOptions): number;
+    /**
+     * Count entities matching a query.
+     *
+     * @param options - Optional query options (only `where`/`whereGroups` are meaningful).
+     * @returns Total count of matching entities.
+     */
+    count(options?: QueryOptions): number;
+    /**
+     * Paginated select — applies optional filters, then paginates.
+     *
+     * @param offset - 0-based offset.
+     * @param limit  - Maximum number of results.
+     * @param options - Optional query options applied before pagination.
+     * @returns {@link PaginatedResult} with `data`, `total`, `offset`, and `limit`.
+     */
+    select(offset: number, limit: number, options?: QueryOptions): PaginatedResult<T>;
+    /**
+     * Group entities by a field value.
+     *
+     * @param field   - Field name to group by.
+     * @param options - Optional query options applied before grouping.
+     * @returns Array of {@link GroupResult} objects.
+     */
+    groupBy(field: string, options?: QueryOptions): GroupResult<T>[];
+    /**
+     * Create a fluent {@link Query} builder for this repository.
+     *
+     * @returns A new Query instance backed by a snapshot of all current entities.
+     */
+    query(): Query<T>;
+    /**
+     * Start buffering save/delete operations for later atomic commit.
+     *
+     * Call {@link commitBatch} to apply all buffered operations, or
+     * {@link rollbackBatch} to discard them.
+     */
+    beginBatch(): void;
+    /**
+     * Commit all buffered operations from {@link beginBatch}.
+     *
+     * L2 optimisation: if the buffer contains only deletes, a bulk rewrite
+     * (replaceAllData) is used instead of N individual deleteRow() calls.
+     */
+    commitBatch(): void;
+    /**
+     * Commit a delete-only batch via bulk replaceAllData.
+     *
+     * Falls back to per-ID deletes for tiny (≤2) or duplicate-heavy batches
+     * to preserve semantics and avoid unnecessary full-sheet rewrites.
+     *
+     * @param ids - Array of entity IDs to delete.
+     */
+    private commitDeleteBatch;
+    /**
+     * Discard all buffered operations without applying them.
+     */
+    rollbackBatch(): void;
+    /**
+     * Check whether batch mode is currently active.
+     *
+     * @returns `true` when {@link beginBatch} was called but not yet committed or rolled back.
+     */
+    isBatchActive(): boolean;
+    /**
+     * Return the memoised ISheetAdapter for this table, resolving it once
+     * from the spreadsheet adapter and caching it for subsequent calls (B7).
+     *
+     * @throws Error if the sheet doesn't exist.
+     */
+    private getSheet;
+    /**
+     * Load all entities from the sheet, deserialise them, and populate the cache.
+     *
+     * Returns the cached array on a cache hit.  On a cache miss, reads all rows
+     * from the sheet, converts them via {@link Serialization.rowToEntity},
+     * builds {@link idToRowIndex}, and stores the result.
+     *
+     * @throws Error if called during an active entity batch (saveAll).
+     * @returns Array of all entities in the table.
+     */
+    private loadAllEntities;
+    /**
+     * Find the 0-based data row index for an entity by its `__id` via a full
+     * sheet scan.  Rebuilds {@link idToRowIndex} as a side-effect.
+     *
+     * @param sheet - The sheet adapter to read from.
+     * @param id    - Entity `__id` to search for.
+     * @returns 0-based row index, or `null` if not found.
+     */
+    private rowIndexById;
+    /**
+     * Add a newly-created entity to all relevant secondary indexes.
+     *
+     * In batch mode, uses pre-cached {@link batchIndexedFields} to avoid
+     * repeated `getIndexedFields()` allocations.
+     *
+     * @param entity - The entity to index.
+     */
+    private addToIndexes;
+    /**
+     * Flush all buffered entity rows to the sheet in a single API call.
+     *
+     * Called at the end of {@link saveAll}.  Sorts buffered entries by
+     * `dataIndex` to build a contiguous row array, then writes them via
+     * `sheet.updateRows()` (or `writeAllRowsWithHeaders` for the L1 path).
+     *
+     * @param sheet - The sheet adapter to write to.
+     */
+    private flushEntityBatch;
+    /** Shallow-clone an entity to prevent external mutation of cached data. */
+    private cloneEntity;
+    /** Shallow-clone an array of entities. */
+    private cloneEntities;
+    /**
+     * Update the entity cache in place after a save (create or update).
+     *
+     * In batch mode, reuses {@link batchCachedData} to avoid repeated
+     * `cache.get()` calls that would trigger verbose logging overhead.
+     *
+     * @param entity - The saved entity.
+     * @param isNew  - Whether this was a create (append) or update (replace).
+     */
+    private updateCacheAfterSave;
+    /**
+     * Remove a deleted entity from the entity cache.
+     *
+     * Note: {@link idToRowIndex} is updated separately in {@link doDelete}.
+     * This method only handles the entity array cache.
+     *
+     * @param id - The `__id` of the deleted entity.
+     */
+    private updateCacheAfterDelete;
+    /**
+     * Check whether a field name has an `@Indexed` decorator.
+     *
+     * Uses the pre-built {@link indexedFieldNames} set for O(1) lookup.
+     *
+     * @param fieldName - Name of the field to check.
+     * @returns `true` if the field is indexed.
+     */
+    private isIndexedField;
+}
+//# sourceMappingURL=SheetRepository.d.ts.map

package/dist/npm/core/SheetRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SheetRepository.d.ts","sourceRoot":"","sources":["../../../src/core/SheetRepository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,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;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAItE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAI1C;;;;;GAKG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,MAAM;IAC3C,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,iBAAiB,CAAwB;IACjD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAA+B;IAC/C,gFAAgF;IAChF,OAAO,CAAC,YAAY,CAAoC;IAExD,2EAA2E;IAC3E,OAAO,CAAC,WAAW,CAAkE;IAErF;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAKF;IAEjB,4FAA4F;IAC5F,OAAO,CAAC,UAAU,CAA8B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB,CAAuB;IAChD,2GAA2G;IAC3G,OAAO,CAAC,eAAe,CAAoB;IAC3C,mHAAmH;IACnH,OAAO,CAAC,kBAAkB,CAA4B;IACtD,8GAA8G;IAC9G,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,+GAA+G;IAC/G,OAAO,CAAC,oBAAoB,CAAS;IACrC,mGAAmG;IACnG,OAAO,CAAC,UAAU,CAA8B;IAChD,4GAA4G;IAC5G,OAAO,CAAC,iBAAiB,CAAc;IACvC,gGAAgG;IAChG,OAAO,CAAC,eAAe,CAAU;IAEjC;;;;;;;;;;;OAWG;gBAED,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,YAAY,CAAC,EAAE,aAAa,EAC5B,eAAe,CAAC,EAAE,MAAM,EACxB,eAAe,CAAC,EAAE,OAAO;IA8C3B;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC;IAmBhD;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAuMd;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE;IAgEzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAsB9B;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,CAAC,EAAE;IAmDjC;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,CAAC,GAAG,IAAI;IAMzC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAS3B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ;IAiEhB;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM;IAkEzC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM;IAMrC;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,eAAe,CAAC,CAAC,CAAC;IAWjF;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE;IAUhE;;;;OAIG;IACH,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC;IAMjB;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IAIlB;;;;;OAKG;IACH,WAAW,IAAI,IAAI;IA+BnB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IA+DzB;;OAEG;IACH,aAAa,IAAI,IAAI;IAIrB;;;;OAIG;IACH,aAAa,IAAI,OAAO;IAMxB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAYhB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA2CvB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAmBpB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IA0BxB,2EAA2E;IAC3E,OAAO,CAAC,WAAW;IAInB,0CAA0C;IAC1C,OAAO,CAAC,aAAa;IAIrB;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;CAGvB"}