unitmaster 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sizone
+
+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,125 @@
+# UnitConvert
+
+TypeScript 기반의 강력하고 유연한 단위 변환 라이브러리입니다.
+컴퓨터 용량, 전력, 거리 등 다양한 도메인의 단위 변환을 지원하며, 사용자 정의 단위를 쉽게 확장할 수 있습니다.
+
+## 설치 (Installation)
+
+```bash
+npm install unitconvert
+```
+
+## 주요 기능 (Features)
+
+- **다양한 기본 변환기 제공**: 컴퓨터 용량, 전력 용량/사용량, 거리 등
+- **상대적 단위 정의**: 이전 단위 대비 배수(Step)를 통한 직관적인 단위 정의
+- **최적 단위 자동 변환**: 값을 가장 읽기 쉬운 단위로 자동 포맷팅 (`formatBest`)
+- **타입 안전성**: TypeScript로 작성되어 완벽한 타입 지원
+- **확장 가능**: `UnitConverter` 클래스를 상속받아 나만의 변환기 제작 가능
+
+## 사용법 (Usage)
+
+### 1. 컴퓨터 용량 변환 (Computer Capacity)
+
+Byte, KB, MB, GB, TB, PB, EB, ZB, YB 등을 지원합니다. (1024 배수 기준)
+
+```typescript
+import { ComputerCapacityConverter } from 'unitconvert';
+
+const converter = new ComputerCapacityConverter();
+
+// 1. 단순 단위 변환
+// 1024 Byte -> 1 KB
+console.log(converter.convertTo(1024, 'Byte', 'KB')); // 1
+
+// 1 MB -> Byte
+console.log(converter.convertTo(1, 'MB', 'Byte')); // 1048576
+
+// 2. 최적 단위 자동 포맷팅
+console.log(converter.formatBest(1048576)); // "1 MB"
+console.log(converter.formatBest(2048));    // "2 KB"
+```
+
+### 2. 거리 변환 (Distance)
+
+mm, cm(10), m(100), km(1000) 단위를 지원합니다.
+
+```typescript
+import { DistanceConverter } from 'unitconvert';
+
+const distConverter = new DistanceConverter();
+
+// 1 km -> m
+console.log(distConverter.convertTo(1, 'km', 'm')); // 1000
+
+// 100 cm -> 1 m
+console.log(distConverter.formatBest(100, undefined)); // "10 cm" 가 아니라 최적 단위인 "1 m"로 변환 (로직에 따라 다름)
+// formatBest는 값이 1 이상이 되는 가장 큰 단위를 찾습니다.
+```
+
+### 3. 전력 변환 (Power)
+
+- **PowerCapacityConverter**: W, kW, MW, GW, TW (1000 배수)
+- **PowerUsageConverter**: Wh, kWh, MWh, GWh, TWh (1000 배수)
+
+```typescript
+import { PowerCapacityConverter } from 'unitconvert';
+
+const powerConverter = new PowerCapacityConverter();
+console.log(powerConverter.formatBest(1500)); // "1.5 kW" (기본 단위 W 기준)
+```
+
+## 고급 사용법 (Advanced)
+
+### 사용자 정의 단위 추가 (Custom Units)
+
+기존 변환기에 새로운 단위를 추가할 수 있습니다. `registerUnit`으로 추가하는 단위는 **마지막 단위**를 기준으로 계산됩니다.
+
+```typescript
+const converter = new ComputerCapacityConverter();
+// YB(YottaByte) 다음 단위로 BrontoByte(BB)를 추가한다고 가정 (1024배)
+converter.registerUnit([{ unit: 'BB', unitValue: 1024 }]);
+```
+
+### 나만의 변환기 만들기 (Custom Converter)
+
+`UnitConverter`를 상속받아 새로운 도메인의 변환기를 만들 수 있습니다.
+
+```typescript
+import { UnitConverter } from 'unitconvert';
+
+class TimeConverter extends UnitConverter {
+    constructor() {
+        super();
+        this.registerUnit([
+            { unit: 'Sec', unitValue: 1 },      // 기준 단위
+            { unit: 'Min', unitValue: 60 },     // 이전 단위(Sec) * 60
+            { unit: 'Hour', unitValue: 60 },    // 이전 단위(Min) * 60
+            { unit: 'Day', unitValue: 24 }      // 이전 단위(Hour) * 24
+        ]);
+    }
+}
+
+const timeConverter = new TimeConverter();
+console.log(timeConverter.formatBest(3600)); // "1 Hour"
+```
+
+### 복합 입력값 처리
+
+값과 단위 정의를 객체로 전달하여 처리할 수도 있습니다. 이 경우 동적으로 전달된 단위 정의를 사용합니다.
+
+```typescript
+const complexInput = {
+    value: 2048,
+    unit: [
+        { unit: 'Byte', unitValue: 1 },
+        { unit: 'KB', unitValue: 1024 }
+    ]
+};
+// converter 인스턴스의 종류와 상관없이 formatBest는 입력받은 unit 정의를 우선할 수 있습니다.
+// (단, formatBest 구현 상세에 따라 사용법이 다를 수 있음. 주로 내부 로직용)
+```
+
+## 라이선스
+
+MIT

package/dist/UnitConverter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file UnitConverter.ts
+ * @author 김영찬
+ * @since 2026-01-20
+ * @description 단위 변환 기능 및 최적 단위 표시 기능을 제공하는 메인 클래스입니다.
+ */
+import { UnitDefinition, ComplexValueInput } from './types';
+/**
+ * 단위 변환기 클래스
+ */
+export declare class UnitConverter {
+    private units;
+    /**
+     * 생성자
+     * @description 기본 컴퓨터 용량 단위(Byte, KB, MB, GB, TB, PB)를 초기화합니다.
+     */
+    constructor();
+    /**
+     * 기본 컴퓨터 용량 단위 등록
+     */
+    private registerDefaultUnits;
+    /**
+     * 단위 등록 (Rule 5)
+     * @param units 단위 정의 목록
+     */
+    registerUnit(units: UnitDefinition[]): void;
+    /**
+     * 특정 단위로 값 변환 (Rule 1, Rule 4)
+     * @param value 값
+     * @param fromUnit 현재 단위 (문자열)
+     * @param toUnit 변환할 단위 (문자열)
+     * @returns 변환된 값
+     */
+    convertTo(value: number, fromUnit: string, toUnit: string): number;
+    /**
+     * 입력 값을 받아 최적의 단위로 변환 (Rule 1, Rule 2, Rule 3)
+     * @param input 복합 입력 값 ({value, unit[]}) 또는 단순 값
+     * @param fixedUnits 사용할 단위 목록 (없으면 등록된 단위 사용)
+     * @returns 변환된 문자열 (예: "100 MB")
+     */
+    formatBest(input: number, fixedUnits?: UnitDefinition[]): string;
+    formatBest(input: ComplexValueInput): string;
+    /**
+     * 단위 정의 검색
+     */
+    private findUnit;
+    /**
+     * 현재 등록된 단위 목록 반환
+     */
+    getUnits(): UnitDefinition[];
+}

package/dist/UnitConverter.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * @file UnitConverter.ts
+ * @author 김영찬
+ * @since 2026-01-20
+ * @description 단위 변환 기능 및 최적 단위 표시 기능을 제공하는 메인 클래스입니다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnitConverter = void 0;
+/**
+ * 단위 변환기 클래스
+ */
+class UnitConverter {
+    /**
+     * 생성자
+     * @description 기본 컴퓨터 용량 단위(Byte, KB, MB, GB, TB, PB)를 초기화합니다.
+     */
+    constructor() {
+        this.units = [];
+        this.registerDefaultUnits();
+    }
+    /**
+     * 기본 컴퓨터 용량 단위 등록
+     */
+    registerDefaultUnits() {
+        this.units = [
+            { unit: 'Byte', unitValue: 1 },
+            { unit: 'KB', unitValue: 1024 },
+            { unit: 'MB', unitValue: 1024 * 1024 },
+            { unit: 'GB', unitValue: 1024 * 1024 * 1024 },
+            { unit: 'TB', unitValue: 1024 * 1024 * 1024 * 1024 },
+            { unit: 'PB', unitValue: 1024 * 1024 * 1024 * 1024 * 1024 }
+        ];
+    }
+    /**
+     * 단위 등록 (Rule 5)
+     * @param units 단위 정의 목록
+     */
+    registerUnit(units) {
+        this.units = [...this.units, ...units];
+        // unitValue 기준으로 오름차순 정렬 (계산 편의성)
+        this.units.sort((a, b) => a.unitValue - b.unitValue);
+    }
+    /**
+     * 특정 단위로 값 변환 (Rule 1, Rule 4)
+     * @param value 값
+     * @param fromUnit 현재 단위 (문자열)
+     * @param toUnit 변환할 단위 (문자열)
+     * @returns 변환된 값
+     */
+    convertTo(value, fromUnit, toUnit) {
+        const fromDef = this.findUnit(fromUnit);
+        const toDef = this.findUnit(toUnit);
+        if (!fromDef || !toDef) {
+            throw new Error(`Unit not found: ${!fromDef ? fromUnit : toUnit}`);
+        }
+        // 기본 단위 값으로 변환 후 목표 단위로 변환
+        // 예: 1 KB (1024) -> MB (1024*1024)
+        // 1 * 1024 / (1024*1024) = 0.0009765625
+        const baseValue = value * fromDef.unitValue;
+        return baseValue / toDef.unitValue;
+    }
+    formatBest(input, fixedUnits) {
+        let value;
+        let unitDefs;
+        if (typeof input === 'object' && 'unit' in input) {
+            // Rule 2 Case
+            // 입력값은 기본 단위(unitValue:1 또는 가장 작은 단위) 기준이라고 가정하거나,
+            // 아니면 입력 구조에 대한 명확한 정의가 필요함.
+            // 여기서는 입력된 value가 제공된 unit[0] (혹은 unitValue=1)이 아니라,
+            // 제공된 unit 리스트를 '사용할 단위 체계'로 보고, 
+            // value는 그 체계의 가장 작은 단위(혹은 기준 값)라고 가정함.
+            // *주의*: 요구사항의 예시가 모호하므로, 값은 Base Unit 기준이라고 가정.
+            value = input.value;
+            unitDefs = input.unit;
+            // 정렬
+            unitDefs.sort((a, b) => a.unitValue - b.unitValue);
+        }
+        else {
+            value = input;
+            unitDefs = fixedUnits || this.units;
+        }
+        if (unitDefs.length === 0)
+            return `${value}`;
+        // 가장 큰 단위부터 확인하여 값이 >= 1 인지 확인 (혹은 가장 적절한 단위)
+        // 오름차순 정렬되어 있다고 가정
+        // 예: 1000 Byte -> Byte (1000 >= 1)
+        // 1024 Byte -> KB (1024 >= 1024) => 1 KB
+        // 뒤(큰 단위)에서부터 탐색
+        for (let i = unitDefs.length - 1; i >= 0; i--) {
+            const unit = unitDefs[i];
+            if (value >= unit.unitValue) {
+                const converted = value / unit.unitValue;
+                // 정수로 딱 떨어지거나, 소수점 2자리까지 표시
+                const formatted = Number.isInteger(converted) ? converted : converted.toFixed(2);
+                return `${formatted} ${unit.unit}`;
+            }
+        }
+        // 가장 작은 단위보다도 작을 경우, 가장 작은 단위로 표시
+        const smallest = unitDefs[0];
+        const converted = value / smallest.unitValue;
+        const formatted = Number.isInteger(converted) ? converted : converted.toFixed(2);
+        return `${formatted} ${smallest.unit}`;
+    }
+    /**
+     * 단위 정의 검색
+     */
+    findUnit(unitName) {
+        return this.units.find(u => u.unit === unitName);
+    }
+    /**
+     * 현재 등록된 단위 목록 반환
+     */
+    getUnits() {
+        return this.units;
+    }
+}
+exports.UnitConverter = UnitConverter;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file index.ts
+ * @author 김영찬
+ * @since 2026-01-20
+ * @description 라이브러리 엔트리 포인트입니다.
+ */
+export * from './types';
+export * from './UnitConverter';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * @file index.ts
+ * @author 김영찬
+ * @since 2026-01-20
+ * @description 라이브러리 엔트리 포인트입니다.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./UnitConverter"), exports);

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file types.ts
+ * @author 김영찬
+ * @since 2026-01-20
+ * @description 단위 변환기에서 사용하는 타입 정의 파일입니다.
+ */
+/**
+ * 단위 정의 인터페이스
+ * @interface UnitDefinition
+ */
+export interface UnitDefinition {
+    /**
+     * 단위 명칭 (예: 'Byte', 'KB')
+     */
+    unit: string;
+    /**
+     * 단위 값 (기준 단위 대비 배수)
+     */
+    unitValue: number;
+}
+/**
+ * 복잡한 입력 값 구조
+ * @description 값과 해당 값의 단위 정의 목록을 포함하는 입력 형태입니다.
+ */
+export interface ComplexValueInput {
+    /**
+     * 변환할 값
+     */
+    value: number;
+    /**
+     * 단위 정의 목록
+     */
+    unit: UnitDefinition[];
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * @file types.ts
+ * @author 김영찬
+ * @since 2026-01-20
+ * @description 단위 변환기에서 사용하는 타입 정의 파일입니다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "unitmaster",
+  "version": "1.0.0",
+  "description": "Unit Converter Library",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "mocha -r ts-node/register test/**/*.test.ts"
+  },
+  "keywords": [
+    "unit",
+    "converter"
+  ],
+  "author": "김영찬",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/chai": "^4.3.11",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^20.10.5",
+    "chai": "^4.3.10",
+    "mocha": "^10.2.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}