@simplysm/excel 1.0.138 → 13.0.0-beta.2

package/dist/core-common/src/utils/xml.d.ts

@@ -0,0 +1,36 @@
+/**
+ * XML 변환 유틸리티
+ */
+import type { XmlBuilderOptions } from "fast-xml-parser";
+/**
+ * XML 문자열을 객체로 파싱
+ * @param str XML 문자열
+ * @param options 옵션
+ * @param options.stripTagPrefix 태그 prefix 제거 여부 (namespace)
+ * @returns 파싱된 객체. 구조:
+ *   - 속성: `$` 객체에 그룹화
+ *   - 텍스트 노드: `_` 키에 저장
+ *   - 자식 요소: 배열로 변환 (루트 요소 제외)
+ * @example
+ * xmlParse('<root id="1"><item>hello</item></root>');
+ * // { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
+ */
+export declare function xmlParse(str: string, options?: {
+    stripTagPrefix?: boolean;
+}): unknown;
+/**
+ * 객체를 XML 문자열로 직렬화
+ * @param obj 직렬화할 객체
+ * @param options fast-xml-parser XmlBuilderOptions (선택)
+ * @returns XML 문자열
+ * @example
+ * xmlStringify({
+ *   root: {
+ *     $: { id: "1" },
+ *     item: [{ _: "hello" }, { _: "world" }],
+ *   },
+ * });
+ * // '<root id="1"><item>hello</item><item>world</item></root>'
+ */
+export declare function xmlStringify(obj: unknown, options?: XmlBuilderOptions): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/core-common/src/utils/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/utils/xml.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAKzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAarF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAS9E"}

package/dist/core-common/src/zip/sd-zip.d.ts

@@ -0,0 +1,80 @@
+import type { Bytes } from "../common.types";
+export interface ZipArchiveProgress {
+    fileName: string;
+    totalSize: number;
+    extractedSize: number;
+}
+/**
+ * ZIP 아카이브 처리 클래스
+ *
+ * ZIP 파일의 읽기, 쓰기, 압축/해제를 처리합니다.
+ * 내부 캐시를 사용하여 동일 파일의 중복 압축 해제를 방지합니다.
+ *
+ * @example
+ * // ZIP 파일 읽기
+ * await using archive = new ZipArchive(zipBytes);
+ * const content = await archive.get("file.txt");
+ *
+ * @example
+ * // ZIP 파일 생성
+ * await using archive = new ZipArchive();
+ * archive.write("file.txt", textBytes);
+ * archive.write("data.json", jsonBytes);
+ * const zipBytes = await archive.compress();
+ *
+ * @example
+ * // 전체 압축 해제 (진행률 표시)
+ * await using archive = new ZipArchive(zipBytes);
+ * const files = await archive.extractAll((progress) => {
+ *   console.log(`${progress.fileName}: ${progress.extractedSize}/${progress.totalSize}`);
+ * });
+ */
+export declare class ZipArchive {
+    private readonly _reader?;
+    private readonly _cache;
+    private _entries?;
+    /**
+     * ZipArchive 생성
+     * @param data ZIP 데이터 (생략 시 새 아카이브 생성)
+     */
+    constructor(data?: Blob | Bytes);
+    private _getEntries;
+    /**
+     * 모든 파일을 압축 해제
+     * @param progressCallback 진행률 콜백
+     */
+    extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
+    /**
+     * 특정 파일 압축 해제
+     * @param fileName 파일 이름
+     */
+    get(fileName: string): Promise<Bytes | undefined>;
+    /**
+     * 파일 존재 여부 확인
+     * @param fileName 파일 이름
+     */
+    exists(fileName: string): Promise<boolean>;
+    /**
+     * 파일 쓰기 (캐시에 저장)
+     * @param fileName 파일 이름
+     * @param bytes 파일 내용
+     */
+    write(fileName: string, bytes: Bytes): void;
+    /**
+     * 캐시된 파일들을 ZIP으로 압축
+     *
+     * @remarks
+     * 내부적으로 `extractAll()`을 호출하여 모든 파일을 메모리에 로드한 후 압축합니다.
+     * 대용량 ZIP 파일의 경우 메모리 사용량에 주의가 필요합니다.
+     */
+    compress(): Promise<Bytes>;
+    /**
+     * 리더 닫기 및 캐시 정리
+     */
+    close(): Promise<void>;
+    /**
+     * await using 지원
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=sd-zip.d.ts.map

package/dist/core-common/src/zip/sd-zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sd-zip.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/zip/sd-zip.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,CAA6D;IAE9E;;;OAGG;gBACS,IAAI,CAAC,EAAE,IAAI,GAAG,KAAK;YAUjB,WAAW;IAQzB;;;OAGG;IACG,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;IAkDpH;;;OAGG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;IAwBvD;;;OAGG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBhD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAM3C;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;IAiBhC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7C"}

package/dist/excel/src/excel-cell.d.ts

@@ -0,0 +1,68 @@
+import type { ZipCache } from "./utils/zip-cache";
+import type { ExcelAddressPoint, ExcelStyleOptions, ExcelValueType } from "./types";
+/**
+ * Excel 셀을 나타내는 클래스.
+ * 값 읽기/쓰기, 수식 설정, 스타일 설정, 셀 병합 등의 기능을 제공한다.
+ *
+ * @remarks
+ * ## 비동기 메서드 설계
+ *
+ * `getVal()`, `setVal()` 등 모든 셀 메서드가 `async`인 이유:
+ * - 셀 타입에 따라 필요한 XML만 선택적으로 로드한다
+ * - 문자열 셀: SharedStrings.xml 로드
+ * - 숫자 셀: SharedStrings 로드 안함
+ * - 스타일이 있는 셀: Styles.xml 로드
+ *
+ * 어떤 셀을 읽을지 미리 알 수 없기 때문에 동기 구조로는 구현할 수 없다.
+ * 동기 구조로 만들려면 모든 XML을 미리 로드해야 하므로 대용량 파일에서 메모리 문제가 발생한다.
+ */
+export declare class ExcelCell {
+    private readonly _zipCache;
+    private readonly _targetFileName;
+    private readonly _r;
+    private readonly _c;
+    /** 셀 주소 (0-based 행/열 인덱스) */
+    readonly addr: ExcelAddressPoint;
+    constructor(_zipCache: ZipCache, _targetFileName: string, _r: number, _c: number);
+    /** 셀에 수식 설정 (undefined: 수식 삭제) */
+    setFormula(val: string | undefined): Promise<void>;
+    /** 셀의 수식 반환 */
+    getFormula(): Promise<string | undefined>;
+    /** 셀 값 설정 (undefined: 셀 삭제) */
+    setVal(val: ExcelValueType): Promise<void>;
+    /** 셀 값 반환 */
+    getVal(): Promise<ExcelValueType>;
+    /**
+     * 현재 셀부터 지정된 끝 좌표까지 셀 병합
+     * @param r 병합 끝 행 인덱스 (0-based)
+     * @param c 병합 끝 열 인덱스 (0-based)
+     * @example
+     * // A1 셀에서 호출하면 A1:C3 범위 (3행 x 3열)를 병합
+     * await ws.cell(0, 0).merge(2, 2);
+     */
+    merge(r: number, c: number): Promise<void>;
+    /** 셀의 스타일 ID 반환 */
+    getStyleId(): Promise<string | undefined>;
+    /** 셀의 스타일 ID 설정 */
+    setStyleId(styleId: string | undefined): Promise<void>;
+    /**
+     * 셀 스타일 설정
+     * @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")
+     */
+    setStyle(opts: ExcelStyleOptions): Promise<void>;
+    private _deleteCell;
+    private _getWsData;
+    private _setStyleInternal;
+    private _getTypeData;
+    private _getSsData;
+    private _getWbRelData;
+    private _getStyleData;
+    private _getOrCreateSsData;
+    private _getOrCreateStyleData;
+}
+//# sourceMappingURL=excel-cell.d.ts.map

package/dist/excel/src/excel-cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-cell.d.ts","sourceRoot":"","sources":["../../../src/excel-cell.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMpF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAGd,SAAS,EAAE,QAAQ,EACnB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM;IAO7B,kCAAkC;IAC5B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD,eAAe;IACT,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,+BAA+B;IACzB,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAmChD,aAAa;IACP,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAkFvC;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,mBAAmB;IACb,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,mBAAmB;IACb,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;;;;OAQG;IACG,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;YAiCxC,WAAW;YAKX,UAAU;YAIV,iBAAiB;YAYjB,YAAY;YAIZ,UAAU;YAIV,aAAa;YAIb,aAAa;YAIb,kBAAkB;YAqBlB,qBAAqB;CAgBpC"}

package/dist/excel/src/excel-col.d.ts

@@ -0,0 +1,19 @@
+import "@simplysm/core-common";
+import { ExcelCell } from "./excel-cell";
+import type { ZipCache } from "./utils/zip-cache";
+/** Excel 워크시트의 열을 나타내는 클래스. 셀 접근 및 열 너비 설정 기능을 제공한다. */
+export declare class ExcelCol {
+    private readonly _zipCache;
+    private readonly _targetFileName;
+    private readonly _c;
+    private readonly _cellMap;
+    constructor(_zipCache: ZipCache, _targetFileName: string, _c: number);
+    /** 행 인덱스에 해당하는 셀 반환 (0-based) */
+    cell(r: number): ExcelCell;
+    /** 열의 모든 셀 반환 */
+    getCells(): Promise<ExcelCell[]>;
+    /** 열 너비 설정 */
+    setWidth(size: number): Promise<void>;
+    private _getWsData;
+}
+//# sourceMappingURL=excel-col.d.ts.map

package/dist/excel/src/excel-col.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-col.d.ts","sourceRoot":"","sources":["../../../src/excel-col.ts"],"names":[],"mappings":"AAAA,OAAO,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,wDAAwD;AACxD,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;IALrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;gBAGtC,SAAS,EAAE,QAAQ,EACnB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM;IAG7B,iCAAiC;IACjC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS;IAI1B,iBAAiB;IACX,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAYtC,cAAc;IACR,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAK7B,UAAU;CAGzB"}

package/dist/excel/src/excel-row.d.ts

@@ -0,0 +1,17 @@
+import "@simplysm/core-common";
+import { ExcelCell } from "./excel-cell";
+import type { ZipCache } from "./utils/zip-cache";
+/** Excel 워크시트의 행을 나타내는 클래스. 셀 접근 기능을 제공한다. */
+export declare class ExcelRow {
+    private readonly _zipCache;
+    private readonly _targetFileName;
+    private readonly _r;
+    private readonly _cellMap;
+    constructor(_zipCache: ZipCache, _targetFileName: string, _r: number);
+    /** 열 인덱스에 해당하는 셀 반환 (0-based) */
+    cell(c: number): ExcelCell;
+    /** 행의 모든 셀 반환 */
+    getCells(): Promise<ExcelCell[]>;
+    private _getWsData;
+}
+//# sourceMappingURL=excel-row.d.ts.map

package/dist/excel/src/excel-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-row.d.ts","sourceRoot":"","sources":["../../../src/excel-row.ts"],"names":[],"mappings":"AAAA,OAAO,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,8CAA8C;AAC9C,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;IALrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;gBAGtC,SAAS,EAAE,QAAQ,EACnB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM;IAG7B,iCAAiC;IACjC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS;IAI1B,iBAAiB;IACX,QAAQ,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YAYxB,UAAU;CAGzB"}

package/dist/excel/src/excel-workbook.d.ts

@@ -0,0 +1,66 @@
+import type { Bytes } from "@simplysm/core-common";
+import { ExcelWorksheet } from "./excel-worksheet";
+import { ZipCache } from "./utils/zip-cache";
+/**
+ * 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 declare class ExcelWorkbook {
+    readonly zipCache: ZipCache;
+    private readonly _wsMap;
+    private _isClosed;
+    /**
+     * @param arg 기존 Excel 파일 데이터 (Blob 또는 Uint8Array). 생략 시 새 워크북을 생성한다.
+     */
+    constructor(arg?: Blob | Bytes);
+    private _ensureNotClosed;
+    /** 워크북의 모든 워크시트 이름을 반환 */
+    getWorksheetNames(): Promise<string[]>;
+    /** 새 워크시트를 생성하고 반환 */
+    createWorksheet(name: string): Promise<ExcelWorksheet>;
+    /** 이름 또는 인덱스(0-based)로 워크시트를 조회 */
+    getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>;
+    /** 워크북을 바이트 배열로 출력 */
+    getBytes(): Promise<Bytes>;
+    /** 워크북을 Blob으로 출력 */
+    getBlob(): Promise<Blob>;
+    /**
+     * 워크북 리소스 해제
+     *
+     * @remarks
+     * ZIP 리더와 내부 캐시를 정리합니다.
+     * 호출 후에는 이 워크북 인스턴스를 사용할 수 없습니다.
+     * 이미 닫힌 워크북에 대해 호출해도 안전합니다 (no-op).
+     */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=excel-workbook.d.ts.map

package/dist/excel/src/excel-workbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-workbook.d.ts","sourceRoot":"","sources":["../../../src/excel-workbook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAO7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;gBACS,GAAG,CAAC,EAAE,IAAI,GAAG,KAAK;IA+B9B,OAAO,CAAC,gBAAgB;IAMxB,0BAA0B;IACpB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAM5C,sBAAsB;IAChB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8B5D,mCAAmC;IAC7B,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuCzE,sBAAsB;IAChB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;IAKhC,qBAAqB;IACf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7C"}

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

@@ -0,0 +1,102 @@
+import type { Bytes } from "@simplysm/core-common";
+import "@simplysm/core-common";
+import type { ExcelCell } from "./excel-cell";
+import { ExcelCol } from "./excel-col";
+import { ExcelRow } from "./excel-row";
+import type { ExcelAddressPoint, ExcelAddressRangePoint, ExcelValueType } from "./types";
+import type { ZipCache } from "./utils/zip-cache";
+/**
+ * Excel 워크시트를 나타내는 클래스.
+ * 셀 접근, 행/열 복사, 데이터 테이블 처리, 이미지 삽입 등의 기능을 제공한다.
+ */
+export declare class ExcelWorksheet {
+    private readonly _zipCache;
+    private readonly _relId;
+    private readonly _targetFileName;
+    private readonly _rowMap;
+    private readonly _colMap;
+    constructor(_zipCache: ZipCache, _relId: number, _targetFileName: string);
+    /** 워크시트 이름 반환 */
+    getName(): Promise<string>;
+    /** 워크시트 이름 변경 */
+    setName(newName: string): Promise<void>;
+    /** 행 객체 반환 (0-based) */
+    row(r: number): ExcelRow;
+    /** 셀 객체 반환 (0-based 행/열) */
+    cell(r: number, c: number): ExcelCell;
+    /** 열 객체 반환 (0-based) */
+    col(c: number): ExcelCol;
+    /** 소스 행의 스타일을 타겟 행에 복사 */
+    copyRowStyle(srcR: number, targetR: number): Promise<void>;
+    /** 소스 셀의 스타일을 타겟 셀에 복사 */
+    copyCellStyle(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
+    /** 소스 행을 타겟 행에 복사 (덮어쓰기) */
+    copyRow(srcR: number, targetR: number): Promise<void>;
+    /** 소스 셀을 타겟 셀에 복사 */
+    copyCell(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
+    /**
+     * 소스 행을 타겟 위치에 삽입 복사.
+     * 타겟 위치 이하의 기존 행들은 한 칸씩 아래로 밀린다.
+     * @param srcR 복사할 소스 행 인덱스 (0-based)
+     * @param targetR 삽입할 타겟 행 인덱스 (0-based)
+     */
+    insertCopyRow(srcR: number, targetR: number): Promise<void>;
+    /** 워크시트의 데이터 범위 반환 */
+    getRange(): Promise<ExcelAddressRangePoint>;
+    /** 워크시트의 모든 셀을 2차원 배열로 반환 */
+    getCells(): Promise<ExcelCell[][]>;
+    /**
+     * 워크시트 데이터를 테이블(레코드 배열) 형식으로 반환.
+     * @param opt.headerRowIndex 헤더 행 인덱스 (기본값: 첫 번째 행)
+     * @param opt.checkEndColIndex 데이터 종료를 판단할 열 인덱스. 해당 열이 비어있으면 데이터 끝으로 간주
+     * @param opt.usableHeaderNameFn 사용할 헤더를 필터링하는 함수
+     */
+    getDataTable(opt?: {
+        headerRowIndex?: number;
+        checkEndColIndex?: number;
+        usableHeaderNameFn?: (headerName: string) => boolean;
+    }): Promise<Record<string, ExcelValueType>[]>;
+    /**
+     * 2차원 배열 데이터를 워크시트에 기록
+     * @param matrix 2차원 배열 데이터 (행 우선, 0번 인덱스가 첫 번째 행)
+     */
+    setDataMatrix(matrix: ExcelValueType[][]): Promise<void>;
+    /**
+     * 레코드 배열을 워크시트에 기록
+     * @param records 레코드 배열. 첫 행에 헤더가 자동 생성되고, 이후 행에 데이터가 기록된다.
+     */
+    setRecords(records: Record<string, ExcelValueType>[]): Promise<void>;
+    /** 워크시트 확대/축소 비율 설정 (퍼센트) */
+    setZoom(percent: number): Promise<void>;
+    /** 행/열 틀 고정 설정 */
+    setFix(point: {
+        r?: number;
+        c?: number;
+    }): Promise<void>;
+    /**
+     * 워크시트에 이미지를 삽입.
+     * @param opts.bytes 이미지 바이너리 데이터
+     * @param opts.ext 이미지 확장자 (png, jpg 등)
+     * @param opts.from 이미지 시작 위치 (0-based 행/열 인덱스, rOff/cOff는 EMU 단위 오프셋)
+     * @param opts.to 이미지 끝 위치 (생략 시 from 위치에 원본 크기로 삽입)
+     */
+    addImage(opts: {
+        bytes: Bytes;
+        ext: string;
+        from: {
+            r: number;
+            c: number;
+            rOff?: number | string;
+            cOff?: number | string;
+        };
+        to?: {
+            r: number;
+            c: number;
+            rOff?: number | string;
+            cOff?: number | string;
+        };
+    }): Promise<void>;
+    private _getWsData;
+    private _getWbData;
+}
+//# sourceMappingURL=excel-worksheet.d.ts.map

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

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

package/dist/excel/src/excel-wrapper.d.ts

@@ -0,0 +1,42 @@
+import type { Bytes } from "@simplysm/core-common";
+import { type z } from "zod";
+import { ExcelWorkbook } from "./excel-workbook";
+/**
+ * Zod 스키마 기반 Excel 래퍼
+ *
+ * 스키마에서 타입 정보를 추론하여 타입 안전한 읽기/쓰기 제공
+ */
+export declare class ExcelWrapper<T extends z.ZodObject<z.ZodRawShape>> {
+    private readonly _schema;
+    private readonly _displayNameMap;
+    /**
+     * @param _schema Zod 스키마 (레코드 구조 정의)
+     * @param _displayNameMap 필드명-표시명 매핑 (Excel 헤더로 사용)
+     */
+    constructor(_schema: T, _displayNameMap: Record<keyof z.infer<T>, string>);
+    /**
+     * Excel 파일 읽기 → 레코드 배열
+     */
+    read(file: Bytes | Blob, wsNameOrIndex?: string | number): Promise<z.infer<T>[]>;
+    /**
+     * 레코드 배열 → Excel 워크북
+     *
+     * @remarks
+     * 반환된 워크북은 호출자가 리소스를 관리해야 합니다.
+     * `await using`을 사용하거나 작업 완료 후 `close()`를 호출하세요.
+     *
+     * @example
+     * ```typescript
+     * await using wb = await wrapper.write("Sheet1", records);
+     * const bytes = await wb.getBytes();
+     * ```
+     */
+    write(wsName: string, records: Partial<z.infer<T>>[]): Promise<ExcelWorkbook>;
+    private _getReverseDisplayNameMap;
+    private _convertValue;
+    private _unwrapSchema;
+    private _getDefaultForSchema;
+    private _isRequired;
+    private _isBoolean;
+}
+//# sourceMappingURL=excel-wrapper.d.ts.map

package/dist/excel/src/excel-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-wrapper.d.ts","sourceRoot":"","sources":["../../../src/excel-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,KAAK,CAAC,EAA0E,MAAM,KAAK,CAAC;AACrG,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD;;;;GAIG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;IAM1D,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,eAAe;IANlC;;;OAGG;gBAEgB,OAAO,EAAE,CAAC,EACV,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAGpE;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,aAAa,GAAE,MAAM,GAAG,MAAU,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAmDzF;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAoDnF,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,oBAAoB;IAmB5B,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;CAMnB"}

package/dist/excel/src/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types";
+export * from "./utils/excel-utils";
+export * from "./excel-cell";
+export * from "./excel-row";
+export * from "./excel-col";
+export * from "./excel-worksheet";
+export * from "./excel-workbook";
+export * from "./excel-wrapper";
+//# sourceMappingURL=index.d.ts.map

package/dist/excel/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAC;AACxB,cAAc,qBAAqB,CAAC;AAGpC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,iBAAiB,CAAC"}