@boristype/ws-version 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BorisType
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# WS Version Converter — Конвертер версий
+
+Утилита для преобразования semver версий в формат целевой системы (4 компонента).
+
+## Установка
+
+```bash
+npm install
+```
+
+## Использование
+
+```javascript
+import { 
+  convertSemverToWsVersion, 
+  convertSemverRangeToWsRange, 
+  compareWsVersions, 
+  isValidWsVersion,
+  isValidWsRange 
+} from './index.js';
+
+// Преобразование semver в ws-формат
+const wsVersion = convertSemverToWsVersion('1.2.3-beta.1');
+console.log(wsVersion); // "1.2.3.2001"
+
+// Преобразование промежутков версий
+const wsRange = convertSemverRangeToWsRange('^1.2.3');
+console.log(wsRange); // "^1.2.3.9999"
+
+const anyVersion = convertSemverRangeToWsRange('*');
+console.log(anyVersion); // "^0.0.0.0"
+
+// Сравнение ws-версий
+const result = compareWsVersions('1.0.0.1001', '1.0.0.9999');
+console.log(result); // -1 (альфа меньше обычной версии)
+
+// Проверка валидности
+console.log(isValidWsVersion('1.0.0')); // true
+console.log(isValidWsRange('^1.0.0.0')); // true
+console.log(isValidWsRange('~1.0.0.0')); // false (тильда не поддерживается)
+```
+
+## Формат целевой системы
+
+Целевая система использует версии из 3-4 компонентов в формате `major.minor.patch[.fourth]`:
+
+- Компоненты - неотрицательные числа
+- Разделитель - точка
+- Могут содержать лидирующие нули (например, `0.01.002`)
+- Максимальная граница компонентов не ограничена (может превышать 255 и 65535)
+
+## Алгоритм преобразования
+
+1. **major.minor.patch** - переносятся как есть из semver
+2. **fourth** - кодирует prerelease информацию:
+   - Если prerelease нет → `9999` (максимальный приоритет)
+   - `alpha.N` → `1000 + N`
+   - `beta.N` → `2000 + N`  
+   - `rc.N` → `3000 + N`
+   - Другие строки → `4000 + hash(string) % 1000`
+   - Только числа → `5000 + number`
+
+Это обеспечивает правильный порядок: prerelease < обычная версия.
+
+## Ограничения
+
+- Компоненты semver (major, minor, patch) не могут превышать 999
+- Информация о build (`+metadata`) игнорируется
+- Порядок сортировки semver сохраняется в ws-формате
+- Prerelease версии меньше обычных версий
+
+## Примеры преобразования
+
+| semver | ws-формат | Описание |
+|--------|-----------|----------|
+| `1.0.0` | `1.0.0.9999` | Стандартная версия |
+| `1.0.0-alpha.1` | `1.0.0.1001` | Alpha с номером |
+| `1.0.0-beta.5` | `1.0.0.2005` | Beta с номером |
+| `1.0.0-rc.1` | `1.0.0.3001` | Release candidate |
+| `2.1.0+build.123` | `2.1.0.9999` | Build metadata игнорируется |
+
+## Промежутки версий (Version Ranges)
+
+Модуль поддерживает преобразование промежутков версий semver в ws-формат:
+
+### Поддерживаемые промежутки:
+- **Точная версия**: `1.2.3` → `1.2.3.9999`
+- **Caret (совместимые)**: `^1.2.3` → `^1.2.3.9999`
+- **Tilde (приблизительно эквивалентные)**: `~1.2.3` → `^1.2.3.9999`
+- **Любая версия**: `*` → `^0.0.0.0`
+
+Примечание: tilde (`~`) преобразуется в caret (`^`), так как ws-формат поддерживает только caret.
+
+### Примеры преобразования ranges:
+| semver range | ws range | Описание |
+|--------------|----------|----------|
+| `1.0.0` | `1.0.0.9999` | Точная версия |
+| `^1.2.3` | `^1.2.3.9999` | Совместимые версии |
+| `~1.2.3` | `^1.2.3.9999` | Приблизительно эквивалентные |
+| `*` | `^0.0.0.0` | Любая версия |
+| `^1.0.0-alpha.1` | `^1.0.0.1001` | Caret с prerelease |
+
+**Порядок сортировки:** 1.0.0-alpha.1 < 1.0.0-beta.5 < 1.0.0-rc.1 < 1.0.0 ✅
+
+## API
+
+### `convertSemverToWsVersion(version: string): string`
+
+Преобразует semver версию в ws-формат.
+
+**Параметры:**
+- `version` - Версия в формате semver
+
+**Возвращает:** Версию в формате `x.y.z.w`
+
+**Исключения:** `Error` если версия невалидна или содержит компоненты > 999
+
+### `compareWsVersions(version1: string, version2: string): -1 | 0 | 1`
+
+Сравнивает две ws-версии.
+
+**Возвращает:**
+- `-1` если version1 < version2
+- `0` если version1 === version2  
+- `1` если version1 > version2
+
+### `isValidWsVersion(version: string): boolean`
+
+Проверяет валидность ws-версии.
+
+**Параметры:**
+- `version` - Версия для проверки
+
+**Возвращает:** `true` если версия валидна
+
+### `convertSemverRangeToWsRange(range: string): string`
+
+Преобразует промежуток semver версий в ws-формат.
+
+**Параметры:**
+- `range` - Промежуток версий в формате semver (например, "^1.2.3", "~1.2.3", "*")
+
+**Возвращает:** Промежуток версий в формате ws
+
+**Исключения:** `Error` если промежуток невалиден
+
+### `isValidWsRange(range: string): boolean`
+
+Проверяет валидность ws-промежутка версий.
+
+## Тестирование
+
+```bash
+npm test
+# или 
+node test.js
+```
+
+## Лицензия
+
+MIT

package/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Преобразует semver версию в формат целевой системы (4 компонента)
+ * @param version - Версия в формате semver
+ * @returns Версия в формате x.y.z.w
+ * @throws {Error} Если версия невалидна или содержит компоненты > 999
+ */
+export function convertSemverToWsVersion(version: string): string;
+
+/**
+ * Сравнивает две версии в ws-формате 
+ * @param version1 - Первая версия
+ * @param version2 - Вторая версия  
+ * @returns Результат сравнения (-1 если v1 < v2, 0 если равны, 1 если v1 > v2)
+ */
+export function compareWsVersions(version1: string, version2: string): -1 | 0 | 1;
+
+/**
+ * Проверяет валидность ws-версии
+ * @param version - Версия для проверки
+ * @returns true если версия валидна
+ */
+export function isValidWsVersion(version: string): boolean;
+
+/**
+ * Кодирует prerelease информацию в число, сохраняя порядок сортировки
+ * @param prerelease - Массив prerelease компонентов
+ * @returns Закодированный номер
+ */
+export function encodePrereleaseToNumber(prerelease: readonly (string | number)[]): number;
+
+/**
+ * Преобразует промежуток версий semver в формат ws
+ * @param range - Промежуток версий в формате semver (например, "^1.2.3", "~1.2.3", "*")
+ * @returns Промежуток версий в формате ws
+ * @throws {Error} Если промежуток невалиден
+ */
+export function convertSemverRangeToWsRange(range: string): string;
+
+/**
+ * Проверяет валидность ws-промежутка версий
+ * @param range - Промежуток версий для проверки
+ * @returns true если промежуток валиден
+ */
+export function isValidWsRange(range: string): boolean;
+
+/**
+ * Тип для версии в ws-формате
+ */
+export type WsVersion = string;
+
+/**
+ * Тип для промежутка версий в ws-формате
+ */
+export type WsVersionRange = string;
+
+/**
+ * Опции для преобразования версий
+ */
+export interface ConversionOptions {
+  /** Максимальное значение для компонентов (по умолчанию 999) */
+  maxComponentValue?: number;
+  /** Строгая проверка semver */
+  strict?: boolean;
+}

package/index.js

@@ -0,0 +1,207 @@
+import semver from 'semver';
+
+/**
+ * Преобразует semver версию в формат целевой системы (4 компонента)
+ * @param {string} version - Версия в формате semver
+ * @returns {string} Версия в формате x.y.z.w
+ * @throws {Error} Если версия невалидна или содержит компоненты > 999
+ */
+function convertSemverToWsVersion(version) {
+  // Парсим semver версию
+  const parsed = semver.parse(version);
+  if (!parsed) {
+    throw new Error(`Invalid semver version: ${version}`);
+  }
+
+  const { major, minor, patch, prerelease } = parsed;
+
+  // Проверяем ограничения (не больше 999)
+  if (major > 999 || minor > 999 || patch > 999) {
+    throw new Error(`Version components cannot exceed 999: ${version}`);
+  }
+
+  // Четвертый компонент для prerelease
+  let fourth = 9999; // Обычные версии получают максимальное значение
+
+  if (prerelease && prerelease.length > 0) {
+    fourth = encodePrereleaseToNumber(prerelease);
+  }
+
+  return `${major}.${minor}.${patch}.${fourth}`;
+}
+
+/**
+ * Кодирует prerelease информацию в число, сохраняя порядок сортировки
+ * Обычные релизы получают значение 9999, prerelease - меньшие значения
+ * @param {Array} prerelease - Массив prerelease компонентов
+ * @returns {number} Закодированный номер
+ */
+function encodePrereleaseToNumber(prerelease) {
+  if (!prerelease || prerelease.length === 0) {
+    return 9999; // Обычные версии имеют максимальный приоритет
+  }
+
+  // Определяем базовое значение на основе типа prerelease
+  const firstComponent = prerelease[0];
+  let base = 0;
+  
+  if (typeof firstComponent === 'string') {
+    switch (firstComponent.toLowerCase()) {
+      case 'alpha':
+        base = 1000;
+        break;
+      case 'beta':  
+        base = 2000;
+        break;
+      case 'rc':
+        base = 3000;
+        break;
+      default:
+        // Для неизвестных строковых компонентов используем хеш
+        base = 4000 + hashString(firstComponent) % 1000;
+        break;
+    }
+  } else if (typeof firstComponent === 'number') {
+    base = 5000;
+  }
+
+  // Добавляем числовой компонент если есть
+  let offset = 0;
+  if (prerelease.length > 1 && typeof prerelease[1] === 'number') {
+    offset = Math.min(prerelease[1], 999); // Ограничиваем 999
+  } else if (typeof firstComponent === 'number') {
+    offset = Math.min(firstComponent, 999);
+  }
+
+  return base + offset;
+}
+
+/**
+ * Простая хеш-функция для строк
+ * @param {string} str - Строка для хеширования
+ * @returns {number} Хеш-код
+ */
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Преобразуем в 32-битное целое
+  }
+  return Math.abs(hash);
+}
+
+/**
+ * Сравнивает две версии в ws-формате 
+ * @param {string} version1 - Первая версия
+ * @param {string} version2 - Вторая версия  
+ * @returns {-1|0|1} Результат сравнения (-1 если v1 < v2, 0 если равны, 1 если v1 > v2)
+ */
+function compareWsVersions(version1, version2) {
+  const v1Parts = version1.split('.').map(Number);
+  const v2Parts = version2.split('.').map(Number);
+  
+  for (let i = 0; i < 4; i++) {
+    const v1Part = v1Parts[i] || 0;
+    const v2Part = v2Parts[i] || 0;
+    
+    if (v1Part < v2Part) return -1;
+    if (v1Part > v2Part) return 1;
+  }
+  
+  return 0;
+}
+
+/**
+ * Проверяет валидность ws-версии
+ * @param {string} version - Версия для проверки
+ * @returns {boolean} true если версия валидна
+ */
+function isValidWsVersion(version) {
+  const parts = version.split('.');
+  if (parts.length < 3 || parts.length > 4) {
+    return false;
+  }
+  
+  return parts.every(part => {
+    // Проверяем что это строка из цифр (могут быть лидирующие нули)
+    if (!/^\d+$/.test(part)) {
+      return false;
+    }
+    const num = parseInt(part, 10);
+    return !isNaN(num) && num >= 0;
+  });
+}
+
+/**
+ * Преобразует промежуток версий semver в формат ws
+ * @param {string} range - Промежуток версий в формате semver (например, "^1.2.3", "~1.2.3", "*")
+ * @returns {string} Промежуток версий в формате ws
+ * @throws {Error} Если промежуток невалиден
+ */
+function convertSemverRangeToWsRange(range) {
+  // Убираем лишние пробелы
+  const trimmedRange = range.trim();
+  
+  // Обрабатываем специальный случай *
+  if (trimmedRange === '*') {
+    return '^0.0.0.0';
+  }
+  
+  // Проверяем наличие префиксов ^ или ~
+  const hasCaretPrefix = trimmedRange.startsWith('^');
+  const hasTildePrefix = trimmedRange.startsWith('~');
+  
+  let version;
+  if (hasCaretPrefix || hasTildePrefix) {
+    // Убираем префикс для парсинга
+    version = trimmedRange.slice(1);
+  } else {
+    // Точная версия без префикса
+    version = trimmedRange;
+  }
+  
+  // Преобразуем базовую версию
+  let wsVersion;
+  try {
+    wsVersion = convertSemverToWsVersion(version);
+  } catch (error) {
+    throw new Error(`Invalid version in range "${range}": ${error.message}`);
+  }
+  
+  // Для ^ и ~ добавляем префикс ^ в ws-формате
+  if (hasCaretPrefix || hasTildePrefix) {
+    return `^${wsVersion}`;
+  }
+  
+  // Для точных версий возвращаем как есть
+  return wsVersion;
+}
+
+/**
+ * Проверяет валидность ws-промежутка версий
+ * @param {string} range - Промежуток версий для проверки
+ * @returns {boolean} true если промежуток валиден
+ */
+function isValidWsRange(range) {
+  const trimmedRange = range.trim();
+  
+  // Проверяем наличие префикса ^
+  if (trimmedRange.startsWith('^')) {
+    const version = trimmedRange.slice(1);
+    return isValidWsVersion(version);
+  }
+  
+  // Проверяем как обычную версию
+  return isValidWsVersion(trimmedRange);
+}
+
+// Экспортируем функции
+export {
+  convertSemverToWsVersion,
+  convertSemverRangeToWsRange,
+  compareWsVersions, 
+  isValidWsVersion,
+  isValidWsRange,
+  encodePrereleaseToNumber
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@boristype/ws-version",
+  "version": "0.1.0-alpha.0",
+  "description": "Утилита для преобразования semver версий в формат целевой системы",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "semver": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.0.0",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "version",
+    "semver",
+    "conversion"
+  ],
+  "author": "BorisType Project",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BorisType/BorisType.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BorisType/BorisType/issues"
+  },
+  "homepage": "https://github.com/BorisType/BorisType#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node test.js"
+  }
+}