@sudobility/types 1.9.53 → 1.9.55

package/dist/types/common.d.ts

@@ -1,15 +1,42 @@
 /**
- * Common utility types used throughout the application
+ * Common utility types used throughout the application.
+ *
+ * Provides foundational types like {@link Optional}, {@link Result},
+ * {@link ValidationResult}, and API response structures used across
+ * every package in the ecosystem.
+ *
+ * @since 1.0.0
  */
 import { ChainType } from './business/enums';
 /**
- * Utility type for values that can be T, undefined, or null
- * Provides a more semantic way to represent optional/nullable values
+ * Utility type for values that can be T, undefined, or null.
+ * Use instead of manual `T | null | undefined` unions for consistency.
+ *
+ * @template T - The base type
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   bio?: Optional<string>;
+ * }
+ * ```
  */
 export type Optional<T> = T | undefined | null;
 /**
- * Base wallet data structure containing address and chain type
- * Used across all wallet-related interfaces to ensure consistency
+ * Base wallet data structure containing address and chain type.
+ * Used across all wallet-related interfaces to ensure consistency.
+ *
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const wallet: WalletData = {
+ *   walletAddress: '0x742d35Cc6634C0532925a3b8D2C36B7f1234567',
+ *   chainType: ChainType.EVM,
+ * };
+ * ```
  */
 export interface WalletData {
     /** Wallet address (EVM 0x format or Solana Base58) */
@@ -18,8 +45,10 @@ export interface WalletData {
     chainType: ChainType;
 }
 /**
- * Base folder data structure containing common folder properties
- * Used across all folder/mailbox-related interfaces to ensure consistency
+ * Base folder data structure containing common folder properties.
+ * Used across all folder/mailbox-related interfaces to ensure consistency.
+ *
+ * @since 1.0.0
  */
 export interface FolderBase {
     /** Folder name */
@@ -30,8 +59,10 @@ export interface FolderBase {
     unreadCount: number;
 }
 /**
- * Base message structure containing core message fields
- * Used across all message/email-related interfaces to ensure consistency
+ * Base message structure containing core message fields.
+ * Used across all message/email-related interfaces to ensure consistency.
+ *
+ * @since 1.0.0
  */
 export interface MessageBase {
     /** Message sender */
@@ -44,8 +75,20 @@ export interface MessageBase {
     body: string;
 }
 /**
- * Base response structure for all API operations
- * Unified response interface for consistency across the entire application
+ * Base response structure for all API operations.
+ * Unified response interface for consistency across the entire application.
+ *
+ * @template T - The response data type (defaults to `unknown`)
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const response: BaseResponse<User> = {
+ *   success: true,
+ *   data: { name: 'Alice' },
+ *   timestamp: new Date().toISOString(),
+ * };
+ * ```
  */
 export interface BaseResponse<T = unknown> {
     /** Operation success status */
@@ -58,7 +101,19 @@ export interface BaseResponse<T = unknown> {
     timestamp: string;
 }
 /**
- * Unified pagination options for querying
+ * Unified pagination options for querying.
+ * Supports both offset-based and cursor-based pagination.
+ *
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const opts: PaginationOptions = {
+ *   limit: 20,
+ *   cursor: 'abc123',
+ *   sortOrder: 'desc',
+ * };
+ * ```
  */
 export interface PaginationOptions {
     /** Number of items per page */
@@ -71,7 +126,9 @@ export interface PaginationOptions {
     sortOrder?: Optional<'asc' | 'desc'>;
 }
 /**
- * Unified pagination metadata for responses
+ * Unified pagination metadata for responses.
+ *
+ * @since 1.0.0
  */
 export interface PaginationInfo {
     /** Whether there are more items after current page */
@@ -88,14 +145,42 @@ export interface PaginationInfo {
     pageSize: number;
 }
 /**
- * Paginated response structure
+ * Paginated response structure extending {@link BaseResponse} with
+ * pagination metadata.
+ *
+ * @template T - The item type in the paginated list
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const page: PaginatedResponse<User> = {
+ *   success: true,
+ *   data: [{ name: 'Alice' }],
+ *   timestamp: new Date().toISOString(),
+ *   pagination: { hasNextPage: true, pageSize: 20 },
+ * };
+ * ```
  */
 export interface PaginatedResponse<T> extends BaseResponse<T[]> {
     /** Pagination metadata */
     pagination: PaginationInfo;
 }
 /**
- * Unified error structure for all operations
+ * Unified error structure for all operations.
+ * Provides typed error categories, human-readable messages,
+ * and optional suggested actions for the user.
+ *
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const error: UnifiedError = {
+ *   type: 'ValidationError',
+ *   message: 'Invalid email address',
+ *   details: { field: 'email' },
+ *   suggestedAction: 'Please enter a valid email.',
+ * };
+ * ```
  */
 export interface UnifiedError {
     /** Error type/code */
@@ -116,9 +201,25 @@ export interface UnifiedError {
     suggestedAction?: Optional<string>;
 }
 /**
- * Result type for operations that can succeed or fail
- * @template T Success result type
- * @template E Error type (defaults to UnifiedError)
+ * Discriminated union for operations that can succeed or fail.
+ * Prefer this over throwing exceptions for recoverable errors.
+ *
+ * @template T - Success result type
+ * @template E - Error type (defaults to {@link UnifiedError})
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * function divide(a: number, b: number): Result<number> {
+ *   if (b === 0) {
+ *     return {
+ *       success: false,
+ *       error: { type: 'ValidationError', message: 'Division by zero' },
+ *     };
+ *   }
+ *   return { success: true, data: a / b };
+ * }
+ * ```
  */
 export type Result<T, E = UnifiedError> = {
     success: true;
@@ -128,8 +229,21 @@ export type Result<T, E = UnifiedError> = {
     error: E;
 };
 /**
- * Unified validation result pattern
- * @template T The validated data type
+ * Unified validation result pattern.
+ * Used by validators and {@link createValidator} to return typed results.
+ *
+ * @template T - The validated data type
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * function validateAge(value: unknown): ValidationResult<number> {
+ *   if (typeof value === 'number' && value >= 0) {
+ *     return { isValid: true, data: value };
+ *   }
+ *   return { isValid: false, error: 'Age must be a non-negative number' };
+ * }
+ * ```
  */
 export type ValidationResult<T = unknown> = {
     isValid: true;

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

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

package/dist/types/common.js

@@ -1,6 +1,12 @@
 "use strict";
 /**
- * Common utility types used throughout the application
+ * Common utility types used throughout the application.
+ *
+ * Provides foundational types like {@link Optional}, {@link Result},
+ * {@link ValidationResult}, and API response structures used across
+ * every package in the ecosystem.
+ *
+ * @since 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=common.js.map

package/dist/types/common.js.map

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

package/dist/utils/async-helpers.cjs

@@ -1,14 +1,32 @@
 "use strict";
 /**
- * Common async operation patterns and helpers
- * Reduces boilerplate code for common async operations
+ * Common async operation patterns and helpers.
+ * Reduces boilerplate code for common async operations.
+ *
+ * @since 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.debounceAsync = exports.clearExpiredCache = exports.withCache = exports.withTimeout = exports.safeParallel = exports.withLoadingState = exports.safeAsync = void 0;
 const logger_1 = require("./logging/logger");
 /**
- * Safely execute an async operation with error handling
- * Returns a result object instead of throwing
+ * Safely execute an async operation with error handling.
+ * Returns a result object instead of throwing.
+ *
+ * @template T - The success data type
+ * @param operation - Async function to execute
+ * @param context - Optional context string for logging
+ * @returns A promise resolving to an {@link AsyncResult}
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await safeAsync(() => fetchUser(id), 'fetchUser');
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error?.message);
+ * }
+ * ```
  */
 const safeAsync = async (operation, context) => {
     try {
@@ -23,7 +41,26 @@ const safeAsync = async (operation, context) => {
 };
 exports.safeAsync = safeAsync;
 /**
- * Execute async operation with loading state tracking
+ * Execute async operation with loading state tracking.
+ * Manages `setLoading` and `setError` callbacks automatically.
+ *
+ * @template T - The success data type
+ * @param operation - Async function to execute
+ * @param setLoading - Callback to update loading state
+ * @param setError - Callback to update error state
+ * @param context - Optional context string for logging
+ * @returns The operation result, or undefined on error
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const data = await withLoadingState(
+ *   () => api.getUsers(),
+ *   setIsLoading,
+ *   setErrorMsg,
+ *   'getUsers'
+ * );
+ * ```
  */
 const withLoadingState = async (operation, setLoading, setError, context) => {
     setLoading(true);
@@ -44,7 +81,22 @@ const withLoadingState = async (operation, setLoading, setError, context) => {
 };
 exports.withLoadingState = withLoadingState;
 /**
- * Execute multiple async operations in parallel with error handling
+ * Execute multiple async operations in parallel with error handling.
+ * All operations run concurrently via `Promise.all`.
+ *
+ * @template T - Tuple of result types
+ * @param operations - Array of async functions to execute in parallel
+ * @param context - Optional context string for logging
+ * @returns A promise resolving to an {@link AsyncResult} of the tuple
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await safeParallel(
+ *   [() => fetchUser(1), () => fetchPosts(1)] as const,
+ *   'loadProfile'
+ * );
+ * ```
  */
 const safeParallel = async (operations, context) => {
     try {
@@ -59,7 +111,25 @@ const safeParallel = async (operations, context) => {
 };
 exports.safeParallel = safeParallel;
 /**
- * Execute async operation with timeout
+ * Execute async operation with a timeout.
+ * Rejects if the operation does not complete within `timeoutMs`.
+ *
+ * @template T - The success data type
+ * @param operation - Async function to execute
+ * @param timeoutMs - Maximum time in milliseconds
+ * @param context - Optional context string for logging
+ * @returns The operation result
+ * @throws Error if the operation times out
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const data = await withTimeout(
+ *   () => fetch('/api/data').then((r) => r.json()),
+ *   5000,
+ *   'fetchData'
+ * );
+ * ```
  */
 const withTimeout = async (operation, timeoutMs, context) => {
     const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Operation timed out after ${timeoutMs}ms`)), timeoutMs));
@@ -73,9 +143,30 @@ const withTimeout = async (operation, timeoutMs, context) => {
 };
 exports.withTimeout = withTimeout;
 /**
- * Cache async operation results with TTL
+ * In-memory cache for {@link withCache}.
  */
 const cache = new Map();
+/**
+ * Cache async operation results with TTL (time-to-live).
+ * Returns cached data if still valid; otherwise executes the operation
+ * and stores the result.
+ *
+ * @template T - The cached data type
+ * @param key - Unique cache key
+ * @param operation - Async function whose result is cached
+ * @param ttlMs - Cache TTL in milliseconds (default: 5 minutes)
+ * @returns The cached or freshly fetched data
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const user = await withCache(
+ *   `user-${id}`,
+ *   () => api.getUser(id),
+ *   60_000 // 1 minute
+ * );
+ * ```
+ */
 const withCache = async (key, operation, ttlMs = 5 * 60 * 1000 // 5 minutes default
 ) => {
     const cached = cache.get(key);
@@ -89,7 +180,8 @@ const withCache = async (key, operation, ttlMs = 5 * 60 * 1000 // 5 minutes defa
 };
 exports.withCache = withCache;
 /**
- * Clear expired cache entries
+ * Clear expired cache entries from the in-memory cache.
+ * @since 1.0.0
  */
 const clearExpiredCache = () => {
     const now = Date.now();
@@ -101,9 +193,31 @@ const clearExpiredCache = () => {
 };
 exports.clearExpiredCache = clearExpiredCache;
 /**
- * Debounce async operations
+ * Active debounce timers keyed by operation key.
  */
 const debounceMap = new Map();
+/**
+ * Debounce async function calls by key.
+ * Only the last call within the delay window will execute.
+ *
+ * @template T - Argument types
+ * @template R - Return type
+ * @param fn - The async function to debounce
+ * @param delay - Debounce delay in milliseconds
+ * @param key - Unique key identifying this debounced operation
+ * @returns A debounced version of `fn`
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = debounceAsync(
+ *   (query: string) => api.search(query),
+ *   300,
+ *   'search'
+ * );
+ * await debouncedSearch('hello');
+ * ```
+ */
 const debounceAsync = (fn, delay, key) => {
     return (...args) => {
         return new Promise(resolve => {

package/dist/utils/async-helpers.d.ts

@@ -1,35 +1,156 @@
 /**
- * Common async operation patterns and helpers
- * Reduces boilerplate code for common async operations
+ * Common async operation patterns and helpers.
+ * Reduces boilerplate code for common async operations.
+ *
+ * @since 1.0.0
  */
 import { Optional } from '../types/common';
+/**
+ * Result type for safe async operations.
+ * Contains either `data` on success or `error` on failure.
+ *
+ * @template T - The success data type
+ * @since 1.0.0
+ */
 type AsyncResult<T> = {
     data?: T;
     error?: Error;
     success: boolean;
 };
 /**
- * Safely execute an async operation with error handling
- * Returns a result object instead of throwing
+ * Safely execute an async operation with error handling.
+ * Returns a result object instead of throwing.
+ *
+ * @template T - The success data type
+ * @param operation - Async function to execute
+ * @param context - Optional context string for logging
+ * @returns A promise resolving to an {@link AsyncResult}
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await safeAsync(() => fetchUser(id), 'fetchUser');
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error?.message);
+ * }
+ * ```
  */
 declare const safeAsync: <T>(operation: () => Promise<T>, context?: string) => Promise<AsyncResult<T>>;
 /**
- * Execute async operation with loading state tracking
+ * Execute async operation with loading state tracking.
+ * Manages `setLoading` and `setError` callbacks automatically.
+ *
+ * @template T - The success data type
+ * @param operation - Async function to execute
+ * @param setLoading - Callback to update loading state
+ * @param setError - Callback to update error state
+ * @param context - Optional context string for logging
+ * @returns The operation result, or undefined on error
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const data = await withLoadingState(
+ *   () => api.getUsers(),
+ *   setIsLoading,
+ *   setErrorMsg,
+ *   'getUsers'
+ * );
+ * ```
  */
 declare const withLoadingState: <T>(operation: () => Promise<T>, setLoading: (loading: boolean) => void, setError: (error: Optional<string>) => void, context?: string) => Promise<Optional<T>>;
 /**
- * Execute multiple async operations in parallel with error handling
+ * Execute multiple async operations in parallel with error handling.
+ * All operations run concurrently via `Promise.all`.
+ *
+ * @template T - Tuple of result types
+ * @param operations - Array of async functions to execute in parallel
+ * @param context - Optional context string for logging
+ * @returns A promise resolving to an {@link AsyncResult} of the tuple
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await safeParallel(
+ *   [() => fetchUser(1), () => fetchPosts(1)] as const,
+ *   'loadProfile'
+ * );
+ * ```
  */
 declare const safeParallel: <T extends readonly unknown[]>(operations: readonly [...{ [K in keyof T]: () => Promise<T[K]>; }], context?: string) => Promise<AsyncResult<T>>;
 /**
- * Execute async operation with timeout
+ * Execute async operation with a timeout.
+ * Rejects if the operation does not complete within `timeoutMs`.
+ *
+ * @template T - The success data type
+ * @param operation - Async function to execute
+ * @param timeoutMs - Maximum time in milliseconds
+ * @param context - Optional context string for logging
+ * @returns The operation result
+ * @throws Error if the operation times out
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const data = await withTimeout(
+ *   () => fetch('/api/data').then((r) => r.json()),
+ *   5000,
+ *   'fetchData'
+ * );
+ * ```
  */
 declare const withTimeout: <T>(operation: () => Promise<T>, timeoutMs: number, context?: string) => Promise<T>;
+/**
+ * Cache async operation results with TTL (time-to-live).
+ * Returns cached data if still valid; otherwise executes the operation
+ * and stores the result.
+ *
+ * @template T - The cached data type
+ * @param key - Unique cache key
+ * @param operation - Async function whose result is cached
+ * @param ttlMs - Cache TTL in milliseconds (default: 5 minutes)
+ * @returns The cached or freshly fetched data
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const user = await withCache(
+ *   `user-${id}`,
+ *   () => api.getUser(id),
+ *   60_000 // 1 minute
+ * );
+ * ```
+ */
 declare const withCache: <T>(key: string, operation: () => Promise<T>, ttlMs?: number) => Promise<T>;
 /**
- * Clear expired cache entries
+ * Clear expired cache entries from the in-memory cache.
+ * @since 1.0.0
  */
 declare const clearExpiredCache: () => void;
+/**
+ * Debounce async function calls by key.
+ * Only the last call within the delay window will execute.
+ *
+ * @template T - Argument types
+ * @template R - Return type
+ * @param fn - The async function to debounce
+ * @param delay - Debounce delay in milliseconds
+ * @param key - Unique key identifying this debounced operation
+ * @returns A debounced version of `fn`
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = debounceAsync(
+ *   (query: string) => api.search(query),
+ *   300,
+ *   'search'
+ * );
+ * await debouncedSearch('hello');
+ * ```
+ */
 declare const debounceAsync: <T extends unknown[], R>(fn: (...args: T) => Promise<R>, delay: number, key: string) => ((...args: T) => Promise<Optional<R>>);
 export { safeAsync, withLoadingState, safeParallel, withTimeout, withCache, clearExpiredCache, debounceAsync, type AsyncResult, };
 //# sourceMappingURL=async-helpers.d.ts.map

package/dist/utils/async-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/async-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,KAAK,WAAW,CAAC,CAAC,IAAI;IACpB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,SAAS,GAAU,CAAC,EACxB,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CASxB,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,gBAAgB,GAAU,CAAC,EAC/B,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,YAAY,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,EACtC,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAC3C,UAAU,MAAM,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAerB,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,YAAY,GAAU,CAAC,SAAS,SAAS,OAAO,EAAE,EACtD,YAAY,SAAS,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,CAAC,EACjE,UAAU,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAaxB,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,WAAW,GAAU,CAAC,EAC1B,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,WAAW,MAAM,EACjB,UAAU,MAAM,KACf,OAAO,CAAC,CAAC,CAcX,CAAC;AAOF,QAAA,MAAM,SAAS,GAAU,CAAC,EACxB,KAAK,MAAM,EACX,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,QAAO,MAAsB,KAC5B,OAAO,CAAC,CAAC,CAWX,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,iBAAiB,QAAO,IAO7B,CAAC;AAOF,QAAA,MAAM,aAAa,GAAI,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC3C,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,MAAM,EACb,KAAK,MAAM,KACV,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAsBvC,CAAC;AAEF,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,KAAK,WAAW,GACjB,CAAC"}
+{"version":3,"file":"async-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/async-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;;;GAMG;AACH,KAAK,WAAW,CAAC,CAAC,IAAI;IACpB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAA,MAAM,SAAS,GAAU,CAAC,EACxB,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CASxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,QAAA,MAAM,gBAAgB,GAAU,CAAC,EAC/B,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,YAAY,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,EACtC,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAC3C,UAAU,MAAM,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAerB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,YAAY,GAAU,CAAC,SAAS,SAAS,OAAO,EAAE,EACtD,YAAY,SAAS,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,CAAC,EACjE,UAAU,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAaxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,QAAA,MAAM,WAAW,GAAU,CAAC,EAC1B,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,WAAW,MAAM,EACjB,UAAU,MAAM,KACf,OAAO,CAAC,CAAC,CAcX,CAAC;AAOF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,QAAA,MAAM,SAAS,GAAU,CAAC,EACxB,KAAK,MAAM,EACX,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,QAAO,MAAsB,KAC5B,OAAO,CAAC,CAAC,CAWX,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,iBAAiB,QAAO,IAO7B,CAAC;AAOF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,QAAA,MAAM,aAAa,GAAI,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC3C,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,MAAM,EACb,KAAK,MAAM,KACV,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAsBvC,CAAC;AAEF,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,KAAK,WAAW,GACjB,CAAC"}