@simplysm/excel 13.0.69 → 13.0.71

package/src/utils/excel-utils.ts

@@ -2,26 +2,26 @@ import { numParseInt } from "@simplysm/core-common";
 import type { ExcelAddressPoint, ExcelAddressRangePoint, ExcelNumberFormat } from "../types";
 
 /**
- * Excel 관련 유틸리티 함수 모음.
- * 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 등의 기능을 제공한다.
+ * Collection of Excel utility functions.
+ * Provides cell address conversion, date/number conversion, and number format processing.
  */
 export class ExcelUtils {
-  /** 셀 좌표를 "A1" 형식 문자열로 변환 */
+  /** Convert cell coordinates to "A1" format string */
   static stringifyAddr(point: ExcelAddressPoint): string {
     const rowStr = this.stringifyRowAddr(point.r);
     const colStr = this.stringifyColAddr(point.c);
     return `${colStr}${rowStr}`;
   }
 
-  /** 행 인덱스(0-based)를 행 주소 문자열로 변환 (예: 0 -> "1") */
+  /** Convert row index (0-based) to row address string (e.g. 0 -> "1") */
   static stringifyRowAddr(r: number): string {
     return (r + 1).toString();
   }
 
-  /** 열 인덱스(0-based)를 열 주소 문자열로 변환 (예: 0 -> "A", 26 -> "AA") */
+  /** Convert column index (0-based) to column address string (e.g. 0 -> "A", 26 -> "AA") */
   static stringifyColAddr(c: number): string {
     if (c < 0 || c > 16383) {
-      throw new Error(`열 인덱스는 0~16383 범위여야 합니다: ${c}`);
+      throw new Error(`Column index must be in range 0~16383: ${c}`);
     }
 
     let remained = c;
@@ -34,17 +34,17 @@ export class ExcelUtils {
     return result;
   }
 
-  /** 셀 주소에서 행 인덱스 추출 (예: "A3" -> 2) */
+  /** Extract row index from cell address (e.g. "A3" -> 2) */
   static parseRowAddrCode(addrCode: string): number {
     const rowAddrCode = /\d*$/.exec(addrCode)?.[0] ?? "";
     const parsed = numParseInt(rowAddrCode);
     if (parsed == null) {
-      throw new Error(`잘못된 행 주소 코드: ${addrCode}`);
+      throw new Error(`Invalid row address code: ${addrCode}`);
     }
     return parsed - 1;
   }
 
-  /** 셀 주소에서 열 인덱스 추출 (예: "B3" -> 1) */
+  /** Extract column index from cell address (e.g. "B3" -> 1) */
   static parseColAddrCode(addrCode: string): number {
     const colAddrCode = /^[a-zA-Z]*/.exec(addrCode)?.[0] ?? "";
 
@@ -57,7 +57,7 @@ export class ExcelUtils {
     return result;
   }
 
-  /** 셀 주소를 좌표로 변환 (예: "B3" -> {r: 2, c: 1}) */
+  /** Convert cell address to coordinates (e.g. "B3" -> {r: 2, c: 1}) */
   static parseCellAddrCode(addr: string): ExcelAddressPoint {
     return {
       r: ExcelUtils.parseRowAddrCode(addr),
@@ -65,7 +65,7 @@ export class ExcelUtils {
     };
   }
 
-  /** 범위 주소를 좌표로 변환 (예: "A1:C3" -> {s: {r:0,c:0}, e: {r:2,c:2}}) */
+  /** Convert range address to coordinates (e.g. "A1:C3" -> {s: {r:0,c:0}, e: {r:2,c:2}}) */
   static parseRangeAddrCode(rangeAddr: string): ExcelAddressRangePoint {
     const parts = rangeAddr.split(":");
     return {
@@ -74,7 +74,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 +87,8 @@ export class ExcelUtils {
   }
 
   /**
-   * JavaScript 타임스탬프(ms)를 Excel 날짜 숫자로 변환.
-   * Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
+   * Convert JavaScript timestamp (ms) to Excel date number.
+   * Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
    */
   static convertTimeTickToNumber(tick: number): number {
     const currDate = new Date(tick);
@@ -99,8 +99,8 @@ export class ExcelUtils {
   }
 
   /**
-   * Excel 날짜 숫자를 JavaScript 타임스탬프(ms)로 변환.
-   * Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
+   * Convert Excel date number to JavaScript timestamp (ms).
+   * Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
    */
   static convertNumberToTimeTick(num: number): number {
     const excelBaseDateNumberUtc = Date.UTC(1899, 11, 31);
@@ -111,7 +111,7 @@ export class ExcelUtils {
     return date.getTime();
   }
 
-  /** 숫자 형식 코드를 형식 이름으로 변환 */
+  /** Convert number format code to format name */
   static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat {
     if (numFmtCode === "General") {
       return "number";
@@ -121,40 +121,40 @@ export class ExcelUtils {
     const hasTime = /hh/i.test(numFmtCode) || /ss/i.test(numFmtCode);
 
     if (hasDate && hasTime) {
-      return "DateTime"; // 날짜+시간 = DateTime
+      return "DateTime"; // date+time = DateTime
     } else if (hasDate) {
-      return "DateOnly"; // 날짜만 = DateOnly
+      return "DateOnly"; // date only = DateOnly
     } else if (hasTime) {
-      return "Time"; // 시간만 = Time
+      return "Time"; // time only = Time
     }
-    // 숫자 형식 패턴: 0, #, 소수점, 천단위 구분자, 음수 구분자, 괄호, 통화, 공백, 지수, 백분율 등
-    // "[조건부 서식]실제형식" 구조에서 실제형식 부분만 검사 (split("]").at(-1))
+    // 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))
     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(`[numFmtCode: ${numFmtCode}]에 대한 형식을 알 수 없습니다.`);
+      throw new Error(`Unknown format for [numFmtCode: ${numFmtCode}].`);
     }
   }
 
   /**
-   * 숫자 형식 ID를 형식 이름으로 변환
+   * Convert number format ID to format name
    *
    * @remarks
-   * Excel 내장 형식 ID 범위:
-   * - 0~13, 37~40, 48: 숫자/일반/통화/백분율 형식
-   * - 14~17, 27~31, 34~36, 50~58: 날짜 형식 (지역화 포함)
-   * - 22: 날짜+시간 형식
-   * - 18~21, 32~33, 45~47: 시간 형식
-   * - 49: 텍스트 형식
+   * 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
    */
   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 +163,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 +175,15 @@ export class ExcelUtils {
     ) {
       return "Time";
     }
-    // 텍스트 형식
+    // Text format
     else if (numFmtId === 49) {
       return "string";
     } else {
-      throw new Error(`[numFmtId: ${numFmtId}]에 대한 형식을 알 수 없습니다.`);
+      throw new Error(`Unknown format for [numFmtId: ${numFmtId}].`);
     }
   }
 
-  /** 숫자 형식 이름을 형식 ID로 변환 */
+  /** Convert number format name to format ID */
   static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number {
     if (numFmtName === "number") {
       return 0;
@@ -194,7 +194,7 @@ export class ExcelUtils {
     } else if (numFmtName === "Time") {
       return 18;
     } else {
-      // 마지막 케이스: "string" (TypeScript가 타입 좁히기를 통해 자동으로 확인)
+      // Last case: "string" (TypeScript verifies automatically through type narrowing)
       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";
 
 /**
- * Excel ZIP 아카이브의 파일 캐시를 관리하는 클래스.
- * XML 파일은 파싱하여 ExcelXml 객체로, 그 외 파일은 바이트 배열로 캐싱한다.
+ * Class managing file cache for Excel ZIP archives.
+ * XML files are parsed into ExcelXml objects; other files are cached as byte arrays.
  *
  * @remarks
- * ## Lazy Loading 캐시 전략
+ * ## Lazy Loading Cache Strategy
  *
- * - 파일은 첫 접근 시에만 ZIP에서 읽고 파싱한다
- * - 이후 접근은 캐시된 객체를 반환한다
- * - 대용량 Excel 파일에서 필요한 부분만 로드하여 메모리 효율성을 높인다
+ * - 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
  */
 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";
 
 /**
- * [Content_Types].xml 파일을 관리하는 클래스.
- * 파일별 MIME 타입 정보를 관리한다.
+ * Class managing [Content_Types].xml.
+ * Manages MIME type information per file.
  */
 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";
 
 /**
- * xl/drawings/drawing*.xml 파일을 관리하는 클래스.
- * 이미지 삽입 시 위치 및 참조 정보를 처리한다.
+ * Class managing xl/drawings/drawing*.xml files.
+ * Handles position and reference information for image insertion.
  */
 export class ExcelXmlDrawing implements ExcelXml {
   data: ExcelXmlDrawingData;

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

@@ -3,8 +3,8 @@ import { numParseInt } from "@simplysm/core-common";
 import type { ExcelRelationshipData, ExcelXml, ExcelXmlRelationshipData } from "../types";
 
 /**
- * *.rels 파일을 관리하는 클래스.
- * 파일 간의 참조 관계를 처리한다.
+ * Class managing *.rels files.
+ * Handles reference relationships between files.
  */
 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(`잘못된 관계 ID 형식입니다: ${rel.$.Id}`);
+      throw new Error(`Invalid relationship ID format: ${rel.$.Id}`);
     }
     return numParseInt(match[0])!;
   }

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

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

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

@@ -21,8 +21,8 @@ export interface ExcelStyle {
 }
 
 /**
- * xl/styles.xml 파일을 관리하는 클래스.
- * 숫자 형식, 배경색, 테두리, 정렬 등의 스타일을 처리한다.
+ * Class managing xl/styles.xml.
+ * Handles styles such as number formats, background colors, borders, and alignment.
  */
 export class ExcelXmlStyle implements ExcelXml {
   data: ExcelXmlStyleData;
@@ -108,11 +108,11 @@ export class ExcelXmlStyle implements ExcelXml {
   addWithClone(id: string, style: ExcelStyle): string {
     const idNum = numParseInt(id);
     if (idNum == null) {
-      throw new Error(`잘못된 스타일 ID: ${id}`);
+      throw new Error(`Invalid style ID: ${id}`);
     }
     const xfArray = this.data.styleSheet.cellXfs[0].xf;
     if (idNum < 0 || idNum >= xfArray.length) {
-      throw new Error(`존재하지 않는 스타일 ID: ${id} (범위: 0-${xfArray.length - 1})`);
+      throw new Error(`Non-existent style ID: ${id} (Range: 0-${xfArray.length - 1})`);
     }
     const prevXf = xfArray[idNum];
     const cloneXf = objClone(prevXf);
@@ -187,7 +187,7 @@ export class ExcelXmlStyle implements ExcelXml {
   get(id: string): ExcelStyle {
     const idNum = numParseInt(id);
     if (idNum == null) {
-      throw new Error(`잘못된 스타일 ID: ${id}`);
+      throw new Error(`Invalid style 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(
-              `존재하지 않는 fill ID: ${xf.$.fillId} (범위: 0-${this.data.styleSheet.fills[0].fill.length - 1})`,
+              `Non-existent fill ID: ${xf.$.fillId} (Range: 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 = numParseInt(xf.$.borderId);
         if (borderIdNum == null) {
-          throw new Error(`잘못된 border ID: ${xf.$.borderId}`);
+          throw new Error(`Invalid border ID: ${xf.$.borderId}`);
         }
         const border = this.data.styleSheet.borders[0].border[borderIdNum] as
           | ExcelXmlStyleDataBorder
           | undefined;
         if (border == null) {
           throw new Error(
-            `존재하지 않는 border ID: ${xf.$.borderId} (범위: 0-${this.data.styleSheet.borders[0].border.length - 1})`,
+            `Non-existent border ID: ${xf.$.borderId} (Range: 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"];
 
-    // 순서 정렬 (numFmts 맨위로)
+    // Sort order (numFmts first)
 
     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 {
-    // 이미 해당 code가 있으면 넘기기
+    // 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 사용자 정의 숫자 형식은 ID 180 이상부터 시작한다 (0-163: 내장 형식, 164-179: 예약됨)
+    // Excel custom number formats start from ID 180+ (0-163: built-in, 164-179: reserved)
     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";
 
 /**
- * 알 수 없는 형식의 Excel XML 데이터를 보존하는 클래스.
- * 원본 데이터를 손실 없이 유지한다.
+ * Class preserving Excel XML data of unknown format.
+ * Maintains original data without loss.
  */
 export class ExcelXmlUnknown implements ExcelXml {
   constructor(public readonly data: Record<string, unknown>) {}

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

@@ -3,8 +3,8 @@ import { numParseInt } from "@simplysm/core-common";
 import type { ExcelXml, ExcelXmlWorkbookData } from "../types";
 
 /**
- * xl/workbook.xml 파일을 관리하는 클래스.
- * 워크시트 목록과 관계 ID를 처리한다.
+ * Class managing xl/workbook.xml.
+ * Handles the worksheet list and relationship IDs.
  */
 export class ExcelXmlWorkbook implements ExcelXml {
   data: ExcelXmlWorkbookData;
@@ -55,7 +55,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   cleanup(): void {
     const result = {} as ExcelXmlWorkbookData["workbook"];
 
-    // 순서 정렬 ("sheets"기준 앞뒤로, 나머지는 원래위치대로)
+    // Sort order (around "sheets", keep others in original position)
 
     const workbookRec = this.data.workbook as Record<string, unknown>;
     const resultRec = result as Record<string, unknown>;
@@ -99,7 +99,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   setWorksheetNameById(id: number, newName: string): void {
     const sheetData = this._getSheetDataById(id);
     if (sheetData == null) {
-      throw new Error(`워크시트 ID ${id}를 찾을 수 없습니다`);
+      throw new Error(`Cannot find worksheet ID ${id}`);
     }
     const replacedName = this._getReplacedName(newName);
     sheetData.$.name = replacedName;
@@ -112,7 +112,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   }
 
   private _getReplacedName(name: string): string {
-    //-- 시트명칭 사용불가 텍스트를 "_"로 변환
+    //-- Replace invalid sheet name characters with "_"
     return name.replace(/[:\\/?*\[\]']/g, "_");
   }
 }