@powersync/common 0.0.0-dev-20260202162549 → 0.0.0-dev-20260202163643

package/lib/client/triggers/TriggerManagerImpl.js

@@ -0,0 +1,393 @@
+import { DEFAULT_WATCH_THROTTLE_MS } from '../watched/WatchedQuery.js';
+import { DiffTriggerOperation } from './TriggerManager.js';
+export const DEFAULT_TRIGGER_MANAGER_CONFIGURATION = {
+    useStorageByDefault: false
+};
+const TRIGGER_CLEANUP_INTERVAL_MS = 120_000; // 2 minutes
+/**
+ * @internal
+ * @experimental
+ */
+export class TriggerManagerImpl {
+    options;
+    schema;
+    defaultConfig;
+    cleanupTimeout;
+    isDisposed;
+    constructor(options) {
+        this.options = options;
+        this.schema = options.schema;
+        options.db.registerListener({
+            schemaChanged: (schema) => {
+                this.schema = schema;
+            }
+        });
+        this.isDisposed = false;
+        /**
+         * Configure a cleanup to run on an interval.
+         * The interval is configured using setTimeout to take the async
+         * execution time of the callback into account.
+         */
+        this.defaultConfig = DEFAULT_TRIGGER_MANAGER_CONFIGURATION;
+        const cleanupCallback = async () => {
+            this.cleanupTimeout = null;
+            if (this.isDisposed) {
+                return;
+            }
+            try {
+                await this.cleanupResources();
+            }
+            catch (ex) {
+                this.db.logger.error(`Caught error while attempting to cleanup triggers`, ex);
+            }
+            finally {
+                // if not closed, set another timeout
+                if (this.isDisposed) {
+                    return;
+                }
+                this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
+            }
+        };
+        this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
+    }
+    get db() {
+        return this.options.db;
+    }
+    async getUUID() {
+        const { id: uuid } = await this.db.get(/* sql */ `
+      SELECT
+        uuid () as id
+    `);
+        // Replace dashes with underscores for SQLite table/trigger name compatibility
+        return uuid.replace(/-/g, '_');
+    }
+    async removeTriggers(tx, triggerIds) {
+        for (const triggerId of triggerIds) {
+            await tx.execute(/* sql */ `DROP TRIGGER IF EXISTS ${triggerId}; `);
+        }
+    }
+    dispose() {
+        this.isDisposed = true;
+        if (this.cleanupTimeout) {
+            clearTimeout(this.cleanupTimeout);
+        }
+    }
+    /**
+     * Updates default config settings for platform specific use-cases.
+     */
+    updateDefaults(config) {
+        this.defaultConfig = {
+            ...this.defaultConfig,
+            ...config
+        };
+    }
+    generateTriggerName(operation, destinationTable, triggerId) {
+        return `__ps_temp_trigger_${operation.toLowerCase()}__${destinationTable}__${triggerId}`;
+    }
+    /**
+     * Cleanup any SQLite triggers or tables that are no longer in use.
+     */
+    async cleanupResources() {
+        // we use the database here since cleanupResources is called during the PowerSyncDatabase initialization
+        await this.db.database.writeLock(async (ctx) => {
+            /**
+             * Note: We only cleanup persisted triggers. These are tracked in the sqlite_master table.
+             * temporary triggers will not be affected by this.
+             * Query all triggers that match our naming pattern
+             */
+            const triggers = await ctx.getAll(/* sql */ `
+        SELECT
+          name
+        FROM
+          sqlite_master
+        WHERE
+          type = 'trigger'
+          AND name LIKE '__ps_temp_trigger_%'
+      `);
+            /** Use regex to extract table names and IDs from trigger names
+             * Trigger naming convention: __ps_temp_trigger_<operation>__<destination_table>__<id>
+             */
+            const triggerPattern = /^__ps_temp_trigger_(?:insert|update|delete)__(.+)__([a-f0-9_]{36})$/i;
+            const trackedItems = new Map();
+            for (const trigger of triggers) {
+                const match = trigger.name.match(triggerPattern);
+                if (match) {
+                    const [, table, id] = match;
+                    // Collect all trigger names for each id combo
+                    const existing = trackedItems.get(id);
+                    if (existing) {
+                        existing.triggerNames.push(trigger.name);
+                    }
+                    else {
+                        trackedItems.set(id, { table, id, triggerNames: [trigger.name] });
+                    }
+                }
+            }
+            for (const trackedItem of trackedItems.values()) {
+                // check if there is anything holding on to this item
+                const hasClaim = await this.options.claimManager.checkClaim(trackedItem.id);
+                if (hasClaim) {
+                    // This does not require cleanup
+                    continue;
+                }
+                this.db.logger.debug(`Clearing resources for trigger ${trackedItem.id} with table ${trackedItem.table}`);
+                // We need to delete the triggers and table
+                for (const triggerName of trackedItem.triggerNames) {
+                    await ctx.execute(`DROP TRIGGER IF EXISTS ${triggerName}`);
+                }
+                await ctx.execute(`DROP TABLE IF EXISTS ${trackedItem.table}`);
+            }
+        });
+    }
+    async createDiffTrigger(options) {
+        await this.db.waitForReady();
+        const { source, destination, columns, when, hooks, 
+        // Fall back to the provided default if not given on this level
+        useStorage = this.defaultConfig.useStorageByDefault } = options;
+        const operations = Object.keys(when);
+        if (operations.length == 0) {
+            throw new Error('At least one WHEN operation must be specified for the trigger.');
+        }
+        /**
+         * The clause to use when executing
+         * CREATE ${tableTriggerTypeClause} TABLE
+         * OR
+         * CREATE ${tableTriggerTypeClause} TRIGGER
+         */
+        const tableTriggerTypeClause = !useStorage ? 'TEMP' : '';
+        const whenClauses = Object.fromEntries(Object.entries(when).map(([operation, filter]) => [operation, `WHEN ${filter}`]));
+        /**
+         * Allow specifying the View name as the source.
+         * We can lookup the internal table name from the schema.
+         */
+        const sourceDefinition = this.schema.tables.find((table) => table.viewName == source);
+        if (!sourceDefinition) {
+            throw new Error(`Source table or view "${source}" not found in the schema.`);
+        }
+        const replicatedColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
+        const internalSource = sourceDefinition.internalName;
+        const triggerIds = [];
+        const id = await this.getUUID();
+        const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
+        /**
+         * We default to replicating all columns if no columns array is provided.
+         */
+        const jsonFragment = (source = 'NEW') => {
+            if (columns == null) {
+                // Track all columns
+                return `${source}.data`;
+            }
+            else if (columns.length == 0) {
+                // Don't track any columns except for the id
+                return `'{}'`;
+            }
+            else {
+                // Filter the data by the replicated columns
+                return `json_object(${replicatedColumns.map((col) => `'${col}', json_extract(${source}.data, '$.${col}')`).join(', ')})`;
+            }
+        };
+        const disposeWarningListener = this.db.registerListener({
+            schemaChanged: () => {
+                this.db.logger.warn(`The PowerSync schema has changed while previously configured triggers are still operational. This might cause unexpected results.`);
+            }
+        });
+        /**
+         * Declare the cleanup function early since if any of the init steps fail,
+         * we need to ensure we can cleanup the created resources.
+         * We unfortunately cannot rely on transaction rollback.
+         */
+        const cleanup = async () => {
+            disposeWarningListener();
+            return this.db.writeLock(async (tx) => {
+                await this.removeTriggers(tx, triggerIds);
+                await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+                await releaseStorageClaim?.();
+            });
+        };
+        const setup = async (tx) => {
+            // Allow user code to execute in this lock context before the trigger is created.
+            await hooks?.beforeCreate?.(tx);
+            await tx.execute(/* sql */ `
+        CREATE ${tableTriggerTypeClause} TABLE ${destination} (
+          operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+          id TEXT,
+          operation TEXT,
+          timestamp TEXT,
+          value TEXT,
+          previous_value TEXT
+        )
+      `);
+            if (operations.includes(DiffTriggerOperation.INSERT)) {
+                const insertTriggerId = this.generateTriggerName(DiffTriggerOperation.INSERT, destination, id);
+                triggerIds.push(insertTriggerId);
+                await tx.execute(/* sql */ `
+          CREATE ${tableTriggerTypeClause} TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[DiffTriggerOperation.INSERT]} BEGIN
+          INSERT INTO
+            ${destination} (id, operation, timestamp, value)
+          VALUES
+            (
+              NEW.id,
+              'INSERT',
+              strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              ${jsonFragment('NEW')}
+            );
+
+          END
+        `);
+            }
+            if (operations.includes(DiffTriggerOperation.UPDATE)) {
+                const updateTriggerId = this.generateTriggerName(DiffTriggerOperation.UPDATE, destination, id);
+                triggerIds.push(updateTriggerId);
+                await tx.execute(/* sql */ `
+          CREATE ${tableTriggerTypeClause} TRIGGER ${updateTriggerId} AFTER
+          UPDATE ON ${internalSource} ${whenClauses[DiffTriggerOperation.UPDATE]} BEGIN
+          INSERT INTO
+            ${destination} (id, operation, timestamp, value, previous_value)
+          VALUES
+            (
+              NEW.id,
+              'UPDATE',
+              strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              ${jsonFragment('NEW')},
+              ${jsonFragment('OLD')}
+            );
+
+          END;
+        `);
+            }
+            if (operations.includes(DiffTriggerOperation.DELETE)) {
+                const deleteTriggerId = this.generateTriggerName(DiffTriggerOperation.DELETE, destination, id);
+                triggerIds.push(deleteTriggerId);
+                // Create delete trigger for basic JSON
+                await tx.execute(/* sql */ `
+          CREATE ${tableTriggerTypeClause} TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[DiffTriggerOperation.DELETE]} BEGIN
+          INSERT INTO
+            ${destination} (id, operation, timestamp, value)
+          VALUES
+            (
+              OLD.id,
+              'DELETE',
+              strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              ${jsonFragment('OLD')}
+            );
+
+          END;
+        `);
+            }
+        };
+        try {
+            await this.db.writeLock(setup);
+            return cleanup;
+        }
+        catch (error) {
+            try {
+                await cleanup();
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], 'Error during operation and cleanup');
+            }
+            throw error;
+        }
+    }
+    async trackTableDiff(options) {
+        const { source, when, columns, hooks, throttleMs = DEFAULT_WATCH_THROTTLE_MS } = options;
+        await this.db.waitForReady();
+        /**
+         * Allow specifying the View name as the source.
+         * We can lookup the internal table name from the schema.
+         */
+        const sourceDefinition = this.schema.tables.find((table) => table.viewName == source);
+        if (!sourceDefinition) {
+            throw new Error(`Source table or view "${source}" not found in the schema.`);
+        }
+        // The columns to present in the onChange context methods.
+        // If no array is provided, we use all columns from the source table.
+        const contextColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
+        const id = await this.getUUID();
+        const destination = `__ps_temp_track_${source}_${id}`;
+        // register an onChange before the trigger is created
+        const abortController = new AbortController();
+        const abortOnChange = () => abortController.abort();
+        this.db.onChange({
+            // Note that the onChange events here have their execution scheduled.
+            // Callbacks are throttled and are sequential.
+            onChange: async () => {
+                if (abortController.signal.aborted)
+                    return;
+                // Run the handler in a write lock to keep the state of the
+                // destination table consistent.
+                await this.db.writeTransaction(async (tx) => {
+                    const callbackResult = await options.onChange({
+                        ...tx,
+                        destinationTable: destination,
+                        withDiff: async (query, params, options) => {
+                            // Wrap the query to expose the destination table
+                            const operationIdSelect = options?.castOperationIdAsText
+                                ? 'id, operation, CAST(operation_id AS TEXT) as operation_id, timestamp, value, previous_value'
+                                : '*';
+                            const wrappedQuery = /* sql */ `
+                  WITH
+                    DIFF AS (
+                      SELECT
+                        ${operationIdSelect}
+                      FROM
+                        ${destination}
+                      ORDER BY
+                        operation_id ASC
+                    ) ${query}
+                `;
+                            return tx.getAll(wrappedQuery, params);
+                        },
+                        withExtractedDiff: async (query, params) => {
+                            // Wrap the query to expose the destination table
+                            const wrappedQuery = /* sql */ `
+                  WITH
+                    DIFF AS (
+                      SELECT
+                        id,
+                        ${contextColumns.length > 0
+                                ? `${contextColumns.map((col) => `json_extract(value, '$.${col}') as ${col}`).join(', ')},`
+                                : ''} operation_id as __operation_id,
+                        operation as __operation,
+                        timestamp as __timestamp,
+                        previous_value as __previous_value
+                      FROM
+                        ${destination}
+                      ORDER BY
+                        __operation_id ASC
+                    ) ${query}
+                `;
+                            return tx.getAll(wrappedQuery, params);
+                        }
+                    });
+                    // Clear the destination table after processing
+                    await tx.execute(/* sql */ `DELETE FROM ${destination};`);
+                    return callbackResult;
+                });
+            }
+        }, { tables: [destination], signal: abortController.signal, throttleMs });
+        try {
+            const removeTrigger = await this.createDiffTrigger({
+                source,
+                destination,
+                columns: contextColumns,
+                when,
+                hooks
+            });
+            return async () => {
+                abortOnChange();
+                await removeTrigger();
+            };
+        }
+        catch (error) {
+            try {
+                abortOnChange();
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], 'Error during operation and cleanup');
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=TriggerManagerImpl.js.map

package/lib/client/triggers/TriggerManagerImpl.js.map

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

package/lib/client/triggers/sanitizeSQL.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export declare function sanitizeUUID(uuid: string): string;
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = sanitizeSQL`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+export declare function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string;

package/lib/client/triggers/sanitizeSQL.js

@@ -0,0 +1,69 @@
+function sanitizeString(input) {
+    return `'${input.replace(/'/g, "''")}'`;
+}
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export function sanitizeUUID(uuid) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    const isValid = uuidRegex.test(uuid);
+    if (!isValid) {
+        throw new Error(`${uuid} is not a valid UUID`);
+    }
+    return uuid;
+}
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = sanitizeSQL`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+export function sanitizeSQL(strings, ...values) {
+    let result = '';
+    strings.forEach((str, i) => {
+        result += str;
+        if (i < values.length) {
+            // For SQL, escape single quotes in string values
+            const value = values[i];
+            if (typeof value == 'string') {
+                result += sanitizeString(value);
+            }
+            else if (value == null) {
+                result += 'NULL';
+            }
+            else if (typeof value == 'object') {
+                // Stringify the object and escape single quotes in the result
+                const stringified = JSON.stringify(value);
+                result += sanitizeString(stringified);
+            }
+            else {
+                result += value;
+            }
+        }
+    });
+    return result;
+}
+//# sourceMappingURL=sanitizeSQL.js.map

package/lib/client/triggers/sanitizeSQL.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeSQL.js","sourceRoot":"","sources":["../../../src/client/triggers/sanitizeSQL.ts"],"names":[],"mappings":"AAAA,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAC1C,CAAC;AACD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,SAAS,GAAG,4EAA4E,CAAC;IAC/F,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,sBAAsB,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,WAAW,CAAC,OAA6B,EAAE,GAAG,MAAa;IACzE,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,CAAC;QACd,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YACtB,iDAAiD;YACjD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,OAAO,KAAK,IAAI,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,cAAc,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;iBAAM,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBACzB,MAAM,IAAI,MAAM,CAAC;YACnB,CAAC;iBAAM,IAAI,OAAO,KAAK,IAAI,QAAQ,EAAE,CAAC;gBACpC,8DAA8D;gBAC9D,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBAC1C,MAAM,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC;YACxC,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/client/watched/GetAllQuery.d.ts

@@ -0,0 +1,32 @@
+import { CompiledQuery } from '../../types/types.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { WatchCompatibleQuery } from './WatchedQuery.js';
+/**
+ * Options for {@link GetAllQuery}.
+ */
+export type GetAllQueryOptions<RowType = unknown> = {
+    sql: string;
+    parameters?: ReadonlyArray<unknown>;
+    /**
+     * Optional mapper function to convert raw rows into the desired RowType.
+     * @example
+     * ```javascript
+     * (rawRow) => ({
+     *   id: rawRow.id,
+     *   created_at: new Date(rawRow.created_at),
+     * })
+     * ```
+     */
+    mapper?: (rawRow: Record<string, unknown>) => RowType;
+};
+/**
+ * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ */
+export declare class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
+    protected options: GetAllQueryOptions<RowType>;
+    constructor(options: GetAllQueryOptions<RowType>);
+    compile(): CompiledQuery;
+    execute(options: {
+        db: AbstractPowerSyncDatabase;
+    }): Promise<RowType[]>;
+}

package/lib/client/watched/GetAllQuery.js

@@ -0,0 +1,25 @@
+/**
+ * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ */
+export class GetAllQuery {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    compile() {
+        return {
+            sql: this.options.sql,
+            parameters: this.options.parameters ?? []
+        };
+    }
+    async execute(options) {
+        const { db } = options;
+        const { sql, parameters = [] } = this.compile();
+        const rawResult = await db.getAll(sql, [...parameters]);
+        if (this.options.mapper) {
+            return rawResult.map(this.options.mapper);
+        }
+        return rawResult;
+    }
+}
+//# sourceMappingURL=GetAllQuery.js.map

package/lib/client/watched/GetAllQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetAllQuery.js","sourceRoot":"","sources":["../../../src/client/watched/GetAllQuery.ts"],"names":[],"mappings":"AAuBA;;GAEG;AACH,MAAM,OAAO,WAAW;IACA;IAAtB,YAAsB,OAAoC;QAApC,YAAO,GAAP,OAAO,CAA6B;IAAG,CAAC;IAE9D,OAAO;QACL,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;YACrB,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE;SAC1C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAA0C;QACtD,MAAM,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;QACvB,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC,MAAM,CAAU,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;QACjE,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,SAAsB,CAAC;IAChC,CAAC;CACF"}