@balancy/utils 1.0.34

package/README.md

@@ -0,0 +1,283 @@
+# @balancy/utils
+
+Набор утилитарных функций и хелперов для экосистемы Balancy.
+
+## ⭐ Основные возможности
+
+- **IndexedDB FileHelper** - Полнофункциональная система работы с файлами через IndexedDB
+- **Утилитарные функции** - Набор полезных хелперов для разработки
+
+## Установка
+
+```bash
+npm install @balancy/utils
+```
+
+## 🚀 Быстрый старт с IndexedDB FileHelper
+
+```typescript
+import { IndexedDBFileHelperAdapter } from '@balancy/utils';
+import { Balancy, DataObjectsManager } from '@balancy/core'; // Импорт из приложения
+
+// Создание и инициализация файлового помощника
+const fileHelperAdapter = await IndexedDBFileHelperAdapter.create({
+    cachePath: '.balancy',
+    preloadStrategy: 'full' // полная предзагрузка для максимальной производительности
+});
+
+// ❗ ВАЖНО: Настройка интеграции с DataObjectsManager (решает проблему дублирования)
+fileHelperAdapter.setSpriteLoader((id, callback) => {
+    DataObjectsManager.loadSprite(id, callback);
+});
+
+// Получение статистики
+const stats = fileHelperAdapter.getCacheStats();
+console.log(`📁 Files: ${stats.fileCount}, 💾 Memory: ${stats.memoryUsage}`);
+
+// Инициализация Balancy
+await Balancy.Main.initializeFileHelper(fileHelperAdapter);
+```
+
+## 🛠️ Использование утилитарных функций
+
+```typescript
+import { isEmpty, deepClone, formatNumber, generateId, delay, retry } from '@balancy/utils';
+
+// Проверка на пустое значение
+console.log(isEmpty('')); // true
+console.log(isEmpty([])); // true
+console.log(isEmpty({})); // true
+
+// Глубокое клонирование
+const original = { a: 1, b: { c: 2 } };
+const cloned = deepClone(original);
+
+// Форматирование чисел
+console.log(formatNumber(1234567)); // "1,234,567"
+
+// Генерация ID
+console.log(generateId()); // "AbC12xyz"
+console.log(generateId(12)); // "AbC12xyzDeFg"
+
+// Задержка
+await delay(1000); // ждет 1 секунду
+
+// Retry с экспоненциальной задержкой
+const result = await retry(async () => {
+  // некая асинхронная операция
+  return await fetchData();
+}, 3, 1000); // 3 попытки, начальная задержка 1с
+```
+
+## 📁 IndexedDB FileHelper API
+
+### `IndexedDBFileHelperAdapter.create(config)`
+Основной способ создания адаптера файловой системы.
+
+```typescript
+interface IndexedDBFileHelperConfig {
+  cachePath: string;           // Путь к кэшу (обязательно)
+  codePath?: string;           // Путь к генерируемому коду
+  resourcesPath?: string;      // Путь к ресурсам
+  preloadStrategy?: 'none' | 'partial' | 'full'; // Стратегия предзагрузки
+  enableLogging?: boolean;     // Включить логирование
+}
+```
+
+### Альтернативные методы создания:
+
+```typescript
+// Быстрое создание без предзагрузки
+const fastAdapter = await IndexedDBFileHelperAdapter.createFast({
+  cachePath: '.balancy'
+});
+
+// Создание с частичной предзагрузкой
+const partialAdapter = await IndexedDBFileHelperAdapter.createWithPartialPreload({
+  cachePath: '.balancy'
+});
+```
+
+### Основные методы:
+
+#### `getBinaryFile(key: string): Promise<Uint8Array | null>`
+Загружает бинарный файл по ключу.
+
+#### `saveBinaryFile(key: string, data: Uint8Array): Promise<boolean>`
+Сохраняет бинарные данные.
+
+#### `hasFile(key: string): Promise<boolean>`
+Проверяет существование файла.
+
+#### `deleteFile(key: string): Promise<boolean>`
+Удаляет файл из кэша.
+
+#### `getCacheStats(): CacheStats`
+Возвращает статистику использования кэша.
+
+```typescript
+interface CacheStats {
+  fileCount: number;        // Количество файлов в кэше
+  memoryUsage: string;      // Использование памяти (в читаемом формате)
+  hitRate?: number;         // Процент попаданий в кэш
+  totalRequests?: number;   // Общее количество запросов
+  cacheHits?: number;       // Количество попаданий в кэш
+}
+```
+
+## 🔧 Утилитарные функции
+
+### `isEmpty(value: any): boolean`
+Проверяет, является ли значение пустым (null, undefined, пустая строка, пустой массив, пустой объект).
+
+### `deepClone<T>(obj: T): T`
+Выполняет глубокое клонирование объекта.
+
+### `formatNumber(num: number, locale?: string): string`
+Форматирует число с разделителями тысяч. По умолчанию использует локаль 'en-US'.
+
+### `generateId(length?: number): string`
+Генерирует случайный ID указанной длины (по умолчанию 8 символов).
+
+### `delay(ms: number): Promise<void>`
+Создает задержку на указанное количество миллисекунд.
+
+### `retry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelay?: number): Promise<T>`
+Выполняет функцию с повторными попытками при ошибках. Использует экспоненциальную задержку между попытками.
+
+## 📖 Примеры использования
+
+### Интеграция с игровой логикой
+
+```typescript
+// Сохранение игровых данных
+const gameData = {
+  playerLevel: 42,
+  coins: 1500,
+  achievements: ['first_win', 'level_10']
+};
+
+const jsonData = JSON.stringify(gameData);
+await adapter.saveBinaryFile('player_data.json', new TextEncoder().encode(jsonData));
+
+// Загрузка игровых данных
+const savedData = await adapter.getBinaryFile('player_data.json');
+if (savedData) {
+  const parsedData = JSON.parse(new TextDecoder().decode(savedData));
+  console.log('Игровые данные:', parsedData);
+}
+```
+
+### Мониторинг производительности
+
+```typescript
+const stats = adapter.getCacheStats();
+console.log(`Cache hit rate: ${stats.hitRate}%`);
+console.log(`Memory usage: ${stats.memoryUsage}`);
+console.log(`Total files: ${stats.fileCount}`);
+```
+
+## 🏗️ Стратегии предзагрузки
+
+- **`'full'`** - Загружает ВСЕ файлы в память при инициализации. Максимальная производительность, больше памяти.
+- **`'partial'`** - Загружает только файлы из основного кэша. Компромисс между скоростью и памятью.
+- **`'none'`** - Не предзагружает файлы. Минимальное использование памяти, файлы загружаются по требованию.
+
+## 📋 TypeScript интерфейсы
+
+```typescript
+// Основные интерфейсы для 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>;
+}
+
+// Утилитарные интерфейсы
+interface RetryOptions {
+  maxAttempts?: number;
+  baseDelay?: number;
+}
+
+interface UtilsConfig {
+  defaultLocale?: string;
+  defaultIdLength?: number;
+}
+```
+
+## 🚨 Важные замечания
+
+### Интеграция с Balancy Core
+
+Пакет `@balancy/utils` создан как **опциональная зависимость** от `@balancy/core`. Это означает:
+
+✅ **Можно использовать** IndexedDB функциональность независимо от Balancy Core  
+✅ **Можно интегрировать** с Balancy Core для полной функциональности  
+✅ **TypeScript поддержка** полностью работает в обоих случаях
+
+```typescript
+// Независимое использование
+import { IndexedDBFileHelperAdapter } from '@balancy/utils';
+const adapter = await IndexedDBFileHelperAdapter.create({ cachePath: '.balancy' });
+
+// Интеграция с Balancy (требует @balancy/core)
+import { Balancy } from '@balancy/core';
+import { IndexedDBFileHelperAdapter } from '@balancy/utils';
+
+const adapter = await IndexedDBFileHelperAdapter.create({ cachePath: '.balancy' });
+await Balancy.Main.initializeFileHelper(adapter);
+```
+
+### Производительность
+
+- **Стратегия `'full'`** рекомендуется для продакшн приложений
+- **Стратегия `'partial'`** подходит для разработки
+- **Стратегия `'none'`** для ограниченных ресурсов
+
+### Совместимость
+
+- ✅ Современные браузеры с поддержкой IndexedDB
+- ✅ Web Workers (с ограничениями)
+- ❌ Node.js (IndexedDB недоступен)
+- ❌ React Native (требуется полифилл)
+
+## 🔧 Решение проблем
+
+### Проблема дублирования 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); // Использует правильный экземпляр
+});
+```
+
+## Лицензия
+
+MIT
+
+## Поддержка
+
+Для вопросов и поддержки обращайтесь к команде Balancy.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export * from './indexeddb';
+/**
+ * Проверяет, является ли значение пустым (null, undefined, пустая строка, пустой массив, пустой объект)
+ */
+export declare function isEmpty(value: any): boolean;
+/**
+ * Глубокое клонирование объекта
+ */
+export declare function deepClone<T>(obj: T): T;
+/**
+ * Форматирование чисел с разделителями тысяч
+ */
+export declare function formatNumber(num: number, locale?: string): string;
+/**
+ * Генерация случайного ID
+ */
+export declare function generateId(length?: number): string;
+/**
+ * Задержка выполнения (Promise-based sleep)
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Retry функция с экспоненциальной задержкой
+ */
+export declare function retry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelay?: number): Promise<T>;
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+}
+export interface UtilsConfig {
+    defaultLocale?: string;
+    defaultIdLength?: number;
+}
+export declare const VERSION = "1.0.0-rc.24";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,aAAa,CAAC;AAM5B;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAM3C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CActC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAgB,GAAG,MAAM,CAE1E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,MAAU,GAAG,MAAM,CAOrD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAAU,EACvB,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,CAAC,CAAC,CAeZ;AAGD,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAGD,eAAO,MAAM,OAAO,gBAAgB,CAAC"}