@simplysm/excel 13.0.0-beta.45 → 13.0.0-beta.47

package/src/excel-cell.ts

@@ -0,0 +1,326 @@
+import type { ExcelXmlWorksheet } from "./xml/excel-xml-worksheet";
+import type { ExcelXmlContentType } from "./xml/excel-xml-content-type";
+import type { ExcelXmlRelationship } from "./xml/excel-xml-relationship";
+import type { ExcelXmlStyle, ExcelStyle } from "./xml/excel-xml-style";
+import type { ExcelXmlSharedString } from "./xml/excel-xml-shared-string";
+import type { ZipCache } from "./utils/zip-cache";
+import type { ExcelAddressPoint, ExcelStyleOptions, ExcelValueType } from "./types";
+import { DateOnly, DateTime, numParseFloat, numParseInt, strIsNullOrEmpty, Time } from "@simplysm/core-common";
+import { ExcelXmlSharedString as ExcelXmlSharedStringClass } from "./xml/excel-xml-shared-string";
+import { ExcelXmlStyle as ExcelXmlStyleClass } from "./xml/excel-xml-style";
+import { ExcelUtils } from "./utils/excel-utils";
+
+/**
+ * Excel 셀을 나타내는 클래스.
+ * 값 읽기/쓰기, 수식 설정, 스타일 설정, 셀 병합 등의 기능을 제공한다.
+ *
+ * @remarks
+ * ## 비동기 메서드 설계
+ *
+ * `getVal()`, `setVal()` 등 모든 셀 메서드가 `async`인 이유:
+ * - 셀 타입에 따라 필요한 XML만 선택적으로 로드한다
+ * - 문자열 셀: SharedStrings.xml 로드
+ * - 숫자 셀: SharedStrings 로드 안함
+ * - 스타일이 있는 셀: Styles.xml 로드
+ *
+ * 어떤 셀을 읽을지 미리 알 수 없기 때문에 동기 구조로는 구현할 수 없다.
+ * 동기 구조로 만들려면 모든 XML을 미리 로드해야 하므로 대용량 파일에서 메모리 문제가 발생한다.
+ */
+export class ExcelCell {
+  /** 셀 주소 (0-based 행/열 인덱스) */
+  readonly addr: ExcelAddressPoint;
+
+  constructor(
+    private readonly _zipCache: ZipCache,
+    private readonly _targetFileName: string,
+    private readonly _r: number,
+    private readonly _c: number,
+  ) {
+    this.addr = { r: this._r, c: this._c };
+  }
+
+  //#region Value Methods
+
+  /** 셀에 수식 설정 (undefined: 수식 삭제) */
+  async setFormula(val: string | undefined): Promise<void> {
+    if (val === undefined) {
+      await this._deleteCell(this.addr);
+    } else {
+      const wsData = await this._getWsData();
+      wsData.setCellType(this.addr, "str");
+      wsData.setCellVal(this.addr, undefined);
+      wsData.setCellFormula(this.addr, val);
+    }
+  }
+
+  /** 셀의 수식 반환 */
+  async getFormula(): Promise<string | undefined> {
+    const wsData = await this._getWsData();
+    return wsData.getCellFormula(this.addr);
+  }
+
+  /** 셀 값 설정 (undefined: 셀 삭제) */
+  async setVal(val: ExcelValueType): Promise<void> {
+    if (val === undefined) {
+      await this._deleteCell(this.addr);
+    } else if (typeof val === "string") {
+      const wsData = await this._getWsData();
+      const ssData = await this._getOrCreateSsData();
+      const ssId = ssData.getIdByString(val);
+      if (ssId !== undefined) {
+        wsData.setCellType(this.addr, "s");
+        wsData.setCellVal(this.addr, ssId.toString());
+      } else {
+        const newSsId = ssData.add(val);
+        wsData.setCellType(this.addr, "s");
+        wsData.setCellVal(this.addr, newSsId.toString());
+      }
+    } else if (typeof val === "boolean") {
+      const wsData = await this._getWsData();
+      wsData.setCellType(this.addr, "b");
+      wsData.setCellVal(this.addr, val ? "1" : "0");
+    } else if (typeof val === "number") {
+      const wsData = await this._getWsData();
+      wsData.setCellType(this.addr, undefined);
+      wsData.setCellVal(this.addr, val.toString());
+    } else if (val instanceof DateOnly || val instanceof DateTime || val instanceof Time) {
+      const wsData = await this._getWsData();
+      wsData.setCellType(this.addr, undefined);
+      wsData.setCellVal(this.addr, ExcelUtils.convertTimeTickToNumber(val.tick).toString());
+
+      const numFmtName = val instanceof DateOnly ? "DateOnly" : val instanceof DateTime ? "DateTime" : "Time";
+      await this._setStyleInternal({ numFmtId: ExcelUtils.convertNumFmtNameToId(numFmtName).toString() });
+    } else {
+      throw new Error(`[${ExcelUtils.stringifyAddr(this.addr)}] 지원되지 않는 타입입니다: ${typeof val}`);
+    }
+  }
+
+  /** 셀 값 반환 */
+  async getVal(): Promise<ExcelValueType> {
+    const wsData = await this._getWsData();
+    const cellVal = wsData.getCellVal(this.addr);
+    if (cellVal === undefined || strIsNullOrEmpty(cellVal)) {
+      return undefined;
+    }
+
+    const cellType = wsData.getCellType(this.addr);
+    if (cellType === "s") {
+      const ssData = await this._getOrCreateSsData();
+      const ssId = numParseInt(cellVal);
+      if (ssId == null) {
+        throw new Error(`[${ExcelUtils.stringifyAddr(this.addr)}] SharedString ID 파싱 실패: ${cellVal}`);
+      }
+      return ssData.getStringById(ssId);
+    } else if (cellType === "str") {
+      return cellVal;
+    } else if (cellType === "inlineStr") {
+      return cellVal;
+    } else if (cellType === "b") {
+      return cellVal === "1";
+    } else if (cellType === "n") {
+      return parseFloat(cellVal);
+    } else if (cellType === "e") {
+      throw new Error(
+        `[${ExcelUtils.stringifyAddr(this.addr)}] 셀 타입 분석 실패: 셀에 에러 값이 포함되어 있습니다 (${cellVal})`,
+      );
+    } else {
+      // cellType === undefined: 숫자 또는 날짜/시간 타입
+      const cellStyleId = wsData.getCellStyleId(this.addr);
+      if (cellStyleId === undefined) {
+        return parseFloat(cellVal);
+      }
+
+      const styleData = await this._getStyleData();
+      if (styleData == null) {
+        return parseFloat(cellVal);
+      }
+
+      const numFmtId = styleData.get(cellStyleId).numFmtId;
+      if (numFmtId === undefined) {
+        return parseFloat(cellVal);
+      }
+
+      const numFmtCode = styleData.getNumFmtCode(numFmtId);
+      let numFmt;
+      if (numFmtCode !== undefined) {
+        numFmt = ExcelUtils.convertNumFmtCodeToName(numFmtCode);
+      } else {
+        const numFmtIdNum = numParseInt(numFmtId);
+        if (numFmtIdNum == null) {
+          throw new Error(`[${ExcelUtils.stringifyAddr(this.addr)}] numFmtId 파싱 실패: ${numFmtId}`);
+        }
+        numFmt = ExcelUtils.convertNumFmtIdToName(numFmtIdNum);
+      }
+
+      if (numFmt === "number") {
+        return parseFloat(cellVal);
+      } else if (numFmt === "string") {
+        return cellVal;
+      } else {
+        // DateOnly, DateTime, Time
+        const dateNum = numParseFloat(cellVal);
+        if (dateNum == null) {
+          throw new Error(`[${ExcelUtils.stringifyAddr(this.addr)}] 날짜 숫자 파싱 실패: ${cellVal}`);
+        }
+        const tick = ExcelUtils.convertNumberToTimeTick(dateNum);
+        if (numFmt === "DateOnly") {
+          return new DateOnly(tick);
+        } else if (numFmt === "DateTime") {
+          return new DateTime(tick);
+        } else {
+          return new Time(tick);
+        }
+      }
+    }
+  }
+
+  //#endregion
+
+  //#region Merge Methods
+
+  /**
+   * 현재 셀부터 지정된 끝 좌표까지 셀 병합
+   * @param r 병합 끝 행 인덱스 (0-based)
+   * @param c 병합 끝 열 인덱스 (0-based)
+   * @example
+   * // A1 셀에서 호출하면 A1:C3 범위 (3행 x 3열)를 병합
+   * await ws.cell(0, 0).merge(2, 2);
+   */
+  async merge(r: number, c: number): Promise<void> {
+    const wsData = await this._getWsData();
+    wsData.setMergeCells(this.addr, { r, c });
+  }
+
+  //#endregion
+
+  //#region Style Methods
+
+  /** 셀의 스타일 ID 반환 */
+  async getStyleId(): Promise<string | undefined> {
+    const wsData = await this._getWsData();
+    return wsData.getCellStyleId(this.addr);
+  }
+
+  /** 셀의 스타일 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")
+   */
+  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)");
+      }
+      style.background = opts.background;
+    }
+
+    if (opts.border != null) {
+      style.border = opts.border;
+    }
+
+    if (opts.horizontalAlign != null) {
+      style.horizontalAlign = opts.horizontalAlign;
+    }
+
+    if (opts.verticalAlign != null) {
+      style.verticalAlign = opts.verticalAlign;
+    }
+
+    if (opts.numberFormat != null) {
+      style.numFmtId = ExcelUtils.convertNumFmtNameToId(opts.numberFormat).toString();
+    }
+
+    await this._setStyleInternal(style);
+  }
+
+  //#endregion
+
+  //#region Private Methods
+
+  private async _deleteCell(addr: ExcelAddressPoint): Promise<void> {
+    const wsData = await this._getWsData();
+    wsData.deleteCell(addr);
+  }
+
+  private async _getWsData(): Promise<ExcelXmlWorksheet> {
+    return (await this._zipCache.get(`xl/worksheets/${this._targetFileName}`)) as ExcelXmlWorksheet;
+  }
+
+  private async _setStyleInternal(style: ExcelStyle): Promise<void> {
+    const wsData = await this._getWsData();
+    const styleData = await this._getOrCreateStyleData();
+    let styleId = wsData.getCellStyleId(this.addr);
+    if (styleId == null) {
+      styleId = styleData.add(style);
+    } else {
+      styleId = styleData.addWithClone(styleId, style);
+    }
+    wsData.setCellStyleId(this.addr, styleId);
+  }
+
+  private async _getTypeData(): Promise<ExcelXmlContentType> {
+    return (await this._zipCache.get("[Content_Types].xml")) as ExcelXmlContentType;
+  }
+
+  private async _getSsData(): Promise<ExcelXmlSharedString | undefined> {
+    return (await this._zipCache.get("xl/sharedStrings.xml")) as ExcelXmlSharedString | undefined;
+  }
+
+  private async _getWbRelData(): Promise<ExcelXmlRelationship> {
+    return (await this._zipCache.get("xl/_rels/workbook.xml.rels")) as ExcelXmlRelationship;
+  }
+
+  private async _getStyleData(): Promise<ExcelXmlStyle | undefined> {
+    return (await this._zipCache.get("xl/styles.xml")) as ExcelXmlStyle | undefined;
+  }
+
+  private async _getOrCreateSsData(): Promise<ExcelXmlSharedString> {
+    let ssData = await this._getSsData();
+    if (ssData == null) {
+      ssData = new ExcelXmlSharedStringClass();
+      this._zipCache.set("xl/sharedStrings.xml", ssData);
+
+      const typeData = await this._getTypeData();
+      typeData.add(
+        "/xl/sharedStrings.xml",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml",
+      );
+
+      const wbRelData = await this._getWbRelData();
+      wbRelData.add(
+        "sharedStrings.xml",
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings",
+      );
+    }
+    return ssData;
+  }
+
+  private async _getOrCreateStyleData(): Promise<ExcelXmlStyle> {
+    let styleData = await this._getStyleData();
+    if (styleData == null) {
+      styleData = new ExcelXmlStyleClass();
+      this._zipCache.set("xl/styles.xml", styleData);
+
+      const typeData = await this._getTypeData();
+      typeData.add("/xl/styles.xml", "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml");
+
+      const wbRelData = await this._getWbRelData();
+      wbRelData.add("styles.xml", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles");
+    }
+    return styleData;
+  }
+
+  //#endregion
+}

package/src/excel-col.ts

@@ -0,0 +1,43 @@
+import "@simplysm/core-common";
+import { ExcelCell } from "./excel-cell";
+import type { ExcelXmlWorksheet } from "./xml/excel-xml-worksheet";
+import type { ZipCache } from "./utils/zip-cache";
+
+/** Excel 워크시트의 열을 나타내는 클래스. 셀 접근 및 열 너비 설정 기능을 제공한다. */
+export class ExcelCol {
+  private readonly _cellMap = new Map<number, ExcelCell>();
+
+  constructor(
+    private readonly _zipCache: ZipCache,
+    private readonly _targetFileName: string,
+    private readonly _c: number,
+  ) {}
+
+  /** 행 인덱스에 해당하는 셀 반환 (0-based) */
+  cell(r: number): ExcelCell {
+    return this._cellMap.getOrCreate(r, new ExcelCell(this._zipCache, this._targetFileName, r, this._c));
+  }
+
+  /** 열의 모든 셀 반환 */
+  async getCells(): Promise<ExcelCell[]> {
+    const result: ExcelCell[] = [];
+    const wsData = await this._getWsData();
+    const range = wsData.range;
+
+    for (let r = range.s.r; r <= range.e.r; r++) {
+      result[r] = this.cell(r);
+    }
+
+    return result;
+  }
+
+  /** 열 너비 설정 */
+  async setWidth(size: number): Promise<void> {
+    const wsData = await this._getWsData();
+    wsData.setColWidth((this._c + 1).toString(), size.toString());
+  }
+
+  private async _getWsData(): Promise<ExcelXmlWorksheet> {
+    return (await this._zipCache.get(`xl/worksheets/${this._targetFileName}`)) as ExcelXmlWorksheet;
+  }
+}

package/src/excel-row.ts

@@ -0,0 +1,37 @@
+import "@simplysm/core-common";
+import { ExcelCell } from "./excel-cell";
+import type { ExcelXmlWorksheet } from "./xml/excel-xml-worksheet";
+import type { ZipCache } from "./utils/zip-cache";
+
+/** Excel 워크시트의 행을 나타내는 클래스. 셀 접근 기능을 제공한다. */
+export class ExcelRow {
+  private readonly _cellMap = new Map<number, ExcelCell>();
+
+  constructor(
+    private readonly _zipCache: ZipCache,
+    private readonly _targetFileName: string,
+    private readonly _r: number,
+  ) {}
+
+  /** 열 인덱스에 해당하는 셀 반환 (0-based) */
+  cell(c: number): ExcelCell {
+    return this._cellMap.getOrCreate(c, new ExcelCell(this._zipCache, this._targetFileName, this._r, c));
+  }
+
+  /** 행의 모든 셀 반환 */
+  async getCells(): Promise<ExcelCell[]> {
+    const result: ExcelCell[] = [];
+    const wsData = await this._getWsData();
+    const range = wsData.range;
+
+    for (let c = range.s.c; c <= range.e.c; c++) {
+      result[c] = this.cell(c);
+    }
+
+    return result;
+  }
+
+  private async _getWsData(): Promise<ExcelXmlWorksheet> {
+    return (await this._zipCache.get(`xl/worksheets/${this._targetFileName}`)) as ExcelXmlWorksheet;
+  }
+}

package/src/excel-workbook.ts

@@ -0,0 +1,206 @@
+import type { Bytes } from "@simplysm/core-common";
+import { ExcelWorksheet } from "./excel-worksheet";
+import { ZipCache } from "./utils/zip-cache";
+import { ExcelXmlContentType } from "./xml/excel-xml-content-type";
+import { ExcelXmlRelationship } from "./xml/excel-xml-relationship";
+import type { ExcelXmlWorkbook } from "./xml/excel-xml-workbook";
+import { ExcelXmlWorkbook as ExcelXmlWorkbookClass } from "./xml/excel-xml-workbook";
+import { ExcelXmlWorksheet as ExcelXmlWorksheetClass } from "./xml/excel-xml-worksheet";
+
+/**
+ * Excel 워크북 처리 클래스
+ *
+ * @remarks
+ * 이 클래스는 내부적으로 ZIP 리소스를 관리합니다.
+ * 사용 완료 후 반드시 리소스를 해제해야 합니다.
+ *
+ * ## 비동기 설계
+ *
+ * 대용량 Excel 파일의 메모리 효율성을 위해 Lazy Loading 구조를 채택합니다:
+ * - ZIP 파일 내부의 XML은 접근 시점에만 읽고 파싱한다
+ * - SharedStrings, Styles 등 대용량 XML은 필요할 때만 로드한다
+ * - 극단적 케이스(예: SharedStrings가 1TB인 파일에서 숫자 셀 하나만 읽기)에서도 메모리 효율적이다
+ *
+ * @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 {
+  readonly zipCache: ZipCache;
+  private readonly _wsMap = new Map<number, ExcelWorksheet>();
+  private _isClosed = false;
+
+  /**
+   * @param arg 기존 Excel 파일 데이터 (Blob 또는 Uint8Array). 생략 시 새 워크북을 생성한다.
+   */
+  constructor(arg?: Blob | Bytes) {
+    if (arg != null) {
+      this.zipCache = new ZipCache(arg);
+    } else {
+      this.zipCache = new ZipCache();
+
+      // Global ContentTypes
+      const typeXml = new ExcelXmlContentType();
+      this.zipCache.set("[Content_Types].xml", typeXml);
+
+      // Global Rels
+      this.zipCache.set(
+        "_rels/.rels",
+        new ExcelXmlRelationship().add(
+          "xl/workbook.xml",
+          "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument",
+        ),
+      );
+
+      // Workbook
+      const wbXml = new ExcelXmlWorkbookClass();
+      this.zipCache.set("xl/workbook.xml", wbXml);
+
+      // Workbook Rels
+      const wbRelXml = new ExcelXmlRelationship();
+      this.zipCache.set("xl/_rels/workbook.xml.rels", wbRelXml);
+    }
+  }
+
+  //#region Worksheet Methods
+
+  private _ensureNotClosed(): void {
+    if (this._isClosed) {
+      throw new Error("ExcelWorkbook이 이미 닫혔습니다. close() 호출 후에는 사용할 수 없습니다.");
+    }
+  }
+
+  /** 워크북의 모든 워크시트 이름을 반환 */
+  async getWorksheetNames(): Promise<string[]> {
+    this._ensureNotClosed();
+    const wbData = (await this.zipCache.get("xl/workbook.xml")) as ExcelXmlWorkbook;
+    return wbData.sheetNames;
+  }
+
+  /** 새 워크시트를 생성하고 반환 */
+  async createWorksheet(name: string): Promise<ExcelWorksheet> {
+    this._ensureNotClosed();
+    // Workbook
+    const wbXml = (await this.zipCache.get("xl/workbook.xml")) as ExcelXmlWorkbook;
+    const newWsRelId = wbXml.addWorksheet(name).lastWsRelId!;
+
+    // Content Types
+    const typeXml = (await this.zipCache.get("[Content_Types].xml")) as ExcelXmlContentType;
+    typeXml.add(
+      `/xl/worksheets/sheet${newWsRelId}.xml`,
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml",
+    );
+
+    // Workbook Rels
+    const wbRelXml = (await this.zipCache.get("xl/_rels/workbook.xml.rels")) as ExcelXmlRelationship;
+    wbRelXml.insert(
+      newWsRelId,
+      `worksheets/sheet${newWsRelId}.xml`,
+      "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet",
+    );
+
+    // 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;
+  }
+
+  /** 이름 또는 인덱스(0-based)로 워크시트를 조회 */
+  async getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet> {
+    this._ensureNotClosed();
+    const wbData = (await this.zipCache.get("xl/workbook.xml")) as ExcelXmlWorkbook;
+    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")) as ExcelXmlRelationship;
+    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;
+  }
+
+  //#endregion
+
+  //#region Export Methods
+
+  /** 워크북을 바이트 배열로 출력 */
+  async getBytes(): Promise<Bytes> {
+    this._ensureNotClosed();
+    return this.zipCache.toBytes();
+  }
+
+  /** 워크북을 Blob으로 출력 */
+  async getBlob(): Promise<Blob> {
+    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(): Promise<void> {
+    if (this._isClosed) {
+      return; // 이미 닫힌 경우 무시
+    }
+    this._isClosed = true;
+    this._wsMap.clear();
+    await this.zipCache.close();
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close();
+  }
+
+  //#endregion
+}