@simplysm/excel 13.0.0-beta.4 → 13.0.0-beta.44

package/src/utils/excel-utils.ts

@@ -1,201 +0,0 @@
-import { numParseInt } from "@simplysm/core-common";
-import type { ExcelAddressPoint, ExcelAddressRangePoint, ExcelNumberFormat } from "../types";
-
-/**
- * Excel 관련 유틸리티 함수 모음.
- * 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 등의 기능을 제공한다.
- */
-export class ExcelUtils {
-  /** 셀 좌표를 "A1" 형식 문자열로 변환 */
-  static stringifyAddr(point: ExcelAddressPoint): string {
-    const rowStr = this.stringifyRowAddr(point.r);
-    const colStr = this.stringifyColAddr(point.c);
-    return `${colStr}${rowStr}`;
-  }
-
-  /** 행 인덱스(0-based)를 행 주소 문자열로 변환 (예: 0 -> "1") */
-  static stringifyRowAddr(r: number): string {
-    return (r + 1).toString();
-  }
-
-  /** 열 인덱스(0-based)를 열 주소 문자열로 변환 (예: 0 -> "A", 26 -> "AA") */
-  static stringifyColAddr(c: number): string {
-    if (c < 0 || c > 16383) {
-      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 = Math.floor(remained / 26);
-    }
-    return result;
-  }
-
-  /** 셀 주소에서 행 인덱스 추출 (예: "A3" -> 2) */
-  static parseRowAddrCode(addrCode: string): number {
-    const rowAddrCode = /\d*$/.exec(addrCode)?.[0] ?? "";
-    const parsed = numParseInt(rowAddrCode);
-    if (parsed == null) {
-      throw new Error(`잘못된 행 주소 코드: ${addrCode}`);
-    }
-    return parsed - 1;
-  }
-
-  /** 셀 주소에서 열 인덱스 추출 (예: "B3" -> 1) */
-  static parseColAddrCode(addrCode: string): number {
-    const colAddrCode = /^[a-zA-Z]*/.exec(addrCode)?.[0] ?? "";
-
-    let result = 0;
-    const revAddr = Array.from(colAddrCode).reverse().join("");
-    for (let i = 0; i < revAddr.length; i++) {
-      const col = revAddr.charCodeAt(i) - (i === 0 ? 65 : 64);
-      result += col * 26 ** i;
-    }
-    return result;
-  }
-
-  /** 셀 주소를 좌표로 변환 (예: "B3" -> {r: 2, c: 1}) */
-  static parseCellAddrCode(addr: string): ExcelAddressPoint {
-    return {
-      r: ExcelUtils.parseRowAddrCode(addr),
-      c: ExcelUtils.parseColAddrCode(addr),
-    };
-  }
-
-  /** 범위 주소를 좌표로 변환 (예: "A1:C3" -> {s: {r:0,c:0}, e: {r:2,c:2}}) */
-  static parseRangeAddrCode(rangeAddr: string): ExcelAddressRangePoint {
-    const parts = rangeAddr.split(":");
-    return {
-      s: ExcelUtils.parseCellAddrCode(parts[0]),
-      e: ExcelUtils.parseCellAddrCode(parts[1] ?? parts[0]),
-    };
-  }
-
-  /** 범위 좌표를 주소 문자열로 변환 */
-  static stringifyRangeAddr(point: ExcelAddressRangePoint): string {
-    const sAddr = this.stringifyAddr(point.s);
-    const eAddr = this.stringifyAddr(point.e);
-
-    if (sAddr === eAddr) {
-      return sAddr;
-    } else {
-      return sAddr + ":" + eAddr;
-    }
-  }
-
-  /**
-   * JavaScript 타임스탬프(ms)를 Excel 날짜 숫자로 변환.
-   * Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
-   */
-  static convertTimeTickToNumber(tick: number): number {
-    const currDate = new Date(tick);
-    currDate.setMinutes(currDate.getMinutes() - currDate.getTimezoneOffset());
-    const excelBaseDateNumberUtc = Date.UTC(1899, 11, 31);
-    const inputExcelDateNumberUtc = currDate.getTime() - excelBaseDateNumberUtc;
-    return inputExcelDateNumberUtc / (24 * 60 * 60 * 1000) + 1;
-  }
-
-  /**
-   * Excel 날짜 숫자를 JavaScript 타임스탬프(ms)로 변환.
-   * Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
-   */
-  static convertNumberToTimeTick(num: number): number {
-    const excelBaseDateNumberUtc = Date.UTC(1899, 11, 31);
-    const excelDateNumberUtc = (num - 1) * 24 * 60 * 60 * 1000;
-    const dateNumberUtc = excelBaseDateNumberUtc + excelDateNumberUtc;
-    const date = new Date(dateNumberUtc);
-    date.setMinutes(date.getMinutes() + date.getTimezoneOffset());
-    return date.getTime();
-  }
-
-  /** 숫자 형식 코드를 형식 이름으로 변환 */
-  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);
-
-    if (hasDate && hasTime) {
-      return "DateTime"; // 날짜+시간 = DateTime
-    } else if (hasDate) {
-      return "DateOnly"; // 날짜만 = DateOnly
-    } else if (hasTime) {
-      return "Time"; // 시간만 = Time
-    }
-    // 숫자 형식 패턴: 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(`[numFmtCode: ${numFmtCode}]에 대한 형식을 알 수 없습니다.`);
-    }
-  }
-
-  /**
-   * 숫자 형식 ID를 형식 이름으로 변환
-   *
-   * @remarks
-   * 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 {
-    // 숫자/일반/통화/백분율 형식
-    if (numFmtId <= 13 || (numFmtId >= 37 && numFmtId <= 40) || numFmtId === 48) {
-      return "number";
-    }
-    // 날짜 형식 (지역화 포함)
-    else if (
-      (numFmtId >= 14 && numFmtId <= 17) ||
-      (numFmtId >= 27 && numFmtId <= 31) ||
-      (numFmtId >= 34 && numFmtId <= 36) ||
-      (numFmtId >= 50 && numFmtId <= 58)
-    ) {
-      return "DateOnly";
-    }
-    // 날짜+시간 형식
-    else if (numFmtId === 22) {
-      return "DateTime";
-    }
-    // 시간 형식
-    else if (
-      (numFmtId >= 18 && numFmtId <= 21) ||
-      (numFmtId >= 32 && numFmtId <= 33) ||
-      (numFmtId >= 45 && numFmtId <= 47)
-    ) {
-      return "Time";
-    }
-    // 텍스트 형식
-    else if (numFmtId === 49) {
-      return "string";
-    } else {
-      throw new Error(`[numFmtId: ${numFmtId}]에 대한 형식을 알 수 없습니다.`);
-    }
-  }
-
-  /** 숫자 형식 이름을 형식 ID로 변환 */
-  static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number {
-    if (numFmtName === "number") {
-      return 0;
-    } else if (numFmtName === "DateOnly") {
-      return 14;
-    } else if (numFmtName === "DateTime") {
-      return 22;
-    } else if (numFmtName === "Time") {
-      return 18;
-    } else {
-      // 마지막 케이스: "string" (TypeScript가 타입 좁히기를 통해 자동으로 확인)
-      return 49;
-    }
-  }
-}

package/src/utils/zip-cache.ts

@@ -1,103 +0,0 @@
-import type { Bytes } from "@simplysm/core-common";
-import { ZipArchive, xmlStringify, xmlParse } from "@simplysm/core-common";
-import type {
-  ExcelXml,
-  ExcelXmlContentTypeData,
-  ExcelXmlDrawingData,
-  ExcelXmlRelationshipData,
-  ExcelXmlSharedStringData,
-  ExcelXmlStyleData,
-  ExcelXmlWorkbookData,
-  ExcelXmlWorksheetData,
-} from "../types";
-import { ExcelXmlContentType } from "../xml/excel-xml-content-type";
-import { ExcelXmlDrawing } from "../xml/excel-xml-drawing";
-import { ExcelXmlRelationship } from "../xml/excel-xml-relationship";
-import { ExcelXmlSharedString } from "../xml/excel-xml-shared-string";
-import { ExcelXmlStyle } from "../xml/excel-xml-style";
-import { ExcelXmlUnknown } from "../xml/excel-xml-unknown";
-import { ExcelXmlWorkbook } from "../xml/excel-xml-workbook";
-import { ExcelXmlWorksheet } from "../xml/excel-xml-worksheet";
-
-/**
- * Excel ZIP 아카이브의 파일 캐시를 관리하는 클래스.
- * XML 파일은 파싱하여 ExcelXml 객체로, 그 외 파일은 바이트 배열로 캐싱한다.
- *
- * @remarks
- * ## Lazy Loading 캐시 전략
- *
- * - 파일은 첫 접근 시에만 ZIP에서 읽고 파싱한다
- * - 이후 접근은 캐시된 객체를 반환한다
- * - 대용량 Excel 파일에서 필요한 부분만 로드하여 메모리 효율성을 높인다
- */
-export class ZipCache {
-  private readonly _cache = new Map<string, ExcelXml | Bytes | undefined>();
-  private readonly _zip: ZipArchive;
-
-  constructor(arg?: Blob | Bytes) {
-    this._zip = new ZipArchive(arg);
-  }
-
-  async get(filePath: string): Promise<ExcelXml | Bytes | undefined> {
-    if (this._cache.has(filePath)) {
-      return this._cache.get(filePath);
-    }
-
-    const fileData = await this._zip.get(filePath);
-    if (fileData == null) {
-      this._cache.set(filePath, undefined);
-      return undefined;
-    }
-
-    if (filePath.endsWith(".xml") || filePath.endsWith(".rels")) {
-      const fileText = new TextDecoder().decode(fileData);
-      const xml = xmlParse(fileText, { stripTagPrefix: true });
-      if (filePath.endsWith(".rels")) {
-        this._cache.set(filePath, new ExcelXmlRelationship(xml as ExcelXmlRelationshipData));
-      } else if (filePath === "[Content_Types].xml") {
-        this._cache.set(filePath, new ExcelXmlContentType(xml as ExcelXmlContentTypeData));
-      } else if (filePath === "xl/workbook.xml") {
-        this._cache.set(filePath, new ExcelXmlWorkbook(xml as ExcelXmlWorkbookData));
-      } else if (filePath.startsWith("xl/worksheets/sheet") && filePath.endsWith(".xml")) {
-        this._cache.set(filePath, new ExcelXmlWorksheet(xml as ExcelXmlWorksheetData));
-      } else if (filePath.startsWith("xl/drawings/drawing") && filePath.endsWith(".xml")) {
-        this._cache.set(filePath, new ExcelXmlDrawing(xml as ExcelXmlDrawingData));
-      } else if (filePath === "xl/sharedStrings.xml") {
-        this._cache.set(filePath, new ExcelXmlSharedString(xml as ExcelXmlSharedStringData));
-      } else if (filePath === "xl/styles.xml") {
-        this._cache.set(filePath, new ExcelXmlStyle(xml as ExcelXmlStyleData));
-      } else {
-        this._cache.set(filePath, new ExcelXmlUnknown(xml as Record<string, unknown>));
-      }
-    } else {
-      this._cache.set(filePath, fileData);
-    }
-
-    return this._cache.get(filePath);
-  }
-
-  set(filePath: string, content: ExcelXml | Bytes): void {
-    this._cache.set(filePath, content);
-  }
-
-  async toBytes(): Promise<Bytes> {
-    for (const filePath of this._cache.keys()) {
-      const content = this._cache.get(filePath);
-      if (content == null) continue;
-
-      if ("cleanup" in content) {
-        content.cleanup();
-        this._zip.write(filePath, new TextEncoder().encode(xmlStringify(content.data)));
-      } else {
-        this._zip.write(filePath, content);
-      }
-    }
-
-    return this._zip.compress();
-  }
-
-  async close(): Promise<void> {
-    await this._zip.close();
-    this._cache.clear();
-  }
-}

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

@@ -1,64 +0,0 @@
-import type { ExcelXml, ExcelXmlContentTypeData } from "../types";
-
-/**
- * [Content_Types].xml 파일을 관리하는 클래스.
- * 파일별 MIME 타입 정보를 관리한다.
- */
-export class ExcelXmlContentType implements ExcelXml {
-  data: ExcelXmlContentTypeData;
-
-  constructor(data?: ExcelXmlContentTypeData) {
-    if (data == null) {
-      this.data = {
-        Types: {
-          $: {
-            xmlns: "http://schemas.openxmlformats.org/package/2006/content-types",
-          },
-          Default: [
-            {
-              $: {
-                Extension: "rels",
-                ContentType: "application/vnd.openxmlformats-package.relationships+xml",
-              },
-            },
-            {
-              $: {
-                Extension: "xml",
-                ContentType: "application/xml",
-              },
-            },
-          ],
-          Override: [
-            {
-              $: {
-                PartName: "/xl/workbook.xml",
-                ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml",
-              },
-            },
-          ],
-        },
-      };
-    } else {
-      this.data = data;
-    }
-  }
-
-  add(partName: string, contentType: string): this {
-    // 중복 체크
-    const exists = this.data.Types.Override.some((item) => item.$.PartName === partName);
-    if (exists) {
-      return this;
-    }
-
-    this.data.Types.Override.push({
-      $: {
-        PartName: partName,
-        ContentType: contentType,
-      },
-    });
-
-    return this;
-  }
-
-  cleanup(): void {}
-}

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

@@ -1,87 +0,0 @@
-import type { ExcelXml, ExcelXmlDrawingData } from "../types";
-
-/**
- * xl/drawings/drawing*.xml 파일을 관리하는 클래스.
- * 이미지 삽입 시 위치 및 참조 정보를 처리한다.
- */
-export class ExcelXmlDrawing implements ExcelXml {
-  data: ExcelXmlDrawingData;
-
-  constructor(data?: ExcelXmlDrawingData) {
-    if (data == null) {
-      this.data = {
-        wsDr: {
-          $: {
-            "xmlns": "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing",
-            "xmlns:a": "http://schemas.openxmlformats.org/drawingml/2006/main",
-            "xmlns:r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
-          },
-          twoCellAnchor: [],
-        },
-      };
-    } else {
-      this.data = data;
-    }
-  }
-
-  addPicture(opts: {
-    from: { r: number; c: number; rOff?: number | string; cOff?: number | string };
-    to: { r: number; c: number; rOff?: number | string; cOff?: number | string };
-    blipRelId: string;
-  }): void {
-    this.data.wsDr.twoCellAnchor = this.data.wsDr.twoCellAnchor ?? [];
-
-    const anchors = this.data.wsDr.twoCellAnchor;
-    const picId = anchors.length + 1;
-    const name = `Picture ${picId}`;
-
-    this.data.wsDr.twoCellAnchor.push({
-      from: [
-        {
-          col: [opts.from.c.toString()],
-          colOff: [opts.from.cOff != null ? opts.from.cOff.toString() : "0"],
-          row: [opts.from.r.toString()],
-          rowOff: [opts.from.rOff != null ? opts.from.rOff.toString() : "0"],
-        },
-      ],
-      to: [
-        {
-          col: [opts.to.c.toString()],
-          colOff: [opts.to.cOff != null ? opts.to.cOff.toString() : "0"],
-          row: [opts.to.r.toString()],
-          rowOff: [opts.to.rOff != null ? opts.to.rOff.toString() : "0"],
-        },
-      ],
-      pic: [
-        {
-          nvPicPr: [
-            {
-              cNvPr: [{ $: { id: picId.toString(), name } }],
-              cNvPicPr: [{ "a:picLocks": [{ $: { noChangeAspect: "1" } }] }],
-            },
-          ],
-          blipFill: [
-            {
-              "a:blip": [{ $: { "r:embed": opts.blipRelId } }],
-              "a:stretch": [{ "a:fillRect": [] }],
-            },
-          ],
-          spPr: [
-            {
-              "a:xfrm": [
-                {
-                  "a:off": [{ $: { x: "0", y: "0" } }],
-                  "a:ext": [{ $: { cx: "0", cy: "0" } }],
-                },
-              ],
-              "a:prstGeom": [{ "$": { prst: "rect" }, "a:avLst": [] }],
-            },
-          ],
-        },
-      ],
-      clientData: [{}],
-    });
-  }
-
-  cleanup(): void {}
-}

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

@@ -1,86 +0,0 @@
-import "@simplysm/core-common";
-import { numParseInt } from "@simplysm/core-common";
-import type { ExcelRelationshipData, ExcelXml, ExcelXmlRelationshipData } from "../types";
-
-/**
- * *.rels 파일을 관리하는 클래스.
- * 파일 간의 참조 관계를 처리한다.
- */
-export class ExcelXmlRelationship implements ExcelXml {
-  data: ExcelXmlRelationshipData;
-
-  constructor(data?: ExcelXmlRelationshipData) {
-    if (data == null) {
-      this.data = {
-        Relationships: {
-          $: {
-            xmlns: "http://schemas.openxmlformats.org/package/2006/relationships",
-          },
-        },
-      };
-    } else {
-      this.data = data;
-    }
-  }
-
-  getTargetByRelId(rId: number): string | undefined {
-    return (this.data.Relationships.Relationship ?? []).single((rel) => this._getRelId(rel) === rId)?.$.Target;
-  }
-
-  add(target: string, type: string): this {
-    this.addAndGetId(target, type);
-    return this;
-  }
-
-  addAndGetId(target: string, type: string): number {
-    this.data.Relationships.Relationship = this.data.Relationships.Relationship ?? [];
-
-    const newId = (this._lastId ?? 0) + 1;
-
-    this.data.Relationships.Relationship.push({
-      $: {
-        Id: `rId${newId}`,
-        Target: target,
-        Type: type,
-      },
-    });
-
-    return newId;
-  }
-
-  insert(rId: number, target: string, type: string): this {
-    this.data.Relationships.Relationship = this.data.Relationships.Relationship ?? [];
-
-    const shiftRels = this.data.Relationships.Relationship.filter((rel) => this._getRelId(rel) >= rId);
-    for (const shiftRel of shiftRels) {
-      shiftRel.$.Id = `rId${this._getRelId(shiftRel) + 1}`;
-    }
-
-    this.data.Relationships.Relationship.push({
-      $: {
-        Id: `rId${rId}`,
-        Target: target,
-        Type: type,
-      },
-    });
-
-    return this;
-  }
-
-  cleanup(): void {}
-
-  private get _lastId(): number | undefined {
-    const rels = this.data.Relationships.Relationship;
-    if (!rels || rels.length === 0) return undefined;
-    const maxRel = rels.orderByDesc((rel) => this._getRelId(rel)).first();
-    return maxRel ? this._getRelId(maxRel) : undefined;
-  }
-
-  private _getRelId(rel: ExcelRelationshipData): number {
-    const match = /[0-9]+$/.exec(rel.$.Id);
-    if (match == null) {
-      throw new Error(`잘못된 관계 ID 형식입니다: ${rel.$.Id}`);
-    }
-    return numParseInt(match[0])!;
-  }
-}

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

@@ -1,80 +0,0 @@
-import type {
-  ExcelXml,
-  ExcelXmlSharedStringData,
-  ExcelXmlSharedStringDataSi,
-  ExcelXmlSharedStringDataText,
-} from "../types";
-import "@simplysm/core-common";
-
-/**
- * xl/sharedStrings.xml 파일을 관리하는 클래스.
- * 문자열 중복을 방지하여 파일 크기를 최적화한다.
- */
-export class ExcelXmlSharedString implements ExcelXml {
-  data: ExcelXmlSharedStringData;
-
-  private readonly _stringIndexesMap: Map<string, number[]>;
-
-  constructor(data?: ExcelXmlSharedStringData) {
-    if (data === undefined) {
-      this.data = {
-        sst: {
-          $: {
-            xmlns: "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
-          },
-        },
-      };
-    } else {
-      this.data = data;
-    }
-
-    this._stringIndexesMap = this.data.sst.si
-      ? this.data.sst.si
-          .map((tag, id) => ({ id, tag }))
-          .filter((item) => !this._getHasInnerStyleOnSiTag(item.tag))
-          .toArrayMap(
-            (item) => this._getStringFromSiTag(item.tag),
-            (item) => item.id,
-          )
-      : new Map<string, number[]>();
-  }
-
-  getIdByString(str: string): number | undefined {
-    return this._stringIndexesMap.get(str)?.[0];
-  }
-
-  getStringById(id: number): string | undefined {
-    const si = this.data.sst.si?.[id];
-    return si != null ? this._getStringFromSiTag(si) : undefined;
-  }
-
-  add(str: string): number {
-    this.data.sst.si = this.data.sst.si ?? [];
-    const newLength = this.data.sst.si.push({ t: [str] });
-    const arr = this._stringIndexesMap.getOrCreate(str, []);
-    arr.push(newLength - 1);
-    return newLength - 1;
-  }
-
-  cleanup(): void {}
-
-  private _getStringFromSiTag(si: ExcelXmlSharedStringDataSi): string {
-    if ("t" in si) {
-      return this._getStringFromTTag(si.t);
-    } else {
-      return si.r.map((item) => this._getStringFromTTag(item.t)).join("");
-    }
-  }
-
-  private _getStringFromTTag(t: ExcelXmlSharedStringDataText): string {
-    const firstItem = t[0];
-    if (typeof firstItem === "string") {
-      return firstItem;
-    }
-    return firstItem._ ?? " ";
-  }
-
-  private _getHasInnerStyleOnSiTag(si: ExcelXmlSharedStringDataSi): boolean {
-    return Object.keys(si).some((item) => item !== "t");
-  }
-}