@gala-chain/launchpad-sdk 5.0.4-beta.6 → 5.0.4-beta.60

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

@@ -0,0 +1,1074 @@
+/**
+ * Validation Helper Utilities
+ *
+ * Reusable validation functions for common patterns across services.
+ * Eliminates duplicate validation logic and provides consistent error messages.
+ *
+ * @category Utilities
+ * @since 3.6.2
+ */
+import { type TokenNameConstraint } from '../types/constraints';
+import { isEmptyValue as isEmptyValuePrimitive, isNonEmptyString as isNonEmptyStringPrimitive, isNullish as isNullishPrimitive } from './primitives';
+/**
+ * Pagination bounds structure (required fields)
+ *
+ * This interface defines the required pagination bounds.
+ */
+export interface PaginationBounds {
+    MIN_OFFSET: number;
+    MAX_OFFSET: number;
+    MIN_LIMIT: number;
+    MAX_LIMIT: number;
+}
+/**
+ * Pagination constraints structure
+ *
+ * This interface defines the expected structure for pagination constraint objects
+ * used across the SDK (e.g., USER_CONSTRAINTS, TRADE_CONSTRAINTS).
+ */
+export interface PaginationConstraints {
+    PAGINATION: PaginationBounds;
+}
+/**
+ * Validates pagination parameters against constraint bounds
+ *
+ * @param offset - Offset (0-based) to validate
+ * @param limit - Results per page limit to validate
+ * @param constraints - Constraint object with PAGINATION bounds
+ * @throws ValidationError if offset or limit is invalid
+ *
+ * @example Basic usage with USER_CONSTRAINTS
+ * ```typescript
+ * import { assertValidPagination } from '../utils/validation-helpers';
+ * import { USER_CONSTRAINTS } from '../types/user.dto';
+ *
+ * function fetchUsers(offset: number, limit: number) {
+ *   assertValidPagination(offset, limit, USER_CONSTRAINTS);
+ *   // Validation passed - proceed with fetch
+ * }
+ * ```
+ *
+ * @example With TRADE_CONSTRAINTS
+ * ```typescript
+ * import { assertValidPagination } from '../utils/validation-helpers';
+ * import { TRADE_CONSTRAINTS } from '../types/trade.dto';
+ *
+ * function fetchTrades(offset: number, limit: number) {
+ *   assertValidPagination(offset, limit, TRADE_CONSTRAINTS);
+ *   // Validation passed - proceed with fetch
+ * }
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * try {
+ *   assertValidPagination(-1, 100, USER_CONSTRAINTS);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.code); // 'INVALID_OFFSET'
+ *     console.log(error.message); // 'Offset must be a number between 0 and 1000000'
+ *   }
+ * }
+ * ```
+ */
+export declare function assertValidPagination(offset: number, limit: number, constraints: PaginationConstraints): void;
+export declare const ADDRESS_PATTERNS: {
+    readonly ETH_ADDRESS: RegExp;
+    readonly BACKEND_ADDRESS: RegExp;
+    readonly CLIENT_ADDRESS: RegExp;
+};
+export declare const isNonEmptyString: typeof isNonEmptyStringPrimitive;
+export declare const isEmptyValue: typeof isEmptyValuePrimitive;
+export declare const isNullish: typeof isNullishPrimitive;
+/**
+ * Validates optional pagination parameters (offset and limit)
+ *
+ * @param offset - Optional offset (0-based) to validate
+ * @param limit - Optional results per page to validate
+ * @param maxLimit - Maximum allowed limit (default: 100)
+ * @throws ValidationError if offset or limit is invalid
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { validatePaginationOptions } from '../utils/validation-helpers';
+ *
+ * function validateListOptions(options: ListOptions): void {
+ *   validatePaginationOptions(options.offset, options.limit);
+ *   // Validation passed - proceed with fetch
+ * }
+ * ```
+ *
+ * @example With custom max limit
+ * ```typescript
+ * // For endpoints with smaller page sizes
+ * validatePaginationOptions(options.offset, options.limit, 50);
+ * ```
+ *
+ * @since 6.4.0
+ */
+export declare function validatePaginationOptions(offset?: number, limit?: number, maxLimit?: number, pageSize?: number, cursor?: string): void;
+/**
+ * Type guard function signature
+ * A function that checks if a value matches a specific type and narrows the type accordingly
+ */
+export type TypeGuard<T> = (value: unknown) => value is T;
+/**
+ * Creates a validation function from a type guard
+ *
+ * @param typeGuard - Type guard function that validates the data type
+ * @param dataTypeName - Human-readable name for error messages (e.g., 'transfer data', 'pool details')
+ * @param fieldName - Optional field name for error context (defaults to 'data')
+ * @param errorCode - Optional error code (defaults to 'INVALID_DATA')
+ * @returns Validation function that throws ValidationError if type guard fails
+ *
+ * @example Basic usage with transfer data
+ * ```typescript
+ * import { createValidator } from '../utils/validation-helpers';
+ * import { isTransferGalaData, TransferGalaData } from '../types/transfer.dto';
+ *
+ * function transferGala(data: unknown) {
+ *   // Validates and narrows type in one call
+ *   createValidator(isTransferGalaData, 'transfer GALA data')(data);
+ *   // data is now typed as TransferGalaData
+ *
+ *   // Proceed with transfer logic
+ * }
+ * ```
+ *
+ * @example With custom field name and error code
+ * ```typescript
+ * createValidator(
+ *   isFetchPoolDetailsData,
+ *   'pool details',
+ *   'poolData',
+ *   'INVALID_POOL_DATA'
+ * )(data);
+ * ```
+ *
+ * @example Reusable validator
+ * ```typescript
+ * const validateTransferData = createValidator(
+ *   isTransferGalaData,
+ *   'transfer data'
+ * );
+ *
+ * // Use in multiple places
+ * validateTransferData(data1);
+ * validateTransferData(data2);
+ * ```
+ */
+export declare function createValidator<T>(typeGuard: TypeGuard<T>, dataTypeName: string, fieldName?: string, errorCode?: string): (value: unknown) => asserts value is T;
+/**
+ * Creates a type guard function for string enums
+ *
+ * This utility eliminates boilerplate for enum validation functions that follow the pattern:
+ * ```typescript
+ * function isEnumValue(value: unknown): value is MyEnum {
+ *   return typeof value === 'string' && Object.values(MyEnum).includes(value as MyEnum);
+ * }
+ * ```
+ *
+ * ## Replaces Patterns
+ *
+ * ### Before (Duplicate across DTOs):
+ * ```typescript
+ * // content-flag.dto.ts
+ * export function isContentType(value: unknown): value is ContentType {
+ *   return typeof value === 'string' && Object.values(ContentType).includes(value as ContentType);
+ * }
+ * export function isFlagReason(value: unknown): value is FlagReason {
+ *   return typeof value === 'string' && Object.values(FlagReason).includes(value as FlagReason);
+ * }
+ * // ... repeated for each enum
+ * ```
+ *
+ * ### After (Single Source of Truth):
+ * ```typescript
+ * import { createEnumTypeGuard } from '../utils/validation-helpers';
+ * export const isContentType = createEnumTypeGuard(ContentType);
+ * export const isFlagReason = createEnumTypeGuard(FlagReason);
+ * ```
+ *
+ * @param enumObj - The TypeScript enum object to create a type guard for
+ * @returns A type guard function that checks if a value is a member of the enum
+ *
+ * @example Basic usage with ContentType enum
+ * ```typescript
+ * import { createEnumTypeGuard } from '../utils/validation-helpers';
+ *
+ * enum ContentType {
+ *   CHAT_MESSAGE = 'CHAT_MESSAGE',
+ *   COMMENT = 'COMMENT',
+ *   STREAM = 'STREAM',
+ * }
+ *
+ * export const isContentType = createEnumTypeGuard(ContentType);
+ *
+ * // Usage
+ * if (isContentType(value)) {
+ *   // value is narrowed to ContentType
+ * }
+ * ```
+ *
+ * @since 6.0.0
+ */
+export declare function createEnumTypeGuard<T extends Record<string, string>>(enumObj: T): (value: unknown) => value is T[keyof T];
+/**
+ * Derives an array of values from a const object
+ *
+ * This utility eliminates the repetitive pattern of creating parallel arrays
+ * from const objects using `Object.values()`.
+ *
+ * ## Replaces Patterns
+ *
+ * ### Before (Duplicate across DTOs):
+ * ```typescript
+ * // api-key.dto.ts
+ * export const API_KEY_ROLE = { MODERATOR: 'MODERATOR', MANAGER: 'MANAGER' } as const;
+ * export type ApiKeyRole = (typeof API_KEY_ROLE)[keyof typeof API_KEY_ROLE];
+ * export const API_KEY_ROLES: ApiKeyRole[] = Object.values(API_KEY_ROLE);
+ *
+ * // moderator.dto.ts
+ * export const MODERATOR_ROLE = { ... } as const;
+ * export type ModeratorRole = (typeof MODERATOR_ROLE)[keyof typeof MODERATOR_ROLE];
+ * export const MODERATOR_ROLES: ModeratorRole[] = Object.values(MODERATOR_ROLE);
+ * ```
+ *
+ * ### After (Single Source of Truth):
+ * ```typescript
+ * import { enumValues } from '../utils/validation-helpers';
+ * export const API_KEY_ROLES = enumValues(API_KEY_ROLE);
+ * export const MODERATOR_ROLES = enumValues(MODERATOR_ROLE);
+ * ```
+ *
+ * @param enumObj - The const object to extract values from
+ * @returns A typed array of all values in the const object
+ *
+ * @example Basic usage with role const
+ * ```typescript
+ * import { enumValues } from '../utils/validation-helpers';
+ *
+ * const API_KEY_ROLE = {
+ *   MODERATOR: 'MODERATOR',
+ *   MANAGER: 'MANAGER',
+ * } as const;
+ *
+ * type ApiKeyRole = (typeof API_KEY_ROLE)[keyof typeof API_KEY_ROLE];
+ * const API_KEY_ROLES = enumValues(API_KEY_ROLE); // ['MODERATOR', 'MANAGER']
+ * // Type: ApiKeyRole[]
+ * ```
+ *
+ * @since 6.11.0
+ */
+export declare function enumValues<T extends Record<string, string>>(enumObj: T): T[keyof T][];
+/**
+ * Result of mutual exclusivity validation
+ */
+export interface MutualExclusivityResult {
+    /** Which field was provided (if valid) */
+    chosen: string;
+    /** Whether fieldA was provided */
+    hasA: boolean;
+    /** Whether fieldB was provided */
+    hasB: boolean;
+}
+/**
+ * Validates that exactly one of two parameters is provided (mutual exclusivity)
+ *
+ * Consolidates 12+ instances of identical validation logic found across services:
+ * - PriceHistoryService: tokenName XOR tokenId (lines 451-470)
+ * - DexService: Similar patterns with token identification
+ * - Other services: Scattered mutual exclusivity validation
+ *
+ * ## Use Cases
+ *
+ * ### Validate Token Identification (Highest Priority)
+ * ```typescript
+ * // In service methods receiving either tokenName or tokenId (but not both)
+ * const { chosen, hasA } = validateMutualExclusive(
+ *   options,
+ *   'tokenName',
+ *   'tokenId',
+ *   { description: 'token identifier' }
+ * );
+ *
+ * if (hasA) {
+ *   // Use tokenName
+ *   const resolved = await this.tokenResolver.resolve(options.tokenName!);
+ * } else {
+ *   // Use tokenId
+ *   const formatted = this.converter.toTokenClassKey(options.tokenId!);
+ * }
+ * ```
+ *
+ * ### Generic Parameter Validation
+ * ```typescript
+ * // Validate address or transaction ID (mutually exclusive)
+ * const { chosen } = validateMutualExclusive(
+ *   params,
+ *   'walletAddress',
+ *   'transactionId',
+ *   { description: 'transaction reference' }
+ * );
+ * ```
+ *
+ * @param obj The object containing the fields to validate
+ * @param fieldA First field name (mutual exclusive with fieldB)
+ * @param fieldB Second field name (mutual exclusive with fieldA)
+ * @param options Validation options
+ * @returns Result object with chosen field and validation flags
+ *
+ * @throws {ConfigurationError} If neither field is provided or both are provided
+ *
+ * @example Token identifier validation
+ * ```typescript
+ * // PriceHistoryService.fetchAllPriceHistory() - replaces 20-line validation method
+ * const { hasA } = validateMutualExclusive(options, 'tokenName', 'tokenId', {
+ *   description: 'token identifier'
+ * });
+ * ```
+ *
+ * @since 3.32.0
+ */
+export declare function validateMutualExclusive(obj: Record<string, unknown>, fieldA: string, fieldB: string, options?: {
+    /** Human-readable description for error messages (e.g., "token identifier") */
+    description?: string;
+    /** Whether empty strings should count as "not provided" (default: true) */
+    treatEmptyAsNull?: boolean;
+}): MutualExclusivityResult;
+export type { TokenNameConstraint };
+/**
+ * Validates a launchpad token name using configurable constraints
+ *
+ * Consolidates duplicate token name validation logic found across multiple DTO files:
+ * - streaming.dto.ts (validateStreamingTokenName)
+ * - content-flag.dto.ts (validateFlagTokenName)
+ * - comment.dto.ts (inline validation)
+ * - ban.dto.ts (inline validation)
+ * - moderator.dto.ts (inline validation)
+ *
+ * ## Usage
+ *
+ * ### With default constraints (3-20 alphanumeric)
+ * ```typescript
+ * validateLaunchpadTokenName(tokenName); // Uses LAUNCHPAD_TOKEN_NAME_CONSTRAINT
+ * ```
+ *
+ * ### With custom constraints from DTO
+ * ```typescript
+ * import { STREAMING_CONSTRAINTS } from '../types/streaming.dto';
+ * validateLaunchpadTokenName(tokenName, 'tokenName', STREAMING_CONSTRAINTS.TOKEN_NAME);
+ * ```
+ *
+ * ### With custom field name for error messages
+ * ```typescript
+ * validateLaunchpadTokenName(options.tokenName, 'tokenName', BAN_CONSTRAINTS.TOKEN_NAME);
+ * ```
+ *
+ * @param tokenName - Token name to validate
+ * @param field - Field name for error messages (defaults to 'tokenName')
+ * @param constraint - Token name constraint configuration (defaults to LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @throws {ValidationError} If token name is invalid (empty, too short, too long, or invalid format)
+ *
+ * @since 6.4.0
+ */
+export declare function validateLaunchpadTokenName(tokenName: string, field?: string, constraint?: TokenNameConstraint): void;
+/**
+ * Validates an optional token name (allows undefined/null, but validates if present)
+ *
+ * Use this for optional token name fields that should be validated when provided.
+ * Consolidates duplicate logic from tokenNameValidator.ts.
+ *
+ * @param tokenName - The token name to validate (may be undefined/null)
+ * @param field - The field name for error messages (default: 'tokenName')
+ * @param constraint - Token name constraint (default: LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @throws {ValidationError} If token name is provided but invalid
+ *
+ * @example
+ * ```typescript
+ * // No error - undefined is allowed
+ * validateOptionalTokenName(undefined);
+ *
+ * // Throws ValidationError - provided but invalid
+ * validateOptionalTokenName('ab');
+ *
+ * // Success - valid token name
+ * validateOptionalTokenName('myToken123');
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function validateOptionalTokenName(tokenName: unknown, field?: string, constraint?: TokenNameConstraint): void;
+/**
+ * Checks if a token name is valid without throwing
+ *
+ * Use this for conditional checks where you don't want exceptions.
+ * Consolidates duplicate logic from tokenNameValidator.ts.
+ *
+ * @param tokenName - The token name to check
+ * @param constraint - Token name constraint (default: LAUNCHPAD_TOKEN_NAME_CONSTRAINT)
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isValidTokenName(userInput)) {
+ *   // Proceed with token lookup
+ * } else {
+ *   // Show validation error to user
+ * }
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function isValidTokenName(tokenName: unknown, constraint?: TokenNameConstraint): tokenName is string;
+/**
+ * Validates a token name with constraint-specific error messages
+ *
+ * Enhanced version that provides the exact length constraint in error messages.
+ * This is the recommended function for service methods.
+ *
+ * @param tokenName - Token name to validate
+ * @param field - Field name for error messages (default: 'tokenName')
+ * @param constraint - Token name constraint with MIN_LENGTH, MAX_LENGTH, PATTERN
+ * @throws {ValidationError} If token name is invalid
+ *
+ * @example
+ * ```typescript
+ * // Throws: "tokenName must be 3-20 alphanumeric characters"
+ * validateTokenName('ab', 'tokenName', LAUNCHPAD_TOKEN_NAME_CONSTRAINT);
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function validateTokenName(tokenName: unknown, field?: string, constraint?: TokenNameConstraint): void;
+/**
+ * Field validator configuration for structural type guards
+ *
+ * Specifies how to validate a single field in a type guard.
+ *
+ * @since 6.12.0
+ */
+export interface FieldTypeValidator {
+    /** Field name to validate */
+    field: string;
+    /** Expected type: 'string', 'number', 'boolean', 'object' */
+    type: 'string' | 'number' | 'boolean' | 'object';
+    /** Whether null is an acceptable value (default: false) */
+    nullable?: boolean;
+    /** Whether undefined is acceptable (field may be missing) (default: false) */
+    optional?: boolean;
+    /** Custom validator for complex checks (return true if valid) */
+    validator?: (value: unknown) => boolean;
+}
+/**
+ * Creates a structural type guard function from field specifications
+ *
+ * This factory eliminates repetitive type guard boilerplate found across DTO files.
+ * Each type guard follows the same pattern: check object exists, cast to Record,
+ * then validate each field's type.
+ *
+ * ## Before (Duplicate across DTOs):
+ * ```typescript
+ * export function isBanData(obj: unknown): obj is BanData {
+ *   if (!obj || typeof obj !== 'object') return false;
+ *   const o = obj as Record<string, unknown>;
+ *   return (
+ *     typeof o.id === 'number' &&
+ *     typeof o.userAddress === 'string' &&
+ *     typeof o.bannedBy === 'string' &&
+ *     typeof o.createdAt === 'string' &&
+ *     typeof o.isPermanent === 'boolean' &&
+ *     (o.tokenName === null || typeof o.tokenName === 'string') &&
+ *     (o.reason === null || typeof o.reason === 'string') &&
+ *     (o.expiresAt === null || typeof o.expiresAt === 'string')
+ *   );
+ * }
+ * ```
+ *
+ * ## After (Single declaration):
+ * ```typescript
+ * export const isBanData = createStructuralTypeGuard<BanData>([
+ *   { field: 'id', type: 'number' },
+ *   { field: 'userAddress', type: 'string' },
+ *   { field: 'bannedBy', type: 'string' },
+ *   { field: 'createdAt', type: 'string' },
+ *   { field: 'isPermanent', type: 'boolean' },
+ *   { field: 'tokenName', type: 'string', nullable: true },
+ *   { field: 'reason', type: 'string', nullable: true },
+ *   { field: 'expiresAt', type: 'string', nullable: true },
+ * ]);
+ * ```
+ *
+ * @param fields - Array of field validators specifying required fields and their types
+ * @returns A type guard function that checks if an object matches the specified structure
+ *
+ * @example Basic usage with required fields
+ * ```typescript
+ * const isUser = createStructuralTypeGuard<User>([
+ *   { field: 'id', type: 'number' },
+ *   { field: 'name', type: 'string' },
+ *   { field: 'isActive', type: 'boolean' },
+ * ]);
+ *
+ * if (isUser(data)) {
+ *   console.log(data.name); // data is typed as User
+ * }
+ * ```
+ *
+ * @example With nullable and optional fields
+ * ```typescript
+ * const isComment = createStructuralTypeGuard<Comment>([
+ *   { field: 'id', type: 'number' },
+ *   { field: 'content', type: 'string' },
+ *   { field: 'parentId', type: 'number', nullable: true },
+ *   { field: 'metadata', type: 'object', optional: true },
+ * ]);
+ * ```
+ *
+ * @since 6.12.0
+ */
+export declare function createStructuralTypeGuard<T>(fields: FieldTypeValidator[]): (obj: unknown) => obj is T;
+import type { FieldValidatorConfig, OptionsValidatorWithErrors } from '../types/common';
+/**
+ * Common field validators for reuse across validation functions
+ *
+ * These validators can be used with `createOptionsValidator` or directly.
+ *
+ * @since 6.12.0
+ */
+export declare const commonValidators: {
+    /**
+     * Creates a validator for required non-empty string fields
+     */
+    requiredString: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for max length string fields
+     */
+    maxLength: (field: string, max: number) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for positive integer fields
+     */
+    positiveInteger: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for required positive integer fields
+     */
+    requiredPositiveInteger: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for enum values
+     */
+    enumValue: <T extends string>(field: string, validValues: readonly T[]) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for required enum values
+     */
+    requiredEnumValue: <T extends string>(field: string, validValues: readonly T[]) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for ISO date strings
+     */
+    isoDate: (field: string) => (value: unknown) => string | undefined;
+    /**
+     * Creates a validator for wallet addresses
+     */
+    walletAddress: (field: string, required?: boolean) => (value: unknown) => string | undefined;
+};
+/**
+ * Creates an options validator from field configurations
+ *
+ * This factory eliminates duplicate validation boilerplate across DTO files.
+ * Returns an array of error messages (empty if valid), which aligns with
+ * moderator.dto.ts and api-key.dto.ts validation patterns.
+ *
+ * ## Usage
+ *
+ * ### Basic field validation
+ * ```typescript
+ * import { createOptionsValidator, commonValidators } from '../utils/validation-helpers';
+ *
+ * const validateCreateOptions = createOptionsValidator<CreateOptions>([
+ *   { field: 'name', required: true, type: 'string' },
+ *   { field: 'description', validator: commonValidators.maxLength('description', 255) },
+ *   { field: 'status', validator: commonValidators.enumValue('status', ['active', 'inactive']) },
+ * ]);
+ *
+ * // Usage
+ * const errors = validateCreateOptions(options);
+ * if (errors.length > 0) {
+ *   throw new ValidationError(errors[0], 'options', 'VALIDATION_FAILED');
+ * }
+ * ```
+ *
+ * ### With custom validators
+ * ```typescript
+ * const validateOptions = createOptionsValidator<MyOptions>([
+ *   { field: 'tokenName', validator: (value) => {
+ *     try {
+ *       validateLaunchpadTokenName(value as string, 'tokenName');
+ *       return undefined;
+ *     } catch (e) {
+ *       return (e as Error).message;
+ *     }
+ *   }},
+ * ]);
+ * ```
+ *
+ * @param configs - Array of field validator configurations
+ * @returns Validation function that returns an array of error messages
+ *
+ * @since 6.12.0
+ */
+export declare function createOptionsValidator<T extends Record<string, unknown>>(configs: FieldValidatorConfig[]): OptionsValidatorWithErrors<T>;
+/**
+ * Regular expression pattern for validating decimal amount strings
+ *
+ * Matches positive decimal numbers like "123", "45.67", "0.001"
+ * Does NOT match negative numbers, leading/trailing dots, or scientific notation.
+ *
+ * @since 6.18.0
+ */
+export declare const DECIMAL_AMOUNT_PATTERN: RegExp;
+/**
+ * Validates a decimal amount string
+ *
+ * Used for validating token amounts in transfer, lock, unlock, burn operations.
+ * Consolidates duplicate validation logic from transfer.dto.ts, lock.dto.ts, burn.dto.ts.
+ *
+ * @param amount - Amount string to validate
+ * @param fieldPath - Field path for error messages (e.g., 'amount', 'tokens[0].amount')
+ * @param options - Validation options
+ * @throws {ValidationError} If amount is invalid
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * validateDecimalAmount(data.amount, 'amount');
+ *
+ * // In batch validation
+ * validateDecimalAmount(entry.amount, `tokens[${index}].amount`);
+ *
+ * // Allow zero
+ * validateDecimalAmount(data.amount, 'amount', { allowZero: true });
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateDecimalAmount(amount: unknown, fieldPath: string, options?: {
+    allowZero?: boolean;
+}): void;
+/**
+ * Validates a token name against a regex pattern
+ *
+ * Used for validating token names in batch operations where full launchpad validation
+ * is not appropriate. Consolidates duplicate validation from lock.dto.ts, burn.dto.ts.
+ *
+ * @param tokenName - Token name to validate
+ * @param fieldPath - Field path for error messages (e.g., 'tokenName', 'tokens[0].tokenName')
+ * @param pattern - Regex pattern for validation
+ * @throws {ValidationError} If token name is invalid
+ *
+ * @example
+ * ```typescript
+ * import { TOKEN_NAME_PATTERN } from './constraints';
+ *
+ * // In batch validation
+ * if (entry.tokenName !== undefined) {
+ *   validateTokenNamePattern(entry.tokenName, `tokens[${index}].tokenName`, TOKEN_NAME_PATTERN);
+ * }
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateTokenNamePattern(tokenName: unknown, fieldPath: string, pattern: RegExp): void;
+/**
+ * Validates that a batch array meets size constraints
+ *
+ * Consolidates duplicate validation from lock.dto.ts, burn.dto.ts for batch operations.
+ *
+ * @param array - Array to validate
+ * @param fieldName - Field name for error messages (e.g., 'tokens')
+ * @param maxSize - Maximum allowed array size
+ * @throws {ValidationError} If array is invalid or exceeds max size
+ *
+ * @example
+ * ```typescript
+ * validateBatchArray(data.tokens, 'tokens', MAX_LOCK_BATCH_SIZE);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateBatchArray(array: unknown, fieldName: string, maxSize: number): void;
+/**
+ * Validates an optional unique key string
+ *
+ * Consolidates duplicate validation from transfer.dto.ts, lock.dto.ts, burn.dto.ts.
+ *
+ * @param uniqueKey - Unique key to validate (may be undefined)
+ * @param maxLength - Maximum allowed length
+ * @throws {ValidationError} If unique key is invalid
+ *
+ * @example
+ * ```typescript
+ * import { UNIQUE_KEY_CONSTRAINT } from './constraints';
+ *
+ * validateUniqueKey(data.uniqueKey, UNIQUE_KEY_CONSTRAINT.MAX_LENGTH);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateUniqueKey(uniqueKey: unknown, maxLength: number): void;
+/**
+ * Validates an optional private key string
+ *
+ * Simple type check for optional private key override.
+ * Consolidates duplicate validation from transfer.dto.ts, lock.dto.ts, burn.dto.ts.
+ *
+ * @param privateKey - Private key to validate (may be undefined)
+ * @throws {ValidationError} If private key is not a string
+ *
+ * @since 6.18.0
+ */
+export declare function validateOptionalPrivateKey(privateKey: unknown): void;
+/**
+ * Validates that at least one of two token identifier fields is provided
+ *
+ * Common pattern in batch operations where either tokenId or tokenName is required.
+ * Consolidates duplicate validation from lock.dto.ts, burn.dto.ts.
+ *
+ * @param entry - Object containing tokenId and/or tokenName
+ * @param fieldPath - Base field path for error messages (e.g., 'tokens[0]')
+ * @throws {ValidationError} If neither tokenId nor tokenName is provided
+ *
+ * @example
+ * ```typescript
+ * validateTokenIdentifier(entry, `tokens[${index}]`);
+ * ```
+ *
+ * @since 6.18.0
+ */
+export declare function validateTokenIdentifier(entry: {
+    tokenId?: unknown;
+    tokenName?: unknown;
+}, fieldPath: string): void;
+/**
+ * NOTE: The primary `isValidAddress()` function is in address-formatter.ts
+ *
+ * Import it from there:
+ * ```typescript
+ * import { isValidAddress } from './address-formatter';
+ * ```
+ *
+ * This consolidation ensures all address validation uses a single,
+ * well-tested implementation with ADDRESS_PATTERNS for consistency.
+ */
+/**
+ * Throws ValidationError if required field is null/undefined with customizable messages
+ *
+ * Use this to validate that required fields are present. Supports generic type
+ * narrowing so TypeScript knows the value is not null/undefined after this check.
+ *
+ * @template T The type of the value being validated
+ * @param value The value to check (can be T, null, or undefined)
+ * @param fieldName Internal field name for error codes (e.g., 'wallet', 'signatureHelper')
+ * @param displayName Optional user-friendly display name for error messages (e.g., 'Wallet instance')
+ * @returns The value if it's not null/undefined (strongly typed as T)
+ * @throws {ValidationError} If value is null or undefined with fieldName and error code REQUIRED
+ *
+ * @example
+ * ```typescript
+ * // Simple validation
+ * const wallet = throwIfMissing(this.wallet, 'wallet', 'Wallet instance');
+ * // wallet is now guaranteed to be non-null by TypeScript
+ *
+ * // Multi-field validation
+ * throwIfMissing(this.wallet, 'wallet', 'Wallet instance');
+ * throwIfMissing(this.signatureHelper, 'signatureHelper', 'Signature helper');
+ * // Both are now guaranteed non-null
+ *
+ * // Generic type preservation
+ * interface Config { apiKey: string }
+ * const config = throwIfMissing<Config>(userConfig, 'config', 'Configuration object');
+ * // config is now Config (not Config | null | undefined)
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function throwIfMissing<T>(value: T | null | undefined, fieldName: string, displayName?: string): T;
+/**
+ * Check if array has no elements (length === 0)
+ *
+ * Provides a readable way to check for empty arrays. Handles null/undefined
+ * gracefully by returning true (treating them as "empty").
+ *
+ * @template T The type of array elements
+ * @param arr The array to check (can be T[], null, or undefined)
+ * @returns True if array is null, undefined, or has length === 0; false otherwise
+ *
+ * @example Basic empty check
+ * ```typescript
+ * import { isEmptyArray } from '@gala-chain/launchpad-sdk';
+ *
+ * const tokens = []; // or null, or undefined
+ *
+ * if (isEmptyArray(tokens)) {
+ *   console.log('No tokens to process');
+ *   return;
+ * }
+ * ```
+ *
+ * @example In conditional logic
+ * ```typescript
+ * import { isEmptyArray } from '@gala-chain/launchpad-sdk';
+ *
+ * if (!symbols || isEmptyArray(symbols)) {
+ *   throw new ValidationError('At least one symbol is required');
+ * }
+ * ```
+ *
+ * @example With different array types
+ * ```typescript
+ * import { isEmptyArray } from '@gala-chain/launchpad-sdk';
+ *
+ * // Works with objects
+ * if (isEmptyArray(this.tokenInstances)) return undefined;
+ *
+ * // Works with strings
+ * if (isEmptyArray(errors)) {
+ *   console.log('Validation passed');
+ * }
+ *
+ * // Works with numbers
+ * const amounts: number[] = [];
+ * if (isEmptyArray(amounts)) {
+ *   console.log('No amounts provided');
+ * }
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function isEmptyArray<T>(arr: T[] | null | undefined): boolean;
+/**
+ * Check if string is empty or contains only whitespace
+ *
+ * A concise alternative to `str.trim().length === 0` or `!str || !str.trim()`.
+ * Returns true if the string is null, undefined, empty, or contains only whitespace characters.
+ * Whitespace includes spaces, tabs, line breaks, carriage returns, form feeds, and non-breaking spaces.
+ *
+ * @param value String to check
+ * @returns true if string is empty or only contains whitespace
+ *
+ * @example Basic check
+ * ```typescript
+ * import { isEmptyOrWhitespace } from '@gala-chain/launchpad-sdk';
+ *
+ * if (isEmptyOrWhitespace(userInput)) {
+ *   console.log('Please provide valid input');
+ * }
+ * ```
+ *
+ * @example Validation in form handlers
+ * ```typescript
+ * const validateReason = (reason: string) => {
+ *   if (isEmptyOrWhitespace(reason)) {
+ *     throw new Error('Reason is required');
+ *   }
+ *   return reason.trim();
+ * };
+ * ```
+ *
+ * @example Filtering whitespace-only values
+ * ```typescript
+ * const values = ['hello', '  ', '', 'world', '\t\n'];
+ * const filtered = values.filter(v => !isEmptyOrWhitespace(v));
+ * // Result: ['hello', 'world']
+ * ```
+ *
+ * @example Conditional logic
+ * ```typescript
+ * const displayName = !isEmptyOrWhitespace(nickname) ? nickname : fullName;
+ * ```
+ *
+ * @since 3.50.0
+ */
+export declare function isEmptyOrWhitespace(value: string): boolean;
+/**
+ * Supported DEX fee tiers in basis points
+ *
+ * Basis points (bps) are used for precise fee tier representation.
+ * 1 basis point = 0.01% = 1/100th of a percent.
+ *
+ * @constant
+ * @example
+ * ```typescript
+ * import { FEE_TIERS } from '@gala-chain/launchpad-sdk';
+ *
+ * const fees = [FEE_TIERS.LOW, FEE_TIERS.MEDIUM, FEE_TIERS.HIGH];
+ * // [500, 3000, 10000]
+ *
+ * const feeName = {
+ *   [FEE_TIERS.LOW]: '0.05%',
+ *   [FEE_TIERS.MEDIUM]: '0.30%',
+ *   [FEE_TIERS.HIGH]: '1.00%'
+ * };
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare const FEE_TIERS: {
+    readonly LOW: 500;
+    readonly MEDIUM: 3000;
+    readonly HIGH: 10000;
+};
+/**
+ * Type-safe fee tier validation assertion
+ *
+ * Validates that a value is one of the recognized fee tiers (500, 3000, 10000).
+ * Throws ValidationError if the value is not a valid fee tier.
+ *
+ * Uses enumValidationWithObjectValues for consistent enum validation.
+ *
+ * @param value - Value to validate as a fee tier
+ * @param field - Optional field name for error messages (default: 'feeTier')
+ * @throws ValidationError if value is not a recognized fee tier
+ *
+ * @example Basic validation
+ * ```typescript
+ * import { validateFeeTier } from '@gala-chain/launchpad-sdk';
+ *
+ * function createPool(fee: number) {
+ *   validateFeeTier(fee);
+ *   // Safe to use fee
+ * }
+ * ```
+ *
+ * @example With custom field name
+ * ```typescript
+ * try {
+ *   validateFeeTier(5000, 'poolFee');
+ * } catch (error) {
+ *   console.log(error.message); // 'Invalid poolFee: 5000'
+ * }
+ * ```
+ *
+ * @example In form validation
+ * ```typescript
+ * const validatePoolForm = (data: PoolFormData) => {
+ *   try {
+ *     validateFeeTier(data.fee, 'fee');
+ *   } catch (error) {
+ *     return { field: 'fee', error: 'Invalid fee tier' };
+ *   }
+ * };
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare function validateFeeTier(value: unknown, field?: string): void;
+/**
+ * Type guard to check if value is a valid fee tier
+ *
+ * Returns true if value is one of the recognized fee tiers (500, 3000, 10000).
+ * Returns false for any other value including null, undefined, and invalid numbers.
+ *
+ * Use this for conditional logic and filtering without throwing errors.
+ *
+ * @param value - Value to check
+ * @returns true if value is a recognized fee tier
+ *
+ * @example Conditional logic
+ * ```typescript
+ * import { isValidFeeTier } from '@gala-chain/launchpad-sdk';
+ *
+ * const userFee = getUserInput();
+ * if (isValidFeeTier(userFee)) {
+ *   createPool({ fee: userFee });
+ * } else {
+ *   showError('Please select a valid fee tier');
+ * }
+ * ```
+ *
+ * @example Filtering
+ * ```typescript
+ * const fees = [500, 1000, 3000, 5000, 10000];
+ * const validFees = fees.filter(fee => isValidFeeTier(fee));
+ * // Result: [500, 3000, 10000]
+ * ```
+ *
+ * @example Type narrowing
+ * ```typescript
+ * const processFee = (value: unknown) => {
+ *   if (isValidFeeTier(value)) {
+ *     // TypeScript knows value is number here
+ *     const tier = value * 0.0001; // Convert to percentage
+ *     return tier;
+ *   }
+ *   return null;
+ * };
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare function isValidFeeTier(value: unknown): value is number;
+/**
+ * Normalize fee percentage to basis points
+ *
+ * Converts decimal percentage values (0.05, 0.30, 1.0) to basis points (500, 3000, 10000).
+ * Useful for converting user-friendly percentage input to internal fee tier representation.
+ *
+ * Returns null if the percentage doesn't correspond to a standard fee tier.
+ *
+ * @param percentage - Fee percentage in decimal format (0.05 = 0.05%, 0.30 = 0.30%, etc.)
+ * @returns Basis points equivalent (500, 3000, 10000) or null if not a standard tier
+ *
+ * @example Converting percentages
+ * ```typescript
+ * import { normalizeFeeTier } from '@gala-chain/launchpad-sdk';
+ *
+ * normalizeFeeTier(0.05)  // Returns: 500
+ * normalizeFeeTier(0.30)  // Returns: 3000
+ * normalizeFeeTier(1.00)  // Returns: 10000
+ * normalizeFeeTier(0.50)  // Returns: null (not a standard tier)
+ * ```
+ *
+ * @example Form input conversion
+ * ```typescript
+ * const handleFeeInput = (percentageInput: string) => {
+ *   const percentage = parseFloat(percentageInput) / 100;
+ *   const basisPoints = normalizeFeeTier(percentage);
+ *
+ *   if (basisPoints === null) {
+ *     showError('Please select a standard fee tier');
+ *     return;
+ *   }
+ *
+ *   createPool({ fee: basisPoints });
+ * };
+ * ```
+ *
+ * @example With fallback
+ * ```typescript
+ * const feeBasisPoints = normalizeFeeTier(userInput) ?? FEE_TIERS.MEDIUM;
+ * ```
+ *
+ * @since 5.20.0
+ */
+export declare function normalizeFeeTier(percentage: number): number | null;
+/**
+ * Extracts and concatenates error messages from Zod validation errors
+ *
+ * Consolidates the pattern of extracting error messages from Zod validation results:
+ * `result.error.errors.map(e => e.message).join('; ')`
+ *
+ * @param errors - Array of Zod validation errors
+ * @returns Array of error message strings
+ *
+ * @example
+ * ```typescript
+ * const result = schema.safeParse(data);
+ * if (!result.success) {
+ *   const messages = collectValidationErrors(result.error.errors);
+ *   // Returns: ['Field is required', 'Must be at least 3 characters']
+ * }
+ * ```
+ *
+ * @since 6.30.0
+ */
+export declare function collectValidationErrors(errors: unknown[]): string[];
+//# sourceMappingURL=validation-helpers.d.ts.map