@simplysm/excel 13.0.69 → 13.0.71

package/README.md

@@ -1,532 +1,35 @@
 # @simplysm/excel
 
-A TypeScript library for reading and writing Excel files (.xlsx). It works in both Node.js and browser environments, and internally uses a ZIP-based Lazy Loading structure for memory-efficient operation even with large files.
+Excel file processing library
 
 ## Installation
 
-```bash
-npm install @simplysm/excel
-# or
-yarn add @simplysm/excel
-# or
 pnpm add @simplysm/excel
-```
 
-## Main Modules
+## Source Index
 
-### Core Classes
+### Types and utilities
 
-| Class | Description |
-|--------|------|
-| `ExcelWorkbook` | Workbook creation, opening, exporting, resource management |
-| `ExcelWorksheet` | Worksheet access, data read/write, image insertion, view settings |
-| `ExcelRow` | Row-level cell access |
-| `ExcelCol` | Column-level cell access and width settings |
-| `ExcelCell` | Cell value, formula, style, merge handling |
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/types.ts` | `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` | All shared XML data types, value types, address types, and style option interfaces | - |
+| `src/utils/excel-utils.ts` | `ExcelUtils` | Utility functions for address conversion, date/number format mapping | `excel-utils.spec.ts` |
 
-### Wrapper Classes
+### Core classes
 
-| Class | Description |
-|--------|------|
-| `ExcelWrapper` | Type-safe Excel data conversion based on Zod schemas |
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/excel-cell.ts` | `ExcelCell` | Single cell with value, formula, style, and merge operations | `excel-cell.spec.ts` |
+| `src/excel-row.ts` | `ExcelRow` | Row container providing cell access by column index | `excel-row.spec.ts` |
+| `src/excel-col.ts` | `ExcelCol` | Column container providing cell access and column width setting | `excel-col.spec.ts` |
+| `src/excel-worksheet.ts` | `ExcelWorksheet` | Worksheet with cell/row/col access, copy, data table, and image support | `excel-worksheet.spec.ts` |
+| `src/excel-workbook.ts` | `ExcelWorkbook` | Workbook with lazy-loading ZIP, worksheet management, and export | `excel-workbook.spec.ts` |
 
-### Utilities
+### Wrapper classes
 
-| Class | Description |
-|--------|------|
-| `ExcelUtils` | Cell address conversion, date/number conversion, number format handling |
-
-### Types
-
-| Type | Description |
-|------|------|
-| `ExcelValueType` | Cell value type (`number \| string \| DateOnly \| DateTime \| Time \| boolean \| undefined`) |
-| `ExcelNumberFormat` | Number format (`"number" \| "string" \| "DateOnly" \| "DateTime" \| "Time"`) |
-| `ExcelCellType` | Cell internal type (`"s" \| "b" \| "str" \| "n" \| "inlineStr" \| "e"`) |
-| `ExcelStyleOptions` | Cell style options (background color, border, alignment, number format) |
-| `ExcelBorderPosition` | Border position (`"left" \| "right" \| "top" \| "bottom"`) |
-| `ExcelHorizontalAlign` | Horizontal alignment (`"center" \| "left" \| "right"`) |
-| `ExcelVerticalAlign` | Vertical alignment (`"center" \| "top" \| "bottom"`) |
-| `ExcelAddressPoint` | Cell coordinates (`{ r: number; c: number }`) |
-| `ExcelAddressRangePoint` | Range coordinates (`{ s: ExcelAddressPoint; e: ExcelAddressPoint }`) |
-| `ExcelXml` | Interface for internal XML data objects (`{ readonly data: unknown; cleanup(): void }`) |
-
-## Usage
-
-### Creating a New Workbook and Writing Cell Values
-
-```typescript
-import { ExcelWorkbook } from "@simplysm/excel";
-
-const wb = new ExcelWorkbook();
-const ws = await wb.createWorksheet("Sheet1");
-
-// Set cell values (both row and column are 0-based indices)
-await ws.cell(0, 0).setVal("Name");
-await ws.cell(0, 1).setVal("Age");
-await ws.cell(1, 0).setVal("John Doe");
-await ws.cell(1, 1).setVal(30);
-
-// Export as Uint8Array
-const bytes = await wb.getBytes();
-
-// Or export as Blob (useful for browser downloads)
-const blob = await wb.getBlob();
-
-// Release resources (required)
-await wb.close();
-```
-
-### Reading an Existing File
-
-```typescript
-import { ExcelWorkbook } from "@simplysm/excel";
-
-// Open workbook from Uint8Array or Blob
-const wb = new ExcelWorkbook(bytes);
-
-// Access worksheet by index (0-based)
-const ws = await wb.getWorksheet(0);
-
-// Or access worksheet by name
-const wsByName = await wb.getWorksheet("Sheet1");
-
-// Read cell values
-const name = await ws.cell(0, 0).getVal();   // string | number | boolean | DateOnly | DateTime | Time | undefined
-const age = await ws.cell(0, 1).getVal();
-
-// Get list of worksheet names
-const sheetNames = await wb.getWorksheetNames();
-
-await wb.close();
-```
-
-### Resource Management (await using)
-
-`ExcelWorkbook` implements `Symbol.asyncDispose` for automatic resource cleanup with the `await using` syntax.
-
-```typescript
-import { ExcelWorkbook } from "@simplysm/excel";
-
-// close() is automatically called when the scope ends
-await using wb = new ExcelWorkbook(bytes);
-const ws = await wb.getWorksheet(0);
-const value = await ws.cell(0, 0).getVal();
-```
-
-If you don't use `await using`, you must release resources with `try-finally`.
-
-```typescript
-const wb = new ExcelWorkbook(bytes);
-try {
-  const ws = await wb.getWorksheet(0);
-  // ... perform operations
-} finally {
-  await wb.close();
-}
-```
-
-### Setting Cell Styles
-
-```typescript
-const cell = ws.cell(0, 0);
-
-// Background color (ARGB 8-digit hexadecimal: AA=alpha, RR=red, GG=green, BB=blue)
-await cell.setStyle({ background: "FFFF0000" });  // Red (opaque)
-await cell.setStyle({ background: "00FFFF00" });  // Yellow
-
-// Border
-await cell.setStyle({ border: ["left", "right", "top", "bottom"] });
-
-// Alignment
-await cell.setStyle({
-  horizontalAlign: "center",
-  verticalAlign: "center",
-});
-
-// Number format
-await cell.setStyle({ numberFormat: "number" });
-await cell.setStyle({ numberFormat: "DateOnly" });
-await cell.setStyle({ numberFormat: "DateTime" });
-await cell.setStyle({ numberFormat: "Time" });
-await cell.setStyle({ numberFormat: "string" });
-
-// Apply multiple styles at once
-await cell.setStyle({
-  background: "FFFF0000",
-  border: ["left", "right", "top", "bottom"],
-  horizontalAlign: "center",
-  verticalAlign: "center",
-  numberFormat: "number",
-});
-```
-
-### Formulas
-
-```typescript
-await ws.cell(0, 0).setVal(10);
-await ws.cell(0, 1).setVal(20);
-await ws.cell(0, 2).setFormula("A1+B1");  // Result: 30
-
-// Read formula
-const formula = await ws.cell(0, 2).getFormula();  // "A1+B1"
-
-// Delete formula
-await ws.cell(0, 2).setFormula(undefined);
-```
-
-### Cell Merging
-
-```typescript
-await ws.cell(0, 0).setVal("Merged Cell");
-
-// Merge from current cell (0,0) to (2,3) (3 rows x 4 columns area, i.e. A1:D3)
-await ws.cell(0, 0).merge(2, 3);
-```
-
-The arguments of the `merge(r, c)` method are the 0-based row/column indices of the merge endpoint.
-
-### Setting Column Width
-
-```typescript
-// Set width of column 0 (column A) to 20
-await ws.col(0).setWidth(20);
-```
-
-### Copying Rows/Cells
-
-```typescript
-// Copy only the style of row 0 to row 2
-await ws.copyRowStyle(0, 2);
-
-// Copy entire row 0 to row 2 (values + styles)
-await ws.copyRow(0, 2);
-
-// Copy individual cell
-await ws.copyCell({ r: 0, c: 0 }, { r: 1, c: 1 });
-
-// Insert copy of source row at target position (existing rows shift down)
-await ws.insertCopyRow(0, 3);
-```
-
-### Reading Data Table (getDataTable)
-
-Converts worksheet data into a header-based record array. Uses the first row as headers and returns in `Record<string, ExcelValueType>[]` format.
-
-```typescript
-// Basic usage: first row is header
-const data = await ws.getDataTable();
-// [{ "Name": "John Doe", "Age": 30 }, { "Name": "Jane Smith", "Age": 25 }]
-
-// Specify header row index
-const data2 = await ws.getDataTable({ headerRowIndex: 2 });
-
-// Determine end of data when specific column is empty
-const data3 = await ws.getDataTable({ checkEndColIndex: 0 });
-
-// Filter to only use certain headers
-const data4 = await ws.getDataTable({
-  usableHeaderNameFn: (name) => ["Name", "Age"].includes(name),
-});
-```
-
-### Writing Data (setDataMatrix / setRecords)
-
-```typescript
-// Write as 2D array
-await ws.setDataMatrix([
-  ["Name", "Age"],
-  ["John Doe", 30],
-  ["Jane Smith", 25],
-]);
-
-// Write as record array (automatic header generation)
-await ws.setRecords([
-  { "Name": "John Doe", "Age": 30 },
-  { "Name": "Jane Smith", "Age": 25 },
-]);
-```
-
-### Inserting Images
-
-```typescript
-await ws.addImage({
-  bytes: imageBytes,   // Uint8Array
-  ext: "png",          // Extension (png, jpg, etc.)
-  from: { r: 0, c: 0 },                  // Start position (0-based)
-  to: { r: 5, c: 3 },                    // End position (0-based)
-});
-
-// Specify offset in EMU (English Metric Units)
-await ws.addImage({
-  bytes: imageBytes,
-  ext: "jpg",
-  from: { r: 0, c: 0, rOff: 0, cOff: 0 },
-  to: { r: 5, c: 3, rOff: 100000, cOff: 100000 },
-});
-
-// If 'to' is omitted, inserts at 'from' position with 1 cell size
-await ws.addImage({
-  bytes: imageBytes,
-  ext: "png",
-  from: { r: 0, c: 0 },
-});
-```
-
-### View Settings
-
-```typescript
-// Set zoom level (percentage)
-await ws.setZoom(85);
-
-// Freeze rows/columns
-await ws.setFix({ r: 0 });          // Freeze first row
-await ws.setFix({ c: 0 });          // Freeze first column
-await ws.setFix({ r: 0, c: 0 });    // Freeze first row + column
-```
-
-### Worksheet Name Management
-
-```typescript
-const name = await ws.getName();
-await ws.setName("New Sheet Name");
-```
-
-### ExcelWrapper (Zod Schema-based Wrapper)
-
-`ExcelWrapper` is a wrapper class that allows type-safe reading and writing of Excel data based on Zod schemas.
-
-```typescript
-import { z } from "zod";
-import { ExcelWrapper } from "@simplysm/excel";
-
-// Define schema (use .describe() for Excel header names; defaults to field key if omitted)
-const schema = z.object({
-  name: z.string().describe("Name"),
-  age: z.number().describe("Age"),
-  email: z.string().optional().describe("Email"),
-  active: z.boolean().describe("Active Status"),
-});
-
-const wrapper = new ExcelWrapper(schema);
-```
-
-#### Writing to Excel
-
-```typescript
-const records = [
-  { name: "John Doe", age: 30, email: "john@test.com", active: true },
-  { name: "Jane Smith", age: 25, active: false },
-];
-
-// write() accepts Partial records and returns ExcelWorkbook, so resource management is required
-await using wb = await wrapper.write("Users", records);
-const bytes = await wb.getBytes();
-
-// Exclude specific fields from the output
-await using wb2 = await wrapper.write("Users", records, { excludes: ["email"] });
-```
-
-The `write()` method automatically applies the following formatting:
-- Borders on all cells
-- Yellow background on required field headers (fields without optional/nullable/default)
-- 85% zoom, freeze first row
-
-#### Reading from Excel
-
-```typescript
-// Read records from file (Uint8Array or Blob)
-const records = await wrapper.read(bytes);
-// records: { name: string; age: number; email?: string; active: boolean }[]
-
-// Specify worksheet name or index
-const records2 = await wrapper.read(bytes, "Users");
-const records3 = await wrapper.read(bytes, 0);
-
-// Exclude specific fields when reading
-const records4 = await wrapper.read(bytes, 0, { excludes: ["email"] });
-```
-
-Behavior of the `read()` method:
-- Only reads headers defined in the schema (via `.describe()` or field key names)
-- Skips rows where all values are empty
-- Validates each row with the Zod schema, throws error on validation failure
-- Throws error if there is no data
-- Automatic type conversion: string -> number, string -> boolean ("1"/"true" -> true), etc.
-
-## ExcelUtils API
-
-| Method | Input | Output | Description |
-|--------|------|------|------|
-| `stringifyAddr(point)` | `{ r: 0, c: 0 }` | `"A1"` | Convert coordinates to cell address string |
-| `stringifyRowAddr(r)` | `0` | `"1"` | Convert row index to row address |
-| `stringifyColAddr(c)` | `0` | `"A"` | Convert column index to column address (0~16383) |
-| `parseCellAddrCode(addr)` | `"B3"` | `{ r: 2, c: 1 }` | Convert cell address to coordinates |
-| `parseRowAddrCode(addr)` | `"A3"` | `2` | Extract row index from cell address |
-| `parseColAddrCode(addr)` | `"B3"` | `1` | Extract column index from cell address |
-| `parseRangeAddrCode(range)` | `"A1:C3"` | `{ s: {r:0,c:0}, e: {r:2,c:2} }` | Convert range address to coordinates |
-| `stringifyRangeAddr(point)` | `{ s: {r:0,c:0}, e: {r:2,c:2} }` | `"A1:C3"` | Convert range coordinates to address string |
-| `convertTimeTickToNumber(tick)` | JS timestamp (ms) | Excel date number | Convert JS date to Excel number |
-| `convertNumberToTimeTick(num)` | Excel date number | JS timestamp (ms) | Convert Excel number to JS date |
-| `convertNumFmtIdToName(id)` | Format ID | `ExcelNumberFormat` | Convert built-in format ID to name |
-| `convertNumFmtCodeToName(code)` | Format code | `ExcelNumberFormat` | Convert format code to name |
-| `convertNumFmtNameToId(name)` | `ExcelNumberFormat` | Format ID | Convert format name to ID |
-
-## ExcelRow API
-
-| Method | Return Type | Description |
-|--------|-----------|------|
-| `cell(c)` | `ExcelCell` | Get cell at column index (0-based) |
-| `getCells()` | `Promise<ExcelCell[]>` | Get all cells in the row |
-
-## ExcelCol API
-
-| Method | Return Type | Description |
-|--------|-----------|------|
-| `cell(r)` | `ExcelCell` | Get cell at row index (0-based) |
-| `getCells()` | `Promise<ExcelCell[]>` | Get all cells in the column |
-| `setWidth(size)` | `Promise<void>` | Set column width |
-
-## ExcelCell API
-
-| Member | Type / Return Type | Description |
-|--------|-----------|------|
-| `addr` | `ExcelAddressPoint` (readonly) | Cell address as 0-based row/column indices |
-| `getVal()` | `Promise<ExcelValueType>` | Get cell value |
-| `setVal(val)` | `Promise<void>` | Set cell value (deletes cell if undefined) |
-| `getFormula()` | `Promise<string \| undefined>` | Get formula |
-| `setFormula(val)` | `Promise<void>` | Set formula (deletes formula if undefined) |
-| `setStyle(opts)` | `Promise<void>` | Set style |
-| `merge(r, c)` | `Promise<void>` | Merge from current cell to (r, c) |
-| `getStyleId()` | `Promise<string \| undefined>` | Get style ID |
-| `setStyleId(id)` | `Promise<void>` | Directly set style ID |
-
-## ExcelWorksheet API
-
-| Method | Return Type | Description |
-|--------|-----------|------|
-| `cell(r, c)` | `ExcelCell` | Get cell object (0-based) |
-| `row(r)` | `ExcelRow` | Get row object (0-based) |
-| `col(c)` | `ExcelCol` | Get column object (0-based) |
-| `getName()` | `Promise<string>` | Get worksheet name |
-| `setName(name)` | `Promise<void>` | Change worksheet name |
-| `getRange()` | `Promise<ExcelAddressRangePoint>` | Get data range |
-| `getCells()` | `Promise<ExcelCell[][]>` | Get all cells as 2D array |
-| `getDataTable(opt?)` | `Promise<Record<string, ExcelValueType>[]>` | Convert to header-based record array |
-| `setDataMatrix(matrix)` | `Promise<void>` | Write 2D array data |
-| `setRecords(records)` | `Promise<void>` | Write record array (automatic header generation) |
-| `copyRow(src, target)` | `Promise<void>` | Copy row |
-| `copyRowStyle(src, target)` | `Promise<void>` | Copy only row style |
-| `copyCell(src, target)` | `Promise<void>` | Copy cell |
-| `copyCellStyle(src, target)` | `Promise<void>` | Copy only cell style |
-| `insertCopyRow(src, target)` | `Promise<void>` | Insert copy of row (existing rows shift) |
-| `addImage(opts)` | `Promise<void>` | Insert image |
-| `setZoom(percent)` | `Promise<void>` | Set zoom level |
-| `setFix(point)` | `Promise<void>` | Set freeze panes |
-
-## ExcelWorkbook API
-
-| Member | Type / Return Type | Description |
-|--------|-----------|------|
-| `constructor(arg?)` | — | Create a new workbook (no arg), or open an existing file from `Uint8Array` or `Blob` |
-| `getWorksheet(nameOrIndex)` | `Promise<ExcelWorksheet>` | Get worksheet (name or 0-based index) |
-| `createWorksheet(name)` | `Promise<ExcelWorksheet>` | Create new worksheet |
-| `getWorksheetNames()` | `Promise<string[]>` | Get all worksheet names |
-| `getBytes()` | `Promise<Uint8Array>` | Export as Uint8Array |
-| `getBlob()` | `Promise<Blob>` | Export as Blob |
-| `close()` | `Promise<void>` | Release resources |
-
-## ExcelWrapper API
-
-| Member | Type / Return Type | Description |
-|--------|-----------|------|
-| `constructor(schema)` | — | Create wrapper with a Zod schema (use `.describe()` on fields for Excel header names; defaults to field key) |
-| `read(file, wsNameOrIndex?, options?)` | `Promise<z.infer<TSchema>[]>` | Read records from Excel file (`Uint8Array` or `Blob`); defaults to first worksheet. `options.excludes` omits specific fields. |
-| `write(wsName, records, options?)` | `Promise<ExcelWorkbook>` | Write partial records to a new workbook; caller must manage the returned workbook's lifecycle. `options.excludes` omits specific fields. |
-
-## XML Data Types
-
-These types represent the raw OOXML structure used internally by the library. They are exported for advanced use cases such as direct XML manipulation.
-
-| Type | Description |
-|------|-------------|
-| `ExcelXmlContentTypeData` | Structure of `[Content_Types].xml` |
-| `ExcelXmlRelationshipData` | Structure of `.rels` relationship XML files |
-| `ExcelRelationshipData` | Single relationship entry within `ExcelXmlRelationshipData` |
-| `ExcelXmlWorkbookData` | Structure of `xl/workbook.xml` |
-| `ExcelXmlWorksheetData` | Structure of `xl/worksheets/sheet*.xml` |
-| `ExcelRowData` | Single row entry within `ExcelXmlWorksheetData` |
-| `ExcelCellData` | Single cell entry within a row |
-| `ExcelXmlDrawingData` | Structure of `xl/drawings/drawing*.xml` |
-| `ExcelXmlSharedStringData` | Structure of `xl/sharedStrings.xml` |
-| `ExcelXmlSharedStringDataSi` | Single shared string item (plain text or rich text) |
-| `ExcelXmlSharedStringDataText` | Text element inside a shared string item |
-| `ExcelXmlStyleData` | Structure of `xl/styles.xml` |
-| `ExcelXmlStyleDataXf` | Cell format (`xf`) entry within `cellXfs` |
-| `ExcelXmlStyleDataFill` | Fill entry within `fills` |
-| `ExcelXmlStyleDataBorder` | Border entry within `borders` |
-
-```typescript
-import type { ExcelXmlWorksheetData, ExcelCellData } from "@simplysm/excel";
-```
-
-## Caveats
-
-### All Cell Methods are Asynchronous
-
-All cell-related methods in this library are designed as `async`. This is due to the Lazy Loading structure for memory efficiency with large files. Only the necessary XML is loaded selectively depending on the cell type:
-
-- Reading string cells: Loads SharedStrings.xml
-- Reading number cells: Does not load SharedStrings
-- Cells with styles: Loads Styles.xml
-
-```typescript
-// Correct usage
-const value = await cell.getVal();
-await cell.setVal("Hello");
-
-// Incorrect usage - returns Promise object
-const value = cell.getVal();
-cell.setVal("Hello");
-```
-
-### Resource Cleanup is Required
-
-`ExcelWorkbook` manages ZIP resources internally, so you must call `close()` after use or use `await using`. After calling `close()`, the workbook instance cannot be used.
-
-### Resource Management of ExcelWrapper.write()
-
-`ExcelWrapper.write()` returns `ExcelWorkbook`, so the caller must manage the resource.
-
-```typescript
-// Correct usage
-await using wb = await wrapper.write("Sheet1", records);
-const bytes = await wb.getBytes();
-
-// Or
-const wb = await wrapper.write("Sheet1", records);
-try {
-  const bytes = await wb.getBytes();
-} finally {
-  await wb.close();
-}
-```
-
-### Background Color Format
-
-Background colors use the ARGB 8-digit hexadecimal format. It must satisfy the `/^[0-9A-F]{8}$/i` pattern, otherwise an error will occur.
-
-```
-Format: AARRGGBB
-  AA = alpha (00=transparent, FF=opaque, but reversed in Excel: 00=opaque)
-  RR = red
-  GG = green
-  BB = blue
-```
-
-### 0-based Indexing
-
-All row/column indices are 0-based. Cell A1 in Excel corresponds to `cell(0, 0)`, cell B3 corresponds to `cell(2, 1)`.
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/excel-wrapper.ts` | `ExcelWrapper` | Zod schema-based type-safe Excel read/write wrapper | `excel-wrapper.spec.ts` |
 
 ## License
 

package/dist/excel-cell.d.ts

@@ -1,58 +1,58 @@
 import type { ZipCache } from "./utils/zip-cache";
 import type { ExcelAddressPoint, ExcelStyleOptions, ExcelValueType } from "./types";
 /**
- * Excel 셀을 나타내는 클래스.
- * 값 읽기/쓰기, 수식 설정, 스타일 설정, 셀 병합 등의 기능을 제공한다.
+ * Class representing an Excel cell.
+ * Provides value read/write, formula, style, and cell merge functionality.
  *
  * @remarks
- * ## 비동기 메서드 설계
+ * ## Async Method Design
  *
- * `getVal()`, `setVal()` 등 모든 셀 메서드가 `async`인 이유:
- * - 셀 타입에 따라 필요한 XML만 선택적으로 로드한다
- * - 문자열 셀: SharedStrings.xml 로드
- * - 숫자 셀: SharedStrings 로드 안함
- * - 스타일이 있는 셀: Styles.xml 로드
+ * Why all cell methods like `getVal()`, `setVal()` 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
  *
- * 어떤 셀을 읽을지 미리 알 수 없기 때문에 동기 구조로는 구현할 수 없다.
- * 동기 구조로 만들려면 모든 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.
  */
 export declare class ExcelCell {
     private readonly _zipCache;
     private readonly _targetFileName;
     private readonly _r;
     private readonly _c;
-    /** 셀 주소 (0-based 행/열 인덱스) */
+    /** Cell address (0-based row/column index) */
     readonly addr: ExcelAddressPoint;
     constructor(_zipCache: ZipCache, _targetFileName: string, _r: number, _c: number);
-    /** 셀에 수식 설정 (undefined: 수식 삭제) */
+    /** Set formula on cell (undefined: remove formula) */
     setFormula(val: string | undefined): Promise<void>;
-    /** 셀의 수식 반환 */
+    /** Return cell formula */
     getFormula(): Promise<string | undefined>;
-    /** 셀 값 설정 (undefined: 셀 삭제) */
+    /** Set cell value (undefined: delete cell) */
     setVal(val: ExcelValueType): Promise<void>;
-    /** 셀 값 반환 */
+    /** Return cell value */
     getVal(): Promise<ExcelValueType>;
     /**
-     * 현재 셀부터 지정된 끝 좌표까지 셀 병합
-     * @param r 병합 끝 행 인덱스 (0-based)
-     * @param c 병합 끝 열 인덱스 (0-based)
+     * 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)
      * @example
-     * // A1 셀에서 호출하면 A1:C3 범위 (3행 x 3열)를 병합
+     * // Called from cell A1, merges range A1:C3 (3 rows x 3 columns)
      * await ws.cell(0, 0).merge(2, 2);
      */
     merge(r: number, c: number): Promise<void>;
-    /** 셀의 스타일 ID 반환 */
+    /** Return cell style ID */
     getStyleId(): Promise<string | undefined>;
-    /** 셀의 스타일 ID 설정 */
+    /** Set cell style 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")
+     * Set cell style
+     * @param opts Style options
+     * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "FFFF0000")
+     * @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")
      */
     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;AAapF;;;;;;;;;;;;;;;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;IAwChD,aAAa;IACP,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFvC;;;;;;;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;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;AAapF;;;;;;;;;;;;;;;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,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAwChD,wBAAwB;IAClB,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFvC;;;;;;;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"}