/**
 * Helper Utilities for BaoLife
 * Ported from Python utils/helpers.py
 */
import type { Player, GameLocation } from '../models/Player.js';
/**
 * Remove text before the first colon in a string
 * Used to clean up AI responses that start with "Character: message"
 */
export declare function removeTextBeforeFirstColon(text: string): string;
/**
 * Get upcoming Saturday from a date string
 */
export declare function upcomingSaturday(dateStr: string): string;
/**
 * Random integer between min and max (inclusive)
 */
export declare function randomInt(min: number, max: number): number;
/**
 * Pick a random item from an array
 */
export declare function randomChoice<T>(arr: T[]): T;
/**
 * Format money amount
 */
export declare function formatMoney(amount: number): string;
/**
 * Capitalize first letter
 */
export declare function capitalize(str: string): string;
/** Default speed values */
export declare const SPEED_MIN = 1;
export declare const SPEED_MAX = 10000;
/**
 * Validate and clamp game speed to acceptable range.
 * Ported from Python validate_game_speed().
 *
 * @param speed - The speed value to validate (can be number or string)
 * @param allowQuestionPause - If true, allows SPEED_QUESTION_PAUSE value
 * @returns A valid game speed within acceptable bounds
 *
 * Note: Higher speed values = slower gameplay (more ticks between updates)
 */
export declare function validateGameSpeed(speed: unknown, allowQuestionPause?: boolean): number;
/**
 * Get the appropriate speed button values based on config.
 * Ported from Python get_speed_button_values().
 */
export declare function getSpeedButtonValues(): readonly number[];
/**
 * Log speed changes for debugging and monitoring.
 * Ported from Python log_speed_change().
 *
 * @param userId - User/player identifier
 * @param oldSpeed - Previous speed value
 * @param newSpeed - New speed value
 * @param source - Source of the change (manual, button, reset, question, etc.)
 */
export declare function logSpeedChange(userId: string, oldSpeed: number, newSpeed: number, source?: string): void;
/**
 * Object with a type property
 */
export interface TypedObject {
    type: string;
    [key: string]: unknown;
}
/**
 * Object with an id property
 */
export interface Identifiable {
    id: string | number;
    [key: string]: unknown;
}
/**
 * Filter array by object type attribute.
 * Ported from Python getFromArray().
 *
 * @param array - List of objects with 'type' attribute
 * @param type - Value to match against object.type
 * @param returnFirst - If true, return first match only; otherwise return all matches
 * @returns Array of matching objects, or single object if returnFirst is true, or undefined if none found
 */
export declare function getByType<T extends TypedObject>(array: T[], type: string, returnFirst?: false): T[];
export declare function getByType<T extends TypedObject>(array: T[], type: string, returnFirst: true): T | undefined;
/**
 * Find an object in array by its id attribute.
 * Ported from Python find_by_id().
 *
 * @param array - Collection of objects with 'id' attribute
 * @param id - ID value to search for
 * @returns First matching object or undefined if not found
 */
export declare function findById<T extends Identifiable>(array: T[], id: string | number): T | undefined;
/**
 * Find first object where all key-value pairs match.
 * Ported from Python find_where().
 *
 * @param array - Collection of objects to search
 * @param criteria - Object with attribute names and values to match
 * @returns First matching object or undefined if not found
 */
export declare function findWhere<T extends Record<string, unknown>>(array: T[], criteria: Partial<T>): T | undefined;
/**
 * Filter objects where all key-value pairs match.
 *
 * @param array - Collection of objects to search
 * @param criteria - Object with attribute names and values to match
 * @returns Array of matching objects
 */
export declare function filterWhere<T extends Record<string, unknown>>(array: T[], criteria: Partial<T>): T[];
/**
 * Find objects with advanced comparison operators.
 * Supports __gt (greater than), __lt (less than), __gte (>=), __lte (<=) suffixes in keys.
 * Ported from Python find_where_test().
 *
 * @param array - Collection of objects to search
 * @param criteria - Object with keys like 'age__gt': 23 or 'score__lt': 100
 * @returns Generator yielding matching objects
 *
 * @example
 * // Find all people over 23 named John
 * const results = [...findWhereAdvanced(people, { age__gt: 23, name: 'John' })];
 */
export declare function findWhereAdvanced<T extends Record<string, unknown>>(array: T[], criteria: Record<string, unknown>): Generator<T, void, undefined>;
/**
 * Find first object with advanced comparison operators.
 * Convenience wrapper around findWhereAdvanced().
 *
 * @param array - Collection of objects to search
 * @param criteria - Object with keys like 'age__gt': 23 or 'score__lt': 100
 * @returns First matching object or undefined
 */
export declare function findFirstWhereAdvanced<T extends Record<string, unknown>>(array: T[], criteria: Record<string, unknown>): T | undefined;
/**
 * Get all objects matching advanced criteria.
 * Convenience wrapper around findWhereAdvanced().
 *
 * @param array - Collection of objects to search
 * @param criteria - Object with keys like 'age__gt': 23 or 'score__lt': 100
 * @returns Array of matching objects
 */
export declare function filterWhereAdvanced<T extends Record<string, unknown>>(array: T[], criteria: Record<string, unknown>): T[];
/**
 * Update location objects with current people present.
 * Increases familiarity between characters at same location.
 * Ported from Python parseLocations().
 *
 * @param player - Player object with c (character), r (relationships), l (locations)
 * @returns Updated player object
 */
export declare function parseLocations(player: Player): Player;
/**
 * Find a location by ID.
 *
 * @param player - Player object with locations
 * @param locationId - Location ID to find
 * @returns Location object or undefined
 */
export declare function findLocation(player: Player, locationId: string): GameLocation | undefined;
/**
 * Get all people at a specific location.
 *
 * @param player - Player object
 * @param locationId - Location ID
 * @returns Array of person IDs at the location
 */
export declare function getPeopleAtLocation(player: Player, locationId: string): string[];
//# sourceMappingURL=helpers.d.ts.map