@simplysm/excel 1.0.138 → 13.0.0-beta.2

package/src/types.ts

@@ -0,0 +1,396 @@
+import type { DateOnly, DateTime, Time } from "@simplysm/core-common";
+
+//#region XML Data Types
+
+export interface ExcelXmlContentTypeData {
+  Types: {
+    $: {
+      xmlns: string;
+    };
+    Default: {
+      $: {
+        Extension: string;
+        ContentType: string;
+      };
+    }[];
+    Override: {
+      $: {
+        PartName: string;
+        ContentType: string;
+      };
+    }[];
+  };
+}
+
+export interface ExcelXmlRelationshipData {
+  Relationships: {
+    $: {
+      xmlns: string;
+    };
+    Relationship?: ExcelRelationshipData[];
+  };
+}
+
+export interface ExcelRelationshipData {
+  $: {
+    Id: string;
+    Target: string;
+    Type: string;
+  };
+}
+
+export interface ExcelXmlWorkbookData {
+  workbook: {
+    $: {
+      "xmlns": string;
+      "xmlns:r"?: string;
+    };
+    bookViews?: [
+      {
+        workbookView: [{}];
+      },
+    ];
+    sheets?: [
+      {
+        sheet: {
+          $: {
+            "name": string;
+            "sheetId": string;
+            "r:id": string;
+          };
+        }[];
+      },
+    ];
+  };
+}
+
+export interface ExcelXmlWorksheetData {
+  worksheet: {
+    $: { "xmlns": string; "xmlns:r"?: string };
+    dimension?: [
+      {
+        $: {
+          ref: string;
+        };
+      },
+    ];
+    sheetViews?: [
+      {
+        sheetView: {
+          $: {
+            workbookViewId: string;
+            zoomScale?: string;
+          };
+          pane?: [
+            {
+              $: {
+                xSplit?: string;
+                ySplit?: string;
+                topLeftCell?: string;
+                activePane?: string;
+                state?: string;
+              };
+            },
+          ];
+        }[];
+      },
+    ];
+    sheetFormatPr?: [
+      {
+        $: {
+          defaultRowHeight: string;
+        };
+      },
+    ];
+    cols?: [
+      {
+        col: {
+          $: {
+            min: string;
+            max: string;
+            width?: string;
+            bestFit?: string;
+            customWidth?: string;
+          };
+        }[];
+      },
+    ];
+    sheetData: [
+      {
+        row?: ExcelRowData[];
+      },
+    ];
+    mergeCells?: [
+      {
+        $: { count: string };
+        mergeCell: {
+          $: { ref: string };
+        }[];
+      },
+    ];
+    drawing?: { $: { "r:id": string } }[];
+  };
+}
+
+export interface ExcelRowData {
+  $: {
+    r: string; // address (1~)
+  };
+  c?: ExcelCellData[];
+}
+
+export interface ExcelCellData {
+  $: {
+    r: string; // address (A~)
+    s?: string; // styleId
+    t?: string; // type: s(sharedString)
+  };
+  v?: [string];
+  f?: [string];
+  is?: {
+    t?: {
+      _?: string;
+    }[];
+  }[];
+}
+
+export interface ExcelXmlDrawingData {
+  wsDr: {
+    $: {
+      "xmlns": string;
+      "xmlns:a"?: string;
+      "xmlns:r"?: string;
+    };
+    twoCellAnchor?: {
+      from?: {
+        col: string[];
+        colOff?: string[];
+        row: string[];
+        rowOff?: string[];
+      }[];
+      to?: {
+        col: string[];
+        colOff?: string[];
+        row: string[];
+        rowOff?: string[];
+      }[];
+      pic?: {
+        nvPicPr?: {
+          cNvPr?: { $: { id: string; name: string; descr?: string } }[];
+          cNvPicPr?: Array<{ "a:picLocks"?: Array<{ $: { noChangeAspect?: string } }> }>;
+        }[];
+        blipFill?: {
+          "a:blip"?: Array<{ $: { "r:embed": string } }>;
+          "a:stretch"?: Array<{ "a:fillRect": unknown[] }>;
+        }[];
+        spPr?: {
+          "a:xfrm"?: Array<{
+            "a:off"?: Array<{ $: { x: string; y: string } }>;
+            "a:ext"?: Array<{ $: { cx: string; cy: string } }>;
+          }>;
+          "a:prstGeom"?: Array<{ "$": { prst: string }; "a:avLst": unknown[] }>;
+        }[];
+      }[];
+      clientData?: unknown[];
+    }[];
+  };
+}
+
+export interface ExcelXmlSharedStringData {
+  sst: {
+    $: { xmlns: string };
+    si?: ExcelXmlSharedStringDataSi[];
+  };
+}
+
+export type ExcelXmlSharedStringDataSi =
+  | {
+      t: ExcelXmlSharedStringDataText;
+    }
+  | {
+      r: {
+        t: ExcelXmlSharedStringDataText;
+      }[];
+    };
+
+export type ExcelXmlSharedStringDataText = [
+  | string
+  | {
+      $: { space?: "preserve" };
+      _?: string;
+    },
+];
+
+export interface ExcelXmlStyleData {
+  styleSheet: {
+    $: { xmlns: string };
+    numFmts?: [
+      {
+        $: { count: string };
+        numFmt?: {
+          $: {
+            numFmtId: string;
+            formatCode: string;
+          };
+        }[];
+      },
+    ];
+    fonts: [
+      {
+        $: { count: string };
+        font: {}[];
+      },
+    ];
+    fills: [
+      {
+        $: { count: string };
+        fill: ExcelXmlStyleDataFill[];
+      },
+    ];
+    borders: [
+      {
+        $: { count: string };
+        border: ExcelXmlStyleDataBorder[];
+      },
+    ];
+    cellXfs: [
+      {
+        $: { count: string };
+        xf: ExcelXmlStyleDataXf[];
+      },
+    ];
+  };
+}
+
+export interface ExcelXmlStyleDataXf {
+  $: {
+    numFmtId?: string;
+    fontId?: string;
+    fillId?: string;
+    borderId?: string;
+    xfId?: string;
+    applyNumberFormat?: string;
+    applyFont?: string;
+    applyAlignment?: string;
+    applyFill?: string;
+    applyBorder?: string;
+  };
+  alignment?: [
+    {
+      $: { horizontal?: "center" | "left" | "right"; vertical?: "center" | "top" | "bottom" };
+    },
+  ];
+}
+
+export interface ExcelXmlStyleDataFill {
+  patternFill: [
+    {
+      $: { patternType: "none" | "solid" | "gray125" };
+      fgColor?: [{ $: { rgb: string } }];
+    },
+  ];
+}
+
+export interface ExcelXmlStyleDataBorder {
+  top?: [
+    {
+      $: { style: "thin" | "medium" };
+      color?: [{ $: { rgb: string } }];
+    },
+  ];
+  left?: [
+    {
+      $: { style: "thin" | "medium" };
+      color?: [{ $: { rgb: string } }];
+    },
+  ];
+  right?: [
+    {
+      $: { style: "thin" | "medium" };
+      color?: [{ $: { rgb: string } }];
+    },
+  ];
+  bottom?: [
+    {
+      $: { style: "thin" | "medium" };
+      color?: [{ $: { rgb: string } }];
+    },
+  ];
+}
+
+//#endregion
+
+//#region Value Types
+
+export type ExcelValueType = number | string | DateOnly | DateTime | Time | boolean | undefined;
+export type ExcelNumberFormat = "number" | "string" | "DateOnly" | "DateTime" | "Time";
+
+/**
+ * Excel 셀 타입
+ * - s: 공유 문자열 (SharedString)
+ * - b: 불리언
+ * - str: 수식 결과 문자열
+ * - n: 숫자
+ * - inlineStr: 인라인 문자열 (리치 텍스트)
+ * - e: 에러
+ */
+export type ExcelCellType = "s" | "b" | "str" | "n" | "inlineStr" | "e";
+
+//#endregion
+
+//#region Address Types
+
+export interface ExcelAddressPoint {
+  r: number;
+  c: number;
+}
+
+export interface ExcelAddressRangePoint {
+  s: ExcelAddressPoint;
+  e: ExcelAddressPoint;
+}
+
+//#endregion
+
+//#region Excel XML Interface
+
+export interface ExcelXml {
+  readonly data: unknown;
+  cleanup(): void;
+}
+
+//#endregion
+
+//#region Style Types
+
+export type ExcelBorderPosition = "left" | "right" | "top" | "bottom";
+export type ExcelHorizontalAlign = "center" | "left" | "right";
+export type ExcelVerticalAlign = "center" | "top" | "bottom";
+
+/**
+ * 셀 스타일 옵션
+ * @example
+ * ```typescript
+ * await cell.setStyle({
+ *   background: "00FF0000",  // 빨간색
+ *   border: ["left", "right", "top", "bottom"],
+ *   horizontalAlign: "center",
+ *   verticalAlign: "center",
+ *   numberFormat: "number",
+ * });
+ * ```
+ */
+export interface ExcelStyleOptions {
+  /** 배경색 (ARGB 형식, 예: "00FF0000") */
+  background?: string;
+  /** 테두리 위치 */
+  border?: ExcelBorderPosition[];
+  /** 가로 정렬 */
+  horizontalAlign?: ExcelHorizontalAlign;
+  /** 세로 정렬 */
+  verticalAlign?: ExcelVerticalAlign;
+  /** 숫자 형식 */
+  numberFormat?: ExcelNumberFormat;
+}
+
+//#endregion

package/src/utils/excel-utils.ts

@@ -0,0 +1,201 @@
+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

@@ -0,0 +1,103 @@
+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();
+  }
+}