@hypequery/clickhouse 2.0.0 → 2.0.2

package/dist/migrations/plan/plan.js

@@ -0,0 +1,416 @@
+/**
+ * Converts a raw snapshot diff into an explicit migration plan.
+ *
+ * The initial planner is intentionally static: it classifies operations and
+ * carries diagnostics/blockers without querying a live ClickHouse instance.
+ * Later phases can enrich this plan with system-table cost estimates.
+ */
+export function createMigrationPlan(diff, options = {}) {
+    const plannedOperations = diff.operations.map((operation, operationIndex) => planOperation(operation, operationIndex, diff, options));
+    const blockerDiagnostics = diff.unsupportedChanges.map((change) => ({
+        level: 'error',
+        kind: change.kind,
+        message: change.message,
+    }));
+    const warningDiagnostics = diff.warnings.map((warning) => ({
+        level: 'warning',
+        kind: warning.kind,
+        message: warning.message,
+    }));
+    const operationDiagnostics = plannedOperations.flatMap(operation => operation.diagnostics);
+    const requiredConfirmations = plannedOperations.flatMap(operation => operation.requiredConfirmations);
+    const recommendedSyncSettings = dedupeSyncSettings(plannedOperations.flatMap(operation => operation.recommendedSyncSettings));
+    const staticBlockers = plannedOperations.flatMap((operation, operationIndex) => operation.classification === 'forbidden'
+        ? [{
+                kind: 'ForbiddenOperation',
+                operationIndex,
+                message: forbiddenOperationMessage(operation.operation),
+            }]
+        : []);
+    const unsupportedBlockers = diff.unsupportedChanges.map(change => ({
+        kind: change.kind,
+        message: change.message,
+        tableName: change.tableName,
+        ...(change.columnName !== undefined ? { columnName: change.columnName } : {}),
+    }));
+    const plan = {
+        previousSnapshot: diff.previousSnapshot,
+        nextSnapshot: diff.nextSnapshot,
+        sourceSnapshotHash: diff.previousSnapshot.contentHash,
+        targetSnapshotHash: diff.nextSnapshot.contentHash,
+        operations: plannedOperations,
+        diagnostics: [
+            ...blockerDiagnostics,
+            ...warningDiagnostics,
+            ...operationDiagnostics,
+        ],
+        blockers: [
+            ...unsupportedBlockers,
+            ...staticBlockers,
+        ],
+        requiredConfirmations,
+        recommendedSyncSettings,
+        // Backward-compatible alias. These settings are recommendations for the future executor,
+        // not proof that generated SQL has applied them.
+        requiredSyncSettings: recommendedSyncSettings,
+    };
+    const analyzerResult = runAnalyzers(plan, diff, options.analyzers ?? [], options.context);
+    if (analyzerResult.diagnostics.length === 0 &&
+        analyzerResult.blockers.length === 0 &&
+        analyzerResult.confirmations.length === 0) {
+        return plan;
+    }
+    return {
+        ...plan,
+        diagnostics: [
+            ...plan.diagnostics,
+            ...analyzerResult.diagnostics,
+        ],
+        blockers: [
+            ...plan.blockers,
+            ...analyzerResult.blockers,
+        ],
+        requiredConfirmations: [
+            ...plan.requiredConfirmations,
+            ...analyzerResult.confirmations,
+        ],
+    };
+}
+export function isMigrationPlan(input) {
+    return 'blockers' in input &&
+        'diagnostics' in input &&
+        'requiredConfirmations' in input &&
+        Array.isArray(input.operations) &&
+        input.operations.every(operation => 'operation' in operation && 'classification' in operation);
+}
+function planOperation(operation, operationIndex, diff, options) {
+    const classification = classifyOperation(operation, diff.previousSnapshot.tables);
+    const costEstimate = estimateOperationCost(operation, options.context);
+    const diagnostics = diagnosticsForOperation(operation, classification, operationIndex, costEstimate, options.context);
+    const requiredConfirmations = confirmationsForOperation(operation, classification, operationIndex, options);
+    return {
+        operation,
+        classification,
+        costEstimate,
+        diagnostics,
+        requiredConfirmations,
+        recommendedSyncSettings: syncSettingsForOperation(operation, classification),
+        requiredSyncSettings: syncSettingsForOperation(operation, classification),
+    };
+}
+function classifyOperation(operation, previousTables) {
+    switch (operation.kind) {
+        case 'ModifyColumnType':
+            return isKeyColumn(previousTables, operation.tableName, operation.columnName)
+                ? 'forbidden'
+                : 'mutation';
+        case 'AlterTableWithDependentViews':
+            return classifyAlterTableWithDependentViews(operation, previousTables);
+        case 'DropColumn':
+            return isKeyColumn(previousTables, operation.tableName, operation.columnName)
+                ? 'forbidden'
+                : 'metadata';
+        case 'AddColumn':
+        case 'CreateMaterializedView':
+        case 'CreateTable':
+        case 'DropMaterializedView':
+        case 'DropTable':
+        case 'ModifyColumnDefault':
+        case 'RecreateMaterializedView':
+            return 'metadata';
+        default: {
+            const exhaustiveCheck = operation;
+            return exhaustiveCheck;
+        }
+    }
+}
+function classifyAlterTableWithDependentViews(operation, previousTables) {
+    const nestedClassifications = operation.operations.map(nestedOperation => classifyTableMutationOperation(nestedOperation, previousTables));
+    if (nestedClassifications.includes('forbidden')) {
+        return 'forbidden';
+    }
+    if (nestedClassifications.includes('mutation')) {
+        return 'mutation';
+    }
+    if (nestedClassifications.includes('data-copy')) {
+        return 'data-copy';
+    }
+    return 'metadata';
+}
+function classifyTableMutationOperation(operation, previousTables) {
+    if ((operation.kind === 'DropColumn' || operation.kind === 'ModifyColumnType') &&
+        isKeyColumn(previousTables, operation.tableName, operation.columnName)) {
+        return 'forbidden';
+    }
+    return operation.kind === 'ModifyColumnType' ? 'mutation' : 'metadata';
+}
+function diagnosticsForOperation(operation, classification, operationIndex, costEstimate, context) {
+    const diagnostics = [];
+    if (classification === 'mutation') {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'MutationOperation',
+            operationIndex,
+            message: `Operation "${operation.kind}" may trigger a ClickHouse mutation. ` +
+                'Review table size and mutation impact before applying.',
+        });
+    }
+    if (classification === 'forbidden') {
+        diagnostics.push({
+            level: 'error',
+            kind: 'ForbiddenOperation',
+            operationIndex,
+            message: forbiddenOperationMessage(operation),
+        });
+    }
+    if (operation.kind === 'DropTable') {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'DestructiveDropTable',
+            operationIndex,
+            message: `Operation drops table "${operation.tableName}".`,
+        });
+    }
+    if (operation.kind === 'DropColumn') {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'DestructiveDropColumn',
+            operationIndex,
+            message: `Operation drops column "${operation.tableName}.${operation.columnName}".`,
+        });
+    }
+    diagnostics.push(...costDiagnosticsForOperation(operation, classification, operationIndex, costEstimate, context));
+    return diagnostics;
+}
+function confirmationsForOperation(operation, classification, operationIndex, options) {
+    if (classification !== 'mutation' || options.requireConfirmationForMutations === false) {
+        return [];
+    }
+    return [
+        {
+            kind: 'MutationRequiresConfirmation',
+            operationIndex,
+            message: `Operation "${operation.kind}" is classified as a mutation and should require explicit confirmation.`,
+        },
+    ];
+}
+function syncSettingsForOperation(operation, classification) {
+    if (classification === 'forbidden') {
+        return [];
+    }
+    const settings = [];
+    if (operation.kind !== 'CreateTable' && operation.kind !== 'CreateMaterializedView') {
+        settings.push({
+            name: 'alter_sync',
+            value: 2,
+            reason: 'Wait for ClickHouse ALTER/DDL operations to finish on active replicas where supported.',
+        });
+    }
+    if (classification === 'mutation') {
+        settings.push({
+            name: 'mutations_sync',
+            value: 2,
+            reason: 'Wait for mutation-triggering ALTER operations to finish before marking the step complete.',
+        });
+    }
+    return settings;
+}
+function dedupeSyncSettings(settings) {
+    const seen = new Set();
+    const deduped = [];
+    for (const setting of settings) {
+        const key = `${setting.name}:${setting.value}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(setting);
+    }
+    return deduped;
+}
+function runAnalyzers(plan, diff, analyzers, context) {
+    const results = analyzers.map((analyzer, index) => {
+        try {
+            return analyzer(plan, { diff, clickhouse: context });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                diagnostics: [{
+                        level: 'error',
+                        kind: 'AnalyzerError',
+                        message: `Analyzer at index ${index} failed: ${message}`,
+                    }],
+                blockers: [{
+                        kind: 'AnalyzerError',
+                        message: `Analyzer at index ${index} failed: ${message}`,
+                    }],
+            };
+        }
+    });
+    return {
+        diagnostics: results.flatMap(result => result.diagnostics ?? []),
+        blockers: results.flatMap(result => result.blockers ?? []),
+        confirmations: results.flatMap(result => result.confirmations ?? []),
+    };
+}
+function estimateOperationCost(operation, context) {
+    const tableName = getOperationTableName(operation);
+    if (!tableName) {
+        return {
+            source: 'static',
+            confidence: 'none',
+        };
+    }
+    const stats = getTableStats(context, tableName);
+    if (!stats) {
+        return {
+            tableName,
+            source: 'static',
+            confidence: 'none',
+        };
+    }
+    return {
+        tableName,
+        affectedRows: stats.totalRows,
+        affectedBytes: stats.totalBytes,
+        activeParts: stats.activeParts,
+        pendingMutations: stats.pendingMutations,
+        replicaAbsoluteDelaySeconds: stats.replicaAbsoluteDelaySeconds,
+        replicaQueueSize: stats.replicaQueueSize,
+        source: 'provided-context',
+        confidence: 'medium',
+    };
+}
+function costDiagnosticsForOperation(operation, classification, operationIndex, costEstimate, context) {
+    if (costEstimate.source !== 'provided-context') {
+        return [];
+    }
+    const diagnostics = [];
+    const mutationWarningBytes = atLeast(context?.mutationWarningBytes, 0, 1024 ** 3);
+    const mutationWarningRows = atLeast(context?.mutationWarningRows, 1, 100_000_000);
+    const activePartsWarningThreshold = atLeast(context?.activePartsWarningThreshold, 1, 200);
+    const pendingMutationsWarningThreshold = atLeast(context?.pendingMutationsWarningThreshold, 0, 0);
+    const replicaDelayWarningSeconds = atLeast(context?.replicaDelayWarningSeconds, 0, 60);
+    if (classification === 'mutation' &&
+        costEstimate.affectedBytes !== undefined &&
+        costEstimate.affectedBytes >= mutationWarningBytes) {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'ExpensiveMutationBytes',
+            operationIndex,
+            message: `Operation "${operation.kind}" may mutate ${costEstimate.affectedBytes} bytes ` +
+                `on table "${costEstimate.tableName}".`,
+        });
+    }
+    if (classification === 'mutation' &&
+        costEstimate.affectedRows !== undefined &&
+        costEstimate.affectedRows >= mutationWarningRows) {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'ExpensiveMutationRows',
+            operationIndex,
+            message: `Operation "${operation.kind}" may mutate ${costEstimate.affectedRows} rows ` +
+                `on table "${costEstimate.tableName}".`,
+        });
+    }
+    if (costEstimate.activeParts !== undefined && costEstimate.activeParts >= activePartsWarningThreshold) {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'HighActivePartCount',
+            operationIndex,
+            message: `Table "${costEstimate.tableName}" has ${costEstimate.activeParts} active parts. ` +
+                'Consider reducing part pressure before applying DDL.',
+        });
+    }
+    if (costEstimate.pendingMutations !== undefined &&
+        costEstimate.pendingMutations > pendingMutationsWarningThreshold) {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'PendingMutations',
+            operationIndex,
+            message: `Table "${costEstimate.tableName}" has ${costEstimate.pendingMutations} pending mutation(s).`,
+        });
+    }
+    if (costEstimate.replicaAbsoluteDelaySeconds !== undefined &&
+        costEstimate.replicaAbsoluteDelaySeconds >= replicaDelayWarningSeconds) {
+        diagnostics.push({
+            level: 'warning',
+            kind: 'ReplicaDelay',
+            operationIndex,
+            message: `Table "${costEstimate.tableName}" has replica delay of ` +
+                `${costEstimate.replicaAbsoluteDelaySeconds} second(s).`,
+        });
+    }
+    return diagnostics;
+}
+function forbiddenOperationMessage(operation) {
+    if (operation.kind === 'DropColumn' || operation.kind === 'ModifyColumnType') {
+        return [
+            `Cannot ${operation.kind === 'DropColumn' ? 'drop' : 'modify'} key column ` +
+                `"${operation.tableName}.${operation.columnName}" automatically.`,
+            'ClickHouse key columns participate in ORDER BY, PRIMARY KEY, PARTITION BY, or SAMPLE BY expressions.',
+            'Recommended approach: create a new table with the desired schema, backfill data in controlled batches, swap tables, then drop the old table.',
+            'Use a custom SQL migration if you understand the operational risk.',
+        ].join(' ');
+    }
+    return [
+        `Operation "${operation.kind}" cannot be generated safely.`,
+        'Use a custom SQL migration or split the schema evolution into supported steps.',
+    ].join(' ');
+}
+function atLeast(value, minimum, fallback) {
+    if (value === undefined || Number.isNaN(value)) {
+        return fallback;
+    }
+    return Math.max(minimum, value);
+}
+function getOperationTableName(operation) {
+    switch (operation.kind) {
+        case 'AddColumn':
+        case 'AlterTableWithDependentViews':
+        case 'DropColumn':
+        case 'DropTable':
+        case 'ModifyColumnDefault':
+        case 'ModifyColumnType':
+            return operation.tableName;
+        case 'CreateTable':
+            return operation.table.name;
+        case 'CreateMaterializedView':
+        case 'DropMaterializedView':
+        case 'RecreateMaterializedView':
+            return undefined;
+        default: {
+            const exhaustiveCheck = operation;
+            return exhaustiveCheck;
+        }
+    }
+}
+function getTableStats(context, tableName) {
+    if (!context?.tables) {
+        return undefined;
+    }
+    if (Array.isArray(context.tables)) {
+        return context.tables.find(table => table.tableName === tableName);
+    }
+    return context.tables[tableName];
+}
+function isKeyColumn(tables, tableName, columnName) {
+    const table = tables.find(candidate => candidate.name === tableName);
+    if (!table) {
+        return false;
+    }
+    return [
+        ...table.engine.orderBy,
+        ...table.engine.primaryKey,
+        table.engine.partitionBy,
+        table.engine.sampleBy,
+    ].some(expression => expression !== undefined && expressionReferencesColumn(expression, columnName));
+}
+function expressionReferencesColumn(expression, columnName) {
+    if (expression === columnName) {
+        return true;
+    }
+    const escapedColumn = columnName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^A-Za-z0-9_])${escapedColumn}([^A-Za-z0-9_]|$)`).test(expression);
+}

package/dist/migrations/plan/types.d.ts

@@ -0,0 +1,93 @@
+import type { MigrationOperation, SnapshotDiffResult } from '../diff/types.js';
+import type { Snapshot } from '../snapshot/types.js';
+export type MigrationOperationClassification = 'metadata' | 'mutation' | 'data-copy' | 'forbidden';
+export type MigrationPlanDiagnosticLevel = 'warning' | 'error';
+export interface MigrationPlanDiagnostic {
+    level: MigrationPlanDiagnosticLevel;
+    kind: string;
+    message: string;
+    operationIndex?: number;
+}
+export interface MigrationPlanBlocker {
+    kind: string;
+    message: string;
+    tableName?: string;
+    columnName?: string;
+    operationIndex?: number;
+}
+export interface MigrationPlanConfirmation {
+    kind: string;
+    message: string;
+    operationIndex: number;
+}
+export interface ClickHouseMigrationSyncSetting {
+    name: 'alter_sync' | 'mutations_sync' | 'replication_alter_partitions_sync' | 'distributed_ddl_task_timeout';
+    value: string | number;
+    reason: string;
+}
+export interface ClickHouseTableCostStats {
+    tableName: string;
+    totalRows?: number;
+    totalBytes?: number;
+    activeParts?: number;
+    pendingMutations?: number;
+    replicaAbsoluteDelaySeconds?: number;
+    replicaQueueSize?: number;
+}
+export interface ClickHouseMigrationPlanContext {
+    tables?: Record<string, ClickHouseTableCostStats> | ClickHouseTableCostStats[];
+    mutationWarningBytes?: number;
+    mutationWarningRows?: number;
+    activePartsWarningThreshold?: number;
+    pendingMutationsWarningThreshold?: number;
+    replicaDelayWarningSeconds?: number;
+}
+export interface MigrationOperationCostEstimate {
+    tableName?: string;
+    affectedRows?: number;
+    affectedBytes?: number;
+    activeParts?: number;
+    pendingMutations?: number;
+    replicaAbsoluteDelaySeconds?: number;
+    replicaQueueSize?: number;
+    source: 'static' | 'provided-context';
+    confidence: 'none' | 'low' | 'medium';
+}
+export interface PlannedMigrationOperation {
+    operation: MigrationOperation;
+    classification: MigrationOperationClassification;
+    costEstimate: MigrationOperationCostEstimate;
+    diagnostics: MigrationPlanDiagnostic[];
+    requiredConfirmations: MigrationPlanConfirmation[];
+    recommendedSyncSettings: ClickHouseMigrationSyncSetting[];
+    requiredSyncSettings: ClickHouseMigrationSyncSetting[];
+}
+export interface MigrationPlan {
+    previousSnapshot: Snapshot;
+    nextSnapshot: Snapshot;
+    sourceSnapshotHash: string;
+    targetSnapshotHash: string;
+    operations: PlannedMigrationOperation[];
+    diagnostics: MigrationPlanDiagnostic[];
+    blockers: MigrationPlanBlocker[];
+    requiredConfirmations: MigrationPlanConfirmation[];
+    recommendedSyncSettings: ClickHouseMigrationSyncSetting[];
+    requiredSyncSettings: ClickHouseMigrationSyncSetting[];
+}
+export interface MigrationPlanAnalyzerContext {
+    diff: SnapshotDiffResult;
+    clickhouse?: ClickHouseMigrationPlanContext;
+}
+export interface MigrationPlanAnalyzerResult {
+    diagnostics?: MigrationPlanDiagnostic[];
+    blockers?: MigrationPlanBlocker[];
+    confirmations?: MigrationPlanConfirmation[];
+}
+export type MigrationPlanAnalyzer = (plan: MigrationPlan, context: MigrationPlanAnalyzerContext) => MigrationPlanAnalyzerResult;
+export interface CreateMigrationPlanOptions {
+    requireConfirmationForMutations?: boolean;
+    analyzers?: MigrationPlanAnalyzer[];
+    context?: ClickHouseMigrationPlanContext;
+}
+export type MigrationPlanInput = SnapshotDiffResult | MigrationPlan;
+//# sourceMappingURL=types.d.ts.map

package/dist/migrations/plan/types.d.ts.map

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

package/dist/migrations/plan/types.js

@@ -0,0 +1 @@
+export {};

package/dist/migrations/schema/column.d.ts

@@ -0,0 +1,71 @@
+import type { ClickHouseColumnBuilderLike, ClickHouseColumnDefaultValue, ClickHouseDefaultInput, ClickHouseColumnDefinition, ClickHouseColumnType } from './types.js';
+type NestedColumnTypeInput = string | ClickHouseColumnBuilder | ClickHouseColumnType;
+/**
+ * Immutable builder for ClickHouse column definitions.
+ *
+ * Each modifier returns a new builder so reusable column fragments can be shared
+ * safely without later calls mutating earlier definitions.
+ */
+export declare class ClickHouseColumnBuilder implements ClickHouseColumnBuilderLike {
+    private readonly columnType;
+    private readonly defaultExpression?;
+    constructor(columnType: ClickHouseColumnType, defaultExpression?: ClickHouseColumnDefaultValue | undefined);
+    /**
+     * Adds a column default.
+     *
+     * Primitive values are rendered as SQL literals. Use the `sql` template tag for
+     * database expressions such as `sql\`now()\``.
+     */
+    default(expression: ClickHouseDefaultInput): ClickHouseColumnBuilder;
+    /**
+     * Wraps this column type in `Nullable(...)`.
+     */
+    nullable(): ClickHouseColumnBuilder;
+    /**
+     * Wraps this column type in `LowCardinality(...)`.
+     */
+    lowCardinality(): ClickHouseColumnBuilder;
+    /**
+     * Materializes the builder into a named column definition for a table AST.
+     */
+    build(name: string): ClickHouseColumnDefinition;
+    /**
+     * Returns the underlying type AST for nested type builders.
+     */
+    toColumnType(): ClickHouseColumnType;
+}
+/**
+ * Factory helpers for common ClickHouse column types.
+ *
+ * Examples:
+ * `column.String().default('pending')`, `column.Nullable('String')`,
+ * `column.DateTime('UTC')`.
+ */
+export declare const column: {
+    Int8: () => ClickHouseColumnBuilder;
+    Int16: () => ClickHouseColumnBuilder;
+    Int32: () => ClickHouseColumnBuilder;
+    Int64: () => ClickHouseColumnBuilder;
+    Int128: () => ClickHouseColumnBuilder;
+    Int256: () => ClickHouseColumnBuilder;
+    UInt8: () => ClickHouseColumnBuilder;
+    UInt16: () => ClickHouseColumnBuilder;
+    UInt32: () => ClickHouseColumnBuilder;
+    UInt64: () => ClickHouseColumnBuilder;
+    UInt128: () => ClickHouseColumnBuilder;
+    UInt256: () => ClickHouseColumnBuilder;
+    Float32: () => ClickHouseColumnBuilder;
+    Float64: () => ClickHouseColumnBuilder;
+    Decimal: (precision: number, scale: number) => ClickHouseColumnBuilder;
+    String: () => ClickHouseColumnBuilder;
+    FixedString: (length: number) => ClickHouseColumnBuilder;
+    Date: () => ClickHouseColumnBuilder;
+    DateTime: (timezone?: string) => ClickHouseColumnBuilder;
+    DateTime64: (precision: number, timezone?: string) => ClickHouseColumnBuilder;
+    UUID: () => ClickHouseColumnBuilder;
+    JSON: () => ClickHouseColumnBuilder;
+    LowCardinality: (inner: NestedColumnTypeInput) => ClickHouseColumnBuilder;
+    Nullable: (inner: NestedColumnTypeInput) => ClickHouseColumnBuilder;
+};
+export {};
+//# sourceMappingURL=column.d.ts.map

package/dist/migrations/schema/column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column.d.ts","sourceRoot":"","sources":["../../../src/migrations/schema/column.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAIpB,KAAK,qBAAqB,GAAG,MAAM,GAAG,uBAAuB,GAAG,oBAAoB,CAAC;AAErF;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,2BAA2B;IAEvE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;gBADlB,UAAU,EAAE,oBAAoB,EAChC,iBAAiB,CAAC,EAAE,4BAA4B,YAAA;IAGnE;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,sBAAsB,GAAG,uBAAuB;IAIpE;;OAEG;IACH,QAAQ,IAAI,uBAAuB;IAOnC;;OAEG;IACH,cAAc,IAAI,uBAAuB;IAOzC;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B;IAQ/C;;OAEG;IACH,YAAY,IAAI,oBAAoB;CAGrC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;yBAeI,MAAM,SAAS,MAAM;;0BAEpB,MAAM;;0BAEN,MAAM;4BACJ,MAAM,aAAa,MAAM;;;4BAIzB,qBAAqB;sBAK3B,qBAAqB;CAKxC,CAAC"}