blendsdk 5.33.0

package/dist/i18n/translator.js

@@ -0,0 +1,259 @@
+import { formatString } from "../stdlib/index.js";
+/**
+ * Core translation engine.
+ *
+ * Provides translation lookup with locale fallback, plural support,
+ * and string interpolation via `formatString`. The catalog is treated
+ * as immutable after construction — use `setCatalog()` for atomic
+ * replacement (e.g., on reload).
+ *
+ * Runtime-agnostic: no Node.js or browser-specific APIs.
+ *
+ * @example
+ * ```typescript
+ * const translator = new Translator({
+ *     defaultLocale: "en",
+ *     catalog: {
+ *         greeting: { en: "Hello ${name}", nl: "Hallo ${name}" },
+ *         book: { en: ["${count} book", "${count} books"] },
+ *     },
+ * });
+ *
+ * translator.translate("greeting", "en", { name: "Alice" });
+ * // → "Hello Alice"
+ *
+ * translator.translate("book", "en", { count: 5 });
+ * // → "5 books"
+ * ```
+ */
+export class Translator {
+    /** The default locale used when none is specified */
+    defaultLocale;
+    /** The translation catalog (atomic reference for reload safety) */
+    catalog;
+    /** Cache for parsed locale parts to avoid repeated parsing */
+    localeCache;
+    /** Optional callback for missing translations */
+    onMissingTranslation;
+    /**
+     * Create a new Translator instance.
+     *
+     * @param config - Optional configuration (defaults to "en" locale, empty catalog)
+     */
+    constructor(config) {
+        this.defaultLocale = config?.defaultLocale ?? "en";
+        this.catalog = config?.catalog ?? {};
+        this.localeCache = new Map();
+        this.onMissingTranslation = config?.onMissingTranslation;
+    }
+    /**
+     * Translate a key for a given locale with optional parameter interpolation.
+     *
+     * Locale fallback chain: exact locale → language only → key as-is.
+     * Plural selection: if the translation value is a [singular, plural] tuple
+     * and params contains a `count` property, the appropriate form is selected.
+     *
+     * @param key - Translation key (e.g., "greeting", "auth.login")
+     * @param locale - Target locale (e.g., "en_GB", "nl"). Uses defaultLocale if omitted.
+     * @param params - Optional interpolation parameters
+     * @returns The translated, interpolated string
+     *
+     * @example
+     * translator.translate("greeting", "en", { name: "Alice" })
+     * // → "Hello Alice"
+     *
+     * translator.translate("book", "en", { count: 1 })
+     * // → "1 book"
+     *
+     * translator.translate("book", "en", { count: 5 })
+     * // → "5 books"
+     *
+     * translator.translate("unknown.key", "en")
+     * // → "unknown.key" (key returned as-is)
+     */
+    translate(key, locale, params) {
+        const resolvedLocale = locale ?? this.defaultLocale;
+        const localeParts = this.parseLocale(resolvedLocale);
+        // Look up the entry for this key
+        const entry = this.catalog[key];
+        if (!entry) {
+            // Key not found — invoke callback and return key as-is
+            this.onMissingTranslation?.(key, resolvedLocale);
+            return key;
+        }
+        // Resolve the best value using the locale fallback chain
+        const value = this.resolveValue(entry, localeParts);
+        if (value === undefined) {
+            // No value for this locale — invoke callback and return key
+            this.onMissingTranslation?.(key, resolvedLocale);
+            return key;
+        }
+        // Select singular/plural form if applicable
+        const selectedString = this.selectPlural(value, params);
+        // Interpolate parameters using formatString from stdlib
+        return formatString(selectedString, params);
+    }
+    /**
+     * Get all translations for a specific locale as a flat key-value map.
+     *
+     * Resolves each key using the locale fallback chain (exact → language).
+     * Plural values are returned as-is (the array form) since the client
+     * needs both forms for dynamic count-based selection.
+     *
+     * Primarily used to serve translations to frontend clients.
+     *
+     * @param locale - Target locale (e.g., "en", "nl_NL")
+     * @returns Flat map of { key: resolvedValue } for the locale
+     *
+     * @example
+     * translator.getTranslationsForLocale("nl")
+     * // → { greeting: "Hallo ${name}", book: ["${count} boek", "${count} boeken"] }
+     */
+    getTranslationsForLocale(locale) {
+        const localeParts = this.parseLocale(locale);
+        const result = {};
+        for (const [key, entry] of Object.entries(this.catalog)) {
+            const value = this.resolveValue(entry, localeParts);
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Check if a translation key exists, optionally for a specific locale.
+     *
+     * @param key - Translation key
+     * @param locale - Optional: check for this specific locale (with fallback)
+     * @returns true if the key exists (and has a value for the locale if specified)
+     */
+    hasKey(key, locale) {
+        const entry = this.catalog[key];
+        if (!entry)
+            return false;
+        if (!locale)
+            return true;
+        // Check if the key has a value for the requested locale (with fallback)
+        const localeParts = this.parseLocale(locale);
+        return this.resolveValue(entry, localeParts) !== undefined;
+    }
+    /**
+     * Atomically replace the translation catalog.
+     *
+     * Used by the reload mechanism to swap in a new catalog without
+     * affecting ongoing translations. The old catalog serves current
+     * requests; the new catalog serves subsequent ones.
+     *
+     * @param catalog - The new translation catalog
+     */
+    setCatalog(catalog) {
+        this.catalog = catalog;
+        // Clear locale cache since new catalog may have different locale coverage
+        this.localeCache.clear();
+    }
+    /**
+     * Get the current translation catalog.
+     * Primarily useful for testing and debugging.
+     *
+     * @returns The current TranslationCatalog
+     */
+    getCatalog() {
+        return this.catalog;
+    }
+    /**
+     * Get the configured default locale.
+     * @returns The default locale string
+     */
+    getDefaultLocale() {
+        return this.defaultLocale;
+    }
+    /**
+     * Parse and cache a locale string into its component parts.
+     *
+     * Handles formats like:
+     * - "en" → { full: "en", language: "en" }
+     * - "en_GB" → { full: "en_GB", language: "en", region: "GB" }
+     * - "en-GB" → { full: "en_GB", language: "en", region: "GB" } (normalizes dash to underscore)
+     * - "en_GB.UTF-8" → { full: "en_GB", language: "en", region: "GB" } (strips encoding)
+     *
+     * Results are cached in a Map for O(1) subsequent lookups.
+     *
+     * @param locale - The locale string to parse
+     * @returns Parsed LocaleParts
+     */
+    parseLocale(locale) {
+        // Check cache first
+        const cached = this.localeCache.get(locale);
+        if (cached)
+            return cached;
+        // Strip encoding (e.g., ".UTF-8")
+        const withoutEncoding = locale.split(".")[0];
+        // Normalize dash to underscore (e.g., "en-GB" → "en_GB")
+        const normalized = withoutEncoding.replace("-", "_");
+        // Split on underscore to get language and optional region
+        const parts = normalized.split("_");
+        const language = parts[0];
+        const region = parts.length > 1 ? parts[1] : undefined;
+        const result = {
+            full: normalized,
+            language,
+            region,
+        };
+        // Cache for future lookups
+        this.localeCache.set(locale, result);
+        return result;
+    }
+    /**
+     * Resolve the best translation value from an entry for a given locale.
+     *
+     * Fallback chain:
+     * 1. Exact match: entry[locale_full] (e.g., entry["en_GB"])
+     * 2. Language match: entry[language] (e.g., entry["en"])
+     * 3. undefined (not found)
+     *
+     * @param entry - The translation entry for a key
+     * @param localeParts - Parsed locale parts
+     * @returns The resolved value, or undefined if no match
+     */
+    resolveValue(entry, localeParts) {
+        // Try exact locale match first (e.g., "en_GB")
+        if (entry[localeParts.full] !== undefined) {
+            return entry[localeParts.full];
+        }
+        // Fall back to language-only match (e.g., "en")
+        // Only try if full locale differs from language (has a region)
+        if (localeParts.region && entry[localeParts.language] !== undefined) {
+            return entry[localeParts.language];
+        }
+        return undefined;
+    }
+    /**
+     * Select singular or plural form based on the `count` parameter.
+     *
+     * If the value is a [singular, plural] tuple and params.count exists
+     * and is a number:
+     * - count === 1 → singular (index 0)
+     * - count !== 1 → plural (index 1)
+     *
+     * If the value is a simple string, returns it unchanged.
+     * If count is not a valid number, defaults to singular.
+     *
+     * @param value - The translation value (string or [singular, plural])
+     * @param params - Parameters that may contain a `count` property
+     * @returns The selected string form
+     */
+    selectPlural(value, params) {
+        // Simple string — return as-is
+        if (typeof value === "string") {
+            return value;
+        }
+        // Plural tuple — select based on count
+        const count = params?.count;
+        if (typeof count === "number" && !Number.isNaN(count)) {
+            return count === 1 ? value[0] : value[1];
+        }
+        // No valid count — default to singular form
+        return value[0];
+    }
+}
+//# sourceMappingURL=translator.js.map

package/dist/i18n/translator.js.map

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

package/dist/i18n/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A single translation value.
+ *
+ * Can be either:
+ * - A simple string: "Hello ${name}"
+ * - A plural pair: ["${count} book", "${count} books"]
+ *   where index 0 = singular, index 1 = plural
+ */
+export type TranslationValue = string | [singular: string, plural: string];
+/**
+ * A translation entry: one key mapped to all its locale translations.
+ *
+ * Keys are locale identifiers (e.g., "en", "en_GB", "nl", "nl_NL").
+ * Values are either simple strings or [singular, plural] tuples.
+ *
+ * @example
+ * {
+ *     en: "Hello ${name}",
+ *     nl: "Hallo ${name}",
+ *     de: "Hallo ${name}",
+ * }
+ *
+ * @example Plural
+ * {
+ *     en: ["${count} book", "${count} books"],
+ *     nl: ["${count} boek", "${count} boeken"],
+ * }
+ */
+export type TranslationEntry = Record<string, TranslationValue>;
+/**
+ * The complete translation catalog.
+ *
+ * A flat map of translation keys to their locale entries.
+ * Keys use dot-notation by convention for namespacing (e.g., "auth.login_button").
+ *
+ * @example
+ * {
+ *     "greeting": { en: "Hello", nl: "Hallo" },
+ *     "auth.login": { en: "Log in", nl: "Inloggen" },
+ *     "item_count": { en: ["${count} item", "${count} items"] },
+ * }
+ */
+export type TranslationCatalog = Record<string, TranslationEntry>;
+/**
+ * Configuration for creating a Translator instance.
+ */
+export interface TranslatorConfig {
+    /**
+     * The default locale to use when no locale is specified.
+     * @default "en"
+     */
+    defaultLocale?: string;
+    /**
+     * Initial translation catalog. Can be empty if translations
+     * will be loaded later via sources.
+     */
+    catalog?: TranslationCatalog;
+    /**
+     * Optional callback invoked when a translation key is not found.
+     * Useful for logging missing translations during development.
+     */
+    onMissingTranslation?: (key: string, locale: string) => void;
+}
+/**
+ * Parsed locale parts.
+ * Splits a locale identifier into its component parts.
+ *
+ * @example
+ * "en_GB.UTF-8" → { full: "en_GB", language: "en", region: "GB" }
+ * "nl" → { full: "nl", language: "nl", region: undefined }
+ */
+export interface LocaleParts {
+    /** The cleaned locale (encoding stripped): "en_GB" */
+    full: string;
+    /** The language part: "en" */
+    language: string;
+    /** The region part (if present): "GB" */
+    region?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAE7B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAChE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IACxB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/i18n/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/i18n/types.js.map

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

package/dist/postgresql/database.d.ts

@@ -0,0 +1,204 @@
+import { Database, DatabaseConfig, DeleteStatement, ExecuteQueryOptions, InsertStatement, QueryResult, UpdateStatement } from '../dbcore/index.js';
+import { FieldDef, Pool, PoolClient } from 'pg';
+/**
+ * Configuration options for the PostgreSQL connection pool.
+ * All properties are optional and have sensible defaults.
+ *
+ * @export
+ * @interface PoolConfig
+ */
+export interface PoolConfig {
+    /**
+     * Maximum number of clients in the pool (default: 10)
+     * @type {number}
+     */
+    max?: number;
+    /**
+     * Number of milliseconds a client must sit idle before being closed (default: 30000)
+     * @type {number}
+     */
+    idleTimeoutMillis?: number;
+    /**
+     * Number of milliseconds to wait before timing out when connecting a new client (default: 0 - no timeout)
+     * @type {number}
+     */
+    connectionTimeoutMillis?: number;
+}
+/**
+ * Defines the configuration options for PostgreSQL database connections.
+ * Extends the base DatabaseConfig with PostgreSQL-specific settings.
+ *
+ * @export
+ * @interface PostgreSQLConfig
+ * @extends {DatabaseConfig}
+ */
+export interface PostgreSQLConfig extends DatabaseConfig {
+    /**
+     * Optional pool configuration for connection management
+     * @type {PoolConfig}
+     */
+    poolConfig?: PoolConfig;
+    /**
+     * Enable automatic graceful shutdown handlers for SIGINT/SIGTERM (default: false).
+     *
+     * **⚠️ WARNING:** Do NOT enable this when the database is managed by a WebApplication
+     * (from `@blendsdk/webafx`), which has its own shutdown handling via SIGTERM/SIGINT.
+     * Enabling both will cause signal handler conflicts and unpredictable shutdown behavior.
+     * Only enable this for standalone database usage outside of the web framework.
+     *
+     * @type {boolean}
+     */
+    enableGracefulShutdown?: boolean;
+}
+/**
+ * Represents the result of a PostgreSQL query execution.
+ * Extends the base QueryResult with PostgreSQL-specific field definitions.
+ *
+ * @export
+ * @interface PostgreSQLQueryResult
+ * @template T - The type of records returned by the query
+ * @extends {QueryResult<T>}
+ */
+export interface PostgreSQLQueryResult<T> extends QueryResult<T> {
+    /**
+     * Array of field definitions describing the structure of returned columns
+     * @type {FieldDef[]}
+     */
+    fields: FieldDef[];
+}
+/**
+ * Provides PostgreSQL database connectivity and query execution capabilities.
+ * Manages connection pooling, transactions, and statement creation for PostgreSQL databases.
+ * Extends the base Database class with PostgreSQL-specific implementations.
+ *
+ * @export
+ * @class PostgreSQLDatabase
+ * @extends {Database}
+ */
+export declare class PostgreSQLDatabase extends Database {
+    /**
+     * The PostgreSQL connection pool for managing database connections
+     * @protected
+     * @type {Pool}
+     * @memberof PostgreSQLDatabase
+     */
+    protected pool: Pool;
+    /**
+     * The current transaction client, null when no transaction is active
+     * @protected
+     * @type {(PoolClient | null)}
+     * @memberof PostgreSQLDatabase
+     */
+    protected transactionClient: PoolClient | null;
+    /**
+     * Flag to prevent new connections during shutdown
+     * @protected
+     * @type {boolean}
+     * @memberof PostgreSQLDatabase
+     */
+    protected isShuttingDown: boolean;
+    /**
+     * Creates an instance of PostgreSQLDatabase.
+     * Initializes the connection pool with the provided configuration settings.
+     *
+     * @param {PostgreSQLConfig} config - The database configuration including host, port, credentials, and database name
+     * @memberof PostgreSQLDatabase
+     */
+    constructor(config: PostgreSQLConfig);
+    /**
+     * Executes a function within a database transaction context.
+     * Automatically handles BEGIN, COMMIT, and ROLLBACK operations.
+     * Ensures proper cleanup of transaction resources in all scenarios.
+     *
+     * @template T - The return type of the transaction function
+     * @param {(db: this) => Promise<T>} fn - The function to execute within the transaction context
+     * @return {Promise<T>} Promise resolving to the result of the transaction function
+     * @throws {Error} When the transaction function fails, triggers automatic ROLLBACK
+     * @memberof PostgreSQLDatabase
+     */
+    withTransaction<T>(fn: (db: this) => Promise<T>): Promise<T>;
+    /**
+     * Acquires a client connection from the connection pool.
+     * Used internally for transaction management and query execution.
+     *
+     * @return {Promise<PoolClient>} Promise resolving to a PostgreSQL client connection
+     * @memberof PostgreSQLDatabase
+     */
+    connect(): Promise<PoolClient>;
+    /**
+     * Closes all connections in the pool and terminates the database connection.
+     * Implements timeout protection to prevent hanging on unreleased connections.
+     * Should be called when the application is shutting down to ensure clean resource cleanup.
+     *
+     * @param {number} [timeoutMs=10000] - Maximum time to wait for graceful shutdown in milliseconds
+     * @return {Promise<void>} Promise that resolves when all connections are closed
+     * @throws {Error} When disconnect times out, after forcing connection closure
+     * @memberof PostgreSQLDatabase
+     */
+    disconnect(timeoutMs?: number): Promise<void>;
+    /**
+     * Forcefully closes all connections in the pool without waiting for graceful shutdown.
+     * This is a last resort method used when normal disconnect times out.
+     * Warning: This may interrupt active queries and transactions.
+     *
+     * @protected
+     * @return {Promise<void>} Promise that resolves when all connections are forcefully closed
+     * @memberof PostgreSQLDatabase
+     */
+    protected forceDisconnect(): Promise<void>;
+    /**
+     * Registers signal handlers for graceful shutdown on SIGINT and SIGTERM.
+     * Automatically calls disconnect() when these signals are received.
+     * Only registered if enableGracefulShutdown is true in config.
+     *
+     * @protected
+     * @memberof PostgreSQLDatabase
+     */
+    protected registerShutdownHandlers(): void;
+    /**
+     * Executes a parameterized SQL query against the PostgreSQL database.
+     * Handles named parameter substitution, transaction management, and query hooks.
+     * Automatically manages connection acquisition and release for non-transactional queries.
+     *
+     * @template R - The type of records returned by the query
+     * @param {string} query - The SQL query string with named parameters (e.g., :paramName)
+     * @param {Record<string, any>} [params] - Object containing named parameter values
+     * @param {ExecuteQueryOptions} [options] - Optional query execution options including beforeQuery and afterQuery hooks
+     * @return {Promise<PostgreSQLQueryResult<R>>} Promise resolving to query results including records, row count, and field definitions
+     * @throws {Error} When no database connection is available
+     * @memberof PostgreSQLDatabase
+     */
+    executeQuery<R>(query: string, params?: Record<string, any>, options?: ExecuteQueryOptions): Promise<PostgreSQLQueryResult<R>>;
+    /**
+     * Creates a new INSERT statement builder for the specified table.
+     * Provides a fluent interface for constructing INSERT queries.
+     *
+     * @template T - The type representing the table structure
+     * @param {string} tableName - The name of the table to insert into
+     * @return {InsertStatement<T>} A new INSERT statement builder instance
+     * @memberof PostgreSQLDatabase
+     */
+    insert<T>(tableName: string): InsertStatement<T>;
+    /**
+     * Creates a new UPDATE statement builder for the specified table.
+     * Provides a fluent interface for constructing UPDATE queries with filtering.
+     *
+     * @template T - The type representing the table structure
+     * @template F - The type representing the filter criteria
+     * @param {string} tableName - The name of the table to update
+     * @return {UpdateStatement<T, F>} A new UPDATE statement builder instance
+     * @memberof PostgreSQLDatabase
+     */
+    update<T, F>(tableName: string): UpdateStatement<T, F>;
+    /**
+     * Creates a new DELETE statement builder for the specified table.
+     * Provides a fluent interface for constructing DELETE queries with filtering.
+     *
+     * @template F - The type representing the filter criteria
+     * @param {string} tableName - The name of the table to delete from
+     * @return {DeleteStatement<F>} A new DELETE statement builder instance
+     * @memberof PostgreSQLDatabase
+     */
+    delete<F>(tableName: string): DeleteStatement<F>;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/postgresql/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAMhD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC9D;;;OAGG;IACH,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC;IAErB;;;;;OAKG;IACH,SAAS,CAAC,iBAAiB,EAAE,UAAU,GAAG,IAAI,CAAQ;IAEtD;;;;;OAKG;IACH,SAAS,CAAC,cAAc,EAAE,OAAO,CAAS;IAE1C;;;;;;OAMG;gBACS,MAAM,EAAE,gBAAgB;IAuBpC;;;;;;;;;;OAUG;IACG,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA4ClE;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAI9B;;;;;;;;;OASG;IACG,UAAU,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1D;;;;;;;;OAQG;cACa,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBhD;;;;;;;OAOG;IACH,SAAS,CAAC,wBAAwB,IAAI,IAAI;IAiB1C;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,CAAC,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IA6DpC;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;IAIhD;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAItD;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;CAIjD"}