@brightchain/brightchain-lib 0.18.0 → 0.19.0

package/src/lib/db/inMemoryDatabase.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * InMemoryDatabase – a platform-agnostic IDatabase implementation.
+ *
+ * Uses MemoryBlockStore and InMemoryHeadRegistry for storage, requiring
+ * no Node.js APIs. This is the base class that BrightChainDb in
+ * brightchain-db extends to add disk persistence.
+ *
+ * Usage:
+ *   const db = new InMemoryDatabase(blockStore, { name: 'mydb' });
+ *   await db.connect();
+ *   const users = db.collection('users');
+ *   await users.insertOne({ name: 'Alice' });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryDatabase = void 0;
+const collection_1 = require("./collection");
+const inMemoryHeadRegistry_1 = require("./inMemoryHeadRegistry");
+const transaction_1 = require("./transaction");
+const uuidGenerator_1 = require("./uuidGenerator");
+/**
+ * The main in-memory database driver – analogous to MongoDB's `Db` class.
+ *
+ * Designed to be extended by `BrightChainDb` in brightchain-db which adds
+ * persistence-specific options (dataDir, poolId, PersistentHeadRegistry).
+ */
+class InMemoryDatabase {
+    constructor(blockStore, options) {
+        this.collections = new Map();
+        /** Server-side cursor sessions for REST pagination */
+        this.cursorSessions = new Map();
+        /** Connection state for IDatabase conformance */
+        this._connected = false;
+        this.store = blockStore;
+        this.name = options?.name ?? 'brightchain';
+        this.headRegistry = options?.headRegistry ?? new inMemoryHeadRegistry_1.InMemoryHeadRegistry();
+        this.uuidGenerator = options?.uuidGenerator ?? (0, uuidGenerator_1.createDefaultUuidGenerator)();
+        this.cursorTimeoutMs = options?.cursorTimeoutMs ?? 300000;
+    }
+    /**
+     * Connect to the backing store.
+     * Block storage does not require a network connection, so the URI is
+     * accepted but ignored. Calling connect on an already-connected instance
+     * completes without error (idempotent).
+     */
+    async connect(_uri) {
+        this._connected = true;
+    }
+    /**
+     * Disconnect from the backing store.
+     * Calling disconnect on an already-disconnected instance completes
+     * without error (idempotent).
+     */
+    async disconnect() {
+        this._connected = false;
+    }
+    /**
+     * Whether the store is currently connected.
+     */
+    isConnected() {
+        return this._connected;
+    }
+    /**
+     * Get (or create) a collection by name.
+     * Collections are created lazily – no explicit create step is needed.
+     */
+    collection(name, options) {
+        if (!this.collections.has(name)) {
+            const coll = new collection_1.Collection(name, this.store, this.name, this.headRegistry, options, this.uuidGenerator);
+            // Wire up cross-collection resolver for $lookup
+            coll.setCollectionResolver((collName) => this.collection(collName));
+            this.collections.set(name, coll);
+        }
+        return this.collections.get(name);
+    }
+    /**
+     * Expose the head registry for components that need to read head block IDs
+     * (e.g. CBLIndex for FEC parity generation on metadata blocks).
+     */
+    getHeadRegistry() {
+        return this.headRegistry;
+    }
+    /**
+     * List all known collection names.
+     */
+    listCollections() {
+        return Array.from(this.collections.keys());
+    }
+    /**
+     * Drop a collection – removes all documents and indexes.
+     */
+    async dropCollection(name) {
+        const coll = this.collections.get(name);
+        if (!coll)
+            return false;
+        await coll.drop();
+        this.collections.delete(name);
+        return true;
+    }
+    /**
+     * Drop the entire database.
+     * Clears all collections. Subclasses may add pool management.
+     */
+    async dropDatabase() {
+        this.collections.clear();
+    }
+    /**
+     * Start a client session for transaction support.
+     *
+     * Usage:
+     *   const session = db.startSession();
+     *   session.startTransaction();
+     *   try {
+     *     await coll.insertOne(doc, { session });
+     *     await session.commitTransaction();
+     *   } catch {
+     *     await session.abortTransaction();
+     *   } finally {
+     *     session.endSession();
+     *   }
+     */
+    startSession() {
+        const commitCallback = async (journal) => {
+            for (const op of journal) {
+                const coll = this.collection(op.collection);
+                switch (op.type) {
+                    case 'insert':
+                        await coll._txInsert(op.doc);
+                        break;
+                    case 'update':
+                        await coll._txUpdate(op.docId, op.after);
+                        break;
+                    case 'delete':
+                        await coll._txDelete(op.docId, op.doc);
+                        break;
+                }
+            }
+        };
+        const rollbackCallback = async (journal) => {
+            // Roll back in reverse order.
+            // Copy-on-write: rollback only restores doc-index mappings.
+            // Blocks written during the failed commit are left as orphans in
+            // the store — they are immutable and harmless.
+            for (let i = journal.length - 1; i >= 0; i--) {
+                const op = journal[i];
+                const coll = this.collection(op.collection);
+                try {
+                    switch (op.type) {
+                        case 'insert':
+                            // Remove the new mapping (block stays in store)
+                            await coll._txRollbackInsert(op.doc._id);
+                            break;
+                        case 'update':
+                            // Restore old mapping (old block still in store — CoW)
+                            await coll._txRollbackUpdate(op.docId, op.before);
+                            break;
+                        case 'delete':
+                            // Restore old mapping (old block still in store — CoW)
+                            await coll._txRollbackDelete(op.doc);
+                            break;
+                    }
+                }
+                catch {
+                    // Best-effort rollback
+                }
+            }
+        };
+        return new transaction_1.DbSession(commitCallback, rollbackCallback, this.uuidGenerator);
+    }
+    /**
+     * Convenience: run a callback within a transaction.
+     * Automatically commits on success, aborts on error.
+     */
+    async withTransaction(fn) {
+        const session = this.startSession();
+        session.startTransaction();
+        try {
+            const result = await fn(session);
+            await session.commitTransaction();
+            return result;
+        }
+        catch (err) {
+            // Only abort if the transaction is still active.
+            // commitTransaction() clears inTransaction in its finally block, so if
+            // the error came from commitTransaction itself the abort is already done.
+            if (session.inTransaction) {
+                await session.abortTransaction();
+            }
+            throw err;
+        }
+        finally {
+            session.endSession();
+        }
+    }
+    // ═══════════════════════════════════════════════════════
+    // Server-side cursor sessions (for REST pagination)
+    // ═══════════════════════════════════════════════════════
+    /**
+     * Create a server-side cursor session for paginated access.
+     */
+    createCursorSession(params) {
+        this.cleanExpiredCursors();
+        const id = this.uuidGenerator();
+        const cursor = {
+            ...params,
+            id,
+            lastAccessed: Date.now(),
+        };
+        this.cursorSessions.set(id, cursor);
+        return cursor;
+    }
+    /**
+     * Get a cursor session by ID and refresh its last-accessed timestamp.
+     * Returns null if the cursor has expired or doesn't exist.
+     */
+    getCursorSession(cursorId) {
+        const cursor = this.cursorSessions.get(cursorId);
+        if (!cursor)
+            return null;
+        if (Date.now() - cursor.lastAccessed > this.cursorTimeoutMs) {
+            this.cursorSessions.delete(cursorId);
+            return null;
+        }
+        cursor.lastAccessed = Date.now();
+        return cursor;
+    }
+    /**
+     * Advance cursor position and return next batch of document IDs.
+     */
+    getNextBatch(cursorId) {
+        const cursor = this.getCursorSession(cursorId);
+        if (!cursor)
+            return null;
+        const start = cursor.position;
+        const end = Math.min(start + cursor.batchSize, cursor.documentIds.length);
+        cursor.position = end;
+        return cursor.documentIds.slice(start, end);
+    }
+    /**
+     * Close and remove a cursor session.
+     */
+    closeCursorSession(cursorId) {
+        return this.cursorSessions.delete(cursorId);
+    }
+    /**
+     * Clean up expired cursor sessions.
+     */
+    cleanExpiredCursors() {
+        const now = Date.now();
+        for (const [id, cursor] of this.cursorSessions.entries()) {
+            if (now - cursor.lastAccessed > this.cursorTimeoutMs) {
+                this.cursorSessions.delete(id);
+            }
+        }
+    }
+}
+exports.InMemoryDatabase = InMemoryDatabase;
+//# sourceMappingURL=inMemoryDatabase.js.map

package/src/lib/db/inMemoryDatabase.js.map

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

package/src/lib/db/inMemoryHeadRegistry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-memory HeadRegistry implementation.
+ *
+ * Preserves the existing HeadRegistry behavior (pure in-memory, no disk I/O)
+ * while conforming to the IHeadRegistry interface. Mutating methods return
+ * resolved Promises for interface compatibility with persistent implementations.
+ *
+ * Use `createIsolated()` for test scenarios that need an independent registry.
+ */
+import type { DeferredHeadUpdate, IHeadRegistry } from '../interfaces/storage/headRegistry';
+export declare class InMemoryHeadRegistry implements IHeadRegistry {
+    private readonly heads;
+    private readonly timestamps;
+    private readonly deferred;
+    private makeKey;
+    getHead(dbName: string, collectionName: string): string | undefined;
+    setHead(dbName: string, collectionName: string, blockId: string): Promise<void>;
+    removeHead(dbName: string, collectionName: string): Promise<void>;
+    clear(): Promise<void>;
+    load(): Promise<void>;
+    getAllHeads(): Map<string, string>;
+    getHeadTimestamp(dbName: string, collectionName: string): Date | undefined;
+    mergeHeadUpdate(dbName: string, collectionName: string, blockId: string, timestamp: Date): Promise<boolean>;
+    deferHeadUpdate(dbName: string, collectionName: string, blockId: string, timestamp: Date): Promise<void>;
+    applyDeferredUpdates(blockId: string): Promise<number>;
+    getDeferredUpdates(): DeferredHeadUpdate[];
+    /**
+     * Factory method that creates an independent InMemoryHeadRegistry instance.
+     * Useful for tests that need isolated state.
+     */
+    static createIsolated(): InMemoryHeadRegistry;
+}
+//# sourceMappingURL=inMemoryHeadRegistry.d.ts.map

package/src/lib/db/inMemoryHeadRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryHeadRegistry.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAE5C,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7D,OAAO,CACX,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAMV,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIpE,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,OAAO,CAAC;IAeb,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,IAAI,CAAC;IAIV,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB5D,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,oBAAoB;CAG9C"}

package/src/lib/db/inMemoryHeadRegistry.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryHeadRegistry = void 0;
+class InMemoryHeadRegistry {
+    constructor() {
+        this.heads = new Map();
+        this.timestamps = new Map();
+        this.deferred = [];
+    }
+    makeKey(dbName, collectionName) {
+        return `${dbName}:${collectionName}`;
+    }
+    getHead(dbName, collectionName) {
+        return this.heads.get(this.makeKey(dbName, collectionName));
+    }
+    async setHead(dbName, collectionName, blockId) {
+        const key = this.makeKey(dbName, collectionName);
+        this.heads.set(key, blockId);
+        this.timestamps.set(key, new Date());
+    }
+    async removeHead(dbName, collectionName) {
+        const key = this.makeKey(dbName, collectionName);
+        this.heads.delete(key);
+        this.timestamps.delete(key);
+    }
+    async clear() {
+        this.heads.clear();
+        this.timestamps.clear();
+        this.deferred.length = 0;
+    }
+    async load() {
+        // No-op for in-memory implementation
+    }
+    getAllHeads() {
+        return new Map(this.heads);
+    }
+    getHeadTimestamp(dbName, collectionName) {
+        return this.timestamps.get(this.makeKey(dbName, collectionName));
+    }
+    async mergeHeadUpdate(dbName, collectionName, blockId, timestamp) {
+        const key = this.makeKey(dbName, collectionName);
+        const localTimestamp = this.timestamps.get(key);
+        // If no local head exists, or the remote timestamp is strictly newer, apply
+        if (!localTimestamp || timestamp.getTime() > localTimestamp.getTime()) {
+            this.heads.set(key, blockId);
+            this.timestamps.set(key, timestamp);
+            return true;
+        }
+        // Local is same age or newer — reject
+        return false;
+    }
+    async deferHeadUpdate(dbName, collectionName, blockId, timestamp) {
+        this.deferred.push({ dbName, collectionName, blockId, timestamp });
+    }
+    async applyDeferredUpdates(blockId) {
+        let applied = 0;
+        const remaining = [];
+        for (const update of this.deferred) {
+            if (update.blockId === blockId) {
+                await this.mergeHeadUpdate(update.dbName, update.collectionName, update.blockId, update.timestamp);
+                applied++;
+            }
+            else {
+                remaining.push(update);
+            }
+        }
+        this.deferred.length = 0;
+        this.deferred.push(...remaining);
+        return applied;
+    }
+    getDeferredUpdates() {
+        return [...this.deferred];
+    }
+    /**
+     * Factory method that creates an independent InMemoryHeadRegistry instance.
+     * Useful for tests that need isolated state.
+     */
+    static createIsolated() {
+        return new InMemoryHeadRegistry();
+    }
+}
+exports.InMemoryHeadRegistry = InMemoryHeadRegistry;
+//# sourceMappingURL=inMemoryHeadRegistry.js.map

package/src/lib/db/inMemoryHeadRegistry.js.map

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

package/src/lib/db/index.d.ts

@@ -0,0 +1,14 @@
+export * from './aggregation';
+export * from './collection';
+export * from './cursor';
+export * from './errors';
+export * from './indexing';
+export * from './inMemoryDatabase';
+export * from './inMemoryHeadRegistry';
+export * from './queryEngine';
+export * from './schemaValidation';
+export * from './transaction';
+export * from './types';
+export * from './updateEngine';
+export * from './uuidGenerator';
+//# sourceMappingURL=index.d.ts.map

package/src/lib/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/src/lib/db/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// db barrel – types & utilities first, building blocks, then higher-level components
+tslib_1.__exportStar(require("./aggregation"), exports);
+tslib_1.__exportStar(require("./collection"), exports);
+tslib_1.__exportStar(require("./cursor"), exports);
+tslib_1.__exportStar(require("./errors"), exports);
+tslib_1.__exportStar(require("./indexing"), exports);
+tslib_1.__exportStar(require("./inMemoryDatabase"), exports);
+tslib_1.__exportStar(require("./inMemoryHeadRegistry"), exports);
+tslib_1.__exportStar(require("./queryEngine"), exports);
+tslib_1.__exportStar(require("./schemaValidation"), exports);
+tslib_1.__exportStar(require("./transaction"), exports);
+tslib_1.__exportStar(require("./types"), exports);
+tslib_1.__exportStar(require("./updateEngine"), exports);
+tslib_1.__exportStar(require("./uuidGenerator"), exports);
+//# sourceMappingURL=index.js.map

package/src/lib/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/index.ts"],"names":[],"mappings":";;;AAAA,qFAAqF;AACrF,wDAA8B;AAC9B,uDAA6B;AAC7B,mDAAyB;AACzB,mDAAyB;AACzB,qDAA2B;AAC3B,6DAAmC;AACnC,iEAAuC;AACvC,wDAA8B;AAC9B,6DAAmC;AACnC,wDAA8B;AAC9B,kDAAwB;AACxB,yDAA+B;AAC/B,0DAAgC"}

package/src/lib/db/indexing.d.ts

@@ -0,0 +1,133 @@
+/**
+ * In-memory index engine for fast document lookups.
+ *
+ * Supports single-field and compound indexes with optional uniqueness.
+ * Indexes are stored as sorted maps from stringified key values to sets of document IDs.
+ */
+import type { IndexOptions, IndexSpec } from '@digitaldefiance/suite-core-lib';
+import type { BsonDocument, DocumentId } from '../interfaces/storage/documentTypes';
+/**
+ * Represents a single index on a collection.
+ */
+export declare class CollectionIndex {
+    /** Name of the index */
+    readonly name: string;
+    /** Fields and sort direction */
+    readonly spec: IndexSpec;
+    /** Whether the index enforces uniqueness */
+    readonly unique: boolean;
+    /** Whether to skip documents missing the indexed field */
+    readonly sparse: boolean;
+    /**
+     * Map from stringified key → Set of document IDs.
+     * For unique indexes the set will have at most 1 entry.
+     */
+    private readonly entries;
+    constructor(spec: IndexSpec, options?: IndexOptions);
+    /**
+     * Extract the index key from a document.
+     * Returns `undefined` if the document is missing a required field (and the index is sparse).
+     */
+    private extractKey;
+    /**
+     * Add a document to the index.
+     * @throws Error if the index is unique and a duplicate key is found.
+     */
+    addDocument(doc: BsonDocument): void;
+    /**
+     * Remove a document from the index.
+     */
+    removeDocument(doc: BsonDocument): void;
+    /**
+     * Look up document IDs by exact field values.
+     * Returns `undefined` if the query cannot use this index.
+     */
+    lookup(query: Record<string, unknown>): Set<DocumentId> | undefined;
+    /**
+     * Get all document IDs in the index.
+     */
+    allIds(): Set<DocumentId>;
+    /**
+     * Clear the index.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the index.
+     */
+    get size(): number;
+    /**
+     * Serialize the index metadata for persistence.
+     */
+    toJSON(): {
+        name: string;
+        spec: IndexSpec;
+        unique: boolean;
+        sparse: boolean;
+    };
+}
+/**
+ * Manages multiple indexes for a collection.
+ */
+export declare class IndexManager {
+    private readonly indexes;
+    /**
+     * Create a new index.
+     * @returns The name of the created index.
+     * @throws Error if an index with the same name already exists with different options.
+     */
+    createIndex(spec: IndexSpec, options?: IndexOptions): string;
+    /**
+     * Drop an index by name.
+     */
+    dropIndex(name: string): boolean;
+    /**
+     * Get all index names.
+     */
+    listIndexes(): string[];
+    /**
+     * Get an index by name.
+     */
+    getIndex(name: string): CollectionIndex | undefined;
+    /**
+     * Index a document in all indexes.
+     * @throws DuplicateKeyError if a unique constraint is violated.
+     */
+    addDocument(doc: BsonDocument): void;
+    /**
+     * Remove a document from all indexes.
+     */
+    removeDocument(doc: BsonDocument): void;
+    /**
+     * Rebuild all indexes from a set of documents.
+     */
+    rebuildAll(docs: BsonDocument[]): void;
+    /**
+     * Try to find an index that can serve the given query filter.
+     * Returns the set of matching document IDs if an index applies, otherwise undefined.
+     */
+    findCandidates(filter: Record<string, unknown>): Set<DocumentId> | undefined;
+    /**
+     * Serialize all index metadata for persistence.
+     */
+    toJSON(): Array<{
+        name: string;
+        spec: IndexSpec;
+        unique: boolean;
+        sparse: boolean;
+    }>;
+    /**
+     * Restore indexes from serialized metadata and rebuild from docs.
+     */
+    restoreFromJSON(metadata: Array<{
+        name: string;
+        spec: IndexSpec;
+        unique: boolean;
+        sparse: boolean;
+    }>, docs: BsonDocument[]): void;
+}
+export declare class DuplicateKeyError extends Error {
+    readonly indexName: string;
+    readonly keyValue: string;
+    constructor(indexName: string, keyValue: string);
+}
+//# sourceMappingURL=indexing.d.ts.map

package/src/lib/db/indexing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/indexing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACX,MAAM,qCAAqC,CAAC;AAE7C;;GAEG;AACH,qBAAa,eAAe;IAC1B,wBAAwB;IACxB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,gCAAgC;IAChC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,4CAA4C;IAC5C,SAAgB,MAAM,EAAE,OAAO,CAAC;IAChC,0DAA0D;IAC1D,SAAgB,MAAM,EAAE,OAAO,CAAC;IAEhC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;gBAElD,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,YAAiB;IAWvD;;;OAGG;IACH,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAuBpC;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAavC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,SAAS;IA+BnE;;OAEG;IACH,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC;IAQzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,MAAM,IAAI;QACR,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;KACjB;CAQF;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM;IAiBhE;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAInD;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAYpC;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAMvC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI;IAStC;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,SAAS;IAQ5E;;OAEG;IACH,MAAM,IAAI,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IAIF;;OAEG;IACH,eAAe,CACb,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC,EACF,IAAI,EAAE,YAAY,EAAE,GACnB,IAAI;CAUR;AAID,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAQhD"}