@simplysm/excel 14.0.100 → 14.0.101

package/src/utils/zip-cache.ts

@@ -1,93 +1,224 @@
 import type { Bytes } from "@simplysm/core-common";
-import { ZipArchive, xml as xmlU } 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";
+import { ZipArchive } from "@simplysm/core-common";
+import { BiffModelFactory } from "../biff/biff-model-factory";
+import type { ExcelFormat } from "../models/excel-format";
+import type { IExcelModel } from "../models/excel-model";
+import type { IExcelModelFactory } from "../models/excel-model-factory";
+import type { IContentTypeModel } from "../models/i-content-type-model";
+import type { IDrawingModel } from "../models/i-drawing-model";
+import type { IRelationshipModel } from "../models/i-relationship-model";
+import type { ISharedStringModel } from "../models/i-shared-string-model";
+import type { IStyleModel } from "../models/i-style-model";
+import type { IWorkbookModel } from "../models/i-workbook-model";
+import type { IWorksheetModel } from "../models/i-worksheet-model";
+import { XmlModelFactory } from "../xml/xml-model-factory";
 
 /**
  * Excel ZIP 아카이브의 파일 캐시를 관리하는 클래스.
- * XML 파일은 ExcelXml 객체로 파싱하고, 기타 파일은 바이트 배열로 캐싱한다.
+ * 모델 파트는 포맷별 팩토리로 파싱/직렬화하고, 기타 파일(media 등)은 바이트 배열로 캐싱한다.
  *
  * @remarks
- * ## Lazy Loading 캐시 전략
+ * ## 포맷 판별·경로 정규화
  *
- * - 파일은 최초 접근 시에만 ZIP에서 읽고 파싱함
- * - 이후 접근은 캐싱된 객체를 반환함
- * - 대용량 Excel 파일에서 필요한 부분만 로드하여 메모리 효율적
+ * 기존 파일은 `xl/workbook.bin` 존재 여부로 xlsx/xlsb 를 1회 판별한다(없으면 xlsx).
+ * 상위 레이어는 `xl/workbook.xml` 같은 OOXML(.xml) 경로를 사용하므로, xlsb 워크북에서는
+ * 이를 `.bin` 경로로 정규화하여 상위 레이어가 포맷을 모르게 한다.
+ *
+ * ## Lazy Loading
+ *
+ * 파일은 최초 접근 시에만 ZIP 에서 읽고 파싱하며, 이후 접근은 캐싱된 객체를 반환한다.
  */
 export class ZipCache {
-  private readonly _cache = new Map<string, ExcelXml | Bytes | undefined>();
+  private readonly _cache = new Map<string, IExcelModel | Bytes | undefined>();
   private readonly _zip: ZipArchive;
+  private _factory: IExcelModelFactory | undefined;
 
-  constructor(arg?: Blob | Bytes) {
+  constructor(arg?: Blob | Bytes, format?: ExcelFormat) {
     this._zip = new ZipArchive(arg);
+    if (format != null) {
+      this._factory = format === "xlsb" ? new BiffModelFactory() : new XmlModelFactory();
+    }
+  }
+
+  /** 워크북 포맷. 미판별 시 xlsx 로 간주. */
+  get format(): ExcelFormat {
+    return (this._factory ??= new XmlModelFactory()).format;
+  }
+
+  /** 기존 파일 포맷을 1회 판별해 팩토리 확정 (async). */
+  private async _resolveFactory(): Promise<IExcelModelFactory> {
+    if (this._factory == null) {
+      const isXlsb = (await this._zip.get("xl/workbook.bin")) != null;
+      this._factory = isXlsb ? new BiffModelFactory() : new XmlModelFactory();
+    }
+    return this._factory;
+  }
+
+  /** 새(빈) 워크북의 동기 생성 경로용 팩토리. 빈 워크북은 xlsx 로 본다. */
+  private get _syncFactory(): IExcelModelFactory {
+    return (this._factory ??= new XmlModelFactory());
+  }
+
+  /** 상위 레이어의 .xml 고정 경로를 xlsb 의 실제 .bin 경로로 정규화. */
+  private _resolvePath(filePath: string): string {
+    if (this._factory?.format !== "xlsb") return filePath;
+    switch (filePath) {
+      case "xl/workbook.xml":
+        return "xl/workbook.bin";
+      case "xl/sharedStrings.xml":
+        return "xl/sharedStrings.bin";
+      case "xl/styles.xml":
+        return "xl/styles.bin";
+      case "xl/_rels/workbook.xml.rels":
+        return "xl/_rels/workbook.bin.rels";
+      default: {
+        const m = /^(xl\/worksheets\/_rels\/sheet\d+)\.xml\.rels$/.exec(filePath);
+        return m != null ? `${m[1]}.bin.rels` : filePath;
+      }
+    }
   }
 
-  async get(filePath: string): Promise<ExcelXml | Bytes | undefined> {
-    if (this._cache.has(filePath)) {
-      return this._cache.get(filePath);
+  async get(filePath: string): Promise<IExcelModel | Bytes | undefined> {
+    const factory = await this._resolveFactory();
+    const path = this._resolvePath(filePath);
+
+    if (this._cache.has(path)) {
+      return this._cache.get(path);
     }
 
-    const fileData = await this._zip.get(filePath);
+    const fileData = await this._zip.get(path);
     if (fileData == null) {
-      this._cache.set(filePath, undefined);
+      this._cache.set(path, undefined);
       return undefined;
     }
 
-    if (filePath.endsWith(".xml") || filePath.endsWith(".rels")) {
-      const fileText = new TextDecoder().decode(fileData);
-      const xml = xmlU.parse(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>));
-      }
+    if (factory.isModelPart(path)) {
+      this._cache.set(path, factory.parse(path, fileData));
     } else {
-      this._cache.set(filePath, fileData);
+      this._cache.set(path, fileData);
     }
 
-    return this._cache.get(filePath);
+    return this._cache.get(path);
+  }
+
+  set(filePath: string, content: IExcelModel | Bytes): void {
+    this._cache.set(this._resolvePath(filePath), content);
+  }
+
+  //#region Factory Delegation (빈 모델 생성)
+
+  createWorkbook(): IWorkbookModel {
+    return this._syncFactory.createWorkbook();
   }
+  createWorksheet(): IWorksheetModel {
+    return this._syncFactory.createWorksheet();
+  }
+  createStyle(): IStyleModel {
+    return this._syncFactory.createStyle();
+  }
+  createSharedString(): ISharedStringModel {
+    return this._syncFactory.createSharedString();
+  }
+  createContentType(): IContentTypeModel {
+    return this._syncFactory.createContentType();
+  }
+  createRelationship(): IRelationshipModel {
+    return this._syncFactory.createRelationship();
+  }
+  createDrawing(): IDrawingModel {
+    return this._syncFactory.createDrawing();
+  }
+
+  //#endregion
+
+  //#region Part 등록 (포맷별 content-type·rel·part 생성)
+
+  /**
+   * 워크시트 파트를 등록한다. content-type override, workbook rels, 빈 worksheet 모델을 포맷에 맞게 생성하고
+   * worksheet 파일명(`sheetN.xml` | `sheetN.bin`)을 반환한다.
+   */
+  async registerWorksheet(relId: number): Promise<string> {
+    const xlsb = this.format === "xlsb";
+    const fileName = `sheet${relId}.${xlsb ? "bin" : "xml"}`;
+
+    const typeXml = (await this.get("[Content_Types].xml")) as IContentTypeModel;
+    typeXml.add(
+      `/xl/worksheets/${fileName}`,
+      xlsb
+        ? "application/vnd.ms-excel.worksheet"
+        : "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml",
+    );
+
+    const wbRel = (await this.get("xl/_rels/workbook.xml.rels")) as IRelationshipModel;
+    wbRel.insert(
+      relId,
+      `worksheets/${fileName}`,
+      "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet",
+    );
 
-  set(filePath: string, content: ExcelXml | Bytes): void {
-    this._cache.set(filePath, content);
+    this.set(`xl/worksheets/${fileName}`, this.createWorksheet());
+    return fileName;
   }
 
+  /** sharedStrings 파트를 보장(없으면 생성+등록)하고 모델을 반환한다. */
+  async ensureSharedStrings(): Promise<ISharedStringModel> {
+    let ss = (await this.get("xl/sharedStrings.xml")) as ISharedStringModel | undefined;
+    if (ss == null) {
+      const xlsb = this.format === "xlsb";
+      ss = this.createSharedString();
+      this.set("xl/sharedStrings.xml", ss);
+
+      const typeXml = (await this.get("[Content_Types].xml")) as IContentTypeModel;
+      typeXml.add(
+        `/xl/sharedStrings.${xlsb ? "bin" : "xml"}`,
+        xlsb
+          ? "application/vnd.ms-excel.sharedStrings"
+          : "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml",
+      );
+
+      const wbRel = (await this.get("xl/_rels/workbook.xml.rels")) as IRelationshipModel;
+      wbRel.add(
+        `sharedStrings.${xlsb ? "bin" : "xml"}`,
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings",
+      );
+    }
+    return ss;
+  }
+
+  /** styles 파트를 보장(없으면 생성+등록)하고 모델을 반환한다. */
+  async ensureStyles(): Promise<IStyleModel> {
+    let st = (await this.get("xl/styles.xml")) as IStyleModel | undefined;
+    if (st == null) {
+      const xlsb = this.format === "xlsb";
+      st = this.createStyle();
+      this.set("xl/styles.xml", st);
+
+      const typeXml = (await this.get("[Content_Types].xml")) as IContentTypeModel;
+      typeXml.add(
+        `/xl/styles.${xlsb ? "bin" : "xml"}`,
+        xlsb
+          ? "application/vnd.ms-excel.styles"
+          : "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml",
+      );
+
+      const wbRel = (await this.get("xl/_rels/workbook.xml.rels")) as IRelationshipModel;
+      wbRel.add(
+        `styles.${xlsb ? "bin" : "xml"}`,
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
+      );
+    }
+    return st;
+  }
+
+  //#endregion
+
   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(xmlU.stringify(content.data)));
+      if ("serialize" in content) {
+        this._zip.write(filePath, content.serialize());
       } else {
         this._zip.write(filePath, content);
       }

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

@@ -1,15 +1,18 @@
-import type { ExcelXml, ExcelXmlContentTypeData } from "../types";
+import type { Bytes } from "@simplysm/core-common";
+import { xml as xmlU } from "@simplysm/core-common";
+import type { IContentTypeModel } from "../models/i-content-type-model";
+import type { ExcelXmlContentTypeData } from "../types";
 
 /**
  * [Content_Types].xml을 관리하는 클래스.
  * 파일별 MIME 타입 정보를 관리한다.
  */
-export class ExcelXmlContentType implements ExcelXml {
-  data: ExcelXmlContentTypeData;
+export class ExcelXmlContentType implements IContentTypeModel {
+  private readonly _data: ExcelXmlContentTypeData;
 
   constructor(data?: ExcelXmlContentTypeData) {
     if (data == null) {
-      this.data = {
+      this._data = {
         Types: {
           $: {
             xmlns: "http://schemas.openxmlformats.org/package/2006/content-types",
@@ -40,18 +43,23 @@ export class ExcelXmlContentType implements ExcelXml {
         },
       };
     } else {
-      this.data = data;
+      this._data = data;
     }
   }
 
+  /** @internal 테스트·디버그용 내부 트리 접근. 상위 레이어는 인터페이스만 사용. */
+  get data(): ExcelXmlContentTypeData {
+    return this._data;
+  }
+
   add(partName: string, contentType: string): this {
     // 중복 검사
-    const exists = this.data.Types.Override.some((item) => item.$.PartName === partName);
+    const exists = this._data.Types.Override.some((item) => item.$.PartName === partName);
     if (exists) {
       return this;
     }
 
-    this.data.Types.Override.push({
+    this._data.Types.Override.push({
       $: {
         PartName: partName,
         ContentType: contentType,
@@ -61,5 +69,7 @@ export class ExcelXmlContentType implements ExcelXml {
     return this;
   }
 
-  cleanup(): void {}
+  serialize(): Bytes {
+    return new TextEncoder().encode(xmlU.stringify(this._data));
+  }
 }

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

@@ -1,15 +1,18 @@
-import type { ExcelXml, ExcelXmlDrawingData } from "../types";
+import type { Bytes } from "@simplysm/core-common";
+import { xml as xmlU } from "@simplysm/core-common";
+import type { IDrawingModel } from "../models/i-drawing-model";
+import type { ExcelXmlDrawingData } from "../types";
 
 /**
  * xl/drawings/drawing*.xml 파일을 관리하는 클래스.
  * 이미지 삽입을 위한 위치 및 참조 정보를 처리한다.
  */
-export class ExcelXmlDrawing implements ExcelXml {
-  data: ExcelXmlDrawingData;
+export class ExcelXmlDrawing implements IDrawingModel {
+  private readonly _data: ExcelXmlDrawingData;
 
   constructor(data?: ExcelXmlDrawingData) {
     if (data == null) {
-      this.data = {
+      this._data = {
         wsDr: {
           $: {
             "xmlns": "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing",
@@ -20,22 +23,27 @@ export class ExcelXmlDrawing implements ExcelXml {
         },
       };
     } else {
-      this.data = data;
+      this._data = data;
     }
   }
 
+  /** @internal 테스트·디버그용 내부 트리 접근. 상위 레이어는 인터페이스만 사용. */
+  get data(): ExcelXmlDrawingData {
+    return this._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 ?? [];
+    this._data.wsDr.twoCellAnchor = this._data.wsDr.twoCellAnchor ?? [];
 
-    const anchors = this.data.wsDr.twoCellAnchor;
+    const anchors = this._data.wsDr.twoCellAnchor;
     const picId = anchors.length + 1;
     const name = `Picture ${picId}`;
 
-    this.data.wsDr.twoCellAnchor.push({
+    this._data.wsDr.twoCellAnchor.push({
       from: [
         {
           col: [opts.from.c.toString()],
@@ -83,5 +91,7 @@ export class ExcelXmlDrawing implements ExcelXml {
     });
   }
 
-  cleanup(): void {}
+  serialize(): Bytes {
+    return new TextEncoder().encode(xmlU.stringify(this._data));
+  }
 }

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

@@ -1,17 +1,19 @@
 import "@simplysm/core-common";
-import { num } from "@simplysm/core-common";
-import type { ExcelRelationshipData, ExcelXml, ExcelXmlRelationshipData } from "../types";
+import type { Bytes } from "@simplysm/core-common";
+import { num, xml as xmlU } from "@simplysm/core-common";
+import type { IRelationshipModel } from "../models/i-relationship-model";
+import type { ExcelRelationshipData, ExcelXmlRelationshipData } from "../types";
 
 /**
  * *.rels 파일을 관리하는 클래스.
  * 파일 간의 참조 관계를 처리한다.
  */
-export class ExcelXmlRelationship implements ExcelXml {
-  data: ExcelXmlRelationshipData;
+export class ExcelXmlRelationship implements IRelationshipModel {
+  private readonly _data: ExcelXmlRelationshipData;
 
   constructor(data?: ExcelXmlRelationshipData) {
     if (data == null) {
-      this.data = {
+      this._data = {
         Relationships: {
           $: {
             xmlns: "http://schemas.openxmlformats.org/package/2006/relationships",
@@ -19,12 +21,17 @@ export class ExcelXmlRelationship implements ExcelXml {
         },
       };
     } else {
-      this.data = data;
+      this._data = data;
     }
   }
 
+  /** @internal 테스트·디버그용 내부 트리 접근. 상위 레이어는 인터페이스만 사용. */
+  get data(): ExcelXmlRelationshipData {
+    return this._data;
+  }
+
   getTargetByRelId(rId: number): string | undefined {
-    return (this.data.Relationships.Relationship ?? []).single((rel) => this._getRelId(rel) === rId)
+    return (this._data.Relationships.Relationship ?? []).single((rel) => this._getRelId(rel) === rId)
       ?.$.Target;
   }
 
@@ -34,11 +41,11 @@ export class ExcelXmlRelationship implements ExcelXml {
   }
 
   addAndGetId(target: string, type: string): number {
-    this.data.Relationships.Relationship = this.data.Relationships.Relationship ?? [];
+    this._data.Relationships.Relationship = this._data.Relationships.Relationship ?? [];
 
     const newId = (this._lastId ?? 0) + 1;
 
-    this.data.Relationships.Relationship.push({
+    this._data.Relationships.Relationship.push({
       $: {
         Id: `rId${newId}`,
         Target: target,
@@ -50,16 +57,16 @@ export class ExcelXmlRelationship implements ExcelXml {
   }
 
   insert(rId: number, target: string, type: string): this {
-    this.data.Relationships.Relationship = this.data.Relationships.Relationship ?? [];
+    this._data.Relationships.Relationship = this._data.Relationships.Relationship ?? [];
 
-    const shiftRels = this.data.Relationships.Relationship.filter(
+    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({
+    this._data.Relationships.Relationship.push({
       $: {
         Id: `rId${rId}`,
         Target: target,
@@ -70,10 +77,17 @@ export class ExcelXmlRelationship implements ExcelXml {
     return this;
   }
 
-  cleanup(): void {}
+  findRelByType(type: string): { relId: string; target: string } | undefined {
+    const rel = (this._data.Relationships.Relationship ?? []).find((r) => r.$.Type === type);
+    return rel != null ? { relId: rel.$.Id, target: rel.$.Target } : undefined;
+  }
+
+  serialize(): Bytes {
+    return new TextEncoder().encode(xmlU.stringify(this._data));
+  }
 
   private get _lastId(): number | undefined {
-    const rels = this.data.Relationships.Relationship;
+    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;

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

@@ -1,5 +1,7 @@
+import type { Bytes } from "@simplysm/core-common";
+import { xml as xmlU } from "@simplysm/core-common";
+import type { ISharedStringModel } from "../models/i-shared-string-model";
 import type {
-  ExcelXml,
   ExcelXmlSharedStringData,
   ExcelXmlSharedStringDataSi,
   ExcelXmlSharedStringDataText,
@@ -10,14 +12,14 @@ import "@simplysm/core-common";
  * xl/sharedStrings.xml을 관리하는 클래스.
  * 문자열 중복을 방지하여 파일 크기를 최적화한다.
  */
-export class ExcelXmlSharedString implements ExcelXml {
-  data: ExcelXmlSharedStringData;
+export class ExcelXmlSharedString implements ISharedStringModel {
+  private readonly _data: ExcelXmlSharedStringData;
 
   private readonly _stringIndexesMap: Map<string, number[]>;
 
   constructor(data?: ExcelXmlSharedStringData) {
     if (data == null) {
-      this.data = {
+      this._data = {
         sst: {
           $: {
             xmlns: "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
@@ -25,11 +27,11 @@ export class ExcelXmlSharedString implements ExcelXml {
         },
       };
     } else {
-      this.data = data;
+      this._data = data;
     }
 
-    this._stringIndexesMap = this.data.sst.si
-      ? this.data.sst.si
+    this._stringIndexesMap = this._data.sst.si
+      ? this._data.sst.si
           .map((tag, id) => ({ id, tag }))
           .filter((item) => !this._getHasInnerStyleOnSiTag(item.tag))
           .toArrayMap(
@@ -39,24 +41,31 @@ export class ExcelXmlSharedString implements ExcelXml {
       : new Map<string, number[]>();
   }
 
+  /** @internal 테스트·디버그용 내부 트리 접근. 상위 레이어는 인터페이스만 사용. */
+  get data(): ExcelXmlSharedStringData {
+    return this._data;
+  }
+
   getIdByString(str: string): number | undefined {
     return this._stringIndexesMap.get(str)?.[0];
   }
 
   getStringById(id: number): string | undefined {
-    const si = this.data.sst.si?.[id];
+    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] });
+    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 {}
+  serialize(): Bytes {
+    return new TextEncoder().encode(xmlU.stringify(this._data));
+  }
 
   private _getStringFromSiTag(si: ExcelXmlSharedStringDataSi): string {
     if ("t" in si) {