@simplysm/excel 13.0.99 → 14.0.1

package/dist/excel-workbook.js

@@ -4,136 +4,162 @@ import { ExcelXmlContentType } from "./xml/excel-xml-content-type.js";
 import { ExcelXmlRelationship } from "./xml/excel-xml-relationship.js";
 import { ExcelXmlWorkbook as ExcelXmlWorkbookClass } from "./xml/excel-xml-workbook.js";
 import { ExcelXmlWorksheet as ExcelXmlWorksheetClass } from "./xml/excel-xml-worksheet.js";
-class ExcelWorkbook {
-  zipCache;
-  _wsMap = /* @__PURE__ */ new Map();
-  _isClosed = false;
-  /**
-   * @param arg Existing Excel file data (Blob or Uint8Array). Creates a new workbook if omitted.
-   */
-  constructor(arg) {
-    if (arg != null) {
-      this.zipCache = new ZipCache(arg);
-    } else {
-      this.zipCache = new ZipCache();
-      const typeXml = new ExcelXmlContentType();
-      this.zipCache.set("[Content_Types].xml", typeXml);
-      this.zipCache.set(
-        "_rels/.rels",
-        new ExcelXmlRelationship().add(
-          "xl/workbook.xml",
-          "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"
-        )
-      );
-      const wbXml = new ExcelXmlWorkbookClass();
-      this.zipCache.set("xl/workbook.xml", wbXml);
-      const wbRelXml = new ExcelXmlRelationship();
-      this.zipCache.set("xl/_rels/workbook.xml.rels", wbRelXml);
+/**
+ * Excel 워크북 처리 클래스
+ *
+ * @remarks
+ * 이 클래스는 내부적으로 ZIP 리소스를 관리한다.
+ * 사용 후 반드시 리소스를 해제해야 한다.
+ *
+ * ## 비동기 설계
+ *
+ * 대용량 Excel 파일의 메모리 효율을 위해 Lazy Loading 아키텍처를 채택:
+ * - ZIP 내부의 XML은 접근 시점에만 읽고 파싱함
+ * - SharedStrings, Styles 등 대용량 XML은 필요할 때만 로드함
+ * - 극단적인 경우에도 메모리 효율적 (예: 1TB SharedStrings가 있는 파일에서 숫자 셀 하나만 읽기)
+ *
+ * @example
+ * ```typescript
+ * // await using 사용 (권장)
+ * await using wb = new ExcelWorkbook(bytes);
+ * const ws = await wb.getWorksheet(0);
+ * // ... 작업 수행
+ * // 스코프 종료 시 리소스 자동 해제
+ *
+ * // 또는 try-finally 사용
+ * const wb = new ExcelWorkbook(bytes);
+ * try {
+ *   const ws = await wb.getWorksheet(0);
+ *   // ... 작업 수행
+ * } finally {
+ *   await wb.close();
+ * }
+ * ```
+ */
+export class ExcelWorkbook {
+    zipCache;
+    _wsMap = new Map();
+    _isClosed = false;
+    /**
+     * @param arg 기존 Excel 파일 데이터 (Blob 또는 Uint8Array). 생략하면 새 워크북을 생성한다.
+     */
+    constructor(arg) {
+        if (arg != null) {
+            this.zipCache = new ZipCache(arg);
+        }
+        else {
+            this.zipCache = new ZipCache();
+            // 전역 ContentTypes
+            const typeXml = new ExcelXmlContentType();
+            this.zipCache.set("[Content_Types].xml", typeXml);
+            // 전역 Rels
+            this.zipCache.set("_rels/.rels", new ExcelXmlRelationship().add("xl/workbook.xml", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"));
+            // 워크북
+            const wbXml = new ExcelXmlWorkbookClass();
+            this.zipCache.set("xl/workbook.xml", wbXml);
+            // 워크북 Rels
+            const wbRelXml = new ExcelXmlRelationship();
+            this.zipCache.set("xl/_rels/workbook.xml.rels", wbRelXml);
+        }
     }
-  }
-  //#region Worksheet Methods
-  _ensureNotClosed() {
-    if (this._isClosed) {
-      throw new Error("ExcelWorkbook is already closed. Cannot use after calling close().");
+    //#region Worksheet Methods
+    _ensureNotClosed() {
+        if (this._isClosed) {
+            throw new Error("ExcelWorkbook이 이미 닫혔습니다. close() 호출 후에는 사용할 수 없습니다.");
+        }
     }
-  }
-  /** Return all worksheet names in the workbook */
-  async getWorksheetNames() {
-    this._ensureNotClosed();
-    const wbData = await this.zipCache.get("xl/workbook.xml");
-    return wbData.sheetNames;
-  }
-  /** Create and return a new worksheet */
-  async addWorksheet(name) {
-    this._ensureNotClosed();
-    const wbXml = await this.zipCache.get("xl/workbook.xml");
-    const newWsRelId = wbXml.addWorksheet(name).lastWsRelId;
-    const typeXml = await this.zipCache.get("[Content_Types].xml");
-    typeXml.add(
-      `/xl/worksheets/sheet${newWsRelId}.xml`,
-      "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
-    );
-    const wbRelXml = await this.zipCache.get(
-      "xl/_rels/workbook.xml.rels"
-    );
-    wbRelXml.insert(
-      newWsRelId,
-      `worksheets/sheet${newWsRelId}.xml`,
-      "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
-    );
-    const wsXml = new ExcelXmlWorksheetClass();
-    this.zipCache.set(`xl/worksheets/sheet${newWsRelId}.xml`, wsXml);
-    const ws = new ExcelWorksheet(this.zipCache, newWsRelId, `sheet${newWsRelId}.xml`);
-    this._wsMap.set(newWsRelId, ws);
-    return ws;
-  }
-  /** Look up a worksheet by name or index (0-based) */
-  async getWorksheet(nameOrIndex) {
-    this._ensureNotClosed();
-    const wbData = await this.zipCache.get("xl/workbook.xml");
-    const wsId = typeof nameOrIndex === "string" ? wbData.getWsRelIdByName(nameOrIndex) : wbData.getWsRelIdByIndex(nameOrIndex);
-    if (wsId === void 0) {
-      if (typeof nameOrIndex === "string") {
-        throw new Error(`Cannot find sheet with name '${nameOrIndex}'.`);
-      } else {
-        throw new Error(`Cannot find sheet at index '${nameOrIndex}'.`);
-      }
+    /** 워크북의 모든 워크시트 이름 반환 */
+    async getWorksheetNames() {
+        this._ensureNotClosed();
+        const wbData = (await this.zipCache.get("xl/workbook.xml"));
+        return wbData.sheetNames;
     }
-    if (this._wsMap.has(wsId)) {
-      return this._wsMap.get(wsId);
+    /** 새 워크시트를 생성하여 반환 */
+    async addWorksheet(name) {
+        this._ensureNotClosed();
+        // 워크북
+        const wbXml = (await this.zipCache.get("xl/workbook.xml"));
+        const newWsRelId = wbXml.addWorksheet(name).lastWsRelId;
+        // Content Types 갱신
+        const typeXml = (await this.zipCache.get("[Content_Types].xml"));
+        typeXml.add(`/xl/worksheets/sheet${newWsRelId}.xml`, "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml");
+        // 워크북 Rels 갱신
+        const wbRelXml = (await this.zipCache.get("xl/_rels/workbook.xml.rels"));
+        wbRelXml.insert(newWsRelId, `worksheets/sheet${newWsRelId}.xml`, "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet");
+        // 워크시트
+        const wsXml = new ExcelXmlWorksheetClass();
+        this.zipCache.set(`xl/worksheets/sheet${newWsRelId}.xml`, wsXml);
+        const ws = new ExcelWorksheet(this.zipCache, newWsRelId, `sheet${newWsRelId}.xml`);
+        this._wsMap.set(newWsRelId, ws);
+        return ws;
     }
-    const relData = await this.zipCache.get("xl/_rels/workbook.xml.rels");
-    const targetFilePath = relData.getTargetByRelId(wsId);
-    if (targetFilePath == null) {
-      throw new Error(`Cannot find sheet relationship information: rId${wsId}`);
+    /** 이름 또는 인덱스(0 기반)로 워크시트 조회 */
+    async getWorksheet(nameOrIndex) {
+        this._ensureNotClosed();
+        const wbData = (await this.zipCache.get("xl/workbook.xml"));
+        const wsId = typeof nameOrIndex === "string"
+            ? wbData.getWsRelIdByName(nameOrIndex)
+            : wbData.getWsRelIdByIndex(nameOrIndex);
+        if (wsId === undefined) {
+            if (typeof nameOrIndex === "string") {
+                throw new Error(`이름이 '${nameOrIndex}'인 시트를 찾을 수 없습니다.`);
+            }
+            else {
+                throw new Error(`인덱스 '${nameOrIndex}'에 해당하는 시트를 찾을 수 없습니다.`);
+            }
+        }
+        if (this._wsMap.has(wsId)) {
+            return this._wsMap.get(wsId);
+        }
+        const relData = (await this.zipCache.get("xl/_rels/workbook.xml.rels"));
+        const targetFilePath = relData.getTargetByRelId(wsId);
+        if (targetFilePath == null) {
+            throw new Error(`시트 관계 정보를 찾을 수 없습니다: rId${wsId}`);
+        }
+        // path.basename 대신 직접 파일명 추출 (브라우저 호환성)
+        const fileName = targetFilePath.split("/").pop();
+        if (fileName == null) {
+            throw new Error(`시트 파일명을 추출할 수 없습니다: ${targetFilePath}`);
+        }
+        const ws = new ExcelWorksheet(this.zipCache, wsId, fileName);
+        this._wsMap.set(wsId, ws);
+        return ws;
     }
-    const fileName = targetFilePath.split("/").pop();
-    if (fileName == null) {
-      throw new Error(`Cannot extract sheet filename: ${targetFilePath}`);
+    //#endregion
+    //#region Export Methods
+    /** 워크북을 바이트 배열로 내보내기 */
+    async toBytes() {
+        this._ensureNotClosed();
+        return this.zipCache.toBytes();
     }
-    const ws = new ExcelWorksheet(this.zipCache, wsId, fileName);
-    this._wsMap.set(wsId, ws);
-    return ws;
-  }
-  //#endregion
-  //#region Export Methods
-  /** Export workbook as byte array */
-  async toBytes() {
-    this._ensureNotClosed();
-    return this.zipCache.toBytes();
-  }
-  /** Export workbook as Blob */
-  async toBlob() {
-    this._ensureNotClosed();
-    const bytes = await this.zipCache.toBytes();
-    return new Blob([new Uint8Array(bytes)], {
-      type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-    });
-  }
-  //#endregion
-  //#region Lifecycle Methods
-  /**
-   * Release workbook resources
-   *
-   * @remarks
-   * 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() {
-    if (this._isClosed) {
-      return;
+    /** 워크북을 Blob으로 내보내기 */
+    async toBlob() {
+        this._ensureNotClosed();
+        const bytes = await this.zipCache.toBytes();
+        return new Blob([new Uint8Array(bytes)], {
+            type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        });
+    }
+    //#endregion
+    //#region Lifecycle Methods
+    /**
+     * 워크북 리소스 해제
+     *
+     * @remarks
+     * ZIP 리더와 내부 캐시를 정리한다.
+     * 이 호출 이후에는 워크북 인스턴스를 사용할 수 없다.
+     * 이미 닫힌 워크북에 대해 호출해도 안전하다 (no-op).
+     */
+    async close() {
+        if (this._isClosed) {
+            return; // 이미 닫힌 경우 무시
+        }
+        this._isClosed = true;
+        this._wsMap.clear();
+        await this.zipCache.close();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
     }
-    this._isClosed = true;
-    this._wsMap.clear();
-    await this.zipCache.close();
-  }
-  async [Symbol.asyncDispose]() {
-    await this.close();
-  }
-  //#endregion
 }
-export {
-  ExcelWorkbook
-};
-//# sourceMappingURL=excel-workbook.js.map
+//# sourceMappingURL=excel-workbook.js.map

package/dist/excel-workbook.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../src/excel-workbook.ts"],
-  "mappings": "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",
-  "names": []
-}
+{"version":3,"file":"excel-workbook.js","sourceRoot":"","sources":["..\\src\\excel-workbook.ts"],"names":[],"mappings":"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"}

package/dist/excel-worksheet.d.ts

@@ -6,8 +6,8 @@ import { ExcelRow } from "./excel-row";
 import type { ExcelAddressPoint, ExcelAddressRangePoint, ExcelValueType } from "./types";
 import type { ZipCache } from "./utils/zip-cache";
 /**
- * Class representing an Excel worksheet.
- * Provides cell access, row/column copying, data table processing, and image insertion.
+ * Excel 워크시트를 나타내는 클래스.
+ * 셀 접근, 행/열 복사, 데이터 테이블 처리, 이미지 삽입 기능을 제공한다.
  */
 export declare class ExcelWorksheet {
     private readonly _zipCache;
@@ -16,40 +16,40 @@ export declare class ExcelWorksheet {
     private readonly _rowMap;
     private readonly _colMap;
     constructor(_zipCache: ZipCache, _relId: number, _targetFileName: string);
-    /** Return worksheet name */
+    /** 워크시트 이름 반환 */
     getName(): Promise<string>;
-    /** Rename worksheet */
+    /** 워크시트 이름 변경 */
     setName(newName: string): Promise<void>;
-    /** Return row object (0-based) */
+    /** 행 객체 반환 (0 기반) */
     row(r: number): ExcelRow;
-    /** Return cell object (0-based row/column) */
+    /** 셀 객체 반환 (0 기반 행/열) */
     cell(r: number, c: number): ExcelCell;
-    /** Return column object (0-based) */
+    /** 열 객체 반환 (0 기반) */
     col(c: number): ExcelCol;
-    /** Copy style from source row to target row */
+    /** 원본 행에서 대상 행으로 스타일 복사 */
     copyRowStyle(srcR: number, targetR: number): Promise<void>;
-    /** Copy style from source cell to target cell */
+    /** 원본 셀에서 대상 셀로 스타일 복사 */
     copyCellStyle(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
-    /** Copy source row to target row (overwrite) */
+    /** 원본 행을 대상 행으로 복사 (덮어쓰기) */
     copyRow(srcR: number, targetR: number): Promise<void>;
-    /** Copy source cell to target cell */
+    /** 원본 셀을 대상 셀로 복사 */
     copyCell(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
     /**
-     * Insert-copy the source row at the target position.
-     * Existing rows at and below the target are shifted down by one.
-     * @param srcR Source row index to copy (0-based)
-     * @param targetR Target row index to insert at (0-based)
+     * 원본 행을 대상 위치에 삽입 복사한다.
+     * 대상 위치 이하의 기존 행은 한 칸 아래로 밀린다.
+     * @param srcR 복사할 원본 행 인덱스 (0 기반)
+     * @param targetR 삽입할 대상 행 인덱스 (0 기반)
      */
     insertCopyRow(srcR: number, targetR: number): Promise<void>;
-    /** Return data range of the worksheet */
+    /** 워크시트의 데이터 범위 반환 */
     getRange(): Promise<ExcelAddressRangePoint>;
-    /** Return all cells as a 2D array */
+    /** 모든 셀을 2차원 배열로 반환 */
     getCells(): Promise<ExcelCell[][]>;
     /**
-     * Return worksheet data as a table (record array).
-     * @param opt.headerRowIndex Header row index (default: first row)
-     * @param opt.checkEndColIndex Column index to determine data end. Data ends when this column is empty.
-     * @param opt.usableHeaderNameFn Function to filter usable headers
+     * 워크시트 데이터를 테이블(레코드 배열)로 반환한다.
+     * @param opt.headerRowIndex 헤더 행 인덱스 (기본값: 첫 번째 행)
+     * @param opt.checkEndColIndex 데이터 끝을 판단할 열 인덱스. 이 열이 비어있으면 데이터가 끝난 것으로 판단한다.
+     * @param opt.usableHeaderNameFn 사용 가능한 헤더를 필터링하는 함수
      */
     getDataTable(opt?: {
         headerRowIndex?: number;
@@ -57,28 +57,28 @@ export declare class ExcelWorksheet {
         usableHeaderNameFn?: (headerName: string) => boolean;
     }): Promise<Record<string, ExcelValueType>[]>;
     /**
-     * Write 2D array data to the worksheet
-     * @param matrix 2D array data (row-major, index 0 is the first row)
+     * 2차원 배열 데이터를 워크시트에 쓰기
+     * @param matrix 2차원 배열 데이터 (행 우선, 인덱스 0이 첫 번째 행)
      */
     setDataMatrix(matrix: ExcelValueType[][]): Promise<void>;
     /**
-     * Write record array to the worksheet
-     * @param records Record array. Headers are auto-generated in the first row, data follows in subsequent rows.
+     * 레코드 배열을 워크시트에 쓰기
+     * @param records 레코드 배열. 첫 번째 행에 헤더가 자동 생성되고, 이후 행에 데이터가 기록된다.
      */
     setRecords(records: Record<string, ExcelValueType>[]): Promise<void>;
-    /** Set worksheet zoom scale (percent) */
+    /** 워크시트 확대/축소 비율 설정 (퍼센트) */
     setZoom(percent: number): Promise<void>;
-    /** Set freeze panes for rows/columns */
+    /** 행/열 틀 고정 설정 */
     freezeAt(point: {
         r?: number;
         c?: number;
     }): Promise<void>;
     /**
-     * Insert an image into the worksheet.
-     * @param opts.bytes Image binary data
-     * @param opts.ext Image extension (png, jpg, etc.)
-     * @param opts.from Image start position (0-based row/column index, rOff/cOff in EMU offset)
-     * @param opts.to Image end position (if omitted, inserted at from position with original size)
+     * 워크시트에 이미지를 삽입한다.
+     * @param opts.bytes 이미지 바이너리 데이터
+     * @param opts.ext 이미지 확장자 (png, jpg 등)
+     * @param opts.from 이미지 시작 위치 (0 기반 행/열 인덱스, rOff/cOff는 EMU 오프셋)
+     * @param opts.to 이미지 끝 위치 (생략 시 from 위치에 원본 크기로 삽입)
      */
     addImage(opts: {
         bytes: Bytes;

package/dist/excel-worksheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"excel-worksheet.d.ts","sourceRoot":"","sources":["..\\src\\excel-worksheet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"excel-worksheet.d.ts","sourceRoot":"","sources":["..\\src\\excel-worksheet.ts"],"names":[],"mappings":"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"}