@simplysm/excel 13.0.100 → 14.0.4

package/README.md

@@ -1,6 +1,8 @@
 # @simplysm/excel
 
-Excel file processing library. Platform-neutral (works in both browser and Node.js).
+Excel file processing library -- read/write .xlsx files with cell styling, formulas, images, and Zod schema-based typed wrapper.
+
+Platform: neutral (Node.js and browser).
 
 ## Installation
 
@@ -10,92 +12,54 @@ npm install @simplysm/excel
 
 ## API Overview
 
-### Types
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ExcelValueType` | type | Union of supported cell value types (`number`, `string`, `DateOnly`, `DateTime`, `Time`, `boolean`, `undefined`) |
-| `ExcelNumberFormat` | type | Number format name (`"number"`, `"string"`, `"DateOnly"`, `"DateTime"`, `"Time"`) |
-| `ExcelCellType` | type | Cell type identifier (`"s"`, `"b"`, `"str"`, `"n"`, `"inlineStr"`, `"e"`) |
-| `ExcelAddressPoint` | interface | Cell coordinate (`r`, `c`, 0-based) |
-| `ExcelAddressRangePoint` | interface | Range of cell coordinates (`s`, `e`) |
-| `ExcelBorderPosition` | type | Border position (`"left"`, `"right"`, `"top"`, `"bottom"`) |
-| `ExcelHorizontalAlign` | type | Horizontal alignment (`"center"`, `"left"`, `"right"`) |
-| `ExcelVerticalAlign` | type | Vertical alignment (`"center"`, `"top"`, `"bottom"`) |
-| `ExcelStyleOptions` | interface | Cell style options (`background`, `border`, `horizontalAlign`, `verticalAlign`, `numberFormat`) |
-| `ExcelXml` | interface | Excel XML interface (`data`, `cleanup()`) |
-| `ExcelXmlContentTypeData` | interface | Content type XML data |
-| `ExcelXmlRelationshipData` | interface | Relationship XML data |
-| `ExcelRelationshipData` | interface | Single relationship data |
-| `ExcelXmlWorkbookData` | interface | Workbook XML data |
-| `ExcelXmlWorksheetData` | interface | Worksheet XML data |
-| `ExcelRowData` | interface | Row XML data |
-| `ExcelCellData` | interface | Cell XML data |
-| `ExcelXmlDrawingData` | interface | Drawing XML data |
-| `ExcelXmlSharedStringData` | interface | Shared strings XML data |
-| `ExcelXmlSharedStringDataSi` | type | Shared string item |
-| `ExcelXmlSharedStringDataText` | type | Shared string text |
-| `ExcelXmlStyleData` | interface | Style XML data |
-| `ExcelXmlStyleDataXf` | interface | Cell format definition |
-| `ExcelXmlStyleDataFill` | interface | Fill style definition |
-| `ExcelXmlStyleDataBorder` | interface | Border style definition |
-
--> See [docs/types.md](./docs/types.md) for details.
-
-### Utilities
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ExcelUtils` | class | Cell address conversion, date/number conversion, number format processing |
-
--> See [docs/utilities.md](./docs/utilities.md) for details.
-
-### Core Classes
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ExcelWorkbook` | class | Workbook processing with lazy-loading ZIP architecture |
-| `ExcelWorksheet` | class | Worksheet with cell access, copying, data tables, images |
-| `ExcelRow` | class | Row with cell access |
-| `ExcelCol` | class | Column with cell access and width configuration |
-| `ExcelCell` | class | Cell with value, formula, style, and merge operations |
-
--> See [docs/core-classes.md](./docs/core-classes.md) for details.
-
-### Wrapper
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ExcelWrapper` | class | Zod schema-based type-safe Excel read/write |
-
--> See [docs/wrapper.md](./docs/wrapper.md) for details.
-
-## Usage Examples
-
-### Create a new workbook
+| Category | Items | Documentation |
+|---|---|---|
+| Types & Utilities | ExcelXmlContentTypeData, ExcelXmlRelationshipData, ExcelRelationshipData, ExcelXmlWorkbookData, ExcelXmlWorksheetData, ExcelRowData, ExcelCellData, ExcelXmlDrawingData, ExcelXmlSharedStringData, ExcelXmlSharedStringDataSi, ExcelXmlSharedStringDataText, ExcelXmlStyleData, ExcelXmlStyleDataXf, ExcelXmlStyleDataFill, ExcelXmlStyleDataBorder, ExcelValueType, ExcelNumberFormat, ExcelCellType, ExcelAddressPoint, ExcelAddressRangePoint, ExcelXml, ExcelBorderPosition, ExcelHorizontalAlign, ExcelVerticalAlign, ExcelStyleOptions, ExcelUtils | [docs/types.md](docs/types.md) |
+| Core Classes | ExcelCell, ExcelRow, ExcelCol, ExcelWorksheet, ExcelWorkbook | [docs/core.md](docs/core.md) |
+| Wrapper | ExcelWrapper | [docs/wrapper.md](docs/wrapper.md) |
+
+## Quick Start
+
+### Read an existing Excel file
+
+```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+
+await using wb = new ExcelWorkbook(fileBytes);
+const ws = await wb.getWorksheet(0);
+
+// Read a single cell
+const value = await ws.cell(0, 0).getValue();
+
+// Read as data table (first row = headers)
+const records = await ws.getDataTable();
+// records: Record<string, ExcelValueType>[]
+```
+
+### Create a new Excel file
 
 ```typescript
 import { ExcelWorkbook } from "@simplysm/excel";
 
 await using wb = new ExcelWorkbook();
 const ws = await wb.addWorksheet("Sheet1");
+
 await ws.cell(0, 0).setValue("Name");
 await ws.cell(0, 1).setValue("Age");
 await ws.cell(1, 0).setValue("Alice");
 await ws.cell(1, 1).setValue(30);
-const bytes = await wb.toBytes();
-```
 
-### Read an existing workbook
+// Apply styling
+await ws.cell(0, 0).setStyle({
+  background: "00FFFF00",
+  border: ["left", "right", "top", "bottom"],
+  horizontalAlign: "center",
+});
 
-```typescript
-await using wb = new ExcelWorkbook(fileBytes);
-const ws = await wb.getWorksheet(0);
-const value = await ws.cell(0, 0).getValue();
-const dataTable = await ws.getDataTable();
+const bytes = await wb.toBytes();
 ```
 
-### Type-safe read/write with Zod schema
+### Typed read/write with Zod schema
 
 ```typescript
 import { z } from "zod";
@@ -104,16 +68,40 @@ import { ExcelWrapper } from "@simplysm/excel";
 const schema = z.object({
   name: z.string().describe("Name"),
   age: z.number().describe("Age"),
+  active: z.boolean().describe("Active").default(false),
 });
 
 const wrapper = new ExcelWrapper(schema);
 
-// Read
+// Read with type safety and validation
 const records = await wrapper.read(fileBytes);
 
-// Write
-await using wb = await wrapper.write("Sheet1", [
-  { name: "Alice", age: 30 },
-]);
+// Write with automatic header/style generation
+await using wb = await wrapper.write("Sheet1", records);
 const bytes = await wb.toBytes();
 ```
+
+### Insert an image
+
+```typescript
+await ws.addImage({
+  bytes: imageBytes,
+  ext: "png",
+  from: { r: 1, c: 1 },
+  to: { r: 5, c: 3 },
+});
+```
+
+### Row operations
+
+```typescript
+// Copy a row (overwrite)
+await ws.copyRow(0, 5);
+
+// Insert-copy a row (shifts existing rows down)
+await ws.insertCopyRow(0, 3);
+
+// Freeze header row and set zoom
+await ws.freezeAt({ r: 0 });
+await ws.setZoom(85);
+```

package/dist/excel-cell.d.ts

@@ -1,58 +1,58 @@
 import type { ZipCache } from "./utils/zip-cache";
 import type { ExcelAddressPoint, ExcelStyleOptions, ExcelValueType } from "./types";
 /**
- * Class representing an Excel cell.
- * Provides value read/write, formula, style, and cell merge functionality.
+ * Excel 셀을 나타내는 클래스.
+ * 값 읽기/쓰기, 수식, 스타일, 셀 병합 기능을 제공한다.
  *
  * @remarks
- * ## Async Method Design
+ * ## 비동기 메서드 설계
  *
- * Why all cell methods like `getValue()`, `setValue()` are `async`:
- * - Only the XML needed for the cell type is selectively loaded
- * - String cell: loads SharedStrings.xml
- * - Number cell: does not load SharedStrings
- * - Styled cell: loads Styles.xml
+ * `getValue()`, `setValue()` 등 모든 셀 메서드가 `async`인 이유:
+ * - 셀 타입에 필요한 XML만 선택적으로 로드함
+ * - 문자열 셀: SharedStrings.xml 로드
+ * - 숫자 셀: SharedStrings 로드하지 않음
+ * - 스타일 적용 셀: Styles.xml 로드
  *
- * Since the cell to be read cannot be known in advance, a synchronous design is not feasible.
- * A synchronous design would require preloading all XML, causing memory issues with large files.
+ * 읽을 셀을 사전에 알 수 없으므로 동기 설계가 불가능하다.
+ * 동기 설계는 모든 XML을 미리 로드해야 하므로 대용량 파일에서 메모리 문제가 발생한다.
  */
 export declare class ExcelCell {
     private readonly _zipCache;
     private readonly _targetFileName;
     private readonly _r;
     private readonly _c;
-    /** Cell address (0-based row/column index) */
+    /** 셀 주소 (0 기반 행/열 인덱스) */
     readonly addr: ExcelAddressPoint;
     constructor(_zipCache: ZipCache, _targetFileName: string, _r: number, _c: number);
-    /** Set formula on cell (undefined: remove formula) */
+    /** 셀에 수식 설정 (undefined: 수식 제거) */
     setFormula(val: string | undefined): Promise<void>;
-    /** Return cell formula */
+    /** 셀 수식 반환 */
     getFormula(): Promise<string | undefined>;
-    /** Set cell value (undefined: delete cell) */
+    /** 셀 값 설정 (undefined: 셀 삭제) */
     setValue(val: ExcelValueType): Promise<void>;
-    /** Return cell value */
+    /** 셀 값 반환 */
     getValue(): Promise<ExcelValueType>;
     /**
-     * Merge cells from current cell to the specified end coordinates
-     * @param r End row index of merge (0-based)
-     * @param c End column index of merge (0-based)
+     * 현재 셀에서 지정된 끝 좌표까지 셀 병합
+     * @param r 병합 끝 행 인덱스 (0 기반)
+     * @param c 병합 끝 열 인덱스 (0 기반)
      * @example
-     * // Called from cell A1, merges range A1:C3 (3 rows x 3 columns)
+     * // A1 셀에서 호출하여 A1:C3 범위 병합 (3행 x 3열)
      * await ws.cell(0, 0).merge(2, 2);
      */
     merge(r: number, c: number): Promise<void>;
-    /** Return cell style ID */
+    /** 셀 스타일 ID 반환 */
     getStyleId(): Promise<string | undefined>;
-    /** Set cell style ID */
+    /** 셀 스타일 ID 설정 */
     setStyleId(styleId: string | undefined): Promise<void>;
     /**
-     * Set cell style
-     * @param opts Style options
-     * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "00FF0000")
-     * @param opts.border Border position array (e.g. ["left", "right", "top", "bottom"])
-     * @param opts.horizontalAlign Horizontal alignment ("left", "center", "right")
-     * @param opts.verticalAlign Vertical alignment ("top", "center", "bottom")
-     * @param opts.numberFormat Number format ("number", "DateOnly", "DateTime", "Time", "string")
+     * 셀 스타일 설정
+     * @param opts 스타일 옵션
+     * @param opts.background 배경색 (ARGB 형식, 8자리 16진수. 예: "00FF0000")
+     * @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;

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

@@ -1 +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;AAYpF;;;;;;;;;;;;;;;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,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAGd,SAAS,EAAE,QAAQ,EACnB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM;IAO7B,sDAAsD;IAChD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD,0BAA0B;IACpB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,8CAA8C;IACxC,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAwClD,wBAAwB;IAClB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFzC;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,2BAA2B;IACrB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,wBAAwB;IAClB,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;CAsBpC"}
+{"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;AAYpF;;;;;;;;;;;;;;;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,0BAA0B;IAC1B,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,cAAc;IACR,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,+BAA+B;IACzB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAwClD,aAAa;IACP,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFzC;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,kBAAkB;IACZ,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,kBAAkB;IACZ,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;CAsBpC"}