@balancy/utils 1.0.34 → 1.0.36

package/README.md

@@ -1,156 +1,148 @@
 # @balancy/utils
 
-Набор утилитарных функций и хелперов для экосистемы Balancy.
+Utility functions and helpers for the Balancy ecosystem.
 
-## ⭐ Основные возможности
+## ⭐ Main Features
 
-- **IndexedDB FileHelper** - Полнофункциональная система работы с файлами через IndexedDB
-- **Утилитарные функции** - Набор полезных хелперов для разработки
+- **IndexedDB FileHelper** - Complete file system integration with IndexedDB for browser environments
+- **Utility Functions** - Collection of useful helper functions for development
 
-## Установка
+## Installation
 
 ```bash
 npm install @balancy/utils
 ```
 
-## 🚀 Быстрый старт с IndexedDB FileHelper
+## 🚀 Quick Start with IndexedDB FileHelper
 
 ```typescript
 import { IndexedDBFileHelperAdapter } from '@balancy/utils';
-import { Balancy, DataObjectsManager } from '@balancy/core'; // Импорт из приложения
+import { Balancy } from '@balancy/core';
 
-// Создание и инициализация файлового помощника
+// Create and initialize the file helper
 const fileHelperAdapter = await IndexedDBFileHelperAdapter.create({
-    cachePath: '.balancy',
-    preloadStrategy: 'full' // полная предзагрузка для максимальной производительности
-});
-
-// ❗ ВАЖНО: Настройка интеграции с DataObjectsManager (решает проблему дублирования)
-fileHelperAdapter.setSpriteLoader((id, callback) => {
-    DataObjectsManager.loadSprite(id, callback);
+    cachePath: '.balancy'
 });
 
-// Получение статистики
+// Get cache statistics
 const stats = fileHelperAdapter.getCacheStats();
 console.log(`📁 Files: ${stats.fileCount}, 💾 Memory: ${stats.memoryUsage}`);
 
-// Инициализация Balancy
+// Initialize Balancy (DataObjectsManager integration is automatic)
 await Balancy.Main.initializeFileHelper(fileHelperAdapter);
 ```
 
-## 🛠️ Использование утилитарных функций
+## 🛠️ Using Utility Functions
 
 ```typescript
 import { isEmpty, deepClone, formatNumber, generateId, delay, retry } from '@balancy/utils';
 
-// Проверка на пустое значение
-console.log(isEmpty('')); // true
-console.log(isEmpty([])); // true
-console.log(isEmpty({})); // true
+// Check for empty values
+console.log(isEmpty(''));     // true
+console.log(isEmpty([]));     // true
+console.log(isEmpty({}));     // true
 
-// Глубокое клонирование
+// Deep clone objects
 const original = { a: 1, b: { c: 2 } };
 const cloned = deepClone(original);
 
-// Форматирование чисел
+// Format numbers
 console.log(formatNumber(1234567)); // "1,234,567"
 
-// Генерация ID
-console.log(generateId()); // "AbC12xyz"
-console.log(generateId(12)); // "AbC12xyzDeFg"
+// Generate random IDs
+console.log(generateId());     // "AbC12xyz"
+console.log(generateId(12));   // "AbC12xyzDeFg"
 
-// Задержка
-await delay(1000); // ждет 1 секунду
+// Delay execution
+await delay(1000); // wait 1 second
 
-// Retry с экспоненциальной задержкой
+// Retry with exponential backoff
 const result = await retry(async () => {
-  // некая асинхронная операция
-  return await fetchData();
-}, 3, 1000); // 3 попытки, начальная задержка 1с
+    // some async operation
+    return await fetchData();
+}, 3, 1000); // 3 attempts, 1s base delay
 ```
 
 ## 📁 IndexedDB FileHelper API
 
 ### `IndexedDBFileHelperAdapter.create(config)`
-Основной способ создания адаптера файловой системы.
+Main method to create a file system adapter.
 
 ```typescript
-interface IndexedDBFileHelperConfig {
-  cachePath: string;           // Путь к кэшу (обязательно)
-  codePath?: string;           // Путь к генерируемому коду
-  resourcesPath?: string;      // Путь к ресурсам
-  preloadStrategy?: 'none' | 'partial' | 'full'; // Стратегия предзагрузки
-  enableLogging?: boolean;     // Включить логирование
+interface FileHelperPaths {
+  cachePath: string;           // Cache path (required)
+  codePath?: string;           // Generated code path
+  resourcesPath?: string;      // Resources path
 }
 ```
 
-### Альтернативные методы создания:
+### Alternative creation methods:
 
 ```typescript
-// Быстрое создание без предзагрузки
+// Fast creation without preloading
 const fastAdapter = await IndexedDBFileHelperAdapter.createFast({
   cachePath: '.balancy'
 });
 
-// Создание с частичной предзагрузкой
+// Creation with partial preloading
 const partialAdapter = await IndexedDBFileHelperAdapter.createWithPartialPreload({
   cachePath: '.balancy'
 });
 ```
 
-### Основные методы:
+### Main methods:
 
 #### `getBinaryFile(key: string): Promise<Uint8Array | null>`
-Загружает бинарный файл по ключу.
+Loads a binary file by key.
 
 #### `saveBinaryFile(key: string, data: Uint8Array): Promise<boolean>`
-Сохраняет бинарные данные.
+Saves binary data.
 
 #### `hasFile(key: string): Promise<boolean>`
-Проверяет существование файла.
+Checks if file exists.
 
 #### `deleteFile(key: string): Promise<boolean>`
-Удаляет файл из кэша.
+Deletes file from cache.
 
 #### `getCacheStats(): CacheStats`
-Возвращает статистику использования кэша.
+Returns cache usage statistics.
 
 ```typescript
 interface CacheStats {
-  fileCount: number;        // Количество файлов в кэше
-  memoryUsage: string;      // Использование памяти (в читаемом формате)
-  hitRate?: number;         // Процент попаданий в кэш
-  totalRequests?: number;   // Общее количество запросов
-  cacheHits?: number;       // Количество попаданий в кэш
+  fileCount: number;        // Number of files in cache
+  memoryUsage: string;      // Memory usage (human readable)
+  hitRate?: number;         // Cache hit rate percentage
+  totalRequests?: number;   // Total number of requests
+  cacheHits?: number;       // Number of cache hits
 }
 ```
 
-## 🔧 Утилитарные функции
+## 🔧 Utility Functions
 
 ### `isEmpty(value: any): boolean`
-Проверяет, является ли значение пустым (null, undefined, пустая строка, пустой массив, пустой объект).
+Checks if value is empty (null, undefined, empty string, empty array, empty object).
 
 ### `deepClone<T>(obj: T): T`
-Выполняет глубокое клонирование объекта.
+Performs deep cloning of objects.
 
 ### `formatNumber(num: number, locale?: string): string`
-Форматирует число с разделителями тысяч. По умолчанию использует локаль 'en-US'.
+Formats numbers with thousand separators. Uses 'en-US' locale by default.
 
 ### `generateId(length?: number): string`
-Генерирует случайный ID указанной длины (по умолчанию 8 символов).
+Generates random ID of specified length (default 8 characters).
 
 ### `delay(ms: number): Promise<void>`
-Создает задержку на указанное количество миллисекунд.
+Creates a delay for specified milliseconds.
 
 ### `retry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelay?: number): Promise<T>`
-Выполняет функцию с повторными попытками при ошибках. Использует экспоненциальную задержку между попытками.
+Executes function with retry attempts on errors. Uses exponential backoff between attempts.
 
-## 📖 Примеры использования
+## 📖 Usage Examples
 
-### Интеграция с игровой логикой
+### Game Data Integration
 
 ```typescript
-// Сохранение игровых данных
+// Save game data
 const gameData = {
   playerLevel: 42,
   coins: 1500,
@@ -160,15 +152,15 @@ const gameData = {
 const jsonData = JSON.stringify(gameData);
 await adapter.saveBinaryFile('player_data.json', new TextEncoder().encode(jsonData));
 
-// Загрузка игровых данных
+// Load game data
 const savedData = await adapter.getBinaryFile('player_data.json');
 if (savedData) {
   const parsedData = JSON.parse(new TextDecoder().decode(savedData));
-  console.log('Игровые данные:', parsedData);
+  console.log('Game data:', parsedData);
 }
 ```
 
-### Мониторинг производительности
+### Performance Monitoring
 
 ```typescript
 const stats = adapter.getCacheStats();
@@ -177,31 +169,25 @@ console.log(`Memory usage: ${stats.memoryUsage}`);
 console.log(`Total files: ${stats.fileCount}`);
 ```
 
-## 🏗️ Стратегии предзагрузки
+## 🏗️ Preloading Strategies
+
+The package supports different preloading strategies for optimal performance:
 
-- **`'full'`** - Загружает ВСЕ файлы в память при инициализации. Максимальная производительность, больше памяти.
-- **`'partial'`** - Загружает только файлы из основного кэша. Компромисс между скоростью и памятью.
-- **`'none'`** - Не предзагружает файлы. Минимальное использование памяти, файлы загружаются по требованию.
+- **`'full'`** - Loads ALL files into memory at initialization. Maximum performance, higher memory usage.
+- **`'partial'`** - Loads only cache files. Balance between speed and memory.
+- **`'none'`** - No preloading. Minimal memory usage, files loaded on demand.
 
-## 📋 TypeScript интерфейсы
+## 📋 TypeScript Interfaces
 
 ```typescript
-// Основные интерфейсы для FileHelper
+// Main interfaces for FileHelper
 interface FileHelperPaths {
   cachePath: string;
   codePath?: string;
   resourcesPath?: string;
 }
 
-interface ICachedFileHelper {
-  getBinaryFile(key: string): Promise<Uint8Array | null>;
-  saveBinaryFile(key: string, data: Uint8Array): Promise<boolean>;
-  hasFile(key: string): Promise<boolean>;
-  deleteFile(key: string): Promise<boolean>;
-  clearCache(): Promise<boolean>;
-}
-
-// Утилитарные интерфейсы
+// Utility interfaces
 interface RetryOptions {
   maxAttempts?: number;
   baseDelay?: number;
@@ -213,71 +199,46 @@ interface UtilsConfig {
 }
 ```
 
-## 🚨 Важные замечания
+## 🚨 Important Notes
 
-### Интеграция с Balancy Core
+### Integration with Balancy Core
 
-Пакет `@balancy/utils` создан как **опциональная зависимость** от `@balancy/core`. Это означает:
+The `@balancy/utils` package is designed as an **optional dependency** of `@balancy/core`. This means:
 
-✅ **Можно использовать** IndexedDB функциональность независимо от Balancy Core  
-✅ **Можно интегрировать** с Balancy Core для полной функциональности  
-✅ **TypeScript поддержка** полностью работает в обоих случаях
+✅ **Can be used** independently for IndexedDB functionality  
+✅ **Can be integrated** with Balancy Core for full functionality  
+✅ **TypeScript support** works fully in both cases  
 
 ```typescript
-// Независимое использование
+// Independent usage
 import { IndexedDBFileHelperAdapter } from '@balancy/utils';
 const adapter = await IndexedDBFileHelperAdapter.create({ cachePath: '.balancy' });
 
-// Интеграция с Balancy (требует @balancy/core)
+// Integration with Balancy (requires @balancy/core)
 import { Balancy } from '@balancy/core';
 import { IndexedDBFileHelperAdapter } from '@balancy/utils';
 
 const adapter = await IndexedDBFileHelperAdapter.create({ cachePath: '.balancy' });
-await Balancy.Main.initializeFileHelper(adapter);
+await Balancy.Main.initializeFileHelper(adapter); // Auto-configures DataObjectsManager
 ```
 
-### Производительность
-
-- **Стратегия `'full'`** рекомендуется для продакшн приложений
-- **Стратегия `'partial'`** подходит для разработки
-- **Стратегия `'none'`** для ограниченных ресурсов
-
-### Совместимость
+### Performance
 
-- ✅ Современные браузеры с поддержкой IndexedDB
-- ✅ Web Workers (с ограничениями)
-- ❌ Node.js (IndexedDB недоступен)
-- ❌ React Native (требуется полифилл)
+- **Strategy `'full'`** recommended for production applications
+- **Strategy `'partial'`** suitable for development
+- **Strategy `'none'`** for resource-constrained environments
 
-## 🔧 Решение проблем
+### Compatibility
 
-### Проблема дублирования DataObjectsManager
-
-Если вы видите ошибку `Cannot read properties of undefined (reading 'loadSpritePrivate')`, это означает дублирование модулей.
-
-**Симптомы:**
-```javascript
-console.log(DataObjectsManager.instance); // то undefined, то объект
-```
-
-**Решение:**
-```typescript
-// ❌ НЕПРАВИЛЬНО: Прямой импорт в utils может привести к дублированию
-// import { DataObjectsManager } from '@balancy/core'; // в utils пакете
-
-// ✅ ПРАВИЛЬНО: Передача через setSpriteLoader
-import { DataObjectsManager } from '@balancy/core'; // в вашем приложении
-
-const adapter = await IndexedDBFileHelperAdapter.create({cachePath: '.balancy'});
-adapter.setSpriteLoader((id, callback) => {
-    DataObjectsManager.loadSprite(id, callback); // Использует правильный экземпляр
-});
-```
+- ✅ Modern browsers with IndexedDB support
+- ✅ Web Workers (with limitations)
+- ❌ Node.js (IndexedDB not available)
+- ❌ React Native (requires polyfill)
 
-## Лицензия
+## License
 
 MIT
 
-## Поддержка
+## Support
 
-Для вопросов и поддержки обращайтесь к команде Balancy.
+For questions and support, contact the Balancy team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balancy/utils",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "homepage": "https://balancy.co",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     }
   },
   "dependencies": {
-    "@balancy/core": "~1.0.34"
+    "@balancy/core": "~1.0.36"
   },
   "devDependencies": {}
 }