@simplysm/excel 1.0.138 → 13.0.0-beta.2

package/README.md

@@ -0,0 +1,491 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @simplysm/excel
+# or
+yarn add @simplysm/excel
+# or
+pnpm add @simplysm/excel
+```
+
+### Dependencies
+
+| Package | Purpose |
+|--------|------|
+| `@simplysm/core-common` | Date/time types (`DateOnly`, `DateTime`, `Time`), utilities |
+| `zod` | Schema-based data validation for `ExcelWrapper` |
+| `mime` | MIME type determination for image insertion |
+
+## Core Modules
+
+### Core Classes
+
+| 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 |
+
+### Wrapper Classes
+
+| Class | Description |
+|--------|------|
+| `ExcelWrapper` | Type-safe Excel data conversion based on Zod schemas |
+
+### Utilities
+
+| 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 }`) |
+
+## 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";
+
+// 1. Define schema
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().optional(),
+  active: z.boolean(),
+});
+
+// 2. Field name to display name mapping (names displayed in Excel headers)
+const displayNameMap = {
+  name: "Name",
+  age: "Age",
+  email: "Email",
+  active: "Active Status",
+};
+
+const wrapper = new ExcelWrapper(schema, displayNameMap);
+```
+
+#### 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() returns ExcelWorkbook, so resource management is required
+await using wb = await wrapper.write("Users", records);
+const bytes = await wb.getBytes();
+```
+
+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);
+```
+
+Behavior of the `read()` method:
+- Only reads headers defined in the schema's `_displayNameMap`
+- 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 |
+
+## ExcelCell API
+
+| Method | Return Type | Description |
+|--------|-----------|------|
+| `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
+
+| Method | Return Type | Description |
+|--------|-----------|------|
+| `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<Bytes>` | Export as Uint8Array |
+| `getBlob()` | `Promise<Blob>` | Export as Blob |
+| `close()` | `Promise<void>` | Release resources |
+
+## Important Notes
+
+### 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)`.
+
+## License
+
+Apache-2.0

package/dist/core-common/src/common.types.d.ts

@@ -0,0 +1,74 @@
+import { DateTime } from "./types/date-time";
+import { DateOnly } from "./types/date-only";
+import { Time } from "./types/time";
+import { Uuid } from "./types/uuid";
+/**
+ * Buffer 대신 사용하는 바이너리 타입
+ */
+export type Bytes = Uint8Array;
+/**
+ * Primitive 타입 매핑
+ * orm-common과 공유
+ */
+export type PrimitiveTypeMap = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    DateTime: DateTime;
+    DateOnly: DateOnly;
+    Time: Time;
+    Uuid: Uuid;
+    Bytes: Bytes;
+};
+/**
+ * Primitive 타입 문자열 키
+ */
+export type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+/**
+ * Primitive 타입 유니온
+ */
+export type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+/**
+ * 깊은 Partial 타입
+ *
+ * 객체의 모든 속성을 재귀적으로 선택적(optional)으로 만듭니다.
+ * Primitive 타입(string, number, boolean 등)은 그대로 유지하고,
+ * 객체/배열 타입만 재귀적으로 Partial을 적용합니다.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   profile: {
+ *     age: number;
+ *     address: { city: string };
+ *   };
+ * }
+ *
+ * // 모든 깊이의 속성이 선택적이 됨
+ * const partial: DeepPartial<User> = {
+ *   profile: { address: {} }
+ * };
+ * ```
+ */
+export type DeepPartial<T> = Partial<{
+    [K in keyof T]: T[K] extends PrimitiveType ? T[K] : DeepPartial<T[K]>;
+}>;
+/**
+ * 생성자 타입
+ *
+ * 클래스 생성자를 타입으로 표현할 때 사용합니다.
+ * 주로 의존성 주입, 팩토리 패턴, instanceof 체크 등에서 활용됩니다.
+ *
+ * @example
+ * function create<T>(ctor: Type<T>): T {
+ *   return new ctor();
+ * }
+ *
+ * class MyClass { name = "test"; }
+ * const instance = create(MyClass); // MyClass 인스턴스
+ */
+export interface Type<T> extends Function {
+    new (...args: unknown[]): T;
+}
+//# sourceMappingURL=common.types.d.ts.map

package/dist/core-common/src/common.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.types.d.ts","sourceRoot":"","sources":["../../../../core-common/src/common.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAIpC;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAM/B;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC;KAClC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,QAAQ;IACvC,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;CAC7B"}

package/dist/core-common/src/env.d.ts

@@ -0,0 +1,6 @@
+export declare const env: {
+    DEV: boolean;
+    VER?: string;
+    [key: string]: unknown;
+};
+//# sourceMappingURL=env.d.ts.map

package/dist/core-common/src/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../core-common/src/env.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}

package/dist/core-common/src/errors/argument-error.d.ts

@@ -0,0 +1,25 @@
+import { SdError } from "./sd-error";
+/**
+ * 인수 오류
+ *
+ * 잘못된 인수를 받았을 때 발생시키는 에러이다.
+ * 인수 객체를 YAML 형식으로 메시지에 포함하여 디버깅을 용이하게 한다.
+ *
+ * @example
+ * // 인수 객체만 전달
+ * throw new ArgumentError({ userId: 123, name: null });
+ * // 결과 메시지: "인수가 잘못되었습니다.\n\nuserId: 123\nname: null"
+ *
+ * @example
+ * // 커스텀 메시지와 인수 객체 전달
+ * throw new ArgumentError("유효하지 않은 사용자", { userId: 123 });
+ * // 결과 메시지: "유효하지 않은 사용자\n\nuserId: 123"
+ */
+export declare class ArgumentError extends SdError {
+    /** 기본 메시지("인수가 잘못되었습니다.")와 함께 인수 객체를 YAML 형식으로 출력 */
+    constructor(argObj: Record<string, unknown>);
+    /** 커스텀 메시지와 함께 인수 객체를 YAML 형식으로 출력 */
+    constructor(message: string, argObj: Record<string, unknown>);
+    constructor(arg1: Record<string, unknown> | string, arg2?: Record<string, unknown>);
+}
+//# sourceMappingURL=argument-error.d.ts.map

package/dist/core-common/src/errors/argument-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/argument-error.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,OAAO;IACxC,qDAAqD;gBACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3C,sCAAsC;gBAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAChD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYnF"}

package/dist/core-common/src/errors/not-implemented-error.d.ts

@@ -0,0 +1,29 @@
+import { SdError } from "./sd-error";
+/**
+ * 미구현 오류
+ *
+ * 아직 구현되지 않은 기능을 호출했을 때 발생시키는 에러이다.
+ * 추상 메서드 스텁, 향후 구현 예정인 분기 등에 사용한다.
+ *
+ * @example
+ * // 추상 메서드 구현 전
+ * class BaseService {
+ *   process(): void {
+ *     throw new NotImplementedError("서브클래스에서 구현 필요");
+ *   }
+ * }
+ *
+ * @example
+ * // 향후 구현 예정 분기
+ * switch (type) {
+ *   case "A": return handleA();
+ *   case "B": throw new NotImplementedError(`타입 ${type} 처리`);
+ * }
+ */
+export declare class NotImplementedError extends SdError {
+    /**
+     * @param message 추가 설명 메시지
+     */
+    constructor(message?: string);
+}
+//# sourceMappingURL=not-implemented-error.d.ts.map

package/dist/core-common/src/errors/not-implemented-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-implemented-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/not-implemented-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,SAAQ,OAAO;IAC9C;;OAEG;gBACS,OAAO,CAAC,EAAE,MAAM;CAI7B"}

package/dist/core-common/src/errors/sd-error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 오류의 Tree 구조 구성이 가능한 오류 클래스
+ * ES2024 cause 속성 활용
+ *
+ * @example
+ * // 원인 에러를 감싸서 생성
+ * try {
+ *   await fetch(url);
+ * } catch (err) {
+ *   throw new SdError(err, "API 호출 실패", "사용자 로드 실패");
+ * }
+ * // 결과 메시지: "사용자 로드 실패 => API 호출 실패 => 원본 에러 메시지"
+ *
+ * @example
+ * // 메시지만으로 생성
+ * throw new SdError("잘못된 상태", "처리 불가");
+ * // 결과 메시지: "처리 불가 => 잘못된 상태"
+ */
+export declare class SdError extends Error {
+    cause?: Error;
+    /** 원인 에러를 감싸서 생성. 메시지는 역순으로 연결됨 (상위 메시지 => 하위 메시지 => 원인 메시지) */
+    constructor(cause: Error, ...messages: string[]);
+    /** 메시지만으로 생성. 메시지는 역순으로 연결됨 (상위 메시지 => 하위 메시지) */
+    constructor(...messages: string[]);
+    constructor(arg1?: unknown, ...messages: string[]);
+}
+//# sourceMappingURL=sd-error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sd-error.d.ts","sourceRoot":"","sources":["../../../../../core-common/src/errors/sd-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;IAEvB,gEAAgE;gBACpD,KAAK,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE;IAC/C,kDAAkD;gBACtC,GAAG,QAAQ,EAAE,MAAM,EAAE;gBACrB,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE;CA2BlD"}