@agentuity/postgres 0.1.41

package/dist/reconnect.d.ts

@@ -0,0 +1,31 @@
+import type { ReconnectConfig } from './types';
+/**
+ * Default reconnection configuration values.
+ */
+export declare const DEFAULT_RECONNECT_CONFIG: Required<ReconnectConfig>;
+/**
+ * Computes the backoff delay for a reconnection attempt using exponential backoff with jitter.
+ *
+ * The delay is calculated as:
+ * `min(maxDelayMs, initialDelayMs * (multiplier ^ attempt)) + random(0, jitterMs)`
+ *
+ * @param attempt - The current attempt number (0-indexed)
+ * @param config - Reconnection configuration
+ * @returns The delay in milliseconds before the next reconnection attempt
+ */
+export declare function computeBackoff(attempt: number, config?: Partial<ReconnectConfig>): number;
+/**
+ * Sleeps for the specified number of milliseconds.
+ *
+ * @param ms - The number of milliseconds to sleep
+ * @returns A promise that resolves after the specified delay
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Merges user-provided reconnect config with defaults.
+ *
+ * @param config - User-provided reconnect configuration
+ * @returns Complete reconnect configuration with all values filled in
+ */
+export declare function mergeReconnectConfig(config?: Partial<ReconnectConfig>): Required<ReconnectConfig>;
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../src/reconnect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,eAAe,CAO9D,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,MAAM,CAkB7F;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC,CAajG"}

package/dist/reconnect.js

@@ -0,0 +1,60 @@
+/**
+ * Default reconnection configuration values.
+ */
+export const DEFAULT_RECONNECT_CONFIG = {
+    maxAttempts: 10,
+    initialDelayMs: 100,
+    maxDelayMs: 30000,
+    multiplier: 2,
+    jitterMs: 1000,
+    enabled: true,
+};
+/**
+ * Computes the backoff delay for a reconnection attempt using exponential backoff with jitter.
+ *
+ * The delay is calculated as:
+ * `min(maxDelayMs, initialDelayMs * (multiplier ^ attempt)) + random(0, jitterMs)`
+ *
+ * @param attempt - The current attempt number (0-indexed)
+ * @param config - Reconnection configuration
+ * @returns The delay in milliseconds before the next reconnection attempt
+ */
+export function computeBackoff(attempt, config = {}) {
+    const { initialDelayMs = DEFAULT_RECONNECT_CONFIG.initialDelayMs, maxDelayMs = DEFAULT_RECONNECT_CONFIG.maxDelayMs, multiplier = DEFAULT_RECONNECT_CONFIG.multiplier, jitterMs = DEFAULT_RECONNECT_CONFIG.jitterMs, } = config;
+    // Calculate exponential delay
+    const exponentialDelay = initialDelayMs * Math.pow(multiplier, attempt);
+    // Cap at maximum delay
+    const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+    // Add random jitter to prevent thundering herd
+    const jitter = Math.random() * jitterMs;
+    return Math.floor(cappedDelay + jitter);
+}
+/**
+ * Sleeps for the specified number of milliseconds.
+ *
+ * @param ms - The number of milliseconds to sleep
+ * @returns A promise that resolves after the specified delay
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Merges user-provided reconnect config with defaults.
+ *
+ * @param config - User-provided reconnect configuration
+ * @returns Complete reconnect configuration with all values filled in
+ */
+export function mergeReconnectConfig(config) {
+    if (!config) {
+        return { ...DEFAULT_RECONNECT_CONFIG };
+    }
+    return {
+        maxAttempts: config.maxAttempts ?? DEFAULT_RECONNECT_CONFIG.maxAttempts,
+        initialDelayMs: config.initialDelayMs ?? DEFAULT_RECONNECT_CONFIG.initialDelayMs,
+        maxDelayMs: config.maxDelayMs ?? DEFAULT_RECONNECT_CONFIG.maxDelayMs,
+        multiplier: config.multiplier ?? DEFAULT_RECONNECT_CONFIG.multiplier,
+        jitterMs: config.jitterMs ?? DEFAULT_RECONNECT_CONFIG.jitterMs,
+        enabled: config.enabled ?? DEFAULT_RECONNECT_CONFIG.enabled,
+    };
+}
+//# sourceMappingURL=reconnect.js.map

package/dist/reconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.js","sourceRoot":"","sources":["../src/reconnect.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA8B;IAClE,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,GAAG;IACnB,UAAU,EAAE,KAAK;IACjB,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;CACb,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,SAAmC,EAAE;IACpF,MAAM,EACL,cAAc,GAAG,wBAAwB,CAAC,cAAc,EACxD,UAAU,GAAG,wBAAwB,CAAC,UAAU,EAChD,UAAU,GAAG,wBAAwB,CAAC,UAAU,EAChD,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,GAC5C,GAAG,MAAM,CAAC;IAEX,8BAA8B;IAC9B,MAAM,gBAAgB,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAExE,uBAAuB;IACvB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;IAE3D,+CAA+C;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC;IAExC,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAiC;IACrE,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,OAAO,EAAE,GAAG,wBAAwB,EAAE,CAAC;IACxC,CAAC;IAED,OAAO;QACN,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,wBAAwB,CAAC,WAAW;QACvE,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,wBAAwB,CAAC,cAAc;QAChF,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,wBAAwB,CAAC,UAAU;QACpE,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,wBAAwB,CAAC,UAAU;QACpE,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,wBAAwB,CAAC,QAAQ;QAC9D,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,wBAAwB,CAAC,OAAO;KAC3D,CAAC;AACH,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Global registry for PostgreSQL clients.
+ *
+ * This module provides a way to track all active PostgreSQL clients
+ * so they can be gracefully shut down together (e.g., on process exit).
+ *
+ * The runtime can use `shutdownAll()` to close all registered clients
+ * during graceful shutdown.
+ *
+ * When @agentuity/runtime is available, this module automatically registers
+ * a shutdown hook so all postgres clients are closed during graceful shutdown.
+ */
+import type { PostgresClient } from './client';
+/**
+ * Registers a client in the global registry.
+ * Called automatically when a client is created.
+ *
+ * @param client - The client to register
+ * @internal
+ */
+export declare function registerClient(client: PostgresClient): void;
+/**
+ * Unregisters a client from the global registry.
+ * Called automatically when a client is closed.
+ *
+ * @param client - The client to unregister
+ * @internal
+ */
+export declare function unregisterClient(client: PostgresClient): void;
+/**
+ * Returns the number of registered clients.
+ * Useful for debugging and testing.
+ */
+export declare function getClientCount(): number;
+/**
+ * Returns all registered clients.
+ * Useful for debugging and monitoring.
+ */
+export declare function getClients(): ReadonlySet<PostgresClient>;
+/**
+ * Shuts down all registered PostgreSQL clients gracefully.
+ *
+ * This function:
+ * 1. Signals shutdown to all clients (prevents reconnection)
+ * 2. Closes all clients in parallel
+ * 3. Clears the registry
+ *
+ * This is intended to be called by the runtime during graceful shutdown.
+ *
+ * @param timeoutMs - Optional timeout in milliseconds. If provided, the function
+ *                    will resolve after the timeout even if some clients haven't
+ *                    finished closing. Default: no timeout.
+ * @returns A promise that resolves when all clients are closed (or timeout)
+ *
+ * @example
+ * ```typescript
+ * import { shutdownAll } from '@agentuity/postgres';
+ *
+ * process.on('SIGTERM', async () => {
+ *   await shutdownAll(5000); // 5 second timeout
+ *   process.exit(0);
+ * });
+ * ```
+ */
+export declare function shutdownAll(timeoutMs?: number): Promise<void>;
+/**
+ * Checks if there are any active (non-shutdown) clients.
+ * Useful for health checks.
+ */
+export declare function hasActiveClients(): boolean;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAuB/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,WAAW,CAAC,cAAc,CAAC,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCnE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAQ1C"}

package/dist/registry.js

@@ -0,0 +1,175 @@
+/**
+ * Global registry for PostgreSQL clients.
+ *
+ * This module provides a way to track all active PostgreSQL clients
+ * so they can be gracefully shut down together (e.g., on process exit).
+ *
+ * The runtime can use `shutdownAll()` to close all registered clients
+ * during graceful shutdown.
+ *
+ * When @agentuity/runtime is available, this module automatically registers
+ * a shutdown hook so all postgres clients are closed during graceful shutdown.
+ */
+/**
+ * Symbol used to store the registry in globalThis to avoid conflicts.
+ */
+const REGISTRY_KEY = Symbol.for('@agentuity/postgres:registry');
+/**
+ * Symbol used to track if we've registered with the runtime.
+ */
+const RUNTIME_HOOK_REGISTERED = Symbol.for('@agentuity/postgres:runtime-hook-registered');
+/**
+ * Gets the global client registry, creating it if it doesn't exist.
+ */
+function getRegistry() {
+    const global = globalThis;
+    if (!global[REGISTRY_KEY]) {
+        global[REGISTRY_KEY] = new Set();
+    }
+    return global[REGISTRY_KEY];
+}
+/**
+ * Registers a client in the global registry.
+ * Called automatically when a client is created.
+ *
+ * @param client - The client to register
+ * @internal
+ */
+export function registerClient(client) {
+    getRegistry().add(client);
+}
+/**
+ * Unregisters a client from the global registry.
+ * Called automatically when a client is closed.
+ *
+ * @param client - The client to unregister
+ * @internal
+ */
+export function unregisterClient(client) {
+    getRegistry().delete(client);
+}
+/**
+ * Returns the number of registered clients.
+ * Useful for debugging and testing.
+ */
+export function getClientCount() {
+    return getRegistry().size;
+}
+/**
+ * Returns all registered clients.
+ * Useful for debugging and monitoring.
+ */
+export function getClients() {
+    return getRegistry();
+}
+/**
+ * Shuts down all registered PostgreSQL clients gracefully.
+ *
+ * This function:
+ * 1. Signals shutdown to all clients (prevents reconnection)
+ * 2. Closes all clients in parallel
+ * 3. Clears the registry
+ *
+ * This is intended to be called by the runtime during graceful shutdown.
+ *
+ * @param timeoutMs - Optional timeout in milliseconds. If provided, the function
+ *                    will resolve after the timeout even if some clients haven't
+ *                    finished closing. Default: no timeout.
+ * @returns A promise that resolves when all clients are closed (or timeout)
+ *
+ * @example
+ * ```typescript
+ * import { shutdownAll } from '@agentuity/postgres';
+ *
+ * process.on('SIGTERM', async () => {
+ *   await shutdownAll(5000); // 5 second timeout
+ *   process.exit(0);
+ * });
+ * ```
+ */
+export async function shutdownAll(timeoutMs) {
+    const registry = getRegistry();
+    const clients = Array.from(registry);
+    if (clients.length === 0) {
+        return;
+    }
+    // Signal shutdown to all clients first (prevents reconnection attempts)
+    for (const client of clients) {
+        client.shutdown();
+    }
+    // Close all clients in parallel
+    const closePromises = clients.map(async (client) => {
+        try {
+            await client.close();
+        }
+        catch {
+            // Ignore close errors during shutdown
+        }
+    });
+    // Wait for all to close, with optional timeout
+    if (timeoutMs !== undefined) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        });
+        try {
+            await Promise.race([Promise.all(closePromises), timeout]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    else {
+        await Promise.all(closePromises);
+    }
+    // Clear the registry
+    registry.clear();
+}
+/**
+ * Checks if there are any active (non-shutdown) clients.
+ * Useful for health checks.
+ */
+export function hasActiveClients() {
+    const registry = getRegistry();
+    for (const client of registry) {
+        if (!client.shuttingDown) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Attempts to register a shutdown hook with @agentuity/runtime if available.
+ * This is called automatically when the first client is registered.
+ *
+ * @internal
+ */
+function tryRegisterRuntimeHook() {
+    const global = globalThis;
+    // Only try once
+    if (global[RUNTIME_HOOK_REGISTERED]) {
+        return;
+    }
+    global[RUNTIME_HOOK_REGISTERED] = true;
+    // Try to dynamically import the runtime and register our shutdown hook
+    // This is done asynchronously to avoid blocking client creation
+    // and to handle the case where runtime is not available
+    // Using Function constructor to avoid TypeScript trying to resolve the module at build time
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    dynamicImport('@agentuity/runtime')
+        .then((runtime) => {
+        if (typeof runtime.registerShutdownHook === 'function') {
+            runtime.registerShutdownHook(async () => {
+                await shutdownAll(5000); // 5 second timeout for graceful shutdown
+            });
+        }
+    })
+        .catch(() => {
+        // Runtime not available - that's fine, user can call shutdownAll manually
+    });
+}
+// Try to register with runtime when this module is first loaded
+tryRegisterRuntimeHook();
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/transaction.d.ts

@@ -0,0 +1,147 @@
+import type { SQL, SQLQuery } from 'bun';
+/**
+ * Represents a PostgreSQL transaction with support for savepoints.
+ *
+ * Transactions are created via `PostgresClient.begin()` and support
+ * tagged template literal syntax for queries.
+ */
+export declare class Transaction {
+    private _sql;
+    private _connection;
+    private _committed;
+    private _rolledBack;
+    private _savepointCounter;
+    constructor(sql: SQL, connection: SQLQuery);
+    /**
+     * Whether the transaction has been committed.
+     */
+    get committed(): boolean;
+    /**
+     * Whether the transaction has been rolled back.
+     */
+    get rolledBack(): boolean;
+    /**
+     * Whether the transaction is still active (not committed or rolled back).
+     */
+    get active(): boolean;
+    /**
+     * Execute a query within this transaction using tagged template literal syntax.
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.begin();
+     * const result = await tx`SELECT * FROM users WHERE id = ${userId}`;
+     * await tx.commit();
+     * ```
+     */
+    query(strings: TemplateStringsArray, ...values: unknown[]): SQLQuery;
+    /**
+     * Create a savepoint within this transaction.
+     *
+     * @param name - Optional name for the savepoint. If not provided, a unique name is generated.
+     *               If provided, must be a valid SQL identifier (alphanumeric and underscores only,
+     *               starting with a letter or underscore).
+     * @returns A Savepoint object that can be used to rollback to this point.
+     * @throws {TransactionError} If the provided name is not a valid SQL identifier.
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.begin();
+     * await tx`INSERT INTO users (name) VALUES ('Alice')`;
+     *
+     * const sp = await tx.savepoint();
+     * await tx`INSERT INTO users (name) VALUES ('Bob')`;
+     *
+     * // Oops, rollback Bob but keep Alice
+     * await sp.rollback();
+     *
+     * await tx.commit(); // Only Alice is committed
+     * ```
+     */
+    savepoint(name?: string): Promise<Savepoint>;
+    /**
+     * Commit the transaction.
+     *
+     * @throws {TransactionError} If the transaction is not active or commit fails.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction.
+     *
+     * @throws {TransactionError} If the transaction is not active or rollback fails.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Ensures the transaction is still active.
+     */
+    private _ensureActive;
+}
+/**
+ * Represents a savepoint within a transaction.
+ */
+export declare class Savepoint {
+    private _sql;
+    private _name;
+    private _released;
+    private _rolledBack;
+    constructor(sql: SQL, name: string);
+    /**
+     * The name of this savepoint.
+     */
+    get name(): string;
+    /**
+     * Whether the savepoint has been released.
+     */
+    get released(): boolean;
+    /**
+     * Whether the savepoint has been rolled back to.
+     */
+    get rolledBack(): boolean;
+    /**
+     * Rollback to this savepoint.
+     * All changes made after this savepoint was created will be undone.
+     *
+     * @throws {TransactionError} If the savepoint has been released or already rolled back.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Release this savepoint.
+     * The savepoint is destroyed but changes are kept.
+     */
+    release(): Promise<void>;
+}
+/**
+ * Represents a reserved (exclusive) connection from the pool.
+ *
+ * Reserved connections are created via `PostgresClient.reserve()` and support
+ * tagged template literal syntax for queries.
+ */
+export declare class ReservedConnection {
+    private _sql;
+    private _released;
+    constructor(sql: SQL);
+    /**
+     * Whether the connection has been released back to the pool.
+     */
+    get released(): boolean;
+    /**
+     * Execute a query on this reserved connection using tagged template literal syntax.
+     *
+     * @example
+     * ```typescript
+     * const conn = await client.reserve();
+     * try {
+     *   await conn`SET LOCAL timezone = 'UTC'`;
+     *   const result = await conn`SELECT NOW()`;
+     * } finally {
+     *   conn.release();
+     * }
+     * ```
+     */
+    query(strings: TemplateStringsArray, ...values: unknown[]): SQLQuery;
+    /**
+     * Release the connection back to the pool.
+     */
+    release(): void;
+}
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAGzC;;;;;GAKG;AACH,qBAAa,WAAW;IACvB,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAK;gBAElB,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ;IAK1C;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ;IAKpE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IA2BlD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAe7B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAe/B;;OAEG;IACH,OAAO,CAAC,aAAa;CAcrB;AAED;;GAEG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;gBAEhB,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM;IAKlC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B/B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB9B;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,SAAS,CAAS;gBAEd,GAAG,EAAE,GAAG;IAIpB;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ;IASpE;;OAEG;IACH,OAAO,IAAI,IAAI;CAQf"}