@simplysm/excel 13.0.69 → 13.0.71

package/src/excel-cell.ts

@@ -18,23 +18,23 @@ import { ExcelXmlStyle as ExcelXmlStyleClass } from "./xml/excel-xml-style";
 import { ExcelUtils } from "./utils/excel-utils";
 
 /**
- * Excel 셀을 나타내는 클래스.
- * 값 읽기/쓰기, 수식 설정, 스타일 설정, 셀 병합 등의 기능을 제공한다.
+ * Class representing an Excel cell.
+ * Provides value read/write, formula, style, and cell merge functionality.
  *
  * @remarks
- * ## 비동기 메서드 설계
+ * ## Async Method Design
  *
- * `getVal()`, `setVal()` 등 모든 셀 메서드가 `async`인 이유:
- * - 셀 타입에 따라 필요한 XML만 선택적으로 로드한다
- * - 문자열 셀: SharedStrings.xml 로드
- * - 숫자 셀: SharedStrings 로드 안함
- * - 스타일이 있는 셀: Styles.xml 로드
+ * Why all cell methods like `getVal()`, `setVal()` are `async`:
+ * - Only the XML needed for the cell type is selectively loaded
+ * - String cell: loads SharedStrings.xml
+ * - Number cell: does not load SharedStrings
+ * - Styled cell: loads Styles.xml
  *
- * 어떤 셀을 읽을지 미리 알 수 없기 때문에 동기 구조로는 구현할 수 없다.
- * 동기 구조로 만들려면 모든 XML을 미리 로드해야 하므로 대용량 파일에서 메모리 문제가 발생한다.
+ * Since the cell to be read cannot be known in advance, a synchronous design is not feasible.
+ * A synchronous design would require preloading all XML, causing memory issues with large files.
  */
 export class ExcelCell {
-  /** 셀 주소 (0-based 행/열 인덱스) */
+  /** Cell address (0-based row/column index) */
   readonly addr: ExcelAddressPoint;
 
   constructor(
@@ -48,7 +48,7 @@ export class ExcelCell {
 
   //#region Value Methods
 
-  /** 셀에 수식 설정 (undefined: 수식 삭제) */
+  /** Set formula on cell (undefined: remove formula) */
   async setFormula(val: string | undefined): Promise<void> {
     if (val === undefined) {
       await this._deleteCell(this.addr);
@@ -60,13 +60,13 @@ export class ExcelCell {
     }
   }
 
-  /** 셀의 수식 반환 */
+  /** Return cell formula */
   async getFormula(): Promise<string | undefined> {
     const wsData = await this._getWsData();
     return wsData.getCellFormula(this.addr);
   }
 
-  /** 셀 값 설정 (undefined: 셀 삭제) */
+  /** Set cell value (undefined: delete cell) */
   async setVal(val: ExcelValueType): Promise<void> {
     if (val === undefined) {
       await this._deleteCell(this.addr);
@@ -102,12 +102,12 @@ export class ExcelCell {
       });
     } else {
       throw new Error(
-        `[${ExcelUtils.stringifyAddr(this.addr)}] 지원되지 않는 타입입니다: ${typeof val}`,
+        `[${ExcelUtils.stringifyAddr(this.addr)}] Unsupported type: ${typeof val}`,
       );
     }
   }
 
-  /** 셀 값 반환 */
+  /** Return cell value */
   async getVal(): Promise<ExcelValueType> {
     const wsData = await this._getWsData();
     const cellVal = wsData.getCellVal(this.addr);
@@ -121,7 +121,7 @@ export class ExcelCell {
       const ssId = numParseInt(cellVal);
       if (ssId == null) {
         throw new Error(
-          `[${ExcelUtils.stringifyAddr(this.addr)}] SharedString ID 파싱 실패: ${cellVal}`,
+          `[${ExcelUtils.stringifyAddr(this.addr)}] Failed to parse SharedString ID: ${cellVal}`,
         );
       }
       return ssData.getStringById(ssId);
@@ -135,10 +135,10 @@ export class ExcelCell {
       return parseFloat(cellVal);
     } else if (cellType === "e") {
       throw new Error(
-        `[${ExcelUtils.stringifyAddr(this.addr)}] 셀 타입 분석 실패: 셀에 에러 값이 포함되어 있습니다 (${cellVal})`,
+        `[${ExcelUtils.stringifyAddr(this.addr)}] Cell type analysis failed: cell contains error value (${cellVal})`,
       );
     } else {
-      // cellType === undefined: 숫자 또는 날짜/시간 타입
+      // cellType === undefined: number or date/time type
       const cellStyleId = wsData.getCellStyleId(this.addr);
       if (cellStyleId === undefined) {
         return parseFloat(cellVal);
@@ -162,7 +162,7 @@ export class ExcelCell {
         const numFmtIdNum = numParseInt(numFmtId);
         if (numFmtIdNum == null) {
           throw new Error(
-            `[${ExcelUtils.stringifyAddr(this.addr)}] numFmtId 파싱 실패: ${numFmtId}`,
+            `[${ExcelUtils.stringifyAddr(this.addr)}] Failed to parse numFmtId: ${numFmtId}`,
           );
         }
         numFmt = ExcelUtils.convertNumFmtIdToName(numFmtIdNum);
@@ -177,7 +177,7 @@ export class ExcelCell {
         const dateNum = numParseFloat(cellVal);
         if (dateNum == null) {
           throw new Error(
-            `[${ExcelUtils.stringifyAddr(this.addr)}] 날짜 숫자 파싱 실패: ${cellVal}`,
+            `[${ExcelUtils.stringifyAddr(this.addr)}] Failed to parse date number: ${cellVal}`,
           );
         }
         const tick = ExcelUtils.convertNumberToTimeTick(dateNum);
@@ -197,11 +197,11 @@ export class ExcelCell {
   //#region Merge Methods
 
   /**
-   * 현재 셀부터 지정된 끝 좌표까지 셀 병합
-   * @param r 병합 끝 행 인덱스 (0-based)
-   * @param c 병합 끝 열 인덱스 (0-based)
+   * Merge cells from current cell to the specified end coordinates
+   * @param r End row index of merge (0-based)
+   * @param c End column index of merge (0-based)
    * @example
-   * // A1 셀에서 호출하면 A1:C3 범위 (3행 x 3열)를 병합
+   * // Called from cell A1, merges range A1:C3 (3 rows x 3 columns)
    * await ws.cell(0, 0).merge(2, 2);
    */
   async merge(r: number, c: number): Promise<void> {
@@ -213,33 +213,33 @@ export class ExcelCell {
 
   //#region Style Methods
 
-  /** 셀의 스타일 ID 반환 */
+  /** Return cell style ID */
   async getStyleId(): Promise<string | undefined> {
     const wsData = await this._getWsData();
     return wsData.getCellStyleId(this.addr);
   }
 
-  /** 셀의 스타일 ID 설정 */
+  /** Set cell style ID */
   async setStyleId(styleId: string | undefined): Promise<void> {
     const wsData = await this._getWsData();
     wsData.setCellStyleId(this.addr, styleId);
   }
 
   /**
-   * 셀 스타일 설정
-   * @param opts 스타일 옵션
-   * @param opts.background 배경색 (ARGB 형식, 8자리 16진수. 예: "FFFF0000")
-   * @param opts.border 테두리 위치 배열 (예: ["left", "right", "top", "bottom"])
-   * @param opts.horizontalAlign 가로 정렬 ("left", "center", "right")
-   * @param opts.verticalAlign 세로 정렬 ("top", "center", "bottom")
-   * @param opts.numberFormat 숫자 형식 ("number", "DateOnly", "DateTime", "Time", "string")
+   * Set cell style
+   * @param opts Style options
+   * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "FFFF0000")
+   * @param opts.border Border position array (e.g. ["left", "right", "top", "bottom"])
+   * @param opts.horizontalAlign Horizontal alignment ("left", "center", "right")
+   * @param opts.verticalAlign Vertical alignment ("top", "center", "bottom")
+   * @param opts.numberFormat Number format ("number", "DateOnly", "DateTime", "Time", "string")
    */
   async setStyle(opts: ExcelStyleOptions): Promise<void> {
     const style: ExcelStyle = {};
 
     if (opts.background != null) {
       if (!/^[0-9A-F]{8}$/i.test(opts.background)) {
-        throw new Error("색상 형식이 잘못되었습니다. (형식: 00000000: alpha(역)+rgb)");
+        throw new Error("Invalid color format. (Format: 00000000: alpha(reversed)+rgb)");
       }
       style.background = opts.background;
     }

package/src/excel-col.ts

@@ -3,7 +3,7 @@ import { ExcelCell } from "./excel-cell";
 import type { ExcelXmlWorksheet } from "./xml/excel-xml-worksheet";
 import type { ZipCache } from "./utils/zip-cache";
 
-/** Excel 워크시트의 열을 나타내는 클래스. 셀 접근 및 열 너비 설정 기능을 제공한다. */
+/** Class representing a column in an Excel worksheet. Provides cell access and column width configuration. */
 export class ExcelCol {
   private readonly _cellMap = new Map<number, ExcelCell>();
 
@@ -13,7 +13,7 @@ export class ExcelCol {
     private readonly _c: number,
   ) {}
 
-  /** 행 인덱스에 해당하는 셀 반환 (0-based) */
+  /** Return cell at the given row index (0-based) */
   cell(r: number): ExcelCell {
     return this._cellMap.getOrCreate(
       r,
@@ -21,7 +21,7 @@ export class ExcelCol {
     );
   }
 
-  /** 열의 모든 셀 반환 */
+  /** Return all cells in the column */
   async getCells(): Promise<ExcelCell[]> {
     const result: ExcelCell[] = [];
     const wsData = await this._getWsData();
@@ -34,7 +34,7 @@ export class ExcelCol {
     return result;
   }
 
-  /** 열 너비 설정 */
+  /** Set column width */
   async setWidth(size: number): Promise<void> {
     const wsData = await this._getWsData();
     wsData.setColWidth((this._c + 1).toString(), size.toString());

package/src/excel-row.ts

@@ -3,7 +3,7 @@ import { ExcelCell } from "./excel-cell";
 import type { ExcelXmlWorksheet } from "./xml/excel-xml-worksheet";
 import type { ZipCache } from "./utils/zip-cache";
 
-/** Excel 워크시트의 행을 나타내는 클래스. 셀 접근 기능을 제공한다. */
+/** Class representing a row in an Excel worksheet. Provides cell access functionality. */
 export class ExcelRow {
   private readonly _cellMap = new Map<number, ExcelCell>();
 
@@ -13,7 +13,7 @@ export class ExcelRow {
     private readonly _r: number,
   ) {}
 
-  /** 열 인덱스에 해당하는 셀 반환 (0-based) */
+  /** Return cell at the given column index (0-based) */
   cell(c: number): ExcelCell {
     return this._cellMap.getOrCreate(
       c,
@@ -21,7 +21,7 @@ export class ExcelRow {
     );
   }
 
-  /** 행의 모든 셀 반환 */
+  /** Return all cells in the row */
   async getCells(): Promise<ExcelCell[]> {
     const result: ExcelCell[] = [];
     const wsData = await this._getWsData();

package/src/excel-workbook.ts

@@ -8,32 +8,32 @@ import { ExcelXmlWorkbook as ExcelXmlWorkbookClass } from "./xml/excel-xml-workb
 import { ExcelXmlWorksheet as ExcelXmlWorksheetClass } from "./xml/excel-xml-worksheet";
 
 /**
- * Excel 워크북 처리 클래스
+ * Excel workbook processing class
  *
  * @remarks
- * 이 클래스는 내부적으로 ZIP 리소스를 관리합니다.
- * 사용 완료 후 반드시 리소스를 해제해야 합니다.
+ * This class internally manages ZIP resources.
+ * Resources must be released after use.
  *
- * ## 비동기 설계
+ * ## Async Design
  *
- * 대용량 Excel 파일의 메모리 효율성을 위해 Lazy Loading 구조를 채택합니다:
- * - ZIP 파일 내부의 XML은 접근 시점에만 읽고 파싱한다
- * - SharedStrings, Styles 등 대용량 XML은 필요할 때만 로드한다
- * - 극단적 케이스(예: SharedStrings가 1TB인 파일에서 숫자 셀 하나만 읽기)에서도 메모리 효율적이다
+ * Adopts a Lazy Loading architecture for memory efficiency with large Excel files:
+ * - XML inside the ZIP is read and parsed only at the point of access
+ * - Large XML such as SharedStrings and Styles is loaded only when needed
+ * - Memory efficient even in extreme cases (e.g., reading a single number cell from a file with 1TB SharedStrings)
  *
  * @example
  * ```typescript
- * // await using 사용 (권장)
+ * // Using await using (recommended)
  * await using wb = new ExcelWorkbook(bytes);
  * const ws = await wb.getWorksheet(0);
- * // ... 작업 수행
- * // 스코프 종료 시 자동으로 리소스 해제
+ * // ... perform operations
+ * // Resources automatically released at scope exit
  *
- * // 또는 try-finally 사용
+ * // Or using try-finally
  * const wb = new ExcelWorkbook(bytes);
  * try {
  *   const ws = await wb.getWorksheet(0);
- *   // ... 작업 수행
+ *   // ... perform operations
  * } finally {
  *   await wb.close();
  * }
@@ -45,7 +45,7 @@ export class ExcelWorkbook {
   private _isClosed = false;
 
   /**
-   * @param arg 기존 Excel 파일 데이터 (Blob 또는 Uint8Array). 생략 시 새 워크북을 생성한다.
+   * @param arg Existing Excel file data (Blob or Uint8Array). Creates a new workbook if omitted.
    */
   constructor(arg?: Blob | Bytes) {
     if (arg != null) {
@@ -80,18 +80,18 @@ export class ExcelWorkbook {
 
   private _ensureNotClosed(): void {
     if (this._isClosed) {
-      throw new Error("ExcelWorkbook이 이미 닫혔습니다. close() 호출 후에는 사용할 수 없습니다.");
+      throw new Error("ExcelWorkbook is already closed. Cannot use after calling close().");
     }
   }
 
-  /** 워크북의 모든 워크시트 이름을 반환 */
+  /** Return all worksheet names in the workbook */
   async getWorksheetNames(): Promise<string[]> {
     this._ensureNotClosed();
     const wbData = (await this.zipCache.get("xl/workbook.xml")) as ExcelXmlWorkbook;
     return wbData.sheetNames;
   }
 
-  /** 새 워크시트를 생성하고 반환 */
+  /** Create and return a new worksheet */
   async createWorksheet(name: string): Promise<ExcelWorksheet> {
     this._ensureNotClosed();
     // Workbook
@@ -124,7 +124,7 @@ export class ExcelWorkbook {
     return ws;
   }
 
-  /** 이름 또는 인덱스(0-based)로 워크시트를 조회 */
+  /** Look up a worksheet by name or index (0-based) */
   async getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet> {
     this._ensureNotClosed();
     const wbData = (await this.zipCache.get("xl/workbook.xml")) as ExcelXmlWorkbook;
@@ -135,9 +135,9 @@ export class ExcelWorkbook {
 
     if (wsId === undefined) {
       if (typeof nameOrIndex === "string") {
-        throw new Error(`시트명이 '${nameOrIndex}'인 시트를 찾을 수 없습니다.`);
+        throw new Error(`Cannot find sheet with name '${nameOrIndex}'.`);
       } else {
-        throw new Error(`'${nameOrIndex}'번째 시트를 찾을 수 없습니다.`);
+        throw new Error(`Cannot find sheet at index '${nameOrIndex}'.`);
       }
     }
 
@@ -148,13 +148,13 @@ export class ExcelWorkbook {
     const relData = (await this.zipCache.get("xl/_rels/workbook.xml.rels")) as ExcelXmlRelationship;
     const targetFilePath = relData.getTargetByRelId(wsId);
     if (targetFilePath == null) {
-      throw new Error(`시트 관계 정보를 찾을 수 없습니다: rId${wsId}`);
+      throw new Error(`Cannot find sheet relationship information: rId${wsId}`);
     }
 
-    // path.basename 대신 직접 파일명 추출 (브라우저 호환성)
+    // Extract filename directly instead of path.basename (browser compatibility)
     const fileName = targetFilePath.split("/").pop();
     if (fileName == null) {
-      throw new Error(`시트 파일명을 추출할 수 없습니다: ${targetFilePath}`);
+      throw new Error(`Cannot extract sheet filename: ${targetFilePath}`);
     }
 
     const ws = new ExcelWorksheet(this.zipCache, wsId, fileName);
@@ -166,13 +166,13 @@ export class ExcelWorkbook {
 
   //#region Export Methods
 
-  /** 워크북을 바이트 배열로 출력 */
+  /** Export workbook as byte array */
   async getBytes(): Promise<Bytes> {
     this._ensureNotClosed();
     return this.zipCache.toBytes();
   }
 
-  /** 워크북을 Blob으로 출력 */
+  /** Export workbook as Blob */
   async getBlob(): Promise<Blob> {
     this._ensureNotClosed();
     const bytes = await this.zipCache.toBytes();
@@ -186,16 +186,16 @@ export class ExcelWorkbook {
   //#region Lifecycle Methods
 
   /**
-   * 워크북 리소스 해제
+   * Release workbook resources
    *
    * @remarks
-   * ZIP 리더와 내부 캐시를 정리합니다.
-   * 호출 후에는 이 워크북 인스턴스를 사용할 수 없습니다.
-   * 이미 닫힌 워크북에 대해 호출해도 안전합니다 (no-op).
+   * Cleans up the ZIP reader and internal cache.
+   * The workbook instance cannot be used after this call.
+   * Safe to call on an already closed workbook (no-op).
    */
   async close(): Promise<void> {
     if (this._isClosed) {
-      return; // 이미 닫힌 경우 무시
+      return; // Ignore if already closed
     }
     this._isClosed = true;
     this._wsMap.clear();