@framers/sql-storage-adapter 0.1.0

package/dist/types/context.js

@@ -0,0 +1,9 @@
+/**
+ * Runtime context and introspection types for storage adapters.
+ *
+ * These types enable runtime inspection of adapter capabilities,
+ * connection state, and performance characteristics without requiring
+ * developers to manually check capability flags.
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/types/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/types/events.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Event system types for adapter lifecycle and query monitoring.
+ *
+ * These types enable applications to subscribe to adapter events
+ * for logging, monitoring, debugging, and analytics purposes.
+ */
+import type { StorageParameters } from '../types';
+import type { AdapterContext } from './context';
+/**
+ * Event emitted when a connection is opened.
+ */
+export interface ConnectionOpenedEvent {
+    type: 'connection:opened';
+    context: AdapterContext;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a connection is closed.
+ */
+export interface ConnectionClosedEvent {
+    type: 'connection:closed';
+    context: AdapterContext;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a connection error occurs.
+ */
+export interface ConnectionErrorEvent {
+    type: 'connection:error';
+    error: Error;
+    context: AdapterContext;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a query starts execution.
+ */
+export interface QueryStartEvent {
+    type: 'query:start';
+    statement: string;
+    parameters?: StorageParameters;
+    timestamp: Date;
+    queryId?: string;
+}
+/**
+ * Event emitted when a query completes successfully.
+ */
+export interface QueryCompleteEvent {
+    type: 'query:complete';
+    statement: string;
+    duration: number;
+    rows?: number;
+    timestamp: Date;
+    queryId?: string;
+}
+/**
+ * Event emitted when a query fails.
+ */
+export interface QueryErrorEvent {
+    type: 'query:error';
+    statement: string;
+    error: Error;
+    duration: number;
+    timestamp: Date;
+    queryId?: string;
+}
+/**
+ * Event emitted when a transaction starts.
+ */
+export interface TransactionStartEvent {
+    type: 'transaction:start';
+    id: string;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a transaction commits successfully.
+ */
+export interface TransactionCommitEvent {
+    type: 'transaction:commit';
+    id: string;
+    duration: number;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a transaction is rolled back.
+ */
+export interface TransactionRollbackEvent {
+    type: 'transaction:rollback';
+    id: string;
+    error?: Error;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a slow query is detected.
+ */
+export interface PerformanceSlowQueryEvent {
+    type: 'performance:slow-query';
+    statement: string;
+    duration: number;
+    threshold: number;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a cache hit occurs.
+ */
+export interface CacheHitEvent {
+    type: 'cache:hit';
+    key: string;
+    statement: string;
+    timestamp: Date;
+}
+/**
+ * Event emitted when a cache miss occurs.
+ */
+export interface CacheMissEvent {
+    type: 'cache:miss';
+    key: string;
+    statement: string;
+    timestamp: Date;
+}
+/**
+ * Event emitted when the cache is cleared.
+ */
+export interface CacheClearEvent {
+    type: 'cache:clear';
+    entriesCleared: number;
+    timestamp: Date;
+}
+/**
+ * Union of all possible adapter events.
+ */
+export type AdapterEvent = ConnectionOpenedEvent | ConnectionClosedEvent | ConnectionErrorEvent | QueryStartEvent | QueryCompleteEvent | QueryErrorEvent | TransactionStartEvent | TransactionCommitEvent | TransactionRollbackEvent | PerformanceSlowQueryEvent | CacheHitEvent | CacheMissEvent | CacheClearEvent;
+/**
+ * Extract event type from AdapterEvent discriminated union.
+ */
+export type AdapterEventType = AdapterEvent['type'];
+/**
+ * Listener function for adapter events.
+ */
+export type AdapterEventListener<T extends AdapterEvent = AdapterEvent> = (event: T) => void;
+/**
+ * Unsubscribe function returned by event listeners.
+ */
+export type UnsubscribeFn = () => void;
+/**
+ * Event emitter interface for storage adapters.
+ *
+ * Provides a simple pub/sub mechanism for monitoring adapter
+ * lifecycle and query execution.
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to all query errors
+ * const unsubscribe = events.on('query:error', (event) => {
+ *   console.error('Query failed:', event.statement, event.error);
+ * });
+ *
+ * // Later, unsubscribe
+ * unsubscribe();
+ *
+ * // Subscribe to slow queries
+ * events.on('performance:slow-query', (event) => {
+ *   if (event.duration > 5000) {
+ *     analytics.track('very_slow_query', {
+ *       statement: event.statement,
+ *       duration: event.duration
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export interface AdapterEventEmitter {
+    /**
+     * Subscribe to an event type.
+     *
+     * @param eventType - The type of event to listen for
+     * @param listener - Callback function to invoke when event occurs
+     * @returns Unsubscribe function
+     */
+    on<T extends AdapterEventType>(eventType: T, listener: AdapterEventListener<Extract<AdapterEvent, {
+        type: T;
+    }>>): UnsubscribeFn;
+    /**
+     * Subscribe to an event type once (auto-unsubscribes after first call).
+     *
+     * @param eventType - The type of event to listen for
+     * @param listener - Callback function to invoke when event occurs
+     * @returns Unsubscribe function
+     */
+    once<T extends AdapterEventType>(eventType: T, listener: AdapterEventListener<Extract<AdapterEvent, {
+        type: T;
+    }>>): UnsubscribeFn;
+    /**
+     * Emit an event to all subscribers.
+     *
+     * @param event - The event to emit
+     */
+    emit(event: AdapterEvent): void;
+    /**
+     * Remove all event listeners.
+     */
+    removeAllListeners(): void;
+    /**
+     * Remove all listeners for a specific event type.
+     *
+     * @param eventType - The event type to clear listeners for
+     */
+    removeListeners(eventType: AdapterEventType): void;
+    /**
+     * Get the number of listeners for an event type.
+     *
+     * @param eventType - The event type to count listeners for
+     * @returns Number of active listeners
+     */
+    listenerCount(eventType: AdapterEventType): number;
+}
+/**
+ * Helper type for creating type-safe event emitter implementations.
+ */
+export interface EventEmitterOptions {
+    /** Maximum number of listeners before warning (default: 10) */
+    maxListeners?: number;
+    /** Whether to log warnings for too many listeners */
+    warnOnMaxListeners?: boolean;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

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

package/dist/types/events.js

@@ -0,0 +1,8 @@
+/**
+ * Event system types for adapter lifecycle and query monitoring.
+ *
+ * These types enable applications to subscribe to adapter events
+ * for logging, monitoring, debugging, and analytics purposes.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types/extensions.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Extended types for advanced adapter features.
+ * These types are used by adapters that provide additional functionality
+ * beyond the core StorageAdapter interface.
+ */
+import type { BatchOperation as CoreBatchOperation } from '../types';
+/**
+ * Performance metrics for monitoring adapter usage.
+ */
+export interface PerformanceMetrics {
+    totalQueries: number;
+    totalDuration: number;
+    averageDuration: number;
+    cacheHits?: number;
+    cacheMisses?: number;
+    slowQueries?: Array<{
+        query: string;
+        duration: number;
+        timestamp: Date;
+    }>;
+}
+/**
+ * Options for streaming large result sets.
+ */
+export interface StreamOptions {
+    batchSize?: number;
+    highWaterMark?: number;
+}
+/**
+ * Database migration definition.
+ */
+export interface Migration {
+    id: string;
+    version: number;
+    up: string;
+    down?: string;
+    description?: string;
+    appliedAt?: Date;
+}
+/**
+ * Extended batch operation with additional metadata.
+ * Used by adapters that support richer batch operation semantics.
+ */
+export interface ExtendedBatchOperation extends CoreBatchOperation {
+    type?: 'insert' | 'update' | 'delete';
+    table?: string;
+    values?: Record<string, unknown> | Array<Record<string, unknown>>;
+    where?: Record<string, unknown>;
+}
+/**
+ * Extended storage adapter interface for advanced features.
+ */
+export interface StorageAdapterExtensions {
+    /**
+     * Apply database migrations.
+     */
+    migrate?(migrations: Migration[]): Promise<void>;
+    /**
+     * Get migration status.
+     */
+    getMigrationStatus?(): Promise<Migration[]>;
+    /**
+     * Get performance metrics.
+     */
+    getMetrics?(): PerformanceMetrics;
+    /**
+     * Stream large result sets.
+     */
+    stream?<T>(statement: string, parameters?: unknown, options?: StreamOptions): AsyncIterableIterator<T>;
+}
+export type { BatchOperation } from '../types';
+export type { BatchResult } from '../types';
+//# sourceMappingURL=extensions.d.ts.map

package/dist/types/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/types/extensions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,IAAI,CAAC;KACjB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,OAAO,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;OAEG;IACH,kBAAkB,CAAC,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAE5C;;OAEG;IACH,UAAU,CAAC,IAAI,kBAAkB,CAAC;IAElC;;OAEG;IACH,MAAM,CAAC,CAAC,CAAC,EACP,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CAAC,CAAC,CAAC,CAAC;CAC7B;AAGD,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/extensions.js

@@ -0,0 +1,7 @@
+/**
+ * Extended types for advanced adapter features.
+ * These types are used by adapters that provide additional functionality
+ * beyond the core StorageAdapter interface.
+ */
+export {};
+//# sourceMappingURL=extensions.js.map

package/dist/types/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/types/extensions.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/types/limitations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Adapter-specific limitation definitions.
+ *
+ * This module provides concrete limitation specifications for each
+ * supported database adapter, enabling runtime introspection and
+ * automatic constraint enforcement.
+ */
+import type { AdapterLimitations } from './context';
+/**
+ * Limitations for better-sqlite3 adapter.
+ */
+export declare const BETTER_SQLITE3_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for SQL.js adapter (WebAssembly SQLite).
+ */
+export declare const SQLJS_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for Capacitor SQLite adapter (mobile).
+ */
+export declare const CAPACITOR_SQLITE_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for PostgreSQL adapter.
+ */
+export declare const POSTGRES_LIMITATIONS: AdapterLimitations;
+/**
+ * Limitations for Supabase adapter (PostgreSQL with extensions).
+ */
+export declare const SUPABASE_LIMITATIONS: AdapterLimitations;
+/**
+ * Map adapter kinds to their limitation definitions.
+ */
+export declare const ADAPTER_LIMITATIONS_MAP: {
+    readonly 'better-sqlite3': AdapterLimitations;
+    readonly sqljs: AdapterLimitations;
+    readonly capacitor: AdapterLimitations;
+    readonly postgres: AdapterLimitations;
+    readonly supabase: AdapterLimitations;
+};
+/**
+ * Get limitations for a specific adapter kind.
+ *
+ * @param kind - Adapter kind
+ * @returns Adapter limitations
+ */
+export declare function getLimitationsForAdapter(kind: keyof typeof ADAPTER_LIMITATIONS_MAP): AdapterLimitations;
+//# sourceMappingURL=limitations.d.ts.map

package/dist/types/limitations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitations.d.ts","sourceRoot":"","sources":["../../src/types/limitations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,WAAW,CAAC;AAqBnB;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,kBAmBxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,kBAqB/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,kBAqB1C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBA4BlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBA4BlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;CAM1B,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,OAAO,uBAAuB,GACzC,kBAAkB,CAEpB"}

package/dist/types/limitations.js

@@ -0,0 +1,154 @@
+/**
+ * Adapter-specific limitation definitions.
+ *
+ * This module provides concrete limitation specifications for each
+ * supported database adapter, enabling runtime introspection and
+ * automatic constraint enforcement.
+ */
+/**
+ * Create performance characteristics object.
+ */
+function createPerformanceCharacteristics(concurrency, persistence, transactionIsolation, usesConnectionPool, asyncExecution) {
+    return {
+        concurrency,
+        persistence,
+        transactionIsolation,
+        usesConnectionPool,
+        asyncExecution
+    };
+}
+/**
+ * Limitations for better-sqlite3 adapter.
+ */
+export const BETTER_SQLITE3_LIMITATIONS = {
+    maxConnections: 1, // Single connection (SQLite limitation)
+    maxStatementLength: 1000000, // 1MB
+    maxBatchSize: undefined, // No hard limit, but memory constrained
+    maxParameterSize: undefined, // Limited by available memory
+    supportedDataTypes: ['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NULL'],
+    unsupportedFeatures: ['streaming', 'concurrent', 'json', 'arrays'],
+    performanceCharacteristics: createPerformanceCharacteristics('single', 'file', ['SERIALIZABLE'], // SQLite only supports serializable
+    false, // No connection pooling
+    false // Synchronous by default
+    ),
+    constraints: {
+        supportsWAL: true,
+        supportsInMemory: true,
+        requiresFilePath: false // Can use :memory:
+    }
+};
+/**
+ * Limitations for SQL.js adapter (WebAssembly SQLite).
+ */
+export const SQLJS_LIMITATIONS = {
+    maxConnections: 1, // Single connection
+    maxStatementLength: 1000000, // 1MB
+    maxBatchSize: undefined,
+    maxParameterSize: undefined,
+    supportedDataTypes: ['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NULL'],
+    unsupportedFeatures: ['streaming', 'concurrent', 'json', 'arrays', 'wal', 'locks'],
+    performanceCharacteristics: createPerformanceCharacteristics('single', 'memory', // Typically in-memory or manual file persistence
+    ['SERIALIZABLE'], false, true // Async wrapper over sync WASM
+    ),
+    constraints: {
+        supportsWAL: false,
+        supportsInMemory: true,
+        requiresFilePath: false,
+        requiresWASM: true,
+        browserCompatible: true
+    }
+};
+/**
+ * Limitations for Capacitor SQLite adapter (mobile).
+ */
+export const CAPACITOR_SQLITE_LIMITATIONS = {
+    maxConnections: 1, // Mobile SQLite single connection
+    maxStatementLength: 1000000,
+    maxBatchSize: undefined,
+    maxParameterSize: undefined,
+    supportedDataTypes: ['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NULL'],
+    unsupportedFeatures: ['streaming', 'concurrent', 'json', 'arrays'],
+    performanceCharacteristics: createPerformanceCharacteristics('single', 'file', ['SERIALIZABLE'], false, true // Async through Capacitor bridge
+    ),
+    constraints: {
+        supportsWAL: true,
+        supportsInMemory: false, // Mobile requires file persistence
+        requiresFilePath: true,
+        requiresCapacitor: true,
+        mobileOnly: true
+    }
+};
+/**
+ * Limitations for PostgreSQL adapter.
+ */
+export const POSTGRES_LIMITATIONS = {
+    maxConnections: 100, // Default pool size (configurable)
+    maxStatementLength: 1073741824, // 1GB theoretical limit
+    maxBatchSize: 1000, // Recommended batch size
+    maxParameterSize: 1073741824, // 1GB for BYTEA/TEXT
+    supportedDataTypes: [
+        'INTEGER', 'BIGINT', 'SMALLINT', 'SERIAL', 'BIGSERIAL',
+        'REAL', 'DOUBLE PRECISION', 'NUMERIC', 'DECIMAL',
+        'TEXT', 'VARCHAR', 'CHAR', 'BYTEA',
+        'BOOLEAN', 'DATE', 'TIME', 'TIMESTAMP', 'TIMESTAMPTZ',
+        'JSON', 'JSONB', 'UUID', 'ARRAY', 'HSTORE', 'XML'
+    ],
+    unsupportedFeatures: ['wal'], // WAL is PostgreSQL-specific, not exposed as capability
+    performanceCharacteristics: createPerformanceCharacteristics('pooled', 'network', ['READ UNCOMMITTED', 'READ COMMITTED', 'REPEATABLE READ', 'SERIALIZABLE'], true, // Connection pooling
+    true // Fully async
+    ),
+    constraints: {
+        supportsWAL: false, // Not relevant for client connections
+        supportsInMemory: false,
+        requiresFilePath: false,
+        requiresNetwork: true,
+        supportsReplication: true,
+        supportsPartitioning: true
+    }
+};
+/**
+ * Limitations for Supabase adapter (PostgreSQL with extensions).
+ */
+export const SUPABASE_LIMITATIONS = {
+    maxConnections: 15, // Supabase free tier default
+    maxStatementLength: 1073741824,
+    maxBatchSize: 1000,
+    maxParameterSize: 1073741824,
+    supportedDataTypes: [
+        ...POSTGRES_LIMITATIONS.supportedDataTypes,
+        'VECTOR' // pgvector extension
+    ],
+    unsupportedFeatures: [],
+    performanceCharacteristics: createPerformanceCharacteristics('pooled', 'network', ['READ COMMITTED', 'REPEATABLE READ', 'SERIALIZABLE'], true, true),
+    constraints: {
+        supportsWAL: false,
+        supportsInMemory: false,
+        requiresFilePath: false,
+        requiresNetwork: true,
+        supportsReplication: true,
+        supportsPartitioning: true,
+        supportsRowLevelSecurity: true,
+        supportsRealtimeSubscriptions: true, // Supabase-specific
+        managedService: true
+    }
+};
+/**
+ * Map adapter kinds to their limitation definitions.
+ */
+export const ADAPTER_LIMITATIONS_MAP = {
+    'better-sqlite3': BETTER_SQLITE3_LIMITATIONS,
+    'sqljs': SQLJS_LIMITATIONS,
+    'capacitor': CAPACITOR_SQLITE_LIMITATIONS,
+    'postgres': POSTGRES_LIMITATIONS,
+    'supabase': SUPABASE_LIMITATIONS
+};
+/**
+ * Get limitations for a specific adapter kind.
+ *
+ * @param kind - Adapter kind
+ * @returns Adapter limitations
+ */
+export function getLimitationsForAdapter(kind) {
+    return ADAPTER_LIMITATIONS_MAP[kind];
+}
+//# sourceMappingURL=limitations.js.map

package/dist/types/limitations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitations.js","sourceRoot":"","sources":["../../src/types/limitations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;GAEG;AACH,SAAS,gCAAgC,CACvC,WAA6B,EAC7B,WAA6B,EAC7B,oBAA8B,EAC9B,kBAA2B,EAC3B,cAAuB;IAEvB,OAAO;QACL,WAAW;QACX,WAAW;QACX,oBAAoB;QACpB,kBAAkB;QAClB,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAuB;IAC5D,cAAc,EAAE,CAAC,EAAE,wCAAwC;IAC3D,kBAAkB,EAAE,OAAO,EAAE,MAAM;IACnC,YAAY,EAAE,SAAS,EAAE,wCAAwC;IACjE,gBAAgB,EAAE,SAAS,EAAE,8BAA8B;IAC3D,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC/D,mBAAmB,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC;IAClE,0BAA0B,EAAE,gCAAgC,CAC1D,QAAQ,EACR,MAAM,EACN,CAAC,cAAc,CAAC,EAAE,oCAAoC;IACtD,KAAK,EAAE,wBAAwB;IAC/B,KAAK,CAAE,yBAAyB;KACjC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,IAAI;QACjB,gBAAgB,EAAE,IAAI;QACtB,gBAAgB,EAAE,KAAK,CAAC,mBAAmB;KAC5C;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAuB;IACnD,cAAc,EAAE,CAAC,EAAE,oBAAoB;IACvC,kBAAkB,EAAE,OAAO,EAAE,MAAM;IACnC,YAAY,EAAE,SAAS;IACvB,gBAAgB,EAAE,SAAS;IAC3B,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC/D,mBAAmB,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC;IAClF,0BAA0B,EAAE,gCAAgC,CAC1D,QAAQ,EACR,QAAQ,EAAE,iDAAiD;IAC3D,CAAC,cAAc,CAAC,EAChB,KAAK,EACL,IAAI,CAAC,+BAA+B;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,KAAK;QAClB,gBAAgB,EAAE,IAAI;QACtB,gBAAgB,EAAE,KAAK;QACvB,YAAY,EAAE,IAAI;QAClB,iBAAiB,EAAE,IAAI;KACxB;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAuB;IAC9D,cAAc,EAAE,CAAC,EAAE,kCAAkC;IACrD,kBAAkB,EAAE,OAAO;IAC3B,YAAY,EAAE,SAAS;IACvB,gBAAgB,EAAE,SAAS;IAC3B,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC/D,mBAAmB,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC;IAClE,0BAA0B,EAAE,gCAAgC,CAC1D,QAAQ,EACR,MAAM,EACN,CAAC,cAAc,CAAC,EAChB,KAAK,EACL,IAAI,CAAC,iCAAiC;KACvC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,IAAI;QACjB,gBAAgB,EAAE,KAAK,EAAE,mCAAmC;QAC5D,gBAAgB,EAAE,IAAI;QACtB,iBAAiB,EAAE,IAAI;QACvB,UAAU,EAAE,IAAI;KACjB;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,cAAc,EAAE,GAAG,EAAE,mCAAmC;IACxD,kBAAkB,EAAE,UAAU,EAAE,wBAAwB;IACxD,YAAY,EAAE,IAAI,EAAE,yBAAyB;IAC7C,gBAAgB,EAAE,UAAU,EAAE,qBAAqB;IACnD,kBAAkB,EAAE;QAClB,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW;QACtD,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS;QAChD,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO;QAClC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa;QACrD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK;KAClD;IACD,mBAAmB,EAAE,CAAC,KAAK,CAAC,EAAE,wDAAwD;IACtF,0BAA0B,EAAE,gCAAgC,CAC1D,QAAQ,EACR,SAAS,EACT,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,CAAC,EACzE,IAAI,EAAE,qBAAqB;IAC3B,IAAI,CAAE,cAAc;KACrB;IACD,WAAW,EAAE;QACX,WAAW,EAAE,KAAK,EAAE,sCAAsC;QAC1D,gBAAgB,EAAE,KAAK;QACvB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,IAAI;QACrB,mBAAmB,EAAE,IAAI;QACzB,oBAAoB,EAAE,IAAI;KAC3B;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,cAAc,EAAE,EAAE,EAAE,6BAA6B;IACjD,kBAAkB,EAAE,UAAU;IAC9B,YAAY,EAAE,IAAI;IAClB,gBAAgB,EAAE,UAAU;IAC5B,kBAAkB,EAAE;QAClB,GAAG,oBAAoB,CAAC,kBAAkB;QAC1C,QAAQ,CAAC,qBAAqB;KAC/B;IACD,mBAAmB,EAAE,EAAE;IACvB,0BAA0B,EAAE,gCAAgC,CAC1D,QAAQ,EACR,SAAS,EACT,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,CAAC,EACrD,IAAI,EACJ,IAAI,CACL;IACD,WAAW,EAAE;QACX,WAAW,EAAE,KAAK;QAClB,gBAAgB,EAAE,KAAK;QACvB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,IAAI;QACrB,mBAAmB,EAAE,IAAI;QACzB,oBAAoB,EAAE,IAAI;QAC1B,wBAAwB,EAAE,IAAI;QAC9B,6BAA6B,EAAE,IAAI,EAAE,oBAAoB;QACzD,cAAc,EAAE,IAAI;KACrB;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,gBAAgB,EAAE,0BAA0B;IAC5C,OAAO,EAAE,iBAAiB;IAC1B,WAAW,EAAE,4BAA4B;IACzC,UAAU,EAAE,oBAAoB;IAChC,UAAU,EAAE,oBAAoB;CACxB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAA0C;IAE1C,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC"}