@yydb/light-db 0.0.0 → 0.0.10

package/dist/core/engine.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 存储引擎
+ *
+ * 只处理数据库语义：记录、WAL、检查点、恢复与事务。
+ * 所有平台能力都经 `StorageAdapter`，本层不接触浏览器或 Node 文件 API。
+ */
+import type { StorageAdapterFactory } from '../storage/StorageAdapter';
+import type { LeaseMode } from './lease';
+/** 默认 WAL 阈值：16MB */
+export declare const DEFAULT_WAL_THRESHOLD: number;
+/** 存储引擎选项 */
+export interface StorageEngineOptions {
+    /** 页大小，默认 4KB */
+    pageSize?: number;
+    /** WAL 字节阈值，超过后自动检查点，默认 16MB */
+    walThreshold?: number;
+    /** 是否自动检查点，默认 true */
+    autoCheckpoint?: boolean;
+    /** 写租约模式，默认 `web-locks` */
+    lease?: LeaseMode;
+}
+/** 事务状态 */
+export type TransactionState = 'idle' | 'active';
+/** 检查点结果 */
+export interface CheckpointResult {
+    /** 检查点覆盖到的 LSN */
+    lsn: bigint;
+    /** 写入字节数 */
+    bytesWritten: number;
+    /** WAL 截断前的字节数 */
+    walBytesReleased: number;
+}
+/** 引擎统计 */
+export interface StorageEngineStats {
+    /** 数据库名 */
+    name: string;
+    /** 当前 LSN */
+    lsn: bigint;
+    /** 记录数量 */
+    recordCount: number;
+    /** WAL 当前字节数 */
+    walBytes: number;
+    /** 页大小 */
+    pageSize: number;
+    /** 适配器类型 */
+    storageKind: string;
+    /** 数据是否持久化 */
+    persistent: boolean;
+    /** 事务状态 */
+    transactionState: TransactionState;
+}
+/**
+ * 存储引擎
+ */
+export declare class StorageEngine {
+    private readonly databaseName;
+    private readonly adapter;
+    private readonly store;
+    private readonly wal;
+    private readonly checkpointWriter;
+    private readonly broadcaster;
+    private readonly lease;
+    private readonly options;
+    private lastLsn;
+    private nextTransactionId;
+    private overlay;
+    private closed;
+    private constructor();
+    /**
+     * 打开数据库
+     * @param name 数据库名
+     * @param factory 存储适配器工厂
+     * @param options 引擎选项
+     */
+    static open(name: string, factory: StorageAdapterFactory, options?: StorageEngineOptions): Promise<StorageEngine>;
+    /** 数据库名 */
+    get name(): string;
+    /** 当前 LSN */
+    get lsn(): bigint;
+    /** 事务状态 */
+    get transactionState(): TransactionState;
+    /** 是否已关闭 */
+    get isClosed(): boolean;
+    /**
+     * 读取键
+     * @param key 键
+     */
+    get(key: string): Promise<Uint8Array | null>;
+    /**
+     * 写入键
+     * @param key 键
+     * @param value 值
+     */
+    put(key: string, value: Uint8Array): Promise<void>;
+    /**
+     * 删除键
+     * @param key 键
+     * @returns 键存在时返回 true
+     */
+    delete(key: string): Promise<boolean>;
+    /** 开启事务 */
+    begin(): void;
+    /**
+     * 提交事务
+     */
+    commit(): Promise<void>;
+    /** 回滚事务 */
+    rollback(): void;
+    /**
+     * 执行检查点
+     */
+    checkpoint(): Promise<CheckpointResult>;
+    /** 广播 schema 变更，供其它标签页失效本地视图 */
+    notifySchemaChange(): void;
+    /** 统计信息 */
+    getStats(): StorageEngineStats;
+    /** 关闭引擎 */
+    close(): Promise<void>;
+    /**
+     * 追加 WAL 并应用记录
+     * @param mutations 变更
+     * @param transactionId 事务号
+     */
+    private applyCommitted;
+    /**
+     * 判断键在当前视图（含事务覆盖层）是否存在
+     * @param key 键
+     */
+    private existsInView;
+    /**
+     * 断言引擎未关闭
+     * @param operation 操作名
+     */
+    private assertOpen;
+    /**
+     * 断言键合法
+     * @param key 键
+     * @param operation 操作名
+     */
+    private assertKey;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/engine.d.ts.map

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

package/dist/core/engine.js

@@ -0,0 +1,304 @@
+/**
+ * 存储引擎
+ *
+ * 只处理数据库语义：记录、WAL、检查点、恢复与事务。
+ * 所有平台能力都经 `StorageAdapter`，本层不接触浏览器或 Node 文件 API。
+ */
+import { BinaryUtils, DEFAULT_PAGE_SIZE, WalOperation } from '../codec';
+import { LightDbError, LightDbErrorCodes } from '../errors';
+import { DatabaseBroadcaster } from './broadcast';
+import { CheckpointWriter } from './checkpoint';
+import { acquireWriterLease } from './lease';
+import { RecordStore } from './records';
+import { RecoveryManager } from './recovery';
+import { WalLog } from './wal';
+/** 默认 WAL 阈值：16MB */
+export const DEFAULT_WAL_THRESHOLD = 16 * 1024 * 1024;
+/**
+ * 存储引擎
+ */
+export class StorageEngine {
+    databaseName;
+    adapter;
+    store;
+    wal;
+    checkpointWriter;
+    broadcaster;
+    lease;
+    options;
+    lastLsn;
+    nextTransactionId;
+    overlay;
+    closed;
+    constructor(name, adapter, wal, lease, options, lastLsn) {
+        this.databaseName = name;
+        this.adapter = adapter;
+        this.wal = wal;
+        this.store = new RecordStore();
+        this.checkpointWriter = new CheckpointWriter(adapter, options.pageSize);
+        this.broadcaster = new DatabaseBroadcaster(name);
+        this.lease = lease;
+        this.options = options;
+        this.lastLsn = lastLsn;
+        this.nextTransactionId = 1n;
+        this.overlay = null;
+        this.closed = false;
+    }
+    /**
+     * 打开数据库
+     * @param name 数据库名
+     * @param factory 存储适配器工厂
+     * @param options 引擎选项
+     */
+    static async open(name, factory, options = {}) {
+        const resolved = {
+            pageSize: options.pageSize ?? DEFAULT_PAGE_SIZE,
+            walThreshold: options.walThreshold ?? DEFAULT_WAL_THRESHOLD,
+            autoCheckpoint: options.autoCheckpoint ?? true,
+        };
+        if (resolved.pageSize < 512) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'page size must be at least 512 bytes', {
+                operation: 'open',
+            });
+        }
+        const lease = await acquireWriterLease(name, options.lease ?? 'web-locks');
+        let adapter = null;
+        try {
+            adapter = await factory.openDatabase(name);
+            const wal = new WalLog(adapter);
+            await wal.open();
+            const recovery = new RecoveryManager(adapter);
+            const outcome = await recovery.recover(wal);
+            const engine = new StorageEngine(name, adapter, wal, lease, resolved, outcome.lastLsn);
+            engine.store.restore(outcome.records);
+            return engine;
+        }
+        catch (error) {
+            if (adapter) {
+                await adapter.close();
+            }
+            await lease.release();
+            if (error instanceof LightDbError) {
+                throw error;
+            }
+            throw new LightDbError(LightDbErrorCodes.io, `failed to open database "${name}"`, {
+                operation: 'open',
+                cause: error,
+            });
+        }
+    }
+    /** 数据库名 */
+    get name() {
+        return this.databaseName;
+    }
+    /** 当前 LSN */
+    get lsn() {
+        return this.lastLsn;
+    }
+    /** 事务状态 */
+    get transactionState() {
+        return this.overlay ? 'active' : 'idle';
+    }
+    /** 是否已关闭 */
+    get isClosed() {
+        return this.closed;
+    }
+    /**
+     * 读取键
+     * @param key 键
+     */
+    async get(key) {
+        this.assertOpen('kvGet');
+        this.assertKey(key, 'kvGet');
+        if (this.overlay?.has(key)) {
+            const pending = this.overlay.get(key);
+            return pending.operation === WalOperation.Delete ? null : BinaryUtils.copy(pending.value);
+        }
+        return this.store.get(key);
+    }
+    /**
+     * 写入键
+     * @param key 键
+     * @param value 值
+     */
+    async put(key, value) {
+        this.assertOpen('kvPut');
+        this.assertKey(key, 'kvPut');
+        if (this.overlay) {
+            this.overlay.set(key, { operation: WalOperation.Put, value: BinaryUtils.copy(value) });
+            return;
+        }
+        await this.applyCommitted([{ operation: WalOperation.Put, key, value: BinaryUtils.copy(value) }]);
+    }
+    /**
+     * 删除键
+     * @param key 键
+     * @returns 键存在时返回 true
+     */
+    async delete(key) {
+        this.assertOpen('kvDelete');
+        this.assertKey(key, 'kvDelete');
+        if (this.overlay) {
+            const exists = this.existsInView(key);
+            this.overlay.set(key, { operation: WalOperation.Delete, value: null });
+            return exists;
+        }
+        if (!this.store.has(key)) {
+            return false;
+        }
+        await this.applyCommitted([{ operation: WalOperation.Delete, key, value: null }]);
+        return true;
+    }
+    /** 开启事务 */
+    begin() {
+        this.assertOpen('begin');
+        if (this.overlay) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'a transaction is already active', {
+                operation: 'begin',
+            });
+        }
+        this.overlay = new Map();
+    }
+    /**
+     * 提交事务
+     */
+    async commit() {
+        this.assertOpen('commit');
+        if (!this.overlay) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'no active transaction', { operation: 'commit' });
+        }
+        const pending = this.overlay;
+        this.overlay = null;
+        if (pending.size === 0) {
+            return;
+        }
+        const transactionId = this.nextTransactionId++;
+        const mutations = [];
+        for (const [key, mutation] of pending) {
+            mutations.push({ operation: mutation.operation, key, value: mutation.value });
+        }
+        await this.applyCommitted(mutations, transactionId);
+    }
+    /** 回滚事务 */
+    rollback() {
+        this.assertOpen('rollback');
+        if (!this.overlay) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'no active transaction', { operation: 'rollback' });
+        }
+        this.overlay = null;
+    }
+    /**
+     * 执行检查点
+     */
+    async checkpoint() {
+        this.assertOpen('checkpoint');
+        if (this.overlay) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'cannot checkpoint during a transaction', {
+                operation: 'checkpoint',
+            });
+        }
+        const walBytesReleased = this.wal.byteSize;
+        const bytesWritten = await this.checkpointWriter.write(this.store.snapshot(), this.lastLsn);
+        await this.wal.truncate(0);
+        return { lsn: this.lastLsn, bytesWritten, walBytesReleased };
+    }
+    /** 广播 schema 变更，供其它标签页失效本地视图 */
+    notifySchemaChange() {
+        this.assertOpen('notifySchemaChange');
+        this.broadcaster.notify({ type: 'schema', name: this.databaseName });
+    }
+    /** 统计信息 */
+    getStats() {
+        this.assertOpen('stats');
+        return {
+            name: this.databaseName,
+            lsn: this.lastLsn,
+            recordCount: this.store.size,
+            walBytes: this.wal.byteSize,
+            pageSize: this.options.pageSize,
+            storageKind: this.adapter.kind,
+            persistent: this.adapter.persistent,
+            transactionState: this.transactionState,
+        };
+    }
+    /** 关闭引擎 */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.overlay = null;
+        this.broadcaster.notify({ type: 'close', name: this.databaseName });
+        this.broadcaster.close();
+        try {
+            await this.wal.close();
+        }
+        finally {
+            try {
+                await this.adapter.close();
+            }
+            finally {
+                await this.lease.release();
+            }
+        }
+    }
+    /**
+     * 追加 WAL 并应用记录
+     * @param mutations 变更
+     * @param transactionId 事务号
+     */
+    async applyCommitted(mutations, transactionId = 0n) {
+        const records = mutations.map((mutation) => ({
+            lsn: ++this.lastLsn,
+            transactionId,
+            operation: mutation.operation,
+            key: mutation.key,
+            value: mutation.value,
+        }));
+        await this.wal.append(records);
+        for (const mutation of mutations) {
+            if (mutation.operation === WalOperation.Delete) {
+                this.store.delete(mutation.key);
+            }
+            else if (mutation.value) {
+                this.store.put(mutation.key, mutation.value);
+            }
+        }
+        this.broadcaster.notify({ type: 'commit', name: this.databaseName, lsn: this.lastLsn.toString() });
+        if (this.options.autoCheckpoint && this.wal.byteSize >= this.options.walThreshold) {
+            await this.checkpoint();
+        }
+    }
+    /**
+     * 判断键在当前视图（含事务覆盖层）是否存在
+     * @param key 键
+     */
+    existsInView(key) {
+        if (this.overlay?.has(key)) {
+            return this.overlay.get(key).operation === WalOperation.Put;
+        }
+        return this.store.has(key);
+    }
+    /**
+     * 断言引擎未关闭
+     * @param operation 操作名
+     */
+    assertOpen(operation) {
+        if (this.closed) {
+            throw new LightDbError(LightDbErrorCodes.sessionClosed, `database "${this.databaseName}" is closed`, {
+                operation,
+            });
+        }
+    }
+    /**
+     * 断言键合法
+     * @param key 键
+     * @param operation 操作名
+     */
+    assertKey(key, operation) {
+        if (key.length === 0) {
+            throw new LightDbError(LightDbErrorCodes.unsupported, 'key must not be empty', { operation });
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/engine.js.map

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

package/dist/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * core 层导出
+ *
+ * 数据库语义、事务、恢复与单写者合同，不依赖具体存储后端。
+ */
+export { RecordStore } from './records';
+export { WalLog } from './wal';
+export { CheckpointWriter } from './checkpoint';
+export { RecoveryManager } from './recovery';
+export type { RecoveryOutcome } from './recovery';
+export { acquireWriterLease } from './lease';
+export type { LeaseMode, WriterLease } from './lease';
+export { DatabaseBroadcaster, listenDatabaseEvents } from './broadcast';
+export type { DatabaseEvent, DatabaseEventType } from './broadcast';
+export { StorageEngine, DEFAULT_WAL_THRESHOLD } from './engine';
+export type { CheckpointResult, StorageEngineOptions, StorageEngineStats, TransactionState } from './engine';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC7C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAChE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * core 层导出
+ *
+ * 数据库语义、事务、恢复与单写者合同，不依赖具体存储后端。
+ */
+export { RecordStore } from './records';
+export { WalLog } from './wal';
+export { CheckpointWriter } from './checkpoint';
+export { RecoveryManager } from './recovery';
+export { acquireWriterLease } from './lease';
+export { DatabaseBroadcaster, listenDatabaseEvents } from './broadcast';
+export { StorageEngine, DEFAULT_WAL_THRESHOLD } from './engine';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExE,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/lease.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 单写者租约
+ *
+ * 浏览器多标签页共享同一份 OPFS 数据，写者必须互斥。
+ * 首选 Web Locks，缺失时不静默退化成多写者。
+ */
+/** 写租约 */
+export interface WriterLease {
+    /** 释放租约 */
+    release(): Promise<void>;
+}
+/** 租约模式 */
+export type LeaseMode = 'web-locks' | 'none';
+/** Web Locks 结构化类型，避免引入 DOM lib */
+interface LockManagerLike {
+    request(name: string, options: {
+        mode: 'exclusive';
+        ifAvailable: true;
+    }, callback: (lock: unknown) => Promise<void>): Promise<void>;
+}
+/**
+ * 获取写租约
+ *
+ * @param databaseName 数据库名，用作锁名
+ * @param mode `web-locks` 走 Web Locks，`none` 表示调用方自行保证单写者（测试或单上下文）
+ * @param locks 可注入的锁实现，`null` 表示显式缺失，省略时读取宿主
+ * @returns 写租约
+ * @throws LightDbError `yydb.lease.unavailable` 当环境没有 Web Locks 或锁已被占用
+ */
+export declare function acquireWriterLease(databaseName: string, mode: LeaseMode, locks?: LockManagerLike | null): Promise<WriterLease>;
+export {};
+//# sourceMappingURL=lease.d.ts.map

package/dist/core/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../src/core/lease.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,UAAU;AACV,MAAM,WAAW,WAAW;IACxB,WAAW;IACX,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,WAAW;AACX,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE7C,mCAAmC;AACnC,UAAU,eAAe;IACrB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,IAAI,CAAA;KAAE,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvI;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAoEpI"}

package/dist/core/lease.js

@@ -0,0 +1,81 @@
+/**
+ * 单写者租约
+ *
+ * 浏览器多标签页共享同一份 OPFS 数据，写者必须互斥。
+ * 首选 Web Locks，缺失时不静默退化成多写者。
+ */
+import { LightDbError, LightDbErrorCodes } from '../errors';
+/**
+ * 获取写租约
+ *
+ * @param databaseName 数据库名，用作锁名
+ * @param mode `web-locks` 走 Web Locks，`none` 表示调用方自行保证单写者（测试或单上下文）
+ * @param locks 可注入的锁实现，`null` 表示显式缺失，省略时读取宿主
+ * @returns 写租约
+ * @throws LightDbError `yydb.lease.unavailable` 当环境没有 Web Locks 或锁已被占用
+ */
+export async function acquireWriterLease(databaseName, mode, locks) {
+    if (mode === 'none') {
+        return { release: async () => undefined };
+    }
+    const manager = locks === undefined ? getLockManager() : locks;
+    if (!manager) {
+        throw new LightDbError(LightDbErrorCodes.leaseUnavailable, 'Web Locks is unavailable, refusing to open a second writer', {
+            operation: 'acquireWriteLease',
+        });
+    }
+    let releaseHold = () => undefined;
+    const hold = new Promise((resolve) => {
+        releaseHold = resolve;
+    });
+    let settled = false;
+    let released = false;
+    let completion = Promise.resolve();
+    const acquired = new Promise((resolve, reject) => {
+        completion = manager
+            .request(`yydb:${databaseName}`, { mode: 'exclusive', ifAvailable: true }, async (lock) => {
+            if (!lock) {
+                if (!settled) {
+                    settled = true;
+                    reject(new LightDbError(LightDbErrorCodes.leaseUnavailable, 'database is opened by another writer', {
+                        operation: 'acquireWriteLease',
+                    }));
+                }
+                return;
+            }
+            if (!settled) {
+                settled = true;
+                resolve();
+            }
+            await hold;
+        })
+            .catch((error) => {
+            if (!settled) {
+                settled = true;
+                reject(new LightDbError(LightDbErrorCodes.leaseUnavailable, 'failed to acquire the writer lease', {
+                    operation: 'acquireWriteLease',
+                    cause: error,
+                }));
+            }
+        });
+    });
+    await acquired;
+    return {
+        release: async () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            releaseHold();
+            await completion.catch(() => undefined);
+        },
+    };
+}
+/**
+ * 取得宿主的 Web Locks 实现
+ */
+function getLockManager() {
+    const navigatorLike = globalThis.navigator;
+    return navigatorLike?.locks ?? null;
+}
+//# sourceMappingURL=lease.js.map

package/dist/core/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../src/core/lease.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAgB5D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,YAAoB,EAAE,IAAe,EAAE,KAA8B;IAC1G,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;IAC9C,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,4DAA4D,EAAE;YACrH,SAAS,EAAE,mBAAmB;SACjC,CAAC,CAAC;IACP,CAAC;IAED,IAAI,WAAW,GAAe,GAAG,EAAE,CAAC,SAAS,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACvC,WAAW,GAAG,OAAO,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,UAAU,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAElD,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnD,UAAU,GAAG,OAAO;aACf,OAAO,CAAC,QAAQ,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtF,IAAI,CAAC,IAAI,EAAE,CAAC;gBACR,IAAI,CAAC,OAAO,EAAE,CAAC;oBACX,OAAO,GAAG,IAAI,CAAC;oBACf,MAAM,CACF,IAAI,YAAY,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,sCAAsC,EAAE;wBACzF,SAAS,EAAE,mBAAmB;qBACjC,CAAC,CACL,CAAC;gBACN,CAAC;gBACD,OAAO;YACX,CAAC;YAED,IAAI,CAAC,OAAO,EAAE,CAAC;gBACX,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,EAAE,CAAC;YACd,CAAC;YAED,MAAM,IAAI,CAAC;QACf,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACtB,IAAI,CAAC,OAAO,EAAE,CAAC;gBACX,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM,CACF,IAAI,YAAY,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,oCAAoC,EAAE;oBACvF,SAAS,EAAE,mBAAmB;oBAC9B,KAAK,EAAE,KAAK;iBACf,CAAC,CACL,CAAC;YACN,CAAC;QACL,CAAC,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC;IAEf,OAAO;QACH,OAAO,EAAE,KAAK,IAAI,EAAE;YAChB,IAAI,QAAQ,EAAE,CAAC;gBACX,OAAO;YACX,CAAC;YACD,QAAQ,GAAG,IAAI,CAAC;YAChB,WAAW,EAAE,CAAC;YACd,MAAM,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,CAAC;KACJ,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAS,cAAc;IACnB,MAAM,aAAa,GAAI,UAA0D,CAAC,SAAS,CAAC;IAC5F,OAAO,aAAa,EAAE,KAAK,IAAI,IAAI,CAAC;AACxC,CAAC"}