@simplysm/excel 13.0.100 → 14.0.4

package/src/utils/excel-utils.ts

@@ -2,49 +2,50 @@ import { num } from "@simplysm/core-common";
 import type { ExcelAddressPoint, ExcelAddressRangePoint, ExcelNumberFormat } from "../types";
 
 /**
- * Collection of Excel utility functions.
- * Provides cell address conversion, date/number conversion, and number format processing.
+ * Excel 유틸리티 함수 모음.
+ * 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 기능을 제공한다.
  */
 export class ExcelUtils {
-  /** Convert cell coordinates to "A1" format string */
+  /** 셀 좌표를 "A1" 형식 문자열로 변환 */
   static stringifyAddr(point: ExcelAddressPoint): string {
     const rowStr = this.stringifyRowAddr(point.r);
     const colStr = this.stringifyColAddr(point.c);
     return `${colStr}${rowStr}`;
   }
 
-  /** Convert row index (0-based) to row address string (e.g. 0 -> "1") */
+  /** 행 인덱스(0 기반)를 행 주소 문자열로 변환 (예: 0 -> "1") */
   static stringifyRowAddr(r: number): string {
     return (r + 1).toString();
   }
 
-  /** Convert column index (0-based) to column address string (e.g. 0 -> "A", 26 -> "AA") */
+  /** 열 인덱스(0 기반)를 열 주소 문자열로 변환 (예: 0 -> "A", 26 -> "AA") */
   static stringifyColAddr(c: number): string {
     if (c < 0 || c > 16383) {
-      throw new Error(`Column index must be in range 0~16383: ${c}`);
+      throw new Error(`열 인덱스는 0~16383 범위여야 합니다: ${c}`);
     }
 
     let remained = c;
     let result = String.fromCharCode((remained % 26) + 65);
     remained = Math.floor(remained / 26);
     while (remained !== 0) {
-      result = String.fromCharCode((remained % 26) + 64) + result;
+      remained -= 1;
+      result = String.fromCharCode((remained % 26) + 65) + result;
       remained = Math.floor(remained / 26);
     }
     return result;
   }
 
-  /** Extract row index from cell address (e.g. "A3" -> 2) */
+  /** 셀 주소에서 행 인덱스 추출 (예: "A3" -> 2) */
   static parseRowAddr(addr: string): number {
     const rowAddrCode = /\d*$/.exec(addr)?.[0] ?? "";
     const parsed = num.parseInt(rowAddrCode);
     if (parsed == null) {
-      throw new Error(`Invalid row address code: ${rowAddrCode}`);
+      throw new Error(`잘못된 행 주소 코드: ${rowAddrCode}`);
     }
     return parsed - 1;
   }
 
-  /** Extract column index from cell address (e.g. "B3" -> 1) */
+  /** 셀 주소에서 열 인덱스 추출 (예: "B3" -> 1) */
   static parseColAddr(addr: string): number {
     const colAddrCode = /^[a-zA-Z]*/.exec(addr)?.[0] ?? "";
 
@@ -57,7 +58,7 @@ export class ExcelUtils {
     return result;
   }
 
-  /** Convert cell address to coordinates (e.g. "B3" -> {r: 2, c: 1}) */
+  /** 셀 주소를 좌표로 변환 (예: "B3" -> {r: 2, c: 1}) */
   static parseCellAddr(addr: string): ExcelAddressPoint {
     return {
       r: ExcelUtils.parseRowAddr(addr),
@@ -65,7 +66,7 @@ export class ExcelUtils {
     };
   }
 
-  /** Convert range address to coordinates (e.g. "A1:C3" -> {s: {r:0,c:0}, e: {r:2,c:2}}) */
+  /** 범위 주소를 좌표로 변환 (예: "A1:C3" -> {s: {r:0,c:0}, e: {r:2,c:2}}) */
   static parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint {
     const parts = rangeAddr.split(":");
     return {
@@ -74,7 +75,7 @@ export class ExcelUtils {
     };
   }
 
-  /** Convert range coordinates to address string */
+  /** 범위 좌표를 주소 문자열로 변환 */
   static stringifyRangeAddr(point: ExcelAddressRangePoint): string {
     const sAddr = this.stringifyAddr(point.s);
     const eAddr = this.stringifyAddr(point.e);
@@ -87,8 +88,8 @@ export class ExcelUtils {
   }
 
   /**
-   * Convert JavaScript timestamp (ms) to Excel date number.
-   * Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
+   * JavaScript 타임스탬프(ms)를 Excel 날짜 숫자로 변환한다.
+   * Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
    */
   static convertTimeTickToNumber(tick: number): number {
     const currDate = new Date(tick);
@@ -99,8 +100,8 @@ export class ExcelUtils {
   }
 
   /**
-   * Convert Excel date number to JavaScript timestamp (ms).
-   * Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
+   * Excel 날짜 숫자를 JavaScript 타임스탬프(ms)로 변환한다.
+   * Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
    */
   static convertNumberToTimeTick(value: number): number {
     const excelBaseDateNumberUtc = Date.UTC(1899, 11, 31);
@@ -111,50 +112,55 @@ export class ExcelUtils {
     return date.getTime();
   }
 
-  /** Convert number format code to format name */
+  /** 숫자 형식 코드를 형식 이름으로 변환 */
   static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat {
     if (numFmtCode === "General") {
       return "number";
     }
 
-    const hasDate = /yy/i.test(numFmtCode) || /dd/i.test(numFmtCode) || /mm/i.test(numFmtCode);
-    const hasTime = /hh/i.test(numFmtCode) || /ss/i.test(numFmtCode);
+    // "mm"이 시간 문맥(h/hh 뒤 또는 ss 앞)에서 쓰이면 분(minute)이므로 날짜 판별에서 제외
+    const codeForDateCheck = numFmtCode
+      .replace(/h{1,2}\s*:?\s*mm/gi, "")
+      .replace(/mm\s*:?\s*ss/gi, "");
+    const hasDate =
+      /yy/i.test(numFmtCode) || /dd/i.test(numFmtCode) || /mm/i.test(codeForDateCheck);
+    const hasTime = /h{1,2}/i.test(numFmtCode) || /ss/i.test(numFmtCode);
 
     if (hasDate && hasTime) {
-      return "DateTime"; // date+time = DateTime
+      return "DateTime"; // 날짜+시간 = DateTime
     } else if (hasDate) {
-      return "DateOnly"; // date only = DateOnly
+      return "DateOnly"; // 날짜만 = DateOnly
     } else if (hasTime) {
-      return "Time"; // time only = Time
+      return "Time"; // 시간만 = Time
     }
-    // Number format pattern: 0, #, decimal, thousands separator, negative separator, parentheses, currency, space, exponent, percent, etc.
-    // In "[conditional format]actual format" structure, only check the actual format part (split("]").at(-1))
+    // 숫자 형식 패턴: 0, #, 소수점, 천단위 구분, 음수 구분, 괄호, 통화, 공백, 지수, 퍼센트 등
+    // "[조건부 형식]실제 형식" 구조에서 실제 형식 부분만 검사 (split("]").at(-1))
     else if (/^[0.#,_;()\-\\$ @*?"E%+]*$/.test(numFmtCode.split("]").at(-1) ?? "")) {
       return "number";
     } else if ((numFmtCode.split("]").at(-1) ?? "").includes("#,0")) {
       return "number";
     } else {
-      throw new Error(`Unknown format for [numFmtCode: ${numFmtCode}].`);
+      throw new Error(`알 수 없는 형식 [numFmtCode: ${numFmtCode}]`);
     }
   }
 
   /**
-   * Convert number format ID to format name
+   * 숫자 형식 ID를 형식 이름으로 변환
    *
    * @remarks
-   * Excel built-in format ID ranges:
-   * - 0~13, 37~40, 48: number/general/currency/percent formats
-   * - 14~17, 27~31, 34~36, 50~58: date formats (including localized)
-   * - 22: date+time format
-   * - 18~21, 32~33, 45~47: time formats
-   * - 49: text format
+   * Excel 내장 형식 ID 범위:
+   * - 0~13, 37~40, 48: 숫자/일반/통화/퍼센트 형식
+   * - 14~17, 27~31, 34~36, 50~58: 날짜 형식 (로컬라이즈 포함)
+   * - 22: 날짜+시간 형식
+   * - 18~21, 32~33, 45~47: 시간 형식
+   * - 49: 텍스트 형식
    */
   static convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat {
-    // Number/general/currency/percent formats
+    // 숫자/일반/통화/퍼센트 형식
     if (numFmtId <= 13 || (numFmtId >= 37 && numFmtId <= 40) || numFmtId === 48) {
       return "number";
     }
-    // Date formats (including localized)
+    // 날짜 형식 (로컬라이즈 포함)
     else if (
       (numFmtId >= 14 && numFmtId <= 17) ||
       (numFmtId >= 27 && numFmtId <= 31) ||
@@ -163,11 +169,11 @@ export class ExcelUtils {
     ) {
       return "DateOnly";
     }
-    // Date+time format
+    // 날짜+시간 형식
     else if (numFmtId === 22) {
       return "DateTime";
     }
-    // Time formats
+    // 시간 형식
     else if (
       (numFmtId >= 18 && numFmtId <= 21) ||
       (numFmtId >= 32 && numFmtId <= 33) ||
@@ -175,15 +181,15 @@ export class ExcelUtils {
     ) {
       return "Time";
     }
-    // Text format
+    // 텍스트 형식
     else if (numFmtId === 49) {
       return "string";
     } else {
-      throw new Error(`Unknown format for [numFmtId: ${numFmtId}].`);
+      throw new Error(`알 수 없는 형식 [numFmtId: ${numFmtId}]`);
     }
   }
 
-  /** Convert number format name to format ID */
+  /** 숫자 형식 이름을 형식 ID로 변환 */
   static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number {
     if (numFmtName === "number") {
       return 0;
@@ -194,7 +200,7 @@ export class ExcelUtils {
     } else if (numFmtName === "Time") {
       return 18;
     } else {
-      // Last case: "string" (TypeScript verifies automatically through type narrowing)
+      // 마지막 케이스: "string" (TypeScript가 타입 좁히기를 통해 자동 검증)
       return 49;
     }
   }

package/src/utils/zip-cache.ts

@@ -20,15 +20,15 @@ import { ExcelXmlWorkbook } from "../xml/excel-xml-workbook";
 import { ExcelXmlWorksheet } from "../xml/excel-xml-worksheet";
 
 /**
- * Class managing file cache for Excel ZIP archives.
- * XML files are parsed into ExcelXml objects; other files are cached as byte arrays.
+ * Excel ZIP 아카이브의 파일 캐시를 관리하는 클래스.
+ * XML 파일은 ExcelXml 객체로 파싱하고, 기타 파일은 바이트 배열로 캐싱한다.
  *
  * @remarks
- * ## Lazy Loading Cache Strategy
+ * ## Lazy Loading 캐시 전략
  *
- * - Files are read and parsed from the ZIP only on first access
- * - Subsequent accesses return the cached object
- * - Loads only the needed parts from large Excel files for memory efficiency
+ * - 파일은 최초 접근 시에만 ZIP에서 읽고 파싱함
+ * - 이후 접근은 캐싱된 객체를 반환함
+ * - 대용량 Excel 파일에서 필요한 부분만 로드하여 메모리 효율적
  */
 export class ZipCache {
   private readonly _cache = new Map<string, ExcelXml | Bytes | undefined>();

package/src/xml/excel-xml-content-type.ts

@@ -1,8 +1,8 @@
 import type { ExcelXml, ExcelXmlContentTypeData } from "../types";
 
 /**
- * Class managing [Content_Types].xml.
- * Manages MIME type information per file.
+ * [Content_Types].xml을 관리하는 클래스.
+ * 파일별 MIME 타입 정보를 관리한다.
  */
 export class ExcelXmlContentType implements ExcelXml {
   data: ExcelXmlContentTypeData;
@@ -45,7 +45,7 @@ export class ExcelXmlContentType implements ExcelXml {
   }
 
   add(partName: string, contentType: string): this {
-    // Duplicate check
+    // 중복 검사
     const exists = this.data.Types.Override.some((item) => item.$.PartName === partName);
     if (exists) {
       return this;

package/src/xml/excel-xml-drawing.ts

@@ -1,8 +1,8 @@
 import type { ExcelXml, ExcelXmlDrawingData } from "../types";
 
 /**
- * Class managing xl/drawings/drawing*.xml files.
- * Handles position and reference information for image insertion.
+ * xl/drawings/drawing*.xml 파일을 관리하는 클래스.
+ * 이미지 삽입을 위한 위치 및 참조 정보를 처리한다.
  */
 export class ExcelXmlDrawing implements ExcelXml {
   data: ExcelXmlDrawingData;

package/src/xml/excel-xml-relationship.ts

@@ -3,8 +3,8 @@ import { num } from "@simplysm/core-common";
 import type { ExcelRelationshipData, ExcelXml, ExcelXmlRelationshipData } from "../types";
 
 /**
- * Class managing *.rels files.
- * Handles reference relationships between files.
+ * *.rels 파일을 관리하는 클래스.
+ * 파일 간의 참조 관계를 처리한다.
  */
 export class ExcelXmlRelationship implements ExcelXml {
   data: ExcelXmlRelationshipData;
@@ -82,7 +82,7 @@ export class ExcelXmlRelationship implements ExcelXml {
   private _getRelId(rel: ExcelRelationshipData): number {
     const match = /[0-9]+$/.exec(rel.$.Id);
     if (match == null) {
-      throw new Error(`Invalid relationship ID format: ${rel.$.Id}`);
+      throw new Error(`잘못된 관계 ID 형식: ${rel.$.Id}`);
     }
     return num.parseInt(match[0])!;
   }

package/src/xml/excel-xml-shared-string.ts

@@ -7,8 +7,8 @@ import type {
 import "@simplysm/core-common";
 
 /**
- * Class managing xl/sharedStrings.xml.
- * Optimizes file size by preventing string duplication.
+ * xl/sharedStrings.xml을 관리하는 클래스.
+ * 문자열 중복을 방지하여 파일 크기를 최적화한다.
  */
 export class ExcelXmlSharedString implements ExcelXml {
   data: ExcelXmlSharedStringData;

package/src/xml/excel-xml-style.ts

@@ -21,8 +21,8 @@ export interface ExcelStyle {
 }
 
 /**
- * Class managing xl/styles.xml.
- * Handles styles such as number formats, background colors, borders, and alignment.
+ * xl/styles.xml을 관리하는 클래스.
+ * 숫자 형식, 배경색, 테두리, 정렬 등의 스타일을 처리한다.
  */
 export class ExcelXmlStyle implements ExcelXml {
   data: ExcelXmlStyleData;
@@ -108,11 +108,11 @@ export class ExcelXmlStyle implements ExcelXml {
   addWithClone(id: string, style: ExcelStyle): string {
     const idNum = num.parseInt(id);
     if (idNum == null) {
-      throw new Error(`Invalid style ID: ${id}`);
+      throw new Error(`잘못된 스타일 ID: ${id}`);
     }
     const xfArray = this.data.styleSheet.cellXfs[0].xf;
     if (idNum < 0 || idNum >= xfArray.length) {
-      throw new Error(`Non-existent style ID: ${id} (Range: 0-${xfArray.length - 1})`);
+      throw new Error(`존재하지 않는 스타일 ID: ${id} (범위: 0-${xfArray.length - 1})`);
     }
     const prevXf = xfArray[idNum];
     const cloneXf = obj.clone(prevXf);
@@ -136,9 +136,9 @@ export class ExcelXmlStyle implements ExcelXml {
         cloneFill.patternFill[0].$.patternType = "solid";
 
         if (cloneFill.patternFill[0].fgColor == null) {
-          cloneFill.patternFill[0].fgColor = [{ $: { rgb: style.background } }];
+          cloneFill.patternFill[0].fgColor = [{ $: { rgb: style.background.toUpperCase() } }];
         } else {
-          cloneFill.patternFill[0].fgColor[0].$.rgb = style.background;
+          cloneFill.patternFill[0].fgColor[0].$.rgb = style.background.toUpperCase();
         }
 
         cloneXf.$.applyFill = "1";
@@ -187,7 +187,7 @@ export class ExcelXmlStyle implements ExcelXml {
   get(id: string): ExcelStyle {
     const idNum = num.parseInt(id);
     if (idNum == null) {
-      throw new Error(`Invalid style ID: ${id}`);
+      throw new Error(`잘못된 스타일 ID: ${id}`);
     }
     const xf = this.data.styleSheet.cellXfs[0].xf[idNum] as ExcelXmlStyleDataXf | undefined;
 
@@ -204,7 +204,7 @@ export class ExcelXmlStyle implements ExcelXml {
             | undefined;
           if (fill == null) {
             throw new Error(
-              `Non-existent fill ID: ${xf.$.fillId} (Range: 0-${this.data.styleSheet.fills[0].fill.length - 1})`,
+              `존재하지 않는 fill ID: ${xf.$.fillId} (범위: 0-${this.data.styleSheet.fills[0].fill.length - 1})`,
             );
           }
           result.background = fill.patternFill[0].fgColor?.[0].$.rgb;
@@ -214,14 +214,14 @@ export class ExcelXmlStyle implements ExcelXml {
       if (xf.$.borderId !== undefined) {
         const borderIdNum = num.parseInt(xf.$.borderId);
         if (borderIdNum == null) {
-          throw new Error(`Invalid border ID: ${xf.$.borderId}`);
+          throw new Error(`잘못된 border ID: ${xf.$.borderId}`);
         }
         const border = this.data.styleSheet.borders[0].border[borderIdNum] as
           | ExcelXmlStyleDataBorder
           | undefined;
         if (border == null) {
           throw new Error(
-            `Non-existent border ID: ${xf.$.borderId} (Range: 0-${this.data.styleSheet.borders[0].border.length - 1})`,
+            `존재하지 않는 border ID: ${xf.$.borderId} (범위: 0-${this.data.styleSheet.borders[0].border.length - 1})`,
           );
         }
         if (
@@ -262,7 +262,7 @@ export class ExcelXmlStyle implements ExcelXml {
   cleanup(): void {
     const result = {} as ExcelXmlStyleData["styleSheet"];
 
-    // Sort order (numFmts first)
+    // 정렬 순서 (numFmts를 먼저)
 
     if (this.data.styleSheet.numFmts != null) {
       result.numFmts = this.data.styleSheet.numFmts;
@@ -282,7 +282,7 @@ export class ExcelXmlStyle implements ExcelXml {
   //#region Private Methods
 
   private _setNumFmtCode(numFmtCode: string): string {
-    // Skip if the code already exists
+    // 코드가 이미 존재하면 건너뛰기
     const existsNumFmtId = (this.data.styleSheet.numFmts?.[0].numFmt ?? []).single(
       (item) => item.$.formatCode === numFmtCode,
     )?.$.numFmtId;
@@ -299,7 +299,7 @@ export class ExcelXmlStyle implements ExcelXml {
 
     this.data.styleSheet.numFmts[0].numFmt = this.data.styleSheet.numFmts[0].numFmt ?? [];
 
-    // Excel custom number formats start from ID 180+ (0-163: built-in, 164-179: reserved)
+    // Excel 사용자 정의 숫자 형식은 ID 180+부터 시작 (0-163: 내장, 164-179: 예약)
     const numFmts = this.data.styleSheet.numFmts[0].numFmt;
     const maxItem =
       numFmts.length > 0

package/src/xml/excel-xml-unknown.ts

@@ -1,8 +1,8 @@
 import type { ExcelXml } from "../types";
 
 /**
- * Class preserving Excel XML data of unknown format.
- * Maintains original data without loss.
+ * 알 수 없는 형식의 Excel XML 데이터를 보존하는 클래스.
+ * 원본 데이터를 손실 없이 유지한다.
  */
 export class ExcelXmlUnknown implements ExcelXml {
   constructor(public readonly data: Record<string, unknown>) {}

package/src/xml/excel-xml-workbook.ts

@@ -3,8 +3,8 @@ import { num } from "@simplysm/core-common";
 import type { ExcelXml, ExcelXmlWorkbookData } from "../types";
 
 /**
- * Class managing xl/workbook.xml.
- * Handles the worksheet list and relationship IDs.
+ * xl/workbook.xml을 관리하는 클래스.
+ * 워크시트 목록 및 관계 ID를 처리한다.
  */
 export class ExcelXmlWorkbook implements ExcelXml {
   data: ExcelXmlWorkbookData;
@@ -31,6 +31,13 @@ export class ExcelXmlWorkbook implements ExcelXml {
     return maxSheet ? num.parseInt(maxSheet.$["r:id"]) : undefined;
   }
 
+  get lastSheetId(): number | undefined {
+    const sheets = this.data.workbook.sheets?.[0].sheet;
+    if (!sheets || sheets.length === 0) return undefined;
+    const maxSheet = sheets.orderByDesc((sheet) => num.parseInt(sheet.$.sheetId)!).first();
+    return maxSheet ? num.parseInt(maxSheet.$.sheetId) : undefined;
+  }
+
   get sheetNames(): string[] {
     return this.data.workbook.sheets?.[0].sheet.map((item) => item.$.name) ?? [];
   }
@@ -39,12 +46,13 @@ export class ExcelXmlWorkbook implements ExcelXml {
     const replacedName = this._getReplacedName(name);
 
     const newWsRelId = (this.lastWsRelId ?? 0) + 1;
+    const newSheetId = (this.lastSheetId ?? 0) + 1;
 
     this.data.workbook.sheets = this.data.workbook.sheets ?? [{ sheet: [] }];
     this.data.workbook.sheets[0].sheet.push({
       $: {
         "name": replacedName,
-        "sheetId": newWsRelId.toString(),
+        "sheetId": newSheetId.toString(),
         "r:id": `rId${newWsRelId}`,
       },
     });
@@ -55,7 +63,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   cleanup(): void {
     const result = {} as ExcelXmlWorkbookData["workbook"];
 
-    // Sort order (around "sheets", keep others in original position)
+    // 정렬 순서 ("sheets" 기준, 나머지는 원래 위치 유지)
 
     const workbookRec = this.data.workbook as Record<string, unknown>;
     const resultRec = result as Record<string, unknown>;
@@ -99,7 +107,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   setWorksheetNameById(id: number, newName: string): void {
     const sheetData = this._getSheetDataById(id);
     if (sheetData == null) {
-      throw new Error(`Cannot find worksheet ID ${id}`);
+      throw new Error(`워크시트 ID ${id}를 찾을 수 없습니다`);
     }
     const replacedName = this._getReplacedName(newName);
     sheetData.$.name = replacedName;
@@ -112,7 +120,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   }
 
   private _getReplacedName(name: string): string {
-    //-- Replace invalid sheet name characters with "_"
+    //-- 잘못된 시트 이름 문자를 "_"로 대체
     return name.replace(/[:\\/?*\[\]']/g, "_");
   }
 }